Agent Identity and Hierarchy — Canonical Reference¶

Version: 1.0 Status: Ratified Author: GO Date: 2026-03-30 Scope: All XIOPro agents

This document reconciles the agent identity model from Parts 1, 4, and 10 into a single canonical reference for identity format, hierarchy, agent types, spawn rules, and lifecycle.

For the full identity specification (role bundles, registry schema, authentication, context rotation, wire format), see SPEC_agent_identity.md.

1. Canonical Identity Format¶

Agent identity follows the pattern Role@Context, where:

Role defines what the agent does (its responsibilities and authority).
Context qualifies where or for whom the agent operates.

Format	Separator	When Used	Examples
`Role`	none	Singleton roles with no qualifier	`GO`
`Role@Host`	`@`	Agents qualified by their host	`HO@MacStudio`, `HO@Server1`
`Role-Project`	`-`	Agents qualified by their project	`PO-MVP1`, `PO-XIOPro`
`Role@Human`	`@`	Agents qualified by the human they serve	`IO@Shai`

The @ separator denotes infrastructure or human binding. The - separator denotes project binding.

2. Four-Layer Hierarchy¶

XIOPro operates as a four-layer orchestration stack above an infrastructure base layer. Each layer has a clear upward escalation path and a clear downward delegation path.

Layer 0: Infrastructure (always on, no agents)
         Bus, PostgreSQL, Caddy, Governor cron, Heartbeat cron, Dashboard

Layer 1: Global Orchestration
         GO — singleton root of the agent hierarchy

Layer 2: Host Orchestration
         HO@Server1, HO@Mac1 — one per physical host

Layer 3: Project Orchestration
         PO-MVP1, PO-XIOPro — one per active project

Layer 4: Interaction Orchestration
         IO@Shai — one per human user

Specialists, Reviewers, and Workers operate beneath Layer 3 (spawned by POs or Specialists) and are not a distinct architectural layer.

3. Agent Types¶

Type	Cardinality	Spawned By	Lifespan	Examples
GO (Global Orchestrator)	Singleton — exactly 1 in the system	Infrastructure (auto-start)	Permanent (lease-renewed)	`GO`
HO (Host Orchestrator)	One per physical host	GO	Host lifetime	`HO@Server1`, `HO@Mac1`
PO (Project Orchestrator)	One per active project	GO	Project lifetime	`PO-MVP1`, `PO-XIOPro`
IO (Interaction Orchestrator)	One per human user	GO	User session lifetime	`IO@Shai`
Specialist	Per domain, within a project	PO	Sprint or task lifetime	`S:backend:a3f9...`
Worker	Ephemeral, per task	Specialist or PO	Task lifetime (minutes to hours)	`W:b2c1...`

Reviewer is a short-lived variant of Specialist, spawned by an orchestrator to evaluate output against a specification. It returns a verdict and terminates.

4. Spawn Rules¶

4.1 Who Spawns Whom¶

GO ──→ HO  (one per host)
GO ──→ PO  (one per project)
GO ──→ IO  (one per human)
PO ──→ Specialist  (per domain need)
PO ──→ Reviewer    (per review need)
PO ──→ Worker      (directly, or via Specialist escalation)
Specialist ──→ (nothing — escalates to PO for Worker spawning)
Worker ──→ (nothing — Workers never spawn agents)

4.2 Maximum Delegation Depth¶

The spawn hierarchy has a hard depth limit of 4 levels:

GO (L1) → PO (L2) → Specialist (L3) → Worker (L4)

No agent at L4 (Worker) may spawn additional agents.
No delegation path may exceed 4 hops from GO.
The Governor enforces this via a spawn depth counter on every spawn request. Any request with depth >= 4 is rejected with a spawn_depth_exceeded error.
Violations are non-recoverable at spawn time — the spawn is rejected, not queued.
Violation triggers a circuit breaker alert to the parent orchestrator.

4.3 Spawn Constraints¶

GO never delegates directly to Workers. The path is always GO -> PO -> Specialist -> Worker.
No cross-layer shortcuts. L3 agents do not talk to L0 infrastructure directly.
All inter-agent communication passes through the Bus. No direct agent-to-agent calls.
IO never executes work. It only mediates between humans and the hierarchy.
Maximum 3 concurrent sub-agents per parent agent.

5. Identity Lifecycle¶

Every agent progresses through five lifecycle states. The Bus owns the authoritative state.

register → active → stale → offline → terminated

State	Description
`register`	Orchestrator has issued the spawn command. Agent is initializing and not yet sending heartbeats.
`active`	Agent is registered, sending heartbeats, and executing work.
`stale`	Agent has missed 1-2 heartbeat windows. Governor is watching but has not yet declared it offline.
`offline`	Agent has missed 3+ heartbeat windows (> 3 minutes). Governor alerts the parent orchestrator.
`terminated`	Agent has cleanly exited (rotation or task completion). Bus state survives for replacement spawning.

5.1 Transitions¶

register ──→ active       (first heartbeat received)
active   ──→ stale        (heartbeat missed for 1 window)
stale    ──→ active       (heartbeat resumes)
stale    ──→ offline      (3+ missed heartbeats)
offline  ──→ terminated   (orchestrator confirms termination)
active   ──→ terminated   (clean rotation or task completion)

5.2 Crash Recovery¶

If an agent reaches offline without a clean rotation:

Heartbeat cron detects missing heartbeat (> 3 minutes).
Governor alerts the parent orchestrator via Bus.
Parent reads the last Bus state for that agent (last known cursor).
Parent spawns a replacement agent with the last known cursor.
Replacement resumes from the last checkpoint.

No file-based handoff. No conversation memory dependency. The Bus is the sole state authority.

6. Cross-Reference to Source Parts¶

Topic	Part 1	Part 4	Part 10	This Document
Identity format	Section 8.1 (3-digit IDs, role properties)	Section 4.1A (surface names)	Section 3 (Role@Host pattern)	Section 1
Hierarchy	orchestrator_id, parent_id fields	GO delegates, PO manages	Section 2 (4-layer stack)	Section 2
Agent types	Key Terms (Section 4A)	Section 4.1A, 5A	Section 2 (full descriptions)	Section 3
Spawn rules	parent_id references	Section 5A.4 (spawning patterns)	Section 11 (design constraints)	Section 4
Lifecycle	status field in schema	Section 5A (spawn/active/rotate/term)	Section 6 (Bus-native rotation)	Section 5

End of SPEC_agent_identity_hierarchy.md