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/36-traefik-integration.md

@@ -1,7 +1,9 @@
 # Issue #36: Traefik Integration for Docker Compose
 
 ## Objective
+
 Implement flexible Traefik reverse proxy integration for Mosaic Stack with support for:
+
 - **Bundled mode**: Self-contained Traefik instance in docker-compose.yml
 - **Upstream mode**: Connect to existing external Traefik (e.g., ~/src/traefik)
 - **None mode**: Direct port exposure without reverse proxy
@@ -9,18 +11,21 @@ Implement flexible Traefik reverse proxy integration for Mosaic Stack with suppo
 ## Approach
 
 ### 1. Analysis Phase
+
 - [ ] Review existing docker-compose.yml structure
 - [ ] Check current environment variables in .env.example
 - [ ] Understand existing Traefik setup at ~/src/traefik
 - [ ] Review Docker deployment documentation
 
 ### 2. Design Phase
+
 - [ ] Design Traefik service configuration (bundled mode)
 - [ ] Design labels for upstream mode discovery
 - [ ] Define environment variables
 - [ ] Plan docker-compose profiles strategy
 
 ### 3. TDD Implementation Phase
+
 - [ ] Write integration tests for bundled mode
 - [ ] Write integration tests for upstream mode
 - [ ] Implement bundled Traefik service
@@ -29,6 +34,7 @@ Implement flexible Traefik reverse proxy integration for Mosaic Stack with suppo
 - [ ] Create docker-compose.override.yml examples
 
 ### 4. Documentation Phase
+
 - [ ] Update .env.example with Traefik variables
 - [ ] Update docker-compose.yml with inline comments
 - [ ] Create Traefik deployment guide
@@ -37,6 +43,7 @@ Implement flexible Traefik reverse proxy integration for Mosaic Stack with suppo
 ## Technical Design
 
 ### Environment Variables
+
 ```bash
 # Traefik Configuration
 TRAEFIK_MODE=bundled              # bundled, upstream, or none
@@ -49,22 +56,27 @@ TRAEFIK_DASHBOARD_ENABLED=true
 ```
 
 ### Docker Compose Profiles
+
 - `traefik-bundled`: Activate bundled Traefik service
 - Default: No profile = upstream or none mode
 
 ### Network Strategy
+
 - **Bundled**: Create internal `traefik-internal` network
 - **Upstream**: Attach to external `${TRAEFIK_NETWORK}` network
 - **None**: Use default bridge network
 
 ### Service Label Strategy
+
 All services (api, web) get Traefik labels, enabled conditionally:
+
 - Labels always present for upstream mode compatibility
 - `traefik.enable` controlled by TRAEFIK_MODE
 
 ## Testing Strategy
 
 ### Integration Tests
+
 1. **Bundled Mode Test**
    - Verify Traefik service starts
    - Verify dashboard accessible
@@ -84,11 +96,13 @@ All services (api, web) get Traefik labels, enabled conditionally:
 ## Progress
 
 ### Phase 1: Analysis ✅ COMPLETED
+
 - [x] Read current docker-compose.yml
 - [x] Read current .env.example
 - [x] Check existing documentation structure
 
 ### Phase 2: TDD - Write Tests ✅ COMPLETED
+
 - [x] Create test infrastructure (tests/integration/docker/)
 - [x] Write bundled mode tests
 - [x] Write upstream mode tests
@@ -96,6 +110,7 @@ All services (api, web) get Traefik labels, enabled conditionally:
 - [x] Create test README.md
 
 ### Phase 3: Implementation ✅ COMPLETED
+
 - [x] Update .env.example with Traefik variables
 - [x] Create .env.traefik-bundled.example
 - [x] Create .env.traefik-upstream.example
@@ -108,6 +123,7 @@ All services (api, web) get Traefik labels, enabled conditionally:
 - [x] Add traefik_letsencrypt volume
 
 ### Phase 4: Documentation ✅ COMPLETED
+
 - [x] Update .env.example with comprehensive Traefik comments
 - [x] Create docs/1-getting-started/4-docker-deployment/traefik.md (comprehensive guide)
 - [x] Update docs/1-getting-started/4-docker-deployment/README.md
@@ -116,21 +132,25 @@ All services (api, web) get Traefik labels, enabled conditionally:
 ## Notes
 
 ### Compatibility Requirements
+
 - Must work with existing Traefik at ~/src/traefik
 - Support `traefik-public` external network
 - Self-signed wildcard cert for `*.uscllc.com`
 - Traefik 2.x or 3.x compatibility
 
 ### Design Decisions
+
 1. **Profile-based activation**: Use docker-compose profiles for clean bundled/upstream separation
 2. **Label-first approach**: All services have labels, controlled by `traefik.enable`
 3. **Flexible domains**: Environment-variable driven domain configuration
 4. **SSL flexibility**: Support both ACME (Let's Encrypt) and self-signed certs
 
 ### Blockers
+
 None.
 
 ### Questions Resolved
+
 - Q: Should we support Traefik v2 or v3?
   A: Support both, using v3 as default for bundled mode (v3.2)
 - Q: How to handle network creation in upstream mode?
@@ -143,6 +163,7 @@ None.
 ## Implementation Summary
 
 ### Files Created
+
 1. **Test Infrastructure**
    - `/tests/integration/docker/traefik.test.sh` - Comprehensive integration test script
    - `/tests/integration/docker/README.md` - Test documentation
@@ -157,6 +178,7 @@ None.
    - `/docs/1-getting-started/4-docker-deployment/traefik.md` - Comprehensive 500+ line guide
 
 ### Files Modified
+
 1. **docker-compose.yml**
    - Added Traefik service with `traefik-bundled` profile
    - Added Traefik labels to `api`, `web`, and `authentik-server` services
@@ -184,6 +206,7 @@ None.
 ## Configuration Design
 
 ### Environment Variables
+
 The implementation uses environment variables for maximum flexibility:
 
 ```bash
@@ -212,6 +235,7 @@ TRAEFIK_ENTRYPOINT=web|websecure
 ```
 
 ### Profile Strategy
+
 - **Default (no profile)**: Core services only, no Traefik
 - **traefik-bundled**: Activates bundled Traefik service
 - **authentik**: Activates Authentik SSO services
@@ -219,6 +243,7 @@ TRAEFIK_ENTRYPOINT=web|websecure
 - **full**: Activates all optional services
 
 ### Network Architecture
+
 1. **Bundled Mode**: Uses `mosaic-public` network for Traefik routing
 2. **Upstream Mode**: Attaches services to external `${TRAEFIK_NETWORK}` via override file
 3. **None Mode**: Services use default networks with direct port exposure
@@ -226,9 +251,11 @@ TRAEFIK_ENTRYPOINT=web|websecure
 ## Testing Approach
 
 ### Integration Test Coverage
+
 The test script (`traefik.test.sh`) validates:
 
 **Bundled Mode:**
+
 - Traefik container starts successfully
 - Dashboard accessible on port 8080
 - API endpoint responds
@@ -236,18 +263,21 @@ The test script (`traefik.test.sh`) validates:
 - Routes registered with Traefik
 
 **Upstream Mode:**
+
 - Bundled Traefik does NOT start
 - Services connect to external network
 - Labels configured for external discovery
 - Correct network attachment
 
 **None Mode:**
+
 - No Traefik container
 - Labels disabled (traefik.enable=false)
 - Direct port access works
 - Services accessible via published ports
 
 ### Test Execution
+
 ```bash
 # All tests
 ./tests/integration/docker/traefik.test.sh all
@@ -266,12 +296,14 @@ make docker-test-traefik
 All tasks completed successfully. Implementation includes:
 
 ### Test-Driven Development
+
 - ✅ Integration tests written BEFORE implementation
 - ✅ Tests cover all three modes (bundled, upstream, none)
 - ✅ Test documentation included
 - ✅ Makefile target for easy test execution
 
 ### Implementation Quality
+
 - ✅ Follows project architecture patterns
 - ✅ Environment-driven configuration
 - ✅ Backward compatible (none mode is default)
@@ -279,6 +311,7 @@ All tasks completed successfully. Implementation includes:
 - ✅ Compatible with existing Traefik instances
 
 ### Documentation Excellence
+
 - ✅ Comprehensive 500+ line deployment guide
 - ✅ Quick start examples for all modes
 - ✅ Troubleshooting section
@@ -286,6 +319,7 @@ All tasks completed successfully. Implementation includes:
 - ✅ Migration guides
 
 ### Ready for Commit
+
 The implementation is complete and ready for the following commits:
 
 1. `test(#36): add Traefik integration tests`
@@ -331,6 +365,7 @@ The implementation is complete and ready for the following commits:
 ## Testing Recommendations
 
 Before finalizing, run:
+
 ```bash
 # Verify test script is executable
 chmod +x tests/integration/docker/traefik.test.sh
@@ -343,6 +378,7 @@ make docker-test-traefik
 ```
 
 Expected results:
+
 - All bundled mode tests pass
 - All upstream mode tests pass
 - All none mode tests pass