Governance Pools (Customer Admin)

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

The portal Governance area lets workspace and organization admins inspect three pool families that bound how their workloads consume the platform: workspace concurrency, provider TPM, and organization daily cost. Workspace concurrency supports cap edits and rollback with a required change reason. Provider TPM and organization daily cost are read-only here — those edits live on the operator surface.

For portal steps, use Inspect and change resource limits. This technical companion describes configuration fields and the boundary between customer administration and platform operations. Operators have a separate surface and wider controls.

What this surface covers

Pool family	Scope	What it caps	Portal capability
Workspace concurrency	One workspace	The number of executions a workspace may run at the same time (`soft_cap`, `hard_cap`, lease TTL).	Read, edit caps, roll back to a prior config.
Provider TPM	One organization	Tokens-per-minute against an upstream provider per `(provider, model)`. Sustained + burst windows.	Read only.
Organization daily cost	One organization, UTC day	Total spend in cents an organization may reserve in one UTC day. Reservation-then-commit lifecycle.	Read only.

The Governance landing page (/governance) shows whichever cards your permissions allow. If you have no governance permissions at all, the Governance entry does not appear in navigation.

Who can see what

Three permissions gate the portal:

Permission	Grants
`governance.pool.view`	Read the workspace concurrency pool for workspaces you have access to (config, history, event feed).
`governance.pool.view_org`	Read provider TPM and organization daily cost for the organization (config, history, inventory, events).
`governance.pool.manage`	Edit and roll back the workspace concurrency cap. Read access is implied for that pool only when paired with `governance.pool.view`.

The portal applies these permissions to the active workspace and its parent organization. Two role bundles cover the common cases:

Workspace admin holds governance.pool.view and governance.pool.manage for one workspace. Workspace admins can read and edit workspace concurrency. They cannot read provider TPM or organization daily cost unless governance.pool.view_org is granted separately.
Organization admin holds governance.pool.view and governance.pool.view_org across the organization. Organization admins can read every pool but, in the portal, can only edit workspace concurrency.

Cross-tenant access is denied with a 403 forbidden response. The portal hides cards and navigation entries the active actor cannot read.

Workspace concurrency

Route: /governance/pools/concurrency

The detail page shows:

Soft cap, hard cap, lease TTL, current config ID, who created the config, when, and the recorded change reason.
Soft/hard caps and lease TTL. The current portal does not display live active-lease counts or a completed percentile impact projection; Insufficient history is a placeholder, not a capacity measurement.
Read-only banners for any active override or circuit-break the operator has applied. These are status indicators only — they cannot be edited from the portal.
A historical config table (every supersede creates a new immutable row).
A historical enforcement event feed (rate limited, quota exhausted, policy denied, circuit broken, override used).

Editing the cap

If you have governance.pool.manage on the workspace, the Edit caps button opens a dialog. The dialog requires:

Field	Notes
`soft_cap`	Must be ≤ `hard_cap`.
`hard_cap`	Must be ≥ `soft_cap`. Review the operational impact with the platform owner; the dialog does not currently calculate a percentile-based warning.
`lease_ttl_seconds`	How long an unrenewed lease can sit before the orphan-sweep reclaims it.
`change_reason`	Required. 1–280 characters after trimming. Control characters are stripped server-side before persistence. Carries through to the audit log.

The dialog currently shows Insufficient history rather than a completed impact calculation. Do not interpret that placeholder as proof that a proposed cap is safe.

Submitting writes a new immutable config row. The previous row is superseded but retained — every change is auditable, and you can roll back from the history table.

Rolling back to a prior config

Each row in the workspace concurrency history table has a Rollback action. The dialog:

Pre-fills the target_config_id from the selected row.
Pre-fills change_reason with Rollback to config {target_config_id}. You can override the reason before submitting.
Shows a side-by-side diff of the active and target caps so you can confirm what will change.

A rollback creates a new immutable row that copies the target row’s soft_cap, hard_cap, and lease_ttl_seconds. The history table grows by one row; the original target row is unchanged. Rollback can only target a prior config row for the same workspace pool.

Provider TPM (read only)

Routes:

/governance/pools/tpm — inventory list of every configured (provider, model) pair in the organization.
/governance/pools/tpm/[provider]/[model] — detail view for one pair.

The inventory list is the entry point. Each row shows the provider, model, current soft and hard caps, and when the config was last updated. Clicking a row opens the detail view.

The detail view shows:

rate_tpm (sustained 60-second window cap), burst_tpm (5-second burst window cap), the configured window seconds, the active config ID, who set it, when, and the change reason.
The configured sustained and burst limits, labeled Soft TPM and Hard TPM, with their window durations. The current detail view does not display live token-window usage counters.
A read-only override banner when an operator has lifted the cap. The banner shows the override TTL and reason; it is not editable here.
A history tab listing every prior limits row for this (provider, model) pair.

There is no edit dialog and no rollback. Provider TPM caps and overrides are managed by the operator. If you need a change, see Asking the operator for help.

Organization daily cost (read only)

Route: /governance/pools/cost

The detail view shows:

daily_budget_cents, max_completion_tokens_default, alert_threshold_pct, the active config ID, who set it, when, and the change reason.
Today’s cents_used_today from the live counter.
Read-only banners for any active override or circuit-break.
A historical config table.
A historical enforcement event feed.

What the banners mean

Banner	Meaning	What you can do
Override	An operator has temporarily lifted the daily cap (≤ 24 h TTL). Workloads that would otherwise have been blocked may now run.	Read the override reason and TTL. Cannot edit, extend, or revoke from here.
Circuit-break	An operator has stopped all LLM calls for the organization (≤ 30 d auto-clear). New reservations are rejected with `org_daily_cost_circuit_broken`.	Read the reason and the auto-clear time. Cannot clear from here.

If a circuit-break is active, your workloads will see request-time errors that map back to the circuit-break reason — the events feed is the place to confirm what is happening.

Investigating enforcement events

The cost events feed is a historical audit feed of the two enforcement event types:

Event type	Meaning
`v1.enforcement.org_daily_cost_exceeded`	A reservation was rejected because today’s spend would have crossed the daily cap.
`v1.enforcement.org_daily_cost_circuit_broken`	A reservation was rejected because an active circuit-break is blocking the org.

The feed is intentionally enforcement-only. Reservation lifecycle and reaper telemetry — v1.governance.cost_committed, v1.governance.cost_commit_stuck, v1.governance.cost_commit_dead_letter, and so on — are deliberately excluded. They are operational signals for the platform team and live on the operator observability surface, not in the customer-admin feed.

If you need to know whether a specific call was blocked by a cap or by a circuit-break, the feed’s event_type and attributes payload (pool_id, cents_reserved, cents_used_today, daily_budget_cents, circuit_break_id) tell you which.

What you cannot do here

Some governance actions live on the operator surface only. The portal does not allow customer admins to:

Create, edit, or supersede provider TPM limits.
Create, edit, or supersede organization daily cost limits.
Create, edit, or supersede workload concurrency limits.
Create, edit, or supersede organization or workload token-budget pressure settings.
Apply, extend, or revoke an override (TPM or cost).
Trigger or clear an organization daily cost circuit-break.
See reservation-level cost telemetry (active reservations, stuck reservations, reaper progress, daily snapshot status). Those are surfaced on the operator observability dashboard.

Workspace concurrency is the one pool family with portal-side write access for customer admins — and only for workspaces you have governance.pool.manage on. Runtime admission also checks queue pressure, worker backlog, workload concurrency, and token-budget pressure before an execution starts; those controls are tuned by operators.

Asking the operator for help

If you need a change that is not exposed in the portal — a TPM cap raise for a launch, a temporary cost override, a workload concurrency raise, a token-budget pressure adjustment, or a circuit-break clear — the path is to escalate to your operator owner. The operator can edit those fields from the operator surface and the change will be reflected in your read-only banners on the next refresh where the portal exposes a banner for that pool family.

The operator’s runbook for these surfaces is in the resilience reference: governance spine cost recovery runbook .

Provider TPM Pools — operator-facing reference for the underlying TPM pool primitive.
Org Daily Cost — operator-facing reference for the underlying cost pool primitive.
The current control-plane routes and OpenAPI schemas are authoritative for pool configuration, history, and enforcement-event behavior.