registerOrRotate hands over any agent's identity on a name collision, unverified — while the CLI's register refuses

[khaliqgant]

Summary

The SDK offers four ways to register an agent. On a name collision they do four different things, ranging from a clean refusal to silently handing the caller the incumbent's identity. Callers pick between them by method name, with nothing in the naming to signal that the choice is a security decision.

All four in packages/sdk-typescript/src/relay.ts:

call	on collision	outcome
agents.register	throws agent_already_exists (409)	incumbent untouched — correct
registerAgent({ strict: true }) (:473)	delegates to agents.register	same as above
registerAgent({ strict: false }) (:482)	registerWithLegacySuffix (:448) — retries under name-<suffix>, up to 5 attempts	a second agent under a near-identical name
registerOrRotate (:485)	agents.get(name) then agents.rotateToken(name)	returns the incumbent's id and a fresh token; the incumbent's token is invalidated

// packages/sdk-typescript/src/relay.ts:485
async registerOrRotate(data: RegisterOrRotateInput): Promise<CreateAgentResponse> {
  try {
    return await this.registerAgent({ ...data, strict: true });
  } catch (err) {
    if (isNameConflictError(err)) {
      const agent = await this.agents.get(data.name);
      const { token } = await this.agents.rotateToken(agent.name);
      ...

registerOrRotate verifies nothing. The name string alone is sufficient to take over any agent record in the workspace and evict whoever was using it.

Both of these are the defect relay#1438 was written to remove

relay's v11.4.2 spawn-admission gate closed exactly these two behaviours on the Rust broker's own registration path. Its doc comment (relay crates/broker/src/relaycast/auth.rs:934-947) names them:

formerly split between a strict branch that always reclaimed a name-collision via register_or_get_agent — handing the caller the incumbent's id, name, AND bearer token — and a non-strict branch that silently minted a -{uuid8} sibling name once before failing. Both were the same defect: a spawn-admission gate that doesn't verify who is asking… A silent suffix would have produced a second agent doing duplicate work under a near-identical name — exactly the AR-448 duplicate-agent class this gate exists to stop.

That reasoning was applied to the Rust path. Both behaviours are still live here, unchanged, and the gate does not cover this code.

Reachable surface

registerOrRotate is what relay's MCP register_agent tool calls (relay packages/cli/src/cli/agent-relay-mcp.ts:381, via registerAgentWithRebind). The caller-supplied name is pinned to the session identity only when strict worker identity is on:

// relay packages/cli/src/cli/agent-relay-mcp.ts:346
const effectiveName = strictAgentName && configuredName ? configuredName : name;

With strict worker identity off, or with no configured name, name passes through as given — so an agent calling the MCP tool can register under another agent's name and receive that agent's credentials.

It is also the Rust broker's documented HTTP fallback for worker pre-registration when node-control agent.register is unavailable (relay crates/broker/src/runtime/relaycast_events.rs:493-510, via ws.rs::register_agent_token). That call site already carries a warning in its own doc comment (ws.rs:163-170) that passing an unvalidated name "risks silently disconnecting an unrelated, already-registered agent that happens to share the name" — the hazard is known at the call site but unfixed at the source.

The CLI refuses, and that inconsistency is the point

A probe on 2026-08-07 ran agent-relay agent register <throwaway> twice. The second call returned Agent "…" already exists in this workspace, exited with no token, and left the incumbent untouched.

That is consistent with everything above, and it is worth stating why: the CLI reaches a different method. Both agent register and agent add call plain agents.register:

// relay packages/cli/src/cli/commands/agent.ts:38 (register) and :85 (add)
const registration = await relay.agents.register({ name, type, persona });

So the surface an operator would naturally use to probe this behaviour is the one surface that is safe, while the programmatic surfaces are not. Anyone testing the takeover by hand will conclude the system is fine. That makes the inconsistency worse than a uniformly permissive API would be — it hides itself from exactly the check most likely to be run.

Suggested direction

The specific fix is a judgement call for the owners, but the shape:

• registerOrRotate's reclaim needs the same thing relay#1438 requires: proof the caller is the same work unit, not just the same name. registerAgentViaNode (packages/engine/src/engine/node.ts:1118) already demonstrates a server-enforced version keyed on node identity — that proof cannot be forged by a caller, unlike anything held in caller-writable metadata (see PATCH /v1/agents/:name lets any workspace-key holder write identity_key onto any agent, satisfying relay's admission gate with a planted proof #310).
• registerWithLegacySuffix should be considered for removal outright. It was judged the wrong behaviour on the Rust side for reasons that apply identically here, and a caller that silently gets a differently-named agent than it asked for has no way to notice.
• Whatever is decided, the four methods should not silently differ. If the collision policy is genuinely a caller choice, the method names should say which one is being made.

Verification

SDK, engine and CLI line references read from relaycast main at 08ddec7; relay references from origin/main. The CLI double-register probe was run against a live workspace with a throwaway name. The registerOrRotate takeover was not executed against a live workspace — it would evict a running agent — and is derived from the source above.

Related

• PATCH /v1/agents/:name lets any workspace-key holder write identity_key onto any agent, satisfying relay's admission gate with a planted proof #310 — PATCH /v1/agents/:name lets a workspace-key holder plant the proof relay#1438 reads. More urgent than this one.
• Admission gate has no migration path: pre-#1438 records can never reclaim their name relay#1452 — the gate's missing migration path, and the map of which registration paths it covers. This is "path 3" in that issue.
• Freeing an agent name requires deleting its history — and the delete is refused for any agent that has ever spoken #309 — releasing a name without destroying history.

Context

Filed from an incident investigation on 2026-08-07. Khaliq owns the merge gate — no agent merges.

[khaliqgant]

Provenance note. Source references in this issue were read from main at 08ddec7. The deployed engine is not this checkout — it demonstrably carries code no local tree has: stored status = 'active' serializes as "unknown" through a mapping that exists nowhere in this source (#312). Treat every file:line here as provisional until checked against the deployed build; if you cannot find a reference, suspect a build difference before assuming the reference is wrong.

Measurements taken against the live workspace — record shapes, status counts, staleness ages, and CLI probe results — do not depend on this and stand on their own.

[khaliqgant]

A third path reaches the same outcome, and here is the takeover demonstrated rather than described

This issue and #310 each read as "this one call is unsafe". Working through #306 turned up a third, independent path with the same outcome, which changes the shape of the claim: the missing invariant is at the identity layer, not at three call sites.

The three are genuinely different code:

path	mechanism
#310	PATCH /v1/agents/:name plants metadata.identity_key, then satisfies relay#1438's gate with the caller's own proof
this issue	SDK registerOrRotate catches the 409 and calls agents.get + agents.rotateToken
new	engine registerAgentViaNode — the node-control agent.register frame — reclaims via onConflictDoUpdate with a token_hash overwrite

The takeover, demonstrated

Run against the engine with two enrolled broker nodes. Same workspace, same agent name, nothing but the name presented.

A — incumbent's row stored active: node_alpha registers contested. node_beta sends agent.register for contested.

locationNodeId after: node_alpha     (unchanged)
tokenHash changed:    false

Refused.

B — same row, flipped to offline: identical setup, one column changed first.

reply to node_beta:
{"ok":true,"data":{"agent_id":"2114640403890913
28","name":"contested","token":"at_live_<redacted>"}}

locationNodeId after: node_beta
tokenHash changed:    true
same row id:          true

node_beta is handed a working bearer token for the incumbent's existing row, and the incumbent's token stops resolving. Not a pointer move, not a duplicate record — a credential handover on the same identity, on name alone.

This matters for how the issues here get prioritised: the takeover in this class is now demonstrated, not inferred.

The standing hole this issue owns

While verifying #306 I found the guard's third disjunct is already satisfied for most agents, today, with no deploy:

// packages/engine/src/engine/node.ts — registerAgentViaNode setWhere
and(
  eq(agents.locationType, 'via_node'),
  or(
    eq(agents.locationNodeId, nodeId),
    sql`${agents.locationNodeId} = 'node_direct_' || ${agents.id}`,   // <-- this one
  ),
)

Agents created through the ordinary registerAgent path are given exactly that value at registration:

// packages/engine/src/engine/agent.ts
locationType: 'via_node',
locationNodeId: directNodeId,        // = `node_direct_${agentId}`

So for every such agent the disjunct is true from any node, and the node-identity condition does no work at all. Measured on relaycast-cloud, 2026-08-07 (20,107 agent rows):

• 14,074 rows sit on their implicit direct node and are reclaimable by any node right now
• 1,578 were additionally protected only by the status column

#306 closes the second group by gating reclaim on observed silence (last_seen) instead of status, so a roster read can no longer widen who may claim an identity. It deliberately does not touch the first group — narrowing or removing the node_direct_ disjunct is a design decision that belongs here, alongside registerOrRotate, not smuggled into a presence fix.

That 14,074 is the number I would put on this issue's priority. It is not a latent risk waiting on a deploy; it is the current state.

Note on scope

The engine-side reclaim path is now gated on silence, but it is still name-based reclaim with a token_hash overwrite once the grace window expires — it verifies elapsed time, not who is asking. The verification this issue asks for is still missing on all three paths. #306 removed an accidental trigger; it did not add proof of identity.