feat(desktop): guard the single definition of agent identity

[mfethe1]

Stacks on #6013 (head 7466131). This branch contains #6013's three commits; the last two are this PR's. Take #6013 first — this guard cannot pass without it (proof under Verification).

Reviewable delta only (2 commits, 6 files): 7466131...1e99477

(GitHub's "Files changed" here shows all 19 files because the base must be block/buzz:main — #6013's branch lives on a fork, so this PR cannot be retargeted at it.)

Why

The bug #6013 fixes was a drift, not a typo. Two surfaces answer "which agents exist" — @-mention autocomplete and the Agents library — and each hand-rolled its own key for "same agent?". #5202 moved autocomplete to the pubkey; nobody moved the library, which still grouped by personaId. Renaming an instance then made it disappear from the library entirely.

Nothing failed loudly. No test broke. A card simply stopped existing.

#6013 fixes that by convention — one shared module, src/features/agents/lib/agentIdentity.ts, and everything imports it. Convention doesn't stop it recurring, so this PR encodes the invariant as a check.

What it does

desktop/scripts/check-agent-identity.mjs flags a string or template literal that begins an identity namespace — `pubkey:` or `persona:` — anywhere under desktop/src outside the canonical module. Those two prefixes are the wire formats agentIdentityKey and agentDisplayGroupKey produce, so a literal starting with one is either a second implementation or one edit away from becoming one.

The match captures the namespace plus the first interpolation or word after it (check-agent-identity.mjs:46), not the bare prefix, so a violation report names one key rather than a whole file.

Wired into desktop/package.json's check chain, which is the single place these guards are enumerated — Justfile:118 runs pnpm check and .github/workflows/ci.yml:192 runs just desktop-check, so no CI mirror needs updating.

The allowlist is empty, on purpose

The first version of this guard carried four path:literal exceptions and matched only the bare prefix — so each entry exempted every occurrence of that prefix in the file, and the exempted files were the agent-adjacent ones. That is theatre over exactly the code most likely to drift. Reproduced before fixing: a second, unrelated `persona:${a.personaId}` added to an allowlisted file passed at exit 0.

The fix is not a tighter allowlist but removing the need for one. This is the product-code half of the diff, and it changes runtime string values:

• desktop/src/features/agents/ui/PersonaCatalogDialog.tsx:60 — the dialog's radio-group selection token becomes catalog-persona: via a named constant, replacing four inline "persona:" literals. The token addresses a row in that dialog's own list, is produced and consumed only in that file, and is never persisted or sent over the wire.
• desktop/src/features/profile/ui/UserProfilePanelUtils.ts:104 (profilePanelTargetKey) and desktop/src/features/profile/ui/UserProfilePanel.tsx:222 — the profile panel's render key becomes profile:. That key exists precisely when there is no agent to identify (an uninstantiated persona has no pubkey), so looking like an agent identity was the wrong signal to send.

overrides at check-agent-identity.mjs:67 is now new Set([]), and documented as worth keeping that way.

Deliberately narrow

A guard that cries wolf gets disabled, so this one is scoped to the shape that caused the outage:

• It does not try to catch every possible way of grouping agents.
• Comment lines are skipped. Unrelated subsystems document their own scope keys — observedUnreadStorage.ts:295 and threadActivityStorage.ts:155 describe a "pubkey:normalizedRelayUrl" scope in prose — and flagging prose teaches people to silence the guard rather than read it.
• Scans src/** for .ts/.tsx only, the same rule shape as desktop/scripts/check-pubkey-truncation.mjs:12-16. .test.mjs and desktop/tests/ are therefore out of scope.

Verification

Numbers below are from the head commit 1e99477.

1. Passes on this branch. node desktop/scripts/check-agent-identity.mjs → exit 0, no output.
2. Catches the real regression, not a synthetic one. Restoring the pre-fix(desktop): retain distinct agent instances in autocomplete #5202 `persona:${candidate.personaId}` into agentAutocompleteEligibility.ts → exit 1:

   Desktop agent-identity check failed:
   - src/features/agents/lib/agentAutocompleteEligibility.ts:295: `persona:${candidate.personaId}
   

3. The stack order is a hard dependency. The same script run against main (f956e6f) → exit 1 with 7 violations, including src/features/agents/lib/agentAutocompleteEligibility.ts:297: \pubkey:${normalizePubkey(candidate.pubkey)}` — the line fix(desktop): stop the agents library hiding renamed agent instances #6013 deletes. Merging this before fix(desktop): stop the agents library hiding renamed agent instances #6013 turns CI red.
4. pnpm check exits 0 with all four guards in the chain; desktop unit suite 4978/4978; tsc --noEmit clean; biome clean on the changed files.

check-file-sizes note: UserProfilePanel.tsx sits one line under the 1000-line ceiling, so this PR's change there is net 0 lines (1 added, 1 removed). A redundant comment was dropped to keep it there.

Out of scope

• Desktop only. web/src has no agents feature, and git grep -n "personaId\|persona_id" -- mobile/lib returns nothing, so there is no mirror of this invariant to add and no shared scripts/*-core.mjs to extract.
• No relay, event-kind, migration, or schema change — the diff touches desktop/ exclusively.
• The guard does not govern the new catalog-persona: and profile: namespaces; they are single-file and single-purpose by construction.

[themiguelamador]

I found two blocking issues:

• The guard's path:matchedLiteral allowlist was file-wide in practice. Once a file was allowed for, say, a `persona:` prefix, any future hand-rolled identity key with that prefix in the same file was silently accepted. The four exceptions are adjacent to agent identity code, so this leaves exactly the high-risk files outside the invariant the guard claims to enforce.
• Three commits in the stacked history contain AI Co-Authored-By trailers, which this repository's AGENTS.md explicitly prohibits. Those commits need to be rewritten before merge while retaining the human DCO signoffs.

I fixed both on Complear:review/pr-6077-fix; the tip is e84d14f17. The legitimate catalog-selection and profile-render tokens now use distinct catalog-persona: and profile: namespaces, so the identity guard has no exceptions at all. I also rewrote the fix-branch history to remove the prohibited trailers without changing any commit trees or human signoffs.

Verification:

• node scripts/check-agent-identity.mjs
• node scripts/check-file-sizes.mjs
• focused UserProfilePanelUtils.test.mjs — 10 passed
• tsc --noEmit
• Biome on all five changed files
• pre-commit desktop formatting and file-size hooks
• git diff --check

[mfethe1]

@themiguelamador — your review was filed against dad6a18, which is no longer in this branch's history. Both findings are addressed at head 20e7cff; requesting a re-review or dismissal.

1. The allowlist was file-wide — you were right, and I reproduced it before fixing. Keying on path:matchedLiteral where the literal was only the namespace prefix meant one entry exempted every occurrence of that prefix in the file, and the exempted files were the agent-adjacent ones. Planting a second, unrelated `persona:${a.personaId}|${a.name}` in an allowlisted file passed at exit 0.

Fixed the way you suggested — by removing the need for exceptions rather than tightening them. The two legitimate non-identity uses now carry their own namespaces: catalog-persona: for the persona catalog dialog's selection token (component-internal, never persisted) and profile: for the profile panel's render key (which exists precisely when there is no agent to identify). overrides is now empty. The match also widened from the bare prefix to the prefix plus what follows it, so a future entry would scope to one literal rather than a file.

Both attack cases re-verified after the change: the second key in a formerly-exempt file is now caught, and reintroducing the historical pre-#5202 `persona:${candidate.personaId}` into agentAutocompleteEligibility.ts still fails with the file and line named.

The tip commit also fixes a stale header comment that still advertised "allowlisted below with a reason each" — the first thing a re-reader would have hit.

2. Attribution trailers are removed across this branch's history; every commit carries only human Co-authored-by: / Signed-off-by:. Same good-faith note as on #6036: I couldn't locate that rule in the repo — AGENTS.md:132 covers only the DCO signoff, and main itself carries maintainer commits with agent co-author trailers. Pointer welcome if it lives somewhere I missed.

Ordering note for whoever merges: this PR stacks on #6013 and contains its commits. The guard run against origin/main alone exits 1, because one of the violations it reports is the exact line #6013 deletes. #6013 must merge first or CI goes red.

Not claimed as green: repository CI has never run on this PR — all runs are at action_required. Local pnpm check (all four guards) and the full desktop suite pass; those numbers are author-local.