How the LoopX Quota System Decides Whether a Goal Should Run

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 and 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#L38-L46). This function serves as the primary API surface for both CLI and programmatic consumers.

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.

#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) constructs a _QuotaDecisionPreparation 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 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 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 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

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

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

{
  "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	Top-level entry point, quota plan construction, pause/normal path decision, final payload assembly
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	Wraps decisions into turn envelopes for scheduler consumption
loopx/control_plane/quota/should_run_packet.py	Payload packet helpers including _execution_obligation
loopx/control_plane/quota/stall_repair.py	Self-repair logic for projection gap scenarios
loopx/control_plane/quota/goal_boundary.py	Boundary determination for registry path and reward-memory gating
loopx/control_plane/quota/monitor_poll.py	Monitor-due logic affecting quota prioritization
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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}