refactor(frontend/ws): unify three WebSocket managers (useWebSocket + useGlobalWebSocket + useLiveEvents) into single useEventBus #6488

Discovery

The frontend has three independent WebSocket subsystems with identical state-enum values defined twice and 14 callers split across patterns. Each wires to a different backend bus, so collapsing them is partially blocked on #6486 (backend event-bus unification).

State enum collision (pure duplication)

Both define exactly: 'disconnected' | 'connecting' | 'connected' | 'error'.

Backend coupling

Today the frontend's split mirrors the backend's split: /api/ws → EventManager, /api/ws/live → LiveEventManager. Once #6486 unifies the backend buses, the frontend can collapse to one transport.

Proposed Solution

Single composable useEventBus() built on GlobalWebSocketService with channel-scoped subscriptions folded in.

export function useEventBus() {
  return {
    subscribe(channel: string, handler: EventCallback): Unsubscribe,
    unsubscribe(channel: string, handler: EventCallback): void,
    isConnected: ComputedRef<boolean>,
    connectionState: ComputedRef<ConnectionState>,
  }
}

Channel format unchanged from useLiveEvents: 'global', 'agent:{id}', 'task:{id}', 'workflow:{id}'.

Caller migration (14 total)

Steps

1. Coordinate with refactor(events): unify three parallel event-bus systems (EventManager + LiveEventManager + RedisEventStreamManager) #6486 — wait for backend bus facade or design unified /api/ws endpoint together
2. Unify state enum — export single ConnectionState from GlobalWebSocketService, delete LiveEventConnectionState
3. Add channel-scoped subscriptions to GlobalWebSocketService — fold LiveEventService channel logic in
4. Create useEventBus() composable — thin wrapper, supports both 'global' and 'agent:X' syntax
5. Migrate 14 callers in 3 batches (per-call → global → live-events)
6. Mark deprecated: useWebSocket, useLiveEvents keep working for one release with deprecation warnings
7. Delete after grep = 0

Acceptance Criteria

• Single ConnectionState type exported; LiveEventConnectionState removed
• useEventBus() composable created and supports channels: 'global', 'agent:{id}', 'task:{id}', 'workflow:{id}'
• All 14 callers migrated; git grep "useWebSocket\\|useLiveEvents" returns 0 in non-shim code
• Reconnect behavior preserved — exponential backoff + backend-wait mode kept from GlobalWebSocketService
• Channel isolation verified — events from agent:123 do NOT leak to agent:456 subscribers (integration test)
• Backend restart recovery — frontend reconnects automatically within 10s
• Event payload shape unchanged — { type, payload } structure preserved for backward compat
• Deprecation warnings emit during test suite run for any remaining old-API imports

Risks

• Components may switch on specific enum values — grep for hardcoded 'connecting'/'error' literals before merge
• Reconnect storms during migration — feature-flag the new bus and migrate callers behind it
• Hidden state-machine logic in components (e.g., Terminal.vue) — audit each caller for assumptions

Files Affected

• Modified: services/GlobalWebSocketService.ts (add channel routing)
• New: composables/useEventBus.ts
• Deleted (after sunset): composables/useWebSocket.ts, composables/useLiveEvents.ts, services/LiveEventService.ts
• Modified: 14 caller files

Related / Dependencies

• Blocked-by partial: refactor(events): unify three parallel event-bus systems (EventManager + LiveEventManager + RedisEventStreamManager) #6486 (unify backend event buses) — frontend can keep two endpoints temporarily but full collapse needs backend single bus
• Memory: documented LiveEventConnectionState and ConnectionState enum duplication