How LoopX Manages Todo States, Claims, and Leases: A Complete Technical Guide

LoopX implements a metadata-driven claim and lease system where todos carry claimed_by and claim_ttl_minutes fields that enforce exclusive agent ownership through CLI validation and mutation authority checks.

The huangruiteng/loopx repository provides a distributed todo management system designed for multi-agent workflows. Understanding how LoopX manages todo states, claims, and leases is essential for building reliable automation pipelines that coordinate work across multiple agents without conflicts.

The Todo Claim Model

LoopX treats every todo as a mutable entity that supports exclusive ownership through claim metadata stored directly in the todo record.

The claimed_by Field and Ownership

Every todo in LoopX includes a claimed_by string field that stores the agent ID currently owning the todo. When an agent claims a todo, this field is populated with their identifier; clearing the claim removes the field entirely.

The schema definition resides in loopx/control_plane/todos/contract.py, which establishes the contract for todo metadata including the ownership field. The CLI commands in loopx/cli_commands/todo.py implement the claim, update, and complete subcommands that read and write this field during mutation operations.

Lease Duration with claim_ttl_minutes

Claims can be temporary through the claim_ttl_minutes field, which defines a time-to-live for the lease. When a claim includes a TTL, the system automatically computes expiration timestamps and stores them in the todo metadata.

The TTL normalization and expiration logic is implemented in loopx/control_plane/todos/contract.py. This allows agents to claim todos for specific durations, ensuring that stalled or abandoned work automatically becomes available for other agents after the lease expires.

Authority Validation and Security

LoopX enforces strict validation to prevent unauthorized mutations to claimed todos through multiple layers of authority checks.

CLI Argument Validation

Before any mutation reaches the control plane, the loopx/cli_commands/todo_argument_validation.py module validates that the --claimed-by argument matches the claim_owner specified in the mutation request. If the caller supplies a mismatched agent ID, the system raises a ValueError and rejects the command.

This validation ensures that agents cannot spoof ownership or accidentally modify todos claimed by other agents through the command-line interface.

Mutation Authority Enforcement

The control plane builds a mutation authority record before processing any todo mutation. This record captures the command type (claim, complete, update) and the acting agent, then validates that the agent matches the current claimed_by value or holds delegated authority.

The mutation authority helper functions in loopx/control_plane/todos/contract.py perform these checks. The test suite in tests/control_plane/test_todo_mutation_authority.py verifies that mismatched owners are rejected, ensuring only the legitimate claim owner (or a properly delegated orchestrator) can modify the todo state.

Claim Scoping and Orchestration

LoopX supports complex delegation patterns where higher-level orchestrators manage work on behalf of subordinate agents.

Delegated Claims via claim_scope_agent_id

The claim_scope_agent_id field enables an orchestrator to claim a todo for a specific subordinate agent while preserving proper authority chains. This scoping mechanism allows the orchestrator to hold the claim technically while the actual work is assigned to the scoped agent.

When validating mutations, LoopX checks both the direct claim owner and the scope agent ID to determine authority. This pattern is exercised in tests/control_plane/test_todo_user_gate_scope.py, which validates that orchestrators can properly delegate and manage claims across agent hierarchies.

Automatic Lease Expiration and Cleanup

The system handles lease lifecycle management automatically, ensuring resources don't remain locked indefinitely.

TTL Checking in TodoIndex

The loopx/control_plane/todos/todo_index.py module builds an in-memory index of todos by processing the rollout event log. During index construction, it identifies expired claims by comparing the current timestamp against the TTL metadata and drops stale claims from the active snapshot.

When cleaning expired leases, the system removes both the claimed_by field and the claim_ttl_minutes metadata, effectively releasing the todo for reclamation by other agents.

Event Logging for Audit Trails

Every claim creation, update, and release generates a todo event in the rollout event log managed by loopx/rollout_event_log.py. These events feed into the todo index via load_rollout_events, allowing the UI and status commands to display current claim states while maintaining a complete audit history of ownership changes.

Practical Examples

The following commands demonstrate claiming, validating, and releasing todos through the LoopX CLI:

# Claim a todo with a 30-minute lease

loopx todo claim --todo-id todo_001 --claimed-by codex-agent \
    --claim-ttl-minutes 30

# Verify the claim is active

loopx todo show --todo-id todo_001 | jq .claimed_by

# Update requires matching claim ownership

loopx todo update --todo-id todo_001 --claimed-by codex-agent \
    --text "Refactor the data pipeline"

# Release the claim explicitly

loopx todo update --todo-id todo_001 --clear-claim

For programmatic access, use the Registry interface to manipulate claims directly:

from loopx.registry import Registry
from loopx.control_plane.todos.contract import normalize_todo_id

registry = Registry()
todo = registry.get_todo(normalize_todo_id("todo_001"))

# Claim with 15-minute TTL

todo["claimed_by"] = "codex-agent"
todo["claim_ttl_minutes"] = 15
registry.save_todo(todo)

# Check validity before working

if registry.is_claim_valid(todo):
    # Perform work...

    pass
else:
    # Handle expired claim

    del todo["claimed_by"]
    del todo["claim_ttl_minutes"]
    registry.save_todo(todo)

Summary

• Metadata Storage: LoopX stores claim state in claimed_by and claim_ttl_minutes fields defined in loopx/control_plane/todos/contract.py.
• Validation Layer: The CLI validates ownership through todo_argument_validation.py before forwarding requests to the control plane.
• Authority Checks: Mutation authority records ensure only claim owners or delegated orchestrators can modify todos.
• Automatic Expiration: The todo_index.py module automatically clears expired claims during index rebuilding.
• Auditability: All claim events are persisted through rollout_event_log.py for complete lifecycle tracking.

Frequently Asked Questions

How does LoopX prevent one agent from modifying another agent's claimed todo?

LoopX enforces ownership through the todo_argument_validation.py module, which validates that the --claimed-by CLI argument matches the claim_owner in the mutation request. The control plane further validates authority through mutation authority checks in contract.py, rejecting any requests where the acting agent does not match the current claimed_by value stored in the todo metadata.

What happens when a todo lease expires in LoopX?

When a lease expires, the loopx/control_plane/todos/todo_index.py module detects the expired TTL during index construction and removes the claimed_by and claim_ttl_minutes fields from the todo snapshot. This cleanup makes the todo immediately available for other agents to claim. The system also logs a lease release event to the rollout event log for audit purposes.

Can an orchestrator claim todos on behalf of other agents?

Yes, LoopX supports delegated claims through the claim_scope_agent_id field. An orchestrator can claim a todo while setting this field to a subordinate agent's ID, allowing the orchestrator to maintain technical ownership while delegating work scope. The mutation authority system validates both the direct owner and the scope agent when processing mutations.

Where are the claim schema and validation rules defined in the LoopX source code?

The todo claim schema, including claimed_by, claim_ttl_minutes, and claim_scope_agent_id fields, is defined in loopx/control_plane/todos/contract.py. This file also contains the mutation authority helper functions. CLI validation logic resides in loopx/cli_commands/todo_argument_validation.py, while the index cleanup logic is implemented in loopx/control_plane/todos/todo_index.py.

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