Understanding the LoopX Status Data Contract and Attention Queue Derivation

The LoopX status data contract is a public-safe JSON-compatible aggregate assembled by 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 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 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.

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.

Component	Source Module	Purpose
Status collection	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 (build_status_runtime_summaries)	Summarizes recent runs, execution profiles, and stale-run warnings.
Goal-channel projection	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 (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 (build_attention_queue)	Generates attention items annotated with waiting_on flags.
Contract health	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 (default_operator_question)	Captures operator-gate decision results.
Quota status	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:

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

{
  "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 to obtain the complete contract:

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:

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:

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, 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 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.

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. 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) 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) 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 (lines 93-122), which is invoked by the main build_attention_queue function after all items have been collected and enriched.

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