Freeing an agent name requires deleting its history — and the delete is refused for any agent that has ever spoken

[khaliqgant]

Summary

There is no way to free an agent name without destroying the agent's history, so the operator escape hatch fails in exactly the situation that needs it: an agent that has been doing work and now needs its name back.

deleteAgent issues a bare delete:

// packages/engine/src/engine/agent.ts:277
export async function deleteAgent(db: Db, workspaceId: string, name: string) {
  const [agent] = await db
    .select()
    .from(agents)
    .where(and(eq(agents.workspaceId, workspaceId), eq(agents.name, name)));

  if (!agent) return false;

  await db.delete(agents).where(eq(agents.id, agent.id));
  await db.delete(nodes).where(eq(nodes.id, directNodeIdForAgent(agent.id)));
  return true;
}

Four foreign keys to agents.id are declared bare — no onDelete, i.e. RESTRICT:

table / column	packages/engine/src/db/schema.ts
channels.created_by	:455
messages sender	:503
files	:666
webhooks.created_by	:759

Every other FK to agents.id in that file carries an explicit onDelete: 'cascade' or 'set null'. These four do not, so the delete is refused for any agent that has ever created a channel, sent a message, uploaded a file, or created a webhook — which is every agent worth reclaiming a name from.

The failure is server-side, so agent-relay agent remove <name> fails too. There is currently no supported operation that frees a name.

Why this is worth fixing first

This is what turned a two-minute node restart into an unrecoverable name loss on 2026-08-07. A broker whose process is killed uncleanly never deregisters; the record stays behind holding the name; the name cannot be freed; the node has to come back under a different name and every --node <name> reference in the fleet has to be rewritten. With this fixed the same incident is a ten-second recovery.

It is also the only path that recovers an already-stranded name.

Do not fix with cascade

Adding onDelete: 'cascade' to these four would make the delete succeed by deleting every message the agent ever sent, plus the channels it created and the files it uploaded. The history is the point — that is a worse outcome than the current failure, and it is silent.

Proposed fix — tombstone rename

The unique constraint is (workspace_id, name). The name only has to stop colliding; the row does not have to go away.

Rename the row to a tombstone and mark it inactive:

• name → <name>#released-<timestamp> (and handle to match)
• status → inactive/released
• record the release in metadata — note that metadata.release { reason, releasedAt } is already an established shape on live records, so this reuses an existing convention rather than inventing one

Result: the name is immediately free for re-registration, all four FK targets remain valid, every message keeps its sender, and no schema migration is required.

Worth deciding as part of the fix:

• whether this replaces deleteAgent or becomes a sibling releaseAgentName, and what agent-relay agent remove maps to
• whether listing endpoints filter tombstoned rows by default (they should, or agent list fills with #released- entries)
• tombstone name collision if the same name is released twice in the same second

Verification

deleteAgent and the four schema lines read from main at 08ddec7. The FK audit is the complete set of bare .references(() => agents.id) in schema.ts — lines 217, 257, 286, 353, 393, 476, 538, 570, 644, 711, 807, 852, 921, 950 all carry an explicit onDelete; only 455, 503, 666 and 759 do not.

Context

Filed from an incident brief covering the 2026-08-07 node outage. Two companion issues cover the relay side. Do not merge without Khaliq — he owns the merge gate.

[khaliqgant]

Companion issues on the relay side, filed from the same incident:

• Admission gate has no migration path: pre-#1438 records can never reclaim their name relay#1452 — admission gate has no migration path for pre-#1438 records. This issue is its prerequisite: releasing a name is what recovers an already-stranded one, and it is the low-risk alternative to inferring ownership where no proof exists.
• node up spawns AGENT_RELAY_BIN unvalidated, bypassing the broker resolver — 10.x hosts get 'unknown command init' relay#1451 — node up binary resolution, the fault that triggered the outage.

Sequencing: this one and #1451 are independent and unblock recovery and recurrence respectively. #1452 should wait on this.

[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]

The tombstone frees the name but leaves the key in the lock — token_hash must be rotated on release

Implementing this shape in #306 surfaced a gap in the proposal that is worth fixing here, because #309 may land first and whoever writes it needs it.

The row survives, so its credential survives with it

// packages/engine/src/db/schema.ts:64
tokenHash: text('token_hash').notNull().unique(),

A tombstone rename changes name, handle, status and metadata. It does not touch token_hash — and token_hash is what authenticates the agent, not the name. So a "released" agent keeps a working bearer token and can carry on authenticating as its own row: reading its inbox, posting messages, and appearing as a live sender, under a record the operator believes they have retired.

That is a worse property than the current failure. Today deleteAgent refuses and the operator knows the name was not freed. With an unrotated tombstone the operator is told the release succeeded, and the credential is still live.

The column is NOT NULL UNIQUE, so it cannot be cleared. It has to be rotated to a value nobody holds:

tokenHash: await sha256Hex(`released:${agent.id}:${randomHex(16)}`),

The row stays valid, the unique index stays satisfied, and the old token stops resolving.

Everything else in the proposal holds up

The FK audit is correct and I re-verified it independently: 455, 503, 666, 759 are the complete set of bare .references(() => agents.id) in schema.ts. One detail strengthens the "do not fix with cascade" argument further — messages.agent_id is also NOT NULL, so onDelete: 'set null' is not available as a middle path either. Between cascade destroying history and set null being structurally impossible, the tombstone is not the preferred option; it is the only remaining one.

Measured scale on relaycast-cloud, 2026-08-07: 444 agents in a single workspace have sent at least one message, so all 444 are refused by the current delete. This is not an edge case.

One deviation from the proposed name, and the reason is mechanical

#309 proposes <name>#released-<timestamp>. In #306 I keyed it on the agent id instead — <name>#released-<agentId>:

• the release runs inside an atomic write batch, where a UNIQUE(workspace_id, name) violation aborts the whole unit, not just the failing statement. That is exactly the failure mode being fixed, so a tombstone name with any collision risk reintroduces the original bug.
• the agent id is already unique per workspace, so the name cannot collide by construction, and a repeat release of the same row is idempotent rather than an abort.
• releasedAt is preserved in metadata.release as proposed, so no information is lost — it just is not load-bearing for uniqueness.

This also answers the open question at the bottom of the issue about "tombstone name collision if the same name is released twice in the same second": with an id-keyed name it cannot arise.

deleteAgent still has the defect, untouched

#306 fixes only the local reap path (dispatchRelease → completeLocally). deleteAgent (packages/engine/src/engine/agent.ts) still issues the bare delete quoted in this issue and is what agent-relay agent remove reaches, so the operator escape hatch is still broken. That was left deliberately scoped to this issue rather than fixed in two places — two mechanisms for freeing a name is how a codebase ends up with three. Noting it here so it is not rediscovered as a regression.

Whoever implements this: the shape landed in #306 is releasedAgentName() + RELEASED_AGENT_STATUS in engine/agent.ts, and listAgents filters released rows so agent list does not fill with #released- entries (the issue's other open question — it should, and it does).

[khaliqgant]

Correction to my own comment above: the tombstone namespace has to be reserved, or the rename is not collision-free

I argued above that keying the tombstone on the agent id makes it collision-free by construction, because the id is unique per workspace. Review on #306 falsified that, and whoever implements this issue needs the correction more than the original claim.

Agent names are validated as:

// packages/engine/src/routes/agent.ts
const registerAgentSchema = z.object({
  name: z.string().min(1),
  ...

Arbitrary strings. So a caller can register an agent named literally <victim>#released-<victimId> in advance. When the victim is later released, the rename collides on UNIQUE(workspace_id, name) — inside the atomic batch, so it aborts the whole unit, which is the precise failure this issue exists to remove. Not a rare accident: a deliberate denial-of-release against any named agent, and it applies to a timestamped tombstone too (a narrower window, same mechanism).

The id-keyed argument was sound given an assumption about the namespace that nothing in the code enforced.

The fix is to make the namespace actually reserved, not to add entropy or retry:

export const RELEASED_NAME_MARKER = '#released-';

export function assertRegistrableAgentName(name: string): void {
  if (name.includes(RELEASED_NAME_MARKER)) {
    throw codedError(`Agent name "${name}" is reserved: ...`, 'invalid_agent_name', 400);
  }
}

called on every registration path — in #306 that is registerAgent and registerAgentViaNode. Miss one and the guarantee is gone, since either can create the squatting row.

Retry-on-collision was considered and rejected: inside runAtomicWrites a single statement cannot be retried without re-running the batch, and a retry loop wrapped around a credential-rotating write is worse than a namespace rule.

Checked before shipping the rejection: production (relaycast-cloud) has 0 agents whose name contains #released-, so the new validation grandfathers nothing out. Worth re-checking at implementation time if that is much later.

Two consequences for this issue's open questions:

• "tombstone name collision if the same name is released twice in the same second" — with an id-keyed name and a reserved namespace this cannot arise at all, rather than being made unlikely.
• "whether listing endpoints filter tombstoned rows by default" — they must, and note there is more than one such endpoint. fix(engine): restore agent presence lifecycle #306 initially filtered listAgents and missed getPresence, which runs its own query, so a released agent vanished from agent list while still appearing on /v1/agents/presence. Filtering one roster surface and not the other is worse than filtering neither.