feat: elect a single leader instance and surface it in the desktop UI

[wpfleger96]

Summary

When multiple Buzz dev instances share an agent keypair, the relay fans every matching event out to all of them (NIP-01) and each instance prompts its agent — duplicate replies for a single @mention. This adds a per-agent-key leader lock so only the leader instance acts autonomously on the wire. Non-leaders still receive and render events (the queue stays ungated for UI) but suppress every path that would emit under the shared identity.

This PR carries the NIP-LE specification (docs/nips/NIP-LE.md), the read side (every instance derives leadership from the lock file), the writer + auto-claim lifecycle (the harness self-elects on launch, fails over on leader death, releases on shutdown), and the desktop leadership UI (a per-agent leader badge plus a cooperative "Make leader" steal control).

The invariant

A single agent identity may have N subscribed instances but exactly one prompter (the leader). Non-leaders suppress all three surfaces that would otherwise act under the shared key:

• (a) the prompt/dispatch path — non-leaders promote nothing queued to a prompt.
• (b) the pre-dispatch 👀 reaction — fires at queue-acceptance time, before dispatch, so the dispatch gate alone would let every sharing instance emit a redundant 👀.
• (c) the autonomous heartbeat prompt path — the periodic self-prompt that, when enabled, has the agent buzz messages send / buzz workflows approve on its own; non-leaders must not fire it, or N instances each act for the same key.

Each surface maps 1:1 to a gate in the code. docs/nips/NIP-LE.md is the normative spec for this invariant and the lock contract.

How leadership is decided (read side)

Every instance reads ~/.buzz/leader-locks/<pubkey-hex>.lock and resolves:

• absent lock → leader (solo dev is unaffected — no lock, no suppression)
• present + instance_id matches this process's election id → leader
• present + foreign instance_id → observer
• no election id → leader (solo CLI with the env unset)
• unreadable or malformed → fail safe to leader: any IO error (permission, mid-write truncation) or parse failure resolves to leader, so a corrupt lock never silences the only responder

Status is cached per agent key and refreshed in place by refresh(). Leadership is read-derived, never acquire-derived: is_leader independently reads the file, so an acquire that fails open on an IO error can never force a process to lead next to a live foreign leader.

How a leader is elected (writer + auto-claim)

The harness self-mints a process-unique election id ({pid}-{nanos}) when BUZZ_INSTANCE_ELECTION_ID is unset, and honors the env verbatim if set (desktop per-spawn injection). The same id is both written into the lock and used by the read check, so a process's writes match its own reads.

• Startup — acquire(agent_pubkey): take an exclusive flock, then read-decide-write under the held lock so the read→decide→write TOCTOU window is closed. The lock is takeable iff free (absent / empty / malformed), already ours, the owner's pid is dead (kill(pid, None) → ESRCH), or the owner's claimed_at is stale (older than STALE_CLAIM = 10s = 2× the refresh). On success it writes {instance_id, pid, claimed_at}; a live, fresh foreign owner → observe.
• Failover — no new timer. The existing 5s leader_refresh tick calls acquire before refresh, so a leader re-stamps its own claimed_at every tick (its claim is always fresher than the bound), and a survivor re-reads a dead-or-stale lock and takes over within 5s.
• Shutdown — release empties the lock file (never unlinks → no detached-inode race) only if we still own it, so a co-located sibling takes over immediately and a successor's claim is never stomped.

Dead-pid vs recycled-pid. The ESRCH fast path catches the common crash-without-release case instantly. The claimed_at staleness arm is the backstop for the rarer case where the OS recycles the crashed leader's pid onto an unrelated live process before any survivor ticks: the recycled pid reads as alive, but with no live leader re-stamping the claim it ages past the bound and becomes takeable — closing what would otherwise be a permanent leaderless wedge. The only owner the staleness arm can evict is a live-pid process that has missed two consecutive refresh ticks, which requires a full-runtime stall (turns run on a spawned pool, so a normal heavy turn never blocks the refresh) — in which state the leader is non-functional and takeover is correct, self-healing to a transient duplicate at worst.

Desktop leadership UI

The desktop is the owner/controller, not a contending instance. leadership_status frames already land in eventsByAgent via the owner-wide observer subscription, so the UI is a cached derivation — no new store, no new subscription, no relay change.

• Leader badge in ManagedAgentRow beside the status — shows when an agent has a live leader instance. Hidden when no live instance reports.
• Leadership submenu in the row's ... dropdown — lists each live instance (truncated instanceId, last-seen, leader marker) with a per-instance "Make leader" action. The current leader's item is disabled. Hidden when <= 1 live instance, so the solo-dev UX is byte-unchanged.
• leadershipByAgent is a cached Map rebuilt only when a leadership_status frame appends, mirroring transcriptByAgent. getAgentLeadership stays a stable map lookup so it satisfies the useSyncExternalStore referential-stability contract (a fresh array per getSnapshot would render-storm).
• parseLeadershipPayload narrows the untrusted unknown payload at the boundary; malformed frames are dropped. lastSeen = Date.parse(event.timestamp) with NaN → drop.
• Staleness lives in the component, not the store — the store stays time-independent. The row filters against a useNow(5000) clock at a 15s threshold (3 missed 5s ticks), so a crashed leader's badge ages out without a new frame arriving.
• Freshest-leader rule: the badge reflects max(lastSeen) among instances reporting isLeader, dissolving the <= 15s transient two-leader window after a crash without a "contested" state.
• Non-authoritative ack: claimManagedAgentLeadership mirrors cancelManagedAgentTurn and returns { status: "sent" }. The UI never optimistically flips — it converges off the leadership_status stream.

Portability

The writer is #[cfg(unix)] (flock is Unix); #[cfg(not(unix))] is an always-leader no-op acquire/release, mirroring the existing kill_process_group cfg pattern. Desktop targets macOS/Linux; Windows is not a leader-election target. The flock feature is added to the existing cfg(unix) nix dependency; claimed_at parsing reuses the already-present chrono workspace dep (Cargo.lock unchanged).

Election identity

The lock keys on a per-process election identity behind a single named constant (ELECTION_ID_ENV = BUZZ_INSTANCE_ELECTION_ID). It is deliberately not the Tauri bundle identifier (BUZZ_MANAGED_AGENT): the bundle id collides across same-class windows (DMG + dev share xyz.block.buzz.app(.dev); a worktree falls back to the shared dev id if swift generate-dev-icon fails), which would let two windows both match the lock and both lead. Reaper identity partitions by app-class; election identity must be unique per process.

What changed

Harness (buzz-acp):

• docs/nips/NIP-LE.md (new) — the NIP-LE spec: the exactly-one-prompter invariant (surfaces a/b/c), the local-filesystem lock contract, claim semantics (auto-on-launch acquire-if-unowned plus explicit re-claim), the flock TOCTOU guard, and dead-pid + stale-claim failover.
• crates/buzz-acp/src/leader.rs — the LeaderCheck trait and FileLeaderCheck: the read side (above), plus the writer half — acquire/release, lock_is_takeable (ours || dead-pid || stale), pid_is_alive (ESRCH-only-dead; EPERM → alive so a live leader is never stolen from), claim_is_stale, and from_env_or_mint (honor env if set, else mint {pid}-{nanos}).
• crates/buzz-acp/src/pool.rs — PromptContext carries leader: Arc<dyn LeaderCheck>.
• crates/buzz-acp/src/lib.rs — constructs from_env_or_mint; auto-acquire on startup; re-acquire before refresh in the 5s leader_refresh tick; release first in shutdown teardown; gates (a) dispatch_pending, (b) the queue-push 👀 reaction_add, (c) dispatch_heartbeat; emits the leadership_status observer frame consumed by the desktop UI.

Desktop:

• leadershipHelpers.ts (new) — pure derivation: parseLeadershipPayload, buildLeadership, filterStaleInstances, selectFreshestLeader.
• leadershipHelpers.test.mjs (new) — 17 behavior tests.
• observerRelayStore.ts — leadershipByAgent cached map, rebuild-on-append, getAgentLeadership selector.
• agentControl.ts — claimManagedAgentLeadership sender.
• useObserverEvents.ts — useAgentLeadership hook.
• agentUi.ts — truncateInstanceId.
• ManagedAgentRow.tsx — leader badge + leadership submenu.
• e2eBridge.ts + observerRelayStore.ts — test-only __BUZZ_E2E_SEED_LEADERSHIP__ hook routing synthetic leadership_status frames through the real cached-map rebuild path (production ingest untouched).
• leadership-screenshots.spec.ts (new) + playwright.config.ts — E2E screenshot spec, 4 scenarios in the smoke project.

Tests

Harness — twenty-one buzz-acp unit tests, all behavior-focused.

• Reader (6): absent → leader, self-owned → leader, foreign-owned → observer, malformed → fail-safe leader, no-election-id → leader even with a foreign lock, and refresh flips status when the lock changes. Ids are opaque per-window strings (window-a/window-b) so the suite can't enshrine bundle-id == election-id.
• Writer (11): unowned-acquire writes self, creates the lock dir when absent, two-writer race yields exactly one winner, dead-pid lock is taken over, live+fresh foreign lock blocks acquire, recycled-pid-with-stale-claim is taken over (the failover-stall reproduction — fails without the staleness arm), reacquire-own is idempotent, release frees the lock for another writer, release does not stomp a successor, no-election-id acquire is a no-op (always leader), and an 8-thread barrier-synced concurrent acquire yields exactly one winner (proving flock serialization, not just the happy path).
• Gates (4): a leader/non-leader pair over the heartbeat gate (c) and a leader/non-leader pair over the dispatch gate (a) — proving each negative test exercises its gate, not a dead path.

cargo test -p buzz-acp → 330 passed. cargo fmt --check / cargo clippy --all-targets clean.

Desktop: 17 behavior tests over the pure leadership derivation (guard drops, latest-per-instance, NaN-timestamp drop, zombie prune, stale boundary, NaN-stale, freshest-among-multiple-leaders, the two-leader transient). The store-level referential-stability contract is verified at review (the store imports Tauri bindings that fail under node). pnpm typecheck / pnpm check clean; pnpm test 760/760. The leadership E2E screenshot spec passes 4/4 in the smoke project.

[wpfleger96]

Phase 3b — Leadership UI E2E screenshots

Captured via leadership-screenshots.spec.ts (smoke project), driving the real cached-map consumer through the __BUZZ_E2E_SEED_LEADERSHIP__ seed hook — synthetic leadership_status frames routed through the production appendAgentEvent rebuild path, not a stub.

Single-instance Leader badge

One instance reporting isLeader: true — the row shows the crown "Leader" badge with no Leadership submenu (≤1 instance, nothing to steal).

Multi-instance freshest-leader badge

Three instances, one leader — the row badge reflects the freshest leader (max(lastSeen) among isLeader: true).

Leadership submenu

The ... dropdown's Leadership submenu listing each instance: truncated instanceId + last-seen + leader marker, with the current leader's item disabled.

"Make leader" cooperative-steal action

The submenu open with a non-leader instance's "Make leader" entry hovered — the cooperative-steal entry point.