feat(agents): editable display label with an immutable slug (ent#181)

[dolho]

Implements trinity-enterprise#181. OSS-core (maintainer decision — an agent's display name is basic UX, not a paid capability).

The problem

An agent has one name: its slug. So "rename" is the heavyweight identity change — PUT /rename stops the container, rewrites agent_name across ~20 tables, clears every per-agent Redis keyspace, renames avatar files, and still leaves the agent's volumes under the old base, because Docker can rename neither a volume nor its immutable trinity.agent-name label. That single operation is the root of #1664 (P0) / #1665 / #1667 / #1669 / #1671.

But "call it Marketing Bot" is the common case, and it should touch none of that.

The fix: render a label, never resolve it

A per-agent display_label that is presentation only. The slug stays the identity every route, container, volume, MCP key and A2A card keys on.

Verified end-to-end on the live stack — this is the property the whole feature turns on:

PUT /api/agents/a2a-demo/label {"label":"Marketing Bot"}
  -> {"label":"Marketing Bot","display_name":"Marketing Bot"}
GET /api/agents          -> a2a-demo carries display_label="Marketing Bot"
container agent-a2a-demo  -> still exists (nothing restarted)
GET /api/agents/a2a-demo -> 200 (the slug still routes)
PUT ... {"label":"   "}  -> label:null, display_name:"a2a-demo"  (blank reverts to the slug)

Shape

• agent_ownership.display_label TEXT, nullable. NULL = "render the slug", so no backfill and every existing agent is unchanged until someone sets one. Dual-track migration per Invariant Feature/vector log retention #3 (SQLite + Alembic 0025, schema.py, tables.py).
• DisplayLabelMixin (Invariant Feature/gemini runtime support #2), with a batched reader for the fleet list so the hottest endpoint stays one query (mirrors get_tags_for_agents), and the four DatabaseManager facade pass-throughs — the fix(volumes): rename-safe volume identity — sweep, purge, create and recovery (#1664, #1665, #1667) #1666 lesson that mocked tests can't see a facade gap.
• GET/PUT /api/agents/{name}/label, owner-only. The read never coerces label to the slug, so the UI can tell "no label" from "label equals slug" and show an empty field. WS agent_label_changed broadcast.
• Frontend — one resolution helper (utils/agentName.js), not per-site label || name (which would show one agent under two names — §1.3.1 FR-3). The header pencil edits the label and keeps the slug visible as secondary text (FR-4); list/tile surfaces render the label with the slug in the tooltip. The store goes through the shared axios client (Invariant security: Fix token logging and add HTML reports to gitignore #7).
• The slug rename is demoted, not removed (FR-5): a separate "Rename the id instead…" affordance with copy that states what it actually does. Owners who need it keep it; it stops being the default gesture.

Requirements §1.3.1 landed before the code. 28 tests.

Notes for review

• Two branch-collision hazards this shares with the merged fix(volumes): rename-safe volume identity — sweep, purge, create and recovery (#1664, #1665, #1667) #1666 and the in-flight A2A feat(a2a): A2A interoperability — inbound server (well-known + JSON-RPC/SSE) + control MCP tools (ent#157/#160) #1628, worth watching at merge time:
  1. Alembic head. This chains 0025 onto dev's current head 0024_volume_base_name. The A2A branch (feat(a2a): A2A interoperability — inbound server (well-known + JSON-RPC/SSE) + control MCP tools (ent#157/#160) #1628) also adds a 0025. Whichever merges second must re-chain to 0026 — same fix I just did on feat(a2a): A2A interoperability — inbound server (well-known + JSON-RPC/SSE) + control MCP tools (ent#157/#160) #1628 when fix(volumes): rename-safe volume identity — sweep, purge, create and recovery (#1664, #1665, #1667) #1666 landed under it. (SQLite's track is a list and unions cleanly; only Postgres branches, which is why pg-migrations is the job that catches it.)
  2. Local DB stamp. Switching between these branches re-stamps the shared local Postgres, so a checkout can leave the backend crash-looping on "Can't locate revision" until you re-stamp to the common ancestor and restart. Not a code issue — a dev-ergonomics one — but I hit it twice today, so flagging it.
• npm run build fails locally on an unrelated pre-existing issue (mermaid declared in package.json, not installed, AgentWorkspace.vue) — reproduces with this branch stashed. My four touched SFCs compile cleanly via @vue/compiler-sfc.

🤖 Generated with Claude Code

[vybe]

Validated via /validate-pr. Requirements §1.3.1 landed before code; dual-track migration complete (SQLite agent_ownership_display_label + Alembic 0025 chained on 0024, schema.py + tables.py); label is rendered-never-resolved with one frontend resolution helper; owner-gated PUT with soft-delete guard; batched fleet read; slug rename demoted with honest copy. Real-DB harness tests pin the invariants (slug never moves, NULL=slug, no name reservation).

Minor follow-ups (non-blocking): (1) tests/registry.json carries a duplicate entry for test_181_agent_display_label.py — dedupe next touch; (2) GET/PUT /api/agents/{name}/label isn't in architecture.md's endpoint table yet; (3) cross-tracker ref — set status-in-dev on trinity-enterprise#181 manually after merge. All checks green.