Key Data Flow Paths in LoopX: From Registry to Runtime State

LoopX moves data from a JSON registry through runtime root resolution, goal validation, state refresh cycles, projection generation, and HTTP status endpoints to create a closed feedback loop between configuration and execution.

The huangruiteng/loopx repository implements a runtime management system that transforms static configuration into monitored execution state. Understanding how data flows between the registry file, runtime directories, and projection layers is essential for extending the system or debugging execution mismatches. These paths demonstrate how LoopX maintains consistency between declared goals and actual runtime behavior.

How LoopX Transforms Registry Files into Runtime Roots

The data flow begins when LoopX ingests the central registry configuration and determines where runtime artifacts will live.

Loading and Resolving the Runtime Directory

In loopx/history.py, the function load_registry reads the JSON registry file, which contains the common_runtime_root key defining the base directory for all runtime data. This registry object is then passed to loopx/paths.py, where resolve_runtime_root extracts the path from registry["common_runtime_root"] or defaults to ~/.codex/loopx if unspecified. The function resolves this path relative to the project root and returns the absolute runtime root directory.

# Simplified flow showing registry to runtime resolution

registry = load_registry(registry_path)                     # loopx/history.py

runtime_root = resolve_runtime_root(registry)               # loopx/paths.py

This resolution step anchors all subsequent file operations, ensuring that goal directories, state files, and projections are written to a consistent location regardless of where the command is executed.

Goal Lifecycle and Archiving Workflows

Once the runtime root is established, LoopX manages individual goals through validation, archiving, and state transition logic defined in loopx/runtime.py.

Validating and Archiving Goals via runtime.py

The archive_runtime_goal function orchestrates the movement of goal data from active runtime to archive storage. It first calls validate_goal_id_path_segment to ensure the goal ID is filesystem-safe, then checks registry_goals to confirm the goal exists in the registry. After verification, it relocates the goal directory to an archive location and returns a payload consumed by render_archive_runtime_markdown for generating human-readable summaries.

payload = archive_runtime_goal(
    registry_path=repo_path / "registry.json",
    runtime_root_override=None,
    goal_id="my-goal",
    archive_root=None,
    allow_registered=False,
    execute=True,
)

Setting execute=False performs a dry-run, returning the projected archive_path without moving files, which is useful for CLI previews and automated safety checks.

State Refresh and Projection Generation

After goals are active in the runtime directory, LoopX continuously refreshes execution state and builds shared projections that serve as the single source of truth for downstream consumers.

Building Shared Runtime Projections

The loopx/state_refresh.py module drives this phase. It loads the current run file, parses the active state and next-action text, then invokes build_shared_runtime_projection to create a structured view of the runtime. This projection is persisted via write_shared_runtime_projection to the runtime root, where it becomes accessible to the status server and summary generators.

projection = build_shared_runtime_projection(state, ...)   # state_refresh.py

write_shared_runtime_projection(runtime_root, projection) # state_refresh.py

Detecting Action Mismatches

In loopx/state_projection.py, the system compares the active next-action against the recommended action from the latest run. The function next_action_projection_warning uses helpers like _action_projection_compare_text and actions_are_projection_aligned to determine if the current state has drifted from the expected execution path.

warning = next_action_projection_warning(
    active_state_next_action=active_next,
    latest_run_recommended_action=run_next,
)

When a mismatch is detected, the warning payload includes metadata about the divergence kind, enabling CLI tools to alert users or triggering automated remediation workflows.

Serving Runtime Status via HTTP

LoopX exposes the internal projection state through HTTP endpoints defined in loopx/status_server.py. The /status endpoint reads the shared projection files from the runtime root and returns JSON-encoded status data, allowing external dashboards and CLI tools to poll for current execution state without direct filesystem access.

@app.get("/status")
async def status():
    return load_shared_runtime_projection(runtime_root)   # status_server.py

This decouples the execution environment from observation tools, supporting distributed monitoring scenarios where the status server runs in a container or remote host.

CLI Entry Points and Orchestration

The top-level entry point in loopx/entrypoint.py forwards command-line arguments to loopx.cli.main, which routes to sub-commands like loopx archive, loopx refresh, or loopx status. This entry point acts as the traffic controller that instantiates the data flows described above based on user intent.

# entrypoint.py

def main(argv=None):
    return cli_main(argv or sys.argv[1:])

By centralizing argument parsing and dispatch here, LoopX ensures consistent error handling and logging across all execution paths.

Summary

• Registry Resolution: load_registry and resolve_runtime_root in loopx/history.py and loopx/paths.py establish the filesystem foundation using common_runtime_root or the ~/.codex/loopx default.
• Goal Archiving: archive_runtime_goal validates goal IDs against the registry, moves directories, and generates markdown summaries via render_archive_runtime_markdown.
• State Projection: build_shared_runtime_projection and write_shared_runtime_projection in loopx/state_refresh.py convert raw run data into structured projections.
• Mismatch Detection: next_action_projection_warning in loopx/state_projection.py compares active and recommended actions using _action_projection_compare_text.
• External Exposure: loopx/status_server.py serves projections via HTTP /status, while loopx/entrypoint.py wires CLI commands to these internal flows.

Frequently Asked Questions

How does LoopX determine where to store runtime data?

LoopX calls resolve_runtime_root in loopx/paths.py, which checks the common_runtime_root key in the registry JSON file. If this key is missing or null, it defaults to ~/.codex/loopx and resolves the path relative to the project root. This ensures that runtime directories are predictable and configurable per project.

What happens during a dry-run archive operation?

When archive_runtime_goal receives execute=False, it performs validation steps—including checking validate_goal_id_path_segment and registry_goals membership—computes the target archive path, and returns a payload containing the projected destination. No filesystem moves occur, allowing users to preview the operation via render_archive_runtime_markdown before committing changes.

How does LoopX detect when execution deviates from the plan?

The next_action_projection_warning function in loopx/state_projection.py compares the active state's next-action text against the latest run's recommended action using actions_are_projection_aligned. If the comparison fails, it returns a warning dictionary describing the mismatch kind, enabling the CLI or status consumers to surface drift alerts to users.

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