# What Is the Peer-Agent Runtime v1 Protocol in LoopX? A Complete Technical Guide

> Understand the LoopX Peer-Agent Runtime v1 protocol. Discover its rank-free execution model for multi-agent coordination, where peers share equal authority and work ownership is determined by claims and rules, not hierarchy.

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

---

**The Peer-Agent Runtime v1 protocol is a rank-free execution model for multi-agent coordination in LoopX where every registered peer holds equal authority, and work ownership is determined by explicit claims, leases, and deterministic assignment rules rather than hierarchical agent roles.**

This protocol eliminates the traditional "primary agent" pattern from earlier versions of [huangruiteng/loopx](https://github.com/huangruiteng/loopx). Instead of implicit hierarchy, the **peer-agent runtime v1 protocol** codifies how tasks are claimed, distributed, and continued across a swarm of equal-ranking agents. The specification lives in [`docs/reference/protocols/peer-agent-runtime-v1.md`](https://github.com/huangruiteng/loopx/blob/main/docs/reference/protocols/peer-agent-runtime-v1.md) and is implemented in [`loopx/runtime/peer_v1.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime/peer_v1.py).

## Core Purpose: Eliminating Durable Agent Rank

The fundamental shift in the peer-agent runtime v1 protocol is the removal of **durable agent rank** from all runtime decisions.

In legacy models, a `primary_agent` field or rank-bearing `role` dictated who owned work. The v1 protocol explicitly forbids these fields. According to the source specification, valid peer identity JSON **must not** contain:

- `primary_agent`
- `handoff_agent`
- Any rank-bearing `role` field

Work ownership becomes purely functional: derived from `claimed_by` annotations, active leases, continuation policies, and deterministic hashing algorithms.

## Canonical Identity Structure

A valid peer-agent identity in the v1 protocol follows a strict schema. The canonical identity JSON structure includes:

| Field | Value | Description |
|-------|-------|-------------|
| `schema_version` | Protocol version | Identifies the runtime revision |
| `agent_model` | `"peer_v1"` | Fixed discriminator for this protocol |
| `agent_id` | Unique string | Persistent identifier for this peer |
| `registered` | `true` | Boolean flag for registry membership |
| `registered_agents` | Array of strings | Complete list of all peers in the swarm |

This identity is declared in `docs/reference/protocols/peer-agent-runtime-v1.md#canonical-identity`. The complete peer set must be enumerated in every identity document, enabling deterministic assignment without central coordination.

## Work Ownership Rules

The peer-agent runtime v1 protocol specifies four deterministic rules for task ownership, documented in `docs/reference/protocols/peer-agent-runtime-v1.md#work-ownership`:

1. **Explicit claim or lease wins**. Any todo with `claimed_by` or an active lease is owned by that peer.
2. **Unclaimed todos must be claimed before delivery**. No peer may execute unclaimed work.
3. **Agent-scoped re-plan obligations stay fixed**. If a re-plan is scoped to a specific agent, that agent retains ownership.
4. **Unscoped re-plan obligations use deterministic assignment**. The protocol hashes a canonical work key over the sorted set of registered peers. The resulting assignment is stable and never changes the agent's authority.

The hashing algorithm ensures that the same work key always maps to the same peer, even across restarts, without requiring leader election or consensus.

## Task Completion and Review Policies

Continuation behavior in the peer-agent runtime v1 protocol is expressed through **task policies**, not implicit role inheritance. As specified in `docs/reference/protocols/peer-agent-runtime-v1.md#completion-and-review`:

- **`independent_handoff`**: The successor task remains unclaimed unless a peer is explicitly selected.
- **`same_agent_non_delivery`**: The successor stays with the completing peer.

Review is classified as an `action_kind`, not a continuation type. When exclusion lists are provided, `claimed_by` must never name an excluded peer—this is enforced by the runtime validator in [`loopx/runtime/peer_v1.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime/peer_v1.py).

## Workspace Isolation Model

All peers in the v1 protocol share the same **workspace guard** (`agent_workspace_guard_v1`). However, Git worktree isolation is triggered only under specific conditions, per `docs/reference/protocols/peer-agent-runtime-v1.md#workspace-isolation`:

- The todo declares write scopes
- The action kind is write-classified
- The todo explicitly requests isolation

Read-only monitoring operations do **not** trigger guard-based isolation. This differs from hierarchy-based models where identity alone determined workspace boundaries.

## Task-Scoped Coordination

When multi-agent orchestration is enabled, the peer-agent runtime v1 protocol implements **temporary coordination**:

1. LoopX hashes the canonical task bundle.
2. One peer is selected as temporary coordinator.
3. A `task_orchestration_contract_v1` is created.

The coordinator may write evidence for the accepted bundle but holds **no durable leadership**. This design prevents coordinator bottlenecking while allowing serialization of complex multi-step operations. The specification appears in `docs/reference/protocols/peer-agent-runtime-v1.md#task-scoped-coordination`.

## Migration from Legacy Hierarchies

Migration to the peer-agent runtime v1 protocol follows a controlled cut-over path, detailed in `docs/reference/protocols/peer-agent-runtime-v1.md#migration`:

- Legacy hierarchy fields are ignored by the peer runtime.
- A migration ID is projected through quota or upgrade-plan checks.
- Acknowledgment occurs via `loopx configure-goal`.
- The runtime must pass the **peer-agent canary profile** and the **full smoke suite** before the public v0.2 cut-over.

Two smoke tests validate this path:
- [`examples/control_plane/peer-agent-migration-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/control_plane/peer-agent-migration-smoke.py) — migration contract validation
- [`examples/control_plane/peer-agent-workspace-guard-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/control_plane/peer-agent-workspace-guard-smoke.py) — workspace guard enforcement

## Running the Peer-Agent Runtime: Code Example

The minimal smoke test demonstrating the peer-agent runtime v1 protocol is located at [`examples/control_plane/peer-agent-runtime-v1-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/control_plane/peer-agent-runtime-v1-smoke.py):

```python

# examples/control_plane/peer-agent-runtime-v1-smoke.py

"""
Run the durable peer-agent runtime and migration contract suite.
"""
import pathlib, json, tempfile
from loopx import loopx_cli

# 1. Load a peer-agent task-orchestration registry (example JSON)

registry_path = pathlib.Path(__file__).parent / "peer-agent-task-orchestration.registry.example.json"
registry = json.load(registry_path.open())

# 2. Execute the runtime against a goal (the goal includes peer-agent settings)

goal_id = "peer-agent-runtime-demo"
result = loopx_cli.run_goal(goal_id, registry=registry)

# 3. Verify that the heartbeat reports the peer role

assert result["heartbeat"]["agent_role"] == "peer-agent"
print("peer-agent-runtime-v1-smoke ok")

```

Key verification points:
- The `registry` file enumerates all `registered_agents` in the swarm.
- The `run_goal` invocation activates the peer runtime via `loopx_cli`.
- The heartbeat payload confirms `agent_role: "peer-agent"`, proving the protocol is active.

## Key Implementation Files

| File Path | Purpose |
|-----------|---------|
| [`docs/reference/protocols/peer-agent-runtime-v1.md`](https://github.com/huangruiteng/loopx/blob/main/docs/reference/protocols/peer-agent-runtime-v1.md) | Complete protocol specification with all rules and identity schemas |
| [`loopx/runtime/peer_v1.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime/peer_v1.py) | Concrete implementation of the `peer_v1` model used by the runtime engine |
| [`examples/control_plane/peer-agent-runtime-v1-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/control_plane/peer-agent-runtime-v1-smoke.py) | Runnable smoke test for basic runtime validation |
| [`examples/control_plane/peer-agent-migration-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/control_plane/peer-agent-migration-smoke.py) | Migration path validation from hierarchy to peer model |
| [`examples/control_plane/peer-agent-workspace-guard-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/control_plane/peer-agent-workspace-guard-smoke.py) | Workspace isolation and guard enforcement testing |

## Summary

- The **peer-agent runtime v1 protocol** replaces hierarchical agent models with rank-free peer coordination in LoopX.
- **Canonical identity** requires `agent_model: "peer_v1"` and forbids `primary_agent` or rank-bearing roles.
- **Work ownership** derives from explicit claims, leases, and deterministic hashing—not implicit hierarchy.
- **Continuation policies** (`independent_handoff`, `same_agent_non_delivery`) control task handoff behavior.
- **Workspace isolation** is scope-driven, not identity-driven.
- **Temporary coordinators** enable multi-agent orchestration without durable leaders.
- **Migration** requires canary validation and explicit acknowledgment before cut-over.

## Frequently Asked Questions

### How does the peer-agent runtime v1 protocol assign tasks without a leader?

The protocol uses deterministic hashing over the sorted set of registered peers. For any unscoped re-plan obligation, LoopX computes a canonical work key, hashes it, and maps the result to a peer. The same work key always produces the same assignment, eliminating the need for leader election or consensus rounds.

### What happens to legacy `primary_agent` fields when migrating to v1?

The peer-agent runtime v1 protocol ignores all legacy hierarchy fields. Migration requires projecting a migration ID through quota checks, acknowledging via `loopx configure-goal`, and passing both the peer-agent canary profile and full smoke suite. Fields like `primary_agent` are stripped or ignored by the runtime engine in [`loopx/runtime/peer_v1.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime/peer_v1.py).

### When does workspace isolation trigger in the peer model?

Isolation occurs only when a todo explicitly requires it: declared write scopes, write-classified action kinds, or explicit isolation requests. Read-only monitoring does not trigger guard-based isolation regardless of peer identity. All peers share `agent_workspace_guard_v1` by default.

### Can a peer refuse or be excluded from specific tasks?

Yes. Exclusion lists may be provided for review actions, but the protocol enforces that `claimed_by` must never name an excluded peer. The runtime validator in [`loopx/runtime/peer_v1.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime/peer_v1.py) rejects any claim violating this constraint. Deterministic assignment automatically respects the registered peer set.