Roster and member lifecycle

​

Profiles are templates and members are declared

• the identity roster: the RosterProvider callback on rpc_gateway (Python .roster(provider), TypeScript .rosterProvider(provider)), or the identity_roster top-level meta/init param on meta_gateway (a list of DurableAgentSpec objects, restored at boot and extended at runtime by meta/ensure_member);
• a Rust Discovery implementation on UnifiedRuntimeBuilder (classic, non-identity boot only; neither gateway binary wires one);
• an explicit meta/ensure_member.

import tomllib

from meerkat_meta import DurableAgentSpec

DEFINITION = tomllib.loads(MOB_TOML)  # the text passed to .mob_inline(MOB_TOML)


def orchestrator_profile(definition):
    # `[mob] orchestrator = "lead"` or `[mob.orchestrator] profile = "lead"`
    orchestrator = definition["mob"].get("orchestrator")
    return orchestrator.get("profile") if isinstance(orchestrator, dict) else orchestrator


class ProfileShapedRoster:
    # One durable identity per profile; the orchestrator is addressable.
    async def roster(self, context):
        orchestrator = orchestrator_profile(DEFINITION)
        return [
            DurableAgentSpec(
                identity=f"{profile_name}:main",
                profile=profile_name,
                addressability=(
                    "addressable" if profile_name == orchestrator else "internal_only"
                ),
            )
            for profile_name in DEFINITION.get("profiles", {})
        ]

​

When to call reconcile_edges

• meta/ensure_member already runs that reconcile after every successful ensure, on both the worker plane and the console identity plane. Calling reconcile_edges after ensure_member is redundant.
• meta/reconcile_identity (Python runtime.reconcile()) and the identity-first gateway boot do not: the gateway reconciles definition edges before the roster is materialized. When the definition declares wiring, call reconcile_edges once after boot and after each runtime.reconcile().
• Without declared wiring there is no definition edge policy; the call returns an empty report. Edges from a host TopologyProvider converge on every identity restore and reconcile on their own.
• With a TopologyProvider, the provider (plus operator topology intent) owns the identities’ edges: reconcile unwires every live edge between two identities that neither the provider nor the definition’s wiring declares, including one wired before a restart. Declare an edge in your provider to keep it. Without a provider, reconcile unwires only the edges it wired itself.

​

Roster operations

​

ensure_member gateway profiles

​

Lightweight roster entries

{
  "agent_identity": "agent-1",
  "role": "worker",
  "runtime_mode": "turn_driven",
  "wired_to": ["agent-2", "agent-3"],
  "labels": {"owner": "user-123"},
  "status": "active",
  "state": "active",
  "is_final": false
}

​

Runtime modes

• A fresh autonomous_host member runs one kickoff turn as soon as it is spawned, on its initial_message if the spawn carried one, otherwise on meerkat’s fallback prompt (You have been spawned as '<identity>' (role: <role>) in mob '<mob>'.). The kickoff field on the roster entry reports that turn. Later sends are ordinary durable inputs that queue behind it; nothing is dropped, but the member answers in order.
• Autonomous inbox delivery carries no user-channel work boundary, so meerkat refuses injected context and completion-bearing sends on that path. Meta therefore skips ambient per-turn agent-memory recall for autonomous_host members with the typed reason runtime_mode_autonomous_host (the turn still runs, without memory). Ambient per-turn memory requires runtime_mode = "turn_driven" until meerkat’s carrier change lands; the Unreleased entry in the repository CHANGELOG.md records this.
• turn_driven members run exactly one turn per delivered input and sit idle between inputs. It is the mode meerkat’s tracked, completion-bearing turn carriers support; on autonomous_host those are refused with tracked turn completion is not supported by autonomous inbox delivery.

​

Durable workers

[profiles.worker]
model = "gpt-5.5"
runtime_mode = "turn_driven"
durable = true

• Meerkat spawns the profile’s members with a durable identity, keyed by the member’s identity, so a host can list and re-attach them after a restart. Every identity-first member is already spawned that way, so for an identity the flag changes nothing in how Meta creates, wakes or resets it.
• A durable profile needs a mob whose member sessions outlive the process: a runtime built with persistent_state or a storage provider. On any other mob Meerkat refuses the spawn before anything is created, whether the profile is inline or a realm profile: MobError::NonDurableService, code CAPABILITY_UNAVAILABLE (-32020), data.kind = "mob_non_durable_service" with the member_id and the profile. That includes Meta’s default composition: without persistent_state or a storage provider its member sessions live in memory, so it answers Meerkat’s keeps_durable_member_sessions false.
  • On the identity plane the refusal is a deterministic build refusal. The wake answers HostRejectedBuild with a reason that names the remedy: run the mob on a persistent realm, or drop durable from the profile. Nothing retries it and nothing is recorded; every wake answers it again.
  • On the worker plane, meta/ensure_member answers Meerkat’s own code and data instead of the generic -32602.
• The mobpack editor document carries the flag as the member key durable, present only when true. The export writes durable = true back into the profile, and update_member accepts a boolean durable patch. Validation refuses a member whose durable disagrees with mob.toml (editor_profile_durable_mismatch) or is not a boolean (invalid_durable).

​

Resuming a durable worker’s run

• A run dispatched for an item (its input carries the WorkGraph attention projection) continues only while the item lives in the mob’s realm and is live, unclaimed or claimed by the worker under a lease that has not lapsed, and while its attention binding is active or paused and still targets the worker.
• A run that named no item continues unless a claim the worker holds has lapsed. A worker that holds no claim continues.
• Otherwise the run is superseded. Meerkat settles it the way a stop does: its bound inputs are abandoned as refused resumes, the run ends failed with the check’s reason, and it never resumes. A lapsed lease is committed first, with the WorkGraph’s lease-expiry observation, so the item can be claimed again, and every later attempt of the same resume answers superseded too.
• When the WorkGraph cannot be read, or the run’s attention projection does not decode, the check answers unavailable. Meerkat asks again, up to three attempts, then settles the run the same way.

​

Long-lived members an agent creates

• It survives a restart as a member of its mob. The roster pass retires only the identities the roster materialized, so a member an agent spawned is never retired because no roster lists it. It ends through its own lifecycle: its work’s completion or supersession, an explicit retire, or the idle-retirement policy when the spawn opted in with idle_retire_secs (see Implicit delegate idle retirement). After a restart it is restored like every member of its mob: a member of the root mob is materialized at start only as member_restore says (see SDK and gateway runtime options), and otherwise on its first message or turn.
• Talking to it. A member an agent spawns into its own mob with mob_spawn_member is wired to it by default: Meta sets auto_wire_parent when the agent omits it, so the two talk through comms, before and after a restart. The member tool spawn_member wires the two only when the agent passes auto_wire_parent: true. The host reaches the member by its member id with meta/send_message.
• On a host store realm child mobs are process-bound and do not survive a restart, while members of the realm’s root mob do (see Keeping a Meta realm in your own database). There, an agent spawns its long-lived members into its own mob.
• What it lacks compared with an identity:
  • identity status: meta/status_identity, meta/inspect_identity and the identity bootstrap report do not know it;
  • a Console identity: it is not among the Console’s identities (/console/identities), and the identity-addressed meta/console/send does not reach it (the Console still shows its spawn and its timeline);
  • agent memory, which is identity-scoped: no recall injection and no memory tool;
  • identity delivery: meta/send, meta/interact and meta/dispatch, with their completion baselines, turn tickets and keyed sends, address identities only.

​

Deep member status

​

Member statuses

​

Role migration

"role_migrations": [{"identity": "domain:automation", "from_role": "domain"}]

from meerkat_meta import RoleMigrationDeclaration

builder.role_migrations([
    RoleMigrationDeclaration(identity="domain:automation", from_role="domain"),
])

• When the identity plane has repair custody (no Meerkat identity intent, or an Absent one), Meta retires the member to absence, after proving the session it will resume exists and carrying its queued input, resumes the same session under the declared role, and releases the member again, so its liveness is as before. Meerkat re-verifies the predecessor role, and Meta checks that the member runs the declared role. A member no wake has created a session for yet (seated, never woken) has no session to keep or transcript to lose: the declared move rotates it onto a fresh session under the declared role at the next generation, and its reconcile outcome reads created.
• When the restored member’s role is not the declared from_role, the declaration does not describe it, and Meta refuses before retiring anything.
• When a Present Meerkat identity intent (from mob/adopt_member_identity_declaration) owns the member, the intent pins its profile and MobMachine owns its materialization, so Meta refuses rather than retire it. Declare the new profile in the identity intent.

​

Peer identity and comms names

​

Mutation results

• MobHandle::retire returns Result<(), MobError>.
• MobHandle::respawn returns Result<MemberRespawnReceipt, MobRespawnError>. The receipt identifies the respawned member.

​

SDK projections

from meerkat_meta import (
    MEMBER_STATE_ACTIVE,
    MEMBER_STATE_BROKEN,
    MEMBER_STATE_COMPLETED,
    MEMBER_STATE_RETIRING,
    MEMBER_STATE_UNKNOWN,
)

known_states = {
    MEMBER_STATE_ACTIVE,
    MEMBER_STATE_RETIRING,
    MEMBER_STATE_BROKEN,
    MEMBER_STATE_COMPLETED,
    MEMBER_STATE_UNKNOWN,
}

members = await handle.list_members()
for member in members:
    if member.state not in known_states:
        # A newer gateway may add a status value.
        continue

detail = await handle.member_status("agent-1")
print(detail.status, detail.is_final, detail.error)

await handle.retire_member("agent-1")  # Returns None.

import {
  MEMBER_STATE_ACTIVE,
  MEMBER_STATE_BROKEN,
  MEMBER_STATE_COMPLETED,
  MEMBER_STATE_RETIRING,
  MEMBER_STATE_UNKNOWN,
} from "@rkat/meta-sdk";

const knownStates = new Set<string>([
  MEMBER_STATE_ACTIVE,
  MEMBER_STATE_RETIRING,
  MEMBER_STATE_BROKEN,
  MEMBER_STATE_COMPLETED,
  MEMBER_STATE_UNKNOWN,
]);

const members = await handle.listMembers();
for (const member of members) {
  if (!knownStates.has(member.state)) {
    // A newer gateway may add a status value.
    continue;
  }
}

const detail = await handle.memberStatus("agent-1");
console.log(detail.status, detail.isFinal, detail.error);

await handle.respawnMember("agent-1"); // Returns void.

​

Reconciliation

​

Roster provider context

{
  "context": {
    "mob_definition": { "id": "team", "profiles": { "...": {} } },
    "previous_identities": ["identity:operator", "triage:main"]
  }
}

​

See also

• Identity-first doctrine - choose the identity plane or worker plane
• Python SDK - Python roster helpers
• TypeScript SDK - TypeScript roster helpers
• RPC API - JSON-RPC protocol and method signatures
• Unified runtime guide - reconciliation and session lifecycle