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

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, 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 and 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 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:

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

Source: 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) 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) 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:

{
    "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:

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 lines 1180-1189 and loopx/control_plane/work_items/attention_queue.py lines 23-70.

Inspecting Controller-Only Items

To determine how many items require elevated controller privileges:

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

Source: build_attention_queue_projection in attention_queue.py lines 100-108.

Finding the Most Urgent Item

Locate the first item requiring immediate user or controller attention:

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.

Key Source Files

File	Role
loopx/status.py	Public façade exposing build_attention_queue and collect_status
loopx/control_plane/work_items/attention_queue.py	Core implementation with AttentionQueueContext and projection logic
loopx/control_plane/status/attention_projection.py	Helpers for backlog/monitor candidates and projection shaping
loopx/control_plane/status/registry_health_projection.py	Global registry findings integration
loopx/control_plane/work_items/attention_item.py	Factory for single attention-item dictionaries
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	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 (lines 23-70) implements the primary transformation pipeline, while 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.

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.

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