# How the LoopX Quota System Decides Whether a Goal Should Run

> Discover how the LoopX quota system decides if a goal runs. Learn about its multi-stage pipeline and the JSON payload determining goal execution status.

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

---

**LoopX determines whether a goal runs through a multi-stage quota-decision pipeline in the `loopx/control_plane/quota/` package that returns a JSON payload with `should_run: true`, `false`, or a paused state.**

The **quota system** is the central gatekeeper that prevents wasteful compute cycles in the LoopX agent runtime. When you invoke `loopx quota should-run` — or call `build_quota_should_run()` programmatically — the system executes a ten-step pipeline that evaluates quota eligibility, goal health, capability constraints, and repair obligations before granting execution permission.

## The 10-Step Quota Decision Pipeline

Each step in the pipeline is implemented across [`should_run.py`](https://github.com/huangruiteng/loopx/blob/main/should_run.py) and [`should_run_prepare.py`](https://github.com/huangruiteng/loopx/blob/main/should_run_prepare.py), with clear separation between plan construction, decision preparation, and final payload assembly.

### Step 1: Resolve the CLI Entry Point

The `quota should-run` command dispatches to `build_quota_should_run` in [[`loopx/control_plane/quota/should_run.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/should_run.py)](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/should_run.py#L38-L46). This function serves as the primary API surface for both CLI and programmatic consumers.

```bash
loopx quota should-run --goal-id my-goal

```

### Step 2: Build the Quota Plan

The pipeline calls `_build_quota_plan_for_goal` to query the **status payload** and assemble a **quota plan** containing the goal's quota item(s) and any associated health items. This plan acts as the working data structure for all subsequent decisions.

### Step 3: Locate the Goal's Quota Item

The system searches the plan for a candidate whose `goal_id` matches the requested goal. If no matching quota item exists, the goal is ineligible for automatic execution.

### Step 4: Quick-Exit for Paused Goals

If `_quota_item_is_paused` returns `true`, the pipeline immediately returns a **paused payload**. This disables compute and notifies the scheduler that the goal cannot proceed — for example, when quota has been exhausted or manually suspended.

```python
#paused check in loopx/control_plane/quota/should_run.py#L94-L99

```

### Step 5: Prepare the Detailed Decision Context

`_prepare_quota_should_run_item` (in [`should_run_prepare.py`](https://github.com/huangruiteng/loopx/blob/main/should_run_prepare.py)) constructs a [`_QuotaDecisionPreparation`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/should_run_prepare.py#L36-L59) dataclass gathering:

- **Quota state** — `eligible`, `paused`, or blocked status
- **Goal health** — `goal_health_ok` and dependency blockers
- **Agent identity and work-mode**
- **Todo summaries** for both user and agent lanes
- **Capability gates** — whether required capabilities are present
- **Monitor debt** — overdue quota monitors that need attention
- **Stall-repair hints** — signals that self-repair may be needed

### Step 6: Apply Stall-Repair and Delivery Guards

The [`apply_stall_repair_delivery_guard`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/should_run_prepare.py#L110-L116) function evaluates whether an **outcome-floor blocker** or **projection gap** requires deferring normal delivery. It may set:

- `normal_delivery_allowed = false`
- `recovery_allowed = true`
- `self_repair_allowed = true`

This ensures the agent repairs its understanding before spending quota on potentially misdirected work.

### Step 7: Build the Work-Lane Contract

Using the quota item and prepared data, [`build_quota_work_lane_contract`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/should_run_prepare.py#L90-L104) creates a **work-lane contract** encoding which Todo or monitor the agent should act upon. Task-orchestration contracts are appended when applicable.

### Step 8: Resolve the Quota Route

`_resolve_quota_should_run_route` translates preparations into a **route struct** containing:

- `should_run` flag
- `agent_lane_next_action`
- `payload_work_lane_contract`

Precedence rules from **settled replay** are then applied to handle edge cases where historical decisions constrain current routing.

### Step 9: Apply Selected-Todo Guards

After route construction, `selected_todo_projection` identifies the exact Todo to act on. The system attaches:

- **Workspace guard** — prevents Todo reordering during policy re-evaluation
- **Boundary-projection-repair hints** — ensures stability across decision cycles

### Step 10: Build the Final Payload

[`_build_quota_should_run_payload`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/should_run.py#L326-L338) assembles the final JSON consumed by the runtime, including:

- Interaction contracts
- Scheduler hints
- Heartbeat recommendations
- **Execution obligation** (`should_run: true/false`)

## Core Decision Factors in the Quota System

Seven primary factors determine whether LoopX executes a goal:

1. **Quota State** — The quota item's `state` field must be `eligible`; `paused` or other states block execution
2. **Goal Health** — Health items in `build_quota_should_run` can flag missing dependencies or configuration errors
3. **Workspace Guard** — Locks the selected Todo against reordering when policy routes change
4. **Capability Gate** — Requires capability monitors or fallback strategies when the agent lacks needed capabilities
5. **Stall-Repair & Projection Gap** — Self-repair takes precedence over normal delivery when understanding gaps are detected
6. **Monitor Debt Arbitration** — Overdue quota monitors may be prioritized over goal advancement
7. **Inbox Priority** — Lark or operator inbox replies bypass normal quota checks entirely

Any factor forcing `should_run` to `false` produces a payload with `"decision": "skip"` and an explanatory `"reason"` field.

## Programmatic Usage Examples

### Basic Quota Check

```python
from loopx.control_plane.quota.should_run import build_quota_should_run

status = {...}  # status payload from runtime

payload = build_quota_should_run(
    status_payload=status,
    goal_id="my-goal",
    include_scheduler_detail=True,
)

if payload["should_run"]:
    print("Goal will run automatically")
else:
    print("Goal is paused or blocked:", payload["reason"])

```

### Inspecting Why a Goal Is Paused

```python
payload = build_quota_should_run(status, goal_id="my-goal")
print(payload["reason"])

# → "compute quota is 0; automatic agent turns are paused"

```

### Sample CLI Output

```json
{
  "ok": true,
  "mode": "should-run",
  "goal_id": "my-goal",
  "decision": "run",
  "should_run": true,
  "reason": "quota eligible and no blockers"
}

```

## Key Source Files in the Quota System

| File | Responsibility |
|------|---------------|
| [`loopx/control_plane/quota/should_run.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/should_run.py) | Top-level entry point, quota plan construction, pause/normal path decision, final payload assembly |
| [`loopx/control_plane/quota/should_run_prepare.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/should_run_prepare.py) | Context gathering into `_QuotaDecisionPreparation`, stall-repair guards, work-lane contract building |
| [`loopx/control_plane/quota/turn_envelope.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/turn_envelope.py) | Wraps decisions into turn envelopes for scheduler consumption |
| [`loopx/control_plane/quota/should_run_packet.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/should_run_packet.py) | Payload packet helpers including `_execution_obligation` |
| [`loopx/control_plane/quota/stall_repair.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/stall_repair.py) | Self-repair logic for projection gap scenarios |
| [`loopx/control_plane/quota/goal_boundary.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/goal_boundary.py) | Boundary determination for registry path and reward-memory gating |
| [`loopx/control_plane/quota/monitor_poll.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/monitor_poll.py) | Monitor-due logic affecting quota prioritization |
| [`loopx/control_plane/quota/recent_runs.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/recent_runs.py) | Recent run data for accountable delivery tracking |

## Summary

- The **quota decision pipeline** in `loopx/control_plane/quota/` is the authoritative gatekeeper for goal execution
- **Ten sequential steps** transform a status payload into a runnable decision with full context
- **Quick-exit on pause** prevents wasted computation when quota is exhausted or manually suspended
- **Stall-repair guards** prioritize self-correction over forward progress when understanding gaps exist
- **Workspace guards and selected-Todo protection** ensure stability across policy re-evaluations
- **Seven core factors** — from quota state to inbox priority — collectively determine `should_run`

## Frequently Asked Questions

### What triggers a goal to be paused in the LoopX quota system?

A goal pauses when its quota item reports a non-eligible state via `_quota_item_is_paused` — typically when compute quota reaches zero, when an operator manually suspends the goal, or when a billing/policy constraint applies. The pipeline returns immediately with a **paused payload** that disables automatic agent turns and notifies the scheduler.

### How does stall-repair affect whether a goal runs?

When `apply_stall_repair_delivery_guard` detects an **outcome-floor blocker** or **projection gap**, it may disable `normal_delivery_allowed` and enable `self_repair_allowed`. In this case, the goal's `should_run` may still be `true`, but the **work-lane contract** directs the agent toward repair actions rather than forward progress on the primary objective.

### Can I bypass the quota system to force a goal to run?

The quota system is designed as the authoritative gatekeeper, but **inbox priority** for Lark or operator replies bypasses normal quota checks. For programmatic override, you would need to manipulate the status payload's quota item state directly — not recommended as it violates LoopX's safety invariants around compute spending and health validation.

### Where is the final `should_run` boolean actually set?

The boolean is materialized in `_resolve_quota_should_run_route` within [`should_run.py`](https://github.com/huangruiteng/loopx/blob/main/should_run.py), then encoded into the **execution obligation** field by `_build_quota_should_run_payload`. The route resolution applies precedence rules from settled replay and evaluates all prepared guards before finalizing the decision.