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

> Discover how LoopX implements the lifetime goal invariant. Learn about its robust persistence, signed turn envelopes, and quota validation for reliable agent goal execution.

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

---

**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](https://github.com/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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

```python
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

```python
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

```python
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/goal_state.py) | Stores and loads [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md) |
| Turn envelope builder | [`loopx/control_plane/quota/turn_envelope.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/turn_envelope.py) | Packs envelope with `goal_route_hint` and signatures |
| Quota decision logic | [`loopx/control_plane/effect_program.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/effect_program.py) (`interpret_quota_should_run_packet`) | Validates envelope before quota spend |
| Invariant test coverage | [`tests/test_turn_envelope.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_turn_envelope.py) | Demonstrates turn envelope enforcement |
| High-level guarantee | [`examples/showcase-frontstage-prototype.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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.