feat(buzz-acp): elect a single leader instance to gate autonomous prompting

[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), and the writer + auto-claim lifecycle (the harness self-elects on launch, fails over on leader death, releases on shutdown). The result is a working headless election: under one shared key, the first instance up leads and every other instance observes, with no UI. The desktop claim/steal UI is a separate stacked PR.

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 (future 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. This needs zero desktop diff — Phase 2 is pure buzz-acp Rust, headlessly testable with two buzz-acp processes.

• 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.

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.

Scope boundaries

• In this PR: NIP-LE spec, read-side leadership, the flock-guarded writer (acquire/release), dead-pid + stale-claim failover, auto-claim-on-launch wired into the harness lifecycle.
• Out of scope (stacked PR): the desktop/Tauri sidebar claim/steal UI and the explicit hard-steal gesture. Phase 2 leaves the steal mechanism reachable but wires no user trigger. queue.push() gating is left untouched so non-leader UI still renders.

What changed

• 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.

Tests

Twenty-one 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) — a non-leader tick claims no agent and never marks in-flight, a companion leader tick claims an idle agent and fires; and a leader/non-leader pair over the dispatch gate (a) — a non-leader promotes nothing queued, a leader promotes one queued event — 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.

Stack: this PR → claim/steal UI (stacked).