Module name_resolution 

The one place a typed agent name is interpreted (identity M3, docs/specs/SPEC_AGENT_IDENTITY_CARRIED_NOT_DERIVED_2026_09_23.md §5).

Callable only from surfaces where a human or a model typed the name — today the POST /agentmux/agents/resolve endpoint the MCP server calls before it enqueues work or schedules a cron job. No internal code path may call this: scripts/check-name-resolver-callers.sh is the CI grep gate that enforces it (§9.3), so §2 rule 1 is mechanical rather than a convention that erodes.

Ambiguity is surfaced, never guessed (§5.2). A name held by two agents is returned as Ambiguous with enough about each candidate for a model to retry by UID and for a human to act on. This is deliberately the opposite of agent_resolve::resolve_agent_id, which collapses “several” into “none” because its callers are internal and have nobody to ask.

What is consulted, in order. (1) A typed value that is a UID. (2) The live registry, by name — every registered block whose display or stable name matches, with its UID when it has one. (3) The store, by slug and by display name (name, instance_name, case-insensitively) over non-template, non-hidden rows — the agents that exist but are not running right now. Live and stored candidates that share a UID are one candidate.

Spec §1.1 measured that a display name never resolves through the exact-case slug tier. That finding is about a resolver that has to pick; this one lists, so it can afford to match display names: a single match resolves, a collision is refused with the candidates, and nothing is ever misrouted.

Structs

AgentCandidate

One agent that a typed name could mean.

Enums

NameResolution

The answer to “which agent did they mean?” (§5.1).

Functions

record 🔒

resolve_name_to_uid 🔒

Resolve typed to a UID, or to the reasons it cannot be resolved.

store_fault 🔒