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/orch-107-valkey.md

@@ -1,13 +1,16 @@
 # Issue ORCH-107: Valkey client and state management
 
 ## Objective
+
 Implement Valkey client and state management system for the orchestrator service using ioredis for:
+
 - Connection management
 - State persistence for tasks and agents
 - Pub/sub for events (agent spawned, completed, failed)
 - Task and agent state machines
 
 ## Acceptance Criteria
+
 - [x] Create scratchpad document
 - [x] `src/valkey/client.ts` with ioredis connection
 - [x] State schema implemented (tasks, agents, queue)
@@ -47,10 +50,11 @@ Implement Valkey client and state management system for the orchestrator service
 ### State Schema Design
 
 **Task State:**
+
 ```typescript
 interface TaskState {
   taskId: string;
-  status: 'pending' | 'assigned' | 'executing' | 'completed' | 'failed';
+  status: "pending" | "assigned" | "executing" | "completed" | "failed";
   agentId?: string;
   context: TaskContext;
   createdAt: string;
@@ -60,10 +64,11 @@ interface TaskState {
 ```
 
 **Agent State:**
+
 ```typescript
 interface AgentState {
   agentId: string;
-  status: 'spawning' | 'running' | 'completed' | 'failed' | 'killed';
+  status: "spawning" | "running" | "completed" | "failed" | "killed";
   taskId: string;
   startedAt?: string;
   completedAt?: string;
@@ -73,20 +78,22 @@ interface AgentState {
 ```
 
 **Event Types:**
+
 ```typescript
 type EventType =
-  | 'agent.spawned'
-  | 'agent.running'
-  | 'agent.completed'
-  | 'agent.failed'
-  | 'agent.killed'
-  | 'task.assigned'
-  | 'task.executing'
-  | 'task.completed'
-  | 'task.failed';
+  | "agent.spawned"
+  | "agent.running"
+  | "agent.completed"
+  | "agent.failed"
+  | "agent.killed"
+  | "task.assigned"
+  | "task.executing"
+  | "task.completed"
+  | "task.failed";
 ```
 
 ### File Structure
+
 ```
 apps/orchestrator/src/valkey/
 ├── valkey.module.ts              # NestJS module (exists, needs update)
@@ -104,21 +111,25 @@ apps/orchestrator/src/valkey/
 ## Progress
 
 ### Phase 1: Types and Interfaces
+
 - [x] Create state.types.ts with TaskState and AgentState
 - [x] Create events.types.ts with event interfaces
 - [x] Create index.ts for type exports
 
 ### Phase 2: Valkey Client (TDD)
+
 - [x] Write ValkeyClient tests (connection, basic ops)
 - [x] Implement ValkeyClient
 - [x] Write state persistence tests
 - [x] Implement state persistence methods
 
 ### Phase 3: Pub/Sub (TDD)
+
 - [x] Write pub/sub tests
 - [x] Implement pub/sub methods
 
 ### Phase 4: NestJS Service (TDD)
+
 - [x] Write ValkeyService tests
 - [x] Implement ValkeyService
 - [x] Update ValkeyModule
@@ -126,6 +137,7 @@ apps/orchestrator/src/valkey/
 - [x] Update .env.example with VALKEY_HOST and VALKEY_PASSWORD
 
 ## Testing
+
 - Using vitest for unit tests
 - Mock ioredis using ioredis-mock or manual mocks
 - Target: ≥85% coverage
@@ -173,6 +185,7 @@ Implementation of ORCH-107 is complete. All acceptance criteria have been met:
 ### Configuration
 
 Added environment variable support:
+
 - `VALKEY_HOST` - Valkey server host (default: localhost)
 - `VALKEY_PORT` - Valkey server port (default: 6379)
 - `VALKEY_PASSWORD` - Optional password for authentication
@@ -190,6 +203,7 @@ Added environment variable support:
 ### Next Steps
 
 This implementation provides the foundation for:
+
 - ORCH-108: BullMQ task queue (uses Valkey for state persistence)
 - ORCH-109: Agent lifecycle management (uses state management)
 - Future orchestrator features that need state persistence
@@ -197,18 +211,22 @@ This implementation provides the foundation for:
 ## Notes
 
 ### Environment Variables
+
 From orchestrator.config.ts:
+
 - VALKEY_HOST (default: localhost)
 - VALKEY_PORT (default: 6379)
 - VALKEY_URL (default: redis://localhost:6379)
 - VALKEY_PASSWORD (optional, from .env.example)
 
 ### Dependencies
+
 - ioredis: Already installed in package.json (^5.9.2)
 - @nestjs/config: Already installed
 - Configuration already set up in src/config/orchestrator.config.ts
 
 ### Key Design Decisions
+
 1. Use ioredis for Valkey client (Redis-compatible)
 2. State keys pattern: `orchestrator:{type}:{id}`
    - Tasks: `orchestrator:task:{taskId}`