feat(#93): implement agent spawn via federation

Implements FED-010: Agent Spawn via Federation feature that enables
spawning and managing Claude agents on remote federated Mosaic Stack
instances via COMMAND message type.

Features:
- Federation agent command types (spawn, status, kill)
- FederationAgentService for handling agent operations
- Integration with orchestrator's agent spawner/lifecycle services
- API endpoints for spawning, querying status, and killing agents
- Full command routing through federation COMMAND infrastructure
- Comprehensive test coverage (12/12 tests passing)

Architecture:
- Hub → Spoke: Spawn agents on remote instances
- Command flow: FederationController → FederationAgentService →
  CommandService → Remote Orchestrator
- Response handling: Remote orchestrator returns agent status/results
- Security: Connection validation, signature verification

Files created:
- apps/api/src/federation/types/federation-agent.types.ts
- apps/api/src/federation/federation-agent.service.ts
- apps/api/src/federation/federation-agent.service.spec.ts

Files modified:
- apps/api/src/federation/command.service.ts (agent command routing)
- apps/api/src/federation/federation.controller.ts (agent endpoints)
- apps/api/src/federation/federation.module.ts (service registration)
- apps/orchestrator/src/api/agents/agents.controller.ts (status endpoint)
- apps/orchestrator/src/api/agents/agents.module.ts (lifecycle integration)

Testing:
- 12/12 tests passing for FederationAgentService
- All command service tests passing
- TypeScript compilation successful
- Linting passed

Refs #93

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

docs/scratchpads/198-strengthen-websocket-auth.md

@@ -1,9 +1,11 @@
 # Issue #198: Strengthen WebSocket Authentication
 
 ## Objective
+
 Strengthen WebSocket authentication to prevent unauthorized access by implementing proper token validation, connection timeouts, rate limiting, and workspace access verification.
 
 ## Security Concerns
+
 - Unauthorized access to real-time updates
 - Missing authentication on WebSocket connections
 - No rate limiting allowing potential DoS
@@ -11,6 +13,7 @@ Strengthen WebSocket authentication to prevent unauthorized access by implementi
 - Missing connection timeouts for unauthenticated sessions
 
 ## Approach
+
 1. Investigate current WebSocket/SSE implementation in apps/api/src/herald/
 2. Write comprehensive authentication tests (TDD approach)
 3. Implement authentication middleware:
@@ -22,6 +25,7 @@ Strengthen WebSocket authentication to prevent unauthorized access by implementi
 5. Document security improvements
 
 ## Progress
+
 - [x] Create scratchpad
 - [x] Investigate current implementation
 - [x] Write failing authentication tests (RED)
@@ -34,12 +38,14 @@ Strengthen WebSocket authentication to prevent unauthorized access by implementi
 - [ ] Commit changes
 
 ## Testing
+
 - Unit tests for authentication middleware ✅
 - Integration tests for connection flow ✅
 - Workspace access validation tests ✅
 - Coverage verification: **85.95%** (exceeds 85% requirement) ✅
 
 **Test Results:**
+
 - 33 tests passing
 - All authentication scenarios covered:
   - Valid token authentication
@@ -55,6 +61,7 @@ Strengthen WebSocket authentication to prevent unauthorized access by implementi
 ### Investigation Findings
 
 **Current Implementation Analysis:**
+
 1. **WebSocket Gateway** (`apps/api/src/websocket/websocket.gateway.ts`)
    - Uses Socket.IO with NestJS WebSocket decorators
    - `handleConnection()` checks for `userId` and `workspaceId` in `socket.data`
@@ -77,6 +84,7 @@ Strengthen WebSocket authentication to prevent unauthorized access by implementi
    - Pattern can be adapted for WebSocket middleware
 
 **Security Issues Identified:**
+
 1. No authentication middleware on Socket.IO connections
 2. Clients can connect without providing tokens
 3. `socket.data` is not validated or populated from tokens
@@ -86,6 +94,7 @@ Strengthen WebSocket authentication to prevent unauthorized access by implementi
 7. Clients can join any workspace room without verification
 
 **Implementation Plan:**
+
 1. ✅ Create Socket.IO authentication middleware
 2. ✅ Extract and validate Bearer token from handshake
 3. ✅ Populate `socket.data.userId` and `socket.data.workspaceId` from validated session
@@ -136,6 +145,7 @@ Strengthen WebSocket authentication to prevent unauthorized access by implementi
 ### Rate Limiting Note
 
 Rate limiting was not implemented in this iteration because:
+
 - It requires Redis/Valkey infrastructure setup
 - Socket.IO connections are already protected by token authentication
 - Can be added as a future enhancement when needed
@@ -144,6 +154,7 @@ Rate limiting was not implemented in this iteration because:
 ### Security Review
 
 **Before:**
+
 - No authentication on WebSocket connections
 - Clients could connect without tokens
 - No workspace access validation
@@ -151,6 +162,7 @@ Rate limiting was not implemented in this iteration because:
 - High risk of unauthorized access
 
 **After:**
+
 - Strong authentication required
 - Token verification on every connection
 - Workspace membership validated
@@ -158,6 +170,7 @@ Rate limiting was not implemented in this iteration because:
 - Low risk - properly secured
 
 **Threat Model:**
+
 1. ❌ Anonymous connections → ✅ Blocked by token requirement
 2. ❌ Invalid tokens → ✅ Blocked by session verification
 3. ❌ Cross-workspace access → ✅ Blocked by membership validation