feat(sdk): usePluginEvent — one shell SSE connection for all plugins (WS3 A1)

[markhayden]

What & why

Part of the 2026-06 audit remediation (WS3, feat/sdk-gaps). This PR ships A1 only — the load-bearing SSE consolidation — so the highest-risk change (it touches the live-update path app-wide) gets reviewed in isolation. A2–A8 (the additive SDK primitives: useJsonFetch, ConfirmDialog, formatters, EmptyState fold, useAvailableModels, tasks workflow types, toneBadge) are carved into a follow-up workstream WS3b and picked up after this merges. See tasks/plan.md for the full backlog.

The problem (audit finding, P1)

The shell already owns exactly one EventSource('/api/events') (src/hooks/use-sse.ts), but it had no subscriber fan-out — its routing was hardcoded to specific plugins (data.type==='taskboard' → bumpTaskboard, doctor → bumpDoctor, reindex → setReindexProgress), with those counters living in the host content store. The assets plugin got no such carve-out, so it opened its own 3 raw EventSource connections (one per mounted component, no reconnect). External plugin authors had no sanctioned way to react to their own broadcast() events.

What changed

New primitive — usePluginEvent (src/hooks/use-plugin-event.ts, re-exported from @makinbakin/sdk/hooks):

• A dependency-free globalThis-backed Map<eventName, Set<handler>> emitter. emitPluginEvent(payload) dispatches to subscribers of payload.event; a throwing handler is isolated so one bad subscriber can't break the others.
• usePluginEvent(event, handler) is stable across handler-identity changes (latest handler held in a ref; only re-subscribes when event changes — no memoization needed by callers).
• The shell's single useSSE.onmessage is the sole publisher: {type:'plugin-event'} frames pass through verbatim; the shell also synthesizes taskboard, doctor.run, and reindex.start|progress|complete from their raw frames.

Migrations:

• Assets: 3 raw EventSources → usePluginEvent (task-assets, VersionedAssetGrid, VersionedAssetDetail). Net: assets goes 3 → 0 connections.
• Counter refactor (the bigger blast radius, requested explicitly): tasks board + nav badge, health nav badge, and the health reindex tiles now subscribe via usePluginEvent; the content store sheds taskboardVersion/doctorVersion/reindexProgress entirely. The store is back to file/audit/activity/heartbeat state only — it no longer knows which plugin cares about which event.

Verification

• bun run test — 4999 pass / 0 fail (new use-plugin-event unit tests; rewritten use-sse-doctor + use-health-summary; obsolete content-store counter test deleted).
• bun run typecheck + lint (touched files) — clean.
• Dockerized-rig isolated E2E (real OpenClaw, all 12 plugins loaded):
  • Playwright sweep of all 10 routes → 0 console/page/network errors.
  • Stack-classified EventSource probe on /assets: assets plugin = 0 /api/events connections (was 3), shell singleton = 1. (The one remaining connection is the out-of-repo messaging user plugin in the test home — not repo scope.)

Docs

.claude/knowledge/plugin-system.md (new § Client SSE fan-out + SDK hooks surface + nav-badge bullets), search-system.md, tasks-plugin.md updated to the new wiring.

Risk / rollback

The emitter is additive (publish-only); the shell keeps its existing content-store routing for everything else. Each commit is independent and green. Merge-order note: independent of WS2 #499 (only shared file packages/sdk/src/utils takes non-conflicting additions).

🤖 Generated with Claude Code