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/design/knowledge-module-issues.md

@@ -27,6 +27,7 @@ Build a native knowledge management module for Mosaic Stack with wiki-style link
 Create Prisma schema and migrations for the Knowledge module.
 
 **Acceptance Criteria:**
+
 - [ ] `KnowledgeEntry` model with all fields
 - [ ] `KnowledgeEntryVersion` model for history
 - [ ] `KnowledgeLink` model for wiki-links
@@ -37,6 +38,7 @@ Create Prisma schema and migrations for the Knowledge module.
 - [ ] Seed data for testing
 
 **Technical Notes:**
+
 - Reference design doc for full schema
 - Ensure `@@unique([workspaceId, slug])` constraint
 - Add `search_vector` column for full-text search
@@ -54,6 +56,7 @@ Create Prisma schema and migrations for the Knowledge module.
 Implement RESTful API for knowledge entry management.
 
 **Acceptance Criteria:**
+
 - [ ] `POST /api/knowledge/entries` - Create entry
 - [ ] `GET /api/knowledge/entries` - List entries (paginated, filterable)
 - [ ] `GET /api/knowledge/entries/:slug` - Get single entry
@@ -64,6 +67,7 @@ Implement RESTful API for knowledge entry management.
 - [ ] OpenAPI/Swagger documentation
 
 **Technical Notes:**
+
 - Follow existing Mosaic API patterns
 - Use `@WorkspaceGuard()` for tenant isolation
 - Slug generation from title with collision handling
@@ -80,6 +84,7 @@ Implement RESTful API for knowledge entry management.
 Implement tag CRUD and entry-tag associations.
 
 **Acceptance Criteria:**
+
 - [ ] `GET /api/knowledge/tags` - List workspace tags
 - [ ] `POST /api/knowledge/tags` - Create tag
 - [ ] `PUT /api/knowledge/tags/:slug` - Update tag
@@ -100,6 +105,7 @@ Implement tag CRUD and entry-tag associations.
 Render markdown content to HTML with caching.
 
 **Acceptance Criteria:**
+
 - [ ] Markdown-to-HTML conversion on entry save
 - [ ] Support GFM (tables, task lists, strikethrough)
 - [ ] Code syntax highlighting (highlight.js or Shiki)
@@ -108,6 +114,7 @@ Render markdown content to HTML with caching.
 - [ ] Invalidate cache on content update
 
 **Technical Notes:**
+
 - Use `marked` or `remark` for parsing
 - Wiki-links (`[[...]]`) parsed but not resolved yet (Phase 2)
 
@@ -123,6 +130,7 @@ Render markdown content to HTML with caching.
 Build the knowledge entry list page in the web UI.
 
 **Acceptance Criteria:**
+
 - [ ] List view with title, summary, tags, updated date
 - [ ] Filter by status (draft/published/archived)
 - [ ] Filter by tag
@@ -144,6 +152,7 @@ Build the knowledge entry list page in the web UI.
 Build the entry view and edit page.
 
 **Acceptance Criteria:**
+
 - [ ] View mode with rendered markdown
 - [ ] Edit mode with markdown editor
 - [ ] Split view option (edit + preview)
@@ -155,6 +164,7 @@ Build the entry view and edit page.
 - [ ] Keyboard shortcuts (Cmd+S to save)
 
 **Technical Notes:**
+
 - Consider CodeMirror or Monaco for editor
 - May use existing rich-text patterns from Mosaic
 
@@ -172,6 +182,7 @@ Build the entry view and edit page.
 Parse `[[wiki-link]]` syntax from markdown content.
 
 **Acceptance Criteria:**
+
 - [ ] Extract all `[[...]]` patterns from content
 - [ ] Support `[[slug]]` basic syntax
 - [ ] Support `[[slug|display text]]` aliased links
@@ -180,12 +191,13 @@ Parse `[[wiki-link]]` syntax from markdown content.
 - [ ] Handle edge cases (nested brackets, escaping)
 
 **Technical Notes:**
+
 ```typescript
 interface ParsedLink {
-  raw: string;           // "[[design|Design Doc]]"
-  target: string;        // "design"
-  display: string;       // "Design Doc"
-  section?: string;      // "header" if [[design#header]]
+  raw: string; // "[[design|Design Doc]]"
+  target: string; // "design"
+  display: string; // "Design Doc"
+  section?: string; // "header" if [[design#header]]
   position: { start: number; end: number };
 }
 ```
@@ -202,6 +214,7 @@ interface ParsedLink {
 Resolve parsed wiki-links to actual entries.
 
 **Acceptance Criteria:**
+
 - [ ] Resolve by exact slug match
 - [ ] Resolve by title match (case-insensitive)
 - [ ] Fuzzy match fallback (optional)
@@ -221,6 +234,7 @@ Resolve parsed wiki-links to actual entries.
 Store links in database and keep in sync with content.
 
 **Acceptance Criteria:**
+
 - [ ] On entry save: parse → resolve → store links
 - [ ] Remove stale links on update
 - [ ] `GET /api/knowledge/entries/:slug/links/outgoing`
@@ -240,6 +254,7 @@ Store links in database and keep in sync with content.
 Show incoming links (backlinks) on entry pages.
 
 **Acceptance Criteria:**
+
 - [ ] Backlinks section on entry detail page
 - [ ] Show linking entry title + context snippet
 - [ ] Click to navigate to linking entry
@@ -258,6 +273,7 @@ Show incoming links (backlinks) on entry pages.
 Autocomplete suggestions when typing `[[`.
 
 **Acceptance Criteria:**
+
 - [ ] Trigger on `[[` typed in editor
 - [ ] Show dropdown with matching entries
 - [ ] Search by title and slug
@@ -278,6 +294,7 @@ Autocomplete suggestions when typing `[[`.
 Render wiki-links as clickable links in entry view.
 
 **Acceptance Criteria:**
+
 - [ ] `[[slug]]` renders as link to `/knowledge/slug`
 - [ ] `[[slug|text]]` shows custom text
 - [ ] Broken links styled differently (red, dashed underline)
@@ -297,6 +314,7 @@ Render wiki-links as clickable links in entry view.
 Set up PostgreSQL full-text search for entries.
 
 **Acceptance Criteria:**
+
 - [ ] Add `tsvector` column to entries table
 - [ ] Create GIN index on search vector
 - [ ] Weight title (A), summary (B), content (C)
@@ -315,6 +333,7 @@ Set up PostgreSQL full-text search for entries.
 Implement search API with full-text search.
 
 **Acceptance Criteria:**
+
 - [ ] `GET /api/knowledge/search?q=...`
 - [ ] Return ranked results with snippets
 - [ ] Highlight matching terms in snippets
@@ -334,6 +353,7 @@ Implement search API with full-text search.
 Build search interface in web UI.
 
 **Acceptance Criteria:**
+
 - [ ] Search input in knowledge module header
 - [ ] Search results page
 - [ ] Highlighted snippets
@@ -354,12 +374,14 @@ Build search interface in web UI.
 Set up pgvector extension for semantic search.
 
 **Acceptance Criteria:**
+
 - [ ] Enable pgvector extension in PostgreSQL
 - [ ] Create embeddings table with vector column
 - [ ] HNSW index for fast similarity search
 - [ ] Verify extension works in dev and prod
 
 **Technical Notes:**
+
 - May need PostgreSQL 15+ for best pgvector support
 - Consider managed options (Supabase, Neon) if self-hosting is complex
 
@@ -375,6 +397,7 @@ Set up pgvector extension for semantic search.
 Generate embeddings for entries using OpenAI or local model.
 
 **Acceptance Criteria:**
+
 - [ ] Service to generate embeddings from text
 - [ ] On entry create/update: queue embedding job
 - [ ] Background worker processes queue
@@ -383,6 +406,7 @@ Generate embeddings for entries using OpenAI or local model.
 - [ ] Config for embedding model selection
 
 **Technical Notes:**
+
 - Start with OpenAI `text-embedding-ada-002`
 - Consider local options (sentence-transformers) for cost/privacy
 
@@ -398,6 +422,7 @@ Generate embeddings for entries using OpenAI or local model.
 Implement semantic (vector) search endpoint.
 
 **Acceptance Criteria:**
+
 - [ ] `POST /api/knowledge/search/semantic`
 - [ ] Accept natural language query
 - [ ] Generate query embedding
@@ -419,6 +444,7 @@ Implement semantic (vector) search endpoint.
 API to retrieve knowledge graph data.
 
 **Acceptance Criteria:**
+
 - [ ] `GET /api/knowledge/graph` - Full graph (nodes + edges)
 - [ ] `GET /api/knowledge/graph/:slug` - Subgraph centered on entry
 - [ ] `GET /api/knowledge/graph/stats` - Graph statistics
@@ -438,6 +464,7 @@ API to retrieve knowledge graph data.
 Interactive knowledge graph visualization.
 
 **Acceptance Criteria:**
+
 - [ ] Force-directed graph layout
 - [ ] Nodes sized by connection count
 - [ ] Nodes colored by status
@@ -447,6 +474,7 @@ Interactive knowledge graph visualization.
 - [ ] Performance OK with 500+ nodes
 
 **Technical Notes:**
+
 - Use D3.js or Cytoscape.js
 - Consider WebGL renderer for large graphs
 
@@ -462,6 +490,7 @@ Interactive knowledge graph visualization.
 Show mini-graph on entry detail page.
 
 **Acceptance Criteria:**
+
 - [ ] Small graph showing entry + direct connections
 - [ ] 1-2 hop neighbors
 - [ ] Click to expand or navigate
@@ -479,6 +508,7 @@ Show mini-graph on entry detail page.
 Dashboard showing knowledge base health.
 
 **Acceptance Criteria:**
+
 - [ ] Total entries, links, tags
 - [ ] Orphan entry count (no links)
 - [ ] Broken link count
@@ -500,6 +530,7 @@ Dashboard showing knowledge base health.
 API for entry version history.
 
 **Acceptance Criteria:**
+
 - [ ] Create version on each save
 - [ ] `GET /api/knowledge/entries/:slug/versions`
 - [ ] `GET /api/knowledge/entries/:slug/versions/:v`
@@ -519,6 +550,7 @@ API for entry version history.
 UI to browse and restore versions.
 
 **Acceptance Criteria:**
+
 - [ ] Version list sidebar/panel
 - [ ] Show version date, author, change note
 - [ ] Click to view historical version
@@ -527,6 +559,7 @@ UI to browse and restore versions.
 - [ ] Compare any two versions
 
 **Technical Notes:**
+
 - Use diff library for content comparison
 - Highlight additions/deletions
 
@@ -542,6 +575,7 @@ UI to browse and restore versions.
 Import existing markdown files into knowledge base.
 
 **Acceptance Criteria:**
+
 - [ ] Upload `.md` file(s)
 - [ ] Parse frontmatter for metadata
 - [ ] Generate slug from filename or title
@@ -561,6 +595,7 @@ Import existing markdown files into knowledge base.
 Export entries to markdown/PDF.
 
 **Acceptance Criteria:**
+
 - [ ] Export single entry as markdown
 - [ ] Export single entry as PDF
 - [ ] Bulk export (all or filtered)
@@ -579,6 +614,7 @@ Export entries to markdown/PDF.
 Implement Valkey caching for knowledge module.
 
 **Acceptance Criteria:**
+
 - [ ] Cache entry JSON
 - [ ] Cache rendered HTML
 - [ ] Cache graph data
@@ -598,6 +634,7 @@ Implement Valkey caching for knowledge module.
 Document the knowledge module.
 
 **Acceptance Criteria:**
+
 - [ ] User guide for knowledge module
 - [ ] API reference (OpenAPI already in place)
 - [ ] Wiki-link syntax reference
@@ -617,6 +654,7 @@ Document the knowledge module.
 Multiple users editing same entry simultaneously.
 
 **Notes:**
+
 - Would require CRDT or OT implementation
 - Significant complexity
 - Evaluate need before committing
@@ -632,6 +670,7 @@ Multiple users editing same entry simultaneously.
 Pre-defined templates for common entry types.
 
 **Notes:**
+
 - ADR template
 - Design doc template
 - Meeting notes template
@@ -648,6 +687,7 @@ Pre-defined templates for common entry types.
 Upload and embed images/files in entries.
 
 **Notes:**
+
 - S3/compatible storage backend
 - Image optimization
 - Paste images into editor
@@ -656,15 +696,15 @@ Upload and embed images/files in entries.
 
 ## Summary
 
-| Phase | Issues | Est. Hours | Focus |
-|-------|--------|------------|-------|
-| 1 | KNOW-001 to KNOW-006 | 31h | CRUD + Basic UI |
-| 2 | KNOW-007 to KNOW-012 | 24h | Wiki-links |
-| 3 | KNOW-013 to KNOW-018 | 28h | Search |
-| 4 | KNOW-019 to KNOW-022 | 19h | Graph |
-| 5 | KNOW-023 to KNOW-028 | 25h | Polish |
-| **Total** | 28 issues | ~127h | ~3-4 dev weeks |
+| Phase     | Issues               | Est. Hours | Focus           |
+| --------- | -------------------- | ---------- | --------------- |
+| 1         | KNOW-001 to KNOW-006 | 31h        | CRUD + Basic UI |
+| 2         | KNOW-007 to KNOW-012 | 24h        | Wiki-links      |
+| 3         | KNOW-013 to KNOW-018 | 28h        | Search          |
+| 4         | KNOW-019 to KNOW-022 | 19h        | Graph           |
+| 5         | KNOW-023 to KNOW-028 | 25h        | Polish          |
+| **Total** | 28 issues            | ~127h      | ~3-4 dev weeks  |
 
 ---
 
-*Generated by Jarvis • 2025-01-29*
+_Generated by Jarvis • 2025-01-29_