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

> Learn how to monitor LoopX applications efficiently. Discover the built-in monitor lane and its monitor-poll operation for effective goal state observation without quota usage.

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

---

**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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli/entrypoint.py) exposes the `quota monitor-poll` command with several customization flags:

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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:

```python
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:

```bash

# 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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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.