fix: BigQuery finops UX — surface bq_region, actionable errors, warehouse_add warning

Partial resolution of #754, focused on the four BigQuery UX/visibility items
that naturally cluster. Three behavioural deferrals (#5 throw-on-invalid,
#6 options-object refactor, #7 e2e silent-skip) remain open in #754.

## Changes

1. `bq_region` surfaced in every BigQuery finops tool response.
   `QueryHistoryResult`, `CreditAnalysisResult`, `ExpensiveQueriesResult`,
   `WarehouseAdvisorResult`, `UnusedResourcesResult`, and `RoleGrantsResult`
   gain an optional `bq_region?: string` field. All five finops modules
   compute `sanitisedBqRegion = sanitizeBqRegion(bqRegion)` once at entry
   and thread it through success and error returns. Non-BigQuery warehouses
   omit the field. Lets the agent (and humans inspecting tool output) see
   which region was actually queried after the silent `us` fallback shipped
   in v0.6.1 (#739).

2. `augmentBqError(error, region)` helper in `bq-utils.ts`.
   Appends a region hint to BigQuery errors that look region-related,
   anchored to `region-<x>.INFORMATION_SCHEMA` references and "Not found"
   lines so unrelated text (`region-based routing`, `multi-region-aware`)
   does not trigger. Idempotent — safe under nested catch wrapping.
   Wired into all five finops `catch` blocks.

3. `isBqPermissionError(error)` helper in `bq-utils.ts`.
   Detects the `INFORMATION_SCHEMA.TABLE_STORAGE` 403 pattern that
   `finops_unused_resources` hits routinely on project-scoped service
   accounts. Word-boundary `\b403\b` check so `4031`, `40322`, `port 4030`
   do not false-positive. `unused-resources.ts` produces an actionable
   message naming `bigquery.resourceAdmin` (org-level requirement) when
   this fires.

4. `warehouse_add` non-fatal warning when a BigQuery connection is
   registered without a `location` field. Catches whitespace-only values
   too — `sanitizeBqRegion` trims at query time and falls back to "us",
   so `location: "  "` would otherwise pass a truthy-only guard but
   silently query the wrong region.

## Review notes

Reviewed via `/consensus:code-review` with eight external models
(GPT 5.4, Gemini 3.1 Pro, Kimi K2.5, MiniMax M2.7, GLM-5, Qwen 3.6 Plus,
DeepSeek V3.2, MiMo-V2-Pro) plus Claude. 7 of 8 converged in round 1;
Qwen's CLI did not return in time. Convergence corrected three accuracy
issues from the initial draft:

- Original draft claimed `includes("accessdenied")` was redundant after
  `.toLowerCase()`. MiniMax retracted this on second look — Google's
  BigQuery SDKs emit `AccessDenied` (camelCase), which lowercases to
  `accessdenied` (no space) and would not be caught by the
  `access denied` substring check. Both checks are kept.
- Original draft attributed dead `?? "us"` to two locations. Verified by
  grep — only `unused-resources.ts:212` had it. Single fix applied.
- Original draft listed several BigQuery `location` aliases
  (`Location`, `projectLocation`, `locationId`) as "auto-normalized" but
  `BIGQUERY_ALIASES` in `packages/drivers/src/normalize.ts` does not
  include any `location` alias. The check on `args.config.location` is
  correct for current aliases. The remaining real concern (whitespace
  trim) was downgraded and addressed.

## Tests

8 new tests in `finops-bq-visibility.test.ts` for the convergence-driven
guards: `region-based routing`, `multi-region-aware`, bare `region-`,
canonical INFORMATION_SCHEMA shapes, numeric-prefix `403` negative cases,
canonical 403 surfaces, whitespace-only and null `location` warnings.
30/30 in this file pass; full altimate + skill suite 3236/3236.

Verified:
- `bun turbo typecheck`: 5/5 green
- `bun run script/upstream/analyze.ts --markers --base main --strict`: clean
- 3236 pass / 491 skipped (env-gated) / 0 fail across altimate + skill

Closes #755

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: anandgupta42

packages/opencode/src/altimate/native/finops/bq-utils.ts

@@ -55,3 +55,59 @@ export function interpolateBqRegion(sqlTemplate: string, bqRegion?: unknown): st
 export function bqRegionFor(warehouse: string): unknown {
   return Registry.getConfig(warehouse)?.location
 }
+
+/**
+ * Append a region-hint to a BigQuery error message when the error looks
+ * region-related (missing dataset, region-not-found, unknown INFORMATION_SCHEMA
+ * view). The hint tells the user which region the query ran against and how to
+ * change it — the root cause on non-US projects is almost always an unset or
+ * mis-typed `location` on the warehouse config.
+ *
+ * Returns the original error string unchanged when no region signal is present,
+ * so non-region failures (bad syntax, auth, quota) stay legible.
+ */
+export function augmentBqError(error: unknown, sanitizedRegion: string): string {
+  const msg = String(error)
+  // Signals we treat as region-related:
+  //   1. A backticked region-qualified INFORMATION_SCHEMA reference, which is
+  //      what BigQuery emits when the dataset can't be resolved in the queried
+  //      region: `region-eu.INFORMATION_SCHEMA.JOBS not found`.
+  //   2. A "Not found: ... INFORMATION_SCHEMA" line — covers cases where BQ
+  //      mentions the view name but not the region prefix.
+  //   3. The literal "Not found: Dataset region-..." form some BQ surfaces use.
+  // Anchored to these specific shapes so unrelated text containing "region-"
+  // (e.g. "region-based routing denied", "multi-region-aware feature disabled")
+  // does NOT trigger the BigQuery-connection hint.
+  const hasRegionSignal =
+    /region-[a-z0-9]+[a-z0-9-]*\.INFORMATION_SCHEMA/i.test(msg) ||
+    /Not\s+found:.*INFORMATION_SCHEMA/i.test(msg) ||
+    /Not\s+found:\s*Dataset\s+region-[a-z0-9]+/i.test(msg)
+  if (!hasRegionSignal) return msg
+  // Idempotent — don't append twice if this helper runs in nested catches
+  if (msg.includes('set "location" on the BigQuery connection')) return msg
+  return `${msg} (queried region-${sanitizedRegion}; set "location" on the BigQuery connection to change this)`
+}
+
+/**
+ * Detect errors raised by BigQuery when the caller lacks the org-level
+ * permissions required by views such as `INFORMATION_SCHEMA.TABLE_STORAGE`
+ * (used by `finops_unused_resources`). Most project-scoped service accounts
+ * lack `bigquery.resourceAdmin` at the org and hit this path first.
+ */
+export function isBqPermissionError(error: unknown): boolean {
+  const msg = String(error).toLowerCase()
+  // Word-boundary regex on `403` so `4031`, `40322`, `port 4030`, and similar
+  // numeric prefixes don't false-positive into the permission-error branch.
+  // The two `accessdenied` / `access denied` checks are intentional and not
+  // redundant — Google's BigQuery SDKs emit `AccessDenied` (camelCase),
+  // which `.toLowerCase()` collapses to `accessdenied` (no space) and would
+  // not be caught by the `access denied` substring check.
+  return (
+    msg.includes("permission denied") ||
+    msg.includes("access denied") ||
+    msg.includes("accessdenied") ||
+    msg.includes("bigquery.resourceadmin") ||
+    msg.includes("iam permission") ||
+    /\b403\b/.test(msg)
+  )
+}

packages/opencode/src/altimate/native/finops/credit-analyzer.ts

@@ -5,7 +5,7 @@
  */
 
 import * as Registry from "../connections/registry"
-import { bqRegionFor, interpolateBqRegion } from "./bq-utils"
+import { augmentBqError, bqRegionFor, interpolateBqRegion, sanitizeBqRegion } from "./bq-utils"
 import type {
   CreditAnalysisParams,
   CreditAnalysisResult,
@@ -306,6 +306,7 @@ export async function analyzeCredits(params: CreditAnalysisParams): Promise<Cred
   const days = params.days ?? 30
   const limit = params.limit ?? 50
   const bqRegion = whType === "bigquery" ? bqRegionFor(params.warehouse) : undefined
+  const sanitisedBqRegion = whType === "bigquery" ? sanitizeBqRegion(bqRegion) : undefined
 
   const dailyBuilt = buildCreditUsageSql(whType, days, limit, params.warehouse_filter, bqRegion)
   const summaryBuilt = buildCreditSummarySql(whType, days, bqRegion)
@@ -319,6 +320,7 @@ export async function analyzeCredits(params: CreditAnalysisParams): Promise<Cred
       days_analyzed: days,
       recommendations: [],
       error: `Credit analysis is not available for ${whType} warehouses.`,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 
@@ -339,6 +341,7 @@ export async function analyzeCredits(params: CreditAnalysisParams): Promise<Cred
       total_credits: Math.round(totalCredits * 10000) / 10000,
       days_analyzed: days,
       recommendations,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   } catch (e) {
     return {
@@ -348,7 +351,8 @@ export async function analyzeCredits(params: CreditAnalysisParams): Promise<Cred
       total_credits: 0,
       days_analyzed: days,
       recommendations: [],
-      error: String(e),
+      error: sanitisedBqRegion ? augmentBqError(e, sanitisedBqRegion) : String(e),
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 }
@@ -358,6 +362,7 @@ export async function getExpensiveQueries(params: ExpensiveQueriesParams): Promi
   const days = params.days ?? 7
   const limit = params.limit ?? 20
   const bqRegion = whType === "bigquery" ? bqRegionFor(params.warehouse) : undefined
+  const sanitisedBqRegion = whType === "bigquery" ? sanitizeBqRegion(bqRegion) : undefined
 
   const built = buildExpensiveSql(whType, days, limit, bqRegion)
   if (!built) {
@@ -367,6 +372,7 @@ export async function getExpensiveQueries(params: ExpensiveQueriesParams): Promi
       query_count: 0,
       days_analyzed: days,
       error: `Expensive query analysis is not available for ${whType} warehouses.`,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 
@@ -380,14 +386,16 @@ export async function getExpensiveQueries(params: ExpensiveQueriesParams): Promi
       queries,
       query_count: queries.length,
       days_analyzed: days,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   } catch (e) {
     return {
       success: false,
       queries: [],
       query_count: 0,
       days_analyzed: days,
-      error: String(e),
+      error: sanitisedBqRegion ? augmentBqError(e, sanitisedBqRegion) : String(e),
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 }

packages/opencode/src/altimate/native/finops/query-history.ts

@@ -5,7 +5,7 @@
  */
 
 import * as Registry from "../connections/registry"
-import { bqRegionFor, interpolateBqRegion, sanitizeBqRegion } from "./bq-utils"
+import { augmentBqError, bqRegionFor, interpolateBqRegion, sanitizeBqRegion } from "./bq-utils"
 import type { QueryHistoryParams, QueryHistoryResult } from "../types"
 
 // ---------------------------------------------------------------------------
@@ -214,6 +214,7 @@ export async function getQueryHistory(params: QueryHistoryParams): Promise<Query
   const days = params.days ?? 7
   const limit = params.limit ?? 100
   const bqRegion = whType === "bigquery" ? bqRegionFor(params.warehouse) : undefined
+  const sanitisedBqRegion = whType === "bigquery" ? sanitizeBqRegion(bqRegion) : undefined
 
   const built = buildHistoryQuery(whType, days, limit, params.user, params.warehouse_filter, bqRegion)
   if (!built) {
@@ -222,6 +223,7 @@ export async function getQueryHistory(params: QueryHistoryParams): Promise<Query
       queries: [],
       summary: {},
       error: `Query history is not available for ${whType} warehouses.`,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 
@@ -255,13 +257,15 @@ export async function getQueryHistory(params: QueryHistoryParams): Promise<Query
       queries,
       summary,
       warehouse_type: whType,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   } catch (e) {
     return {
       success: false,
       queries: [],
       summary: {},
-      error: String(e),
+      error: sanitisedBqRegion ? augmentBqError(e, sanitisedBqRegion) : String(e),
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 }

packages/opencode/src/altimate/native/finops/role-access.ts

@@ -5,7 +5,7 @@
  */
 
 import * as Registry from "../connections/registry"
-import { bqRegionFor, interpolateBqRegion } from "./bq-utils"
+import { augmentBqError, bqRegionFor, interpolateBqRegion, sanitizeBqRegion } from "./bq-utils"
 import type {
   RoleGrantsParams,
   RoleGrantsResult,
@@ -167,6 +167,7 @@ export async function queryGrants(params: RoleGrantsParams): Promise<RoleGrantsR
   const whType = getWhType(params.warehouse)
   const limit = params.limit ?? 100
   const bqRegion = whType === "bigquery" ? bqRegionFor(params.warehouse) : undefined
+  const sanitisedBqRegion = whType === "bigquery" ? sanitizeBqRegion(bqRegion) : undefined
 
   const built = buildGrantsSql(whType, params.role, params.object_name, limit, bqRegion)
   if (!built) {
@@ -176,6 +177,7 @@ export async function queryGrants(params: RoleGrantsParams): Promise<RoleGrantsR
       grant_count: 0,
       privilege_summary: {},
       error: `Role/access queries are not available for ${whType} warehouses.`,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 
@@ -195,14 +197,16 @@ export async function queryGrants(params: RoleGrantsParams): Promise<RoleGrantsR
       grants,
       grant_count: grants.length,
       privilege_summary: privilegeSummary,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   } catch (e) {
     return {
       success: false,
       grants: [],
       grant_count: 0,
       privilege_summary: {},
-      error: String(e),
+      error: sanitisedBqRegion ? augmentBqError(e, sanitisedBqRegion) : String(e),
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 }

packages/opencode/src/altimate/native/finops/unused-resources.ts

@@ -5,7 +5,13 @@
  */
 
 import * as Registry from "../connections/registry"
-import { bqRegionFor, interpolateBqRegion } from "./bq-utils"
+import {
+  augmentBqError,
+  bqRegionFor,
+  interpolateBqRegion,
+  isBqPermissionError,
+  sanitizeBqRegion,
+} from "./bq-utils"
 import type {
   UnusedResourcesParams,
   UnusedResourcesResult,
@@ -145,6 +151,8 @@ export async function findUnusedResources(params: UnusedResourcesParams): Promis
   const whType = getWhType(params.warehouse)
   const days = params.days ?? 30
   const limit = params.limit ?? 50
+  const bqRegion = whType === "bigquery" ? bqRegionFor(params.warehouse) : undefined
+  const sanitisedBqRegion = whType === "bigquery" ? sanitizeBqRegion(bqRegion) : undefined
 
   if (!["snowflake", "bigquery", "databricks"].includes(whType)) {
     return {
@@ -187,11 +195,22 @@ export async function findUnusedResources(params: UnusedResourcesParams): Promis
       }
     } else if (whType === "bigquery") {
       try {
-        const sql = interpolateBqRegion(BIGQUERY_UNUSED_TABLES_SQL, bqRegionFor(params.warehouse))
+        const sql = interpolateBqRegion(BIGQUERY_UNUSED_TABLES_SQL, bqRegion)
         const result = await connector.execute(sql, limit, [days, limit])
         unusedTables = rowsToRecords(result)
       } catch (e) {
-        errors.push(`Could not query unused tables: ${e}`)
+        // TABLE_STORAGE is an org-level view. Most project-scoped service
+        // accounts lack bigquery.resourceAdmin at the org and hit 403 here —
+        // point them at the specific permission rather than a raw SQL error.
+        if (isBqPermissionError(e)) {
+          errors.push(
+            `Could not query unused tables: BigQuery returned a permission error for INFORMATION_SCHEMA.TABLE_STORAGE. ` +
+              `This view is org-level and requires bigquery.resourceAdmin (or equivalent) at the organisation. ` +
+              `Project-scoped service accounts typically can't read it. Raw error: ${e}`,
+          )
+        } else {
+          errors.push(`Could not query unused tables: ${augmentBqError(e, sanitisedBqRegion!)}`)
+        }
       }
     } else if (whType === "databricks") {
       try {
@@ -220,6 +239,7 @@ export async function findUnusedResources(params: UnusedResourcesParams): Promis
       },
       days_analyzed: days,
       error: errors.length > 0 ? errors.join("; ") : undefined,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   } catch (e) {
     return {
@@ -228,7 +248,8 @@ export async function findUnusedResources(params: UnusedResourcesParams): Promis
       idle_warehouses: [],
       summary: {},
       days_analyzed: days,
-      error: String(e),
+      error: sanitisedBqRegion ? augmentBqError(e, sanitisedBqRegion) : String(e),
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 }

packages/opencode/src/altimate/native/finops/warehouse-advisor.ts

@@ -5,7 +5,7 @@
  */
 
 import * as Registry from "../connections/registry"
-import { bqRegionFor, interpolateBqRegion } from "./bq-utils"
+import { augmentBqError, bqRegionFor, interpolateBqRegion, sanitizeBqRegion } from "./bq-utils"
 import type {
   WarehouseAdvisorParams,
   WarehouseAdvisorResult,
@@ -223,6 +223,7 @@ export async function adviseWarehouse(params: WarehouseAdvisorParams): Promise<W
   const whType = getWhType(params.warehouse)
   const days = params.days ?? 14
   const bqRegion = whType === "bigquery" ? bqRegionFor(params.warehouse) : undefined
+  const sanitisedBqRegion = whType === "bigquery" ? sanitizeBqRegion(bqRegion) : undefined
 
   const loadSql = buildLoadSql(whType, days, bqRegion)
   const sizingSql = buildSizingSql(whType, days, bqRegion)
@@ -235,6 +236,7 @@ export async function adviseWarehouse(params: WarehouseAdvisorParams): Promise<W
       recommendations: [],
       days_analyzed: days,
       error: `Warehouse sizing advice is not available for ${whType} warehouses.`,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 
@@ -276,6 +278,7 @@ export async function adviseWarehouse(params: WarehouseAdvisorParams): Promise<W
       warehouse_performance: sizingData,
       recommendations,
       days_analyzed: days,
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   } catch (e) {
     return {
@@ -284,7 +287,8 @@ export async function adviseWarehouse(params: WarehouseAdvisorParams): Promise<W
       warehouse_performance: [],
       recommendations: [],
       days_analyzed: days,
-      error: String(e),
+      error: sanitisedBqRegion ? augmentBqError(e, sanitisedBqRegion) : String(e),
+      ...(sanitisedBqRegion && { bq_region: sanitisedBqRegion }),
     }
   }
 }

packages/opencode/src/altimate/native/types.ts

@@ -534,6 +534,8 @@ export interface QueryHistoryResult {
   queries: Record<string, unknown>[]
   summary: Record<string, unknown>
   warehouse_type?: string
+  /** For BigQuery warehouses: the sanitised region the query was executed against. */
+  bq_region?: string
   error?: string
 }
 
@@ -553,6 +555,8 @@ export interface CreditAnalysisResult {
   total_credits: number
   days_analyzed: number
   recommendations: Record<string, unknown>[]
+  /** For BigQuery warehouses: the sanitised region the query was executed against. */
+  bq_region?: string
   error?: string
 }
 
@@ -569,6 +573,8 @@ export interface ExpensiveQueriesResult {
   queries: Record<string, unknown>[]
   query_count: number
   days_analyzed: number
+  /** For BigQuery warehouses: the sanitised region the query was executed against. */
+  bq_region?: string
   error?: string
 }
 
@@ -585,6 +591,8 @@ export interface WarehouseAdvisorResult {
   warehouse_performance: Record<string, unknown>[]
   recommendations: Record<string, unknown>[]
   days_analyzed: number
+  /** For BigQuery warehouses: the sanitised region the query was executed against. */
+  bq_region?: string
   error?: string
 }
 
@@ -602,6 +610,8 @@ export interface UnusedResourcesResult {
   idle_warehouses: Record<string, unknown>[]
   summary: Record<string, unknown>
   days_analyzed: number
+  /** For BigQuery warehouses: the sanitised region the query was executed against. */
+  bq_region?: string
   error?: string
 }
 
@@ -619,6 +629,8 @@ export interface RoleGrantsResult {
   grants: Record<string, unknown>[]
   grant_count: number
   privilege_summary: Record<string, number>
+  /** For BigQuery warehouses: the sanitised region the query was executed against. */
+  bq_region?: string
   error?: string
 }