# LoopX Status/Attention Queue Architecture: Multi-Source Aggregation and Projection

> Discover the LoopX status attention queue architecture. Learn how LoopX aggregates contract health, goal data, and scans into a centralized queue for proactive intervention and projection.

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

---

**LoopX aggregates contract health flags, historical goal data, and global registry scans into a centralized attention queue using the `build_attention_queue` function in [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py), which projects a deterministic view of items requiring user or controller intervention.**

The status/attention queue architecture in LoopX serves as the central nervous system for operational visibility, transforming disparate data sources into a unified view of work requiring human or automated attention. By combining real-time contract states, persisted goal histories, and global registry health scans, the system generates a prioritized projection of actionable items. This architecture is implemented across [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) and [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py), providing both CLI and programmatic interfaces for monitoring system health.

## Core Data Flow

The attention queue pipeline ingests data from three primary sources and processes it through a structured enrichment layer before emitting a final projection.

### Collect Status from Three Sources

The pipeline begins in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) where `collect_status` (lines 1180-1189) orchestrates the gathering of three distinct payloads:

1. **Contract data** – Global health flags and contract-check failures from the current status request
2. **Historical goal data** – Per-goal todo items, run metadata, and active-state projections from persisted history
3. **Global registry findings** – Health scans and shadow-findings from the global registry

These payloads pass into `build_attention_queue` as explicit parameters:

```python
queue = build_attention_queue(
    contract=contract,
    history=history,
    global_registry=global_registry,
    context=AttentionQueueContext(...),
)

```

*Source:* [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) → `collect_status` and `build_attention_queue`.

### Create the AttentionQueueContext

The `AttentionQueueContext` dataclass (defined in [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py)) bundles every helper function needed to enrich individual attention items. This container holds over twenty specialized utilities including:

- `active_state_todo_attention_item` and `goal_attention` for todo-state resolution
- `latest_run_recommended_action_for_projection` for run-based recommendations
- `enrich_project_asset` and `attach_active_state_project_asset_fields` for asset handling
- `attach_global_registry_shadow_finding` for registry health integration
- `build_task_graph_projection` for optional dependency visualization

By encapsulating these helpers in a single context object, the architecture maintains clean separation between raw data and transformation logic.

### Iterate and Enrich Per-Goal Items

For each goal in `history["goals"]`, the system selects either the *active-state* attention item (when live todos exist) or the generic goal attention template. The enrichment process attaches:

- Latest run recommendations and autonomous replan acknowledgments
- Control-plane policy mappings and quota status
- Project asset metadata including budget and orchestration data
- Task-graph projections (when enabled)
- Dependency blockers and channel projections

This iteration ensures every goal receives contextual metadata specific to its current operational state.

### Merge Global Registry Findings

After processing individual goals, the `merge_global_registry_findings` function (in [`attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/attention_queue.py)) integrates health items derived from the global registry scan. This step attaches shadow findings to appropriate quota items and ensures system-wide health signals appear alongside goal-specific concerns.

### Build the Final Projection

The `build_attention_queue_projection` function (lines 100-108) assembles a deterministic, UI-friendly dictionary structure:

```json
{
    "available": true,
    "item_count": <int>,
    "needs_user_or_controller": <int>,
    "needs_controller": <int>,
    "needs_codex": <int>,
    "watching_external_evidence": <int>,
    "watching_monitor": <int>,
    "items": [ ... enriched attention items ... ],
    "goal_filter": <optional>,
    "autonomous_backlog_candidates": <optional>,
    "autonomous_monitor_candidates": <optional>
}

```

These counters provide immediate cardinality metrics without requiring UI clients to rescan the item list.

## Architecture Design Principles

### Separation of Concerns

Raw data from contracts, history, and registry remains immutable throughout the pipeline. All transformations occur within the `AttentionQueueContext`, enabling isolated unit testing of individual enrichment helpers without mocking entire data sources.

### Extensibility via Context Injection

Adding new attention sources requires only a new helper function injected into the `AttentionQueueContext`. The core iteration loop remains unchanged, supporting new monitoring signals or health checks without modification to `build_attention_queue`.

### Deterministic Ordering and Safety

The architecture guarantees that `item_count` and categorical counters (`needs_user_or_controller`, `needs_controller`, etc.) reflect precise calculations performed during projection construction. Additionally, the system excludes items from stopped goals unless `include_stopped_goal_context=True` is explicitly passed, ensuring dashboards display only runnable attention items.

## Practical Code Examples

### Building a Queue for a Specific Goal

To programmatically construct the attention queue for inspection or custom tooling:

```python
from loopx.status import collect_status, build_status_collection_context

# Assume contract, history, and global_registry are already-loaded dicts

contract = {...}
history = {...}
global_registry = {...}

queue = build_attention_queue(
    contract=contract,
    history=history,
    global_registry=global_registry,
    runtime_root=None,               # Optional Path to runtime root

    include_task_graph=False,       # Set True to include task-graph projections

    goal_id_filter=None,            # Filter to specific goal ID if desired

    include_stopped_goal_context=False,
)

print(queue["item_count"])          # Total attention items

for item in queue["items"]:
    print(item["goal_id"], item["waiting_on"], item["status"])

```

*Relevant source:* [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) lines 1180-1189 and [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py) lines 23-70.

### Inspecting Controller-Only Items

To determine how many items require elevated controller privileges:

```python
needs_controller = queue["needs_controller"]
print(f"Controller-only items awaiting action: {needs_controller}")

```

*Source:* `build_attention_queue_projection` in [`attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/attention_queue.py) lines 100-108.

### Finding the Most Urgent Item

Locate the first item requiring immediate user or controller attention:

```python
urgent = next(
    (it for it in queue["items"] if it["waiting_on"] in {"user_or_controller", "controller"}),
    None,
)
if urgent:
    print("Top urgent item:", urgent["goal_id"], urgent["status"])

```

*Logic reference:* `build_attention_queue_projection` lines 100-106 in [`attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/attention_queue.py).

## Key Source Files

| File | Role |
|------|------|
| [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) | Public façade exposing `build_attention_queue` and `collect_status` |
| [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py) | Core implementation with `AttentionQueueContext` and projection logic |
| [`loopx/control_plane/status/attention_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/status/attention_projection.py) | Helpers for backlog/monitor candidates and projection shaping |
| [`loopx/control_plane/status/registry_health_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/status/registry_health_projection.py) | Global registry findings integration |
| [`loopx/control_plane/work_items/attention_item.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_item.py) | Factory for single attention-item dictionaries |
| [`loopx/control_plane/todos/active_state_todo_parser.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/todos/active_state_todo_parser.py) | Active-state todo parsing for live goal attention |
| [`loopx/control_plane/status/monitor_display_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/status/monitor_display_projection.py) | Monitor-quiet normalization and display logic |

## Summary

- The LoopX attention queue aggregates **three distinct data sources**—contract health flags, historical goal data, and global registry scans—into a unified projection.
- **`AttentionQueueContext`** encapsulates all enrichment logic, enabling modular testing and extension without modifying core data aggregation.
- **`build_attention_queue`** in [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py) (lines 23-70) implements the primary transformation pipeline, while [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) provides the public API entry point.
- The projection includes deterministic counters (`needs_user_or_controller`, `needs_controller`) that eliminate the need for UI-side recalculation.
- Stopped goals are automatically filtered unless `include_stopped_goal_context=True` is specified, ensuring operational dashboards remain focused on actionable work.

## Frequently Asked Questions

### What are the three primary data sources for the LoopX attention queue?

The attention queue draws from the **current contract** (global health flags and contract-check failures), **historical goal data** (per-goal todos, run metadata, and active-state information), and **global registry findings** (health scans and shadow-findings). These sources feed into `build_attention_queue` via the `contract`, `history`, and `global_registry` parameters respectively.

### How does LoopX prevent stopped goals from polluting the attention queue?

By default, the architecture excludes any items originating from stopped goals unless the caller explicitly passes `include_stopped_goal_context=True` to `build_attention_queue`. This safety mechanism ensures that dashboards and CLI outputs display only runnable attention items relevant to active operations.

### What purpose does the AttentionQueueContext serve in the architecture?

`AttentionQueueContext` acts as a dependency injection container bundling over twenty enrichment helpers—ranging from `enrich_project_asset` to `attach_global_registry_shadow_finding`. This design decouples raw data sources from transformation logic, allowing developers to add new attention signals by injecting new helpers without altering the core iteration loop in [`attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/attention_queue.py).

### How does the projection determine how many items need controller intervention?

During the final projection phase, `build_attention_queue_projection` (lines 100-108) scans all enriched items and increments counters based on each item's `waiting_on` field. Items marked for `controller` or `user_or_controller` increment their respective counters, providing immediate cardinality metrics in the returned dictionary without requiring client-side filtering.