How LoopX Implements the Lifetime Goal Invariant: Persistence, Turn Envelopes, and Quota Validation

LoopX enforces the lifetime goal invariant through durable file-based state persistence, cryptographically signed turn envelopes, and strict quota validation that together ensure every long-running agent goal survives across turn boundaries, tool invocations, and system restarts.

The lifetime goal invariant is a core architectural guarantee in LoopX that treats every long-running agent goal as a lifetime-goal—a persistent entity that must maintain its identity, configuration, and progress state regardless of runtime disruptions. This article examines the three-layered implementation in the huangruiteng/loopx repository, drawing directly from source files and test cases.

---

Goal State Persistence: The File System Anchor

LoopX anchors every goal's lifetime to the file system rather than volatile memory. When a goal is created, the control plane writes a durable state file at .codex/goals/<goal_id>/ACTIVE_GOAL_STATE.md. This file serves as the single source of truth for the goal's identity, configuration, and current progress.

The persistence mechanism ensures recoverability:

• Every turn loads the goal from this file
• Modifications are written back immediately after state changes
• System restarts reload the identical state, enabling seamless continuation

In tests/test_turn_envelope.py (lines 28–34 and 95–101), the test constructs a turn envelope that reads the goal file, mutates the envelope, and writes the updated state back—demonstrating the read-modify-write cycle that preserves goal lifetime across turns.

---

Turn Envelope and Quota Budget: The Validation Gate

Each turn in LoopX is wrapped in a turn envelope (loopx.control_plane.quota.turn_envelope). This envelope carries critical metadata that enforces the lifetime goal invariant before any work proceeds.

The envelope contains:

Field	Purpose
goal_id	Links the turn to its persistent goal state
TURN_ENVELOPE_BUDGET_BYTES	Resource budget allocated for this turn
turn_envelope_action_signature_document	Cryptographic signature for integrity verification
goal_route_hint	Carries invariant flags including preserves_goal_next_action

The goal_route_hint includes the boolean flag preserves_goal_next_action: true, which signals that the next action must remain consistent with the previously stored goal-next-action. This design makes the quota system a gate that refuses to spend a slot unless the goal's lifetime invariant holds.

The envelope construction and verification logic appears in tests/test_turn_envelope.py (lines 11–17, 69–78), showing how the envelope is assembled and validated against stored goal state before execution.

---

Goal-Route Hint and Automation Liveness: Cross-Component Enforcement

The goal-route hint (JSON schema goal_route_hint_v0) propagates the lifetime goal invariant to every downstream component—scheduler, executor, and external tools.

Key fields in the goal-route hint:

• goal_next_action_mutation: Set to "none" when the invariant is satisfied, indicating no unauthorized changes to the goal's next action
• preserves_goal_next_action: Boolean assertion that the goal's next action is preserved across turns

Additionally, the automation_liveness sub-document (schema automation_liveness_v0) includes the keep_active: true flag, which prevents accidental goal termination while work remains. This combination ensures that any component can only progress the goal if the invariant remains intact.

The high-level guarantee is explicitly documented in examples/showcase-frontstage-prototype.py (line 348), which states the system "Preserves the lifetime-goal control plane across turns, tools, agents, gates, evidence, and quota."

---

Practical Implementation: Code Examples

Creating a Turn Envelope with Invariant Enforcement

from loopx.control_plane.quota.turn_envelope import (
    build_turn_envelope, TURN_ENVELOPE_BUDGET_BYTES
)

envelope = build_turn_envelope(
    goal_id="my-long-running-goal",
    budget_bytes=TURN_ENVELOPE_BUDGET_BYTES,
    # The route hint carries the invariant flag

    goal_route_hint={
        "schema_version": "goal_route_hint_v0",
        "preserves_goal_next_action": True,
        "goal_next_action_mutation": "none",
    },
)

# The envelope is signed and later validated before any quota spend

signature = envelope["turn_envelope_action_signature_document"]

Updating Persistent Goal State

from pathlib import Path
import json

goal_state_path = Path(".codex/goals") / "my-long-running-goal" / "ACTIVE_GOAL_STATE.md"

# Load current state

state = json.loads(goal_state_path.read_text())

# Mutate state (e.g., mark a todo as done)

state["selected_todo"]["status"] = "closed"

# Write back – this is the single source of truth for the goal's lifetime

goal_state_path.write_text(json.dumps(state, indent=2))

Scheduler Validation Before Quota Spend

from loopx.control_plane.quota.turn_envelope import (
    quota_action_signature_document, interpret_quota_should_run_packet
)

# Load envelope from previous turn

envelope = ...  # obtained from the turn envelope construction

# Verify that the envelope signature matches the stored goal state

assert quota_action_signature_document(envelope) == interpret_quota_should_run_packet(envelope)

# Only then can the scheduler call `loopx quota spend-slot --goal-id …`

---

Source File Reference

Component	File Path	Role in Lifetime Goal Invariant
Goal state persistence	loopx/control_plane/quota/goal_state.py	Stores and loads ACTIVE_GOAL_STATE.md
Turn envelope builder	loopx/control_plane/quota/turn_envelope.py	Packs envelope with goal_route_hint and signatures
Quota decision logic	loopx/control_plane/effect_program.py (interpret_quota_should_run_packet)	Validates envelope before quota spend
Invariant test coverage	tests/test_turn_envelope.py	Demonstrates turn envelope enforcement
High-level guarantee	examples/showcase-frontstage-prototype.py (line 348)	Documents lifetime-goal preservation

---

Summary

LoopX implements the lifetime goal invariant through three coordinated mechanisms:

• Durable state files anchor goal identity to the file system, surviving crashes and restarts
• Cryptographically signed turn envelopes carry invariant assertions that must validate before any work proceeds
• Quota validation gates refuse resource allocation unless the preserves_goal_next_action flag confirms goal consistency

Together, these layers ensure that goal lifecycle remains idempotent and recoverable: any deviation from the stored goal state fails signature verification, aborts the turn, and preserves the original lifetime-goal.

---

Frequently Asked Questions

What happens if the turn envelope signature validation fails?

The turn is aborted before any quota is spent or work is executed. The signature check in interpret_quota_should_run_packet acts as a gate—mismatch between the envelope signature and stored goal state prevents the scheduler from calling loopx quota spend-slot, preserving the original goal state.

Can external tools modify the goal state directly?

Any direct modification to .codex/goals/<goal_id>/ACTIVE_GOAL_STATE.md without going through the turn envelope will cause subsequent signature validations to fail. The cryptographic signature turn_envelope_action_signature_document binds the envelope to the legitimate goal state, making unauthorized edits detectable.

How does LoopX handle system crashes during goal execution?

On restart, the next turn reloads the same ACTIVE_GOAL_STATE.md file, reconstructs the turn envelope, and re-validates the invariant before scheduling new work. Since state is persisted to the file system after every turn, no progress is lost and the goal continues from its last consistent state.

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