# LoopX Quota Should‑Run Contract: How Agent Eligibility Is Determined

> Understand the LoopX quota should-run contract. Discover how it evaluates agent eligibility by analyzing compute limits, health, operator gates, and slot consumption.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-07

---

**The LoopX quota should‑run contract is the decision routine that evaluates whether an autonomous agent turn may execute based on current quota state, analyzing compute limits, health severity, operator gates, and slot consumption in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py).**

The LoopX framework governs autonomous agent execution through a sophisticated quota system. The **quota should‑run contract** serves as the definitive gatekeeper that determines agent eligibility before each turn, implemented primarily in the [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) module according to the huangruiteng/loopx source code.

## What Is the Should‑Run Contract?

The should‑run contract is a specific decision mode within the generic quota planning logic. When you invoke the CLI command:

```bash
loopx quota should-run --goal-id <goal>

```

The request forwards to [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py), which executes `build_quota_plan(..., mode="should-run")`. This mode evaluates whether current conditions permit an automatic agent turn to proceed, returning a structured payload that includes a `state` field and a human‑readable `reason`.

## How Agent Eligibility Is Determined

The eligibility check follows a five‑step pipeline:

1. **Collects the latest status payload** for the requested goal, including attention items, project assets, and recent runs.
2. **Builds a quota plan** by calling `build_quota_plan` with mode set to `should-run`. Inside this planner, the function `_quota_plan_goal_quota` (lines 438‑478 in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py)) assembles the quota object for the goal.
3. **Derives the quota state** via `quota_status` (lines 72‑85), which evaluates a strict hierarchy of blocking conditions.
4. **Applies hand‑off outcome floor logic** through `quota_with_handoff_outcome_floor` (lines 4‑27), which may impose additional `focus_wait` states.
5. **Returns the quota payload** to the CLI, where the `state` field determines execution rights.

### The Evaluation Hierarchy in `quota_status`

The `quota_status` function evaluates conditions in the following order of precedence:

- **Compute quota** — If `compute` ≤ 0, the state becomes `paused`.
- **Health severity** — If `severity == "high"`, the state becomes `blocked_health`.
- **Operator gate** — If `waiting_on` indicates a controller or user gate, the state becomes `operator_gate`.
- **External evidence** — When `waiting_on == "external_evidence"`, the state becomes `waiting`.
- **Focus‑wait** — If the goal waits on the Codex and lifecycle markers contain a focus‑wait flag, the state becomes `focus_wait`.
- **Quota throttling** — When `waiting_on == "codex"`, the routine compares **allowed slots** versus **spent slots**:
  - If `spent_slots ≥ allowed_slots` → `throttled`.
  - Otherwise → `eligible`.
- **Fallback** — Any other situation defaults to `waiting` ("no active Codex‑ready work").

The resulting quota object includes a **`state`** field (e.g., `eligible`, `throttled`, `focus_wait`) and a **`reason`** field explaining the decision (lines 86‑119).

## Quota States and Their Meanings

| State | Condition | Meaning |
|-------|-----------|---------|
| `eligible` | `waiting_on == "codex"` and slots remain | Agent may run an automatic turn. |
| `throttled` | `spent_slots ≥ allowed_slots` | Quota slots exhausted for the current window. |
| `paused` | `compute` ≤ 0 | No compute quota remains; all automatic turns paused. |
| `blocked_health` | `severity == "high"` | Health or contract blocker prevents spending compute. |
| `operator_gate` | `waiting_on` is `user_or_controller` or `controller` | Operator gate blocks gated delivery; read‑only work may continue. |
| `waiting` | `waiting_on == "external_evidence"` or fallback | External evidence pending or no Codex‑ready work selected. |
| `focus_wait` | Focus‑wait marker present or hand‑off floor not met | Delivery paused awaiting new evidence or novelty. |

## Hand‑Off Outcome Floor Logic

Before finalizing the decision, the system applies `quota_with_handoff_outcome_floor` (lines 4‑27). If the hand‑off outcome floor has not been met, this logic can override the state to `focus_wait` with a detailed reason, ensuring agents do not proceed until substantive progress thresholds are satisfied.

## Code Examples

The following examples demonstrate how `quota_status` evaluates different scenarios:

```python
from loopx.quota import quota_status

# Example: Eligible goal with available compute and slots

goal = {
    "id": "example-goal",
    "quota": {"compute": 1.0, "allowed_slots": 5, "spent_slots": 3},
}
print(quota_status(goal))

```

Output shows the eligible state:

```python
{'compute': 1.0, 'window_hours': 24, 'slot_minutes': 1,
 'allowed_slots': 5, 'spent_slots': 3,
 'state': 'eligible',
 'reason': '1 compute quota; eligible for the next automatic agent turn'}

```

```python

# Example: Throttled because slots are exhausted

goal["quota"]["spent_slots"] = 5
print(quota_status(goal))

```

Output:

```python
{'state': 'throttled',
 'reason': '1 compute quota spent 5/5 slots in this window'}

```

```python

# Example: Operator gate blocks delivery

print(quota_status(goal, waiting_on="controller"))

```

Output:

```python
{'state': 'operator_gate',
 'reason': 'operator gate blocks gated delivery; safe non‑gated steering may continue'}

```

## Key Files in the Implementation

- **[`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py)** — Core quota‑state computation (`quota_status`, `_quota_plan_goal_quota`, `quota_with_handoff_outcome_floor`).
- **[`loopx/cli_commands/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/quota.py)** — CLI wrapper mapping `loopx quota should-run` to the planning logic.
- **[`tests/test_turn_envelope.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_turn_envelope.py)** — Verifies should‑run behavior across states.
- **[`loopx/presentation/renderers/quota_markdown.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/presentation/renderers/quota_markdown.py)** — Renders quota decisions for CLI output.

## Summary

- The **LoopX quota should‑run contract** determines agent eligibility through `build_quota_plan(..., mode="should-run")` in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py).
- **Eligibility hierarchy** evaluates compute, health, operator gates, external evidence, focus‑wait markers, and slot consumption in strict order.
- **Quota states** include `eligible`, `throttled`, `paused`, `blocked_health`, `operator_gate`, `waiting`, and `focus_wait`.
- **Hand‑off outcome floor logic** provides an additional blocking layer before finalizing the decision.
- The CLI command `loopx quota should-run --goal-id <goal>` exposes this contract for external automation and monitoring.

## Frequently Asked Questions

### What triggers the `throttled` state in LoopX?

The `throttled` state occurs when `waiting_on == "codex"` and `spent_slots` reaches or exceeds `allowed_slots` in the current quota window. This condition is evaluated within `quota_status` (lines 72‑85) and prevents additional automatic turns until the quota window resets or slots become available.

### How does the operator gate affect agent execution?

When `waiting_on` indicates `user_or_controller` or `controller`, the `quota_status` function returns `operator_gate`. According to the source code in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py), this state blocks gated delivery while permitting safe non‑gated steering operations to continue. This ensures human oversight maintains control over critical execution paths.

### What is the difference between `waiting` and `focus_wait` states?

The `waiting` state indicates the goal is pending external evidence or has no active Codex‑ready work, serving as a general pause condition. In contrast, `focus_wait` is a specific blocking state that occurs when lifecycle markers indicate the goal requires new evidence or novelty before proceeding, or when the hand‑off outcome floor has not been met. The latter enforces stricter readiness criteria before agents may resume.

### Where is the quota state actually computed in the codebase?

The definitive quota state computation resides in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py), specifically within the `quota_status` function (lines 72‑85) which derives the state, and `_quota_plan_goal_quota` (lines 438‑478) which assembles the quota object. Additional processing occurs in `quota_with_handoff_outcome_floor` (lines 4‑27), which may modify the state based on outcome floor requirements.