Summary

Relates to floomhq/workeros-cloud#1201. Live user test: a user seeing 500
runs/day asked twice "who pays for this, doesn't this cost a lot" and wanted
visible costs/limits (he praised Claude Code's statusline showing model +
percent-of-limit). This ships a full cut, not a stub.

• GET /workspace/spend (new): a purpose-built, read-only readout of
  workspace day/month spend-to-date against the configured daily/monthly
  caps. Reuses the existing services.run_cost aggregation functions
  (_workspace_day_to_date_cost_usd, _workspace_month_to_date_cost_usd,
  _workspace_daily_spend_cap_usd, _workspace_monthly_spend_cap_usd) -
  the same math that already gates the spend-cap enforcement on run
  dispatch, so the number shown always agrees with what actually blocks a
  run. No mutation.
• GET /workers/{id}/spend (new): a single worker's month-to-date
  spend + its configured monthly cap (null if uncapped). Reuses
  _worker_month_to_date_cost_usd + _spend_cap_for_config /
  get_worker_config_for_run. 404s for a worker the caller can't see (same
  visibility check as GET /workers/{id}).
• Bug fix in GET /workspace/settings: its existing
  current_day_spend_usd / current_month_spend_usd mirrors were computed
  by calling _workspace_day_to_date_cost_usd() / _workspace_month_to_date_cost_usd()
  with no repos/user_id arguments. Without those, the aggregation always
  fell back to the engine's local sqlite file, which is empty on any
  deployment using a different Repositories backend (e.g. Supabase on
  cloud) - so cloud always rendered $0.00 regardless of real spend. This
  PR passes repos=repos, user_id=auth.user_id through, matching the
  pattern already used by the spend-cap enforcement path in
  run_service._enforce_run_spend_caps.
• Settings page: ModelDefaults now renders "$X of $Y spent this month" (plus a daily figure when a daily cap is set) directly under the
  existing "Monthly spend cap (USD)" field, sourced from the new
  GET /workspace/spend endpoint.
• Worker detail page: the Overview tab's stat row now includes a
  "Spend (mo)" tile (month-to-date spend, or "spend / cap" when the worker
  has a configured monthly cap), sourced from GET /workers/{id}/spend via
  a cache-first useWorkerSpendQuery hook. Fails soft (omitted if the
  fetch errors), same as every other stat on that row.
• Test fix: test_797_workspace_defaults_enforcement.py's
  test_settings_returns_current_month_spend seeded a run at a hardcoded
  day-05 and then asserted current_day_spend_usd >= 4.25 - a
  date-dependent flake that fails on any day after the 5th of the month
  (confirmed failing on main before this PR, unrelated to this change;
  fixed here since it's directly in the code path this PR touches).

Deferred

• floomhq/workeros-cloud#1183 ("Not reported" cost/tokens on some
  runs). Investigated the code path
  (services/ai_observability.py + cost.py's
  resolved_cost_usd_from_transcript): a run's cost/tokens read
  "Not reported" only when no {"type":"usage",...} row exists in its
  transcript at all - correct behavior for genuinely non-agent
  (pure-script) runs that made no LLM calls, since there's nothing to sum.
  Whether the specific repro run (run_16145da453f5) is that case, or a
  genuine instrumentation gap, needs looking at the actual run's
  transcript/runner type, which isn't reproducible from this local
  investigation. Deeper root-causing (and possibly changing "no usage data"
  vs "confirmed zero cost" semantics in the persisted total_cost_usd)
  is a separate, more involved change and is out of scope for this pass -
  filed as a follow-up rather than rabbit-holed here.

(Per-worker spend UI, originally scoped as a possible defer, shipped in
this PR instead - see the worker detail bullet above.)

Files touched

• apps/api/routers/workspace.py - GET /workspace/spend + settings bug fix
• apps/api/routers/worker_admin.py - GET /workers/{id}/spend
• apps/web/app/settings/page.tsx - spend readout in ModelDefaults
• apps/web/app/workers/WorkersCollection.tsx - "Spend (mo)" stat on worker detail
• apps/web/lib/api.ts, apps/web/lib/types.ts - client + types
• apps/web/lib/query/hooks.ts - useWorkerSpendQuery + query key
• apps/api/tests/test_1201_worker_spend_endpoint.py (new)
• apps/api/tests/test_797_workspace_defaults_enforcement.py - new
  endpoint tests + flaky-date fix
• apps/web/tests/model-defaults-spend-1201.dom.test.tsx (new)
• apps/web/tests/worker-detail-spend-1201.dom.test.tsx (new)
• apps/web/tests/model-defaults-797.dom.test.tsx - mock update for the
  new api.workspace.getSpend call
• docs/API.md - documents the two new endpoints

Test plan

• cd apps/api && python -m pytest tests/test_797_workspace_defaults_enforcement.py tests/test_1201_worker_spend_endpoint.py -q - 27 passed
• cd apps/web && npm run lint - 0 errors (21 pre-existing warnings, none in touched files)
• cd apps/web && npm run lint:emdash - clean
• cd apps/web && npx tsc --noEmit - no new errors in touched files
• cd apps/web && npx vitest run - 204 files / 1015 passed, 1 pre-existing skip
• Confirmed test_1185_session_storage.py::test_cli_command_panel_uses_session_storage fails identically on main before this change (missing file, unrelated pre-existing issue)
• Ran the full apps/api pytest suite twice in parallel (this branch vs. a clean origin/main worktree, on this shared/loaded box) to separate real regressions from environmental noise: both runs hit failures/errors at the same percentage markers on the same clusters of tests, confirming the noise is pre-existing/load-induced on this box, not introduced by this diff. Re-ran several of the affected tests in isolation afterward and they passed cleanly.

Generated with Claude Code