refactor: rename region → siteId across DB, API, daemon, and client

[guohai]

Summary

Completes the region → siteId terminology refactor: the DB columns, server responses, daemon, and client all now call an exact site ID (<base>-<NN>, e.g. na-us-seattle-01) what it is, ending the region-means-two-things overload.

• DB: 9 columns renamed to site_id + 2 indexes (migration 0025, v34, data-preserving).
• Server: schema, storage, routes, and the v1 API consume/emit siteId; the eval-jobs list filter is ?siteId=.
• Daemon: vox_eval_agentd consumes siteId job rows; the ignored job-poll param is gone.
• Client: formatRegion/formatSite split; all hand-rolled interfaces and call-sites read siteId (including the silent non-tsc cases: eval-agents, leaderboard, org-settings schedules, run-your-own jobs, clash pages).
• OpenAPI: 12 field renames; stale [na,apac,eu,sa] enum removed everywhere.
• Fixes folded in from the full local test gate (now fully green — unit 1556/1556, audio 12/12, E2E 133/0):
  • clash-detail.tsx called useQuery after early returns — the match page crashed once data loaded.
  • Fixture drift in DB-level suites (site_id NOT NULL), stale E2E specs (admin redirect since feat: admin edits user role/plan; move User Management + Providers under /console #52, renamed tabs, strict-mode locators), flaky networkidle waits replaced with deterministic ones.
  • full-tests-run.sh defaults DATABASE_URL so DB-level suites can't silently skip.
  • Dead code removed (mockData.ts, dead match.region displays), stale region-wording comments swept.
• New: tests/site-id-wire.test.ts locks the wire contract (renamed surfaces emit siteId, never region; ?siteId= validates; token endpoints keep the documented back-compat region key).

Known scope decision (documented, not a bug)

A few surfaces still use the region JSON key carrying a site-id value (eval-agent-token responses, run-targets agents, clash-runner admin lists, several POST request bodies). Server ↔ client are internally consistent and the wire test pins the contract; closing this fully is a follow-up.

Test plan

• npm run check clean, npm test 1556/1556
• ./scripts/full-tests-run.sh: unit + audio + E2E all green
• Rebased onto main after feat(secrets): auto-select auth broker type for login-style secret names #117 merged (its commit dropped cleanly)

Generated with SMT smt@agora.build

[github-actions]

🤖 Codex Code Review

Findings

• Medium: docs/openapi.yaml:1358 documents POST /eval-agent-tokens as requiring siteId, and docs/openapi.yaml:1386 documents a siteId response, but the server still accepts regionLocationBaseId/region and returns region for this back-compat surface at server/routes.ts:2663 and server/routes.ts:2710. Generated clients will send the documented body and get 400 "Name and region location required", and readers expecting siteId will see undefined. Either update OpenAPI to match the intentionally retained region contract, or change the route and client/test contract together.
• Medium: The daemon/server protocol has no rolling-upgrade compatibility. New daemons require agent.siteId from registration at vox_eval_agentd/vox-agentd.ts:336 and then stop polling if it is absent at vox_eval_agentd/vox-agentd.ts:408; the server now returns only siteId at server/routes.ts:3172. That means upgrading daemon before server, or server before existing deployed daemons that still read region, strands agents as idle/no-job. Consider emitting both siteId and region for one release and making the daemon accept agent.siteId ?? agent.region.

No other security, authorization, injection, or performance issues stood out in the reviewed refactor paths. I did not run the test suite in this read-only environment.

[github-actions]

🤖 Claude Code Review

Reviewed the full diff against 047f0b5. The mechanical rename is careful and well-executed — migration registered in server/migrate.ts (v34), index rename targets match the exact names from 0000_opposite_hobgoblin.sql, snakeToCamel() correctly maps site_id → siteId on the three raw-SQL SELECT * paths, and tests/site-id-wire.test.ts is a good addition that locks the JSON keys where hand-rolled client interfaces can't. Findings below.

Deployed eval-agent daemons will silently stall

POST /api/eval-agent/register now returns siteId (server/routes.ts:3170) where it previously returned region. The daemon shipped in the field does:

this.region = agent.region;            // vox-agentd.ts:336 (old)
...
if (!this.region) return [];           // vox-agentd.ts:408 (old)

So after this deploys, every unupgraded agent registers successfully, heartbeats successfully, shows online/idle in the console — and never fetches a job again. No error is logged on either side; the only symptom is jobs aging out through failPendingJobsWithNoAgent, which reports "No eval agent available" even though the agent is visibly online. Given scripts/vox-upgrade.sh exists, there is a fleet out there that upgrades on its own schedule.

The reverse also breaks: the new daemon reads agent.siteId, so a new agent against a not-yet-deployed Core hits the same dead end.

Cheapest fix is to emit both keys from register for one release:

res.json({ id: agent.id, name: agent.name, siteId: agent.siteId, region: agent.siteId, state: agent.state, leaseId });

Dropping ?region= from fetchJobs is fine on its own — the route authenticates by token and never read the query param.

Breaking change to public API v1 without back-compat

server/routes-api-v1.ts renamed the request body field on POST /api/v1/workflows/:id/run from region to siteId, and the region query filter to siteId, with no alias. This is the vox_live_-keyed external API — existing integrations get a hard 400 ("An exact site ID is required") on the next deploy. Given the rest of the PR deliberately preserves back-compat elsewhere (eval-agent-tokens keeps the region key), accepting the old name for a deprecation window seems more consistent:

const siteId = req.body.siteId ?? req.body.region;

In-app API docs now show a request that 400s

client/src/pages/run-your-own.tsx:596 still renders:

-d '{"region": "na-us-seattle-01"}' \
  .../api/v1/workflows/1/run

Copy-pasting that from the UI now fails. Needs siteId (or the alias above).

Minor

• Half-migrated wire contract. /api/eval-agents/dispatchable maps siteId → region → siteId across three lines (server/routes.ts:3050-3065) because DispatchableAgentRow/DispatchToken in dispatch.ts/permissions.ts still declare region: string. Correct, but formatSite(token.region) and formatSite(agent.siteId) now sit ~250 lines apart in console-eval-agents.tsx. The split is documented in the wire test and clash surfaces are internally consistent, so it holds — worth a tracking issue rather than a change here.
• formatRegion / regionOf have no production callers (client/src/lib/utils.ts:85,91) — only tests/regions.test.ts exercises them. Also note the rewrite dropped the legacy macro-code mapping (na → "North America"); I found no caller passing a macro code, so this looks intentional, but the new formatRegion only matches exact baseIds.
• as any casts carried forward at server/storage.ts:2313 and the createClashRunner insert. Both columns are plain varchar now, so the casts are dead weight suppressing real type checking on a SQL-bound value (parameterized, so not an injection risk).
• failPendingJobsWithNoAgent error text still reads "No eval agent available for region " while the surrounding logs were reworded to "site" (server/index.ts). Cosmetic, but it's the string users actually see on a failed job.
• Rollout ordering: RENAME COLUMN is metadata-only and fast, but not backward compatible — any old app instance still serving during the swap errors on region. Fine for a stop-then-start Coolify deploy; worth confirming that's what's configured.

I could not run npm run check or the test suite (both needed approval), so the type-level claims above are from reading; the two remaining .region reads I found (dispatch.ts:59, routes.ts:3065) are both on internal types that still declare the field and are populated from siteId at the call site, so they're correct.