How to Monitor LoopX Applications Using the Built-In Monitor Lane

LoopX provides a built-in monitor lane that observes goal states without consuming quota through the monitor-poll operation implemented in loopx/control_plane/quota/monitor_poll.py.

The huangruiteng/loopx repository offers a dedicated monitoring subsystem that allows you to track application state, detect material changes, and maintain audit trails without spending quota resources. When you monitor LoopX applications, you leverage a specialized control plane that records monitor events, manages todo states, and persists observations to the runtime file system.

Understanding the LoopX Monitor Lane

LoopX implements monitoring as a quota-free observation channel distinct from regular execution lanes. The monitor lane captures the state of a goal through a monitor-poll operation, which records structured events and optionally updates todo items based on what it observes.

The monitoring system supports four primary monitor modes:

• due: Triggered when a monitor todo item reaches its scheduled time
• external: Used for external observations that don't consume slot budget
• blocked-successor-wait: Indicates the goal is waiting for a successor to complete
• quiet: Silent monitoring that skips until a material transition occurs

These modes are determined by policy predicates in loopx/control_plane/quota/monitor_poll_policy.py, such as allows_due_monitor_poll and allows_no_spend_external_monitor_poll.

Core Implementation in monitor_poll.py

The heart of the monitoring system resides in loopx/control_plane/quota/monitor_poll.py. This module implements the record_quota_monitor_poll_for_decision function, which orchestrates the entire observation flow.

Building the Monitor Event

When you initiate a monitor poll, the system constructs a detailed event payload through build_quota_monitor_poll_event. This event captures:

• Source: The origin of the poll, which must be one of the allowed VALID_SLOT_SPEND_SOURCES values defined in the quota system
• Monitor target: Built via build_quota_monitor_target, representing the specific object under observation
• Metadata: Including todo_id, target_key, result_hash, and a human-readable reason_summary
• Turn identification: The turn_instance_id used to track the specific execution turn

Persistence and Replay Mechanics

If the poll executes with execute=True, the system persists the event to the runtime's runs folder. The function generates both a json_path and markdown_path for the event, appending entries to an index.jsonl file for later querying.

The helper _status_with_monitor_poll injects the new poll into the run-history of the status payload, ensuring downstream components see the observation. This mechanism supports event replay: if a poll for the same turn already exists (identified by turn_instance_id), _find_monitor_poll_turn retrieves the existing record and merges it with the current decision, preventing duplicate writes.

CLI Interface for Monitoring

You can trigger monitor polls directly from the command line using the LoopX CLI. The entry point in loopx/cli/entrypoint.py exposes the quota monitor-poll command with several customization flags:

loopx quota monitor-poll \
    --goal-id g123 \
    --todo-id todo_monitor \
    --material-change \
    --source quota-monitor \
    --execute

This command writes a JSON record under /tmp/runtime/goals/g123/runs/<timestamp>-quota-monitor-poll.json and updates the status run history accordingly. Available flags include --target-key, --next-agent-todo, and --material-change to customize the observation and any follow-up actions.

Todo Subsystem Integration

Monitoring integrates tightly with LoopX's todo management system. The loopx/control_plane/todos/todo_summary.py module provides helper functions that identify items on the monitor lane:

• todo_item_is_due_monitor: Detects todos scheduled for immediate monitoring
• todo_item_missing_monitor_schedule: Identifies gaps in monitoring schedules
• todo_item_is_watch_only_monitor: Flags todos designated for passive observation

These helpers feed into the todo summary view, which surfaces due monitor items and claimed monitor todos. The scheduler module at loopx/control_plane/scheduler/monitor_todo.py resolves these items and checks if they are due for polling.

Practical Examples

Python API Integration

To record a monitor poll programmatically, import the decision recorder and configure the event renderers:

from loopx.control_plane.quota.monitor_poll import record_quota_monitor_poll_for_decision

def render_md(event):
    return f"## Monitor Event\n- Mode: {event['monitor_event']['monitor_mode']}\n- Reason: {event['monitor_event']['reason_summary']}"

before = {
    "goal_id": "g123",
    "effective_action": "monitor_quiet_skip",
    "heartbeat_recommendation": {"recommended_mode": "monitor_quiet_until_material_transition"},
}
status = {"runtime_root": "/tmp/runtime"}

result = record_quota_monitor_poll_for_decision(
    before,
    status,
    goal_id="g123",
    after_decision=lambda s: s,
    render_markdown=render_md,
    execute=False,  # Dry-run mode

    source="quota-monitor",
    todo_id="todo_monitor",
    material_change=False,
)
print(result["monitor_event"]["monitor_mode"])

# Output: monitor_quiet_until_material_transition

Command Line Execution

For production monitoring with persistence enabled:

# Execute a real monitor poll with material change detection

$ loopx quota monitor-poll \
    --goal-id g123 \
    --todo-id todo_monitor \
    --material-change \
    --source quota-monitor \
    --execute

# Verify the written record

$ cat /tmp/runtime/goals/g123/runs/*-quota-monitor-poll.json

Summary

• Quota-free observation: The monitor lane lets you observe goal states without consuming execution budget, implemented via record_quota_monitor_poll_for_decision in loopx/control_plane/quota/monitor_poll.py.
• Structured events: Each poll generates a detailed monitor event capturing source, mode, target, and metadata, persisted to the runtime runs folder.
• Replay support: The system detects existing polls by turn_instance_id and merges new decisions to prevent duplicates.
• Todo integration: Monitor items are tracked through specialized helpers in loopx/control_plane/todos/todo_summary.py that identify due dates, schedule gaps, and watch-only states.
• Dual interface: Access monitoring through both the Python API or the loopx quota monitor-poll CLI command.

Frequently Asked Questions

How does LoopX prevent duplicate monitor events?

The system tracks each poll by its turn_instance_id. When record_quota_monitor_poll_for_decision runs, it calls _find_monitor_poll_turn to check for existing records from the same turn. If found, it merges the new decision with the previous payload rather than creating a separate entry, ensuring the run history remains clean and idempotent.

What determines which monitor mode is selected?

Monitor modes are selected by policy functions in loopx/control_plane/quota/monitor_poll_policy.py. The code evaluates predicates like allows_due_monitor_poll for scheduled todos, allows_no_spend_external_monitor_poll for external observations, and checks for blocked successor states. The resulting mode (due, external, blocked-successor-wait, or quiet) is embedded in the monitor event's metadata.

Can I monitor LoopX applications without writing to disk?

Yes. When calling record_quota_monitor_poll_for_decision, set execute=False to run in dry-run mode. This builds the monitor event and returns the structured payload without persisting to json_path, markdown_path, or index.jsonl. The CLI also supports dry-run flags to preview actions before committing them to the runtime folder.

Where are monitor events stored in the file system?

Executed monitor events are written to the runtime root under goals/{goal_id}/runs/. Each event generates a timestamped JSON file (e.g., <timestamp>-quota-monitor-poll.json), a corresponding markdown representation, and an entry in index.jsonl for chronological indexing. The _status_with_monitor_poll helper then updates the in-memory status object's run history to reference these paths.

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