# Understanding the LoopX Status Data Contract and Attention Queue Derivation

> Explore the LoopX status data contract and learn how the attention queue is derived. Understand health metrics, runtime summaries, and multi-stage enrichment for LoopX.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: deep-dive
- Published: 2026-08-07

---

**The LoopX status data contract is a public-safe JSON-compatible aggregate assembled by [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) that merges health metrics, runtime summaries, and an attention queue, which is derived through a multi-stage enrichment process in [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py) that analyzes per-goal state, global registry findings, and handoff readiness.**

LoopX exposes a comprehensive **status data contract** that aggregates runtime health, goal projections, and actionable items into a deterministic, serializable format safe for external tools and user interfaces. In the `huangruiteng/loopx` repository, this contract is orchestrated by [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) and specifically implements the **attention queue**—a prioritized list of items requiring action—through a sophisticated derivation pipeline located in [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py).

## Anatomy of the LoopX Status Data Contract

The status contract is not a monolithic structure but a composition of specialized read-models merged into a single dictionary by the `build_status` function in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py).

| Component | Source Module | Purpose |
|-----------|---------------|---------|
| **Status collection** | [`loopx/control_plane/status_collection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/status_collection.py) (`collect_status`) | Gathers core health information including contract validation and operator-gate status. |
| **Runtime summaries** | [`loopx/control_plane/status_runtime_summaries.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/status_runtime_summaries.py) (`build_status_runtime_summaries`) | Summarizes recent runs, execution profiles, and stale-run warnings. |
| **Goal-channel projection** | [`loopx/control_plane/goals/goal_channel_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/goals/goal_channel_projection.py) (`build_goal_channel_projection`) | Provides compact views of goal communication channels (Codex, user, monitor). |
| **Handoff readiness** | [`loopx/control_plane/handoff/project_handoff.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/handoff/project_handoff.py) (`project_asset_handoff_readiness`, `project_asset_handoff_state`) | Indicates whether goals are ready for lane handoff. |
| **Attention queue** | [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py) (`build_attention_queue`) | Generates attention items annotated with *waiting_on* flags. |
| **Contract health** | [`loopx/control_plane/work_items/status_contract.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/status_contract.py) (`build_status_contract`) | Verifies high-level status contracts and reports failures. |
| **Operator gate** | [`loopx/control_plane/operator_gate.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/operator_gate.py) (`default_operator_question`) | Captures operator-gate decision results. |
| **Quota status** | [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) (`quota_status`, `quota_with_handoff_outcome_floor`) | Provides current quota status and hand-off outcome floors. |

The final contract follows a deterministic JSON schema:

```json
{
  "ok": true,
  "timestamp": "2026-08-07T12:34:56Z",
  "contract": {...},
  "runtime_summaries": {...},
  "goal_channel_projection": {...},
  "attention_queue": {...},
  "quota": {...},
  "operator_gate": {...},
  "handoff_readiness": {...}
}

```

## How the Attention Queue Is Derived

The attention queue is constructed by `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) through a systematic seven-stage pipeline that transforms raw goal state into actionable items.

### Step 1: Create the AttentionQueueContext

The process begins by instantiating an **`AttentionQueueContext`** dataclass (defined at lines 12-45 in [`attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/attention_queue.py)). This context bundles callbacks required to fetch per-goal data including active-state fields, latest runs, lane recommendations, and autonomous re-plan acknowledgments.

### Step 2: Collect Health Items and Iterate Goals

The function first checks the top-level contract status; if `ok` is `false`, it injects a high-severity `contract_check_failed` item (lines 35-45). It then iterates over each goal in the history (lines 47-67), selecting either the `active_state_todo_attention_item` for goals with active todos or the generic `goal_attention` item otherwise.

### Step 3: Enrich Items with Runtime State

Each item receives additional metadata through enrichment callbacks:

- **Latest run recommended action** (lines 84-93)
- **Autonomous re-plan acknowledgment** (lines 94-99)
- **Project-asset copies** when present (lines 100-104)

### Step 4: Merge Global Registry Findings

The `merge_global_registry_findings` function scans the global registry for health-severity findings (high or action). Depending on the `source_registry_shadow_findings` configuration, these are either attached as *global-registry shadow* data or instantiated as new attention items (lines 46-90).

### Step 5: Insert Backlog and Monitor Candidates

Optional autonomous backlog and monitor candidates are inserted unchanged into the queue via `autonomous_backlog_candidates` and `autonomous_monitor_candidates` parameters (lines 116-120).

### Step 6: Project the Final Queue

Finally, `build_attention_queue_projection` tallies items by their blocking signal: `user_or_controller`, `controller`, `codex`, `external_evidence`, or the configured `monitor_signal_waiting_on`. This projection also records total item count and availability status (lines 93-122).

The resulting structure includes counts for each waiting state:

```json
{
  "available": true,
  "item_count": 7,
  "needs_user_or_controller": 2,
  "needs_controller": 1,
  "needs_codex": 3,
  "watching_external_evidence": 0,
  "watching_monitor": 1,
  "items": [...],
  "goal_filter": "my-goal-id"
}

```

## Working with the Status Contract in Code

### Retrieve the Full Status Contract

Use the public `build_status` entry point in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) to obtain the complete contract:

```python
from loopx.status import build_status
from pathlib import Path

status_contract = build_status(
    contract=contract,
    history=history,
    global_registry=global_registry,
    runtime_root=Path("/var/run/loopx"),
    include_task_graph=True,
)

print(status_contract["attention_queue"]["item_count"])

```

### Build the Attention Queue Directly

For scenarios requiring only the attention queue, instantiate `AttentionQueueContext` and call `build_attention_queue`:

```python
from loopx.control_plane.work_items.attention_queue import (
    AttentionQueueContext,
    build_attention_queue,
)

ctx = AttentionQueueContext(
    active_state_todo_fields=...,
    active_state_todo_attention_item=...,
    latest_run=...,
    goal_attention=...,
    compact_agent_lane_recommendation=...,
    latest_agent_lane_run=...,
    latest_run_recommended_action_for_projection=...,
    compact_autonomous_replan_ack=...,
    latest_autonomous_replan_ack_for_projection=...,
    compact_control_plane_policy=...,
    subagent_activity_for_goal=...,
    interface_budget_cadence_for_runs=...,
    active_state_projection_warning=...,
    enrich_project_asset=...,
    project_asset_latest_validation=...,
    attach_active_state_project_asset_fields=...,
    sync_connected_attention_action_from_todos=...,
    quota_status=...,
    quota_with_handoff_outcome_floor=...,
    normalize_monitor_quiet_attention_display=...,
    build_task_graph_projection=...,
    attach_goal_channel_projection=...,
    attach_dependency_blockers=...,
    autonomous_backlog_candidates=...,
    autonomous_monitor_candidates=...,
    attention_item=...,
    attach_global_registry_shadow_finding=...,
    next_action_projection_warning=...,
    autonomous_replan_obligation_from_runs=...,
    source_registry_shadow_findings=set(),
    monitor_signal_waiting_on="monitor_signal",
)

queue = build_attention_queue(
    contract=contract,
    history=history,
    global_registry=global_registry,
    context=ctx,
    runtime_root=Path("/var/run/loopx"),
)

print(queue["needs_codex"])

```

### Inspect Individual Attention Items

Iterate over attention items to identify specific blockers:

```python
queue = build_attention_queue(...)
for item in queue["items"]:
    if item["waiting_on"] == "codex":
        print(f"{item['goal_id']}: {item['status']} – {item['recommended_action']}")

```

## Summary

- The **LoopX status data contract** is a composite data structure assembled by `build_status` in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py), aggregating health metrics, runtime summaries, and goal projections into a public-safe JSON format.
- The **attention queue** is derived through a seven-stage pipeline in [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py) that contextually enriches per-goal state with runtime recommendations, global registry findings, and handoff readiness.
- **Key entry points**: `build_status` for the full contract, `build_attention_queue` for queue-specific analysis, and `AttentionQueueContext` for dependency injection of data sources.
- The queue projection tallies items by their `waiting_on` status—categorizing blockers as `user_or_controller`, `controller`, `codex`, `external_evidence`, or monitor signals—to surface actionable next steps.

## Frequently Asked Questions

### What components make up the LoopX status data contract?

The contract comprises **status collection** (health validation), **runtime summaries** (execution profiles), **goal-channel projections** (communication channels), **handoff readiness** (lane transition status), **attention queue** (actionable items), **contract health** (schema validation), **operator gate** (decision results), and **quota status** (resource limits), all merged into a single dictionary by [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py).

### How does LoopX determine what an attention item is waiting on?

Each attention item receives a **`waiting_on`** annotation derived from the `build_attention_queue_projection` function in [`attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/attention_queue.py). The system analyzes the goal's active state, latest run recommendations, and external dependencies to classify blockers into categories: `user_or_controller`, `controller`, `codex`, `external_evidence`, or the configurable `monitor_signal_waiting_on` value.

### What is the difference between `build_status` and `build_attention_queue`?

**`build_status`** (in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py)) orchestrates the complete status data contract by invoking multiple read-models including the attention queue builder. **`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)) is a specialized function that constructs only the attention queue portion, requiring an explicit `AttentionQueueContext` and returning the queue projection without other contract components.

### Where is the attention queue projection logic located?

The projection logic that tallies `needs_user_or_controller`, `needs_codex`, and other waiting states resides in **`build_attention_queue_projection`** within [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py) (lines 93-122), which is invoked by the main `build_attention_queue` function after all items have been collected and enriched.