abandon_registration
Abandon an orphaned agent registration when the agent token was lost before first authentication. Use the one-time recovery handle from register_agent to safely delete the never-authenticated row.
Instructions
Self-clean YOUR OWN botched (orphaned) registration when you lost the agent_token before ever authenticating — e.g. a curl/script caller truncated the register response. Authenticated by the one-time registration_recovery handle returned in the register_agent response (NOT the lost token), so it needs no auth token.
When to use: you registered but never captured/used the token, and the row is now an orphan you can't unregister (unregister needs the token you lost). NOT for a live agent that lost its token mid-session — that agent has authenticated, so this is refused; use rotate_token / relay recover instead.
Behavior: verifies the registration_recovery handle (bcrypt, name-scoped, one-time, TTL-bound) and — ONLY if the target row has NEVER authenticated (the keystone) — deletes it, bumps the auth generation, and fires an agent.unregistered webhook. The keystone is re-asserted inside the DELETE, so it can never reach a working agent (a row that authenticates between check and delete is left intact) — the safe, self-serve alternative to the operator kill endpoint. Orphans are also auto-GC'd after ~30min (never-authed + session-less + older than the orphan TTL) as a backstop.
Returns: { success, name, abandoned }. Errors (AUTH_FAILED): agent has authenticated (not an orphan), invalid/expired handle, or no such registration.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The agent name whose orphaned registration to abandon. | |
| recovery_handle | Yes | The one-time registration-recovery handle returned in the register_agent response (the `registration_recovery` field). Name-scoped + short-lived. |