diff --git a/.beads/.gitignore b/.beads/.gitignore
index f438450fc..f7f9c3350 100644
--- a/.beads/.gitignore
+++ b/.beads/.gitignore
@@ -10,6 +10,13 @@ daemon.lock
 daemon.log
 daemon.pid
 bd.sock
+bd.sock.startlock
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Local interaction log (session-specific)
+interactions.jsonl
 
 # Legacy database files
 db.sqlite
diff --git a/.beads/.local_version b/.beads/.local_version
deleted file mode 100644
index ae6dd4e20..000000000
--- a/.beads/.local_version
+++ /dev/null
@@ -1 +0,0 @@
-0.29.0
diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl
index f0d944081..4338ed42b 100644
--- a/.beads/issues.jsonl
+++ b/.beads/issues.jsonl
@@ -1,111 +1,185 @@
-{"id":"agent-relay-0bn","title":"Dashboard doesn't show real-time connection status","description":"Dashboard shows agent status from messages but doesn't show live connection status (connected/disconnected). The daemon tracks this in agents.json but dashboard could show online/offline indicators with last-seen timestamps.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:18:04.647965+01:00","updated_at":"2025-12-20T00:18:04.647965+01:00"}
-{"id":"agent-relay-0uh","title":"Add session discovery for better status output","description":"Auto-discover relay sessions via 'tmux list-sessions'. Filter to relay-* sessions and extract agent names. Enhance 'agent-relay status' command output. See docs/TMUX_IMPROVEMENTS.md for implementation details.","status":"closed","priority":2,"issue_type":"feature","assignee":"LeadDev","created_at":"2025-12-20T21:28:49.058578+01:00","updated_at":"2025-12-20T21:36:23.10406+01:00","closed_at":"2025-12-20T21:36:23.10406+01:00"}
-{"id":"agent-relay-1ek","title":"Add agent registry for persistence across restarts","description":"Store agent metadata in persistent registry (agents.json): id, name, cli, workingDirectory, firstSeen, lastSeen, messagesSent, messagesReceived. Enables agent history and stats. See docs/TMUX_IMPROVEMENTS.md for implementation details.","notes":"No progress today; agent registry idea remains open. Consider aligning with Swarm Mail 'agents' projection + last_active tracking.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-20T21:28:50.235444+01:00","updated_at":"2025-12-20T22:00:47.791303+01:00"}
-{"id":"agent-relay-2lw","title":"Add agent metadata tracking","description":"Track program, model, task description in agents.json. Better agent discovery.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:36:19.741328+01:00","updated_at":"2025-12-20T21:36:19.741328+01:00"}
-{"id":"agent-relay-2sn","title":"Competitive Analysis: mcp_agent_mail vs agent-relay","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-20T21:34:44.49366+01:00","updated_at":"2025-12-20T21:36:26.362391+01:00","closed_at":"2025-12-20T21:36:26.362391+01:00"}
-{"id":"agent-relay-2uf","title":"Add message threading support","description":"@relay:Bob [thread:feature-123] pattern. Group related messages for better context.","notes":"Current state: thread parsing + protocol/storage support implemented (ParsedCommand.thread, SendPayload.thread, DB messages.thread + filter). Remaining: wire cmd.thread through tmux-wrapper sendRelayCommand -\u003e RelayClient.sendMessage(..., thread) and include thread in injected display/Inbox. See src/wrapper/tmux-wrapper.ts sendRelayCommand + handleIncomingMessage.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:36:19.631448+01:00","updated_at":"2025-12-20T21:59:53.973954+01:00"}
-{"id":"agent-relay-2z1","title":"ACK messages not used for reliability","description":"In connection.ts:114-116, ACK messages are accepted but not processed. The protocol supports reliable delivery with ACK/NACK but it's not implemented. Need to: (1) Track unACKed messages, (2) Implement retry logic, (3) Add configurable TTL for messages.","status":"closed","priority":2,"issue_type":"feature","assignee":"LeadDev","created_at":"2025-12-20T00:17:43.615251+01:00","updated_at":"2025-12-20T21:56:07.202292+01:00","closed_at":"2025-12-20T21:56:07.202292+01:00"}
-{"id":"agent-relay-37i","title":"Message deduplication uses in-memory Set without limits","description":"In tmux-wrapper.ts:65, sentMessageHashes is a Set that grows unbounded. For long-running sessions, this could cause memory issues. Add: (1) Max size with LRU eviction, (2) Time-based expiration, (3) Bloom filter alternative for memory efficiency.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T00:18:47.229988+01:00","updated_at":"2025-12-20T00:18:47.229988+01:00"}
 {"id":"agent-relay-41f","title":"BUG: better-sqlite3 bindings fail on Node 25","description":"agent-relay read command fails with 'Could not locate the bindings file' on Node v25.2.1. Need to rebuild bindings or use compatible Node version.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-20T21:46:24.882216+01:00","updated_at":"2025-12-20T21:49:56.89756+01:00","closed_at":"2025-12-20T21:49:56.89756+01:00"}
+{"id":"agent-relay-9uy","title":"Durable inbox state (unread/read/acked per recipient)","description":"Implement per-recipient inbox state (unread/read/acked) similar to swarm-mail’s message_recipients projection. Persist and query unread/urgent; expose to dashboard + CLI read/lookup.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-20T21:43:46.201965+01:00","updated_at":"2025-12-22T14:25:41.862138+01:00","closed_at":"2025-12-22T14:25:41.862138+01:00"}
+{"id":"agent-relay-90h","title":"Show 'needs attention' indicator when agent is waiting for permissions","description":"Frontend complete: needsAttention field, pulsing indicator, badge. Backend piece still needed: detect when agents are waiting for permissions and set the flag.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-23T22:55:26.87753+01:00","updated_at":"2025-12-24T11:48:32.679452+01:00","closed_at":"2025-12-24T11:48:32.679452+01:00"}
+{"id":"agent-relay-85z","title":"Merge dashboard into start command","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-19T21:59:51.61716+01:00","updated_at":"2025-12-19T22:06:44.27487+01:00","closed_at":"2025-12-19T22:06:44.27487+01:00"}
+{"id":"ctrl-004","title":"[Control Plane] Human authentication (OAuth/magic link)","description":"Secure human access to control plane. OAuth2 (GitHub/Google) or magic link email auth. JWT tokens for API access. Role-based permissions (admin/operator/viewer).","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"fed-026","title":"[Transport] Implement NATS transport adapter","description":"Create NatsTransport implementing PeerTransport interface. JetStream for persistence. Subject-based routing. See FEDERATION_PROPOSAL.md Section 11.4.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"agent-relay-multi-project-dashboard","title":"Enhance dashboard for multi-project bridge view","description":"Add a bridge view to the dashboard that shows all connected projects, their leads, workers, and cross-project message flow. Should be accessible at /bridge?projects=... See docs/DESIGN_BRIDGE_STAFFING.md for mockups.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-21T10:45:00Z","updated_at":"2025-12-22T22:04:18.511591+01:00","closed_at":"2025-12-22T22:04:18.511591+01:00"}
+{"id":"agent-relay-6mo","title":"Lead spawn capability not working (@relay:spawn pattern)","description":"The lead command advertises spawn capability via @relay:spawn pattern but it's not fully implemented. Agents started with 'agent-relay lead' should be able to spawn workers, but the parser extension mentioned in the code is not implemented.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-23T12:14:59.492237+01:00","updated_at":"2025-12-23T12:18:14.114911+01:00","closed_at":"2025-12-23T12:18:14.114911+01:00"}
+{"id":"agent-relay-threads","title":"Implement threaded conversations (Slack-style)","description":"Add thread replies with parent_message_id tracking in storage, nested thread UI display in dashboard, thread notification badges, and expand/collapse thread views. Backend: add parent_message_id column, thread reply routing. Frontend: inline thread expansion, reply count badges, thread-specific compose.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-23T12:00:00Z","updated_at":"2025-12-23T16:37:22.987643+01:00","closed_at":"2025-12-23T16:37:22.987643+01:00"}
+{"id":"agent-relay-u2z","title":"Add @-mention autocomplete with Tab in dashboard chat input","description":"When a user types '@' in the dashboard chat input, show a dropdown of available/connected agents. Tab key should autocomplete the selected agent name. This enables easy @-mentioning of agents for direct messages.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-23T22:52:34.749062+01:00","updated_at":"2025-12-23T22:57:11.634365+01:00","closed_at":"2025-12-23T22:57:11.634365+01:00"}
+{"id":"agent-relay-52d","title":"Add metrics/observability for daemon","description":"No way to monitor daemon health, message throughput, or agent activity. Add: (1) /metrics endpoint for Prometheus, (2) Message count/rate stats, (3) Connection lifecycle events, (4) Error rate tracking.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:18:48.378728+01:00","updated_at":"2025-12-25T13:59:43.376287+01:00","closed_at":"2025-12-25T13:59:43.376287+01:00"}
+{"id":"agent-relay-1le","title":"Agent name truncated in tmux pane/status bar","description":"Agent name gets cut off in tmux display. May need to adjust tmux status bar width or session naming convention. Check: tmux status-left-length, session name format (relay-{name}-{pid}).","status":"closed","priority":3,"issue_type":"bug","created_at":"2025-12-20T22:11:15.795453+01:00","updated_at":"2025-12-22T14:55:02.472816+01:00","closed_at":"2025-12-22T14:55:02.472818+01:00"}
+{"id":"agent-relay-p0k","title":"Gemini agents cannot send relay messages","description":"Gem (Gemini CLI) can receive messages but cannot send them. Tried: -\u003erelay:, \u003e\u003erelay:, escaping with backticks, splitting lines. Messages don't get captured/sent. Possibly Gemini CLI output handling differs from Claude/Codex. Need to investigate how Gemini outputs text and whether the tmux capture-pane is picking it up correctly.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-22T13:52:43.407612+01:00","updated_at":"2025-12-22T13:55:11.068344+01:00","closed_at":"2025-12-22T13:55:11.068344+01:00"}
+{"id":"hook-011","title":"[Hooks] Implement onIdle event","description":"Add onIdle hook to TmuxWrapper.pollOutput(). Fire when no output for idleThreshold (default 30s). Fire once per idle period, not continuously. Configurable threshold. See HOOKS_API.md lifecycle spec.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z"}
+{"id":"ctrl-003","title":"[Control Plane] Build web dashboard v2 (fleet control)","description":"Next.js dashboard with: fleet overview, task assignment UI, agent status cards, trajectory viewer, decision queue. Learn from ai-maestro's hierarchical naming and color coding.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"agent-relay-spawn-handler","title":"Wire up spawn/release command handling in lead mode","description":"Lead agents can output @relay:spawn and @relay:release commands, but the handler needs to be wired up to actually call the AgentSpawner. The spawner exists in src/bridge/spawner.ts, need to intercept these commands in the TmuxWrapper or add a message handler.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-21T10:45:00Z","updated_at":"2025-12-24T15:09:22.953849+01:00","closed_at":"2025-12-24T15:09:22.953849+01:00"}
+{"id":"agent-relay-ex7","title":"Competitive analysis: Agent-to-agent messaging solutions","description":"Research and compare 17 multi-agent orchestration tools against agent-relay. Analyze: agent communication patterns, pros/cons, server/mobile support, memory architecture.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-23T16:34:31.174109+01:00","updated_at":"2025-12-23T16:55:19.264056+01:00","closed_at":"2025-12-23T16:55:19.264056+01:00"}
+{"id":"agent-relay-hks","title":"Increase test coverage for daemon/server.ts, dashboard, and CLI","description":"Current coverage is only 39% overall. Key files with 0% coverage: daemon/server.ts, dashboard/server.ts, cli/index.ts, wrapper/client.ts, wrapper/tmux-wrapper.ts, utils/project-namespace.ts. Need integration tests for the daemon startup/shutdown lifecycle and CLI commands.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-20T00:17:29.603137+01:00","updated_at":"2025-12-22T17:14:41.611717+01:00","closed_at":"2025-12-22T17:14:41.611717+01:00"}
+{"id":"fed-008","title":"[Phase 2] CLI: agent-relay agents --fleet","description":"Add --fleet flag to agents command. Query FleetRegistry for all agents across servers. Display server, CLI, status, connected_at columns.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"fed-023","title":"[Phase 5] Implement flow control","description":"Add credit-based flow control per peer. PEER_ACK to replenish credits. PEER_BUSY/PEER_READY for backpressure. Rate limiting. See FEDERATION_PROPOSAL.md Section 9.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"fed-018","title":"[Phase 5] Add TLS support for peer connections","description":"Configure wss:// with cert/key/ca paths. Support mutual TLS (mTLS) optionally. Reject non-TLS in production mode.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"agent-relay-3px","title":"Add playbook system for batch automation","description":"Implement playbook system (like Maestro's Auto Run) for batch-processing task lists through agents. Define workflows in YAML/markdown, execute automatically with context isolation. Enables reproducible multi-step automation.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-23T17:04:54.464749+01:00","updated_at":"2025-12-23T17:04:54.464749+01:00"}
+{"id":"agent-relay-8z1","title":"Add CLI tests for new command structure","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-19T22:00:04.561793+01:00","updated_at":"2025-12-22T17:10:28.100961+01:00","closed_at":"2025-12-22T17:10:28.100961+01:00","dependencies":[{"issue_id":"agent-relay-8z1","depends_on_id":"agent-relay-85z","type":"blocks","created_at":"2025-12-19T22:00:27.632396+01:00","created_by":"daemon"},{"issue_id":"agent-relay-8z1","depends_on_id":"agent-relay-4ft","type":"blocks","created_at":"2025-12-19T22:00:27.671868+01:00","created_by":"daemon"},{"issue_id":"agent-relay-8z1","depends_on_id":"agent-relay-bd0","type":"blocks","created_at":"2025-12-19T22:00:27.713889+01:00","created_by":"daemon"},{"issue_id":"agent-relay-8z1","depends_on_id":"agent-relay-f3q","type":"blocks","created_at":"2025-12-19T22:00:27.752052+01:00","created_by":"daemon"}]}
+{"id":"agent-relay-7bp","title":"Memory storage adapter has fixed 1000 message limit","description":"In storage/adapter.ts:60-63, MemoryStorageAdapter hard-codes 1000 message limit. This should be configurable and potentially use LRU eviction instead of slice.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T00:17:46.132735+01:00","updated_at":"2025-12-20T00:17:46.132735+01:00"}
+{"id":"agent-relay-5fa","title":"Add exponential backoff for daemon reconnection","description":"Implement graceful reconnection with exponential backoff delays [100, 500, 1000, 2000, 5000ms]. After max attempts, operate offline gracefully. See docs/TMUX_IMPROVEMENTS.md for implementation details.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:28:48.055013+01:00","updated_at":"2025-12-20T21:33:42.229756+01:00","closed_at":"2025-12-20T21:33:42.229756+01:00"}
 {"id":"agent-relay-47z","title":"Express 5 may have breaking changes from Express 4 patterns","description":"package.json uses express@5.2.1 which is a major version with breaking changes from Express 4. Verify: (1) Error handling middleware patterns, (2) Router behavior, (3) Body parsing (express.json vs body-parser).","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T00:18:49.269841+01:00","updated_at":"2025-12-20T00:18:49.269841+01:00"}
-{"id":"agent-relay-4e0","title":"Fix message truncation - messages cut off at source","description":"Root cause found: parser.ts:40 inline regex only captures single line. Multi-line messages are split by parsePassThrough() at line 206. Fix options: (1) Allow continuation lines in inline format, (2) Use block format for multi-line, (3) Add heuristic to join lines until next @relay pattern.","status":"closed","priority":2,"issue_type":"bug","assignee":"MistyShelter","created_at":"2025-12-19T23:40:35.082717+01:00","updated_at":"2025-12-20T00:03:54.806087+01:00","closed_at":"2025-12-20T00:03:54.806087+01:00"}
-{"id":"agent-relay-4ft","title":"Merge project info into status command","description":"","status":"closed","priority":2,"issue_type":"task","assignee":"Pruner","created_at":"2025-12-19T21:59:52.685495+01:00","updated_at":"2025-12-19T22:06:44.276187+01:00","closed_at":"2025-12-19T22:06:44.276187+01:00"}
-{"id":"agent-relay-51u","title":"Outgoing messages truncated before delivery","description":"Agent messages are being cut off mid-sentence. Examples: 'Updates for mcl/2z1:' and 'Signing off. Progress report:' - both end abruptly. May be related to capture-pane buffer limits, parser issues, or injection timing. Investigate: (1) capture-pane -S - scrollback limits, (2) parser line joining, (3) message storage truncation.","notes":"PROGRESS: Reproduced truncation in tmux wrapper/relay flow. Likely due to display truncation on injection length and terminal capture limitations. No code changes yet.","status":"open","priority":1,"issue_type":"bug","created_at":"2025-12-20T21:50:11.411952+01:00","updated_at":"2025-12-20T21:58:01.000293+01:00"}
-{"id":"agent-relay-52d","title":"Add metrics/observability for daemon","description":"No way to monitor daemon health, message throughput, or agent activity. Add: (1) /metrics endpoint for Prometheus, (2) Message count/rate stats, (3) Connection lifecycle events, (4) Error rate tracking.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:18:48.378728+01:00","updated_at":"2025-12-20T00:18:48.378728+01:00"}
+{"id":"hook-010","title":"[Hooks] Implement onOutput event","description":"Add onOutput hook to TmuxWrapper.pollOutput(). Fire on new output diff. Pass output string and context. Keep handlers fast (warn if \u003e100ms). See HOOKS_API.md lifecycle spec.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z"}
+{"id":"ctrl-002","title":"[Control Plane] Implement Lead Agent orchestration","description":"Lead Agent receives human intent, breaks into tasks, assigns to specialized agents based on skills, monitors progress, escalates decisions. Can be AI-powered or rule-based initially.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"agent-relay-8fc","title":"Agent auto-complete menu is transparent/invisible","description":"The agent auto-complete dropdown menu in the dashboard appears to be transparent or has visibility issues, making it unusable. Need to debug CSS/z-index/display issues in bridge.html agent selector component.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-24T15:04:53.390674+01:00","updated_at":"2025-12-24T15:30:23.72431+01:00","closed_at":"2025-12-24T15:30:23.72431+01:00"}
+{"id":"agent-relay-68a","title":"Ask pattern: request/response messaging (replyTo + deferred)","description":"Implement an RPC-like ask() over agent-relay: sender creates a short-lived deferred handle, sends message with replyTo, receiver responds resolving the deferred. Similar to swarm-mail DurableDeferred + ask/respond.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T21:44:33.930531+01:00","updated_at":"2025-12-20T21:44:33.930531+01:00"}
+{"id":"agent-relay-7fx","title":"PR-9 Review: Fix @relay vs -\u003erelay syntax inconsistency in docs","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-22T22:02:02.782958+01:00","updated_at":"2025-12-22T22:04:02.664058+01:00","closed_at":"2025-12-22T22:04:02.664058+01:00"}
+{"id":"agent-relay-lto","title":"Command palette channel/chat selection","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-23T16:15:32.818842+01:00","updated_at":"2025-12-23T16:18:00.952354+01:00","closed_at":"2025-12-23T16:18:00.952354+01:00"}
+{"id":"agent-relay-oiw","title":"BUG: No per-agent inbox files created","description":"Expected /tmp/agent-relay/\u003cproject\u003e/\u003cagent\u003e/inbox.md but only team/agents.json exists. Agents cannot read their inbox via file.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-20T21:46:24.826442+01:00","updated_at":"2025-12-22T14:29:46.830632+01:00","closed_at":"2025-12-22T14:29:46.830632+01:00"}
+{"id":"agent-relay-7yo","title":"Update CLAUDE.md with new CLI commands","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-19T22:00:02.661859+01:00","updated_at":"2025-12-19T22:07:27.766701+01:00","closed_at":"2025-12-19T22:07:27.766701+01:00","dependencies":[{"issue_id":"agent-relay-7yo","depends_on_id":"agent-relay-85z","type":"blocks","created_at":"2025-12-19T22:00:25.731921+01:00","created_by":"daemon"},{"issue_id":"agent-relay-7yo","depends_on_id":"agent-relay-4ft","type":"blocks","created_at":"2025-12-19T22:00:25.772241+01:00","created_by":"daemon"},{"issue_id":"agent-relay-7yo","depends_on_id":"agent-relay-bd0","type":"blocks","created_at":"2025-12-19T22:00:25.80776+01:00","created_by":"daemon"},{"issue_id":"agent-relay-7yo","depends_on_id":"agent-relay-f3q","type":"blocks","created_at":"2025-12-19T22:00:25.843131+01:00","created_by":"daemon"}]}
+{"id":"fed-024","title":"[Storage] Implement trajectory storage adapter","description":"Create TrajectoryStorageAdapter interface. File system backend (default). SQLite backend for local queries. See FEDERATION_PROPOSAL.md Section 17 and Trajectories Proposal.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"agent-relay-hgw","title":"PR-9 Review: Add reconnection logic to MultiProjectClient","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-22T21:54:09.712003+01:00","updated_at":"2025-12-24T11:50:55.708361+01:00","closed_at":"2025-12-24T11:50:55.708361+01:00"}
+{"id":"agent-relay-hgd","title":"Reliable delivery: resume/replay via cursor/checkpoint","description":"Make ACK/RESUME real: persist a per-agent delivery cursor (last delivered/acked seq) and on reconnect replay missed messages from storage. Use existing delivery.seq as stream position, similar to swarm-mail DurableCursor checkpointing.","status":"in_progress","priority":1,"issue_type":"task","created_at":"2025-12-20T21:44:02.016428+01:00","updated_at":"2025-12-24T14:29:48.822052+01:00"}
+{"id":"fed-009","title":"[Phase 3] Implement PEER_ROUTE handling","description":"Handle incoming PEER_ROUTE messages. Extract target agent, look up in local registry, deliver via existing tmux send-keys injection. Preserve automatic delivery magic.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"hook-009","title":"[Hooks] Implement onSessionEnd event","description":"Add onSessionEnd hook to TmuxWrapper.stop() and SIGINT handler. Fire before cleanup. Inject returned text and wait for agent response (5s timeout). See HOOKS_API.md lifecycle spec.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z"}
+{"id":"agent-relay-9uq","title":"Project chat targeting in bridge","description":"Enable sending messages to agents in a selected project from the bridge interface","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-24T11:47:33.46287+01:00","updated_at":"2025-12-24T11:56:54.182321+01:00","closed_at":"2025-12-24T11:56:54.182321+01:00"}
+{"id":"agent-relay-9qa","title":"Dashboard websocket 'Invalid frame header' error on localhost:3888","description":"Websocket connection to ws://localhost:3888/ws fails with 'Invalid frame header' error from browser. Blocking dashboard functionality.","notes":"WS handshake fixed: restored default WebSocket compression (removed perMessageDeflate:false), removed HTTP polling fallback. FE-Dev confirmed 101 upgrade on 127.0.0.1:3888 after rebuild/refresh.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-23T16:42:29.342087+01:00","updated_at":"2025-12-23T17:04:04.246054+01:00","closed_at":"2025-12-23T17:04:04.246054+01:00"}
+{"id":"agent-relay-2sn","title":"Competitive Analysis: mcp_agent_mail vs agent-relay","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-20T21:34:44.49366+01:00","updated_at":"2025-12-20T21:36:26.362391+01:00","closed_at":"2025-12-20T21:36:26.362391+01:00"}
+{"id":"agent-relay-4ft","title":"Merge project info into status command","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-19T21:59:52.685495+01:00","updated_at":"2025-12-19T22:06:44.276187+01:00","closed_at":"2025-12-19T22:06:44.276187+01:00"}
+{"id":"mem-004","title":"[Memory] Implement fleet-wide knowledge workspace","description":"Build knowledge workspace layer: decisions log, pattern library, cross-agent context. Query interface for agents to access fleet knowledge. Uses Mem0 for storage.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z"}
+{"id":"fed-001","title":"[Phase 1] Define peer protocol types","description":"Create src/protocol/peer-types.ts with PeerMessageType, PeerEnvelope, PeerHelloPayload, PeerWelcomePayload, PeerSyncPayload, PeerRoutePayload, PeerBroadcastPayload. See FEDERATION_PROPOSAL.md Section 4.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"agent-relay-i7s","title":"Add priority-based message queuing","description":"Implement message priority levels (urgent/high/normal/low) like AI Maestro. Urgent messages jump the queue and interrupt agents. Enables time-sensitive coordination in production scenarios.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-23T17:04:48.031237+01:00","updated_at":"2025-12-23T17:04:48.031237+01:00"}
+{"id":"agent-relay-4vl","title":"PR-9 Review: Add unit tests for AgentSpawner","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-22T21:54:03.195295+01:00","updated_at":"2025-12-22T22:00:57.315234+01:00","closed_at":"2025-12-22T22:00:57.315234+01:00"}
+{"id":"agent-relay-cli-simplify","title":"Simplify agent-relay CLI interface","description":"The CLI has too many commands. Consolidate into a clean, simple interface:\n\n1. `relay start` should also kick off the dashboard automatically\n2. Merge redundant team-* commands\n3. Remove rarely-used commands or make them subcommands\n4. Target: 5-7 top-level commands max\n\nCurrent commands to evaluate:\n- start, stop, status (keep)\n- wrap (keep)\n- project (keep or merge into status)\n- send (keep)\n- team-setup, team-status, team-send, team-check, team-listen, team-start (consolidate)\n- msg-read (make subcommand or integrate)\n- dashboard (merge into start)","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-22T21:51:14.010849+01:00","updated_at":"2025-12-22T21:51:14.010849+01:00","closed_at":"2025-12-19T22:08:44.107992+01:00"}
+{"id":"agent-relay-cross-project-parser","title":"Add cross-project message syntax to parser","description":"Extend the parser (src/wrapper/parser.ts) to recognize @relay:project:agent syntax for cross-project messaging. Currently only @relay:agent is parsed. Need to add pattern matching for the project:agent format.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-21T10:45:00Z","updated_at":"2025-12-24T11:46:51.622328+01:00","closed_at":"2025-12-24T11:46:51.622328+01:00"}
 {"id":"agent-relay-5af","title":"Hook doesn't integrate with daemon-based messaging","description":"hooks/inbox-check/hook.ts reads from file-based inbox but the daemon uses SQLite. When using daemon mode, the hook won't see messages. Need to: (1) Query daemon storage, (2) Or ensure inbox files are written in daemon mode too.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-20T00:18:35.503078+01:00","updated_at":"2025-12-20T00:18:35.503078+01:00"}
-{"id":"agent-relay-5fa","title":"Add exponential backoff for daemon reconnection","description":"Implement graceful reconnection with exponential backoff delays [100, 500, 1000, 2000, 5000ms]. After max attempts, operate offline gracefully. See docs/TMUX_IMPROVEMENTS.md for implementation details.","status":"closed","priority":2,"issue_type":"feature","assignee":"LeadDev","created_at":"2025-12-20T21:28:48.055013+01:00","updated_at":"2025-12-20T21:33:42.229756+01:00","closed_at":"2025-12-20T21:33:42.229756+01:00"}
-{"id":"agent-relay-5g0","title":"Heartbeat timeout could be more configurable","description":"In connection.ts:196, heartbeat timeout is hardcoded as 2x heartbeatMs. This should be independently configurable. Also, heartbeat failures immediately kill the connection - could implement exponential backoff for transient issues.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T00:18:03.556614+01:00","updated_at":"2025-12-20T00:18:03.556614+01:00"}
-{"id":"agent-relay-68a","title":"Ask pattern: request/response messaging (replyTo + deferred)","description":"Implement an RPC-like ask() over agent-relay: sender creates a short-lived deferred handle, sends message with replyTo, receiver responds resolving the deferred. Similar to swarm-mail DurableDeferred + ask/respond.","acceptance_criteria":"- ask() returns response or times out\\n- Deferreds are persisted with TTL\\n- Works across process restarts/reconnects","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T21:44:33.930531+01:00","updated_at":"2025-12-20T21:44:33.930531+01:00","labels":["coordination","protocol"]}
-{"id":"agent-relay-6nx","title":"Add activity state tracking for better injection timing","description":"Track active/idle/disconnected state with timestamps. When session goes idle (30s no activity), trigger message injection opportunity. Improves injection timing vs current fixed 1.5s wait. See docs/TMUX_IMPROVEMENTS.md for implementation details.","status":"closed","priority":2,"issue_type":"feature","assignee":"LeadDev","created_at":"2025-12-20T21:28:46.993856+01:00","updated_at":"2025-12-20T21:33:42.223042+01:00","closed_at":"2025-12-20T21:33:42.223042+01:00"}
-{"id":"agent-relay-6ny","title":"Fix message truncation: store full message in SQLite first, include ID in relay","description":"","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-19T22:04:36.168862+01:00","updated_at":"2025-12-19T22:08:28.207532+01:00","closed_at":"2025-12-19T22:08:28.207532+01:00"}
-{"id":"agent-relay-6rz","title":"Message injection timing can cause race conditions","description":"In tmux-wrapper.ts:564-569, injection waits for 'idle' (1.5s since last output) but this is fragile. If agent produces output during injection, messages could interleave. Consider: (1) Input buffer detection, (2) Bracketed paste mode, (3) Agent-specific injection strategies.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-20T00:18:17.76865+01:00","updated_at":"2025-12-20T00:18:17.76865+01:00"}
-{"id":"agent-relay-7bp","title":"Memory storage adapter has fixed 1000 message limit","description":"In storage/adapter.ts:60-63, MemoryStorageAdapter hard-codes 1000 message limit. This should be configurable and potentially use LRU eviction instead of slice.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T00:17:46.132735+01:00","updated_at":"2025-12-20T00:17:46.132735+01:00"}
-{"id":"agent-relay-7tu","title":"Fix storage portability: better-sqlite3 native binding failures","description":"The read command fails in some Node versions (e.g., Node 25) due to missing better-sqlite3 bindings. Decide path: pin supported Node LTS + ensure rebuild, or replace with a non-native option (e.g., Node sqlite, wasm, or a pure JS adapter).","design":"Implement driver selection/fallback: try better-sqlite3, fallback to node:sqlite DatabaseSync when bindings missing. Add env override AGENT_RELAY_SQLITE_DRIVER=node|better-sqlite3. Convert queries to positional params so both drivers share code.","acceptance_criteria":"- dist CLI read works on supported Node versions\\n- CI/build docs reflect supported runtime or replacement adapter","notes":"Implemented sqlite portability: dynamic better-sqlite3 import + fallback to node:sqlite (env override AGENT_RELAY_SQLITE_DRIVER). Updated sqlite adapter to use positional params for compatibility; added/updated tests; npx vitest run passes (216).","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-20T21:44:57.868091+01:00","updated_at":"2025-12-20T21:56:13.384399+01:00","closed_at":"2025-12-20T21:56:13.3844+01:00","labels":["build","storage"]}
-{"id":"agent-relay-7yo","title":"Update CLAUDE.md with new CLI commands","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-19T22:00:02.661859+01:00","updated_at":"2025-12-19T22:07:27.766701+01:00","closed_at":"2025-12-19T22:07:27.766701+01:00","dependencies":[{"issue_id":"agent-relay-7yo","depends_on_id":"agent-relay-85z","type":"blocks","created_at":"2025-12-19T22:00:25.731921+01:00","created_by":"daemon"},{"issue_id":"agent-relay-7yo","depends_on_id":"agent-relay-4ft","type":"blocks","created_at":"2025-12-19T22:00:25.772241+01:00","created_by":"daemon"},{"issue_id":"agent-relay-7yo","depends_on_id":"agent-relay-bd0","type":"blocks","created_at":"2025-12-19T22:00:25.80776+01:00","created_by":"daemon"},{"issue_id":"agent-relay-7yo","depends_on_id":"agent-relay-f3q","type":"blocks","created_at":"2025-12-19T22:00:25.843131+01:00","created_by":"daemon"}]}
-{"id":"agent-relay-85z","title":"Merge dashboard into start command","description":"","status":"closed","priority":2,"issue_type":"task","assignee":"InterfaceManager","created_at":"2025-12-19T21:59:51.61716+01:00","updated_at":"2025-12-19T22:06:44.27487+01:00","closed_at":"2025-12-19T22:06:44.27487+01:00"}
-{"id":"agent-relay-8ff","title":"Add agent list command to CLI","description":"CLI has up/down/status/read but no way to list connected agents or see message history from command line. Add: (1) agent-relay agents - list connected agents, (2) agent-relay history - show recent messages, (3) agent-relay send \u003cagent\u003e \u003cmsg\u003e - send from CLI.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:18:34.400432+01:00","updated_at":"2025-12-20T00:18:34.400432+01:00"}
-{"id":"agent-relay-8nx","title":"SIGINT/SIGTERM handlers don't await cleanup","description":"In cli/index.ts:74-77 and daemon setup, SIGINT handlers call stop() but process.exit(0) runs immediately. The stop() is async but not awaited, potentially leaving socket files or incomplete shutdown.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-20T00:18:19.189514+01:00","updated_at":"2025-12-20T00:18:19.189514+01:00"}
-{"id":"agent-relay-8z1","title":"Add CLI tests for new command structure","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-19T22:00:04.561793+01:00","updated_at":"2025-12-20T21:57:43.401385+01:00","dependencies":[{"issue_id":"agent-relay-8z1","depends_on_id":"agent-relay-85z","type":"blocks","created_at":"2025-12-19T22:00:27.632396+01:00","created_by":"daemon"},{"issue_id":"agent-relay-8z1","depends_on_id":"agent-relay-4ft","type":"blocks","created_at":"2025-12-19T22:00:27.671868+01:00","created_by":"daemon"},{"issue_id":"agent-relay-8z1","depends_on_id":"agent-relay-bd0","type":"blocks","created_at":"2025-12-19T22:00:27.713889+01:00","created_by":"daemon"},{"issue_id":"agent-relay-8z1","depends_on_id":"agent-relay-f3q","type":"blocks","created_at":"2025-12-19T22:00:27.752052+01:00","created_by":"daemon"}]}
-{"id":"agent-relay-9uy","title":"Durable inbox state (unread/read/acked per recipient)","description":"Implement per-recipient inbox state (unread/read/acked) similar to swarm-mail’s message_recipients projection. Persist and query unread/urgent; expose to dashboard + CLI read/lookup.","acceptance_criteria":"- Can mark message read and acked per recipient\\n- Dashboard/API can query unreadOnly and urgentOnly\\n- State survives daemon restart","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-20T21:43:46.201965+01:00","updated_at":"2025-12-20T21:43:46.201965+01:00","labels":["durability","storage"]}
-{"id":"agent-relay-ahe","title":"Session resume not implemented - RESUME_TOO_OLD always sent","description":"In connection.ts:140-143, session resume tokens are received but not persisted or validated. The server always responds with RESUME_TOO_OLD. This breaks the resume capability advertised in the protocol. Need to implement token persistence and session state recovery.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-20T00:17:30.605649+01:00","updated_at":"2025-12-20T00:17:30.605649+01:00"}
-{"id":"agent-relay-bd0","title":"Consolidate team-* commands under team subcommand","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-19T21:59:54.102815+01:00","updated_at":"2025-12-19T22:06:16.220013+01:00","closed_at":"2025-12-19T22:06:16.220013+01:00"}
-{"id":"agent-relay-bei","title":"Gemini (CleverBeacon) bash syntax errors - unexpected EOF","description":"Gemini agent gets bash errors: 'unexpected EOF while looking for matching quote' and 'syntax error: unexpected end of file' when running shell commands. Possibly related to quote escaping in the relay wrapper.","status":"closed","priority":2,"issue_type":"bug","assignee":"GraniteElk","created_at":"2025-12-19T23:40:36.464079+01:00","updated_at":"2025-12-19T23:45:46.05609+01:00","closed_at":"2025-12-19T23:45:46.05609+01:00"}
-{"id":"agent-relay-cli-simplify","title":"Simplify agent-relay CLI interface","description":"The CLI has too many commands. Consolidate into a clean, simple interface:\n\n1. `relay start` should also kick off the dashboard automatically\n2. Merge redundant team-* commands\n3. Remove rarely-used commands or make them subcommands\n4. Target: 5-7 top-level commands max\n\nCurrent commands to evaluate:\n- start, stop, status (keep)\n- wrap (keep)\n- project (keep or merge into status)\n- send (keep)\n- team-setup, team-status, team-send, team-check, team-listen, team-start (consolidate)\n- msg-read (make subcommand or integrate)\n- dashboard (merge into start)","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-19T22:00:00Z","updated_at":"2025-12-19T22:08:44.107992+01:00","closed_at":"2025-12-19T22:08:44.107992+01:00"}
-{"id":"agent-relay-d07","title":"Message metadata: subject/thread/importance/replyTo","description":"Add first-class metadata fields to messages (subject, threadId, importance, ackRequired, replyTo/correlationId). Carry them via SendPayload.data and/or [[RELAY]] blocks; persist in storage; update injection formatting + dashboard filters.","acceptance_criteria":"- Can send/receive messages with threadId + importance\\n- Dashboard can filter/group by threadId\\n- Injection shows importance/thread hint without breaking TUIs","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T21:44:18.094598+01:00","updated_at":"2025-12-20T21:44:18.094598+01:00","labels":["protocol","ux"]}
-{"id":"agent-relay-d2f","title":"Add optional Git audit trail","description":"Commit messages to .agent-relay/messages/ directory. Recoverable history, compliance-friendly.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:36:19.689795+01:00","updated_at":"2025-12-20T21:36:19.689795+01:00"}
-{"id":"agent-relay-dd8","title":"Add file reservation system (from mcp_agent_mail)","description":"Advisory locks with TTL, @relay:lock pattern, pre-commit hook integration. Critical for multi-agent file editing.","notes":"No progress today; added as future work from swarm-mail comparison: implement reservations/locks with TTL + conflict detection. See swarm-mail reservations + locks patterns.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:36:19.573504+01:00","updated_at":"2025-12-20T22:00:37.608017+01:00"}
+{"id":"agent-relay-d07","title":"Message metadata: subject/thread/importance/replyTo","description":"Add first-class metadata fields to messages (subject, threadId, importance, ackRequired, replyTo/correlationId). Carry them via SendPayload.data and/or [[RELAY]] blocks; persist in storage; update injection formatting + dashboard filters.","notes":"SecondLead: Implemented thread support end-to-end. SendMeta added to client.sendMessage(). tmux-wrapper converts ParsedMessageMetadata to SendMeta. Injection shows [thread:xxx] hint. Dashboard displays thread badge. REMAINING: importance field requires protocol update - DeliverEnvelope needs payload_meta to carry importance through to receivers.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-20T21:44:18.094598+01:00","updated_at":"2025-12-22T17:15:37.261368+01:00","closed_at":"2025-12-22T17:15:37.261368+01:00"}
+{"id":"mem-005","title":"[Memory] Abstract MemoryBackend for future flexibility","description":"Create MemoryBackend interface allowing swap between Mem0, Zep, or custom SQLite+Chroma. Default to Mem0. Enable migration path if needs change.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z"}
+{"id":"agent-relay-vxc","title":"Navigation consistency between bridge and project views","description":"Ensure navigation patterns are consistent when switching between bridge and project dashboard views","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T11:47:46.62539+01:00","updated_at":"2025-12-24T12:00:15.805473+01:00","closed_at":"2025-12-24T12:00:15.805473+01:00"}
+{"id":"agent-relay-nox","title":"Dashboard not showing live agents or messages","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-23T12:11:48.614811+01:00","updated_at":"2025-12-23T12:26:51.322956+01:00","closed_at":"2025-12-23T12:26:51.322956+01:00"}
+{"id":"agent-relay-j9z","title":"Message injection corrupts human input in progress","description":"When a relay message arrives while the human is actively typing, the injection (Esc + Ctrl-U + message + Enter) destroys their partial input. Need to detect active input state before injecting. Options: (1) Check tmux pane input buffer, (2) Queue messages until prompt detected, (3) Use tmux display-message instead of send-keys for non-intrusive notification, (4) Add visual indicator that message is pending.","status":"open","priority":1,"issue_type":"bug","created_at":"2025-12-20T21:48:03.280298+01:00","updated_at":"2025-12-20T22:00:04.196161+01:00","dependencies":[{"issue_id":"agent-relay-j9z","depends_on_id":"agent-relay-6rz","type":"blocks","created_at":"2025-12-20T21:48:10.118963+01:00","created_by":"daemon"}]}
+{"id":"agent-relay-2uf","title":"Add message threading support","description":"@relay:Bob [thread:feature-123] pattern. Group related messages for better context.","notes":"Current state: thread parsing + protocol/storage support implemented (ParsedCommand.thread, SendPayload.thread, DB messages.thread + filter). Remaining: wire cmd.thread through tmux-wrapper sendRelayCommand -\u003e RelayClient.sendMessage(..., thread) and include thread in injected display/Inbox. See src/wrapper/tmux-wrapper.ts sendRelayCommand + handleIncomingMessage.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:36:19.631448+01:00","updated_at":"2025-12-22T17:17:42.876826+01:00","closed_at":"2025-12-22T17:17:42.876826+01:00"}
+{"id":"agent-relay-mcl","title":"Gemini agent cannot send messages properly","description":"Gemini agent cannot autonomously send relay messages. When Gemini outputs @relay: patterns, it enters shell mode instead of being intercepted by the relay wrapper. Manual typing works fine. This suggests a PTY parsing issue specific to how Gemini outputs the @relay: pattern - possibly timing, escaping, or output buffering differences compared to Claude.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-20T00:29:15.797552+01:00","updated_at":"2025-12-20T21:56:07.20143+01:00","closed_at":"2025-12-20T21:56:07.20143+01:00"}
+{"id":"fed-007","title":"[Phase 2] Implement name resolution","description":"Add resolve() method to FleetRegistry. Support patterns: Bob (local-first then fleet), Bob@server (explicit), *@server (broadcast to server). See FEDERATION_PROPOSAL.md Section 5.2.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"mem-002","title":"[Memory] Configure Mem0 MCP for Claude Code agents","description":"Add MCP configuration for Mem0 integration with Claude Code. Document setup in agent-relay README. Test memory persistence across sessions.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z"}
+{"id":"hook-014","title":"[Hooks] Implement hook sandboxing and limits","description":"Enforce hook restrictions: Object.freeze(ctx) for immutability, 2000 char inject limit, 5000 char message limit, one sendMessage per invocation. Add capability escalation config (allowNetworkInHooks, allowFileReadInHooks, unlimitedInjection). See HOOKS_API.md sandboxing section.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T18:00:00Z","updated_at":"2025-12-21T18:00:00Z"}
+{"id":"fed-004","title":"[Phase 1] Add peer WebSocket listener to daemon","description":"Extend daemon to listen for incoming peer connections on configurable port (default 8765). Accept connections, perform handshake, register with PeerManager.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"agent-relay-xn1","title":"Add remote access via Cloudflare tunnels","description":"Enable remote/mobile access to agent-relay dashboard and control. Use Cloudflare tunnels (like Maestro) for secure access without port forwarding. Include QR code generation for easy mobile connection. Major gap vs competitors - AI Maestro and Maestro both have this.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-23T17:04:28.788302+01:00","updated_at":"2025-12-23T17:04:28.788302+01:00"}
+{"id":"agent-relay-1ek","title":"Add agent registry for persistence across restarts","description":"Store agent metadata in persistent registry (agents.json): id, name, cli, workingDirectory, firstSeen, lastSeen, messagesSent, messagesReceived. Enables agent history and stats. See docs/TMUX_IMPROVEMENTS.md for implementation details.","notes":"No progress today; agent registry idea remains open. Consider aligning with Swarm Mail 'agents' projection + last_active tracking.","status":"closed","priority":3,"issue_type":"feature","created_at":"2025-12-20T21:28:50.235444+01:00","updated_at":"2025-12-22T17:08:50.330703+01:00","closed_at":"2025-12-22T17:08:50.330703+01:00"}
+{"id":"agent-relay-5g0","title":"Heartbeat timeout could be more configurable","description":"In connection.ts:196, heartbeat timeout is hardcoded as 2x heartbeatMs. This should be independently configurable. Also, heartbeat failures immediately kill the connection - could implement exponential backoff for transient issues.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-20T00:18:03.556614+01:00","updated_at":"2025-12-23T23:03:07.563273+01:00","closed_at":"2025-12-23T23:03:07.563273+01:00"}
+{"id":"fed-012","title":"[Phase 3] Implement loop prevention","description":"Add hops array to PEER_ROUTE messages. Check for loops before forwarding. Drop messages that have already visited this server. Note: Can be implemented as part of fed-009/010.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"ctrl-009","title":"[Control Plane] Agent skills registry","description":"Track agent capabilities: skills map (Network→websocket,tcp,tls), availability, current workload, performance history. Used by Lead Agent for smart assignment.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"fed-006","title":"[Phase 2] Implement PEER_SYNC message handling","description":"Handle agent_joined, agent_left, full_sync message types. Update FleetRegistry on sync. Trigger sync on new peer connection and periodically (60s).","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"fed-025","title":"[Storage] Implement central trajectory sync","description":"PostgreSQL backend for team sharing. Sync on task complete. Conflict resolution (server-wins default). See FEDERATION_PROPOSAL.md Section 17.3.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"fed-011","title":"[Phase 3] Integrate FederatedRouter with existing Router","description":"Modify existing Router to check FleetRegistry for remote agents. Route to PeerManager for cross-server delivery. Keep local delivery path unchanged.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"agent-relay-ytj","title":"Filter chat view to show only messages with selected agent","description":"When clicking on a particular agent in the dashboard sidebar, the chat view should filter to only show messages between Dashboard and that specific agent. This provides a focused conversation view instead of showing all messages.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-23T22:53:31.325805+01:00","updated_at":"2025-12-23T22:58:41.407339+01:00","closed_at":"2025-12-23T22:58:41.407339+01:00"}
+{"id":"agent-relay-51u","title":"Outgoing messages truncated before delivery","description":"Agent messages are being cut off mid-sentence. Examples: 'Updates for mcl/2z1:' and 'Signing off. Progress report:' - both end abruptly. May be related to capture-pane buffer limits, parser issues, or injection timing. Investigate: (1) capture-pane -S - scrollback limits, (2) parser line joining, (3) message storage truncation.","notes":"PROGRESS: Reproduced truncation in tmux wrapper/relay flow. Likely due to display truncation on injection length and terminal capture limitations. No code changes yet.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-20T21:50:11.411952+01:00","updated_at":"2025-12-22T13:48:45.264136+01:00","closed_at":"2025-12-22T13:48:45.264136+01:00"}
 {"id":"agent-relay-dyr","title":"No authentication between agents","description":"Any process can connect to the daemon socket and impersonate any agent name. Consider: (1) Per-agent tokens/secrets, (2) Socket permission checks, (3) Optional TLS for non-localhost deployments.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:18:16.215889+01:00","updated_at":"2025-12-20T00:18:16.215889+01:00"}
-{"id":"agent-relay-f3q","title":"Make msg-read a subcommand of send or message","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-19T21:59:55.123772+01:00","updated_at":"2025-12-19T22:04:51.112763+01:00","closed_at":"2025-12-19T22:04:51.112763+01:00"}
-{"id":"agent-relay-fb3","title":"Add configurable relay prefix for Gemini compatibility","description":"Gemini CLI uses @ for file references, conflicting with @relay:. Add --prefix flag to CLI and relayPrefix config option. Auto-detect CLI type and use appropriate default (\u003e\u003e for Gemini, @relay: for Claude/Codex). Update parser to use dynamic prefix. See docs/TMUX_IMPROVEMENTS.md for full implementation plan.","status":"closed","priority":2,"issue_type":"feature","assignee":"Coordinator","created_at":"2025-12-20T21:28:52.685002+01:00","updated_at":"2025-12-20T21:40:13.066766+01:00","closed_at":"2025-12-20T21:40:13.066766+01:00"}
-{"id":"agent-relay-ghy","title":"Team config: auto-spawn agents or auto-assign names from teams.json","description":"When a project has a teams.json config file, agent-relay up should either:\n\n1. **Auto-spawn option**: Automatically kick off terminal sessions for each agent defined in teams.json\n2. **Auto-assign option**: When users manually start sessions with `agent-relay -n \u003cname\u003e claude`, validate the name against teams.json and auto-assign roles/permissions\n\n## teams.json format\n```json\n{\n  \"team\": \"my-project\",\n  \"agents\": [\n    {\"name\": \"Coordinator\", \"cli\": \"claude\", \"role\": \"coordinator\"},\n    {\"name\": \"LeadDev\", \"cli\": \"claude\", \"role\": \"developer\"},\n    {\"name\": \"Reviewer\", \"cli\": \"claude\", \"role\": \"reviewer\"}\n  ],\n  \"autoSpawn\": false\n}\n```\n\n## Behavior\n- If `autoSpawn: true`, `agent-relay up` spawns tmux sessions for each agent\n- If `autoSpawn: false`, validate names against config when agents connect\n- Store teams.json in project root or .agent-relay/teams.json\n\n## Commands\n- `agent-relay up --spawn` - force spawn all agents\n- `agent-relay up --no-spawn` - just start daemon, manual agent starts","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-19T23:13:02.482971+01:00","updated_at":"2025-12-20T21:57:43.362401+01:00"}
+{"id":"agent-relay-l99","title":"Add output filtering for cleaner logs","description":"Filter noisy patterns from logs: thinking indicators [1/418], empty ANSI-only lines, etc. Add config.filterLogs option. See docs/TMUX_IMPROVEMENTS.md for implementation details.","status":"open","priority":4,"issue_type":"feature","created_at":"2025-12-20T21:28:51.199736+01:00","updated_at":"2025-12-20T21:28:51.199736+01:00","dependencies":[{"issue_id":"agent-relay-l99","depends_on_id":"agent-relay-1ek","type":"blocks","created_at":"2025-12-20T21:29:26.987526+01:00","created_by":"daemon"}]}
+{"id":"hook-007","title":"[Hooks] Create HookEmitter class","description":"Create src/hooks/emitter.ts with HookEmitter class. Support on(event, handler), emit(event, ...args). Handle async handlers. Support stop propagation. Load handlers from config object. See HOOKS_API.md.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z"}
+{"id":"agent-relay-pvx","title":"Dashboard agent detection debugging","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-23T17:14:36.376736+01:00","updated_at":"2025-12-23T17:16:13.115531+01:00","closed_at":"2025-12-23T17:16:13.115531+01:00"}
+{"id":"agent-relay-coh","title":"Add tests for heartbeat timeout behavior","description":"The heartbeat timeout fix (10s-\u003e30s) was made but no new tests were added. Add unit tests for: 1) configurable heartbeatTimeoutMultiplier, 2) connection survives slow pong responses, 3) connection dies after timeout exceeded.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-23T23:10:18.599194+01:00","updated_at":"2025-12-25T13:31:23.910414+01:00","closed_at":"2025-12-25T13:31:23.910414+01:00"}
+{"id":"agent-relay-9w0","title":"Auto-detect agent role from .claude/agents or .openagents on init","description":"When an agent connects with a name (e.g., 'Lead'), check .claude/agents/ and .openagents/ directories for a matching agent definition file. If found, include in the initialization message that the agent should assume that role. This enables automatic role assignment without manual configuration.","status":"in_progress","priority":1,"issue_type":"feature","created_at":"2025-12-23T16:26:27.510393+01:00","updated_at":"2025-12-24T08:01:39.714171+01:00"}
+{"id":"agent-relay-37i","title":"Message deduplication uses in-memory Set without limits","description":"In tmux-wrapper.ts:65, sentMessageHashes is a Set that grows unbounded. For long-running sessions, this could cause memory issues. Add: (1) Max size with LRU eviction, (2) Time-based expiration, (3) Bloom filter alternative for memory efficiency.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T00:18:47.229988+01:00","updated_at":"2025-12-20T00:18:47.229988+01:00"}
+{"id":"fed-005","title":"[Phase 2] Implement FleetRegistry","description":"Create src/federation/registry.ts with FleetRegistry class. Track agents across fleet with agentToServer mapping. Support fleet-wide unique name enforcement with quorum registration. See FEDERATION_PROPOSAL.md Section 5.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"hook-004","title":"[Hooks] Implement relay.config.ts loader","description":"Create config loader for relay.config.ts. Support project root and ~/.config/agent-relay/. Load pattern handlers and lifecycle hooks. Type-safe config with RelayConfig interface. See HOOKS_API.md.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z"}
+{"id":"fed-019","title":"[Phase 5] Implement Ed25519 authentication","description":"Generate server keypair on first run. Challenge-response handshake. Sign all peer messages. Verify signatures on receive. See FEDERATION_PROPOSAL.md Section 8.1-8.3.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"hook-003","title":"[Hooks] Implement @memory: built-in handler","description":"Create built-in @memory: pattern handler. Support actions: save, search, forget, list. Connect to Mem0 backend. Inject results back to agent. See HOOKS_API.md and MEMORY_STACK_DECISION.md.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z"}
+{"id":"fed-015","title":"[Phase 4] Implement heartbeat (PING/PONG)","description":"Send PEER_PING every 30s. Expect PEER_PONG within 60s. Trigger reconnect on timeout. Track latency_ms in ServerRecord.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"agent-relay-290","title":"Interface parity: bridge vs dashboard features","description":"Audit and synchronize features between bridge and dashboard interfaces to ensure feature parity","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T11:47:58.911802+01:00","updated_at":"2025-12-24T12:01:06.6157+01:00","closed_at":"2025-12-24T12:01:06.6157+01:00"}
+{"id":"agent-relay-t4b","title":"Add spawn agent UI to dashboard","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-25T13:20:54.452959+01:00","updated_at":"2025-12-25T13:25:05.019339+01:00","closed_at":"2025-12-25T13:25:05.019339+01:00"}
+{"id":"agent-relay-bd0","title":"Consolidate team-* commands under team subcommand","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-19T21:59:54.102815+01:00","updated_at":"2025-12-19T22:06:16.220013+01:00","closed_at":"2025-12-19T22:06:16.220013+01:00"}
+{"id":"agent-relay-8nx","title":"SIGINT/SIGTERM handlers don't await cleanup","description":"In cli/index.ts:74-77 and daemon setup, SIGINT handlers call stop() but process.exit(0) runs immediately. The stop() is async but not awaited, potentially leaving socket files or incomplete shutdown.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-20T00:18:19.189514+01:00","updated_at":"2025-12-20T00:18:19.189514+01:00"}
 {"id":"agent-relay-go9","title":"PostgreSQL storage adapter not implemented","description":"In storage/adapter.ts:152-162, PostgreSQL is listed as a storage option but throws 'not yet implemented'. For production multi-node deployments, SQLite won't scale. Implement PostgreSQL adapter for distributed storage.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:17:45.065487+01:00","updated_at":"2025-12-20T00:17:45.065487+01:00"}
-{"id":"agent-relay-hgd","title":"Reliable delivery: resume/replay via cursor/checkpoint","description":"Make ACK/RESUME real: persist a per-agent delivery cursor (last delivered/acked seq) and on reconnect replay missed messages from storage. Use existing delivery.seq as stream position, similar to swarm-mail DurableCursor checkpointing.","acceptance_criteria":"- Client can reconnect and receive missed messages\\n- Duplicate suppression is deterministic (id/seq based)\\n- Cursor persists across daemon restarts","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-20T21:44:02.016428+01:00","updated_at":"2025-12-20T21:44:02.016428+01:00","labels":["durability","protocol"]}
-{"id":"agent-relay-hks","title":"Increase test coverage for daemon/server.ts, dashboard, and CLI","description":"Current coverage is only 39% overall. Key files with 0% coverage: daemon/server.ts, dashboard/server.ts, cli/index.ts, wrapper/client.ts, wrapper/tmux-wrapper.ts, utils/project-namespace.ts. Need integration tests for the daemon startup/shutdown lifecycle and CLI commands.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T00:17:29.603137+01:00","updated_at":"2025-12-20T00:17:29.603137+01:00"}
-{"id":"agent-relay-j9z","title":"Message injection corrupts human input in progress","description":"When a relay message arrives while the human is actively typing, the injection (Esc + Ctrl-U + message + Enter) destroys their partial input. Need to detect active input state before injecting. Options: (1) Check tmux pane input buffer, (2) Queue messages until prompt detected, (3) Use tmux display-message instead of send-keys for non-intrusive notification, (4) Add visual indicator that message is pending.","design":"Mitigation ideas: 1) Prefer tmux non-intrusive notify: tmux display-message (and always write to inbox/storage) instead of send-keys when user is typing. 2) Gate send-keys injection on 'safe' state: pane idle AND prompt detected AND no partial input; otherwise queue. 3) If queued, show pending count via display-message.","status":"open","priority":1,"issue_type":"bug","created_at":"2025-12-20T21:48:03.280298+01:00","updated_at":"2025-12-20T22:00:04.196161+01:00","dependencies":[{"issue_id":"agent-relay-j9z","depends_on_id":"agent-relay-6rz","type":"blocks","created_at":"2025-12-20T21:48:10.118963+01:00","created_by":"daemon"}]}
+{"id":"ctrl-010","title":"[Control Plane] Code Graph integration","description":"Learn from ai-maestro: visualize codebase as graph (classes, functions, relationships). Delta indexing for performance. Shared context for all agents. Multi-language support.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"agent-relay-v7f","title":"Add conflict detection and resolution","description":"Implement conflict detection when multiple agents work on same files/resources. Add resolution strategies: priority-based, timestamp-based, voting-based. Prevents race conditions in production. Pattern from Claude-Flow's ConflictResolver and OptimisticLockManager.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-23T17:03:34.498546+01:00","updated_at":"2025-12-23T17:03:34.498546+01:00"}
+{"id":"agent-relay-mkz","title":"Fix multi-line message display in dashboard","description":"Multi-line messages are not displaying properly in the dashboard UI. This is a critical UX issue affecting message readability. Need to fix the frontend rendering of message content to properly handle newlines, formatting, and multi-line text.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-25T14:11:25.663841+01:00","updated_at":"2025-12-25T14:25:16.745017+01:00","closed_at":"2025-12-25T14:25:16.745017+01:00"}
+{"id":"agent-relay-6rz","title":"Message injection timing can cause race conditions","description":"In tmux-wrapper.ts:564-569, injection waits for 'idle' (1.5s since last output) but this is fragile. If agent produces output during injection, messages could interleave. Consider: (1) Input buffer detection, (2) Bracketed paste mode, (3) Agent-specific injection strategies.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-20T00:18:17.76865+01:00","updated_at":"2025-12-25T14:31:59.858855+01:00","closed_at":"2025-12-25T14:31:59.858855+01:00"}
+{"id":"hook-006","title":"[Hooks] Document hooks API with examples","description":"Write hooks documentation: pattern syntax, lifecycle events, config file format, programmatic API. Include examples for @memory:, @notify:, @deploy: patterns. Update README.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z"}
+{"id":"agent-relay-kaj","title":"Show project connection status in dashboard (Connected/Reconnecting/Disconnected)","description":"Use onProjectStateChange callbacks from MultiProjectClient to show connection status in dashboard. When onProjectStateChange(id, false) fires, show 'Disconnected' or 'Reconnecting...' indicator. When onProjectStateChange(id, true) fires, show 'Connected'. Could use a status badge in the sidebar or header.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-24T11:51:40.774105+01:00","updated_at":"2025-12-24T11:55:00.944949+01:00","closed_at":"2025-12-24T11:55:00.944949+01:00"}
+{"id":"agent-relay-7b2","title":"CRITICAL: Agents cycling between offline/online status","description":"Dashboard reports agents cycling between offline/online. Root cause analysis: Heartbeat timeout in connection.ts line 230 - if PONG not received within 10 seconds (2x heartbeat interval), connection is killed. This is too aggressive for AI agents that may be processing. Fix: increase timeout tolerance or make configurable. See connection.ts:223-244.","status":"closed","issue_type":"bug","created_at":"2025-12-23T22:57:53.052261+01:00","updated_at":"2025-12-23T23:02:41.925425+01:00","closed_at":"2025-12-23T23:02:41.925425+01:00"}
+{"id":"agent-relay-3tx","title":"PR-9 Review: Document configurable timeouts","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-22T21:54:15.789418+01:00","updated_at":"2025-12-22T21:54:15.789418+01:00"}
+{"id":"agent-relay-6nx","title":"Add activity state tracking for better injection timing","description":"Track active/idle/disconnected state with timestamps. When session goes idle (30s no activity), trigger message injection opportunity. Improves injection timing vs current fixed 1.5s wait. See docs/TMUX_IMPROVEMENTS.md for implementation details.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:28:46.993856+01:00","updated_at":"2025-12-20T21:33:42.223042+01:00","closed_at":"2025-12-20T21:33:42.223042+01:00"}
+{"id":"agent-relay-7mm","title":"Add orphaned tmux session cleanup","description":"When agent-relay wrapper crashes or gets SIGKILL, the tmux session remains. Need: 1) CLI command to gc orphaned sessions, 2) Daemon-side cleanup on client disconnect","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-22T15:52:01.58781+01:00","updated_at":"2025-12-22T15:54:59.840769+01:00","closed_at":"2025-12-22T15:54:59.840769+01:00"}
+{"id":"agent-relay-0bn","title":"Dashboard doesn't show real-time connection status","description":"Dashboard shows agent status from messages but doesn't show live connection status (connected/disconnected). The daemon tracks this in agents.json but dashboard could show online/offline indicators with last-seen timestamps.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:18:04.647965+01:00","updated_at":"2025-12-22T22:07:18.220968+01:00","closed_at":"2025-12-22T22:07:18.220968+01:00"}
+{"id":"agent-relay-2lw","title":"Add agent metadata tracking","description":"Track program, model, task description in agents.json. Better agent discovery.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:36:19.741328+01:00","updated_at":"2025-12-22T17:17:25.919228+01:00","closed_at":"2025-12-22T17:17:25.919228+01:00"}
+{"id":"agent-relay-0uh","title":"Add session discovery for better status output","description":"Auto-discover relay sessions via 'tmux list-sessions'. Filter to relay-* sessions and extract agent names. Enhance 'agent-relay status' command output. See docs/TMUX_IMPROVEMENTS.md for implementation details.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:28:49.058578+01:00","updated_at":"2025-12-20T21:36:23.10406+01:00","closed_at":"2025-12-20T21:36:23.10406+01:00"}
+{"id":"agent-relay-sio","title":"Add graceful degradation when relay daemon is unavailable","description":"In wrapper/tmux-wrapper.ts:195-197, daemon connection failures are silently caught. Consider: (1) Periodic reconnection attempts, (2) Queueing messages for later delivery, (3) Visual indicator in terminal showing connection status.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:17:32.600333+01:00","updated_at":"2025-12-22T17:12:29.892345+01:00","closed_at":"2025-12-22T17:12:29.892345+01:00"}
+{"id":"agent-relay-b11","title":"Cannot scroll in agent tmux window","description":"User unable to scroll in the tmux window when running agent-relay wrapped agents. Need to fix mouse scroll or keyboard scroll behavior.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-23T15:01:55.791186+01:00","updated_at":"2025-12-23T15:04:51.896303+01:00","closed_at":"2025-12-23T15:04:51.896303+01:00"}
+{"id":"agent-relay-hr1","title":"Show project reconnection status in dashboard","description":"Display project connection status (Connected/Reconnecting/Disconnected) in dashboard header. Use onProjectStateChange callbacks from MultiProjectClient to drive 'Connected/Disconnecting' indicators. Show per-project status and overall relay connection health. Color code: green (connected), yellow (reconnecting), red (disconnected).","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-24T11:51:32.74308+01:00","updated_at":"2025-12-24T11:52:22.778492+01:00","closed_at":"2025-12-24T11:52:22.778492+01:00"}
+{"id":"ctrl-001","title":"[Control Plane] Design Control API (REST + WebSocket)","description":"Design API for human control plane: POST /tasks, GET /agents, POST /agents/:id/msg, WS /stream. OpenAPI spec. Authentication endpoints. See ai-maestro's manager/worker pattern for reference.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"hook-008","title":"[Hooks] Implement onSessionStart event","description":"Add onSessionStart hook to TmuxWrapper.start(). Fire after tmux spawn, before polling. Pass HookContext with agentId, sessionId, workingDir. Inject returned text. See HOOKS_API.md lifecycle spec.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z"}
+{"id":"agent-relay-4oy","title":"Fix beads sync prefix mismatch errors","description":"During bd sync, getting 'prefix mismatch detected: database uses agent-relay- but found issues with prefixes: agent- (5 issues)'. Need to investigate and fix the prefix inconsistency or use --rename-on-import flag.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-23T23:10:12.720183+01:00","updated_at":"2025-12-23T23:10:12.720183+01:00"}
+{"id":"agent-relay-aqy","title":"Display cross-project messages with project badge in dashboard","description":"When messages use @project:agent format, display them in the dashboard with a project badge/indicator. Parse project:agent from the 'to' field and render as [ProjectBadge] @AgentName. Depends on agent-relay-cross-project-parser completing first.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-24T10:29:37.528325+01:00","updated_at":"2025-12-24T11:46:39.341486+01:00","closed_at":"2025-12-24T11:46:39.341486+01:00","dependencies":[{"issue_id":"agent-relay-aqy","depends_on_id":"agent-relay-cross-project-parser","type":"blocks","created_at":"2025-12-24T10:29:48.712573+01:00","created_by":"khaliqgant"}]}
+{"id":"agent-relay-8ap","title":"CRITICAL: send command triggers infinite reconnection loop","description":"When sending relay messages to Gem agent, the send command triggers an infinite reconnection loop. Client repeatedly connects with RESUME_TOO_OLD errors, never actually delivers the message. Each connection gets a new session ID and immediately reconnects (~90-110ms apart). This is a critical client/daemon issue, not just Gemini-specific.","notes":"CLI send command removed (keeping surface area small). Root cause still needs investigation - client reconnection loop with RESUME_TOO_OLD errors.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-22T12:18:13.272843+01:00","updated_at":"2025-12-22T14:37:19.435751+01:00","closed_at":"2025-12-22T14:37:19.435751+01:00"}
+{"id":"fed-027","title":"Write federation integration tests","description":"Docker Compose setup for multi-server testing. Test cross-server messaging, reconnection, broadcast. Chaos testing for network partitions.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"hook-002","title":"[Hooks] Implement hook lifecycle events","description":"Add lifecycle events to tmux wrapper: onSessionStart, onSessionEnd, onOutput, onIdle, onMessageReceived. Emit events with HookContext. Allow handlers to inject text. See HOOKS_API.md.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z"}
+{"id":"fed-028","title":"Write federation documentation","description":"Update README with federation quick start. Document configuration options. Add architecture diagrams. Troubleshooting guide.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"fed-014","title":"[Phase 4] Implement message queue for disconnected peers","description":"Create src/federation/message-queue.ts. Bounded queue per peer (max 1000 messages). TTL expiration (1 hour). Flush on reconnect.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"ctrl-008","title":"[Control Plane] Human escalation queue","description":"Queue for decisions needing human input. Agents can escalate with context. Humans respond via any interface (web/mobile/Slack). Response routed back to agent.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"agent-relay-j7y","title":"Implement composer toolbar buttons (bold, emoji)","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-23T16:26:23.598781+01:00","updated_at":"2025-12-23T16:27:53.92751+01:00","closed_at":"2025-12-23T16:27:53.92751+01:00"}
+{"id":"agent-relay-tx9","title":"Add circuit breaker for unresponsive agents","description":"Implement circuit breaker pattern to handle unresponsive or failing agents. Auto-detect agents that stop responding, temporarily remove from routing, attempt recovery, alert on persistent failures. Prevents cascade failures in production. Pattern from Claude-Flow's CircuitBreakerManager.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-23T17:03:48.162055+01:00","updated_at":"2025-12-23T17:03:48.162055+01:00"}
+{"id":"agent-relay-fb3","title":"Add configurable relay prefix for Gemini compatibility","description":"Gemini CLI uses @ for file references, conflicting with @relay:. Add --prefix flag to CLI and relayPrefix config option. Auto-detect CLI type and use appropriate default (\u003e\u003e for Gemini, @relay: for Claude/Codex). Update parser to use dynamic prefix. See docs/TMUX_IMPROVEMENTS.md for full implementation plan.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:28:52.685002+01:00","updated_at":"2025-12-20T21:40:13.066766+01:00","closed_at":"2025-12-20T21:40:13.066766+01:00"}
+{"id":"agent-relay-bx0","title":"Filter stale/internal agents from agents list","description":"agent-relay agents shows __status__ and cli agents which are temporary internal connections. Should filter these out by default, with --all flag to show everything.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-22T15:44:51.944084+01:00","updated_at":"2025-12-22T15:45:44.262049+01:00","closed_at":"2025-12-22T15:45:44.262049+01:00"}
+{"id":"agent-relay-2z1","title":"ACK messages not used for reliability","description":"In connection.ts:114-116, ACK messages are accepted but not processed. The protocol supports reliable delivery with ACK/NACK but it's not implemented. Need to: (1) Track unACKed messages, (2) Implement retry logic, (3) Add configurable TTL for messages.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:17:43.615251+01:00","updated_at":"2025-12-20T21:56:07.202292+01:00","closed_at":"2025-12-20T21:56:07.202292+01:00"}
+{"id":"hook-013","title":"[Hooks] Define HookContext and HookResult types","description":"Create src/hooks/types.ts with HookContext interface (agentId, sessionId, workingDir, env, inject(), send(), memory, relay, output[], messages[]). Define HookResult (inject?, suppress?, stop?). See HOOKS_API.md.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z"}
+{"id":"fed-020","title":"[Phase 5] Add configuration file support","description":"Parse /etc/agent-relay/config.yaml or ~/.agent-relay/config.yaml. Support all federation settings from FEDERATION_PROPOSAL.md Section 12. Environment variable overrides.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"agent-relay-dkx","title":"Add metrics dashboard for system health monitoring","description":"Track agent metrics (throughput, uptime, online status), session lifecycle (active/closed/error rates), and per-agent message counts. Provide Prometheus-format export for monitoring integration. Includes metrics.ts utilities and metrics.html dashboard page.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-25T14:07:28.416696+01:00","updated_at":"2025-12-25T14:07:28.416696+01:00"}
+{"id":"agent-relay-a4k","title":"Add safety mechanisms for dangerous commands","description":"Implement safety layer for dangerous operations (like ACFS's two-person rule). Require confirmation from second agent or human for destructive commands (rm -rf, git push -f, DROP TABLE). Configurable blocklist and approval workflow.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-23T17:05:21.032206+01:00","updated_at":"2025-12-23T17:05:21.032206+01:00"}
+{"id":"agent-relay-52e","title":"Unify bridge view with dashboard UI","description":"Make bridge view feel like the main dashboard with project tabs, same agent/messaging UI, spawn capability at bridge level, and ability to click into individual project dashboards","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-25T13:44:11.491787+01:00","updated_at":"2025-12-25T13:49:36.007645+01:00","closed_at":"2025-12-25T13:49:36.007645+01:00"}
+{"id":"agent-relay-ey9","title":"Dashboard message sending not working","description":"User reports sending messages from dashboard doesn't work. Need to investigate.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-22T15:54:48.975146+01:00","updated_at":"2025-12-22T17:07:48.705786+01:00","closed_at":"2025-12-22T17:07:48.705786+01:00"}
+{"id":"ctrl-006","title":"[Control Plane] iPhone app MVP","description":"React Native or Swift app: fleet status view, task list, agent messaging, push notifications, decision queue with quick actions. Minimal viable version.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"fed-003","title":"[Phase 1] Implement PeerManager","description":"Create src/federation/peer-manager.ts. Manages multiple PeerConnection instances. Connect to configured peers on daemon start. Handle peer discovery from WELCOME messages.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"agent-relay-1t7","title":"Project name display in bridge header","description":"Show selected project name in the bridge interface header for clarity","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-24T11:47:39.531513+01:00","updated_at":"2025-12-24T11:59:16.98688+01:00","closed_at":"2025-12-24T11:59:16.98688+01:00"}
+{"id":"agent-relay-ude","title":"Complete agent-relay-90h backend: detect when agents need input","description":"Frontend for permission indicator is done (needsAttention field, pulsing indicator, badge). Backend needs to detect when agents are waiting for permissions/input and set the needsAttention flag. Could monitor stdin, parse terminal output for permission prompts, or have agents send explicit STATUS messages.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-23T23:10:06.438813+01:00","updated_at":"2025-12-24T11:48:43.798848+01:00","closed_at":"2025-12-24T11:48:43.798848+01:00"}
+{"id":"agent-relay-d2f","title":"Add optional Git audit trail","description":"Commit messages to .agent-relay/messages/ directory. Recoverable history, compliance-friendly.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:36:19.689795+01:00","updated_at":"2025-12-20T21:36:19.689795+01:00"}
 {"id":"agent-relay-kzw","title":"Project namespace uses /tmp which can be cleared on reboot","description":"In utils/project-namespace.ts:13, BASE_DIR is /tmp/agent-relay. On macOS/Linux, /tmp is cleared on reboot, losing all message history. Consider: (1) XDG_DATA_HOME fallback, (2) ~/.agent-relay option, (3) Per-project .agent-relay folder.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T00:18:33.224965+01:00","updated_at":"2025-12-20T00:18:33.224965+01:00"}
-{"id":"agent-relay-l99","title":"Add output filtering for cleaner logs","description":"Filter noisy patterns from logs: thinking indicators [1/418], empty ANSI-only lines, etc. Add config.filterLogs option. See docs/TMUX_IMPROVEMENTS.md for implementation details.","status":"open","priority":4,"issue_type":"feature","created_at":"2025-12-20T21:28:51.199736+01:00","updated_at":"2025-12-20T21:28:51.199736+01:00","dependencies":[{"issue_id":"agent-relay-l99","depends_on_id":"agent-relay-1ek","type":"blocks","created_at":"2025-12-20T21:29:26.987526+01:00","created_by":"daemon"}]}
-{"id":"agent-relay-mcl","title":"Gemini agent cannot send messages properly","description":"Gemini agent cannot autonomously send relay messages. When Gemini outputs @relay: patterns, it enters shell mode instead of being intercepted by the relay wrapper. Manual typing works fine. This suggests a PTY parsing issue specific to how Gemini outputs the @relay: pattern - possibly timing, escaping, or output buffering differences compared to Claude.","status":"closed","priority":2,"issue_type":"bug","assignee":"LeadDev","created_at":"2025-12-20T00:29:15.797552+01:00","updated_at":"2025-12-20T21:56:07.20143+01:00","closed_at":"2025-12-20T21:56:07.20143+01:00"}
-{"id":"agent-relay-oiw","title":"BUG: No per-agent inbox files created","description":"Expected /tmp/agent-relay/\u003cproject\u003e/\u003cagent\u003e/inbox.md but only team/agents.json exists. Agents cannot read their inbox via file.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-20T21:46:24.826442+01:00","updated_at":"2025-12-20T21:46:24.826442+01:00"}
-{"id":"agent-relay-sio","title":"Add graceful degradation when relay daemon is unavailable","description":"In wrapper/tmux-wrapper.ts:195-197, daemon connection failures are silently caught. Consider: (1) Periodic reconnection attempts, (2) Queueing messages for later delivery, (3) Visual indicator in terminal showing connection status.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:17:32.600333+01:00","updated_at":"2025-12-20T00:17:32.600333+01:00"}
+{"id":"ctrl-012","title":"[Control Plane] Agent portability (export/import)","description":"Learn from ai-maestro: export agent as .zip with config, message history, git associations, skills. Import with conflict detection. Enable agent migration between fleets.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"fed-013","title":"[Phase 4] Implement reconnection logic","description":"Add exponential backoff reconnection (1s→2s→4s→...→30s max). Unlimited retry attempts for configured peers. Resume session on reconnect.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"agent-relay-ylf","title":"Add knowledge graph for persistent memory","description":"Implement knowledge graph storage (like Mimir's Neo4j approach) for persistent cross-session context. Store entities, relationships, and semantic embeddings. Enable agents to learn from past sessions and share knowledge. Could use SQLite with FTS5 or optional Neo4j adapter.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-23T17:05:08.367875+01:00","updated_at":"2025-12-23T17:05:08.367875+01:00"}
+{"id":"agent-relay-k8t","title":"Consider backend-focused agent for daemon work","description":"Session retrospective: only had FE-Dev specialist, so backend work (permission detection, daemon issues) fell to Lead. Consider spawning a dedicated backend agent for daemon/server work in future sessions.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-23T23:10:24.756163+01:00","updated_at":"2025-12-23T23:10:24.756163+01:00"}
+{"id":"agent-relay-cw8","title":"Add procedural memory for learned patterns","description":"Implement procedural memory system (like ACFS's cass-memory) to store learned patterns and successful approaches. Agents can query 'how did we solve X before?' Enable cross-session learning and pattern reuse.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-23T17:05:14.667585+01:00","updated_at":"2025-12-23T17:05:14.667585+01:00"}
+{"id":"agent-relay-4e0","title":"Fix message truncation - messages cut off at source","description":"Root cause found: parser.ts:40 inline regex only captures single line. Multi-line messages are split by parsePassThrough() at line 206. Fix options: (1) Allow continuation lines in inline format, (2) Use block format for multi-line, (3) Add heuristic to join lines until next @relay pattern.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-19T23:40:35.082717+01:00","updated_at":"2025-12-20T00:03:54.806087+01:00","closed_at":"2025-12-20T00:03:54.806087+01:00"}
+{"id":"agent-relay-bei","title":"Gemini (CleverBeacon) bash syntax errors - unexpected EOF","description":"Gemini agent gets bash errors: 'unexpected EOF while looking for matching quote' and 'syntax error: unexpected end of file' when running shell commands. Possibly related to quote escaping in the relay wrapper.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-19T23:40:36.464079+01:00","updated_at":"2025-12-19T23:45:46.05609+01:00","closed_at":"2025-12-19T23:45:46.05609+01:00"}
+{"id":"fed-017","title":"[Phase 4] CLI: agent-relay peer status","description":"Add peer subcommands: list, add, remove, status. Show connection state, latency, agent count, last seen.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"ctrl-007","title":"[Control Plane] Slack/Discord bot integration","description":"Bot for team chat: /fleet status, /assign task agent, @mentions for escalations, threaded replies for agent questions. Webhook-based notifications.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"agent-relay-7tk","title":"Dashboard truncates multi-line messages","description":"Messages containing line breaks only show the first line in the dashboard. Need to render newlines properly - either with CSS white-space or by converting newlines to \u003cbr\u003e tags.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-23T23:05:03.86361+01:00","updated_at":"2025-12-23T23:05:59.96346+01:00","closed_at":"2025-12-23T23:05:59.96346+01:00"}
+{"id":"agent-relay-4jv","title":"Add session discovery from existing Claude Code","description":"Auto-discover and import existing Claude Code sessions (like Maestro). Detect running claude processes, offer to wrap them with agent-relay messaging. Reduces friction for adoption - users don't have to restart their agents.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-23T17:05:01.003851+01:00","updated_at":"2025-12-23T17:05:01.003851+01:00"}
+{"id":"agent-relay-kto","title":"Add topic-based pub/sub messaging","description":"Add topic subscription alongside direct addressing. Agents can subscribe to topics (e.g., 'errors', 'deploys', 'reviews') and receive all messages on those topics. Complements existing -\u003erelay:Name with -\u003erelay:#topic pattern. Pattern from Claude-Flow's message bus.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-23T17:05:27.213842+01:00","updated_at":"2025-12-23T17:05:27.213842+01:00"}
+{"id":"agent-relay-0g4","title":"Add agent portability (export/import)","description":"Enable exporting agent state and history as portable packages (like AI Maestro's .zip export). Include conversation history, learned patterns, configuration. Enables agent migration between machines and backup/restore workflows.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-23T17:04:41.847187+01:00","updated_at":"2025-12-23T17:04:41.847187+01:00"}
+{"id":"fed-016","title":"[Phase 4] Implement graceful shutdown (PEER_BYE)","description":"Send PEER_BYE on daemon shutdown. Remove agents from fleet registry. Allow queued messages to be sent before disconnect.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"agent-relay-f3q","title":"Make msg-read a subcommand of send or message","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-19T21:59:55.123772+01:00","updated_at":"2025-12-19T22:04:51.112763+01:00","closed_at":"2025-12-19T22:04:51.112763+01:00"}
+{"id":"agent-relay-1ie","title":"Fix Gemini CLI message injection and handling","description":"Investigate and fix issues where Gemini agent messages are not being correctly picked up by the tmux-wrapper. Ensure the special printf injection path is working and that standard LLM output is captured correctly.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-22T12:11:57.073531+01:00","updated_at":"2025-12-22T12:17:27.434451+01:00","closed_at":"2025-12-22T12:17:27.434456+01:00"}
+{"id":"agent-relay-i5f","title":"Fix rendering and display issues","description":"Relay messages display with garbled/overlapping text in terminal. Characters appear scattered and mixed with other terminal content. Example: message text like 'Ping me when you're ready' renders with letters displaced across the line. PR #10 added input detection (isInputClear, waitForClearInput, getCursorX) to prevent this, but it's not working effectively. Need to investigate why the input detection/wait logic isn't preventing message injection during active typing.","notes":"Parser improvements for continuation lines (bullets, numbered lists, box drawing chars for Gemini). Debug flag set to false.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-22T11:59:53.254169+01:00","updated_at":"2025-12-22T14:21:32.043374+01:00","closed_at":"2025-12-22T14:21:32.043374+01:00"}
+{"id":"fed-026a","title":"[Transport] Define PeerTransport interface","description":"Create src/federation/transport.ts with PeerTransport interface: connect(), disconnect(), send(), broadcast(), subscribe(), getConnectedPeers(). WebSocketTransport as default implementation. See FEDERATION_PROPOSAL.md Section 11.2.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T13:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"hook-005","title":"[Hooks] Programmatic hook API","description":"Export Relay class with pattern() and on() methods. Allow programmatic registration of handlers. TypeScript types for HookContext, PatternHandler. See HOOKS_API.md.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z"}
+{"id":"agent-relay-4xs","title":"Dashboard: Enter to send, Shift+Enter for newline (Slack-style)","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-24T15:25:01.248707+01:00","updated_at":"2025-12-24T15:26:24.619384+01:00","closed_at":"2025-12-24T15:26:24.619384+01:00"}
+{"id":"agent-relay-aq2","title":"Implement agent-to-agent spawning via relay","description":"Allow agents to spawn new agents through relay messaging. Enable -\u003erelay:spawn pattern so agents can dynamically create specialized sub-agents. This unblocks multi-agent workflows and team hierarchies.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-25T14:14:02.110506+01:00","updated_at":"2025-12-25T14:32:10.400627+01:00","closed_at":"2025-12-25T14:32:10.400627+01:00"}
+{"id":"agent-relay-tun","title":"Debug output leaking to terminal during relay message send","description":"When sending relay messages (observed with relay:Gem), debug output is leaking to the terminal repeatedly. Output shows: 'relay:Gem] isInputClear: lastLine=\"\" ~/.../agent-relay (main*)' and 'ear=false' (truncated 'isInputClear=false'). Lines are split/corrupted and repeating in a loop. Likely issue in the tmux wrapper or message injection code where debug logging isn't being suppressed properly.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-22T13:40:28.576361+01:00","updated_at":"2025-12-22T13:42:16.746166+01:00","closed_at":"2025-12-22T13:42:16.746166+01:00"}
+{"id":"agent-relay-8ff","title":"Add agent list command to CLI","description":"CLI has up/down/status/read but no way to list connected agents or see message history from command line. Add: (1) agent-relay agents - list connected agents, (2) agent-relay history - show recent messages, (3) agent-relay send \u003cagent\u003e \u003cmsg\u003e - send from CLI.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-20T00:18:34.400432+01:00","updated_at":"2025-12-22T15:35:44.695605+01:00","closed_at":"2025-12-22T15:35:44.695605+01:00"}
+{"id":"fed-022","title":"[Phase 5] Implement delivery confirmation","description":"Add DELIVERY_CONFIRMED message type. Detect injection via capture-pane. Send confirmation back to sender. Optional sender notification. See FEDERATION_PROPOSAL.md Section 7.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z"}
+{"id":"agent-relay-f9k","title":"Fix WebSocket Invalid frame header error","description":"Dashboard WebSocket throws Invalid frame header with 415KB payload. Missing wss.on('connection') handler causes race condition.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-23T17:17:26.412812+01:00","updated_at":"2025-12-23T17:18:30.4994+01:00","closed_at":"2025-12-23T17:18:30.4994+01:00"}
+{"id":"agent-relay-blj","title":"Add metrics and observability endpoint","description":"Add metrics collection and observability for production monitoring. Include: message throughput, agent health, latency percentiles, error rates, queue depths. Expose via HTTP endpoint (Prometheus format) and/or dashboard integration. Currently flying blind in production.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-23T17:03:41.964359+01:00","updated_at":"2025-12-25T13:33:56.132695+01:00","closed_at":"2025-12-25T13:33:56.132695+01:00"}
+{"id":"agent-relay-ghy","title":"Team config: auto-spawn agents or auto-assign names from teams.json","description":"When a project has a teams.json config file, agent-relay up should either:\n\n1. **Auto-spawn option**: Automatically kick off terminal sessions for each agent defined in teams.json\n2. **Auto-assign option**: When users manually start sessions with `agent-relay -n \u003cname\u003e claude`, validate the name against teams.json and auto-assign roles/permissions\n\n## teams.json format\n```json\n{\n  \"team\": \"my-project\",\n  \"agents\": [\n    {\"name\": \"Coordinator\", \"cli\": \"claude\", \"role\": \"coordinator\"},\n    {\"name\": \"LeadDev\", \"cli\": \"claude\", \"role\": \"developer\"},\n    {\"name\": \"Reviewer\", \"cli\": \"claude\", \"role\": \"reviewer\"}\n  ],\n  \"autoSpawn\": false\n}\n```\n\n## Behavior\n- If `autoSpawn: true`, `agent-relay up` spawns tmux sessions for each agent\n- If `autoSpawn: false`, validate names against config when agents connect\n- Store teams.json in project root or .agent-relay/teams.json\n\n## Commands\n- `agent-relay up --spawn` - force spawn all agents\n- `agent-relay up --no-spawn` - just start daemon, manual agent starts","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-19T23:13:02.482971+01:00","updated_at":"2025-12-22T22:11:38.639588+01:00"}
+{"id":"mem-003","title":"[Memory] Build task-based trajectory layer on Mem0","description":"Implement trajectory grouping on top of Mem0 observations. Map task_id to Mem0 user_id or metadata. Support chapter-based organization within trajectories.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z"}
+{"id":"ctrl-005","title":"[Control Plane] Push notification service","description":"Real-time notifications to mobile/web: APNs for iOS, FCM for Android/web. Notify on: task completion, agent questions, escalations, errors.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"ctrl-011","title":"[Control Plane] Agent health monitoring","description":"Like ai-maestro's green/red/yellow status: heartbeat checks, resource usage, error rates, stuck detection. Alert on degradation. Auto-recovery actions.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z"}
+{"id":"agent-relay-bai","title":"Fix bridge reconnection loop caused by agent name conflict","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-25T13:26:46.025963+01:00","updated_at":"2025-12-25T13:27:04.323001+01:00","closed_at":"2025-12-25T13:27:04.323001+01:00"}
+{"id":"agent-relay-ruv","title":"Add work stealing for load balancing","description":"Implement work stealing so idle agents can claim tasks from overloaded peers. Key production feature for better resource utilization. Pattern from Claude-Flow's WorkStealingCoordinator. Requires task queue visibility and agent load metrics.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-23T17:03:28.153623+01:00","updated_at":"2025-12-23T17:03:28.153623+01:00"}
+{"id":"agent-relay-6ny","title":"Fix message truncation: store full message in SQLite first, include ID in relay","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-19T22:04:36.168862+01:00","updated_at":"2025-12-19T22:08:28.207532+01:00","closed_at":"2025-12-19T22:08:28.207532+01:00"}
+{"id":"agent-relay-eek","title":"Change relay prefix from @relay to \u003e\u003erelay","description":"Unify the relay protocol prefix to \u003e\u003erelay (instead of @relay) so it works for all agents including Gemini. Update parser, documentation, and any hardcoded references.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-22T12:20:35.35848+01:00","updated_at":"2025-12-22T12:30:21.696239+01:00","closed_at":"2025-12-22T12:30:21.696239+01:00"}
+{"id":"agent-relay-v57","title":"No message expiration/cleanup in SQLite storage","description":"SQLite adapter has no TTL or cleanup mechanism for old messages. Over time, the database will grow unbounded. Add: (1) Configurable message retention period, (2) Automatic cleanup job, (3) Index on ts column is there but no cleanup uses it.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-20T00:18:01.86766+01:00","updated_at":"2025-12-22T17:17:41.867951+01:00","closed_at":"2025-12-22T17:17:41.867951+01:00"}
+{"id":"fed-010","title":"[Phase 3] Implement PEER_BROADCAST handling","description":"Handle incoming PEER_BROADCAST messages. Deliver to all local agents except excluded. Support scope (fleet vs server).","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"hook-001","title":"[Hooks] Implement pattern namespace registry","description":"Create src/hooks/pattern-registry.ts. Register pattern handlers by namespace (@relay:, @memory:, @custom:). Match output against patterns. Route to handlers. Support built-in and user-defined namespaces. See HOOKS_API.md.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z"}
+{"id":"hook-012","title":"[Hooks] Implement onMessageReceived event","description":"Add onMessageReceived hook to TmuxWrapper.handleIncomingMessage(). Fire before injection. Allow suppress or custom inject. Pass RelayMessage and context. See HOOKS_API.md lifecycle spec.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z"}
+{"id":"agent-relay-rm7","title":"Add scheduling strategies for task distribution","description":"Implement scheduling strategies for distributing tasks across agents. Start with round-robin, then add capability-based, least-loaded, and affinity strategies. Inspired by Claude-Flow's 4-strategy approach. Enables autonomous task assignment instead of manual coordination.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-23T17:03:22.014068+01:00","updated_at":"2025-12-23T17:03:22.014068+01:00"}
+{"id":"agent-relay-n36","title":"Add metrics dashboard for system health monitoring","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-25T14:07:36.499133+01:00","updated_at":"2025-12-25T14:07:36.499133+01:00"}
+{"id":"agent-relay-7tu","title":"Fix storage portability: better-sqlite3 native binding failures","description":"The read command fails in some Node versions (e.g., Node 25) due to missing better-sqlite3 bindings. Decide path: pin supported Node LTS + ensure rebuild, or replace with a non-native option (e.g., Node sqlite, wasm, or a pure JS adapter).","notes":"Implemented sqlite portability: dynamic better-sqlite3 import + fallback to node:sqlite (env override AGENT_RELAY_SQLITE_DRIVER). Updated sqlite adapter to use positional params for compatibility; added/updated tests; npx vitest run passes (216).","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-20T21:44:57.868091+01:00","updated_at":"2025-12-20T21:56:13.384399+01:00","closed_at":"2025-12-20T21:56:13.3844+01:00"}
+{"id":"agent-relay-wsd","title":"URGENT: Gemini interprets relay messages as shell commands","status":"closed","issue_type":"bug","created_at":"2025-12-22T14:23:05.989732+01:00","updated_at":"2025-12-22T14:24:18.714626+01:00","closed_at":"2025-12-22T14:24:18.714626+01:00"}
+{"id":"fed-002","title":"[Phase 1] Implement PeerConnection class","description":"Create src/federation/peer-connection.ts. WebSocket connection to single peer with state machine (DISCONNECTED→CONNECTING→HANDSHAKING→ACTIVE→RECONNECTING). Handle HELLO/WELCOME handshake. See FEDERATION_PROPOSAL.md Section 4.6.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"agent-relay-ujq","title":"Add @-mention autocomplete in chat input","description":"When typing @ in the chat input, show autocomplete dropdown with available agent names. Tab to complete selection, arrow keys to navigate through options. Should filter as user types after @.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-24T08:01:03.793267+01:00","updated_at":"2025-12-24T08:02:51.638981+01:00","closed_at":"2025-12-24T08:02:51.638981+01:00"}
+{"id":"agent-relay-9kw","title":"Add multi-machine agent support","description":"Enable agents to run across multiple machines with centralized coordination. AI Maestro scales to 100+ agents across machines. Extend bridge mode to support remote daemon connections over TCP/WebSocket. Critical for scaling beyond single machine.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-23T17:04:35.521241+01:00","updated_at":"2025-12-23T17:04:35.521241+01:00"}
+{"id":"agent-relay-ahe","title":"Session resume not implemented - RESUME_TOO_OLD always sent","description":"In connection.ts:140-143, session resume tokens are received but not persisted or validated. The server always responds with RESUME_TOO_OLD. This breaks the resume capability advertised in the protocol. Need to implement token persistence and session state recovery.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-20T00:17:30.605649+01:00","updated_at":"2025-12-22T15:31:05.795905+01:00","closed_at":"2025-12-22T15:31:05.795905+01:00"}
+{"id":"agent-relay-hgn","title":"Agent team hierarchies with specialized sub-agents","description":"Each main agent should be able to spawn and coordinate a team of specialized sub-agents:\n\n- **Lead** → Operations Consultant (monitors behavior, provides retrospective feedback on coordination)\n- **Implementer** → Code Reviewer (reviews code before commits, suggests improvements)\n- **Designer** → UX Reviewer (validates design decisions)\n- **Architect** → Security Auditor (checks for vulnerabilities)\n\nImplementation ideas:\n1. Define agent profiles with 'team' configurations in .claude/agents/\n2. When an agent starts, it can auto-spawn its team members\n3. Sub-agents monitor the parent agent's work and provide feedback\n4. At session end, sub-agents provide retrospective summaries\n5. Use -\u003erelay:spawn to create sub-agents with specific roles\n\nThis enables each agent to have a dedicated support team for quality assurance and improvement.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-23T15:03:56.608847+01:00","updated_at":"2025-12-23T15:03:56.608847+01:00"}
+{"id":"agent-relay-dd8","title":"Add file reservation system (from mcp_agent_mail)","description":"Advisory locks with TTL, @relay:lock pattern, pre-commit hook integration. Critical for multi-agent file editing.","notes":"No progress today; added as future work from swarm-mail comparison: implement reservations/locks with TTL + conflict detection. See swarm-mail reservations + locks patterns.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-20T21:36:19.573504+01:00","updated_at":"2025-12-20T22:00:37.608017+01:00"}
+{"id":"mem-001","title":"[Memory] Integrate Mem0 as memory substrate","description":"Add Mem0 dependency to agent-trajectories. Implement MemoryBackend interface wrapping Mem0 SDK. Support both self-hosted and cloud Mem0. See MEMORY_STACK_DECISION.md for architecture.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z"}
+{"id":"fed-021","title":"[Phase 5] Update dashboard for fleet view","description":"Add fleet view toggle to dashboard. Show agents from all servers with server badge. Show peer connection status. Real-time updates via existing WebSocket.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z"}
+{"id":"agent-relay-9kc","title":"Add skip-permissions flag for spawned Claude agents","description":"When spawning Claude agents via agent-relay, automatically use --dangerously-skip-permissions to avoid permission dialog delays. Update spawn command in CLI to pass this flag to spawned sessions.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-25T14:09:00.07082+01:00","updated_at":"2025-12-25T14:15:45.925839+01:00","closed_at":"2025-12-25T14:15:45.925839+01:00"}
+{"id":"agent-relay-3y1","title":"Fix dashboard auto-scroll interfering with manual scrolling","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-24T15:09:41.112636+01:00","updated_at":"2025-12-24T15:10:59.748796+01:00","closed_at":"2025-12-24T15:10:59.748796+01:00"}
 {"id":"agent-relay-ucw","title":"Dashboard: multi-project navigation or dynamic port allocation","description":"When the dashboard is already running for one project, users should be able to either: (1) Navigate between different projects in a single dashboard view, OR (2) Start a new dashboard instance on an automatically allocated available port for a different project. Currently if a dashboard is running, starting another project conflicts.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-19T23:40:18.667766+01:00","updated_at":"2025-12-20T00:18:05.10495+01:00","closed_at":"2025-12-20T00:18:05.10495+01:00"}
-{"id":"agent-relay-v57","title":"No message expiration/cleanup in SQLite storage","description":"SQLite adapter has no TTL or cleanup mechanism for old messages. Over time, the database will grow unbounded. Add: (1) Configurable message retention period, (2) Automatic cleanup job, (3) Index on ts column is there but no cleanup uses it.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-20T00:18:01.86766+01:00","updated_at":"2025-12-20T00:18:01.86766+01:00"}
-{"id":"fed-003","title":"[Phase 1] Implement PeerManager","description":"Create src/federation/peer-manager.ts. Manages multiple PeerConnection instances. Connect to configured peers on daemon start. Handle peer discovery from WELCOME messages.","status":"open","priority":1,"issue_type":"task","assignee":"Network","depends_on":["fed-002"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-1"]}
-{"id":"fed-004","title":"[Phase 1] Add peer WebSocket listener to daemon","description":"Extend daemon to listen for incoming peer connections on configurable port (default 8765). Accept connections, perform handshake, register with PeerManager.","status":"open","priority":1,"issue_type":"task","assignee":"Network","depends_on":["fed-003"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-1"]}
-{"id":"fed-005","title":"[Phase 2] Implement FleetRegistry","description":"Create src/federation/registry.ts with FleetRegistry class. Track agents across fleet with agentToServer mapping. Support fleet-wide unique name enforcement with quorum registration. See FEDERATION_PROPOSAL.md Section 5.","status":"open","priority":1,"issue_type":"task","assignee":"Router","depends_on":["fed-004"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-2"]}
-{"id":"fed-006","title":"[Phase 2] Implement PEER_SYNC message handling","description":"Handle agent_joined, agent_left, full_sync message types. Update FleetRegistry on sync. Trigger sync on new peer connection and periodically (60s).","status":"open","priority":1,"issue_type":"task","assignee":"Router","depends_on":["fed-005"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-2"]}
-{"id":"fed-007","title":"[Phase 2] Implement name resolution","description":"Add resolve() method to FleetRegistry. Support patterns: Bob (local-first then fleet), Bob@server (explicit), *@server (broadcast to server). See FEDERATION_PROPOSAL.md Section 5.2.","status":"open","priority":1,"issue_type":"task","assignee":"Router","depends_on":["fed-006"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-2"]}
-{"id":"fed-008","title":"[Phase 2] CLI: agent-relay agents --fleet","description":"Add --fleet flag to agents command. Query FleetRegistry for all agents across servers. Display server, CLI, status, connected_at columns.","status":"open","priority":2,"issue_type":"task","assignee":"CLI","depends_on":["fed-005"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-2","cli"]}
-{"id":"fed-009","title":"[Phase 3] Implement PEER_ROUTE handling","description":"Handle incoming PEER_ROUTE messages. Extract target agent, look up in local registry, deliver via existing tmux send-keys injection. Preserve automatic delivery magic.","status":"open","priority":1,"issue_type":"task","assignee":"Router","depends_on":["fed-007"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-3"]}
-{"id":"fed-010","title":"[Phase 3] Implement PEER_BROADCAST handling","description":"Handle incoming PEER_BROADCAST messages. Deliver to all local agents except excluded. Support scope (fleet vs server).","status":"open","priority":1,"issue_type":"task","assignee":"Router","depends_on":["fed-009"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-3"]}
-{"id":"fed-015","title":"[Phase 4] Implement heartbeat (PING/PONG)","description":"Send PEER_PING every 30s. Expect PEER_PONG within 60s. Trigger reconnect on timeout. Track latency_ms in ServerRecord.","status":"open","priority":1,"issue_type":"task","assignee":"Network","depends_on":["fed-013"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-4"]}
-{"id":"fed-016","title":"[Phase 4] Implement graceful shutdown (PEER_BYE)","description":"Send PEER_BYE on daemon shutdown. Remove agents from fleet registry. Allow queued messages to be sent before disconnect.","status":"open","priority":2,"issue_type":"task","assignee":"Network","depends_on":["fed-015"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-4"]}
-{"id":"fed-017","title":"[Phase 4] CLI: agent-relay peer status","description":"Add peer subcommands: list, add, remove, status. Show connection state, latency, agent count, last seen.","status":"open","priority":2,"issue_type":"task","assignee":"CLI","depends_on":["fed-015"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-4","cli"]}
-{"id":"fed-020","title":"[Phase 5] Add configuration file support","description":"Parse /etc/agent-relay/config.yaml or ~/.agent-relay/config.yaml. Support all federation settings from FEDERATION_PROPOSAL.md Section 12. Environment variable overrides.","status":"open","priority":1,"issue_type":"task","assignee":"CLI","depends_on":["fed-016"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-5","cli"]}
-{"id":"fed-021","title":"[Phase 5] Update dashboard for fleet view","description":"Add fleet view toggle to dashboard. Show agents from all servers with server badge. Show peer connection status. Real-time updates via existing WebSocket.","status":"open","priority":2,"issue_type":"task","assignee":"CLI","depends_on":["fed-008"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-5","dashboard"]}
-{"id":"fed-024","title":"[Storage] Implement trajectory storage adapter","description":"Create TrajectoryStorageAdapter interface. File system backend (default). SQLite backend for local queries. See FEDERATION_PROPOSAL.md Section 17 and Trajectories Proposal.","status":"open","priority":2,"issue_type":"task","assignee":"Storage","created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","storage","trajectories"]}
-{"id":"fed-025","title":"[Storage] Implement central trajectory sync","description":"PostgreSQL backend for team sharing. Sync on task complete. Conflict resolution (server-wins default). See FEDERATION_PROPOSAL.md Section 17.3.","status":"open","priority":3,"issue_type":"task","assignee":"Storage","depends_on":["fed-024"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","storage","trajectories"]}
-{"id":"fed-001","title":"[Phase 1] Define peer protocol types","description":"Create src/protocol/peer-types.ts with PeerMessageType, PeerEnvelope, PeerHelloPayload, PeerWelcomePayload, PeerSyncPayload, PeerRoutePayload, PeerBroadcastPayload. See FEDERATION_PROPOSAL.md Section 4.","status":"open","priority":1,"issue_type":"task","assignee":"Architect","collaborators":["Network"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","phase-1"]}
-{"id":"fed-011","title":"[Phase 3] Integrate FederatedRouter with existing Router","description":"Modify existing Router to check FleetRegistry for remote agents. Route to PeerManager for cross-server delivery. Keep local delivery path unchanged.","status":"open","priority":1,"issue_type":"task","assignee":"Router","collaborators":["Network"],"depends_on":["fed-010"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","phase-3"]}
-{"id":"fed-012","title":"[Phase 3] Implement loop prevention","description":"Add hops array to PEER_ROUTE messages. Check for loops before forwarding. Drop messages that have already visited this server. Note: Can be implemented as part of fed-009/010.","status":"open","priority":3,"issue_type":"task","assignee":"Router","depends_on":["fed-009"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","phase-3","can-merge"]}
-{"id":"fed-014","title":"[Phase 4] Implement message queue for disconnected peers","description":"Create src/federation/message-queue.ts. Bounded queue per peer (max 1000 messages). TTL expiration (1 hour). Flush on reconnect.","status":"open","priority":1,"issue_type":"task","assignee":"Storage","collaborators":["Network"],"depends_on":["fed-004"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","phase-4","storage"]}
-{"id":"fed-018","title":"[Phase 5] Add TLS support for peer connections","description":"Configure wss:// with cert/key/ca paths. Support mutual TLS (mTLS) optionally. Reject non-TLS in production mode.","status":"open","priority":1,"issue_type":"task","assignee":"Security","collaborators":["Network"],"depends_on":["fed-016"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","phase-5","security"]}
-{"id":"fed-022","title":"[Phase 5] Implement delivery confirmation","description":"Add DELIVERY_CONFIRMED message type. Detect injection via capture-pane. Send confirmation back to sender. Optional sender notification. See FEDERATION_PROPOSAL.md Section 7.","status":"open","priority":2,"issue_type":"task","assignee":"Router","collaborators":["Network"],"depends_on":["fed-011"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","phase-5"]}
-{"id":"fed-026a","title":"[Transport] Define PeerTransport interface","description":"Create src/federation/transport.ts with PeerTransport interface: connect(), disconnect(), send(), broadcast(), subscribe(), getConnectedPeers(). WebSocketTransport as default implementation. See FEDERATION_PROPOSAL.md Section 11.2.","status":"open","priority":2,"issue_type":"task","assignee":"Architect","collaborators":["Network"],"depends_on":["fed-023"],"created_at":"2025-12-21T13:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","transport"]}
-{"id":"fed-026","title":"[Transport] Implement NATS transport adapter","description":"Create NatsTransport implementing PeerTransport interface. JetStream for persistence. Subject-based routing. See FEDERATION_PROPOSAL.md Section 11.4.","status":"open","priority":3,"issue_type":"task","assignee":"Network","depends_on":["fed-026a"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","nats","optional"]}
-{"id":"fed-027","title":"Write federation integration tests","description":"Docker Compose setup for multi-server testing. Test cross-server messaging, reconnection, broadcast. Chaos testing for network partitions.","status":"open","priority":2,"issue_type":"task","assignee":"Architect","collaborators":["Network","Router"],"depends_on":["fed-022"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","testing"]}
-{"id":"fed-002","title":"[Phase 1] Implement PeerConnection class","description":"Create src/federation/peer-connection.ts. WebSocket connection to single peer with state machine (DISCONNECTED→CONNECTING→HANDSHAKING→ACTIVE→RECONNECTING). Handle HELLO/WELCOME handshake. See FEDERATION_PROPOSAL.md Section 4.6.","status":"open","priority":1,"issue_type":"task","assignee":"Network","depends_on":["fed-001"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-1"]}
-{"id":"fed-013","title":"[Phase 4] Implement reconnection logic","description":"Add exponential backoff reconnection (1s→2s→4s→...→30s max). Unlimited retry attempts for configured peers. Resume session on reconnect.","status":"open","priority":1,"issue_type":"task","assignee":"Network","depends_on":["fed-011"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","phase-4"]}
-{"id":"fed-019","title":"[Phase 5] Implement Ed25519 authentication","description":"Generate server keypair on first run. Challenge-response handshake. Sign all peer messages. Verify signatures on receive. See FEDERATION_PROPOSAL.md Section 8.1-8.3.","status":"open","priority":1,"issue_type":"task","assignee":"Security","collaborators":["Architect"],"depends_on":["fed-018"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","phase-5","security"]}
-{"id":"fed-023","title":"[Phase 5] Implement flow control","description":"Add credit-based flow control per peer. PEER_ACK to replenish credits. PEER_BUSY/PEER_READY for backpressure. Rate limiting. See FEDERATION_PROPOSAL.md Section 9.","status":"open","priority":2,"issue_type":"task","assignee":"Network","collaborators":["Storage"],"depends_on":["fed-014"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T13:00:00Z","labels":["federation","phase-5"]}
-{"id":"fed-028","title":"Write federation documentation","description":"Update README with federation quick start. Document configuration options. Add architecture diagrams. Troubleshooting guide.","status":"open","priority":2,"issue_type":"task","assignee":"Architect","depends_on":["fed-027"],"created_at":"2025-12-21T12:00:00Z","updated_at":"2025-12-21T12:00:00Z","labels":["federation","docs"]}
-{"id":"ctrl-001","title":"[Control Plane] Design Control API (REST + WebSocket)","description":"Design API for human control plane: POST /tasks, GET /agents, POST /agents/:id/msg, WS /stream. OpenAPI spec. Authentication endpoints. See ai-maestro's manager/worker pattern for reference.","status":"open","priority":2,"issue_type":"task","assignee":"Architect","collaborators":["CLI"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","api"]}
-{"id":"ctrl-002","title":"[Control Plane] Implement Lead Agent orchestration","description":"Lead Agent receives human intent, breaks into tasks, assigns to specialized agents based on skills, monitors progress, escalates decisions. Can be AI-powered or rule-based initially.","status":"open","priority":2,"issue_type":"task","assignee":"Router","collaborators":["Architect"],"depends_on":["ctrl-001","fed-011"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","orchestration"]}
-{"id":"ctrl-003","title":"[Control Plane] Build web dashboard v2 (fleet control)","description":"Next.js dashboard with: fleet overview, task assignment UI, agent status cards, trajectory viewer, decision queue. Learn from ai-maestro's hierarchical naming and color coding.","status":"open","priority":2,"issue_type":"task","assignee":"CLI","depends_on":["ctrl-001","fed-021"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","dashboard"]}
-{"id":"ctrl-004","title":"[Control Plane] Human authentication (OAuth/magic link)","description":"Secure human access to control plane. OAuth2 (GitHub/Google) or magic link email auth. JWT tokens for API access. Role-based permissions (admin/operator/viewer).","status":"open","priority":2,"issue_type":"task","assignee":"Security","depends_on":["ctrl-001"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","security"]}
-{"id":"ctrl-005","title":"[Control Plane] Push notification service","description":"Real-time notifications to mobile/web: APNs for iOS, FCM for Android/web. Notify on: task completion, agent questions, escalations, errors.","status":"open","priority":3,"issue_type":"task","assignee":"Network","depends_on":["ctrl-001"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","notifications"]}
-{"id":"ctrl-006","title":"[Control Plane] iPhone app MVP","description":"React Native or Swift app: fleet status view, task list, agent messaging, push notifications, decision queue with quick actions. Minimal viable version.","status":"open","priority":3,"issue_type":"task","assignee":"CLI","collaborators":["Architect"],"depends_on":["ctrl-003","ctrl-005"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","mobile"]}
-{"id":"ctrl-007","title":"[Control Plane] Slack/Discord bot integration","description":"Bot for team chat: /fleet status, /assign task agent, @mentions for escalations, threaded replies for agent questions. Webhook-based notifications.","status":"open","priority":3,"issue_type":"task","assignee":"CLI","depends_on":["ctrl-001"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","integrations"]}
-{"id":"ctrl-008","title":"[Control Plane] Human escalation queue","description":"Queue for decisions needing human input. Agents can escalate with context. Humans respond via any interface (web/mobile/Slack). Response routed back to agent.","status":"open","priority":2,"issue_type":"task","assignee":"Router","collaborators":["CLI"],"depends_on":["ctrl-002"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","escalation"]}
-{"id":"ctrl-009","title":"[Control Plane] Agent skills registry","description":"Track agent capabilities: skills map (Network→websocket,tcp,tls), availability, current workload, performance history. Used by Lead Agent for smart assignment.","status":"open","priority":2,"issue_type":"task","assignee":"Router","depends_on":["fed-005"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","registry"]}
-{"id":"ctrl-010","title":"[Control Plane] Code Graph integration","description":"Learn from ai-maestro: visualize codebase as graph (classes, functions, relationships). Delta indexing for performance. Shared context for all agents. Multi-language support.","status":"open","priority":3,"issue_type":"task","assignee":"Storage","collaborators":["Architect"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","intelligence"]}
-{"id":"ctrl-011","title":"[Control Plane] Agent health monitoring","description":"Like ai-maestro's green/red/yellow status: heartbeat checks, resource usage, error rates, stuck detection. Alert on degradation. Auto-recovery actions.","status":"open","priority":2,"issue_type":"task","assignee":"Network","depends_on":["fed-015"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","monitoring"]}
-{"id":"ctrl-012","title":"[Control Plane] Agent portability (export/import)","description":"Learn from ai-maestro: export agent as .zip with config, message history, git associations, skills. Import with conflict detection. Enable agent migration between fleets.","status":"open","priority":3,"issue_type":"task","assignee":"Storage","depends_on":["fed-024"],"created_at":"2025-12-21T14:00:00Z","updated_at":"2025-12-21T14:00:00Z","labels":["control-plane","portability"]}
-{"id":"mem-001","title":"[Memory] Integrate Mem0 as memory substrate","description":"Add Mem0 dependency to agent-trajectories. Implement MemoryBackend interface wrapping Mem0 SDK. Support both self-hosted and cloud Mem0. See MEMORY_STACK_DECISION.md for architecture.","status":"open","priority":1,"issue_type":"task","assignee":"Storage","created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z","labels":["memory","mem0","agent-trajectories"]}
-{"id":"mem-002","title":"[Memory] Configure Mem0 MCP for Claude Code agents","description":"Add MCP configuration for Mem0 integration with Claude Code. Document setup in agent-relay README. Test memory persistence across sessions.","status":"open","priority":2,"issue_type":"task","assignee":"CLI","depends_on":["mem-001"],"created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z","labels":["memory","mcp","claude-code"]}
-{"id":"mem-003","title":"[Memory] Build task-based trajectory layer on Mem0","description":"Implement trajectory grouping on top of Mem0 observations. Map task_id to Mem0 user_id or metadata. Support chapter-based organization within trajectories.","status":"open","priority":1,"issue_type":"task","assignee":"Storage","collaborators":["Architect"],"depends_on":["mem-001"],"created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z","labels":["memory","trajectories","agent-trajectories"]}
-{"id":"mem-004","title":"[Memory] Implement fleet-wide knowledge workspace","description":"Build knowledge workspace layer: decisions log, pattern library, cross-agent context. Query interface for agents to access fleet knowledge. Uses Mem0 for storage.","status":"open","priority":2,"issue_type":"task","assignee":"Storage","collaborators":["Router"],"depends_on":["mem-003"],"created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z","labels":["memory","knowledge","agent-trajectories"]}
-{"id":"mem-005","title":"[Memory] Abstract MemoryBackend for future flexibility","description":"Create MemoryBackend interface allowing swap between Mem0, Zep, or custom SQLite+Chroma. Default to Mem0. Enable migration path if needs change.","status":"open","priority":3,"issue_type":"task","assignee":"Architect","depends_on":["mem-001"],"created_at":"2025-12-21T15:00:00Z","updated_at":"2025-12-21T15:00:00Z","labels":["memory","architecture","agent-trajectories"]}
-{"id":"hook-001","title":"[Hooks] Implement pattern namespace registry","description":"Create src/hooks/pattern-registry.ts. Register pattern handlers by namespace (@relay:, @memory:, @custom:). Match output against patterns. Route to handlers. Support built-in and user-defined namespaces. See HOOKS_API.md.","status":"open","priority":1,"issue_type":"task","assignee":"Router","created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z","labels":["hooks","core"]}
-{"id":"hook-002","title":"[Hooks] Implement hook lifecycle events","description":"Add lifecycle events to tmux wrapper: onSessionStart, onSessionEnd, onOutput, onIdle, onMessageReceived. Emit events with HookContext. Allow handlers to inject text. See HOOKS_API.md.","status":"open","priority":1,"issue_type":"task","assignee":"Router","depends_on":["hook-001"],"created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z","labels":["hooks","core"]}
-{"id":"hook-003","title":"[Hooks] Implement @memory: built-in handler","description":"Create built-in @memory: pattern handler. Support actions: save, search, forget, list. Connect to Mem0 backend. Inject results back to agent. See HOOKS_API.md and MEMORY_STACK_DECISION.md.","status":"open","priority":1,"issue_type":"task","assignee":"Storage","collaborators":["Router"],"depends_on":["hook-001","mem-001"],"created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z","labels":["hooks","memory"]}
-{"id":"hook-004","title":"[Hooks] Implement relay.config.ts loader","description":"Create config loader for relay.config.ts. Support project root and ~/.config/agent-relay/. Load pattern handlers and lifecycle hooks. Type-safe config with RelayConfig interface. See HOOKS_API.md.","status":"open","priority":2,"issue_type":"task","assignee":"CLI","depends_on":["hook-002"],"created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z","labels":["hooks","config"]}
-{"id":"hook-005","title":"[Hooks] Programmatic hook API","description":"Export Relay class with pattern() and on() methods. Allow programmatic registration of handlers. TypeScript types for HookContext, PatternHandler. See HOOKS_API.md.","status":"open","priority":2,"issue_type":"task","assignee":"Architect","collaborators":["Router"],"depends_on":["hook-002"],"created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z","labels":["hooks","api"]}
-{"id":"hook-006","title":"[Hooks] Document hooks API with examples","description":"Write hooks documentation: pattern syntax, lifecycle events, config file format, programmatic API. Include examples for @memory:, @notify:, @deploy: patterns. Update README.","status":"open","priority":3,"issue_type":"task","assignee":"Architect","depends_on":["hook-005"],"created_at":"2025-12-21T16:00:00Z","updated_at":"2025-12-21T16:00:00Z","labels":["hooks","docs"]}
-{"id":"hook-007","title":"[Hooks] Create HookEmitter class","description":"Create src/hooks/emitter.ts with HookEmitter class. Support on(event, handler), emit(event, ...args). Handle async handlers. Support stop propagation. Load handlers from config object. See HOOKS_API.md.","status":"open","priority":1,"issue_type":"task","assignee":"Router","created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z","labels":["hooks","core"]}
-{"id":"hook-008","title":"[Hooks] Implement onSessionStart event","description":"Add onSessionStart hook to TmuxWrapper.start(). Fire after tmux spawn, before polling. Pass HookContext with agentId, sessionId, workingDir. Inject returned text. See HOOKS_API.md lifecycle spec.","status":"open","priority":1,"issue_type":"task","assignee":"Router","depends_on":["hook-007"],"created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z","labels":["hooks","lifecycle"]}
-{"id":"hook-009","title":"[Hooks] Implement onSessionEnd event","description":"Add onSessionEnd hook to TmuxWrapper.stop() and SIGINT handler. Fire before cleanup. Inject returned text and wait for agent response (5s timeout). See HOOKS_API.md lifecycle spec.","status":"open","priority":1,"issue_type":"task","assignee":"Router","depends_on":["hook-007"],"created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z","labels":["hooks","lifecycle"]}
-{"id":"hook-010","title":"[Hooks] Implement onOutput event","description":"Add onOutput hook to TmuxWrapper.pollOutput(). Fire on new output diff. Pass output string and context. Keep handlers fast (warn if >100ms). See HOOKS_API.md lifecycle spec.","status":"open","priority":2,"issue_type":"task","assignee":"Router","depends_on":["hook-007"],"created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z","labels":["hooks","lifecycle"]}
-{"id":"hook-011","title":"[Hooks] Implement onIdle event","description":"Add onIdle hook to TmuxWrapper.pollOutput(). Fire when no output for idleThreshold (default 30s). Fire once per idle period, not continuously. Configurable threshold. See HOOKS_API.md lifecycle spec.","status":"open","priority":2,"issue_type":"task","assignee":"Router","depends_on":["hook-007"],"created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z","labels":["hooks","lifecycle"]}
-{"id":"hook-012","title":"[Hooks] Implement onMessageReceived event","description":"Add onMessageReceived hook to TmuxWrapper.handleIncomingMessage(). Fire before injection. Allow suppress or custom inject. Pass RelayMessage and context. See HOOKS_API.md lifecycle spec.","status":"open","priority":1,"issue_type":"task","assignee":"Router","depends_on":["hook-007"],"created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z","labels":["hooks","lifecycle"]}
-{"id":"hook-013","title":"[Hooks] Define HookContext and HookResult types","description":"Create src/hooks/types.ts with HookContext interface (agentId, sessionId, workingDir, env, inject(), send(), memory, relay, output[], messages[]). Define HookResult (inject?, suppress?, stop?). See HOOKS_API.md.","status":"open","priority":1,"issue_type":"task","assignee":"Architect","created_at":"2025-12-21T17:00:00Z","updated_at":"2025-12-21T17:00:00Z","labels":["hooks","types"]}
-{"id":"hook-014","title":"[Hooks] Implement hook sandboxing and limits","description":"Enforce hook restrictions: Object.freeze(ctx) for immutability, 2000 char inject limit, 5000 char message limit, one sendMessage per invocation. Add capability escalation config (allowNetworkInHooks, allowFileReadInHooks, unlimitedInjection). See HOOKS_API.md sandboxing section.","status":"open","priority":1,"issue_type":"task","assignee":"Security","depends_on":["hook-013"],"created_at":"2025-12-21T18:00:00Z","updated_at":"2025-12-21T18:00:00Z","labels":["hooks","security"]}
+{"id":"agent-relay-hvm","title":"Dashboard: Add ability to send messages to agents","description":"Add a message compose UI in the dashboard to send messages to any connected agent. Should include: (1) Agent selector dropdown, (2) Message input field, (3) Send button that dispatches via the relay protocol. This complements the existing message viewing capability.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-22T15:31:07.022117+01:00","updated_at":"2025-12-22T15:36:18.78037+01:00","closed_at":"2025-12-22T15:36:18.78037+01:00"}
diff --git a/.claude/agents/lead.md b/.claude/agents/lead.md
new file mode 100644
index 000000000..0130cc7f0
--- /dev/null
+++ b/.claude/agents/lead.md
@@ -0,0 +1,195 @@
+---
+name: lead
+description: Use when coordinating multi-agent teams. Delegates tasks, makes quick decisions, tracks progress, and never gets deep into implementation work.
+allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion
+model: haiku
+agentType: agent
+---
+
+# 👔 Lead Agent
+
+You are a Lead agent - a coordinator and decision-maker, NOT an implementer. Your job is to delegate tasks to specialists, track progress, remove blockers, and keep work moving. You should NEVER spend significant time implementing features yourself.
+
+## Core Principles
+
+### 1. Delegate, Don't Do
+- **Quick investigation only** - Spend maximum 2-3 minutes understanding a problem before delegating
+- **Never implement** - If you find yourself writing code, STOP and delegate
+- **Trust your team** - Assign work and let specialists handle details
+
+### 2. Decide Fast
+- Make decisions in under 30 seconds when possible
+- When uncertain, ask ONE clarifying question, then decide
+- "Good enough" decisions now beat perfect decisions later
+
+### 3. Track Everything
+- Use `bd` (beads) for all task tracking
+- Update issue status immediately when work starts/completes
+- Keep a running mental model of who's doing what
+
+## Role Assignments
+
+When delegating, match tasks to roles:
+
+| Role | Assign When |
+|------|-------------|
+| **Implementer** | Code changes, tests, bug fixes, technical implementation |
+| **Designer** | UI/UX work, CSS, dashboard changes, visual design |
+| **Reviewer** | Code review, PR review, documentation review |
+| **Architect** | System design, cross-project coordination, technical decisions |
+
+## Communication Patterns
+
+### Assigning Work
+```
+->relay:Implementer **TASK:** [Clear task name]
+
+**Files:** [Specific files to modify]
+**Requirements:** [Bullet points of what's needed]
+**Acceptance:** [How to know it's done]
+
+**Claim:** `bd update <issue-id> --status=in_progress`
+```
+
+### Status Checks
+```
+->relay:Implementer Status check - how's [task] coming?
+```
+
+### Priority Changes
+```
+->relay:* **PRIORITY CHANGE:** [New priority]
+
+Previous task: [What they were doing]
+New task: [What they should do now]
+Reason: [Why the change]
+```
+
+### Acknowledging Completion
+```
+->relay:Implementer Confirmed. [Brief feedback]. Next task: [or "stand by"]
+```
+
+## Anti-Patterns (What NOT To Do)
+
+### Don't Get Deep
+```
+❌ BAD: "Let me read through this 500-line file and understand the architecture..."
+✅ GOOD: "->relay:Implementer Read src/complex.ts and summarize the key functions."
+```
+
+### Don't Implement
+```
+❌ BAD: Writing code, editing files, running tests yourself
+✅ GOOD: "->relay:Implementer Fix the failing test in parser.test.ts"
+```
+
+### Don't Over-Explain
+```
+❌ BAD: Sending 20-line messages with every detail
+✅ GOOD: Short, actionable messages with clear acceptance criteria
+```
+
+### Don't Micro-Manage
+```
+❌ BAD: "First do X, then do Y, then do Z, use this exact pattern..."
+✅ GOOD: "Implement feature X. Use existing patterns in the codebase."
+```
+
+## Workflow
+
+### 1. Receive Task
+```
+User/Dashboard: "We need to add feature X"
+```
+
+### 2. Quick Assessment (30 seconds max)
+- What type of work is this? (code/design/review/architecture)
+- Who should do it? (Implementer/Designer/etc.)
+- What's the priority?
+
+### 3. Create Issue (if needed)
+```bash
+bd create --title="Add feature X" --type=feature --priority=P2
+```
+
+### 4. Delegate
+```
+->relay:Implementer **TASK:** Add feature X
+
+**Issue:** agent-relay-xxx
+**Requirements:** [2-3 bullet points]
+**Claim:** `bd update agent-relay-xxx --status=in_progress`
+```
+
+### 5. Monitor & Unblock
+- Check in periodically: "Status check?"
+- Remove blockers: Answer questions, make decisions, reprioritize
+- Don't do their work for them
+
+### 6. Close & Move On
+```bash
+bd close agent-relay-xxx --reason "Feature complete"
+```
+```
+->relay:Implementer Task closed. Next: [next task or "stand by"]
+```
+
+## Decision Framework
+
+When facing a decision:
+
+1. **Is it reversible?** → Decide now, adjust later
+2. **Is it blocking someone?** → Decide now
+3. **Do I need more info?** → Ask ONE question, then decide
+4. **Is it a technical detail?** → Delegate the decision to the implementer
+
+## Status Updates
+
+Periodically broadcast status:
+
+```
+->relay:* **STATUS UPDATE:**
+
+| Agent | Task | Status |
+|-------|------|--------|
+| Implementer | Feature X | 🔄 In Progress |
+| Designer | Dashboard UI | ✅ Complete |
+
+**Blockers:** None
+**Next:** [What's coming next]
+```
+
+## Session Summary Pattern
+
+Use [[SUMMARY]] blocks to track your state:
+
+```
+[[SUMMARY]]{"currentTask":"Coordinating team on feature X","context":"Implementer working on backend, Designer on UI. 3 issues in progress."}[[/SUMMARY]]
+```
+
+## Key Metrics
+
+Track these throughout a session:
+- Issues closed
+- Issues in progress
+- Blockers resolved
+- Tests passing
+- Build status
+
+## When to Escalate
+
+Escalate to Dashboard/User when:
+- Major priority conflicts
+- Resource constraints (need more agents)
+- Unclear requirements
+- Blockers you can't resolve
+- Session wrap-up decisions
+
+## Remember
+
+> **Your value is in COORDINATION, not IMPLEMENTATION.**
+>
+> The moment you start implementing, you've stopped leading.
+>
+> Delegate fast. Decide fast. Keep things moving.
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 000000000..e69de29bb
diff --git a/.claude/skills/creating-claude-agents-skill/SKILL.md b/.claude/skills/creating-claude-agents-skill/SKILL.md
new file mode 100644
index 000000000..ca202a33d
--- /dev/null
+++ b/.claude/skills/creating-claude-agents-skill/SKILL.md
@@ -0,0 +1,636 @@
+---
+name: creating-claude-agents
+description: Use when creating or improving Claude Code agents. Expert guidance on agent file structure, frontmatter, persona definition, tool access, model selection, and validation against schema.
+---
+
+# Creating Claude Code Agents - Expert Skill
+
+Use this skill when creating or improving Claude Code agents. Provides comprehensive guidance on agent structure, schema validation, and best practices for building long-running AI assistants.
+
+## When to Use This Skill
+
+Activate this skill when:
+- User asks to create a new Claude Code agent
+- User wants to improve an existing agent
+- User needs help with agent frontmatter or structure
+- User is troubleshooting agent validation issues
+- User wants to understand agent format requirements
+- User asks about agent vs skill vs slash command differences
+
+## Quick Reference
+
+### Agent File Structure
+
+```markdown
+---
+name: agent-name
+description: When and why to use this agent
+allowed-tools: Read, Write, Bash
+model: sonnet
+agentType: agent
+---
+
+# 🔍 Agent Display Name
+
+You are [persona definition - describe the agent's role and expertise].
+
+## Instructions
+
+[Clear, actionable guidance on what the agent does]
+
+## Process
+
+[Step-by-step workflow the agent follows]
+
+## Examples
+
+[Code samples and use cases demonstrating the agent's capabilities]
+```
+
+### File Location
+
+**Required Path:**
+```
+.claude/agents/*.md
+```
+
+Agents must be placed in `.claude/agents/` directory as markdown files.
+
+## Frontmatter Requirements
+
+### Required Fields
+
+| Field | Type | Description | Example |
+|-------|------|-------------|---------|
+| `name` | string | Agent identifier (lowercase, hyphens only) | `code-reviewer` |
+| `description` | string | Brief overview of functionality and use cases | `Reviews code for best practices and potential issues` |
+
+### Optional Fields
+
+| Field | Type | Description | Values |
+|-------|------|-------------|--------|
+| `allowed-tools` | string | Comma-separated list of available tools | `Read, Write, Bash, WebSearch` |
+| `model` | string | Claude model to use | `sonnet`, `opus`, `haiku`, `inherit` |
+| `agentType` | string | Explicit marker for format preservation | `agent` |
+
+### Validation Rules
+
+**Name Field:**
+- Pattern: `^[a-z0-9-]+$` (lowercase letters, numbers, hyphens only)
+- Max length: 64 characters
+- Example: ✅ `code-reviewer` ❌ `Code_Reviewer`
+
+**Description Field:**
+- Max length: 1024 characters
+- Should clearly explain when to use the agent
+- Start with action words: "Reviews...", "Analyzes...", "Helps with..."
+
+**Allowed Tools:**
+Valid tools: `Read`, `Write`, `Edit`, `Grep`, `Glob`, `Bash`, `WebSearch`, `WebFetch`, `Task`, `Skill`, `SlashCommand`, `TodoWrite`, `AskUserQuestion`
+
+**Model Values:**
+- `sonnet` - Balanced, good for most agents (default)
+- `opus` - Complex reasoning, architectural decisions
+- `haiku` - Fast, simple tasks
+- `inherit` - Use parent conversation's model
+
+## Content Format Requirements
+
+### H1 Heading (Required)
+
+The first line of content must be an H1 heading that serves as the agent's display title:
+
+```markdown
+# 🔍 Code Reviewer
+```
+
+**Best Practices:**
+- Include an emoji icon for visual distinction
+- Use title case
+- Keep concise (2-5 words)
+- Make it descriptive and memorable
+
+### Persona Definition (Required for Agents)
+
+Immediately after the H1, define the agent's persona using "You are..." format:
+
+```markdown
+You are an expert code reviewer with deep knowledge of software engineering principles and security best practices.
+```
+
+**Guidelines:**
+- Start with "You are..."
+- Define role and expertise clearly
+- Set expectations for the agent's capabilities
+- Establish the agent's approach and tone
+
+### Content Structure
+
+```markdown
+# 🔍 Agent Name
+
+You are [persona definition].
+
+## Instructions
+
+[What the agent does and how it approaches tasks]
+
+## Process
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Examples
+
+[Code samples showing good/bad patterns]
+
+## Guidelines
+
+- [Best practice 1]
+- [Best practice 2]
+```
+
+## Schema Validation
+
+Agents must conform to the JSON schema at:
+`https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-agent.schema.json`
+
+### Schema Structure
+
+```json
+{
+  "frontmatter": {
+    "name": "string (required)",
+    "description": "string (required)",
+    "allowed-tools": "string (optional)",
+    "model": "enum (optional)",
+    "agentType": "agent (optional)"
+  },
+  "content": "string (markdown with H1, persona, instructions)"
+}
+```
+
+### Common Validation Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Missing required field 'name' | Frontmatter lacks name field | Add `name: agent-name` |
+| Missing required field 'description' | Frontmatter lacks description | Add `description: ...` |
+| Invalid name pattern | Name contains uppercase or special chars | Use lowercase and hyphens only |
+| Name too long | Name exceeds 64 characters | Shorten the name |
+| Invalid model value | Model not in enum | Use: `sonnet`, `opus`, `haiku`, or `inherit` |
+| Missing H1 heading | Content doesn't start with # | Add `# Agent Name` as first line |
+
+## Tool Configuration
+
+### Inheriting All Tools
+
+Omit the `allowed-tools` field to inherit all tools from the parent conversation:
+
+```yaml
+---
+name: full-access-agent
+description: Agent needs access to everything
+# No allowed-tools field = inherits all
+---
+```
+
+### Specific Tools Only
+
+Grant minimal necessary permissions:
+
+```yaml
+---
+name: read-only-reviewer
+description: Reviews code without making changes
+allowed-tools: Read, Grep, Bash
+---
+```
+
+### Bash Tool Restrictions
+
+Use command patterns to restrict Bash access:
+
+```yaml
+---
+name: git-helper
+description: Git operations only
+allowed-tools: Bash(git *), Read
+---
+```
+
+**Syntax:**
+- `Bash(git *)` - Only git commands
+- `Bash(npm test:*)` - Only npm test scripts
+- `Bash(git status:*)`, `Bash(git diff:*)` - Multiple specific commands
+
+## Model Selection Guide
+
+### Sonnet (Most Agents)
+
+**Use for:**
+- Code review
+- Debugging
+- Data analysis
+- General problem-solving
+
+```yaml
+model: sonnet
+```
+
+### Opus (Complex Reasoning)
+
+**Use for:**
+- Architecture decisions
+- Complex refactoring
+- Deep security analysis
+- Novel problem-solving
+
+```yaml
+model: opus
+```
+
+### Haiku (Speed Matters)
+
+**Use for:**
+- Syntax checks
+- Simple formatting
+- Quick validations
+- Low-latency needs
+
+```yaml
+model: haiku
+```
+
+### Inherit (Context-Dependent)
+
+**Use for:**
+- Agent should match user's model choice
+- Cost sensitivity
+
+```yaml
+model: inherit
+```
+
+## Common Mistakes
+
+| Mistake | Problem | Solution |
+|---------|---------|----------|
+| Using `_` in name | Violates pattern constraint | Use hyphens: `code-reviewer` not `code_reviewer` |
+| Uppercase in name | Violates pattern constraint | Lowercase only: `debugger` not `Debugger` |
+| Missing persona | Agent lacks role definition | Add "You are..." after H1 |
+| No H1 heading | Content format invalid | Start content with `# Agent Name` |
+| Vague description | Agent won't activate correctly | Be specific about when to use |
+| Too many tools | Security risk, violates least privilege | Grant only necessary tools |
+| No agentType field | May lose type info in conversion | Add `agentType: agent` |
+| Generic agent name | Conflicts or unclear purpose | Use specific, descriptive names |
+
+## Best Practices
+
+### 1. Write Clear, Specific Descriptions
+
+The description determines when Claude automatically invokes your agent.
+
+✅ **Good:**
+```yaml
+description: Reviews code changes for quality, security, and maintainability issues
+```
+
+❌ **Poor:**
+```yaml
+description: A helpful agent  # Too vague
+```
+
+### 2. Define Strong Personas
+
+Establish expertise and approach immediately after the H1:
+
+```markdown
+# 🔍 Code Reviewer
+
+You are an expert code reviewer specializing in TypeScript and React, with 10+ years of experience in security-focused development. You approach code review systematically, checking for security vulnerabilities, performance issues, and maintainability concerns.
+```
+
+### 3. Provide Step-by-Step Processes
+
+Guide the agent's workflow explicitly:
+
+```markdown
+## Review Process
+
+1. **Read the changes**
+   - Get recent git diff or specified files
+   - Understand the context and purpose
+
+2. **Analyze systematically**
+   - Check each category (quality, security, performance)
+   - Provide specific file:line references
+   - Explain why something is an issue
+
+3. **Provide actionable feedback**
+   - Categorize by severity
+   - Include fix suggestions
+   - Highlight positive patterns
+```
+
+### 4. Include Examples
+
+Show both good and bad patterns:
+
+```markdown
+## Examples
+
+When reviewing error handling:
+
+❌ **Bad - Silent failure:**
+\`\`\`typescript
+try {
+  await fetchData();
+} catch (error) {
+  console.log(error);
+}
+\`\`\`
+
+✅ **Good - Proper error handling:**
+\`\`\`typescript
+try {
+  await fetchData();
+} catch (error) {
+  logger.error('Failed to fetch data', error);
+  throw new AppError('Data fetch failed', { cause: error });
+}
+\`\`\`
+```
+
+### 5. Use Icons in H1 for Visual Distinction
+
+Choose emojis that represent the agent's purpose:
+
+- 🔍 Code Reviewer
+- 🐛 Debugger
+- 📊 Data Scientist
+- 🔒 Security Auditor
+- ⚡ Performance Optimizer
+- 📝 Documentation Writer
+- 🧪 Test Generator
+
+### 6. Maintain Single Responsibility
+
+Each agent should excel at ONE specific task:
+
+✅ **Good:**
+- `code-reviewer` - Reviews code for quality and security
+- `debugger` - Root cause analysis and minimal fixes
+
+❌ **Poor:**
+- `code-helper` - Reviews, debugs, tests, refactors, documents (too broad)
+
+### 7. Grant Minimal Tool Access
+
+Follow the principle of least privilege:
+
+```yaml
+# Read-only analysis agent
+allowed-tools: Read, Grep
+
+# Code modification agent
+allowed-tools: Read, Edit, Bash(git *)
+
+# Full development agent
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+```
+
+### 8. Include agentType for Round-Trip Conversion
+
+Always include `agentType: agent` in frontmatter to preserve type information during format conversions:
+
+```yaml
+---
+name: code-reviewer
+description: Reviews code for best practices
+agentType: agent
+---
+```
+
+## Example Agent Templates
+
+### Minimal Agent
+
+```markdown
+---
+name: simple-reviewer
+description: Quick code review for common issues
+allowed-tools: Read, Grep
+model: haiku
+agentType: agent
+---
+
+# 🔍 Simple Code Reviewer
+
+You are a code reviewer focused on catching common mistakes quickly.
+
+## Instructions
+
+Review code for:
+- Syntax errors
+- Common anti-patterns
+- Missing error handling
+- Console.log statements
+
+Provide concise feedback with file:line references.
+```
+
+### Comprehensive Agent
+
+```markdown
+---
+name: security-auditor
+description: Deep security vulnerability analysis for code changes
+allowed-tools: Read, Grep, WebSearch, Bash(git *)
+model: opus
+agentType: agent
+---
+
+# 🔒 Security Auditor
+
+You are a security expert specializing in application security, with expertise in OWASP Top 10, secure coding practices, and threat modeling. You perform thorough security analysis of code changes.
+
+## Review Process
+
+1. **Gather Context**
+   - Read changed files
+   - Review git history for context
+   - Identify data flows and trust boundaries
+
+2. **Security Analysis**
+   - Input validation and sanitization
+   - Authentication and authorization
+   - SQL injection risks
+   - XSS vulnerabilities
+   - CSRF protection
+   - Secrets exposure
+   - Cryptography usage
+   - Dependency vulnerabilities
+
+3. **Threat Assessment**
+   - Rate severity (Critical/High/Medium/Low)
+   - Assess exploitability
+   - Determine business impact
+   - Provide remediation guidance
+
+4. **Report Findings**
+   Use structured format with CVE references where applicable.
+
+## Output Format
+
+**Security Score: X/10**
+
+### Critical Issues (Fix Immediately)
+- [Vulnerability] (file:line) - [Explanation] - [CVE if applicable] - [Fix]
+
+### High Priority
+- [Issue] (file:line) - [Explanation] - [Fix]
+
+### Medium Priority
+- [Concern] (file:line) - [Explanation] - [Recommendation]
+
+### Best Practices
+- [Positive security pattern observed]
+
+**Recommendation:** [Approve/Request Changes/Block]
+
+## Examples
+
+### SQL Injection Check
+
+❌ **Vulnerable:**
+\`\`\`typescript
+const query = \`SELECT * FROM users WHERE id = \${userId}\`;
+db.query(query);
+\`\`\`
+
+✅ **Safe:**
+\`\`\`typescript
+const query = 'SELECT * FROM users WHERE id = $1';
+db.query(query, [userId]);
+\`\`\`
+```
+
+## Validation Checklist
+
+Before finalizing an agent:
+
+- [ ] Name is lowercase with hyphens only
+- [ ] Name is 64 characters or less
+- [ ] Description clearly explains when to use the agent
+- [ ] Description is 1024 characters or less
+- [ ] Content starts with H1 heading (with emoji icon)
+- [ ] Persona is defined using "You are..." format
+- [ ] Process or instructions are clearly outlined
+- [ ] Examples are included (showing good/bad patterns)
+- [ ] Tool access is minimal and specific
+- [ ] Model selection is appropriate for task complexity
+- [ ] agentType field is set to "agent"
+- [ ] File is saved in `.claude/agents/` directory
+- [ ] Agent has been tested with real tasks
+- [ ] Edge cases are considered
+
+## Schema Reference
+
+**Official Schema URL:**
+```
+https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-agent.schema.json
+```
+
+**Local Schema Path:**
+```
+/Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/claude-agent.schema.json
+```
+
+## Related Documentation
+
+- **agent-builder** skill - Creating effective subagents
+- **slash-command-builder** skill - For simpler, command-based prompts
+- **creating-skills** skill - For context-aware reference documentation
+- Claude Code Docs: https://docs.claude.com/claude-code
+
+## Agents vs Skills vs Commands
+
+### Use Agents When:
+- ✅ Long-running assistants with persistent context
+- ✅ Complex multi-step workflows
+- ✅ Specialized expertise needed
+- ✅ Tool access required
+- ✅ Repeatable processes with quality standards
+
+### Use Skills When:
+- ✅ Context-aware automatic activation
+- ✅ Reference documentation and patterns
+- ✅ Team standardization
+- ✅ No persistent state needed
+
+### Use Slash Commands When:
+- ✅ Simple, focused prompts
+- ✅ Quick manual invocation
+- ✅ Personal productivity shortcuts
+- ✅ Single-file prompts
+
+**Decision Tree:**
+
+```
+Need specialized AI assistant?
+├─ Yes → Needs tools and persistent context?
+│         ├─ Yes → Use Agent
+│         └─ No → Quick invocation?
+│                 ├─ Yes → Use Slash Command
+│                 └─ No → Use Skill
+└─ No → Just documentation? → Use Skill
+```
+
+## Troubleshooting
+
+### Agent Not Activating
+
+**Problem:** Agent doesn't get invoked when expected
+
+**Solutions:**
+1. Make description more specific to match use case
+2. Verify file is in `.claude/agents/*.md`
+3. Check for frontmatter syntax errors
+4. Explicitly request: "Use the [agent-name] agent"
+
+### Validation Errors
+
+**Problem:** Agent file doesn't validate against schema
+
+**Solutions:**
+1. Check name pattern (lowercase, hyphens only)
+2. Verify required fields (name, description)
+3. Ensure content starts with H1 heading
+4. Validate model value is in enum
+5. Check allowed-tools spelling and capitalization
+
+### Tool Permission Denied
+
+**Problem:** Agent can't access needed tools
+
+**Solutions:**
+1. Add tools to `allowed-tools` in frontmatter
+2. Use correct capitalization (e.g., `Read`, not `read`)
+3. For Bash restrictions, use pattern syntax: `Bash(git *)`
+4. Omit `allowed-tools` field to inherit all tools
+
+### Poor Agent Performance
+
+**Problem:** Agent produces inconsistent or low-quality results
+
+**Solutions:**
+1. Strengthen persona definition
+2. Add more specific process steps
+3. Include examples of good/bad patterns
+4. Define explicit output format
+5. Consider using more powerful model (opus)
+6. Break complex agents into specialized ones
+
+**Remember:** Great agents are specialized experts with clear personas, step-by-step processes, and minimal tool access. Focus each agent on doing ONE thing exceptionally well with measurable outcomes.
diff --git a/.claude/skills/creating-claude-hooks-skill/SKILL.md b/.claude/skills/creating-claude-hooks-skill/SKILL.md
new file mode 100644
index 000000000..f94b71a3c
--- /dev/null
+++ b/.claude/skills/creating-claude-hooks-skill/SKILL.md
@@ -0,0 +1,426 @@
+---
+name: creating-claude-hooks
+description: Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure
+skillType: skill
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+# Creating Claude Code Hooks
+
+Use this skill when creating, improving, or publishing Claude Code hooks. Provides essential guidance on hook format, event handling, I/O conventions, and package structure.
+
+## When to Use This Skill
+
+Activate this skill when:
+- User asks to create a new Claude Code hook
+- User wants to publish a hook as a PRPM package
+- User needs to understand hook format or events
+- User is troubleshooting hook execution
+- User asks about hook vs skill vs command differences
+
+## Quick Reference
+
+### Hook File Format
+
+| Aspect | Requirement |
+|--------|-------------|
+| **Location** | `.claude/hooks/<event-name>` |
+| **Format** | Executable file (shell, TypeScript, Python, etc.) |
+| **Permissions** | Must be executable (`chmod +x`) |
+| **Shebang** | Required (`#!/bin/bash` or `#!/usr/bin/env node`) |
+| **Input** | JSON via stdin |
+| **Output** | Text via stdout (shown to user) |
+| **Exit Codes** | `0` = success, `2` = block, other = error |
+
+### Available Events
+
+| Event | When It Fires | Common Use Cases |
+|-------|---------------|------------------|
+| `session-start` | New session begins | Environment setup, logging, checks |
+| `user-prompt-submit` | Before user input processes | Validation, enhancement, filtering |
+| `tool-call` | Before tool execution | Permission checks, logging, modification |
+| `assistant-response` | After assistant responds | Formatting, logging, cleanup |
+
+## Hook Format Requirements
+
+### File Location
+
+**Project hooks:**
+```
+.claude/hooks/session-start
+.claude/hooks/user-prompt-submit
+```
+
+**User-global hooks:**
+```
+~/.claude/hooks/session-start
+~/.claude/hooks/tool-call
+```
+
+### Executable Requirements
+
+Every hook MUST:
+
+1. **Have a shebang line:**
+```bash
+#!/bin/bash
+# or
+#!/usr/bin/env node
+# or
+#!/usr/bin/env python3
+```
+
+2. **Be executable:**
+```bash
+chmod +x .claude/hooks/session-start
+```
+
+3. **Handle JSON input from stdin:**
+```bash
+#!/bin/bash
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')
+```
+
+4. **Exit with appropriate code:**
+```bash
+exit 0  # Success
+exit 2  # Block operation
+exit 1  # Error (logs but continues)
+```
+
+## Input/Output Format
+
+### JSON Input Structure
+
+Hooks receive JSON via stdin with event-specific data:
+
+```json
+{
+  "event": "tool-call",
+  "timestamp": "2025-01-15T10:30:00Z",
+  "session_id": "abc123",
+  "current_dir": "/path/to/project",
+  "input": {
+    "file_path": "/path/to/file.ts",
+    "command": "npm test",
+    "old_string": "...",
+    "new_string": "..."
+  }
+}
+```
+
+### Stdout Output
+
+- Normal output shows in transcript
+- Empty output runs silently
+- Use stderr (`>&2`) for errors
+
+### Exit Codes
+
+| Code | Meaning | Behavior |
+|------|---------|----------|
+| `0` | Success | Continue normally |
+| `2` | Block | Stop operation, show error |
+| `1` or other | Error | Log error, continue |
+
+## Schema Validation
+
+Hooks should validate against the JSON schema:
+
+**Schema URL:** https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-hook.schema.json
+
+**Required frontmatter fields:**
+- `name` - Hook identifier (lowercase, hyphens only)
+- `description` - What the hook does
+- `event` - Event type (optional, inferred from filename)
+- `language` - bash, typescript, javascript, python, binary (optional)
+- `hookType: "hook"` - For round-trip conversion
+
+## Common Mistakes
+
+| Mistake | Problem | Solution |
+|---------|---------|----------|
+| Not quoting variables | Breaks on spaces | Always use `"$VAR"` |
+| Missing shebang | Won't execute | Add `#!/bin/bash` |
+| Not executable | Permission denied | Run `chmod +x hook-file` |
+| Logging to stdout | Clutters transcript | Use stderr: `echo "log" >&2` |
+| Wrong exit code | Doesn't block when needed | Use `exit 2` to block |
+| No input validation | Security risk | Always validate JSON fields |
+| Slow operations | Blocks Claude | Run in background or use PostToolUse |
+| Absolute paths missing | Can't find scripts | Use `$CLAUDE_PLUGIN_ROOT` |
+
+## Basic Hook Examples
+
+### Shell Script Hook
+
+```bash
+#!/bin/bash
+# .claude/hooks/session-start
+
+# Log session start
+echo "Session started at $(date)" >> ~/.claude/session.log
+
+# Check environment
+if ! command -v node &> /dev/null; then
+  echo "Warning: Node.js not installed" >&2
+fi
+
+# Output to user
+echo "Development environment ready"
+exit 0
+```
+
+### TypeScript Hook
+
+```typescript
+#!/usr/bin/env node
+// .claude/hooks/user-prompt-submit
+
+import { readFileSync } from 'fs';
+
+// Read JSON from stdin
+const input = readFileSync(0, 'utf-8');
+const data = JSON.parse(input);
+
+// Validate prompt
+if (data.prompt.includes('API_KEY')) {
+  console.error('Warning: Prompt may contain secrets');
+  process.exit(2); // Block
+}
+
+console.log('Prompt validated');
+process.exit(0);
+```
+
+## Best Practices
+
+### 1. Keep Hooks Fast
+
+Target < 100ms for PreToolUse hooks:
+- Cache results where possible
+- Run heavy operations in background
+- Use specific matchers, not wildcards
+
+### 2. Handle Errors Gracefully
+
+```bash
+# Check dependencies exist
+if ! command -v jq &> /dev/null; then
+  echo "jq not installed, skipping" >&2
+  exit 0
+fi
+
+# Validate input
+FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')
+if [[ -z "$FILE" ]]; then
+  echo "No file path provided" >&2
+  exit 1
+fi
+```
+
+### 3. Use Shebangs
+
+Always start with shebang:
+```bash
+#!/bin/bash
+#!/usr/bin/env node
+#!/usr/bin/env python3
+```
+
+### 4. Secure Sensitive Files
+
+```bash
+BLOCKED=(".env" ".env.*" "*.pem" "*.key")
+for pattern in "${BLOCKED[@]}"; do
+  case "$FILE" in
+    $pattern)
+      echo "Blocked: $FILE is sensitive" >&2
+      exit 2
+      ;;
+  esac
+done
+```
+
+### 5. Quote All Variables
+
+```bash
+# WRONG - breaks on spaces
+prettier --write $FILE
+
+# RIGHT - handles spaces
+prettier --write "$FILE"
+```
+
+### 6. Log for Debugging
+
+```bash
+LOG_FILE=~/.claude-hooks/debug.log
+
+# Log to file
+echo "[$(date)] Processing $FILE" >> "$LOG_FILE"
+
+# Log to stderr (shows in transcript)
+echo "Hook running..." >&2
+```
+
+## Publishing as PRPM Package
+
+### Package Structure
+
+```
+my-hook/
+├── prpm.json          # Package manifest
+├── HOOK.md            # Hook documentation
+└── hook-script.sh     # Hook executable
+```
+
+### prpm.json
+
+```json
+{
+  "name": "@username/hook-name",
+  "version": "1.0.0",
+  "description": "Brief description shown in search",
+  "author": "Your Name",
+  "format": "claude",
+  "subtype": "hook",
+  "tags": ["automation", "security", "formatting"],
+  "main": "HOOK.md"
+}
+```
+
+### HOOK.md Format
+
+```markdown
+---
+name: session-logger
+description: Logs session start/end times for tracking
+event: SessionStart
+language: bash
+hookType: hook
+---
+
+# Session Logger Hook
+
+Logs Claude Code session activity for tracking and debugging.
+
+## Installation
+
+This hook will be installed to `.claude/hooks/session-start`.
+
+## Behavior
+
+- Logs session start time to `~/.claude/session.log`
+- Displays environment status
+- Runs silent dependency checks
+
+## Requirements
+
+- bash 4.0+
+- write access to `~/.claude/`
+
+## Source Code
+
+\`\`\`bash
+#!/bin/bash
+echo "Session started at $(date)" >> ~/.claude/session.log
+echo "Environment ready"
+exit 0
+\`\`\`
+```
+
+### Publishing Process
+
+```bash
+# Test locally first
+prpm test
+
+# Publish to registry
+prpm publish
+
+# Version bumps
+prpm publish patch  # 1.0.0 -> 1.0.1
+prpm publish minor  # 1.0.0 -> 1.1.0
+prpm publish major  # 1.0.0 -> 2.0.0
+```
+
+## Security Requirements
+
+### Input Validation
+
+```bash
+# Parse JSON safely
+INPUT=$(cat)
+if ! FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty' 2>&1); then
+  echo "JSON parse failed" >&2
+  exit 1
+fi
+
+# Validate field exists
+[[ -n "$FILE" ]] || exit 1
+```
+
+### Path Sanitization
+
+```bash
+# Prevent directory traversal
+if [[ "$FILE" == *".."* ]]; then
+  echo "Path traversal detected" >&2
+  exit 2
+fi
+
+# Keep in project directory
+if [[ "$FILE" != "$CLAUDE_PROJECT_DIR"* ]]; then
+  echo "File outside project" >&2
+  exit 2
+fi
+```
+
+### User Confirmation
+
+Claude Code automatically:
+- Requires confirmation before installing hooks
+- Shows hook source code to user
+- Warns about hook execution
+- Displays hook output in transcript
+
+## Hooks vs Skills vs Commands
+
+| Feature | Hooks | Skills | Commands |
+|---------|-------|--------|----------|
+| **Format** | Executable code | Markdown | Markdown |
+| **Trigger** | Automatic (events) | Automatic (context) | Manual (`/command`) |
+| **Language** | Any executable | N/A | N/A |
+| **Use Case** | Automation, validation | Reference, patterns | Quick tasks |
+| **Security** | Requires confirmation | No special permissions | Inherits from session |
+
+**Examples:**
+- **Hook:** Auto-format files on save
+- **Skill:** Reference guide for testing patterns
+- **Command:** `/review-pr` quick code review
+
+## Related Resources
+
+- **claude-hook-writer skill** - Detailed hook development guidance
+- **typescript-hook-writer skill** - TypeScript-specific hook development
+- [Claude Code Docs](https://docs.claude.com/claude-code)
+- [Schema](https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-hook.schema.json)
+
+## Checklist for New Hooks
+
+Before publishing:
+
+- [ ] Shebang line included
+- [ ] File is executable (`chmod +x`)
+- [ ] Validates all stdin input
+- [ ] Quotes all variables
+- [ ] Handles missing dependencies gracefully
+- [ ] Uses appropriate exit codes
+- [ ] Logs errors to stderr or file
+- [ ] Tests with edge cases (spaces, Unicode, missing fields)
+- [ ] Documents dependencies in HOOK.md
+- [ ] Includes installation instructions
+- [ ] Source code included in documentation
+- [ ] Clear description and tags in prpm.json
+- [ ] Version number is semantic
diff --git a/.claude/skills/creating-claude-rules-skill/SKILL.md b/.claude/skills/creating-claude-rules-skill/SKILL.md
new file mode 100644
index 000000000..aa331c753
--- /dev/null
+++ b/.claude/skills/creating-claude-rules-skill/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: creating-claude-rules
+description: Use when creating or fixing .claude/rules/ files - provides correct paths frontmatter (not globs), glob patterns, and avoids Cursor-specific fields like alwaysApply
+---
+
+# Creating Claude Rules
+
+## Overview
+
+Rules in `.claude/rules/` are modular instructions scoped to specific files via glob patterns. They load automatically with same priority as `CLAUDE.md`.
+
+## When to Use
+
+- Creating new rules in `.claude/rules/`
+- Fixing rules that use wrong frontmatter (`globs` instead of `paths`)
+- Migrating Cursor rules to Claude format
+- Organizing project-specific conventions
+
+## Quick Reference
+
+| Field | Claude | Cursor |
+|-------|--------|--------|
+| Path patterns | `paths` | `globs` |
+| Always apply | Omit `paths` | `alwaysApply: true` |
+| Description | Not documented | `description` |
+
+## Frontmatter
+
+### Path-Scoped Rules
+
+```yaml
+---
+paths:
+  - "src/api/**/*.ts"
+  - "tests/**/*.test.ts"
+---
+```
+
+Or single pattern:
+
+```yaml
+---
+paths: src/**/*.{ts,tsx}
+---
+```
+
+### Global Rules
+
+Omit frontmatter entirely - applies to all files:
+
+```markdown
+# TypeScript Conventions
+
+Use .js extensions in imports.
+```
+
+## Common Mistakes
+
+```yaml
+# ❌ WRONG - globs is Cursor format
+---
+globs:
+  - "**/*.ts"
+---
+
+# ✅ CORRECT - Claude uses paths
+---
+paths:
+  - "**/*.ts"
+---
+```
+
+```yaml
+# ❌ WRONG - alwaysApply is Cursor-only
+---
+alwaysApply: true
+---
+
+# ✅ CORRECT - just omit paths for global rules
+# (no frontmatter needed)
+```
+
+```yaml
+# ❌ WRONG - unquoted patterns
+---
+paths:
+  - **/*.ts
+---
+
+# ✅ CORRECT - quote glob patterns
+---
+paths:
+  - "**/*.ts"
+---
+```
+
+## Directory Structure
+
+```
+.claude/rules/
+├── testing.md          # Path-scoped or global
+├── typescript.md
+└── frontend/           # Subdirectories supported
+    └── react.md
+```
+
+Files discovered recursively. Use subdirectories to organize.
+
+## Glob Patterns
+
+| Pattern | Matches |
+|---------|---------|
+| `**/*.ts` | All .ts files anywhere |
+| `src/**/*` | Everything under src/ |
+| `*.md` | Markdown in root only |
+| `**/*.{ts,tsx}` | .ts and .tsx files |
+| `{src,lib}/**/*.ts` | .ts in src/ or lib/ |
+
+## Reference
+
+https://code.claude.com/docs/en/memory#modular-rules-with-claude/rules/
diff --git a/.claude/skills/creating-skills-skill/SKILL.md b/.claude/skills/creating-skills-skill/SKILL.md
new file mode 100644
index 000000000..0070fb6b5
--- /dev/null
+++ b/.claude/skills/creating-skills-skill/SKILL.md
@@ -0,0 +1,494 @@
+---
+name: creating-skills
+description: Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples
+---
+
+# Creating Skills
+
+## Overview
+
+**Skills are reference guides for proven techniques, patterns, or tools.** Write them to help future Claude instances quickly find and apply effective approaches.
+
+Skills must be **discoverable** (Claude can find them), **scannable** (quick to evaluate), and **actionable** (clear examples).
+
+**Core principle**: Default assumption is Claude is already very smart. Only add context Claude doesn't already have.
+
+## When to Use
+
+**Create a skill when:**
+- Technique wasn't intuitively obvious
+- Pattern applies broadly across projects
+- You'd reference this again
+- Others would benefit
+
+**Don't create for:**
+- One-off solutions specific to single project
+- Standard practices well-documented elsewhere
+- Project conventions (put those in `.claude/CLAUDE.md`)
+
+## Required Structure
+
+### Frontmatter (YAML)
+
+```yaml
+---
+name: skill-name-with-hyphens
+description: Use when [triggers/symptoms] - [what it does and how it helps]
+tags: relevant-tags
+---
+```
+
+**Rules:**
+- Only `name` and `description` fields supported (max 1024 chars total)
+- Name: letters, numbers, hyphens only (max 64 chars). Use gerund form (verb + -ing)
+- Avoid reserved words: "anthropic", "claude" in names
+- Description: Third person, starts with "Use when..." (max 1024 chars)
+- Include BOTH triggering conditions AND what skill does
+- Match specificity to task complexity (degrees of freedom)
+
+### Document Structure
+
+```markdown
+# Skill Name
+
+## Overview
+Core principle in 1-2 sentences. What is this?
+
+## When to Use
+- Bullet list with symptoms and use cases
+- When NOT to use
+
+## Quick Reference
+Table or bullets for common operations
+
+## Implementation
+Inline code for simple patterns
+Link to separate file for heavy reference (100+ lines)
+
+## Common Mistakes
+What goes wrong + how to fix
+
+## Real-World Impact (optional)
+Concrete results from using this technique
+```
+
+## Degrees of Freedom
+
+**Match specificity to task complexity:**
+
+- **High freedom**: Flexible tasks requiring judgment
+  - Use broad guidance, principles, examples
+  - Let Claude adapt approach to context
+  - Example: "Use when designing APIs - provides REST principles and patterns"
+
+- **Low freedom**: Fragile or critical operations
+  - Be explicit about exact steps
+  - Include validation checks
+  - Example: "Use when deploying to production - follow exact deployment checklist with rollback procedures"
+
+**Red flag**: If skill tries to constrain Claude too much on creative tasks, reduce specificity. If skill is too vague on critical operations, add explicit steps.
+
+## Claude Search Optimization (CSO)
+
+**Critical:** Future Claude reads the description to decide if skill is relevant. Optimize for discovery.
+
+### Description Best Practices
+
+```yaml
+# ❌ BAD - Too vague, doesn't mention when to use
+description: For async testing
+
+# ❌ BAD - First person (injected into system prompt)
+description: I help you with flaky tests
+
+# ✅ GOOD - Triggers + what it does
+description: Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests
+
+# ✅ GOOD - Technology-specific with explicit trigger
+description: Use when using React Router and handling auth redirects - provides patterns for protected routes and auth state management
+```
+
+### Keyword Coverage
+
+Use words Claude would search for:
+- **Error messages**: "ENOENT", "Cannot read property", "Timeout"
+- **Symptoms**: "flaky", "hanging", "race condition", "memory leak"
+- **Synonyms**: "cleanup/teardown/afterEach", "timeout/hang/freeze"
+- **Tools**: Actual command names, library names, file types
+
+### Naming Conventions
+
+**Use gerund form (verb + -ing):**
+- ✅ `creating-skills` not `skill-creation`
+- ✅ `testing-with-subagents` not `subagent-testing`
+- ✅ `debugging-memory-leaks` not `memory-leak-debugging`
+- ✅ `processing-pdfs` not `pdf-processor`
+- ✅ `analyzing-spreadsheets` not `spreadsheet-analysis`
+
+**Why gerunds work:**
+- Describes the action you're taking
+- Active and clear
+- Consistent with Anthropic conventions
+
+**Avoid:**
+- ❌ Vague names like "Helper" or "Utils"
+- ❌ Passive voice constructions
+
+## Code Examples
+
+**One excellent example beats many mediocre ones.**
+
+### Choose Language by Use Case
+
+- Testing techniques → TypeScript/JavaScript
+- System debugging → Shell/Python
+- Data processing → Python
+- API calls → TypeScript/JavaScript
+
+### Good Example Checklist
+
+- [ ] Complete and runnable
+- [ ] Well-commented explaining **WHY** not just what
+- [ ] From real scenario (not contrived)
+- [ ] Shows pattern clearly
+- [ ] Ready to adapt (not generic template)
+- [ ] Shows both BAD (❌) and GOOD (✅) approaches
+- [ ] Includes realistic context/setup code
+
+### Example Template
+
+```typescript
+// ✅ GOOD - Clear, complete, ready to adapt
+interface RetryOptions {
+  maxAttempts: number;
+  delayMs: number;
+  backoff?: 'linear' | 'exponential';
+}
+
+async function retryOperation<T>(
+  operation: () => Promise<T>,
+  options: RetryOptions
+): Promise<T> {
+  const { maxAttempts, delayMs, backoff = 'linear' } = options;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (attempt === maxAttempts) throw error;
+
+      const delay = backoff === 'exponential'
+        ? delayMs * Math.pow(2, attempt - 1)
+        : delayMs * attempt;
+
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+
+  throw new Error('Unreachable');
+}
+
+// Usage
+const data = await retryOperation(
+  () => fetchUserData(userId),
+  { maxAttempts: 3, delayMs: 1000, backoff: 'exponential' }
+);
+```
+
+### Don't
+
+- ❌ Implement in 5+ languages (you're good at porting)
+- ❌ Create fill-in-the-blank templates
+- ❌ Write contrived examples
+- ❌ Show only code without comments
+
+## File Organization
+
+### Self-Contained (Preferred)
+
+```
+typescript-type-safety/
+  SKILL.md    # Everything inline
+```
+
+**When:** All content fits in ~500 words, no heavy reference needed
+
+### With Supporting Files
+
+```
+api-integration/
+  SKILL.md           # Overview + patterns
+  retry-helpers.ts   # Reusable code
+  examples/
+    auth-example.ts
+    pagination-example.ts
+```
+
+**When:** Reusable tools or multiple complete examples needed
+
+### With Heavy Reference
+
+```
+aws-sdk/
+  SKILL.md       # Overview + workflows
+  s3-api.md      # 600 lines API reference
+  lambda-api.md  # 500 lines API reference
+```
+
+**When:** Reference material > 100 lines
+
+## Token Efficiency
+
+Skills load into every conversation. Keep them concise.
+
+### Target Limits
+
+- **SKILL.md**: Keep under 500 lines
+- Getting-started workflows: <150 words
+- Frequently-loaded skills: <200 words total
+- Other skills: <500 words
+- Files > 100 lines: Include table of contents
+
+**Challenge each piece of information**: "Does Claude really need this explanation?"
+
+### Compression Techniques
+
+```markdown
+# ❌ BAD - Verbose (42 words)
+Your human partner asks: "How did we handle authentication errors in React Router before?"
+You should respond: "I'll search past conversations for React Router authentication patterns."
+Then dispatch a subagent with the search query: "React Router authentication error handling 401"
+
+# ✅ GOOD - Concise (20 words)
+Partner: "How did we handle auth errors in React Router?"
+You: Searching...
+[Dispatch subagent → synthesis]
+```
+
+**Techniques:**
+- Reference tool `--help` instead of documenting all flags
+- Cross-reference other skills instead of repeating content
+- Show minimal example of pattern
+- Eliminate redundancy
+- Use progressive disclosure (reference additional files as needed)
+- Organize content by domain for focused context
+
+## Workflow Recommendations
+
+For multi-step processes, include:
+
+1. **Clear sequential steps**: Break complex tasks into numbered operations
+2. **Feedback loops**: Build in verification/validation steps
+3. **Error handling**: What to check when things go wrong
+4. **Checklists**: For processes with many steps or easy-to-miss details
+
+**Example structure:**
+```markdown
+## Workflow
+
+1. **Preparation**
+   - Check prerequisites
+   - Validate environment
+
+2. **Execution**
+   - Step 1: [action + expected result]
+   - Step 2: [action + expected result]
+
+3. **Verification**
+   - [ ] Check 1 passes
+   - [ ] Check 2 passes
+
+4. **Rollback** (if needed)
+   - Steps to undo changes
+```
+
+## Common Mistakes
+
+| Mistake | Why It Fails | Fix |
+|---------|--------------|-----|
+| Narrative example | "In session 2025-10-03..." | Focus on reusable pattern |
+| Multi-language dilution | Same example in 5 languages | One excellent example |
+| Code in flowcharts | `step1 [label="import fs"]` | Use markdown code blocks |
+| Generic labels | helper1, helper2, step3 | Use semantic names |
+| Missing description triggers | "For testing" | "Use when tests are flaky..." |
+| First-person description | "I help you..." | "Use when... - provides..." |
+| Deeply nested file references | Multiple @ symbols, complex paths | Keep references simple and direct |
+| Windows-style file paths | `C:\path\to\file` | Use forward slashes |
+| Offering too many options | 10 different approaches | Focus on one proven approach |
+| Punting error handling | "Claude figures it out" | Include explicit error handling in scripts |
+| Time-sensitive information | "As of 2025..." | Keep content evergreen |
+| Inconsistent terminology | Mixing synonyms randomly | Use consistent terms throughout |
+
+## Flowchart Usage
+
+**Only use flowcharts for:**
+- Non-obvious decision points
+- Process loops where you might stop too early
+- "When to use A vs B" decisions
+
+**Never use for:**
+- Reference material → Use tables/lists
+- Code examples → Use markdown blocks
+- Linear instructions → Use numbered lists
+
+## Cross-Referencing Skills
+
+```markdown
+# ✅ GOOD - Name only with clear requirement
+**REQUIRED:** Use superpowers:test-driven-development before proceeding
+
+**RECOMMENDED:** See typescript-type-safety for proper type guards
+
+# ❌ BAD - Unclear if required
+See skills/testing/test-driven-development
+
+# ❌ BAD - Force-loads file, wastes context
+@skills/testing/test-driven-development/SKILL.md
+```
+
+## Advanced Practices
+
+### Iterative Development
+
+**Best approach**: Develop skills iteratively with Claude
+1. Start with minimal viable skill
+2. Test with real use cases
+3. Refine based on what works
+4. Remove what doesn't add value
+
+### Build Evaluations First
+
+Before extensive documentation:
+1. Create test scenarios
+2. Identify what good looks like
+3. Document proven patterns
+4. Skip theoretical improvements
+
+### Utility Scripts
+
+For reliability, provide:
+- Scripts with explicit error handling (don't defer errors to Claude)
+- Exit codes for success/failure
+- Clear error messages
+- Examples of usage
+- List required dependencies explicitly
+
+**Example:**
+```bash
+#!/bin/bash
+set -e  # Exit on error
+
+if [ ! -f "config.json" ]; then
+  echo "Error: config.json not found" >&2
+  exit 1
+fi
+
+# Script logic here
+echo "Success"
+exit 0
+```
+
+### Verifiable Intermediate Outputs
+
+For complex operations, create validation checkpoints:
+1. Have Claude produce a structured plan file
+2. Validate the plan with a script
+3. Execute only after validation passes
+
+This catches errors before they compound.
+
+### Templates for Structured Output
+
+When skills produce consistent formats:
+```markdown
+## Output Template
+
+\`\`\`typescript
+interface ExpectedOutput {
+  status: 'success' | 'error';
+  data: YourDataType;
+  errors?: string[];
+}
+\`\`\`
+
+**Usage**: Copy and adapt for your context
+```
+
+## Skill Creation Checklist
+
+**Before writing:**
+- [ ] Technique isn't obvious or well-documented elsewhere
+- [ ] Pattern applies broadly (not project-specific)
+- [ ] I would reference this across multiple projects
+
+**Frontmatter:**
+- [ ] Name uses only letters, numbers, hyphens
+- [ ] Description starts with "Use when..."
+- [ ] Description includes triggers AND what skill does
+- [ ] Description is third person
+- [ ] Total frontmatter < 1024 characters
+
+**Content:**
+- [ ] Overview states core principle (1-2 sentences)
+- [ ] "When to Use" section with symptoms
+- [ ] Quick reference table for common operations
+- [ ] One excellent code example (if technique skill)
+- [ ] Common mistakes section
+- [ ] Keywords throughout for searchability
+
+**Quality:**
+- [ ] Word count appropriate for frequency (see targets above)
+- [ ] SKILL.md under 500 lines
+- [ ] No narrative storytelling
+- [ ] Flowcharts only for non-obvious decisions
+- [ ] Supporting files only if needed (100+ lines reference)
+- [ ] Cross-references use skill name, not file paths
+- [ ] No time-sensitive information
+- [ ] Consistent terminology throughout
+- [ ] Concrete examples (not templates)
+- [ ] Degrees of freedom match task complexity
+
+**Testing:**
+- [ ] Tested with Claude Haiku, Sonnet, and Opus (instructions effective for Opus may need more detail for Haiku)
+- [ ] Tested with subagent scenarios (if discipline-enforcing skill)
+- [ ] Addresses common rationalizations
+- [ ] Includes red flags list
+
+## Directory Structure
+
+```
+skills/
+  skill-name/
+    SKILL.md              # Required
+    supporting-file.*     # Optional
+    examples/             # Optional
+      example1.ts
+    scripts/              # Optional
+      helper.py
+```
+
+**Flat namespace** - all skills in one searchable directory
+
+## Real-World Impact
+
+**Good skills:**
+- Future Claude finds them quickly (CSO optimization)
+- Can be scanned in seconds (quick reference)
+- Provide clear actionable examples
+- Prevent repeating same research
+- Stay under 500 lines (token efficient)
+- Match specificity to task needs (right degrees of freedom)
+
+**Bad skills:**
+- Get ignored (vague description)
+- Take too long to evaluate (no quick reference)
+- Leave gaps in understanding (no examples)
+- Waste token budget (verbose explanations of obvious things)
+- Over-constrain creative tasks or under-specify critical operations
+- Include time-sensitive or obsolete information
+
+---
+
+**Remember:** Skills are for future Claude, not current you. Optimize for discovery, scanning, and action.
+
+**Golden rule:** Default assumption is Claude is already very smart. Only add context Claude doesn't already have.
\ No newline at end of file
diff --git a/.claude/skills/debugging-websocket-issues/SKILL.md b/.claude/skills/debugging-websocket-issues/SKILL.md
new file mode 100644
index 000000000..95e8d7c4c
--- /dev/null
+++ b/.claude/skills/debugging-websocket-issues/SKILL.md
@@ -0,0 +1,128 @@
+---
+name: debugging-websocket-issues
+description: Use when seeing WebSocket errors like "Invalid frame header", "RSV1 must be clear", or "WS_ERR_UNEXPECTED_RSV_1" - covers multiple WebSocketServer conflicts, compression issues, and raw frame debugging techniques
+tags: websocket, debugging, ws, node
+---
+
+# Debugging WebSocket Issues
+
+## Overview
+
+WebSocket "invalid frame header" errors often stem from raw HTTP being written to an upgraded socket, not actual frame corruption. The most common cause is multiple `WebSocketServer` instances conflicting on the same HTTP server.
+
+## When to Use
+
+- Error: `Invalid WebSocket frame: RSV1 must be clear`
+- Error: `WS_ERR_UNEXPECTED_RSV_1`
+- Error: `Invalid frame header`
+- WebSocket connects then immediately disconnects with code 1006
+- Server logs success but client receives garbage data
+
+## Quick Reference
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| RSV1 must be clear | Multiple WSS on same server OR compression mismatch | Use `noServer: true` mode |
+| Hex starts with `48545450` | Raw HTTP on WebSocket (0x48='H') | Check for conflicting upgrade handlers |
+| Code 1006, no reason | Abnormal closure, often server-side abort | Check `abortHandshake` calls |
+| Works isolated, fails in app | Something else writing to socket | Audit all upgrade listeners |
+
+## The Multiple WebSocketServer Bug
+
+### Problem
+
+When attaching multiple `WebSocketServer` instances to the same HTTP server using the `server` option:
+
+```typescript
+// ❌ BAD - Both servers add upgrade listeners, causing conflicts
+const wss1 = new WebSocketServer({ server, path: '/ws' });
+const wss2 = new WebSocketServer({ server, path: '/ws/other' });
+```
+
+**What happens:**
+1. Client connects to `/ws`
+2. BOTH upgrade handlers fire (Node.js EventEmitter calls all listeners)
+3. `wss1` matches path, handles upgrade successfully
+4. `wss2` doesn't match, calls `abortHandshake(socket, 400)`
+5. Raw `HTTP/1.1 400 Bad Request` written to the now-WebSocket socket
+6. Client receives HTTP text as WebSocket frame data
+7. First byte `0x48` ('H') interpreted as: RSV1=1, opcode=8 → invalid frame
+
+### Solution
+
+Use `noServer: true` and manually route upgrades:
+
+```typescript
+// ✅ GOOD - Single upgrade handler routes to correct server
+const wss1 = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+const wss2 = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+
+server.on('upgrade', (request, socket, head) => {
+  const pathname = new URL(request.url || '', `http://${request.headers.host}`).pathname;
+
+  if (pathname === '/ws') {
+    wss1.handleUpgrade(request, socket, head, (ws) => {
+      wss1.emit('connection', ws, request);
+    });
+  } else if (pathname === '/ws/other') {
+    wss2.handleUpgrade(request, socket, head, (ws) => {
+      wss2.emit('connection', ws, request);
+    });
+  } else {
+    socket.destroy();
+  }
+});
+```
+
+## Debugging Techniques
+
+### Raw Frame Inspection
+
+Hook into the socket to see actual bytes received:
+
+```typescript
+ws.on('open', () => {
+  const socket = ws._socket;
+  const originalPush = socket.push.bind(socket);
+
+  socket.push = function(chunk, encoding) {
+    if (chunk) {
+      console.log('First 20 bytes (hex):', chunk.slice(0, 20).toString('hex'));
+      const byte0 = chunk[0];
+      console.log(`FIN: ${!!(byte0 & 0x80)}, RSV1: ${!!(byte0 & 0x40)}, Opcode: ${byte0 & 0x0f}`);
+
+      // Check if it's actually HTTP text
+      if (chunk.slice(0, 4).toString() === 'HTTP') {
+        console.log('*** RECEIVED RAW HTTP ON WEBSOCKET ***');
+      }
+    }
+    return originalPush(chunk, encoding);
+  };
+});
+```
+
+### Key Hex Patterns
+
+- `81` = FIN + text frame (normal)
+- `82` = FIN + binary frame (normal)
+- `88` = FIN + close frame (normal)
+- `48545450` = "HTTP" - raw HTTP on WebSocket (bug!)
+- `c1` or similar with bit 6 set = compressed frame (RSV1=1)
+
+## Common Mistakes
+
+| Mistake | Result | Fix |
+|---------|--------|-----|
+| Multiple WSS with `server` option | HTTP 400 written to socket | Use `noServer: true` |
+| `perMessageDeflate: true` (default in older ws) | RSV1 set on frames | Explicitly set `perMessageDeflate: false` |
+| Not checking upgrade headers | Miss compression negotiation | Log `sec-websocket-extensions` header |
+| Assuming RSV1 error = compression | Could be raw HTTP | Check if bytes decode as ASCII "HTTP" |
+
+## Verification Checklist
+
+After fixing, verify:
+- [ ] `RSV1: false` in frame inspection
+- [ ] `Extensions header: NONE` in upgrade response
+- [ ] No `HTTP/1.1` in raw frame data
+- [ ] Messages received match sent payload size
+- [ ] Multiple broadcasts work (test interval sends)
diff --git a/.claude/skills/frontend-design/SKILL.md b/.claude/skills/frontend-design/SKILL.md
new file mode 100644
index 000000000..43aec9ae8
--- /dev/null
+++ b/.claude/skills/frontend-design/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
diff --git a/.claude/skills/prpm-json-best-practices-skill/SKILL.md b/.claude/skills/prpm-json-best-practices-skill/SKILL.md
new file mode 100644
index 000000000..3a762c60f
--- /dev/null
+++ b/.claude/skills/prpm-json-best-practices-skill/SKILL.md
@@ -0,0 +1,1217 @@
+---
+name: prpm-json-best-practices
+description: Best practices for structuring prpm.json package manifests with required fields, tags, organization, multi-package management, enhanced file format, eager/lazy activation, and conversion hints
+---
+
+# PRPM JSON Best Practices
+
+You are an expert at creating and maintaining `prpm.json` package manifests for PRPM (Prompt Package Manager). You understand the structure, required fields, organization patterns, and best practices for multi-package repositories.
+
+## When to Apply This Skill
+
+**Use when:**
+- Creating a new `prpm.json` manifest for publishing packages
+- Maintaining existing `prpm.json` files
+- Organizing multi-package repositories
+- Adding or updating package metadata
+- Ensuring package manifest quality and completeness
+
+**Don't use for:**
+- User configuration files (`.prpmrc`) - those are for users
+- Lockfiles (`prpm.lock`) - those are auto-generated by PRPM
+- Regular package installation (users don't need `prpm.json`)
+- Dependencies already tracked in lockfiles
+
+## Core Purpose
+
+`prpm.json` is **only needed if you're publishing packages**. Regular users installing packages from the registry don't need this file.
+
+Use `prpm.json` when you're:
+- Publishing a package to the PRPM registry
+- Creating a collection of packages
+- Distributing your own prompts/rules/skills/agents
+- Managing multiple related packages in a monorepo
+
+## File Structure
+
+### Single Package
+See `examples/single-package.json` for complete structure.
+
+**Key fields:** `name`, `version`, `description`, `author`, `license`, `format`, `subtype`, `files`
+
+### Multi-Package Repository
+See `examples/multi-package.json` for complete structure.
+
+**Use when:** Publishing multiple related packages from one repo
+**Key difference:** Top-level `packages` array with individual package definitions
+
+### Collections Repository
+See `examples/collections-repository.json` for complete structure.
+
+**Use when:** Bundling existing published packages into curated collections
+**Key points:**
+- `collections` array references packages by `packageId` (not files)
+- Each collection has `id`, `name`, `description`, `packages`
+- Packages can be `required: true` (default) or `false` (optional)
+- Use version ranges (`^1.0.0`) or `latest`
+- Add `reason` to explain why package is included
+
+### Packages + Collections (Combined)
+See `examples/packages-with-collections.json` for complete structure.
+
+**Use when:** Publishing packages AND creating collections that bundle them
+**Key points:**
+- Define packages in `packages` array with files
+- Define collections in `collections` array referencing those packages
+- Collections can reference both local packages and external ones
+- Publish both individual packages and collection bundles from same repo
+
+## Required Fields
+
+### Top-Level (Single Package)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | **Yes** | Package name (kebab-case, unique in registry) |
+| `version` | string | **Yes** | Semver version (e.g., `1.0.0`) |
+| `description` | string | **Yes** | Clear description of what the package does |
+| `author` | string | **Yes** | Author name and optional email |
+| `license` | string | **Yes** | SPDX license identifier (e.g., `MIT`, `Apache-2.0`) |
+| `format` | string | **Yes** | Target format: `claude`, `cursor`, `continue`, `windsurf`, etc. |
+| `subtype` | string | **Yes** | Package type: `agent`, `skill`, `rule`, `slash-command`, `prompt`, `collection` |
+| `files` | string[] | **Yes** | Array of files to include in package |
+
+### Optional Top-Level Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `repository` | string | Git repository URL |
+| `organization` | string | Organization name (for scoped packages) |
+| `homepage` | string | Package homepage URL |
+| `documentation` | string | Documentation URL |
+| `license_text` | string | Full text of the license file for proper attribution |
+| `license_url` | string | URL to the license file in the repository |
+| `tags` | string[] | Searchable tags (kebab-case) |
+| `keywords` | string[] | Additional keywords for search |
+| `category` | string | Package category |
+| `private` | boolean | If `true`, won't be published to public registry |
+| `dependencies` | object | Package dependencies (name: semver) |
+| `scripts` | object | Lifecycle scripts (multi-package only) |
+| `eager` | boolean | If `true`, skill/agent loads at session start (not on-demand) |
+
+### Multi-Package Fields
+
+When using `packages` array:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | **Yes** | Unique package name |
+| `version` | string | **Yes** | Package version |
+| `description` | string | **Yes** | Package description |
+| `format` | string | **Yes** | Package format |
+| `subtype` | string | **Yes** | Package subtype |
+| `tags` | string[] | Recommended | Searchable tags |
+| `files` | string[] | **Yes** | Files to include |
+| `private` | boolean | No | Mark as private |
+| `eager` | boolean | No | Load at session start (skills/agents only) |
+
+### Collection Fields
+
+When using `collections` array:
+
+**Top-level (repository with collections):**
+- `name`, `version`, `description`, `author`, `license` - **Required**
+- `repository`, `organization` - Recommended
+- Note: No `format`, `subtype`, or `files` required at top level
+
+**Each collection object:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | **Yes** | Unique collection identifier (kebab-case, 3-100 chars) |
+| `name` | string | **Yes** | Display name (3-100 chars) |
+| `description` | string | **Yes** | What the collection provides (10-500 chars) |
+| `packages` | array | **Yes** | Array of packages to include (minimum 1) |
+| `version` | string | Recommended | Semantic version of collection |
+| `category` | string | Recommended | Collection category (development, testing, etc.) |
+| `tags` | string[] | Recommended | Searchable tags (kebab-case, 1-10 items) |
+| `icon` | string | Optional | Emoji or icon (max 10 chars) |
+
+**Each package within collection:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `packageId` | string | **Yes** | Package to include |
+| `version` | string | Optional | Version range (^1.0.0, ~2.1.0, 1.0.0, latest) |
+| `required` | boolean | Optional | Whether package is required (default: true) |
+| `reason` | string | Optional | Why package is included (max 200 chars) |
+
+## Format and Subtype Values
+
+### Format (Target AI Tool)
+
+| Format | Description |
+|--------|-------------|
+| `claude` | Claude Code (agents, skills) |
+| `cursor` | Cursor IDE (rules, MDC files) |
+| `continue` | Continue.dev extension |
+| `windsurf` | Windsurf IDE |
+| `copilot` | GitHub Copilot |
+| `kiro` | Kiro IDE |
+| `agents.md` | Agents.md format |
+| `generic` | Generic/universal format |
+| `mcp` | Model Context Protocol |
+
+### Subtype (Package Type)
+
+| Subtype | Description | Typical Formats |
+|---------|-------------|-----------------|
+| `agent` | Autonomous agents | `claude`, `agents.md` |
+| `skill` | Specialized capabilities | `claude` |
+| `rule` | IDE rules and guidelines | `cursor`, `windsurf` |
+| `slash-command` | Slash commands | `cursor`, `continue` |
+| `prompt` | Prompt templates | `generic` |
+| `collection` | Package collections | Any |
+| `chatmode` | Chat modes | `kiro` |
+| `tool` | MCP tools | `mcp` |
+
+## Eager vs Lazy Activation
+
+Skills and agents can be configured to load eagerly (at session start) or lazily (on-demand when relevant).
+
+### When to Use Eager
+
+**Use `eager: true` when:**
+- The skill should ALWAYS be active (coding standards, style guides)
+- Critical behavior that must never be skipped
+- Small, foundational skills with minimal token cost
+
+**Keep lazy (default) when:**
+- Specialized skills for specific contexts
+- Large skills with significant token overhead
+- Skills that only apply to certain file types
+
+### Setting Eager in prpm.json
+
+**Package-level:**
+```json
+{
+  "name": "code-style-enforcer",
+  "version": "1.0.0",
+  "format": "claude",
+  "subtype": "skill",
+  "eager": true,
+  "files": [".claude/skills/code-style/SKILL.md"]
+}
+```
+
+**File-level (enhanced files format):**
+```json
+{
+  "files": [
+    {
+      "path": ".claude/skills/critical-skill/SKILL.md",
+      "format": "claude",
+      "subtype": "skill",
+      "eager": true
+    },
+    {
+      "path": ".claude/skills/optional-skill/SKILL.md",
+      "format": "claude",
+      "subtype": "skill",
+      "eager": false
+    }
+  ]
+}
+```
+
+### Precedence
+
+When installing, the final eager setting is determined by:
+1. CLI flag (`--eager`/`--lazy`) - highest priority
+2. File-level `eager` setting (enhanced files)
+3. Package-level `eager` setting
+4. Default: lazy (false)
+
+### Applicable Subtypes
+
+| Subtype | Supports Eager |
+|---------|----------------|
+| `skill` | Yes |
+| `agent` | Yes |
+| `rule` | No |
+| `slash-command` | No |
+| `hook` | No |
+
+Eager loading only affects progressive disclosure formats (agents.md, gemini.md, claude.md, aider).
+
+## Tags Best Practices
+
+### Tag Structure
+
+- Use **kebab-case** for all tags
+- Be **specific** and **searchable**
+- Include 3-8 tags per package
+- Combine technology, domain, and purpose tags
+
+### Tag Categories
+
+**Technology Tags:**
+- Languages: `typescript`, `python`, `javascript`, `rust`
+- Frameworks: `react`, `nextjs`, `fastify`, `django`
+- Tools: `aws`, `docker`, `kubernetes`, `postgresql`
+
+**Domain Tags:**
+- `deployment`, `testing`, `ci-cd`, `database`
+- `infrastructure`, `cloud`, `monitoring`
+- `documentation`, `code-review`, `security`
+
+**Purpose Tags:**
+- `troubleshooting`, `debugging`, `best-practices`
+- `automation`, `quality-assurance`, `performance`
+- `architecture`, `design-patterns`
+
+**Meta Tags:**
+- `meta` - For packages about creating packages
+- `prpm-internal` - For internal/private packages
+- `prpm-development` - For PRPM development itself
+
+### Tag Examples
+
+**Good Tags:**
+```json
+{
+  "tags": [
+    "typescript",
+    "type-safety",
+    "code-quality",
+    "best-practices",
+    "static-analysis"
+  ]
+}
+```
+
+**Poor Tags:**
+```json
+{
+  "tags": [
+    "code",  // Too generic
+    "stuff", // Meaningless
+    "TypeScript", // Wrong case
+    "type_safety"  // Wrong format (use kebab-case)
+  ]
+}
+```
+
+## Organization Best Practices
+
+### Multi-Package Organization
+
+**Order packages by:**
+1. **Privacy** - Private packages first
+2. **Format** - Group by format (claude, cursor, etc.)
+3. **Subtype** - Group by subtype (agent, skill, rule)
+
+**Example organization:**
+
+```json
+{
+  "packages": [
+    // Private > Claude > Agents
+    { "name": "internal-agent", "private": true, "format": "claude", "subtype": "agent" },
+
+    // Private > Claude > Skills
+    { "name": "internal-skill", "private": true, "format": "claude", "subtype": "skill" },
+
+    // Private > Cursor > Rules
+    { "name": "internal-rule", "private": true, "format": "cursor", "subtype": "rule" },
+
+    // Public > Claude > Skills
+    { "name": "public-skill", "format": "claude", "subtype": "skill" },
+
+    // Public > Cursor > Rules
+    { "name": "public-rule", "format": "cursor", "subtype": "rule" }
+  ]
+}
+```
+
+### Naming Conventions
+
+**Package Names:**
+- Use **kebab-case**: `my-awesome-skill`
+- Be **descriptive**: `typescript-type-safety` not `ts-types`
+- Avoid duplicates across formats: use suffixes if needed
+  - `format-conversion-agent` (Claude agent)
+  - `format-conversion` (Cursor rule)
+
+**File Paths:**
+- Use **full paths from project root** (where prpm.json lives)
+- Agents: `.claude/agents/name.md`
+- Skills: `.claude/skills/name/SKILL.md`
+- Rules: `.cursor/rules/name.mdc`
+- Commands: `.claude/commands/category/name.md`
+
+## Version Management
+
+### Semver Guidelines
+
+Follow semantic versioning:
+
+- **Major (1.0.0 → 2.0.0)**: Breaking changes
+- **Minor (1.0.0 → 1.1.0)**: New features, backward compatible
+- **Patch (1.0.0 → 1.0.1)**: Bug fixes, backward compatible
+
+### Version Bumping
+
+When to bump versions:
+- **Patch**: Bug fixes, typo corrections, minor improvements
+- **Minor**: New sections, additional examples, new features
+- **Major**: Complete rewrites, breaking changes, renamed fields
+
+### Keep Versions in Sync
+
+For multi-package repos, keep related packages in sync:
+```json
+{
+  "packages": [
+    { "name": "pkg-one", "version": "1.2.0" },
+    { "name": "pkg-two", "version": "1.2.0" },
+    { "name": "pkg-three", "version": "1.2.0" }
+  ]
+}
+```
+
+## File Management
+
+### Files Array
+
+**CRITICAL: File paths must be full paths from project root (where prpm.json lives).**
+
+**Required:**
+- List all files to include in the package
+- Use **full paths from project root** - not relative to destination directories
+- Paths should start with `.claude/`, `.cursor/`, etc.
+- Include documentation files
+
+**Why Full Paths?**
+File paths in `prpm.json` are used for:
+1. **Tarball creation** - Reads files directly from these paths
+2. **Snippet extraction** - Shows file preview before install
+3. **Installation** - CLI derives destination from format/subtype
+
+**Examples:**
+
+Claude agent (single file):
+```json
+{
+  "format": "claude",
+  "subtype": "agent",
+  "files": [".claude/agents/my-agent.md"]
+}
+```
+
+Claude skill (multiple files):
+```json
+{
+  "format": "claude",
+  "subtype": "skill",
+  "files": [
+    ".claude/skills/my-skill/SKILL.md",
+    ".claude/skills/my-skill/EXAMPLES.md",
+    ".claude/skills/my-skill/README.md"
+  ]
+}
+```
+
+Cursor rule:
+```json
+{
+  "format": "cursor",
+  "subtype": "rule",
+  "files": [".cursor/rules/my-rule.mdc"]
+}
+```
+
+Slash command:
+```json
+{
+  "format": "claude",
+  "subtype": "slash-command",
+  "files": [".claude/commands/category/my-command.md"]
+}
+```
+
+### Enhanced File Format
+
+**Advanced:** Files can be objects with metadata instead of simple strings. Useful for packages with multiple files targeting different formats or needing per-file metadata.
+
+**Enhanced file object structure:**
+```json
+{
+  "files": [
+    {
+      "path": ".cursor/rules/typescript.mdc",
+      "format": "cursor",
+      "subtype": "rule",
+      "name": "TypeScript Rules",
+      "description": "TypeScript coding standards and best practices",
+      "tags": ["typescript", "frontend"]
+    },
+    {
+      "path": ".cursor/rules/python.mdc",
+      "format": "cursor",
+      "subtype": "rule",
+      "name": "Python Rules",
+      "description": "Python best practices for backend development",
+      "tags": ["python", "backend"]
+    }
+  ]
+}
+```
+
+**When to use enhanced format:**
+- Multi-file packages with different formats/subtypes per file
+- Need per-file descriptions or tags
+- Want to provide display names for individual files
+- Building collection packages with mixed content types
+
+**Enhanced file fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `path` | **Yes** | Relative path to file from project root |
+| `format` | **Yes** | File's target format (`cursor`, `claude`, etc.) |
+| `subtype` | No | File's subtype (`rule`, `skill`, `agent`, etc.) |
+| `name` | No | Display name for this file |
+| `description` | No | Description of what this file does |
+| `tags` | No | File-specific tags (array of strings) |
+
+**Note:** Cannot mix simple strings and objects in the same `files` array. Use all strings OR all objects, not both.
+
+**Common Mistake:**
+```json
+{
+  // ❌ WRONG - Relative paths without directory prefix
+  "files": ["agents/my-agent.md"]  // Will fail to find file
+
+  // ✅ CORRECT - Full path from project root
+  "files": [".claude/agents/my-agent.md"]
+}
+```
+
+### File Verification
+
+Always verify files exist:
+```bash
+# Check all files in prpm.json exist
+for file in $(cat prpm.json | jq -r '.packages[].files[]'); do
+  if [ ! -f "$file" ]; then
+    echo "Missing: $file"
+  fi
+done
+```
+
+## Duplicate Detection
+
+### Check for Duplicate Names
+
+Run this check before committing:
+
+```bash
+# Check for duplicate package names
+cat prpm.json | jq -r '.packages[].name' | sort | uniq -d
+```
+
+If output is empty, no duplicates exist. If names appear, you have duplicates to resolve.
+
+### Resolving Duplicates
+
+**Bad:**
+```json
+{
+  "packages": [
+    { "name": "typescript-safety", "format": "claude" },
+    { "name": "typescript-safety", "format": "cursor" }
+  ]
+}
+```
+
+**Good:**
+```json
+{
+  "packages": [
+    { "name": "typescript-safety", "format": "claude", "subtype": "skill" },
+    { "name": "typescript-safety-rule", "format": "cursor", "subtype": "rule" }
+  ]
+}
+```
+
+## Conversion Hints (Advanced)
+
+**Purpose:** Help improve quality when converting packages to other formats. The `conversion` field provides format-specific hints for cross-format transformations.
+
+**Note:** This is an advanced feature primarily used by format conversion tools. Most packages don't need this.
+
+**Structure:**
+
+```json
+{
+  "name": "my-package",
+  "version": "1.0.0",
+  "format": "claude",
+  "conversion": {
+    "cursor": {
+      "alwaysApply": false,
+      "priority": "high",
+      "globs": ["**/*.ts", "**/*.tsx"]
+    },
+    "kiro": {
+      "inclusion": "fileMatch",
+      "fileMatchPattern": "**/*.ts",
+      "domain": "typescript",
+      "tools": ["fs_read", "fs_write"],
+      "mcpServers": {
+        "database": {
+          "command": "mcp-server-postgres",
+          "args": [],
+          "env": {
+            "DATABASE_URL": "${DATABASE_URL}"
+          }
+        }
+      }
+    },
+    "copilot": {
+      "applyTo": ["src/**", "lib/**"],
+      "excludeAgent": "code-review"
+    }
+  }
+}
+```
+
+**Supported conversion hints:**
+
+### Cursor Hints
+```json
+{
+  "conversion": {
+    "cursor": {
+      "alwaysApply": boolean,      // Whether rule should always apply
+      "priority": "high|medium|low", // Rule priority level
+      "globs": ["**/*.ts"]         // File patterns to auto-attach
+    }
+  }
+}
+```
+
+### Claude Hints
+```json
+{
+  "conversion": {
+    "claude": {
+      "model": "sonnet|opus|haiku|inherit", // Preferred model
+      "tools": ["Read", "Write"],          // Allowed tools
+      "subagentType": "format-conversion"  // Subagent type if agent
+    }
+  }
+}
+```
+
+### Kiro Hints
+```json
+{
+  "conversion": {
+    "kiro": {
+      "inclusion": "always|fileMatch|manual", // When to include
+      "fileMatchPattern": "**/*.ts",         // Pattern for fileMatch mode
+      "domain": "typescript",                // Domain category
+      "tools": ["fs_read", "fs_write"],     // Available tools
+      "mcpServers": {                        // MCP server configs
+        "database": {
+          "command": "mcp-server-postgres",
+          "args": [],
+          "env": { "DATABASE_URL": "${DATABASE_URL}" }
+        }
+      }
+    }
+  }
+}
+```
+
+### Copilot Hints
+```json
+{
+  "conversion": {
+    "copilot": {
+      "applyTo": "src/**",                         // Path patterns
+      "excludeAgent": "code-review|coding-agent"  // Agent to exclude
+    }
+  }
+}
+```
+
+### Continue Hints
+```json
+{
+  "conversion": {
+    "continue": {
+      "alwaysApply": boolean,           // Always apply rule
+      "globs": ["**/*.ts"],             // File patterns
+      "regex": ["import.*from"]         // Regex patterns
+    }
+  }
+}
+```
+
+### Windsurf Hints
+```json
+{
+  "conversion": {
+    "windsurf": {
+      "characterLimit": 12000  // Warn if exceeding limit
+    }
+  }
+}
+```
+
+### Agents.md Hints
+```json
+{
+  "conversion": {
+    "agentsMd": {
+      "project": "my-project",  // Project name
+      "scope": "backend"        // Scope/domain
+    }
+  }
+}
+```
+
+**When to use conversion hints:**
+- Publishing cross-format packages that need specific settings per format
+- Format conversion tools need guidance on how to transform content
+- Package behavior should change based on target format
+- Want to preserve format-specific metadata during conversions
+
+## Common Patterns
+
+### Private Internal Packages
+
+```json
+{
+  "name": "internal-tool",
+  "version": "1.0.0",
+  "description": "Internal development tool",
+  "private": true,
+  "format": "claude",
+  "subtype": "skill",
+  "tags": ["prpm-internal", "development"],
+  "files": [".claude/skills/internal-tool/SKILL.md"]
+}
+```
+
+### Meta Packages (Creating Other Packages)
+
+```json
+{
+  "name": "creating-skills",
+  "version": "1.0.0",
+  "description": "Guide for creating effective Claude Code skills",
+  "format": "claude",
+  "subtype": "skill",
+  "tags": ["meta", "claude-code", "skills", "documentation", "best-practices"],
+  "files": [".claude/skills/creating-skills/SKILL.md"]
+}
+```
+
+### Cross-Format Packages
+
+When you have the same content for multiple formats:
+
+```json
+{
+  "packages": [
+    {
+      "name": "format-conversion-agent",
+      "format": "claude",
+      "subtype": "agent",
+      "description": "Agent for converting between AI prompt formats",
+      "files": [".claude/agents/format-conversion.md"]
+    },
+    {
+      "name": "format-conversion",
+      "format": "cursor",
+      "subtype": "rule",
+      "description": "Rule for converting between AI prompt formats",
+      "files": [".cursor/rules/format-conversion.mdc"]
+    }
+  ]
+}
+```
+
+### Collections in prpm.json
+
+Collections CAN be defined in prpm.json alongside packages using the `collections` array. Collections bundle multiple packages together for easier installation.
+
+**Example with both packages and collections:**
+
+```json
+{
+  "name": "my-prompts-repo",
+  "author": "Your Name",
+  "license": "MIT",
+  "packages": [
+    {
+      "name": "typescript-rules",
+      "version": "1.0.0",
+      "description": "TypeScript best practices",
+      "format": "cursor",
+      "subtype": "rule",
+      "tags": ["typescript"],
+      "files": [".cursor/rules/typescript.mdc"]
+    }
+  ],
+  "collections": [
+    {
+      "id": "my-dev-setup",
+      "name": "My Development Setup",
+      "description": "Complete development setup with TypeScript and React",
+      "version": "1.0.0",
+      "category": "development",
+      "tags": ["typescript", "react"],
+      "packages": [
+        {
+          "packageId": "typescript-strict",
+          "version": "^1.0.0",
+          "required": true,
+          "reason": "Enforces strict TypeScript type safety"
+        },
+        {
+          "packageId": "react-best-practices",
+          "version": "^2.0.0",
+          "required": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+For more details on creating collections, see the PRPM documentation at https://docs.prpm.dev or run `prpm help collections`.
+
+**Summary:** `prpm.json` can contain both packages (skills, agents, rules, slash-commands, etc.) and collections.
+
+## Lifecycle Scripts
+
+**IMPORTANT:** The `scripts` field only applies to **multi-package manifests** (prpm.json with a `packages` array). It does NOT work in single-package manifests.
+
+Use the `scripts` field to run commands automatically during package operations, particularly for building TypeScript hooks before publishing.
+
+### When to Use Scripts
+
+**Primary use case: Building TypeScript Hooks**
+
+If your packages include Claude Code hooks written in TypeScript, you MUST build them to JavaScript before publishing:
+
+```json
+{
+  "name": "my-packages",
+  "license": "MIT",
+  "scripts": {
+    "prepublishOnly": "cd packages/hooks && npm run build"
+  },
+  "packages": [
+    {
+      "name": "my-hook",
+      "version": "1.0.0",
+      "format": "claude",
+      "subtype": "hook",
+      "files": [
+        ".claude/hooks/my-hook/hook.ts",
+        ".claude/hooks/my-hook/hook.json",
+        ".claude/hooks/my-hook/dist/hook.js"
+      ]
+    }
+  ]
+}
+```
+
+### Available Script Types
+
+| Script | When it Runs | Use Case |
+|--------|--------------|----------|
+| `prepublishOnly` | Before `prpm publish` only | **Recommended** - Build hooks, compile assets |
+| `prepublish` | Before publish AND on npm install | **Not recommended** - causes unexpected builds |
+
+**Always use `prepublishOnly` instead of `prepublish`** to avoid running builds when users install your packages.
+
+### prepublishOnly Examples
+
+**Single hook:**
+```json
+{
+  "scripts": {
+    "prepublishOnly": "cd .claude/hooks/my-hook && npm run build"
+  }
+}
+```
+
+**Multiple hooks:**
+```json
+{
+  "scripts": {
+    "prepublishOnly": "cd .claude/hooks/hook-one && npm run build && cd ../hook-two && npm run build"
+  }
+}
+```
+
+**With tests:**
+```json
+{
+  "scripts": {
+    "prepublishOnly": "npm test && cd packages/hooks && npm run build"
+  }
+}
+```
+
+### What Happens During Publishing
+
+When you run `prpm publish`:
+
+1. PRPM checks for `scripts.prepublishOnly` in your prpm.json
+2. If found, runs the script from the directory containing prpm.json
+3. If script succeeds (exit code 0), publishing continues
+4. If script fails (non-zero exit code), publishing is aborted
+
+**Script execution details:**
+- Working directory: Same directory as prpm.json
+- Timeout: 5 minutes (300,000ms) default
+- Environment: Inherits your shell's environment variables
+- Output: Shown in real-time
+
+### Best Practices for Scripts
+
+**DO:**
+- ✅ Use `prepublishOnly` for building hooks
+- ✅ Chain commands with `&&` for dependencies: `npm test && npm run build`
+- ✅ Keep scripts fast (under 1 minute if possible)
+- ✅ Test scripts locally before publishing
+
+**DON'T:**
+- ❌ Use `prepublish` (runs on install too)
+- ❌ Forget to build hooks before publishing
+- ❌ Use scripts in single-package manifests (not supported)
+- ❌ Put long-running operations in scripts
+
+### Common Patterns
+
+**Hooks in packages/ directory:**
+```json
+{
+  "scripts": {
+    "prepublishOnly": "cd packages/hooks && npm run build"
+  }
+}
+```
+
+**Hooks in .claude/ directory:**
+```json
+{
+  "scripts": {
+    "prepublishOnly": "cd .claude/hooks/my-hook && npm run build"
+  }
+}
+```
+
+**Build multiple components:**
+```json
+{
+  "scripts": {
+    "prepublishOnly": "npm run build:hooks && npm run build:assets"
+  }
+}
+```
+
+### Debugging Script Failures
+
+If your prepublishOnly script fails:
+
+1. **Check the output** - Error messages show what went wrong
+2. **Run manually** - Test the exact command in your terminal
+3. **Verify working directory** - Scripts run from prpm.json location
+4. **Check dependencies** - Ensure npm packages are installed
+
+**Example debugging:**
+```bash
+# Test your prepublishOnly script manually
+cd /path/to/prpm.json/directory
+cd packages/hooks && npm run build
+
+# If it works manually but fails in PRPM, check:
+# - Working directory assumptions
+# - Environment variables
+# - Installed dependencies
+```
+
+### Why This Matters
+
+**Without prepublishOnly:**
+- You might forget to build hooks before publishing
+- Published packages contain stale/outdated JavaScript
+- Users install broken hooks
+- Manual builds are error-prone
+
+**With prepublishOnly:**
+- Hooks automatically build before every publish
+- JavaScript always matches TypeScript source
+- Prevents publishing broken code
+- Consistent, reliable publishing workflow
+
+## Validation Checklist
+
+Before publishing, verify:
+
+**Required Fields:**
+- [ ] All packages have `name`, `version`, `description`
+- [ ] All packages have `format` and `subtype`
+- [ ] All packages have `files` array
+- [ ] Top-level has `author` and `license`
+
+**File Verification:**
+- [ ] All files in `files` arrays exist
+- [ ] File paths are relative to repo root
+- [ ] No missing or broken file references
+
+**No Duplicates:**
+- [ ] No duplicate package names
+- [ ] Package names are unique across entire manifest
+
+**Tags:**
+- [ ] Tags use kebab-case
+- [ ] 3-8 relevant tags per package
+- [ ] Tags include technology, domain, and purpose
+
+**Organization:**
+- [ ] Private packages listed first
+- [ ] Packages grouped by format and subtype
+- [ ] Consistent versioning across related packages
+
+## Lockfile Management
+
+### Understanding prpm.lock
+
+The `prpm.lock` file is **auto-generated** and tracks installed packages. It serves as the source of truth for what's installed in your project.
+
+**IMPORTANT:** Do NOT add packages to `prpm.json` if they already exist in `prpm.lock`:
+
+- `prpm.lock` tracks **installed dependencies** (packages you use)
+- `prpm.json` defines **published packages** (packages you create and share)
+
+### When to Use prpm.json vs prpm.lock
+
+**Use `prpm.json` when:**
+- You're creating a package to publish to the registry
+- You want to define metadata for YOUR packages
+- You're setting up a multi-package repository
+
+**Use `prpm.lock` (auto-generated) when:**
+- You install packages with `prpm install`
+- You want to track which packages are installed
+- You want reproducible installations across environments
+
+### Common Mistake: Duplicating Dependencies
+
+**❌ WRONG - Don't add installed packages to prpm.json:**
+
+```json
+// prpm.json
+{
+  "name": "my-project",
+  "packages": [
+    {
+      "name": "typescript-safety",  // ❌ This is an INSTALLED package
+      "version": "1.0.0",
+      "format": "cursor",
+      "subtype": "rule",
+      "files": [".cursor/rules/typescript-safety.mdc"]
+    }
+  ]
+}
+```
+
+```json
+// prpm.lock (auto-generated)
+{
+  "packages": {
+    "@prpm/typescript-safety": {  // ✅ Already tracked here
+      "version": "1.0.0",
+      "format": "cursor",
+      "subtype": "rule"
+    }
+  }
+}
+```
+
+**✅ CORRECT - prpm.json only for YOUR packages:**
+
+```json
+// prpm.json - Only YOUR packages you're publishing
+{
+  "name": "my-project",
+  "packages": [
+    {
+      "name": "my-custom-rule",  // ✅ This is YOUR package
+      "version": "1.0.0",
+      "format": "cursor",
+      "subtype": "rule",
+      "files": [".cursor/rules/my-custom-rule.mdc"]
+    }
+  ]
+}
+```
+
+```json
+// prpm.lock - Installed dependencies (auto-generated)
+{
+  "packages": {
+    "@prpm/typescript-safety": {  // ✅ Installed from registry
+      "version": "1.0.0",
+      "format": "cursor",
+      "subtype": "rule"
+    }
+  }
+}
+```
+
+### Key Principles
+
+1. **Lockfile is Auto-Generated** - Never manually edit `prpm.lock`
+2. **Separation of Concerns**:
+   - `prpm.json` = What you PUBLISH
+   - `prpm.lock` = What you INSTALL
+3. **Check Lockfile First** - Before adding to `prpm.json`, check if it's already in `prpm.lock`
+4. **Trust the Lockfile** - It's the authoritative record of installed packages
+
+### Workflow Example
+
+```bash
+# Install a package (updates prpm.lock automatically)
+prpm install @prpm/typescript-safety
+
+# This creates/updates prpm.lock - DO NOT add to prpm.json!
+
+# Only create prpm.json entries for packages YOU create:
+# 1. Create your custom rule/skill/agent
+# 2. Add entry to prpm.json
+# 3. Publish with: prpm publish
+```
+
+## Publishing Workflow
+
+### 1. Validate Manifest
+
+```bash
+# Validate JSON syntax
+cat prpm.json | jq . > /dev/null
+
+# Check for duplicates
+cat prpm.json | jq -r '.packages[].name' | sort | uniq -d
+
+# Verify files exist
+# (see File Verification section)
+```
+
+### 2. Bump Versions
+
+Update version numbers for changed packages.
+
+### 3. Test Locally
+
+```bash
+# Test package installation
+prpm install . --dry-run
+```
+
+### 4. Publish
+
+```bash
+# Publish all packages
+prpm publish
+
+# Or publish specific package
+prpm publish --package my-skill
+```
+
+## Common Mistakes to Avoid
+
+### ❌ Missing Required Fields
+
+```json
+{
+  "name": "my-skill",
+  // Missing: version, description, format, subtype, files
+}
+```
+
+### ❌ Wrong Tag Format
+
+```json
+{
+  "tags": ["TypeScript", "Code_Quality", "bestPractices"]
+  // Should be: ["typescript", "code-quality", "best-practices"]
+}
+```
+
+### ❌ Duplicate Names
+
+```json
+{
+  "packages": [
+    { "name": "my-skill", "format": "claude" },
+    { "name": "my-skill", "format": "cursor" }
+    // Second should be: "my-skill-rule" or similar
+  ]
+}
+```
+
+### ❌ Missing Files
+
+```json
+{
+  "files": [".claude/skills/my-skill/SKILL.md"]
+  // But .claude/skills/my-skill/SKILL.md doesn't exist in the repo
+}
+```
+
+### ❌ Absolute Paths
+
+```json
+{
+  "files": ["/Users/me/project/.claude/skills/my-skill/SKILL.md"]
+  // Should be: ".claude/skills/my-skill/SKILL.md" (relative to project root)
+}
+```
+
+### ❌ Missing Directory Prefix
+
+```json
+{
+  "files": ["agents/my-agent.md"]
+  // Should be: ".claude/agents/my-agent.md" (include .claude/ prefix)
+}
+```
+
+## Remember
+
+- `prpm.json` is **only for publishing YOUR packages/collections**, not for installed dependencies
+- **Never add packages from `prpm.lock` to `prpm.json`** - they serve different purposes
+- `prpm.lock` tracks what you INSTALL, `prpm.json` defines what you PUBLISH
+- Use `collections` array to bundle existing packages (references by packageId)
+- Use `packages` array to define packages with files
+- Can combine both `packages` and `collections` in same repo
+- Always validate before committing
+- Keep versions in sync for related packages
+- Use consistent, searchable tags
+- Verify all file paths exist
+- Check for duplicate names
+- Follow semver for version management
+
+**Goal:** Create maintainable, well-organized package manifests and curated collections that are easy to publish and discover in the PRPM registry.
diff --git a/.claude/skills/prpm-json-best-practices-skill/examples/collections-repository.json b/.claude/skills/prpm-json-best-practices-skill/examples/collections-repository.json
new file mode 100644
index 000000000..0f2651cc4
--- /dev/null
+++ b/.claude/skills/prpm-json-best-practices-skill/examples/collections-repository.json
@@ -0,0 +1,40 @@
+{
+  "name": "@prpm/collections",
+  "version": "1.0.0",
+  "description": "Official PRPM collections for popular development workflows",
+  "author": "PRPM Team",
+  "license": "MIT",
+  "repository": "https://github.com/prpm/collections",
+  "organization": "prpm",
+  "collections": [
+    {
+      "id": "nextjs-pro",
+      "name": "Next.js Professional Setup",
+      "description": "Complete Next.js development environment with TypeScript, React best practices, and modern tooling",
+      "version": "1.0.0",
+      "category": "development",
+      "tags": ["nextjs", "react", "typescript", "frontend"],
+      "icon": "⚡",
+      "packages": [
+        {
+          "packageId": "react-best-practices",
+          "version": "^2.0.0",
+          "required": true,
+          "reason": "Core React patterns and component guidelines"
+        },
+        {
+          "packageId": "typescript-strict",
+          "version": "latest",
+          "required": true,
+          "reason": "TypeScript strict mode for type safety"
+        },
+        {
+          "packageId": "tailwind-helper",
+          "version": "^1.5.0",
+          "required": false,
+          "reason": "Optional Tailwind CSS utilities"
+        }
+      ]
+    }
+  ]
+}
diff --git a/.claude/skills/prpm-json-best-practices-skill/examples/multi-package.json b/.claude/skills/prpm-json-best-practices-skill/examples/multi-package.json
new file mode 100644
index 000000000..8f240b053
--- /dev/null
+++ b/.claude/skills/prpm-json-best-practices-skill/examples/multi-package.json
@@ -0,0 +1,29 @@
+{
+  "name": "prpm-packages",
+  "version": "1.0.0",
+  "author": "yourgithubusername",
+  "license": "MIT",
+  "repository": "https://github.com/yourgithubusername/repo",
+  "organization": "your-org",
+  "packages": [
+    {
+      "name": "package-one",
+      "version": "1.0.0",
+      "description": "Description of package one",
+      "private": true,
+      "format": "claude",
+      "subtype": "agent",
+      "tags": ["tag1", "tag2"],
+      "files": [".claude/agents/package-one.md"]
+    },
+    {
+      "name": "package-two",
+      "version": "1.0.0",
+      "description": "Description of package two",
+      "format": "cursor",
+      "subtype": "rule",
+      "tags": ["tag1", "tag3"],
+      "files": [".cursor/rules/package-two.mdc"]
+    }
+  ]
+}
diff --git a/.claude/skills/prpm-json-best-practices-skill/examples/packages-with-collections.json b/.claude/skills/prpm-json-best-practices-skill/examples/packages-with-collections.json
new file mode 100644
index 000000000..7deb0a2fe
--- /dev/null
+++ b/.claude/skills/prpm-json-best-practices-skill/examples/packages-with-collections.json
@@ -0,0 +1,51 @@
+{
+  "name": "@username/my-prompts-repo",
+  "author": "yourgithubusername",
+  "license": "MIT",
+  "repository": "https://github.com/username/my-collection",
+  "packages": [
+    {
+      "name": "tdd-skill",
+      "version": "1.0.0",
+      "description": "Guides you through TDD workflow",
+      "format": "claude",
+      "subtype": "skill",
+      "tags": ["testing", "tdd"],
+      "files": [".claude/skills/tdd.md"]
+    },
+    {
+      "name": "typescript-rules",
+      "version": "1.0.0",
+      "description": "Best practices for TypeScript development",
+      "format": "cursor",
+      "subtype": "rule",
+      "tags": ["typescript", "frontend"],
+      "files": [".cursor/rules/typescript.mdc"]
+    }
+  ],
+  "collections": [
+    {
+      "id": "testing-suite",
+      "name": "Complete Testing Suite",
+      "description": "A collection of testing tools and best practices for TDD",
+      "version": "1.0.0",
+      "category": "testing",
+      "tags": ["testing", "tdd", "productivity"],
+      "icon": "🧪",
+      "packages": [
+        {
+          "packageId": "tdd-skill",
+          "version": "^1.0.0",
+          "required": true,
+          "reason": "Essential TDD workflow guidance"
+        },
+        {
+          "packageId": "@external/test-runner",
+          "version": "^2.0.0",
+          "required": false,
+          "reason": "Optional external test runner"
+        }
+      ]
+    }
+  ]
+}
diff --git a/.claude/skills/prpm-json-best-practices-skill/examples/single-package.json b/.claude/skills/prpm-json-best-practices-skill/examples/single-package.json
new file mode 100644
index 000000000..e0e6fc4c1
--- /dev/null
+++ b/.claude/skills/prpm-json-best-practices-skill/examples/single-package.json
@@ -0,0 +1,15 @@
+{
+  "name": "my-awesome-skill",
+  "version": "1.0.0",
+  "description": "Clear, concise description of what this package does",
+  "author": "yourgithubusername",
+  "license": "MIT",
+  "repository": "https://github.com/yourgithubusername/repo",
+  "organization": "your-org",
+  "format": "claude",
+  "subtype": "skill",
+  "tags": ["typescript", "best-practices", "code-quality"],
+  "files": [
+    ".claude/skills/my-awesome-skill/SKILL.md"
+  ]
+}
diff --git a/.claude/skills/prpm-json-best-practices-skill/prpm-manifest.schema.json b/.claude/skills/prpm-json-best-practices-skill/prpm-manifest.schema.json
new file mode 100644
index 000000000..da52703b1
--- /dev/null
+++ b/.claude/skills/prpm-json-best-practices-skill/prpm-manifest.schema.json
@@ -0,0 +1,758 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://prpm.dev/schemas/manifest.json",
+  "title": "PRPM Package Manifest",
+  "description": "Schema for PRPM package manifest (prpm.json)",
+  "type": "object",
+  "required": [
+    "name",
+    "version",
+    "description",
+    "format"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Package name in format: package-name or @scope/package-name",
+      "pattern": "^(@[a-z0-9-]+\\/)?[a-z0-9-]+$",
+      "minLength": 1,
+      "maxLength": 214,
+      "examples": [
+        "react-rules",
+        "@community/testing-skills",
+        "@company/cursor-rules"
+      ]
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version (semver)",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$",
+      "examples": [
+        "1.0.0",
+        "2.1.3",
+        "1.0.0-beta.1"
+      ]
+    },
+    "description": {
+      "type": "string",
+      "description": "Package description",
+      "minLength": 10,
+      "maxLength": 500
+    },
+    "format": {
+      "type": "string",
+      "description": "Package format - the AI tool/platform this package is for",
+      "enum": [
+        "cursor",
+        "claude",
+        "claude-plugin",
+        "continue",
+        "windsurf",
+        "copilot",
+        "kiro",
+        "agents.md",
+        "generic",
+        "mcp"
+      ]
+    },
+    "subtype": {
+      "type": "string",
+      "description": "Package subtype - the functional category (optional, defaults to 'rule')",
+      "enum": [
+        "rule",
+        "agent",
+        "skill",
+        "slash-command",
+        "prompt",
+        "workflow",
+        "tool",
+        "template",
+        "collection",
+        "chatmode",
+        "hook",
+        "plugin",
+        "server"
+      ]
+    },
+    "author": {
+      "description": "Package author",
+      "oneOf": [
+        {
+          "type": "string",
+          "examples": [
+            "John Doe",
+            "Jane Smith"
+          ]
+        },
+        {
+          "type": "object",
+          "required": [
+            "name"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Author name"
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "description": "Author email"
+            },
+            "url": {
+              "type": "string",
+              "format": "uri",
+              "description": "Author URL"
+            }
+          }
+        }
+      ]
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier",
+      "examples": [
+        "MIT",
+        "Apache-2.0",
+        "GPL-3.0",
+        "BSD-3-Clause"
+      ]
+    },
+    "license_text": {
+      "type": "string",
+      "description": "Full text of the license file for proper attribution"
+    },
+    "license_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to the license file in the repository"
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri",
+      "description": "Repository URL",
+      "examples": [
+        "https://github.com/username/repo"
+      ]
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri",
+      "description": "Package homepage URL"
+    },
+    "documentation": {
+      "type": "string",
+      "format": "uri",
+      "description": "Documentation URL"
+    },
+    "organization": {
+      "type": "string",
+      "description": "Organization name or ID to publish this package under. If not specified, publishes to personal account.",
+      "examples": [
+        "my-team",
+        "my-company"
+      ]
+    },
+    "private": {
+      "type": "boolean",
+      "description": "Whether the package is private. Private packages are only accessible to the owner/organization members. Defaults to false (public).",
+      "default": false
+    },
+    "eager": {
+      "type": "boolean",
+      "description": "Whether this package should be loaded eagerly (at session start) or lazily (on-demand). Only applies to skills and agents in progressive disclosure formats (AGENTS.md, GEMINI.md, etc.). Defaults to false (lazy loading).",
+      "default": false,
+      "examples": [true, false]
+    },
+    "scripts": {
+      "type": "object",
+      "description": "Lifecycle scripts that run during package operations. Only applies to multi-package manifests (prpm.json with packages array).",
+      "properties": {
+        "prepublishOnly": {
+          "type": "string",
+          "description": "Script to run before publishing (recommended - only runs on 'prpm publish')",
+          "examples": [
+            "npm run build",
+            "cd packages/hooks && npm run build",
+            "npm test && npm run build"
+          ]
+        },
+        "prepublish": {
+          "type": "string",
+          "description": "Script to run before publishing and on npm install (not recommended - use prepublishOnly instead)",
+          "examples": [
+            "npm run build"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "tags": {
+      "type": "array",
+      "description": "Package tags for categorization",
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 10,
+      "uniqueItems": true,
+      "examples": [
+        [
+          "productivity",
+          "coding"
+        ],
+        [
+          "testing",
+          "quality"
+        ]
+      ]
+    },
+    "keywords": {
+      "type": "array",
+      "description": "Search keywords",
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 20,
+      "uniqueItems": true,
+      "examples": [
+        [
+          "ai",
+          "prompts",
+          "development"
+        ]
+      ]
+    },
+    "category": {
+      "type": "string",
+      "description": "Package category",
+      "examples": [
+        "development",
+        "productivity",
+        "testing"
+      ]
+    },
+    "files": {
+      "description": "Files to include in package. Can be simple paths or enhanced file objects with metadata.",
+      "oneOf": [
+        {
+          "type": "array",
+          "description": "Simple format: array of file paths",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "examples": [
+            [
+              "skill.md",
+              "README.md"
+            ],
+            [
+              ".cursor/rules/react.mdc",
+              "LICENSE"
+            ]
+          ]
+        },
+        {
+          "type": "array",
+          "description": "Enhanced format: array of file objects with metadata",
+          "items": {
+            "type": "object",
+            "required": [
+              "path",
+              "format"
+            ],
+            "properties": {
+              "path": {
+                "type": "string",
+                "description": "Relative path to file",
+                "examples": [
+                  ".claude/skills/tdd.md",
+                  ".cursor/rules/react.mdc",
+                  ".continue/rules/python.json"
+                ]
+              },
+              "format": {
+                "type": "string",
+                "description": "File format - the AI tool/platform this file is for",
+                "enum": [
+                  "cursor",
+                  "claude",
+                  "claude-plugin",
+                  "continue",
+                  "windsurf",
+                  "copilot",
+                  "kiro",
+                  "agents.md",
+                  "generic",
+                  "mcp"
+                ]
+              },
+              "subtype": {
+                "type": "string",
+                "description": "File subtype - the functional category",
+                "enum": [
+                  "rule",
+                  "agent",
+                  "skill",
+                  "slash-command",
+                  "prompt",
+                  "workflow",
+                  "tool",
+                  "template",
+                  "collection",
+                  "chatmode",
+                  "hook",
+                  "plugin",
+                  "server"
+                ]
+              },
+              "name": {
+                "type": "string",
+                "description": "Display name for this file",
+                "examples": [
+                  "React Rules",
+                  "Test-Driven Development"
+                ]
+              },
+              "description": {
+                "type": "string",
+                "description": "Description of what this file does"
+              },
+              "tags": {
+                "type": "array",
+                "description": "File-specific tags",
+                "items": {
+                  "type": "string"
+                },
+                "uniqueItems": true,
+                "examples": [
+                  [
+                    "react",
+                    "typescript"
+                  ],
+                  [
+                    "testing",
+                    "tdd"
+                  ]
+                ]
+              },
+              "eager": {
+                "type": "boolean",
+                "description": "File-level eager setting. Overrides package-level eager for this specific file.",
+                "default": false
+              }
+            },
+            "additionalProperties": false
+          },
+          "minItems": 1
+        }
+      ]
+    },
+    "main": {
+      "type": "string",
+      "description": "Main entry file (for single-file packages)",
+      "examples": [
+        "index.md",
+        "skill.md"
+      ]
+    },
+    "dependencies": {
+      "type": "object",
+      "description": "Package dependencies",
+      "patternProperties": {
+        "^(@[a-z0-9-]+\\/)?[a-z0-9-]+$": {
+          "type": "string",
+          "pattern": "^(\\^|~)?\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$"
+        }
+      },
+      "additionalProperties": false,
+      "examples": [
+        {
+          "@pr-pm/utils": "^1.0.0",
+          "common-rules": "~2.1.0"
+        }
+      ]
+    },
+    "peerDependencies": {
+      "type": "object",
+      "description": "Peer dependencies (packages that should be installed alongside)",
+      "patternProperties": {
+        "^(@[a-z0-9-]+\\/)?[a-z0-9-]+$": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "engines": {
+      "type": "object",
+      "description": "Required engine versions",
+      "properties": {
+        "prpm": {
+          "type": "string",
+          "description": "Required PRPM version"
+        },
+        "node": {
+          "type": "string",
+          "description": "Required Node.js version"
+        }
+      },
+      "additionalProperties": false,
+      "examples": [
+        {
+          "prpm": ">=1.0.0",
+          "node": ">=18.0.0"
+        }
+      ]
+    },
+    "packages": {
+      "type": "array",
+      "description": "Array of packages to publish from a single manifest (multi-package publishing). Packages inherit top-level fields unless overridden.",
+      "items": {
+        "$ref": "#"
+      },
+      "minItems": 1
+    },
+    "collections": {
+      "type": "array",
+      "description": "Array of collections to publish. Collections bundle multiple packages together for easier installation.",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "description", "packages"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique collection identifier (kebab-case)",
+            "pattern": "^[a-z0-9-]+$",
+            "minLength": 3,
+            "maxLength": 100,
+            "examples": ["nextjs-complete", "fullstack-setup", "react-essentials"]
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name of the collection",
+            "minLength": 3,
+            "maxLength": 100,
+            "examples": ["Next.js Complete", "Full Stack Setup"]
+          },
+          "description": {
+            "type": "string",
+            "description": "What this collection provides",
+            "minLength": 10,
+            "maxLength": 500
+          },
+          "version": {
+            "type": "string",
+            "description": "Semantic version of the collection",
+            "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$",
+            "examples": ["1.0.0", "2.1.0"]
+          },
+          "category": {
+            "type": "string",
+            "description": "Collection category",
+            "enum": ["development", "testing", "deployment", "data-science", "devops", "design", "documentation", "security", "performance", "general"],
+            "examples": ["development", "testing"]
+          },
+          "tags": {
+            "type": "array",
+            "description": "Tags for discoverability (kebab-case)",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9-]+$"
+            },
+            "minItems": 1,
+            "maxItems": 10,
+            "examples": [["react", "typescript", "nextjs"], ["python", "data-science", "ml"]]
+          },
+          "icon": {
+            "type": "string",
+            "description": "Emoji or icon for the collection",
+            "maxLength": 10,
+            "examples": ["⚛️", "🚀", "📦"]
+          },
+          "packages": {
+            "type": "array",
+            "description": "Array of packages included in this collection",
+            "items": {
+              "type": "object",
+              "required": ["packageId"],
+              "properties": {
+                "packageId": {
+                  "type": "string",
+                  "description": "Package identifier to include",
+                  "minLength": 1,
+                  "examples": ["typescript-strict", "react-best-practices"]
+                },
+                "version": {
+                  "type": "string",
+                  "description": "Version range (semver) or 'latest'",
+                  "examples": ["^1.0.0", "~2.1.0", "1.0.0", "latest"]
+                },
+                "required": {
+                  "type": "boolean",
+                  "description": "Whether this package is required (true) or optional (false)",
+                  "default": true
+                },
+                "reason": {
+                  "type": "string",
+                  "description": "Explanation of why this package is included",
+                  "maxLength": 200,
+                  "examples": ["Enforces strict TypeScript type safety", "React component best practices"]
+                }
+              }
+            },
+            "minItems": 1
+          }
+        }
+      },
+      "minItems": 1
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "name": "@username/simple-package",
+      "version": "1.0.0",
+      "description": "A simple package with basic files",
+      "format": "claude", "subtype": "skill",
+      "author": "Your Name",
+      "license": "MIT",
+      "files": [
+        "skill.md",
+        "README.md"
+      ]
+    },
+    {
+      "name": "@company/coding-standards",
+      "version": "1.0.0",
+      "description": "Team coding standards that must be active in every session",
+      "format": "claude",
+      "subtype": "skill",
+      "author": "Company Team",
+      "organization": "my-company",
+      "license": "MIT",
+      "eager": true,
+      "files": [
+        ".claude/skills/coding-standards/SKILL.md"
+      ]
+    },
+    {
+      "name": "@company/team-package",
+      "version": "1.0.0",
+      "description": "A package published under organization account",
+      "format": "cursor",
+      "author": "Team Name",
+      "organization": "my-company",
+      "license": "MIT",
+      "files": [
+        ".cursor/rules/guidelines.mdc",
+        "README.md"
+      ]
+    },
+    {
+      "name": "@username/cursor-rules",
+      "version": "1.0.0",
+      "description": "Multiple Cursor rules for different languages",
+      "format": "cursor",
+      "author": {
+        "name": "Your Name",
+        "email": "you@example.com"
+      },
+      "license": "MIT",
+      "repository": "https://github.com/username/cursor-rules",
+      "tags": [
+        "cursor",
+        "rules",
+        "multi-language"
+      ],
+      "files": [
+        {
+          "path": ".cursor/rules/typescript.mdc",
+          "format": "cursor",
+          "name": "TypeScript Rules",
+          "tags": [
+            "typescript",
+            "frontend"
+          ]
+        },
+        {
+          "path": ".cursor/rules/python.mdc",
+          "format": "cursor",
+          "name": "Python Rules",
+          "tags": [
+            "python",
+            "backend"
+          ]
+        }
+      ]
+    },
+    {
+      "name": "@community/testing-suite",
+      "version": "2.0.0",
+      "description": "Complete testing suite with skills and agents",
+      "format": "generic", "subtype": "collection",
+      "author": "Community",
+      "license": "MIT",
+      "tags": [
+        "testing",
+        "quality"
+      ],
+      "files": [
+        {
+          "path": ".claude/skills/tdd.md",
+          "format": "claude", "subtype": "skill",
+          "name": "Test-Driven Development"
+        },
+        {
+          "path": ".claude/agents/test-generator.md",
+          "format": "claude", "subtype": "agent",
+          "name": "Test Generator"
+        }
+      ]
+    },
+    {
+      "name": "@username/copilot-instructions",
+      "version": "1.0.0",
+      "description": "GitHub Copilot instructions for API development",
+      "format": "copilot",
+      "author": "Your Name",
+      "license": "MIT",
+      "tags": [
+        "copilot",
+        "api",
+        "backend"
+      ],
+      "files": [
+        "api-guidelines.md"
+      ]
+    },
+    {
+      "name": "@username/kiro-steering",
+      "version": "1.0.0",
+      "description": "Kiro steering file for testing standards",
+      "format": "kiro",
+      "author": "Your Name",
+      "license": "MIT",
+      "tags": [
+        "kiro",
+        "testing",
+        "quality"
+      ],
+      "files": [
+        "testing.md"
+      ]
+    },
+    {
+      "name": "@username/windsurf-rules",
+      "version": "1.0.0",
+      "description": "Windsurf coding rules for React projects",
+      "format": "windsurf",
+      "author": "Your Name",
+      "license": "MIT",
+      "tags": [
+        "windsurf",
+        "react",
+        "frontend"
+      ],
+      "files": [
+        ".windsurfrules"
+      ]
+    },
+    {
+      "name": "@company/private-package",
+      "version": "1.0.0",
+      "description": "A private package only accessible to organization members",
+      "format": "claude",
+      "subtype": "skill",
+      "author": "Company Team",
+      "organization": "my-company",
+      "private": true,
+      "license": "Proprietary",
+      "files": [
+        "internal-skill.md",
+        "README.md"
+      ]
+    },
+    {
+      "name": "@username/multi-package-example",
+      "version": "1.0.0",
+      "description": "Multi-package manifest example",
+      "author": "Your Name",
+      "license": "MIT",
+      "repository": "https://github.com/username/multi-package",
+      "packages": [
+        {
+          "name": "@username/package-one",
+          "version": "1.0.0",
+          "description": "First package in the multi-package manifest",
+          "format": "claude",
+          "subtype": "skill",
+          "files": [
+            "package-one/SKILL.md"
+          ]
+        },
+        {
+          "name": "@username/package-two",
+          "version": "1.0.0",
+          "description": "Second package with different settings",
+          "format": "cursor",
+          "private": true,
+          "files": [
+            "package-two/.cursor/rules/main.mdc"
+          ]
+        }
+      ]
+    },
+    {
+      "name": "@username/multi-package-with-collection",
+      "version": "1.0.0",
+      "description": "Repository with both packages and a collection",
+      "author": "Your Name",
+      "license": "MIT",
+      "packages": [
+        {
+          "name": "typescript-rules",
+          "version": "1.0.0",
+          "description": "TypeScript coding standards",
+          "format": "cursor",
+          "subtype": "rule",
+          "tags": ["typescript", "cursor"],
+          "files": [".cursor/rules/typescript.mdc"]
+        },
+        {
+          "name": "react-patterns",
+          "version": "1.0.0",
+          "description": "React best practices",
+          "format": "claude",
+          "subtype": "skill",
+          "tags": ["react", "best-practices"],
+          "files": [".claude/skills/react-patterns/SKILL.md"]
+        }
+      ],
+      "collections": [
+        {
+          "id": "fullstack-setup",
+          "name": "Full Stack Setup",
+          "description": "Complete full-stack development setup with TypeScript and React",
+          "version": "1.0.0",
+          "category": "development",
+          "tags": ["typescript", "react", "fullstack"],
+          "icon": "🚀",
+          "packages": [
+            {
+              "packageId": "typescript-rules",
+              "version": "^1.0.0",
+              "required": true,
+              "reason": "TypeScript coding standards for the project"
+            },
+            {
+              "packageId": "react-patterns",
+              "version": "^1.0.0",
+              "required": true,
+              "reason": "React component best practices"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/.claude/skills/using-agent-relay/SKILL.md b/.claude/skills/using-agent-relay/SKILL.md
new file mode 100644
index 000000000..dd6b2423a
--- /dev/null
+++ b/.claude/skills/using-agent-relay/SKILL.md
@@ -0,0 +1,137 @@
+---
+name: using-agent-relay
+description: Use when coordinating multiple AI agents in real-time - provides inter-agent messaging via tmux wrapper (sub-5ms latency) or file-based team inbox for async workflows
+---
+
+# Using agent-relay
+
+## Overview
+
+Real-time agent-to-agent messaging. Two modes: **tmux wrapper** (real-time, sub-5ms) and **file-based team** (async, simpler).
+
+## When to Use
+
+- Multiple agents coordinating on shared codebase
+- Turn-based interactions (games, reviews, task handoff)
+- Parallel task distribution
+- Real-time Claude/Codex/Gemini collaboration
+
+**Don't use:** Single agent, cross-host networking, guaranteed delivery required.
+
+## Quick Reference
+
+| Pattern | Description |
+|---------|-------------|
+| `->relay:Name message` | Direct message (output as text) |
+| `->relay:* message` | Broadcast to all |
+| `[[RELAY]]{"to":"Name","body":"msg"}[[/RELAY]]` | Structured JSON |
+| `\->relay:` | Escape (literal output) |
+| `relay read <id>` | Read truncated message |
+
+## CLI Commands
+
+```bash
+relay -f                    # Start daemon + dashboard
+relay --status              # Check daemon
+relay --stop                # Stop daemon
+relay wrap -n Alice claude  # Wrap agent with messaging
+relay read abc123           # Read truncated message
+```
+
+### Team Commands (file-based)
+
+```bash
+relay team send -n You -t Recipient -m "Message"
+relay team send -n You -t "*" -m "Broadcast"
+relay team check -n You --no-wait     # Non-blocking
+relay team check -n You --clear       # Clear after read
+relay team status                     # Show team
+```
+
+## Sending Messages (Tmux Mode)
+
+**Output the pattern directly** - don't use bash commands:
+
+```
+->relay:BlueLake I've finished the API refactor.
+->relay:* STATUS: Starting auth module.
+```
+
+Pattern must be at line start (whitespace/prefixes OK):
+
+```
+->relay:Name message          # Works
+  ->relay:Name message        # Works
+- ->relay:Name message        # Works
+Some text ->relay:Name msg    # Won't work
+```
+
+## Receiving Messages
+
+Messages appear as:
+```
+Relay message from Alice [abc123]: Message here
+```
+
+### Truncated Messages
+
+Long messages show `[TRUNCATED...]`. Read full content:
+```bash
+relay read abc123
+```
+
+**Rule:** If message ends abruptly, always read full message before responding.
+
+## Coordination Patterns
+
+```
+# Task assignment
+->relay:Developer TASK: Implement /api/register
+
+# Status broadcast
+->relay:* STATUS: Starting auth module
+->relay:* DONE: Auth complete
+
+# Review request
+->relay:Reviewer REVIEW: src/auth/*.ts
+
+# Question
+->relay:Architect QUESTION: JWT or sessions?
+
+# Blocked
+->relay:* BLOCKED: Need DB credentials
+```
+
+## Multi-Project Bridge
+
+```bash
+# Bridge multiple projects
+relay bridge ~/auth ~/frontend ~/api
+
+# Cross-project messaging
+@relay:projectId:agent Message
+@relay:*:lead Broadcast to leads
+
+# Spawn workers (lead mode)
+relay lead Alice
+->relay:spawn Dev1 claude "Implement login"
+->relay:release Dev1
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using bash to send real-time messages | Output `->relay:` directly as text |
+| Messages not sending | `relay --status` to check daemon |
+| Incomplete message content | `relay read <id>` for full text |
+| Pattern not at line start | Move `->relay:` to beginning |
+| Forgetting to clear inbox | Use `--clear` flag |
+
+## Troubleshooting
+
+```bash
+relay --status                    # Check daemon
+relay --stop && relay -f          # Restart
+ls -la /tmp/agent-relay.sock      # Verify socket
+```
diff --git a/.gitignore b/.gitignore
index 1515d4fb3..071edfe3a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,7 +18,7 @@ pnpm-debug.log*
 .DS_Store
 .vscode/
 .idea/
-.claude/
+.claude/settings.local.json
 
 # Relay runtime artifacts
 *.sock
@@ -31,3 +31,4 @@ pnpm-debug.log*
 coverage/
 .npm-cache
 .tmp-supervisor-tests
+.tmp-agent-relay-data
diff --git a/.openskills/frontend-design/SKILL.md b/.openskills/frontend-design/SKILL.md
new file mode 100644
index 000000000..43aec9ae8
--- /dev/null
+++ b/.openskills/frontend-design/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
diff --git a/AGENTS.md b/AGENTS.md
index fa0758372..eb6ed0b83 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,20 +30,20 @@ agent-relay -n Bob claude
 
 ## For Agents: How to Communicate
 
-When wrapped with `agent-relay`, agents communicate by outputting `@relay:` patterns.
+When wrapped with `agent-relay`, agents communicate by outputting `->relay:` patterns.
 
 ### Send a Message
 
 Output this in your response (not in a bash command):
 
 ```
-@relay:AgentName Your message here
+->relay:AgentName Your message here
 ```
 
 ### Broadcast to All
 
 ```
-@relay:* This message goes to everyone
+->relay:* This message goes to everyone
 ```
 
 ### Receiving Messages
@@ -87,48 +87,48 @@ agent-relay read abc12345
 ### Status Updates
 
 ```
-@relay:* STATUS: Starting work on auth module
-@relay:* DONE: Auth module complete
+->relay:* STATUS: Starting work on auth module
+->relay:* DONE: Auth module complete
 ```
 
 ### Task Assignment
 
 ```
-@relay:Developer TASK: Implement /api/register endpoint
+->relay:Developer TASK: Implement /api/register endpoint
 ```
 
 ### Questions
 
 ```
-@relay:Architect QUESTION: Should we use JWT or sessions?
+->relay:Architect QUESTION: Should we use JWT or sessions?
 ```
 
 ### Review Requests
 
 ```
-@relay:Reviewer REVIEW: Please check src/auth/*.ts
+->relay:Reviewer REVIEW: Please check src/auth/*.ts
 ```
 
 ---
 
 ## Pattern Rules
 
-The `@relay:` pattern must be at the start of a line:
+The `->relay:` pattern must be at the start of a line:
 
 ```
-@relay:Name message           # Works
-  @relay:Name message         # Works (whitespace OK)
-> @relay:Name message         # Works (prompt OK)
-- @relay:Name message         # Works (list OK)
-Some text @relay:Name msg     # Won't work
+->relay:Name message           # Works
+  ->relay:Name message         # Works (whitespace OK)
+> ->relay:Name message         # Works (prompt OK)
+- ->relay:Name message         # Works (list OK)
+Some text ->relay:Name msg     # Won't work
 ```
 
 ### Escape
 
-To output literal `@relay:` without sending:
+To output literal `->relay:` without sending:
 
 ```
-\@relay: This won't be sent
+\->relay: This won't be sent
 ```
 
 ---
@@ -140,3 +140,59 @@ To output literal `@relay:` without sending:
 | Messages not sending | `agent-relay status` to check daemon |
 | Socket not found | `agent-relay up` to start daemon |
 | Truncated message | `agent-relay read <id>` for full content |
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd sync
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
+
+<!-- PRPM_MANIFEST_START -->
+
+<skills_system priority="1">
+<usage>
+When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
+
+How to use skills (loaded into main context):
+- Use the <path> from the skill entry below
+- Invoke: Bash("cat <path>")
+- The skill content will load into your current context
+- Example: Bash("cat .openskills/backend-architect/SKILL.md")
+
+Usage notes:
+- Skills share your context window
+- Do not invoke a skill that is already loaded in your context
+</usage>
+
+<available_skills>
+
+<skill activation="lazy">
+<name>frontend-design</name>
+<description>Design and build modern frontend interfaces with best practices and user experience principles. Create beautiful, accessible, and performant web interfaces.</description>
+<path>.openskills/frontend-design/SKILL.md</path>
+</skill>
+
+</available_skills>
+</skills_system>
+
+<!-- PRPM_MANIFEST_END -->
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 6c82e5b6d..2797d5004 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -6,7 +6,7 @@ Agent Relay is a real-time messaging system that enables autonomous agent-to-age
 
 The system works by:
 1. Wrapping agent CLI processes in monitored tmux sessions
-2. Parsing agent output for `@relay:` commands
+2. Parsing agent output for `->relay:` commands
 3. Routing messages through a central daemon via Unix domain sockets
 4. Injecting incoming messages directly into agent terminal input
 
@@ -44,7 +44,7 @@ Agent Relay solves this by providing a communication layer that requires **zero
 
 ### 1.2 Core Principle: Output Parsing, Not API Integration
 
-The fundamental insight is that AI agents already produce text output. By monitoring that output for specific patterns (`@relay:Target message`), we can extract communication intent without modifying the agent itself.
+The fundamental insight is that AI agents already produce text output. By monitoring that output for specific patterns (`->relay:Target message`), we can extract communication intent without modifying the agent itself.
 
 This approach:
 - Works with any CLI-based agent
@@ -113,7 +113,7 @@ Web UI for monitoring. Shows connected agents, message flow, real-time updates.
 │  Layer 2: Wrapper                                               │
 │  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐        │
 │  │ TmuxWrapper   │ │ OutputParser  │ │ RelayClient   │        │
-│  │ (PTY mgmt)    │ │ (@relay:)     │ │ (Socket I/O)  │        │
+│  │ (PTY mgmt)    │ │ (->relay:)     │ │ (Socket I/O)  │        │
 │  └───────────────┘ └───────────────┘ └───────────────┘        │
 ├─────────────────────────────────────────────────────────────────┤
 │  Layer 3: Daemon                                                │
@@ -162,7 +162,7 @@ The TmuxWrapper is the most complex component. It bridges the gap between agent
 │  │  │              Agent Process (claude, etc.)          │  │  │
 │  │  │                                                    │  │  │
 │  │  │  Output: "I'll send a message to Bob"             │  │  │
-│  │  │  Output: "@relay:Bob Can you review auth.ts?"     │  │  │
+│  │  │  Output: "->relay:Bob Can you review auth.ts?"     │  │  │
 │  │  │                                                    │  │  │
 │  │  └────────────────────────────────────────────────────┘  │  │
 │  └──────────────────────────────────────────────────────────┘  │
@@ -173,7 +173,7 @@ The TmuxWrapper is the most complex component. It bridges the gap between agent
 │  │  OutputParser                                             │  │
 │  │  - Strip ANSI codes                                       │  │
 │  │  - Join continuation lines                                │  │
-│  │  - Extract @relay: commands                               │  │
+│  │  - Extract ->relay: commands                               │  │
 │  │  - Deduplicate (hash-based)                               │  │
 │  └──────────────────────────────────────────────────────────┘  │
 │                              │                                  │
@@ -214,9 +214,9 @@ return str.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
 ```
 
 **3. Continuation Line Joining**
-When TUIs wrap long lines, `@relay:` commands can span multiple lines:
+When TUIs wrap long lines, `->relay:` commands can span multiple lines:
 ```
-@relay:Bob This is a very long message that gets
+->relay:Bob This is a very long message that gets
     wrapped by the terminal and continues here
 ```
 The wrapper joins these back together.
@@ -252,8 +252,8 @@ Extracts relay commands from agent output.
 
 **1. Inline Format (Primary)**
 ```
-@relay:AgentName Your message here
-@relay:* Broadcast to everyone
+->relay:AgentName Your message here
+->relay:* Broadcast to everyone
 @thinking:AgentName Share reasoning (not displayed to user)
 ```
 
@@ -268,15 +268,15 @@ The parser handles real-world terminal output complexity:
 
 ```typescript
 // Allow common input prefixes: >, $, %, #, bullets, etc.
-const INLINE_RELAY = /^(?:\s*(?:[>$%#→➜›»●•◦‣⁃\-*⏺◆◇○□■]\s*)*)?@relay:(\S+)\s+(.+)$/;
+const INLINE_RELAY = /^(?:\s*(?:[>$%#→➜›»●•◦‣⁃\-*⏺◆◇○□■]\s*)*)?->relay:(\S+)\s+(.+)$/;
 ```
 
 This matches:
-- `@relay:Bob hello` (plain)
-- `  @relay:Bob hello` (indented)
-- `> @relay:Bob hello` (quoted)
-- `- @relay:Bob hello` (bullet point)
-- `⏺ @relay:Bob hello` (Claude's bullet)
+- `->relay:Bob hello` (plain)
+- `  ->relay:Bob hello` (indented)
+- `> ->relay:Bob hello` (quoted)
+- `- ->relay:Bob hello` (bullet point)
+- `⏺ ->relay:Bob hello` (Claude's bullet)
 
 #### Code Fence Awareness
 
@@ -601,7 +601,7 @@ Messages can have different semantic kinds:
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │ 1. AGENT OUTPUT                                                         │
-│    Agent (Claude) produces text: "@relay:Bob Can you review auth.ts?"   │
+│    Agent (Claude) produces text: "->relay:Bob Can you review auth.ts?"   │
 └─────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
@@ -617,7 +617,7 @@ Messages can have different semantic kinds:
 │    OutputParser:                                                        │
 │    - Strips ANSI escape codes                                           │
 │    - Joins continuation lines                                           │
-│    - Matches /^@relay:(\S+)\s+(.+)$/                                    │
+│    - Matches /^->relay:(\S+)\s+(.+)$/                                    │
 │    - Returns: { to: "Bob", body: "Can you review auth.ts?" }           │
 └─────────────────────────────────────────────────────────────────────────┘
                                     │
@@ -700,7 +700,7 @@ Messages can have different semantic kinds:
 
 ### 5.2 Broadcast Flow
 
-When sending to `@relay:*`:
+When sending to `->relay:*`:
 
 ```
 Alice                    Daemon                    Bob, Carol, Dave
@@ -800,7 +800,7 @@ Alice                    Daemon                    Bob, Carol, Dave
 │  └─────────────┘                                               │
 │                                                                 │
 │  State Tracking:                                                │
-│  - inCodeFence: boolean - ignore @relay inside code fences     │
+│  - inCodeFence: boolean - ignore ->relay inside code fences    │
 │  - inBlock: boolean - buffering [[RELAY]]...[[/RELAY]]         │
 │  - blockBuffer: string - accumulated block content             │
 │                                                                 │
@@ -958,7 +958,7 @@ For sensitive environments:
 
 ### 9.1 Why Output Parsing Instead of API Integration?
 
-**Decision**: Parse agent stdout for `@relay:` patterns instead of modifying agent code.
+**Decision**: Parse agent stdout for `->relay:` patterns instead of modifying agent code.
 
 **Rationale**:
 - Works with any CLI agent without modification
@@ -971,7 +971,7 @@ For sensitive environments:
 - ❌ Can miss messages in edge cases
 - ❌ No structured validation of message content
 - ✅ Zero changes to Claude, Codex, or other agents
-- ✅ Transparent - users see `@relay:` in agent output
+- ✅ Transparent - users see `->relay:` in agent output
 
 ### 9.2 Why Tmux Instead of Direct PTY?
 
@@ -1162,7 +1162,7 @@ agent-relay/
 │   ├── wrapper/
 │   │   ├── tmux-wrapper.ts       # Tmux session management
 │   │   ├── client.ts             # Daemon client connection
-│   │   ├── parser.ts             # Output parsing (@relay:)
+│   │   ├── parser.ts             # Output parsing (->relay:)
 │   │   ├── inbox.ts              # File-based inbox
 │   │   └── index.ts
 │   ├── protocol/
@@ -1217,10 +1217,10 @@ agent-relay -n Bob claude
 
 ```
 # Direct message
-@relay:Bob Please review the auth module
+->relay:Bob Please review the auth module
 
 # Broadcast
-@relay:* I've finished the database migration
+->relay:* I've finished the database migration
 
 # Structured (block format)
 [[RELAY]]{"to":"Bob","type":"action","body":"Run tests"}[[/RELAY]]
diff --git a/CLAUDE.md b/CLAUDE.md
index 35deb264b..91fe3f2bd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -72,20 +72,20 @@ agent-relay -n Bob claude
 
 ## For Agents: How to Communicate
 
-When wrapped with `agent-relay`, agents communicate by outputting `@relay:` patterns.
+When wrapped with `agent-relay`, agents communicate by outputting `->relay:` patterns.
 
 ### Send a Message
 
 Output this in your response (not in a bash command):
 
 ```
-@relay:AgentName Your message here
+->relay:AgentName Your message here
 ```
 
 ### Broadcast to All
 
 ```
-@relay:* This message goes to everyone
+->relay:* This message goes to everyone
 ```
 
 ### Receiving Messages
@@ -115,24 +115,24 @@ agent-relay read abc12345...
 ## Communication Patterns
 
 ```
-@relay:* STATUS: Starting work on auth module
-@relay:* DONE: Auth module complete
-@relay:Developer TASK: Implement /api/register
-@relay:Reviewer REVIEW: Please check src/auth/*.ts
-@relay:Architect QUESTION: JWT or sessions?
+->relay:* STATUS: Starting work on auth module
+->relay:* DONE: Auth module complete
+->relay:Developer TASK: Implement /api/register
+->relay:Reviewer REVIEW: Please check src/auth/*.ts
+->relay:Architect QUESTION: JWT or sessions?
 ```
 
 ---
 
 ## Pattern Rules
 
-`@relay:` must be at the start of a line:
+`->relay:` must be at the start of a line:
 
 ```
-@relay:Name message           # Works
-  @relay:Name message         # Works (whitespace OK)
-- @relay:Name message         # Works (list OK)
-Some text @relay:Name msg     # Won't work
+->relay:Name message           # Works
+  ->relay:Name message         # Works (whitespace OK)
+- ->relay:Name message         # Works (list OK)
+Some text ->relay:Name msg     # Won't work
 ```
 
-Escape with `\@relay:` to output literally.
+Escape with `\->relay:` to output literally.
diff --git a/EXECUTIVE_SUMMARY.md b/EXECUTIVE_SUMMARY.md
index 6c02636be..581d861a0 100644
--- a/EXECUTIVE_SUMMARY.md
+++ b/EXECUTIVE_SUMMARY.md
@@ -8,6 +8,8 @@
 
 Agent Relay enables AI coding assistants (Claude, Codex, Gemini) running in separate terminals to **discover each other and communicate autonomously** - without any code changes to the AI systems.
 
+**Key differentiator:** agent-relay is a **composable messaging layer**, not a monolithic solution. It does one thing exceptionally well (<5ms real-time messaging) and integrates with best-of-breed tools for memory, UI, and workflows.
+
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                                                                         │
@@ -34,7 +36,7 @@ Agent Relay enables AI coding assistants (Claude, Codex, Gemini) running in sepa
 **Agents already produce text.** By watching for a simple pattern in their output, we can extract communication intent:
 
 ```
-Agent Output:  "I'll ask Bob for help. @relay:Bob Can you review auth.ts?"
+Agent Output:  "I'll ask Bob for help. ->relay:Bob Can you review auth.ts?"
                                         ▲
                                         │
                             Relay captures this, routes to Bob
@@ -54,7 +56,7 @@ No API integration. No agent modification. Just pattern matching on stdout.
 │                                                                          │
 │  agent-relay               Background                  Daemon            │
 │  -n Alice claude    ───▶   polling     ───▶   finds   routes    ───▶    │
-│                            captures          @relay:   message          │
+│                            captures          ->relay:   message          │
 │  Agent runs in             output            Bob...    to Bob           │
 │  tmux session                                                            │
 │                                                                          │
@@ -67,7 +69,7 @@ No API integration. No agent modification. Just pattern matching on stdout.
 │  message                   terminal                    as input          │
 │                                                                          │
 │                            "Relay message              Can reply with    │
-│                             from Alice:                @relay:Alice      │
+│                             from Alice:                ->relay:Alice      │
 │                             Can you..."                                  │
 │                                                                          │
 └──────────────────────────────────────────────────────────────────────────┘
@@ -88,7 +90,7 @@ agent-relay -n Alice claude
 agent-relay -n Bob claude
 ```
 
-Alice can now send: `@relay:Bob Can you help with the auth module?`
+Alice can now send: `->relay:Bob Can you help with the auth module?`
 
 Bob receives: `Relay message from Alice [abc123]: Can you help with the auth module?`
 
@@ -117,7 +119,7 @@ Bob receives: `Relay message from Alice [abc123]: Can you help with the auth mod
 │  │   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │   │
 │  │   │TmuxWrapper  │  │OutputParser │  │RelayClient  │            │   │
 │  │   │             │  │             │  │             │            │   │
-│  │   │• Runs agent │  │• @relay:    │  │• Socket I/O │            │   │
+│  │   │• Runs agent │  │• ->relay:    │  │• Socket I/O │            │   │
 │  │   │  in tmux    │  │  patterns   │  │• Reconnect  │            │   │
 │  │   │• Captures   │  │• ANSI strip │  │• Handshake  │            │   │
 │  │   │  output     │  │• Dedup      │  │             │            │   │
@@ -160,7 +162,7 @@ Bob receives: `Relay message from Alice [abc123]: Can you help with the auth mod
   Alice (Claude)                    Daemon                      Bob (Codex)
        │                              │                              │
        │  Agent outputs:              │                              │
-       │  "@relay:Bob review auth"    │                              │
+       │  "->relay:Bob review auth"    │                              │
        │                              │                              │
        ├──────────────────────────────┤                              │
        │     TmuxWrapper captures     │                              │
@@ -186,7 +188,7 @@ Bob receives: `Relay message from Alice [abc123]: Can you help with the auth mod
        │                              │              └───────────────┤
        │                              │                              │
        │                              │     Bob can respond:         │
-       │                              │     "@relay:Alice Done!"     │
+       │                              │     "->relay:Alice Done!"     │
        │                              │                              │
        │                              │◀─────────────────────────────┤
        │◀─────────────────────────────┤                              │
@@ -261,12 +263,12 @@ Bob receives: `Relay message from Alice [abc123]: Can you help with the auth mod
 
 ### Direct Message
 ```
-@relay:Bob Please review the authentication module
+->relay:Bob Please review the authentication module
 ```
 
 ### Broadcast
 ```
-@relay:* I've completed the database migration - all tests passing
+->relay:* I've completed the database migration - all tests passing
 ```
 
 ### Structured (Block Format)
@@ -276,10 +278,10 @@ Bob receives: `Relay message from Alice [abc123]: Can you help with the auth mod
 
 ### Common Conventions
 ```
-@relay:* STATUS: Starting work on auth module
-@relay:* DONE: Auth module complete
-@relay:Reviewer REVIEW: Please check src/auth/*.ts
-@relay:Architect QUESTION: Should we use JWT or sessions?
+->relay:* STATUS: Starting work on auth module
+->relay:* DONE: Auth module complete
+->relay:Reviewer REVIEW: Please check src/auth/*.ts
+->relay:Architect QUESTION: Should we use JWT or sessions?
 ```
 
 ---
@@ -321,7 +323,7 @@ agent-relay/
 │   ├── wrapper/
 │   │   ├── tmux-wrapper.ts    # Tmux session management
 │   │   ├── client.ts          # Daemon client
-│   │   └── parser.ts          # @relay: pattern matching
+│   │   └── parser.ts          # ->relay: pattern matching
 │   ├── protocol/
 │   │   ├── types.ts           # Message types
 │   │   └── framing.ts         # Wire format
@@ -349,6 +351,7 @@ agent-relay/
 
 - **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Complete technical deep-dive
 - **[README.md](./README.md)** - Quick start guide
+- **[docs/COMPETITIVE_ANALYSIS.md](./docs/COMPETITIVE_ANALYSIS.md)** - Comparison with 16 multi-agent tools
 
 ---
 
diff --git a/README.md b/README.md
index b5834a5b0..f91c3a806 100644
--- a/README.md
+++ b/README.md
@@ -23,11 +23,11 @@ agent-relay -n Alice claude
 agent-relay -n Bob codex
 ```
 
-Agents communicate by outputting `@relay:` patterns:
+Agents communicate by outputting `->relay:` patterns:
 
 ```
-@relay:Bob Hey, can you review my changes?
-@relay:* Broadcasting to everyone
+->relay:Bob Hey, can you review my changes?
+->relay:* Broadcasting to everyone
 ```
 
 ## CLI
@@ -40,11 +40,13 @@ Agents communicate by outputting `@relay:` patterns:
 | `agent-relay down` | Stop daemon |
 | `agent-relay status` | Check if running |
 | `agent-relay read <id>` | Read truncated message |
+| `agent-relay bridge <projects...>` | Bridge multiple projects |
+| `agent-relay lead <name>` | Start as project lead |
 
 ## How It Works
 
 1. `agent-relay up` starts a daemon that routes messages via Unix socket
-2. `agent-relay <cmd>` wraps your agent in tmux, parsing output for `@relay:` patterns
+2. `agent-relay <cmd>` wraps your agent in tmux, parsing output for `->relay:` patterns
 3. Messages are injected into recipient terminals in real-time
 
 ```
@@ -67,13 +69,13 @@ Agents communicate by outputting `@relay:` patterns:
 ### Send Message
 
 ```
-@relay:AgentName Your message here
+->relay:AgentName Your message here
 ```
 
 ### Broadcast
 
 ```
-@relay:* Message to all agents
+->relay:* Message to all agents
 ```
 
 ### Receive
@@ -92,12 +94,124 @@ Long messages are truncated. Use the ID to read full content:
 agent-relay read abc123
 ```
 
+## Agent Roles
+
+Agent names automatically match role definitions (case-insensitive):
+
+```bash
+# If .claude/agents/lead.md exists:
+agent-relay -n Lead claude    # matches lead.md
+agent-relay -n LEAD claude    # matches lead.md
+agent-relay -n lead claude    # matches lead.md
+
+# Supported locations:
+# - .claude/agents/<name>.md
+# - .openagents/<name>.md
+```
+
+Create role agents for your team:
+
+```
+.claude/agents/
+├── lead.md          # Coordinator
+├── implementer.md   # Developer
+├── designer.md      # UI/UX
+└── reviewer.md      # Code review
+```
+
+## Multi-Project Orchestration
+
+Bridge multiple projects with a single orchestrator:
+
+```bash
+# Bridge projects (Architect mode)
+agent-relay bridge ~/auth ~/frontend ~/api
+
+# Start as project lead with spawn capability
+agent-relay lead Alice
+```
+
+### Workflow
+
+1. **Start daemons** in each project: `agent-relay up`
+2. **Start leads** in each project: `agent-relay lead Alice`
+3. **Bridge** from anywhere: `agent-relay bridge ~/project1 ~/project2`
+
+### Cross-Project Messaging
+
+```
+->relay:projectId:agent Message to specific agent
+->relay:*:lead Broadcast to all project leads
+```
+
+### Spawn Agents (Lead only)
+
+```
+->relay:spawn Dev1 claude "Implement login endpoint"
+->relay:release Dev1
+```
+
+See [docs/DESIGN_BRIDGE_STAFFING.md](docs/DESIGN_BRIDGE_STAFFING.md) for full details.
+
+## Enabling AI Agents
+
+To teach your AI agents how to use agent-relay, you have two options:
+
+### Option 1: Install the Skill (Recommended)
+
+```bash
+prpm install using-agent-relay
+```
+
+This installs the `using-agent-relay` skill which provides agents with messaging patterns, coordination workflows, and troubleshooting guidance.
+
+### Option 2: Copy AGENTS.md
+
+Copy [docs/AGENTS.md](docs/AGENTS.md) to your project's agent instructions file (e.g., `CLAUDE.md`, `AGENTS.md`, or similar). This gives agents the messaging syntax and patterns they need.
+
 ## Dashboard
 
 `agent-relay up` starts a web dashboard at http://localhost:3888
 
 ![Agent Relay Dashboard](dashboard.png)
 
+## REST API for Spawning Agents
+
+The dashboard includes a REST API for programmatically spawning and managing agents.
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/spawn` | Spawn a new agent |
+| `GET` | `/api/spawned` | List spawned agents |
+| `DELETE` | `/api/spawned/:name` | Release an agent |
+
+### Examples
+
+```bash
+# Spawn an agent
+curl -X POST http://localhost:3888/api/spawn \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Dev1", "cli": "claude", "task": "Implement login"}'
+
+# List spawned agents
+curl http://localhost:3888/api/spawned
+
+# Release an agent
+curl -X DELETE http://localhost:3888/api/spawned/Dev1
+```
+
+### Response Format
+
+```json
+{
+  "success": true,
+  "name": "Dev1",
+  "window": "relay-workers:Dev1"
+}
+```
+
 ## Troubleshooting
 
 | Issue | Solution |
@@ -114,6 +228,54 @@ cd agent-relay
 npm install && npm run build
 ```
 
+## Why agent-relay?
+
+### The Composable Approach
+
+Most multi-agent tools try to be complete solutions - handling communication, memory, UI, workflows, and orchestration. agent-relay takes a different approach: **do one thing exceptionally well** (real-time messaging) and integrate with best-of-breed tools for everything else.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Your Agent System                        │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   Mimir     │  │  Maestro    │  │    Beads    │         │
+│  │  (Memory)   │  │    (UI)     │  │ (Workflows) │         │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
+│         └────────────────┼────────────────┘                 │
+│                ┌─────────▼─────────┐                        │
+│                │   agent-relay     │  ◄── Messaging layer   │
+│                │     <5ms P2P      │                        │
+│                └─────────┬─────────┘                        │
+│         ┌────────────────┼────────────────┐                 │
+│    ┌────▼────┐     ┌────▼────┐     ┌────▼────┐             │
+│    │ Claude  │     │  Codex  │     │  Gemini │             │
+│    └─────────┘     └─────────┘     └─────────┘             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Unix Philosophy
+
+- **Do one thing well**: Real-time agent messaging with <5ms latency
+- **Work with others**: Simple `->relay:` pattern, standard I/O
+- **Text streams**: Messages are just text, easy to parse/transform
+- **Composability**: Pipe into other tools, wrap any CLI
+
+### When to Use agent-relay
+
+| Use Case | agent-relay? |
+|----------|--------------|
+| Quick prototyping with multiple agents | **Yes** - 1 min setup |
+| Real-time agent collaboration | **Yes** - fastest option |
+| CLI-native workflows | **Yes** - no Electron/desktop needed |
+| Need persistent knowledge graph | Combine with Mimir |
+| Need rich desktop UI | Combine with Maestro |
+| Enterprise compliance | Combine with governance layer |
+
+See [docs/COMPETITIVE_ANALYSIS.md](docs/COMPETITIVE_ANALYSIS.md) for detailed comparisons with 16 other multi-agent tools.
+
+---
+
 ## Inspiration
 
 This project was inspired by some excellent work in the multi-agent coordination space:
diff --git a/TESTING.md b/TESTING.md
new file mode 100644
index 000000000..109d1926f
--- /dev/null
+++ b/TESTING.md
@@ -0,0 +1,268 @@
+# Manual Testing Guide
+
+Manual testing instructions for bridge, staffing, and multi-project orchestration features.
+
+## Prerequisites
+
+- Node.js installed
+- `agent-relay` built and available (`npm run build`)
+- tmux installed (`brew install tmux` on macOS)
+
+---
+
+## 1. Single Project - Lead + Spawning
+
+Test the Lead role and worker spawning within a single project.
+
+### Setup
+
+```bash
+# Terminal 1: Start daemon
+cd /path/to/your/project
+agent-relay up
+```
+
+```bash
+# Terminal 2: Start as Lead
+agent-relay lead Alice
+```
+
+### Test Spawning
+
+Inside Alice's terminal, output these patterns:
+
+```
+->relay:spawn Dev1 claude "Write unit tests for the auth module"
+```
+
+**Expected:**
+- New tmux window created in `relay-workers` session
+- Dev1 agent starts with the task injected
+- Message: `[spawner] Spawned Dev1 (claude) for Alice`
+
+### Verify Spawn
+
+```bash
+# Check tmux windows
+tmux list-windows -t relay-workers
+```
+
+### Test Release
+
+```
+->relay:release Dev1
+```
+
+**Expected:**
+- Dev1 window closed
+- Message: `[spawner] Released Dev1`
+
+### Test Release All
+
+First spawn multiple workers:
+```
+->relay:spawn Dev1 claude "Task 1"
+->relay:spawn Dev2 claude "Task 2"
+->relay:spawn QA1 claude "Task 3"
+```
+
+Then release all:
+```
+->relay:release *
+```
+
+**Expected:** All workers released.
+
+---
+
+## 2. Multi-Project Bridge
+
+Test cross-project communication with the bridge command.
+
+### Setup (3 terminals minimum)
+
+```bash
+# Terminal 1: Project A daemon
+mkdir -p /tmp/project-a
+cd /tmp/project-a
+agent-relay up
+```
+
+```bash
+# Terminal 2: Project B daemon
+mkdir -p /tmp/project-b
+cd /tmp/project-b
+agent-relay up
+```
+
+```bash
+# Terminal 3: Bridge (Architect mode)
+agent-relay bridge /tmp/project-a /tmp/project-b
+```
+
+**Expected:**
+- Bridge connects to both project sockets
+- Dashboard shows both projects (if enabled)
+
+### Start Leads in Each Project
+
+```bash
+# Terminal 4: Lead in Project A
+cd /tmp/project-a
+agent-relay lead Alice
+```
+
+```bash
+# Terminal 5: Lead in Project B
+cd /tmp/project-b
+agent-relay lead Bob
+```
+
+### Test Cross-Project Messaging
+
+From Alice (Project A):
+```
+->relay:project-b:Bob Hey Bob, can you review my changes?
+```
+
+**Expected:** Bob receives the message in Project B.
+
+From Bob (Project B):
+```
+->relay:project-a:Alice Sure, sending review now.
+```
+
+**Expected:** Alice receives the message in Project A.
+
+### Test Broadcast to All Leads
+
+From the bridge/architect:
+```
+->relay:*:lead Standup time - report your status
+```
+
+**Expected:** Both Alice and Bob receive the message.
+
+---
+
+## 3. Dashboard Verification
+
+### Main Dashboard
+
+Open: http://localhost:4280
+
+Check:
+- [ ] Connected agents appear
+- [ ] Online/Offline status badges show correctly
+- [ ] Messages appear in activity log
+- [ ] Last seen timestamps update
+
+### Bridge Dashboard
+
+Open: http://localhost:4280/bridge
+
+Check:
+- [ ] Connected projects appear
+- [ ] Leads shown per project
+- [ ] Workers shown under their lead
+- [ ] Cross-project messages in message flow panel
+
+---
+
+## 4. Agent Role Auto-Detection
+
+Test that agent names match role definitions.
+
+### Setup
+
+Create a role agent:
+```bash
+mkdir -p .claude/agents
+cat > .claude/agents/lead.md << 'EOF'
+---
+name: lead
+description: Coordinator agent
+model: haiku
+---
+
+# Lead Agent
+
+You are a Lead agent - coordinate and delegate.
+EOF
+```
+
+### Test
+
+```bash
+agent-relay -n Lead claude
+```
+
+**Expected:** Agent assumes the Lead role from `lead.md` (case-insensitive match).
+
+---
+
+## 5. Cleanup
+
+```bash
+# Stop all daemons
+agent-relay down
+
+# Kill any orphaned tmux sessions
+tmux kill-session -t relay-workers 2>/dev/null
+tmux list-sessions | grep relay | cut -d: -f1 | xargs -I {} tmux kill-session -t {}
+
+# Remove test directories
+rm -rf /tmp/project-a /tmp/project-b
+```
+
+---
+
+## Quick Smoke Test Script
+
+Save as `test-bridge.sh` and run:
+
+```bash
+#!/bin/bash
+set -e
+
+echo "=== Bridge Smoke Test ==="
+
+# Setup
+mkdir -p /tmp/smoke-a /tmp/smoke-b
+cd /tmp/smoke-a && agent-relay up &
+PID_A=$!
+sleep 1
+
+cd /tmp/smoke-b && agent-relay up &
+PID_B=$!
+sleep 1
+
+# Check daemons
+echo "Checking daemons..."
+agent-relay status
+
+# Bridge
+echo "Starting bridge..."
+agent-relay bridge /tmp/smoke-a /tmp/smoke-b &
+PID_BRIDGE=$!
+sleep 2
+
+# Cleanup
+echo "Cleaning up..."
+kill $PID_A $PID_B $PID_BRIDGE 2>/dev/null || true
+rm -rf /tmp/smoke-a /tmp/smoke-b
+
+echo "=== Smoke Test Complete ==="
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Socket not found" | Start daemon with `agent-relay up` |
+| Spawn not working | Check tmux is installed, check `relay-workers` session |
+| Cross-project messages not delivered | Verify bridge is running and connected to both daemons |
+| Dashboard not loading | Check daemon started with dashboard enabled (default) |
+| Agent role not applied | Check file exists at `.claude/agents/<name>.md` (case-insensitive) |
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index b98958430..92666b3e6 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -74,11 +74,65 @@ relay wrap -n PlayerO claude
 
 ### Why tmux?
 - Real terminal: you attach directly to tmux (no double PTY).
-- Background capture/parse of `@relay:` without touching stdout.
+- Background capture/parse of `->relay:` without touching stdout.
 - Reliable injection via `tmux send-keys`.
 
 ---
 
+## Agent Role Auto-Detection
+
+When you start an agent with `-n`, the name is matched against agent definitions in your project. If a matching agent file exists, the agent automatically assumes that role.
+
+**Supported locations:**
+- `.claude/agents/<name>.md` - Claude Code agents
+- `.openagents/<name>.md` - OpenAgents format
+
+### Example
+
+```bash
+# If .claude/agents/lead.md exists:
+relay wrap -n lead claude
+# → Agent automatically assumes the Lead role defined in lead.md
+
+# If .claude/agents/implementer.md exists:
+relay wrap -n implementer claude
+# → Agent assumes the Implementer role
+
+# No matching file? Agent starts with default behavior
+relay wrap -n CustomName claude
+# → Standard agent, no role injection
+```
+
+### How It Works
+
+1. Agent name from `-n` flag is matched **case-insensitively**
+2. System checks for `<project>/.claude/agents/<name>.md` or `<project>/.openagents/<name>.md`
+3. If found, the agent definition is injected into the agent's initial context
+4. Agent assumes the persona, instructions, and behaviors defined in the file
+
+**Case insensitive matching:**
+```bash
+relay wrap -n Lead claude      # matches lead.md
+relay wrap -n LEAD claude      # matches lead.md
+relay wrap -n lead claude      # matches lead.md
+```
+
+### Creating Role Agents
+
+Create agent files for your team roles:
+
+```
+.claude/agents/
+├── lead.md          # Coordinator, delegates work
+├── implementer.md   # Writes code, fixes bugs
+├── designer.md      # UI/UX, frontend work
+└── reviewer.md      # Code review, quality checks
+```
+
+Each file follows the standard Claude agent format with frontmatter and instructions.
+
+---
+
 ## Team Communication
 
 If you have an INSTRUCTIONS.md file in `/tmp/agent-relay-team/{YourName}/`, use these commands:
@@ -107,8 +161,8 @@ relay team status
 
 **Inline format** (simple messages):
 ```
-@relay:AgentName Your message here
-@relay:* Broadcast to all agents
+->relay:AgentName Your message here
+->relay:* Broadcast to all agents
 ```
 
 **Block format** (structured data):
@@ -137,11 +191,11 @@ Use this when you're wrapped with `relay wrap`.
 
 ### CRITICAL: How to Send Messages
 
-**You (the AI agent) must OUTPUT the @relay pattern as part of your response.** Do not wait for user input. The pattern is detected from your terminal output.
+**You (the AI agent) must OUTPUT the ->relay pattern as part of your response.** Do not wait for user input. The pattern is detected from your terminal output.
 
 **Correct - Output this directly:**
 ```
-@relay:PlayerO I've finished the API refactor. Ready for your review.
+->relay:PlayerO I've finished the API refactor. Ready for your review.
 ```
 
 **Wrong - Don't use bash commands for real-time messaging:**
@@ -152,28 +206,28 @@ relay team send -n MyName -t PlayerO -m "message"
 
 ### Pattern Requirements
 
-The `@relay:` pattern must appear on its own line. It can have common terminal/markdown prefixes:
+The `->relay:` pattern must appear on its own line. It can have common terminal/markdown prefixes:
 
 ```
-@relay:AgentName message          Works
-  @relay:AgentName message        Works (leading whitespace OK)
-> @relay:AgentName message        Works (input prompt OK)
-$ @relay:AgentName message        Works (shell prompt OK)
-- @relay:AgentName message        Works (list items OK)
-* @relay:AgentName message        Works (asterisk lists OK)
-Some text @relay:AgentName msg    Won't work (not at line start)
+->relay:AgentName message          Works
+  ->relay:AgentName message        Works (leading whitespace OK)
+> ->relay:AgentName message        Works (input prompt OK)
+$ ->relay:AgentName message        Works (shell prompt OK)
+- ->relay:AgentName message        Works (list items OK)
+* ->relay:AgentName message        Works (asterisk lists OK)
+Some text ->relay:AgentName msg    Won't work (not at line start)
 ```
 
 ### Examples
 
 **Direct message:**
 ```
-@relay:PlayerO Your turn! I played X at center.
+->relay:PlayerO Your turn! I played X at center.
 ```
 
 **Broadcast to all agents:**
 ```
-@relay:* I've completed the authentication module. Ready for review.
+->relay:* I've completed the authentication module. Ready for review.
 ```
 
 **Structured data:**
@@ -190,7 +244,7 @@ When another agent sends you a message, it appears in your terminal as:
 Relay message from PlayerO: Their message content here
 ```
 
-Respond by outputting another `@relay:` pattern.
+Respond by outputting another `->relay:` pattern.
 
 ### IMPORTANT: Handling Truncated Messages
 
@@ -217,9 +271,9 @@ This retrieves the complete message from the database.
 
 ### Escaping
 
-To output literal `@relay:` without triggering the parser:
+To output literal `->relay:` without triggering the parser:
 ```
-\@relay: This won't be sent as a message
+\->relay: This won't be sent as a message
 ```
 
 ---
@@ -317,7 +371,7 @@ Just 4 commands:
 ### Task Handoff
 
 ```
-@relay:Developer TASK: Implement user registration endpoint
+->relay:Developer TASK: Implement user registration endpoint
 Requirements:
 - POST /api/register
 - Validate email format
@@ -328,29 +382,29 @@ Requirements:
 ### Status Updates
 
 ```
-@relay:* STATUS: Starting work on authentication module
-@relay:* DONE: Authentication module complete, ready for review
-@relay:Reviewer REVIEW: Please review src/auth/*.ts
+->relay:* STATUS: Starting work on authentication module
+->relay:* DONE: Authentication module complete, ready for review
+->relay:Reviewer REVIEW: Please review src/auth/*.ts
 ```
 
 ### Requesting Help
 
 ```
-@relay:Architect QUESTION: Should we use JWT or session-based auth?
-@relay:* BLOCKED: Need database credentials to proceed
+->relay:Architect QUESTION: Should we use JWT or session-based auth?
+->relay:* BLOCKED: Need database credentials to proceed
 ```
 
 ### Code Review Flow
 
 ```
 # Developer requests review
-@relay:Reviewer REVIEW: src/api/users.ts - Added pagination support
+->relay:Reviewer REVIEW: src/api/users.ts - Added pagination support
 
 # Reviewer provides feedback
-@relay:Developer FEEDBACK: Line 45 - Consider using cursor-based pagination for better performance
+->relay:Developer FEEDBACK: Line 45 - Consider using cursor-based pagination for better performance
 
 # Developer confirms fix
-@relay:Reviewer FIXED: Updated to cursor-based pagination, please re-review
+->relay:Reviewer FIXED: Updated to cursor-based pagination, please re-review
 ```
 
 ---
diff --git a/docs/ARCHITECTURE_DECISIONS.md b/docs/ARCHITECTURE_DECISIONS.md
new file mode 100644
index 000000000..ca59bcf3e
--- /dev/null
+++ b/docs/ARCHITECTURE_DECISIONS.md
@@ -0,0 +1,175 @@
+# Multi-Agent Coordination: Architecture Decisions
+
+This document compares approaches to multi-agent coordination and explains when to use each.
+
+## Two Approaches
+
+### 1. Subagents (Hierarchical)
+
+Spawn child agents from a parent, collect results, continue.
+
+```
+       ┌─────────┐
+       │ Parent  │
+       └────┬────┘
+            │ spawn
+    ┌───────┼───────┐
+    ▼       ▼       ▼
+┌───────┐┌───────┐┌───────┐
+│ Child ││ Child ││ Child │
+└───────┘└───────┘└───────┘
+    │       │       │
+    └───────┼───────┘
+            ▼ return
+       ┌─────────┐
+       │ Parent  │
+       └─────────┘
+```
+
+**Characteristics:**
+- Tree topology (parent orchestrates)
+- Synchronous - parent waits for children
+- Ephemeral - children die after returning
+- State held by parent
+- No peer-to-peer communication
+
+### 2. Agent-Relay (Mesh)
+
+Persistent agents communicate via message passing.
+
+```
+┌───────┐     ┌───────┐
+│ Agent │◄───►│ Agent │
+└───┬───┘     └───┬───┘
+    │             │
+    └──────┬──────┘
+           ▼
+    ┌─────────────┐
+    │   Daemon    │ ← routes messages
+    │  (router)   │ ← persists history
+    └─────────────┘
+           │
+    ┌──────┴──────┐
+    ▼             ▼
+┌───────┐     ┌───────┐
+│ Agent │◄───►│ Agent │
+└───────┘     └───────┘
+```
+
+**Characteristics:**
+- Mesh topology (any-to-any)
+- Asynchronous - fire and respond
+- Persistent - agents live across tasks
+- Distributed state + message log
+- Direct peer communication
+
+## Decision Matrix
+
+| Requirement | Subagents | Agent-Relay |
+|-------------|:---------:|:-----------:|
+| Simple one-shot tasks | ✅ | ⚠️ overkill |
+| Clear parent/child hierarchy | ✅ | ✅ |
+| No infrastructure to manage | ✅ | ❌ |
+| Agents debate/negotiate | ❌ | ✅ |
+| Long-running agents | ❌ | ✅ |
+| Mix different AI providers | ⚠️ limited | ✅ |
+| Audit trail / replay | ❌ | ✅ |
+| External observability | ❌ | ✅ |
+| Horizontal scaling | ❌ | ✅ |
+| Resume after crash | ❌ | ✅ |
+
+## When to Use Subagents
+
+Choose subagents when:
+
+1. **Tasks are independent** - Fan out, collect, aggregate
+2. **Hierarchy is natural** - One coordinator, many workers
+3. **No persistence needed** - Results matter, not the conversation
+4. **Same provider** - All agents are Claude (or same SDK)
+5. **Simplicity wins** - Fewer moving parts
+
+**Example use cases:**
+- Parallel code analysis (security, perf, style)
+- Research tasks with multiple queries
+- Map-reduce style workloads
+- One-time batch processing
+
+```typescript
+// Subagent pattern
+const [security, perf, style] = await Promise.all([
+  analyzeSecurityAgent(code),
+  analyzePerfAgent(code),
+  analyzeStyleAgent(code),
+]);
+return summarize(security, perf, style);
+```
+
+## When to Use Agent-Relay
+
+Choose agent-relay when:
+
+1. **Agents need to discuss** - Back-and-forth negotiation
+2. **Persistence matters** - Audit, debug, replay conversations
+3. **Mixed ecosystem** - Claude + Codex + Gemini + custom bots
+4. **External integration** - Dashboard, Slack, webhooks
+5. **Long-running sessions** - Agents stay alive, handle multiple tasks
+6. **Decoupling** - Add/remove agents without code changes
+
+**Example use cases:**
+- Collaborative document editing
+- Multi-agent game playing
+- Continuous monitoring systems
+- Team simulations with distinct personas
+- Human-in-the-loop workflows
+
+```typescript
+// Agent-relay pattern
+const daemon = new Daemon({ socketPath, storagePath });
+await daemon.start();
+
+// Agents live independently, communicate async
+const architect = new RelayClient({ name: 'Architect', socketPath });
+const developer = new RelayClient({ name: 'Developer', socketPath });
+const reviewer = new RelayClient({ name: 'Reviewer', socketPath });
+
+// They message each other directly
+architect.send({ to: 'Developer', body: 'Implement auth module' });
+// Developer works, then...
+developer.send({ to: 'Reviewer', body: 'Ready for review' });
+// Reviewer responds to Developer directly
+```
+
+## Hybrid Approach
+
+You can combine both:
+
+```
+┌─────────────────────────────────────┐
+│           Orchestrator              │
+│         (agent-relay)               │
+└──────┬──────────────┬───────────────┘
+       │              │
+       ▼              ▼
+┌─────────────┐ ┌─────────────┐
+│  Team Lead  │ │  Team Lead  │
+│  (relay)    │ │  (relay)    │
+└──────┬──────┘ └──────┬──────┘
+       │               │
+   ┌───┴───┐       ┌───┴───┐
+   ▼       ▼       ▼       ▼
+┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
+│Sub 1│ │Sub 2│ │Sub 3│ │Sub 4│  ← subagents
+└─────┘ └─────┘ └─────┘ └─────┘
+```
+
+- **Agent-relay** for cross-team coordination
+- **Subagents** for parallelizable work within a team
+
+## Summary
+
+| Approach | Mental Model | Best For |
+|----------|--------------|----------|
+| Subagents | Function calls | Hierarchical, stateless, one-shot |
+| Agent-Relay | Microservices | Mesh, persistent, observable |
+
+**Rule of thumb:** Start with subagents. Move to agent-relay when you need persistence, observability, or peer-to-peer communication.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 877cded5b..8de9f1df3 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -5,7 +5,7 @@
 Initial public release.
 
 - Local daemon + client protocol for low-latency agent messaging (Unix domain sockets).
-- `agent-relay wrap` for intercepting `@relay:AgentName ...` and `[[RELAY]]...[[/RELAY]]` messages.
+- `agent-relay wrap` for intercepting `->relay:AgentName ...` and `[[RELAY]]...[[/RELAY]]` messages.
 - Inbox utilities (`inbox-write`, `inbox-poll`, etc.) for file-based coordination in shared workspaces.
 - Built-in demos/games (e.g., tic-tac-toe) to validate turn-based coordination.
 
diff --git a/docs/COMPETITIVE_ANALYSIS.md b/docs/COMPETITIVE_ANALYSIS.md
new file mode 100644
index 000000000..ae62fb665
--- /dev/null
+++ b/docs/COMPETITIVE_ANALYSIS.md
@@ -0,0 +1,897 @@
+# Multi-Agent Orchestration: Competitive Analysis
+
+*Generated: December 2025*
+
+## Executive Summary
+
+This analysis evaluates 16 multi-agent orchestration tools against agent-relay. The key finding is that **most tools don't provide true real-time agent-to-agent communication** - they use sub-agent delegation, file-based polling, or shared databases instead.
+
+**agent-relay's differentiators:**
+- Real-time messaging via Unix Domain Socket (sub-5ms latency)
+- Direct peer-to-peer agent communication (not just orchestrator-worker)
+- No API key required (wraps existing CLI tools)
+- Simple `->relay:` pattern for messaging
+
+---
+
+## Quick Comparison Matrix
+
+| Tool | API Key? | Communication Type | Mechanism | Real-time? | Memory |
+|------|----------|-------------------|-----------|------------|--------|
+| **agent-relay** | No | Direct P2P | Unix socket | Yes | SQLite (pluggable) |
+| Multiagent Chat | No | File + PTY push | Outbox → PTY write | Partial | JSONL chat log |
+| AI Maestro | No (OAuth) | File + WebSocket | File-based queues | Partial | Built-in (code graph) |
+| Toad | Yes | Protocol-based | ACP/A2A protocol | No | Minimal |
+| Oh-My-OpenCode | Yes (multi) | Hierarchical | Sub-agent delegation | No | Context-based |
+| Auto-Claude | Yes | Isolated | Git worktrees | No | Optional (Graphiti) |
+| Maestro | Yes | Group chat + IPC | Electron IPC | Partial | Ephemeral |
+| ACFS | Yes (multi) | File + HTTP | mcp_agent_mail | No | Hybrid (cm) |
+| Claude-Flow | No | Hive-mind | Message bus | Yes | Built-in (AgentDB) |
+| Vibe Kanban | Yes | Unknown | Undocumented | Unknown | Unknown |
+| AxonFlow | Yes | Centralized | Service mesh | Partial | External (Postgres) |
+| Mimir | Optional | Shared DB | Neo4j graph | No | Built-in (Neo4j) |
+| Claude MPM | No | Orchestrator | Subprocess | No | Pluggable |
+| Multi-MCP | Yes | Parallel LLM | asyncio.gather | N/A | None |
+| Every Code | Yes | Consensus | Racing pattern | Partial | Session-based |
+| Orc | Yes | File-based | Drums directory | No | State files |
+| Pied Piper | Yes | Task-based | Beads labels | No | Beads |
+
+---
+
+## Tier 1: Most Relevant Competitors (Check First)
+
+### 1. Claude-Flow (ruvnet/claude-flow)
+**Most Similar to agent-relay**
+
+**Communication:** Queen-led hive-mind with message bus pattern
+- 19-file coordination system with work-stealing
+- MCP tools for swarm orchestration
+- Circuit breakers and distributed locking
+
+**Key Stats:**
+- 84.8% SWE-Bench solve rate
+- 96x-164x memory query performance boost
+- No API key required (hash-based embeddings)
+
+**Pros:**
+- Sophisticated coordination (scheduling, load balancing, fault tolerance)
+- Built-in memory (AgentDB with HNSW indexing)
+- 25 specialized skills + 9 RL algorithms
+
+**Cons:**
+- Very complex (steep learning curve)
+- Heavy resource requirements
+- Overkill for simple orchestration
+
+**What We Can Learn:**
+- Work-stealing for dynamic load balancing
+- Circuit breaker patterns for fault tolerance
+- Dependency graph for task ordering
+
+**Where We're Stronger:**
+- Simpler to understand and use
+- Lighter weight
+- Direct terminal integration with tmux
+
+---
+
+### 2. Maestro (pedramamini/Maestro)
+**Best Desktop UI**
+
+**Communication:** Group chat with AI moderator + Git worktrees
+- Dual-process sessions (AI agent + terminal)
+- Message queueing while agents busy
+- Electron IPC for internal coordination
+
+**Pros:**
+- Rich desktop UI with three-panel layout
+- Auto Run playbooks for batch processing
+- Mobile access via Cloudflare tunnels
+- Session discovery from existing Claude Code
+
+**Cons:**
+- Desktop-only (requires Electron)
+- No persistent cross-session memory
+- Single-agent per session limitation
+
+**What We Can Learn:**
+- Playbook system for automated task batching
+- Session discovery/import from existing tools
+- QR code + tunneling for mobile access
+
+**Where We're Stronger:**
+- CLI-native (no Electron overhead)
+- True multi-agent in single project
+- Persistent message history
+
+---
+
+### 3. AI Maestro (23blocks-OS/ai-maestro)
+**Best Remote/Multi-Machine**
+
+**Communication:** File-based messaging + WebSocket proxy
+- Priority queues (urgent/high/normal/low)
+- Persistent inbox/outbox per agent
+- CLI scripts for agent-to-agent messaging
+
+**Pros:**
+- Excellent mobile support (Tailscale VPN)
+- Scales to 100+ agents across machines
+- Rich memory (code graph, semantic search)
+- Portable agent export/import
+
+**Cons:**
+- File-based messaging has latency
+- Complex setup (PM2, SSH, tmux)
+- macOS 15+ needs daemon fixes
+
+**What We Can Learn:**
+- Multi-machine support architecture
+- Agent portability (export/import)
+- Code graph visualization
+- Priority-based message queuing
+
+**Where We're Stronger:**
+- Real-time messaging (not file polling)
+- Simpler single-machine setup
+- No PM2/SSH complexity
+
+---
+
+## Tier 2: Interesting Approaches
+
+### 4. Multiagent Chat (appoly/multiagent-chat)
+**Best Planning/Discussion Workflow**
+
+**Communication:** File-based outbox with PTY push delivery
+- Each agent writes to its outbox markdown file
+- Chokidar file watcher detects changes
+- Messages pushed to other agents via `pty.write()` or `stdin.write()`
+- Immutable chat log in JSONL format
+
+**Architecture:**
+- Electron desktop app with xterm terminals
+- node-pty for pseudo-terminal management
+- YAML configuration for agents
+- Two-phase workflow: Planning → Implementation
+
+**Pros:**
+- Nice desktop UI with live xterm terminals
+- Works with existing CLI tools (Claude, Codex)
+- Structured planning workflow with PLAN_FINAL.md output
+- Peer review during implementation phase
+- Message sequence numbering for ordering
+- No API key required (uses local CLI auth)
+
+**Cons:**
+- Electron-only (desktop required)
+- File-based messaging adds latency
+- Node.js v23+ not supported (native module issues)
+- Limited to discussion/planning workflow
+- No persistent memory across sessions
+- Push-based but not true real-time socket
+
+**Technical Details:**
+```yaml
+agents:
+  - name: "Claude"
+    command: "claude"
+    args: ['--dangerously-skip-permissions']
+    use_pty: true
+```
+
+**What We Can Learn:**
+- Structured planning workflow before implementation
+- Peer review patterns for agent collaboration
+- xterm terminal embedding for agent visibility
+- Message sequence numbering for ordering
+
+**Where We're Stronger:**
+- True real-time Unix socket (<5ms vs file I/O latency)
+- CLI-native (no Electron overhead)
+- Direct P2P messaging (not file-mediated)
+- Works with Node.js v23+
+- More flexible use cases (not just planning)
+
+---
+
+### 5. Mimir (orneryd/Mimir)
+**Best Memory System**
+
+**Communication:** Indirect via shared Neo4j graph database
+- Multi-agent locking mechanism
+- 13 MCP tools for memory operations
+- No direct messaging (async via DB)
+
+**Pros:**
+- Persistent knowledge graph
+- Semantic search with embeddings
+- PM/Worker/QC workflow patterns
+- Can run offline with Ollama
+
+**Cons:**
+- Complex infrastructure (Docker + Neo4j)
+- No real-time direct messaging
+- Resource intensive
+
+**What We Can Learn:**
+- Knowledge graph for persistent context
+- Multi-agent locking patterns
+- Role-specific context filtering
+
+**Where We're Stronger:**
+- Real-time communication
+- Simpler setup
+- Direct agent-to-agent messaging
+
+---
+
+### 5. ACFS (Dicklesworthstone/agentic_coding_flywheel_setup)
+**Best Developer Environment**
+
+**Communication:** MCP HTTP server (mcp_agent_mail) + file-based state
+- 8-tool "Dicklesworthstone stack"
+- Named tmux session management
+- Procedural memory across sessions
+
+**Pros:**
+- VPS-optimized with 30-min setup
+- Comprehensive dev environment (30+ tools)
+- Persistent learning via cass-memory
+- Safety mechanisms (two-person rule)
+
+**Cons:**
+- VPS-only (not for local dev)
+- Asynchronous (not real-time)
+- Complex 11-category install
+
+**What We Can Learn:**
+- mcp_agent_mail patterns for messaging
+- Procedural memory (cm) for learned patterns
+- Safety mechanisms for dangerous commands
+
+**Where We're Stronger:**
+- Works locally (not VPS-only)
+- Real-time sync
+- Simpler setup
+
+---
+
+### 6. Orc (bsmith24/orc)
+**Simplest Two-Agent System**
+
+**Communication:** File-based "drums" directory
+- `pm_out.txt` / `dev_out.txt` for responses
+- `pm_in.txt` / `dev_in.txt` for input
+- Approval tracking files
+
+**Pros:**
+- Dead simple architecture
+- Clear Taskmaster/Builder separation
+- Session persistence via state files
+- Works with existing Claude CLI
+
+**Cons:**
+- Only two agents
+- No real-time updates
+- Manual file-watching
+
+**What We Can Learn:**
+- Simple file-based approach can work
+- Clear role separation patterns
+- Session state persistence
+
+**Where We're Stronger:**
+- Unlimited agents
+- Real-time messaging
+- Automatic message routing
+
+---
+
+### 7. Pied Piper (sathish316/pied-piper)
+**Best Task-Centric Approach**
+
+**Communication:** Beads-based task labels
+- Label-based routing (`@ready-for-hld`, etc.)
+- Human-in-loop approvals
+- YAML playbook configurations
+
+**Pros:**
+- Integrates with Beads for task tracking
+- Multi-model ensembles
+- Full audit trails
+- Customizable team configs
+
+**Cons:**
+- Not real-time communication
+- Task-based (not message-based)
+- Requires Go build
+
+**What We Can Learn:**
+- Beads integration patterns (we already use this!)
+- Playbook YAML structure for teams
+- Audit trail approaches
+
+**Where We're Stronger:**
+- Real-time messaging vs task handoffs
+- Direct communication vs label routing
+- Simpler npm install
+
+---
+
+## Tier 3: Different Focus
+
+### 8. Oh-My-OpenCode
+**Best Multi-Model Strategy**
+
+Uses hierarchical sub-agents (Sisyphus → Oracle → Frontend Engineer → Librarian) with different models for different roles. $24k token investment in refinement.
+
+**Best for:** Sophisticated multi-model workflows
+**Not competing on:** Direct agent communication
+
+---
+
+### 9. Auto-Claude
+**Best Parallel Isolation**
+
+Up to 12 agents in isolated git worktrees. AI-assisted conflict resolution during merge. Optional Graphiti memory layer.
+
+**Best for:** Autonomous parallel development
+**Not competing on:** Agent collaboration
+
+---
+
+### 10. AxonFlow
+**Best Enterprise Governance**
+
+Policy-first with PII detection, SQL injection blocking. Multi-model routing based on cost/compliance.
+
+**Best for:** Regulated environments
+**Not competing on:** Developer workflow
+
+---
+
+### 11. Every Code (just-every/code)
+**Best Consensus Approach**
+
+Multiple agents compete or collaborate via `/plan` (consensus) and `/solve` (fastest wins).
+
+**Best for:** Quick task completion
+**Not competing on:** Persistent collaboration
+
+---
+
+### 12. Toad
+**Best Terminal UI**
+
+Beautiful TUI for 12+ different AI agents. Uses Agent Client Protocol (ACP) merged with Google's A2A.
+
+**Best for:** Unified terminal experience
+**Not competing on:** Multi-agent orchestration
+
+---
+
+### 13. Vibe Kanban
+**Best Visual Workflow**
+
+Kanban-style task management with agent switching. Rust + TypeScript. 6.7k stars.
+
+**Best for:** Visual project management
+**Not competing on:** Agent communication (undocumented)
+
+---
+
+### 14. Claude MPM
+**Best Agent Library**
+
+47+ specialized agents from curated repos. Intelligent routing via orchestrator.
+
+**Best for:** Finding the right agent for a task
+**Not competing on:** Direct agent messaging
+
+---
+
+### 15. Multi-MCP
+**Not True Multi-Agent**
+
+Just parallel LLM calls via asyncio.gather(). Useful for consensus but agents don't communicate.
+
+---
+
+## Communication Mechanism Comparison
+
+### Real-Time Direct (Like agent-relay)
+| Tool | Mechanism | Latency |
+|------|-----------|---------|
+| agent-relay | Unix Domain Socket | <5ms |
+| Claude-Flow | Message Bus | Low |
+| Maestro | Electron IPC | Low |
+
+### File-Based Async
+| Tool | Mechanism | Latency |
+|------|-----------|---------|
+| Multiagent Chat | Outbox → PTY push | ~50-100ms |
+| AI Maestro | Priority queues | ~100ms+ |
+| ACFS | mcp_agent_mail | ~100ms+ |
+| Orc | Drums directory | Polling |
+
+### Sub-Agent/Delegation
+| Tool | Pattern |
+|------|---------|
+| Oh-My-OpenCode | Hierarchical (Sisyphus model) |
+| Claude MPM | Orchestrator → specialists |
+| Auto-Claude | Isolated worktrees |
+
+### Shared State
+| Tool | Mechanism |
+|------|-----------|
+| Mimir | Neo4j graph database |
+| Pied Piper | Beads labels |
+| AxonFlow | PostgreSQL + Redis |
+
+---
+
+## Memory Architecture Comparison
+
+### Built-In Sophisticated
+- **Claude-Flow:** AgentDB + 4-layer architecture + HNSW indexing
+- **Mimir:** Neo4j knowledge graph + semantic embeddings
+- **AI Maestro:** Code graph + conversation indexing
+
+### Component/Pluggable
+- **agent-relay:** SQLite (default) or memory adapter
+- **ACFS:** cass-memory for procedural patterns
+- **Auto-Claude:** Optional Graphiti layer
+
+### Minimal/Session-Only
+- **Maestro:** Ephemeral (context isolation focus)
+- **Claude MPM:** Resume logs only
+- **Multi-MCP:** Conversation threading
+
+---
+
+## Remote/Mobile Access
+
+| Tier | Tools |
+|------|-------|
+| **Excellent** | AI Maestro (Tailscale VPN, mobile UI) |
+| **Good** | Maestro (Cloudflare tunnels), Claude-Flow (Flow Nexus cloud) |
+| **Partial** | Vibe Kanban (SSH), AxonFlow (SDKs), Mimir (Docker web) |
+| **None** | Claude MPM, Oh-My-OpenCode, Auto-Claude, Orc |
+
+agent-relay: **Partial** (dashboard at localhost:3888, could add remote tunneling)
+
+---
+
+## Recommended Priority for Investigation
+
+### Must Study (High Priority)
+1. **Claude-Flow** - Most sophisticated coordination, similar goals
+2. **Maestro** - Best UX patterns, mobile access approach
+3. **AI Maestro** - Multi-machine scaling, agent portability
+
+### Should Study (Medium Priority)
+4. **Multiagent Chat** - Planning workflow, peer review patterns
+5. **Mimir** - Memory/knowledge graph patterns
+6. **ACFS** - mcp_agent_mail patterns, procedural memory
+7. **Pied Piper** - Already uses Beads, complementary
+
+### Worth Knowing (Low Priority)
+8. **Orc** - Simple file-based reference
+9. **Every Code** - Consensus patterns
+10. **Oh-My-OpenCode** - Multi-model strategies
+
+---
+
+## What agent-relay Should Learn
+
+### From Claude-Flow
+- [ ] Work-stealing for load balancing
+- [ ] Circuit breaker patterns
+- [ ] Dependency graph for task ordering
+- [ ] HNSW indexing for fast memory queries
+
+### From Maestro
+- [ ] Session discovery from existing Claude Code
+- [ ] Playbook system for automated batching
+- [ ] Cloudflare tunneling for remote access
+- [ ] QR code for easy mobile connection
+
+### From AI Maestro
+- [ ] Multi-machine agent support
+- [ ] Agent portability (export/import)
+- [ ] Priority-based message queuing
+- [ ] Code graph visualization
+
+### From Mimir
+- [ ] Knowledge graph for persistent context
+- [ ] Multi-agent locking mechanisms
+- [ ] Role-specific context filtering
+
+### From ACFS
+- [ ] Procedural memory for learned patterns
+- [ ] Safety mechanisms (two-person rule)
+- [ ] Named tmux session management patterns
+
+### From Multiagent Chat
+- [ ] Structured planning phase before implementation
+- [ ] Peer review workflow for agent collaboration
+- [ ] xterm terminal embedding in dashboard
+- [ ] Message sequence numbering for ordering
+
+---
+
+## Where agent-relay is Stronger
+
+| vs Tool | Our Advantage |
+|---------|---------------|
+| Most competitors | True real-time messaging (<5ms) |
+| File-based (AI Maestro, Orc, ACFS, Multiagent Chat) | No polling, instant delivery |
+| Sub-agent (Claude MPM, Oh-My-OpenCode) | Direct P2P, not orchestrator bottleneck |
+| Desktop (Maestro, Multiagent Chat) | CLI-native, no Electron overhead |
+| Complex (Claude-Flow) | Simple to understand and use |
+| VPS-only (ACFS) | Works locally |
+| Heavy (Mimir) | Lightweight, no Neo4j required |
+| Multiagent Chat | Node.js v23+ support, flexible use cases |
+
+---
+
+## Gaps to Address
+
+### High Priority
+1. **Remote/Mobile Access** - Most competitors have this, we don't
+2. **Multi-Machine Support** - AI Maestro does this well
+3. **Persistent Memory** - Claude-Flow and Mimir have sophisticated approaches
+
+### Medium Priority
+4. **Playbooks/Automation** - Maestro's batch processing approach
+5. **Session Discovery** - Import existing Claude Code sessions
+6. **Priority Queuing** - AI Maestro's urgent/high/normal/low
+
+### Nice to Have
+7. **Work-Stealing** - From Claude-Flow for load balancing
+8. **Circuit Breakers** - Fault tolerance patterns
+9. **Agent Portability** - Export/import agent state
+
+---
+
+## Solution Rankings by Use Case
+
+### Overall Tier List
+
+| Tier | Tools | Why |
+|------|-------|-----|
+| **S-Tier** | Claude-Flow | Most complete feature set, proven SWE-Bench results |
+| **A-Tier** | agent-relay, Maestro, AI Maestro | Strong in specific areas, production-viable |
+| **B-Tier** | Multiagent Chat, Mimir, ACFS | Good for specific workflows, some limitations |
+| **C-Tier** | Orc, Pied Piper, Every Code | Niche use cases or early stage |
+| **D-Tier** | Multi-MCP, Toad | Not true multi-agent or limited scope |
+
+---
+
+### Best Solution by Use Case
+
+#### 1. Real-Time Agent Communication
+*Need: Agents talking to each other with minimal latency*
+
+| Rank | Tool | Latency | Notes |
+|------|------|---------|-------|
+| 🥇 | **agent-relay** | <5ms | Unix socket, direct P2P |
+| 🥈 | Claude-Flow | Low | Message bus, more overhead |
+| 🥉 | Maestro | Low | Electron IPC, desktop only |
+| 4th | Multiagent Chat | ~50-100ms | File → PTY push |
+| 5th | AI Maestro | ~100ms+ | File-based queues |
+
+**Winner: agent-relay** - Fastest, simplest real-time messaging
+
+---
+
+#### 2. Easiest Setup / Getting Started
+*Need: Minimal configuration, works out of the box*
+
+| Rank | Tool | Setup Time | Requirements |
+|------|------|------------|--------------|
+| 🥇 | **agent-relay** | ~1 min | npm install, no config needed |
+| 🥈 | Orc | ~2 min | Simple file-based, 2 agents only |
+| 🥉 | Multiagent Chat | ~5 min | npm install, YAML config |
+| 4th | Maestro | ~10 min | Electron install, desktop app |
+| 5th | Claude-Flow | ~15 min | Complex configuration |
+| 6th | Mimir | ~30 min | Docker + Neo4j setup |
+| 7th | ACFS | ~30 min | VPS + 11-category install |
+
+**Winner: agent-relay** - `npm i -g agent-relay && agent-relay up`
+
+---
+
+#### 3. Rich Desktop UI / Visualization
+*Need: Visual interface for monitoring agents*
+
+| Rank | Tool | UI Type | Features |
+|------|------|---------|----------|
+| 🥇 | **Maestro** | Electron | Three-panel layout, session discovery |
+| 🥈 | **Multiagent Chat** | Electron | xterm terminals, live chat |
+| 🥉 | Vibe Kanban | Web | Kanban boards (6.7k stars) |
+| 4th | agent-relay | Web | Dashboard at localhost:3888 |
+| 5th | AI Maestro | Web | Basic status dashboard |
+| 6th | Claude-Flow | CLI | Flow Nexus (limited) |
+
+**Winner: Maestro** - Best desktop experience with mobile access
+
+---
+
+#### 4. Enterprise / Production Scale
+*Need: Governance, compliance, fault tolerance*
+
+| Rank | Tool | Governance | Scale | Fault Tolerance |
+|------|------|------------|-------|-----------------|
+| 🥇 | **AxonFlow** | PII detection, policy-first | High | Service mesh |
+| 🥈 | **Claude-Flow** | Circuit breakers | High | Work-stealing, locking |
+| 🥉 | AI Maestro | Basic | 100+ agents | PM2 process management |
+| 4th | agent-relay | None | Medium | SQLite persistence |
+| 5th | Mimir | Multi-agent locking | Medium | Neo4j reliability |
+
+**Winner: AxonFlow** - Built for regulated environments
+
+---
+
+#### 5. Multi-Machine / Distributed Agents
+*Need: Agents running on different machines*
+
+| Rank | Tool | Multi-Machine | Mobile Access |
+|------|------|---------------|---------------|
+| 🥇 | **AI Maestro** | Native (SSH, PM2) | Tailscale VPN |
+| 🥈 | **Maestro** | Cloudflare tunnels | QR code pairing |
+| 🥉 | Claude-Flow | Flow Nexus cloud | Partial |
+| 4th | ACFS | VPS-native | SSH |
+| 5th | agent-relay | Not yet | Dashboard only |
+
+**Winner: AI Maestro** - Purpose-built for distributed teams
+
+---
+
+#### 6. Persistent Memory / Knowledge Graph
+*Need: Agents remembering context across sessions*
+
+| Rank | Tool | Memory Type | Sophistication |
+|------|------|-------------|----------------|
+| 🥇 | **Mimir** | Neo4j knowledge graph | Semantic embeddings |
+| 🥈 | **Claude-Flow** | AgentDB + HNSW | 4-layer architecture |
+| 🥉 | AI Maestro | Code graph + indexing | Conversation memory |
+| 4th | ACFS | cass-memory | Procedural patterns |
+| 5th | agent-relay | SQLite | Message history only |
+| 6th | Multiagent Chat | JSONL | Chat log only |
+
+**Winner: Mimir** - Full knowledge graph with semantic search
+
+---
+
+#### 7. Planning & Structured Workflows
+*Need: Formal planning before implementation*
+
+| Rank | Tool | Planning Features |
+|------|------|-------------------|
+| 🥇 | **Multiagent Chat** | Two-phase workflow, PLAN_FINAL.md, peer review |
+| 🥈 | **Pied Piper** | Beads integration, playbooks, audit trails |
+| 🥉 | **Maestro** | Auto Run playbooks, batch processing |
+| 4th | Oh-My-OpenCode | Hierarchical refinement ($24k token investment) |
+| 5th | agent-relay | No built-in workflow |
+
+**Winner: Multiagent Chat** - Purpose-built for planning discussions
+
+---
+
+#### 8. Multi-Model Orchestration
+*Need: Different AI models for different tasks*
+
+| Rank | Tool | Models Supported | Routing |
+|------|------|------------------|---------|
+| 🥇 | **Oh-My-OpenCode** | Multiple (Sisyphus hierarchy) | Role-based |
+| 🥈 | **AxonFlow** | Multiple | Cost/compliance routing |
+| 🥉 | **Toad** | 12+ agents | Unified TUI |
+| 4th | Every Code | Multiple | Consensus/racing |
+| 5th | agent-relay | Any CLI | No routing (user choice) |
+
+**Winner: Oh-My-OpenCode** - Sophisticated multi-model workflows
+
+---
+
+#### 9. CLI-Native / Lightweight
+*Need: Terminal-first, minimal resource usage*
+
+| Rank | Tool | Runtime | Memory Footprint |
+|------|------|---------|------------------|
+| 🥇 | **agent-relay** | Node.js CLI | ~50MB |
+| 🥈 | **Orc** | Shell scripts | ~10MB |
+| 🥉 | Claude-Flow | Node.js | ~200MB |
+| 4th | ACFS | Node.js + tools | ~300MB |
+| 5th | Maestro | Electron | ~500MB+ |
+| 6th | Mimir | Docker + Neo4j | ~2GB+ |
+
+**Winner: agent-relay** - Lightest full-featured solution
+
+---
+
+#### 10. Parallel Development / Isolation
+*Need: Multiple agents working on same codebase without conflicts*
+
+| Rank | Tool | Isolation Method |
+|------|------|------------------|
+| 🥇 | **Auto-Claude** | Git worktrees (up to 12 agents) |
+| 🥈 | **Maestro** | Session isolation per worktree |
+| 🥉 | agent-relay | tmux sessions (shared codebase) |
+| 4th | Every Code | Racing pattern |
+
+**Winner: Auto-Claude** - Purpose-built for parallel isolation
+
+---
+
+### Quick Decision Matrix
+
+| If you need... | Use this |
+|----------------|----------|
+| **Fastest setup** | agent-relay |
+| **Real-time chat between agents** | agent-relay |
+| **Beautiful desktop UI** | Maestro or Multiagent Chat |
+| **Agents on multiple machines** | AI Maestro |
+| **Enterprise governance** | AxonFlow |
+| **Persistent knowledge graph** | Mimir |
+| **Structured planning workflow** | Multiagent Chat |
+| **Different models for different tasks** | Oh-My-OpenCode |
+| **Lightest resource usage** | agent-relay or Orc |
+| **Parallel isolated development** | Auto-Claude |
+| **Most features overall** | Claude-Flow |
+
+---
+
+### Where agent-relay Wins
+
+| Use Case | Why agent-relay |
+|----------|-----------------|
+| **Quick prototyping** | 1-minute setup, immediate messaging |
+| **Real-time collaboration** | <5ms latency, direct P2P |
+| **CLI workflows** | No Electron, integrates with tmux |
+| **Simple multi-agent** | Just works with existing Claude/Codex |
+| **Resource-constrained** | Lightweight, no Docker/Neo4j |
+
+### Where agent-relay Should Defer
+
+| Use Case | Better Choice | Why |
+|----------|---------------|-----|
+| Enterprise compliance | AxonFlow | Policy-first, PII detection |
+| Visual workflows | Maestro | Rich desktop UI |
+| Multi-machine | AI Maestro | Native distributed support |
+| Knowledge persistence | Mimir | Neo4j graph database |
+| Planning discussions | Multiagent Chat | Structured workflow |
+| Parallel isolation | Auto-Claude | Git worktree isolation |
+
+---
+
+## agent-relay as a Composable Layer
+
+### The Integration Advantage
+
+Most competitors try to be **complete solutions** - handling communication, memory, UI, workflows, and orchestration. agent-relay takes a different approach: **do one thing exceptionally well** (real-time messaging) and integrate with best-of-breed tools for everything else.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Your Agent System                        │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   Mimir     │  │  Maestro    │  │  Pied Piper │         │
+│  │  (Memory)   │  │    (UI)     │  │ (Workflows) │         │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
+│         │                │                │                 │
+│         └────────────────┼────────────────┘                 │
+│                          │                                  │
+│                ┌─────────▼─────────┐                        │
+│                │   agent-relay     │                        │
+│                │  (Real-time P2P)  │                        │
+│                │     <5ms          │                        │
+│                └─────────┬─────────┘                        │
+│                          │                                  │
+│         ┌────────────────┼────────────────┐                 │
+│         │                │                │                 │
+│    ┌────▼────┐     ┌────▼────┐     ┌────▼────┐             │
+│    │ Claude  │     │  Codex  │     │  Gemini │             │
+│    └─────────┘     └─────────┘     └─────────┘             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Composition Examples
+
+| Combine agent-relay with... | You get... |
+|-----------------------------|------------|
+| **Mimir** | Real-time chat + persistent knowledge graph |
+| **Maestro** | Real-time messaging + rich desktop UI |
+| **Beads/Pied Piper** | Real-time chat + dependency-aware task tracking |
+| **Auto-Claude** | Real-time coordination + isolated git worktrees |
+| **AxonFlow** | Real-time P2P + enterprise governance layer |
+| **ACFS** | Real-time sync + procedural memory |
+
+### Why This Matters
+
+**Monolithic solutions** (Claude-Flow, AI Maestro):
+- ✅ Everything works together out of the box
+- ❌ Locked into their choices (Neo4j, Electron, etc.)
+- ❌ Hard to swap components
+- ❌ Heavier resource usage
+
+**Composable approach** (agent-relay + X):
+- ✅ Best tool for each job
+- ✅ Swap components as better ones emerge
+- ✅ Lighter base footprint
+- ✅ Works with existing infrastructure
+- ❌ Requires integration work
+
+### Potential Integrations Roadmap
+
+| Integration | Benefit | Complexity |
+|-------------|---------|------------|
+| **Mimir adapter** | Add Neo4j memory to agent-relay | Medium |
+| **Maestro bridge** | Use Maestro UI with relay messaging | Medium |
+| **Beads sync** | Auto-create Beads issues from agent messages | Low (already partial) |
+| **Cloudflare tunnel** | Remote access like Maestro | Low |
+| **MCP server** | Expose relay as MCP tools | Low |
+
+### Revised Tier List (as Integration Layer)
+
+When considering agent-relay as a **messaging layer** rather than complete solution:
+
+| Scenario | Tier |
+|----------|------|
+| Standalone simple multi-agent | **A-Tier** |
+| + Mimir for memory | **S-Tier** (best of both) |
+| + Maestro UI | **S-Tier** (best of both) |
+| + Beads for workflows | **A-Tier** (already works) |
+| Enterprise (+ AxonFlow governance) | **A-Tier** |
+
+### The Unix Philosophy
+
+agent-relay follows the Unix philosophy:
+- **Do one thing well**: Real-time agent messaging
+- **Work with others**: Simple patterns (`->relay:`), standard I/O
+- **Text streams**: Messages are just text, easy to parse/transform
+- **Composability**: Pipe into other tools, wrap other CLIs
+
+This is why agent-relay can potentially **beat Claude-Flow** in a composed system - you get real-time messaging without the 19-file coordination complexity, then add only the features you actually need.
+
+---
+
+## Conclusion
+
+agent-relay occupies a unique position: **the real-time messaging layer for multi-agent systems**.
+
+### Standalone Value
+- Simple, real-time, direct agent-to-agent communication
+- No API keys required (wraps existing CLI tools)
+- <5ms latency via Unix Domain Socket
+- 1-minute setup
+
+### Composable Value
+- **Messaging primitive** that integrates with best-of-breed tools
+- Combine with Mimir (memory), Maestro (UI), Beads (workflows)
+- Unix philosophy: do one thing well, compose with others
+- Lighter than monolithic solutions
+
+### Competitive Position
+
+| Approach | Example | agent-relay's Role |
+|----------|---------|-------------------|
+| Monolithic | Claude-Flow | Alternative (simpler) |
+| File-based | AI Maestro, Orc | Replacement (faster) |
+| Desktop-only | Maestro, Multiagent Chat | Complement (CLI layer) |
+| Memory-focused | Mimir | Complement (add messaging) |
+| Workflow-focused | Pied Piper | Complement (add real-time) |
+
+### Strategic Direction
+
+**Short-term:** Best standalone real-time messaging for simple multi-agent
+**Long-term:** The messaging backbone that other tools integrate with
+
+**Key opportunities:**
+1. **MCP server** - Expose relay as MCP tools for broader integration
+2. **Cloudflare tunnel** - Remote access like Maestro
+3. **Mimir adapter** - Optional persistent memory
+4. **Maestro bridge** - Use their UI with our messaging
+
+**Biggest threat:** Claude-Flow has similar real-time capabilities with more features, but is significantly more complex. The composable approach may win in the long run as developers prefer best-of-breed components over monolithic solutions.
diff --git a/docs/DESIGN_BRIDGE_STAFFING.md b/docs/DESIGN_BRIDGE_STAFFING.md
new file mode 100644
index 000000000..88261df78
--- /dev/null
+++ b/docs/DESIGN_BRIDGE_STAFFING.md
@@ -0,0 +1,878 @@
+# Bridge & Staffing: Multi-Project Agent Orchestration
+
+## Overview
+
+This document describes the **Bridge** feature - a multi-project orchestration layer that allows a single agent (the **Architect** or **Principal**) to coordinate work across multiple projects, each managed by a **Lead** who can dynamically **staff** worker agents.
+
+This builds on the existing agent-relay infrastructure while adding:
+1. Cross-project communication via socket bridging
+2. SE role hierarchy (Architect → Lead → Engineer)
+3. Dynamic agent spawning by Leads
+4. Multi-project dashboard visibility
+
+---
+
+## Terminology
+
+| Term | Description |
+|------|-------------|
+| **Bridge** | CLI command and mode for multi-project orchestration |
+| **Architect** / **Principal** | SE role for the bridging agent (cross-project coordinator) |
+| **Lead** | Project leader (Tech Lead) - one per project, can spawn workers |
+| **Engineer** / **Worker** | Agents spawned by Leads to execute specific tasks |
+| **Spawn** | Action of creating a new worker agent |
+| **Standup** | Morning coordination where Architect assigns work to Leads |
+
+---
+
+## Architecture
+
+```
+                        ┌─────────────────────────────────────┐
+                        │        ARCHITECT (bridge agent)     │
+                        │   agent-relay bridge --as architect │
+                        │                                     │
+                        │   ┌─────────────────────────────┐   │
+                        │   │   MultiProjectClient        │   │
+                        │   │   - projectSockets: Map     │   │
+                        │   │   - projectLeads: Map       │   │
+                        │   └─────────────────────────────┘   │
+                        └──────────────┬──────────────────────┘
+                                       │
+               ┌───────────────────────┼───────────────────────┐
+               │                       │                       │
+               ▼                       ▼                       ▼
+      ┌────────────────┐      ┌────────────────┐      ┌────────────────┐
+      │ auth-service   │      │ frontend       │      │ api-service    │
+      │ Project Daemon │      │ Project Daemon │      │ Project Daemon │
+      │                │      │                │      │                │
+      │ Socket:        │      │ Socket:        │      │ Socket:        │
+      │ /tmp/.../auth/ │      │ /tmp/.../fe/   │      │ /tmp/.../api/  │
+      └───────┬────────┘      └───────┬────────┘      └───────┬────────┘
+              │                       │                       │
+              ▼                       ▼                       ▼
+      ┌────────────────┐      ┌────────────────┐      ┌────────────────┐
+      │ Lead: Alice    │      │ Lead: Bob      │      │ Lead: Carol    │
+      │ (can spawn)    │      │ (can spawn)    │      │ (can spawn)    │
+      └───────┬────────┘      └───────┬────────┘      └───────┬────────┘
+              │                       │                       │
+        ┌─────┴─────┐           ┌─────┴─────┐                 │
+        ▼           ▼           ▼           ▼                 ▼
+    ┌───────┐   ┌───────┐   ┌───────┐   ┌───────┐       ┌───────┐
+    │ Dev1  │   │ QA1   │   │ Dev1  │   │ Rev1  │       │ SRE1  │
+    └───────┘   └───────┘   └───────┘   └───────┘       └───────┘
+```
+
+### Key Design Decisions
+
+1. **Keep Daemons Project-Local**: Each project maintains its own daemon and socket. The Architect connects to multiple daemons simultaneously. This preserves security isolation.
+
+2. **Coordination at Client Layer**: The `MultiProjectClient` handles cross-project routing, not the daemons. Daemons remain simple and unchanged.
+
+3. **Leads Own Staffing**: Leads decide how many workers and what types to spawn based on work assigned by the Architect.
+
+---
+
+## CLI Commands
+
+### Design Principle
+
+> **Tight surface area. Simple interfaces hiding complexity.**
+
+### Start Bridge (Architect)
+
+```bash
+# Bridge multiple projects - just list the paths
+agent-relay bridge ~/auth ~/frontend ~/api
+```
+
+That's it. The system handles:
+- Socket discovery for each project
+- Multi-socket connections
+- Lead auto-detection (first registered agent per project)
+- Cross-project message routing
+
+### Start Lead
+
+```bash
+# Be a lead - just your name
+agent-relay lead Alice
+```
+
+That's it. The system handles:
+- Project detection from current directory
+- Spawn capability (automatic for leads)
+- Daemon registration
+- Worker management
+
+### Workers (spawned by Leads)
+
+Workers are created via relay messages - not CLI commands:
+
+```bash
+->relay:spawn Dev1 claude "Build the login page"
+->relay:release Dev1
+```
+
+### What's Hidden
+
+| User types | System handles |
+|------------|----------------|
+| `bridge ~/auth ~/frontend` | Socket discovery, multi-connection, lead detection |
+| `lead Alice` | Spawn capability, project detection, daemon registration |
+| `->relay:spawn Dev1 claude "task"` | Tmux window, agent launch, task injection |
+
+---
+
+## Message Patterns
+
+### Cross-Project Addressing
+
+```bash
+# Architect → specific project lead
+@relay:auth-service:lead Implement OAuth flow by EOD
+
+# Architect → all leads
+@relay:*:lead Standup time - report status and blockers
+
+# Architect → specific agent in a project
+@relay:frontend:Dev1 Focus on the login form first
+
+# Architect → broadcast to entire project
+@relay:api-service:* Code freeze starts in 1 hour
+```
+
+### Intra-Project (existing patterns still work)
+
+```bash
+# Lead → worker (same project)
+@relay:Dev1 Start on the user endpoint
+
+# Worker → Lead
+@relay:lead Task complete, ready for next assignment
+
+# Worker → Worker
+@relay:QA1 My PR is ready for testing
+```
+
+### Spawn Messages
+
+```bash
+# Lead spawns a worker
+->relay:spawn Dev1 claude "Implement login endpoint"
+
+# Lead spawns with specific model
+->relay:spawn SeniorDev claude:opus "Design the auth architecture"
+->relay:spawn QuickFix claude:haiku "Fix typos in error messages"
+
+# Lead releases a worker
+->relay:release Dev1
+
+# Lead releases all workers
+->relay:release *
+```
+
+---
+
+## Spawn Protocol
+
+### Spawn Message Format
+
+```
+->relay:spawn <name> <cli>[:<model>] "<initial_task>"
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Worker agent name (unique within project) |
+| `cli` | Yes | Agent CLI: `claude`, `codex`, `gemini` |
+| `model` | No | Model variant: `opus`, `sonnet`, `haiku` |
+| `initial_task` | Yes | Task injected into worker on startup |
+
+### Spawn Sequence
+
+```
+┌─────────┐         ┌─────────┐         ┌─────────┐
+│  Lead   │         │ Daemon  │         │ Spawner │
+└────┬────┘         └────┬────┘         └────┬────┘
+     │                   │                   │
+     │ ->relay:spawn Dev1│                   │
+     │ claude "task"     │                   │
+     │──────────────────>│                   │
+     │                   │                   │
+     │                   │ SPAWN request     │
+     │                   │──────────────────>│
+     │                   │                   │
+     │                   │    Create tmux    │
+     │                   │    window "Dev1"  │
+     │                   │                   │
+     │                   │    Launch:        │
+     │                   │    agent-relay    │
+     │                   │    -n Dev1 claude │
+     │                   │                   │
+     │                   │    Inject task    │
+     │                   │                   │
+     │                   │ SPAWN_ACK         │
+     │                   │<──────────────────│
+     │                   │                   │
+     │  SPAWN_COMPLETE   │                   │
+     │   Dev1 ready      │                   │
+     │<──────────────────│                   │
+     │                   │                   │
+```
+
+### Spawn Implementation
+
+```typescript
+// src/daemon/spawner.ts
+
+interface SpawnRequest {
+  name: string;
+  cli: string;
+  model?: string;
+  task: string;
+  requestedBy: string;  // Lead's name
+}
+
+export class AgentSpawner {
+  constructor(private projectRoot: string) {}
+
+  async spawn(request: SpawnRequest): Promise<SpawnResult> {
+    const { name, cli, model, task, requestedBy } = request;
+
+    // 1. Create tmux window
+    const sessionName = `relay-${name}`;
+    await exec(`tmux new-window -t relay -n ${name}`);
+
+    // 2. Build command
+    let cmd = `agent-relay -n ${name}`;
+    if (model) {
+      cmd += ` ${cli}:${model}`;
+    } else {
+      cmd += ` ${cli}`;
+    }
+
+    // 3. Launch agent
+    await exec(`tmux send-keys -t relay:${name} '${cmd}' Enter`);
+
+    // 4. Wait for agent to register
+    await this.waitForAgent(name, 30_000);
+
+    // 5. Inject initial task
+    await exec(`tmux send-keys -t relay:${name} '${escapeTask(task)}' Enter`);
+
+    return {
+      success: true,
+      name,
+      window: `relay:${name}`,
+      spawnedBy: requestedBy,
+    };
+  }
+
+  async release(name: string): Promise<void> {
+    // Send graceful shutdown
+    await exec(`tmux send-keys -t relay:${name} '/exit' Enter`);
+    // Kill window after delay
+    setTimeout(() => {
+      exec(`tmux kill-window -t relay:${name}`).catch(() => {});
+    }, 5000);
+  }
+}
+```
+
+---
+
+## Daily Workflow: Standup Protocol
+
+### Morning Standup Sequence
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                         MORNING STANDUP                                 │
+├────────────────────────────────────────────────────────────────────────┤
+│                                                                        │
+│  1. ARCHITECT INITIATES                                                │
+│     @relay:*:lead Standup - report status, blockers, and staffing needs│
+│                                                                        │
+│  2. LEADS REPORT                                                       │
+│     Alice (auth):    STATUS: OAuth 60% complete                        │
+│                      BLOCKED: Need API spec from api-service           │
+│                      STAFF: Need 2 devs + 1 QA once unblocked          │
+│                                                                        │
+│     Bob (frontend):  STATUS: Dashboard ready for review                │
+│                      BLOCKED: None                                     │
+│                      STAFF: Need 1 reviewer                            │
+│                                                                        │
+│     Carol (api):     STATUS: Spec complete                             │
+│                      BLOCKED: None                                     │
+│                      STAFF: Ready for 3 parallel endpoint devs         │
+│                                                                        │
+│  3. ARCHITECT COORDINATES CROSS-PROJECT                                │
+│     @relay:api-service:lead Alice needs your API spec - priority       │
+│     @relay:auth-service:lead Unblocked - Carol sending spec now        │
+│                                                                        │
+│  4. ARCHITECT ASSIGNS WORK                                             │
+│     @relay:auth-service:lead APPROVED: Staff 2 devs + 1 QA. Pri: HIGH  │
+│     @relay:frontend:lead APPROVED: Staff 1 reviewer for dashboard      │
+│     @relay:api-service:lead APPROVED: Staff 3 devs for endpoints       │
+│                                                                        │
+│  5. LEADS STAFF THEIR TEAMS                                            │
+│     Alice: ->relay:spawn Dev1 claude "Implement OAuth token flow"      │
+│            ->relay:spawn Dev2 claude "Implement OAuth callback"        │
+│            ->relay:spawn QA1 claude "Write OAuth integration tests"    │
+│                                                                        │
+│     Bob:   ->relay:spawn Reviewer claude "Review dashboard PR #42"     │
+│                                                                        │
+│     Carol: ->relay:spawn Dev1 claude "POST /users endpoint"            │
+│            ->relay:spawn Dev2 claude "GET /users/:id endpoint"         │
+│            ->relay:spawn Dev3 claude "DELETE /users/:id endpoint"      │
+│                                                                        │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+### Staffing Strategy by Work Type
+
+| Work Type | Recommended Agent | Rationale |
+|-----------|-------------------|-----------|
+| Architecture/Design | `claude:opus` | Complex reasoning needed |
+| Feature Implementation | `claude:sonnet` | Balance speed/quality |
+| Code Review | `claude:sonnet` | Good judgment required |
+| Testing/QA | `claude:sonnet` | Thoroughness matters |
+| Bug Fixes | `claude:haiku` | Fast, focused |
+| Documentation | `claude:haiku` | Straightforward |
+| Refactoring | `claude:sonnet` | Context-aware changes |
+
+### End of Day Protocol
+
+```bash
+# Architect requests EOD status
+@relay:*:lead EOD status report
+
+# Leads report and release workers
+@relay:architect STATUS: OAuth complete, PR #123 ready
+                 RELEASING: Dev1, Dev2, QA1
+->relay:release Dev1
+->relay:release Dev2
+->relay:release QA1
+
+# Architect summarizes for dashboard/records
+@relay:*:lead Good work today. Tomorrow: auth integration testing
+```
+
+---
+
+## Multi-Project Dashboard
+
+### Dashboard URL
+
+```
+http://localhost:3888/bridge?projects=auth-service,frontend,api-service
+```
+
+### Dashboard Layout
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    AGENT RELAY - BRIDGE DASHBOARD                       │
+├─────────────────────────────────────────────────────────────────────────┤
+│  Orchestrator: Architect (Principal)                      [Refresh]     │
+├───────────────┬──────────────┬──────────────┬──────────────────────────┤
+│ PROJECT       │ LEAD         │ TEAM         │ STATUS                   │
+├───────────────┼──────────────┼──────────────┼──────────────────────────┤
+│ auth-service  │ Alice ●      │ 3 workers    │ ✓ OAuth implementation   │
+│               │              │ Dev1 ●       │                          │
+│               │              │ Dev2 ●       │                          │
+│               │              │ QA1 ○        │                          │
+├───────────────┼──────────────┼──────────────┼──────────────────────────┤
+│ frontend      │ Bob ●        │ 1 worker     │ ⚠ Blocked on API spec    │
+│               │              │ Reviewer ●   │                          │
+├───────────────┼──────────────┼──────────────┼──────────────────────────┤
+│ api-service   │ Carol ●      │ 3 workers    │ ✓ Parallel endpoints     │
+│               │              │ Dev1 ●       │                          │
+│               │              │ Dev2 ●       │                          │
+│               │              │ Dev3 ●       │                          │
+└───────────────┴──────────────┴──────────────┴──────────────────────────┘
+
+│  Cross-Project Message Flow                              [Filter: All]  │
+├─────────────────────────────────────────────────────────────────────────┤
+│ 09:00 Architect → *:lead: Standup time                                  │
+│ 09:01 auth:Alice → Architect: STATUS: OAuth 60%...                      │
+│ 09:01 frontend:Bob → Architect: STATUS: Dashboard ready...              │
+│ 09:02 api:Carol → Architect: STATUS: Spec complete...                   │
+│ 09:05 Architect → api:lead: Send spec to Alice                          │
+│ 09:06 api:Carol → auth:Alice: Here's the spec...                        │
+│ 09:10 auth:Alice: ->relay:spawn Dev1 claude "OAuth token..."            │
+└─────────────────────────────────────────────────────────────────────────┘
+
+│  [Click project to drill down]  [Click agent to attach]                 │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Drill-Down View (Single Project)
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  auth-service                                    [← Back to Overview]   │
+├─────────────────────────────────────────────────────────────────────────┤
+│  Lead: Alice                                                            │
+│  Status: Active - OAuth implementation                                  │
+│  Workers: 3/3 active                                                    │
+├─────────────────────────────────────────────────────────────────────────┤
+│  AGENT       │ STATUS   │ TASK                        │ MESSAGES        │
+├──────────────┼──────────┼─────────────────────────────┼─────────────────┤
+│ Alice (Lead) │ ● active │ Coordinating OAuth impl     │ 12↑ 8↓          │
+│ Dev1         │ ● active │ OAuth token flow            │ 5↑ 14↓          │
+│ Dev2         │ ● typing │ OAuth callback handler      │ 3↑ 6↓           │
+│ QA1          │ ○ idle   │ Waiting for impl complete   │ 1↑ 2↓           │
+├─────────────────────────────────────────────────────────────────────────┤
+│  Project Messages                                                       │
+├─────────────────────────────────────────────────────────────────────────┤
+│ 09:15 Alice → Dev1: Start on token flow                                 │
+│ 09:16 Alice → Dev2: Handle the callback endpoint                        │
+│ 09:30 Dev1 → Alice: Token generation done, testing...                   │
+│ 09:45 Dev1 → QA1: Ready for your test suite                             │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Implementation Plan
+
+### Phase 1: Multi-Socket Client
+
+**File: `src/wrapper/multi-project-client.ts`**
+
+```typescript
+export class MultiProjectClient {
+  private sockets: Map<string, net.Socket> = new Map();
+  private projectLeads: Map<string, string> = new Map();
+
+  constructor(private projects: ProjectConfig[]) {}
+
+  async connect(): Promise<void> {
+    for (const project of this.projects) {
+      const socket = await this.connectToProject(project);
+      this.sockets.set(project.id, socket);
+      if (project.lead) {
+        this.projectLeads.set(project.id, project.lead);
+      }
+    }
+  }
+
+  async send(target: string, message: string): Promise<void> {
+    // Parse target: "project:agent" or "project:*" or "*:lead"
+    const { projectId, agentName } = this.parseTarget(target);
+
+    if (projectId === '*') {
+      // Broadcast to all projects
+      for (const [pid, socket] of this.sockets) {
+        await this.sendToSocket(socket, agentName, message);
+      }
+    } else {
+      const socket = this.sockets.get(projectId);
+      if (socket) {
+        await this.sendToSocket(socket, agentName, message);
+      }
+    }
+  }
+
+  private parseTarget(target: string): { projectId: string; agentName: string } {
+    const [projectId, agentName] = target.split(':');
+    return {
+      projectId: projectId || '*',
+      agentName: agentName === 'lead'
+        ? this.projectLeads.get(projectId) || 'lead'
+        : agentName,
+    };
+  }
+}
+```
+
+### Phase 2: Extended Parser
+
+**File: `src/wrapper/parser.ts`** (modifications)
+
+```typescript
+// Extended pattern for cross-project messaging
+const CROSS_PROJECT_PATTERN = /^@relay:([a-zA-Z0-9_-]+):([a-zA-Z0-9_*]+)\s+(.+)$/;
+const SPAWN_PATTERN = /^->relay:spawn\s+(\S+)\s+(\S+)\s+"([^"]+)"$/;
+const RELEASE_PATTERN = /^->relay:release\s+(\S+)$/;
+
+export function parseRelayCommand(line: string): RelayCommand | null {
+  // Check for spawn command
+  const spawnMatch = line.match(SPAWN_PATTERN);
+  if (spawnMatch) {
+    return {
+      type: 'spawn',
+      name: spawnMatch[1],
+      cli: spawnMatch[2],
+      task: spawnMatch[3],
+    };
+  }
+
+  // Check for release command
+  const releaseMatch = line.match(RELEASE_PATTERN);
+  if (releaseMatch) {
+    return {
+      type: 'release',
+      name: releaseMatch[1],
+    };
+  }
+
+  // Check for cross-project message
+  const crossMatch = line.match(CROSS_PROJECT_PATTERN);
+  if (crossMatch) {
+    return {
+      type: 'message',
+      project: crossMatch[1],
+      target: crossMatch[2],
+      body: crossMatch[3],
+    };
+  }
+
+  // Fall back to existing single-project pattern
+  // ...existing code...
+}
+```
+
+### Phase 3: Bridge CLI Command
+
+**File: `src/cli/bridge.ts`**
+
+```typescript
+import { Command } from 'commander';
+import { MultiProjectClient } from '../wrapper/multi-project-client.js';
+
+export function bridgeCommand(program: Command): void {
+  program
+    .command('bridge')
+    .description('Bridge multiple projects as orchestrator')
+    .argument('<projects...>', 'Project paths to bridge')
+    .action(async (projectPaths: string[]) => {
+      // Resolve and validate paths
+      const projects = await resolveProjects(projectPaths);
+
+      // Connect to all project sockets
+      const client = new MultiProjectClient(projects);
+      await client.connect();
+
+      // Auto-detect leads (first registered agent per project)
+      await client.discoverLeads();
+
+      // Start wrapper with multi-project client
+      const wrapper = new TmuxWrapper({
+        agentName: 'Architect',
+        client,
+        isOrchestrator: true,
+      });
+
+      await wrapper.start();
+    });
+}
+```
+
+**File: `src/cli/lead.ts`**
+
+```typescript
+export function leadCommand(program: Command): void {
+  program
+    .command('lead')
+    .description('Start as project lead with spawn capability')
+    .argument('<name>', 'Your name')
+    .action(async (name: string) => {
+      // Detect project from cwd
+      const project = await detectProject(process.cwd());
+
+      // Start as lead with spawn capability
+      const wrapper = new TmuxWrapper({
+        agentName: name,
+        projectRoot: project.root,
+        isLead: true,
+        canSpawn: true,
+      });
+
+      await wrapper.start();
+    });
+}
+```
+
+### Phase 4: Spawner Service
+
+**File: `src/daemon/spawner.ts`**
+
+```typescript
+export class AgentSpawner {
+  private activeWorkers: Map<string, WorkerInfo> = new Map();
+
+  constructor(
+    private projectRoot: string,
+    private tmuxSession: string,
+  ) {}
+
+  async spawn(request: SpawnRequest): Promise<SpawnResult> {
+    const { name, cli, model, task, requestedBy } = request;
+
+    // Validate
+    if (this.activeWorkers.has(name)) {
+      throw new Error(`Worker ${name} already exists`);
+    }
+
+    // Create tmux window
+    const windowName = `${name}`;
+    await execAsync(`tmux new-window -t ${this.tmuxSession} -n ${windowName}`);
+
+    // Build and launch command
+    const cliCmd = model ? `${cli}:${model}` : cli;
+    const cmd = `agent-relay -n ${name} ${cliCmd}`;
+    await execAsync(`tmux send-keys -t ${this.tmuxSession}:${windowName} '${cmd}' Enter`);
+
+    // Wait for registration
+    const registered = await this.waitForAgent(name, 30_000);
+    if (!registered) {
+      await this.cleanup(windowName);
+      throw new Error(`Worker ${name} failed to register`);
+    }
+
+    // Inject initial task
+    await sleep(2000); // Wait for agent to be ready
+    await execAsync(
+      `tmux send-keys -t ${this.tmuxSession}:${windowName} ${escapeForTmux(task)} Enter`
+    );
+
+    // Track worker
+    this.activeWorkers.set(name, {
+      name,
+      cli: cliCmd,
+      task,
+      spawnedBy: requestedBy,
+      spawnedAt: Date.now(),
+      window: `${this.tmuxSession}:${windowName}`,
+    });
+
+    return { success: true, name, window: windowName };
+  }
+
+  async release(name: string): Promise<void> {
+    const worker = this.activeWorkers.get(name);
+    if (!worker) return;
+
+    // Send exit command
+    try {
+      await execAsync(`tmux send-keys -t ${worker.window} '/exit' Enter`);
+      await sleep(3000);
+    } catch {
+      // Window may already be gone
+    }
+
+    // Kill window
+    try {
+      await execAsync(`tmux kill-window -t ${worker.window}`);
+    } catch {
+      // Ignore
+    }
+
+    this.activeWorkers.delete(name);
+  }
+
+  async releaseAll(): Promise<void> {
+    for (const name of this.activeWorkers.keys()) {
+      await this.release(name);
+    }
+  }
+
+  getActiveWorkers(): WorkerInfo[] {
+    return Array.from(this.activeWorkers.values());
+  }
+}
+```
+
+### Phase 5: Dashboard Enhancement
+
+**File: `src/dashboard/bridge-view.ts`**
+
+```typescript
+export function createBridgeRouter(projects: ProjectConnection[]): Router {
+  const router = Router();
+
+  router.get('/bridge', async (req, res) => {
+    const projectData = await Promise.all(
+      projects.map(async (project) => ({
+        id: project.id,
+        name: project.name,
+        lead: await project.getLead(),
+        agents: await project.getAgents(),
+        status: await project.getStatus(),
+        recentMessages: await project.getRecentMessages(10),
+      }))
+    );
+
+    res.render('bridge', {
+      projects: projectData,
+      orchestrator: req.query.as || 'Architect',
+    });
+  });
+
+  router.get('/bridge/:projectId', async (req, res) => {
+    const project = projects.find(p => p.id === req.params.projectId);
+    if (!project) {
+      return res.status(404).send('Project not found');
+    }
+
+    const data = {
+      ...project,
+      agents: await project.getAgents(),
+      messages: await project.getMessages(50),
+      workers: await project.getWorkers(),
+    };
+
+    res.render('bridge-project', data);
+  });
+
+  return router;
+}
+```
+
+---
+
+## Protocol Extensions
+
+### New Message Types
+
+```typescript
+// src/protocol/types.ts additions
+
+export interface SpawnPayload {
+  name: string;
+  cli: string;
+  model?: string;
+  task: string;
+}
+
+export interface ReleasePayload {
+  name: string;
+}
+
+export interface SpawnResultPayload {
+  success: boolean;
+  name: string;
+  window?: string;
+  error?: string;
+}
+
+// Extended envelope for cross-project
+export interface CrossProjectEnvelope<T> extends Envelope<T> {
+  sourceProject?: string;
+  targetProject?: string;
+}
+```
+
+### Wire Format Examples
+
+```json
+// Spawn request
+{
+  "v": 1,
+  "type": "SPAWN",
+  "id": "spawn-123",
+  "payload": {
+    "name": "Dev1",
+    "cli": "claude",
+    "model": "sonnet",
+    "task": "Implement the login endpoint"
+  }
+}
+
+// Cross-project message
+{
+  "v": 1,
+  "type": "SEND",
+  "id": "msg-456",
+  "to": "Alice",
+  "sourceProject": "api-service",
+  "targetProject": "auth-service",
+  "payload": {
+    "kind": "message",
+    "body": "Here's the API spec you requested"
+  }
+}
+```
+
+---
+
+## Security Considerations
+
+1. **Socket Permissions**: Each project daemon maintains 0o600 permissions. The Architect must have filesystem access to all project socket paths.
+
+2. **Spawn Validation**: Only agents with `--can-spawn` flag can spawn workers. Daemon validates the request source.
+
+3. **Cross-Project Isolation**: Messages are routed through the Architect's client, not directly between daemons. This provides an audit point.
+
+4. **Worker Limits**: Consider adding `--max-workers` flag to prevent runaway spawning.
+
+---
+
+## Configuration
+
+### Project Config File (optional)
+
+```json
+// ~/auth-service/.agent-relay/config.json
+{
+  "projectName": "auth-service",
+  "defaultLead": "Alice",
+  "maxWorkers": 5,
+  "allowedClis": ["claude", "codex"],
+  "spawnDefaults": {
+    "model": "sonnet",
+    "timeout": 3600
+  }
+}
+```
+
+### Bridge Config File (optional)
+
+```json
+// ~/.config/agent-relay/bridge.json
+{
+  "defaultRole": "architect",
+  "projects": {
+    "auth-service": {
+      "path": "~/auth-service",
+      "lead": "Alice"
+    },
+    "frontend": {
+      "path": "~/frontend",
+      "lead": "Bob"
+    }
+  },
+  "standup": {
+    "autoStart": true,
+    "time": "09:00"
+  }
+}
+```
+
+---
+
+## Future Enhancements
+
+1. **Scheduled Standups**: Auto-trigger standup at configured time
+2. **Worker Health Checks**: Monitor spawned workers for crashes
+3. **Load Balancing**: Auto-distribute work across projects
+4. **Metrics/Analytics**: Track productivity across projects
+5. **Notification Integration**: Slack/Discord alerts for blockers
+6. **Replay Mode**: Re-run standups from message history
+
+---
+
+## Summary
+
+The Bridge & Staffing feature enables:
+
+- **Architect/Principal** as cross-project orchestrator via `agent-relay bridge`
+- **Leads** who can dynamically spawn worker agents via `->relay:spawn`
+- **Standup protocol** for daily work coordination
+- **Multi-project dashboard** for visibility across all projects
+- **SE vernacular** with familiar role hierarchy
+
+This maintains the simplicity of `@relay:` patterns while enabling sophisticated multi-project orchestration.
diff --git a/docs/DESIGN_V2.md b/docs/DESIGN_V2.md
index b63d515d5..abb71cb86 100644
--- a/docs/DESIGN_V2.md
+++ b/docs/DESIGN_V2.md
@@ -4,7 +4,7 @@
 
 This document outlines improvements to agent-relay while preserving its core philosophy: **simple, transparent agent-to-agent communication via terminal output patterns**.
 
-The `@relay:` pattern is the killer feature. Agents communicate naturally by just printing text. No APIs, no SDKs, no special integrations. This must remain the foundation.
+The `->relay:` pattern is the killer feature. Agents communicate naturally by just printing text. No APIs, no SDKs, no special integrations. This must remain the foundation.
 
 ---
 
@@ -38,7 +38,7 @@ The `@relay:` pattern is the killer feature. Agents communicate naturally by jus
 
 1. **Keep it simple** - Every feature must justify its complexity
 2. **Terminal-native** - Users stay in tmux, not a browser
-3. **Pattern-based** - `@relay:` is the API
+3. **Pattern-based** - `->relay:` is the API
 4. **Zero config** - Works out of the box
 5. **Debuggable** - Easy to understand what's happening
 
@@ -362,7 +362,7 @@ src/
 │   └── router.ts             # Message routing + queue
 ├── wrapper/
 │   ├── tmux-wrapper.ts       # Agent wrapper
-│   ├── parser.ts             # @relay: pattern parser
+│   ├── parser.ts             # ->relay: pattern parser
 │   └── client.ts             # Relay client
 ├── protocol/
 │   └── types.ts              # Message types (reduced)
@@ -410,11 +410,11 @@ Group agents for targeted messaging:
 }
 
 # Send to group
-@relay:@backend We need to refactor the user service
+->relay:@backend We need to refactor the user service
 # → Message delivered to ApiDev, DbAdmin, AuthService
 
 # Broadcast to all
-@relay:* Starting deployment in 5 minutes
+->relay:* Starting deployment in 5 minutes
 ```
 
 **Implementation:**
@@ -506,9 +506,9 @@ One agent orchestrates the others:
 
 ```
 Coordinator
-    ├── @relay:ApiDev Implement /api/users endpoint
-    ├── @relay:DbAdmin Create users table
-    └── @relay:UiDev Build user profile page
+    ├── ->relay:ApiDev Implement /api/users endpoint
+    ├── ->relay:DbAdmin Create users table
+    └── ->relay:UiDev Build user profile page
 
 ApiDev → Coordinator: Done, endpoint at /api/users
 DbAdmin → Coordinator: Table created with schema...
@@ -524,11 +524,11 @@ Agents pass work sequentially:
 ```
 Developer → Reviewer → QA → Deployer
 
-@relay:Reviewer PR #123 ready for review
+->relay:Reviewer PR #123 ready for review
           ↓
-@relay:QA Review passed, ready for testing
+->relay:QA Review passed, ready for testing
           ↓
-@relay:Deployer Tests passed, deploy when ready
+->relay:Deployer Tests passed, deploy when ready
 ```
 
 #### Pattern 3: Pub/Sub Topics
@@ -537,10 +537,10 @@ Agents subscribe to topics of interest:
 
 ```bash
 # Agent subscribes to topic
-@relay:subscribe security-alerts
+->relay:subscribe security-alerts
 
 # Any agent can publish
-@relay:topic:security-alerts Found SQL injection in auth.ts
+->relay:topic:security-alerts Found SQL injection in auth.ts
 
 # All subscribers receive the message
 ```
@@ -548,14 +548,14 @@ Agents subscribe to topics of interest:
 **Implementation:**
 ```typescript
 // Subscribe syntax
-@relay:+topic-name      # Subscribe
-@relay:-topic-name      # Unsubscribe
-@relay:#topic-name msg  # Publish to topic
+->relay:+topic-name      # Subscribe
+->relay:-topic-name      # Unsubscribe
+->relay:#topic-name msg  # Publish to topic
 
 // In parser.ts
-const TOPIC_SUBSCRIBE = /^@relay:\+(\S+)$/;
-const TOPIC_UNSUBSCRIBE = /^@relay:-(\S+)$/;
-const TOPIC_PUBLISH = /^@relay:#(\S+)\s+(.+)$/;
+const TOPIC_SUBSCRIBE = /^->relay:\+(\S+)$/;
+const TOPIC_UNSUBSCRIBE = /^->relay:-(\S+)$/;
+const TOPIC_PUBLISH = /^->relay:#(\S+)\s+(.+)$/;
 ```
 
 ### 5.4 Tmux Layout Helper
@@ -639,21 +639,21 @@ With more agents, message prioritization becomes important:
 
 ```bash
 # Urgent message (interrupts immediately)
-@relay:!ApiDev Production is down, check auth service
+->relay:!ApiDev Production is down, check auth service
 
 # Normal message (waits for idle)
-@relay:ApiDev When you have time, review this PR
+->relay:ApiDev When you have time, review this PR
 
 # Low priority (batched, delivered during quiet periods)
-@relay:?ApiDev FYI: Updated the style guide
+->relay:?ApiDev FYI: Updated the style guide
 ```
 
 **Injection behavior:**
 | Priority | Syntax | Behavior |
 |----------|--------|----------|
-| Urgent | `@relay:!Name` | Inject immediately, even if busy |
-| Normal | `@relay:Name` | Wait for idle (current behavior) |
-| Low | `@relay:?Name` | Batch and deliver during long idle |
+| Urgent | `->relay:!Name` | Inject immediately, even if busy |
+| Normal | `->relay:Name` | Wait for idle (current behavior) |
+| Low | `->relay:?Name` | Batch and deliver during long idle |
 
 ### 5.7 Status Broadcasts
 
@@ -661,9 +661,9 @@ Agents automatically announce state changes:
 
 ```typescript
 // Automatic status messages
-@relay:* STATUS: ApiDev is now idle
-@relay:* STATUS: Reviewer completed task (closed PR #123)
-@relay:* STATUS: QA disconnected
+->relay:* STATUS: ApiDev is now idle
+->relay:* STATUS: Reviewer completed task (closed PR #123)
+->relay:* STATUS: QA disconnected
 
 // Agents can filter these
 // In wrapper config:
@@ -755,7 +755,7 @@ The goal: **Single pane of glass, but in the terminal**
 │  │              NATIVE TMUX SESSION                         │    │
 │  │                                                          │    │
 │  │  claude> Working on the API endpoint...                  │    │
-│  │  @relay:DbAdmin Need the users table schema              │    │
+│  │  ->relay:DbAdmin Need the users table schema              │    │
 │  │                                                          │    │
 │  └─────────────────────────────────────────────────────────┘    │
 │                           │                                      │
@@ -1055,7 +1055,7 @@ Key changes:
 
 | Feature | Effort | Priority |
 |---------|--------|----------|
-| Agent groups (`@relay:@groupname`) | 1 day | P1 |
+| Agent groups (`->relay:@groupname`) | 1 day | P1 |
 | TUI dashboard (`agent-relay watch`) | 2 days | P1 |
 | Tmux layout helper | 0.5 day | P2 |
 | Message priority (`!`, `?`) | 0.5 day | P2 |
diff --git a/docs/INTEGRATION-GUIDE.md b/docs/INTEGRATION-GUIDE.md
new file mode 100644
index 000000000..4bb9937a8
--- /dev/null
+++ b/docs/INTEGRATION-GUIDE.md
@@ -0,0 +1,926 @@
+# Agent Infrastructure Integration Guide
+
+How to integrate agent-relay, claude-mem, and agent-trajectories into a cohesive stack.
+
+---
+
+## The Stack at a Glance
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  YOUR AGENT (Claude Code, Codex, Gemini, etc.)                 │
+├─────────────────────────────────────────────────────────────────┤
+│                         │                                       │
+│            ┌────────────┴────────────┐                         │
+│            ▼                         ▼                         │
+│  ┌─────────────────┐      ┌─────────────────┐                  │
+│  │  CLAUDE-MEM     │      │  AGENT-RELAY    │                  │
+│  │  (Observations) │      │  (Messaging)    │                  │
+│  │                 │      │                 │                  │
+│  │  • Tool calls   │      │  • ->relay:Agent │                  │
+│  │  • Concepts     │      │  • Broadcasting │                  │
+│  │  • Sessions     │      │  • Persistence  │                  │
+│  └────────┬────────┘      └────────┬────────┘                  │
+│           │                        │                           │
+│           └──────────┬─────────────┘                           │
+│                      ▼                                         │
+│           ┌─────────────────────┐                              │
+│           │  AGENT-TRAJECTORIES │                              │
+│           │  (Narratives)       │                              │
+│           │                     │                              │
+│           │  • Task stories     │                              │
+│           │  • Decisions        │                              │
+│           │  • Retrospectives   │                              │
+│           │  • Workspace        │                              │
+│           └─────────────────────┘                              │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 0: Current State (What Exists)
+
+### agent-relay (✅ Ready)
+
+**What it does:** Real-time agent-to-agent messaging via Unix sockets.
+
+**Installation:**
+```bash
+npm install -g agent-relay
+```
+
+**Usage:**
+```bash
+# Start daemon
+agent-relay up
+
+# Wrap agent
+agent-relay -n Alice claude
+```
+
+**What it provides for integration:**
+```typescript
+import { StoredMessage, MessageQuery, StorageAdapter } from 'agent-relay';
+
+// Query messages for a time range
+const messages = await storage.getMessages({
+  sinceTs: startTime,
+  order: 'asc'
+});
+```
+
+### claude-mem (✅ Exists, needs integration)
+
+**What it does:** Captures tool observations with semantic concepts.
+
+**Installation:**
+```bash
+# Clone and setup
+git clone https://github.com/thedotmack/claude-mem
+cd claude-mem
+bun install
+```
+
+**How it works:**
+- Hooks into Claude Code lifecycle (SessionStart, PostToolUse, SessionEnd)
+- Stores observations in SQLite + Chroma (vector search)
+- Provides `mem-search` skill for natural language queries
+
+**What it provides for integration:**
+- Tool call history with semantic tags
+- Session continuity
+- Concept-based search
+
+---
+
+## Phase 1: Install claude-mem
+
+### Step 1.1: Clone and Configure
+
+```bash
+# From your project root
+git clone https://github.com/thedotmack/claude-mem .claude-mem
+
+# Install dependencies
+cd .claude-mem
+bun install
+
+# Start the worker service
+bun run start
+```
+
+### Step 1.2: Configure Claude Code Hooks
+
+Add to your `~/.claude/settings.json` (or project `.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "command": "node .claude-mem/hooks/session-start.js",
+        "timeout": 5000
+      }
+    ],
+    "PostToolUse": [
+      {
+        "command": "node .claude-mem/hooks/post-tool-use.js",
+        "timeout": 3000
+      }
+    ],
+    "SessionEnd": [
+      {
+        "command": "node .claude-mem/hooks/session-end.js",
+        "timeout": 5000
+      }
+    ]
+  }
+}
+```
+
+### Step 1.3: Verify It's Working
+
+```bash
+# Start a Claude Code session
+claude
+
+# Do some work...
+
+# Check the web viewer
+open http://localhost:37777
+```
+
+You should see observations being captured.
+
+---
+
+## Phase 2: Create agent-trajectories
+
+### Step 2.1: Initialize the Project
+
+```bash
+# Create new repo
+mkdir agent-trajectories
+cd agent-trajectories
+npm init -y
+
+# Install dependencies
+npm install better-sqlite3 commander uuid
+npm install -D typescript @types/node @types/better-sqlite3 vitest
+```
+
+### Step 2.2: Project Structure
+
+```
+agent-trajectories/
+├── src/
+│   ├── core/
+│   │   ├── types.ts           # Trajectory, Chapter, Event types
+│   │   ├── schema.ts          # JSON schema for .trajectory format
+│   │   └── trajectory.ts      # Trajectory class
+│   │
+│   ├── storage/
+│   │   ├── file-storage.ts    # .trajectories/ directory
+│   │   └── sqlite-storage.ts  # SQLite for indexing
+│   │
+│   ├── adapters/
+│   │   ├── adapter.ts         # TaskSourceAdapter interface
+│   │   ├── beads.ts           # Beads integration
+│   │   ├── github.ts          # GitHub Issues integration
+│   │   ├── linear.ts          # Linear integration
+│   │   └── plain.ts           # Standalone trajectories
+│   │
+│   ├── integrations/
+│   │   ├── relay.ts           # Import from agent-relay
+│   │   └── claude-mem.ts      # Import from claude-mem
+│   │
+│   ├── workspace/
+│   │   ├── decisions.ts       # Decision log
+│   │   ├── patterns.ts        # Pattern library
+│   │   └── extract.ts         # Auto-extraction
+│   │
+│   ├── export/
+│   │   ├── markdown.ts        # Notion-style export
+│   │   └── timeline.ts        # Linear-style export
+│   │
+│   ├── cli/
+│   │   └── index.ts           # CLI commands
+│   │
+│   └── index.ts               # Main exports
+│
+├── package.json
+└── tsconfig.json
+```
+
+### Step 2.3: Core Types
+
+```typescript
+// src/core/types.ts
+
+export interface Trajectory {
+  id: string;
+  version: 1;
+
+  task: TaskReference;
+
+  startedAt: string;
+  completedAt?: string;
+  status: 'active' | 'completed' | 'abandoned';
+
+  agents: AgentParticipation[];
+  chapters: Chapter[];
+  retrospective?: Retrospective;
+
+  commits: string[];
+  filesChanged: string[];
+
+  projectId: string;
+  tags: string[];
+}
+
+export interface TaskReference {
+  title: string;
+  description?: string;
+  source?: {
+    system: string;  // 'beads' | 'linear' | 'github' | 'plain'
+    id: string;
+    url?: string;
+  };
+}
+
+export interface Chapter {
+  id: string;
+  title: string;
+  agentName: string;
+  startedAt: string;
+  endedAt?: string;
+  events: TrajectoryEvent[];
+}
+
+export interface TrajectoryEvent {
+  ts: number;
+  type: EventType;
+  content: string;
+  raw?: unknown;
+  significance?: 'low' | 'medium' | 'high' | 'critical';
+  tags?: string[];
+  source?: 'relay' | 'claude-mem' | 'manual';
+}
+
+export type EventType =
+  | 'prompt'
+  | 'thinking'
+  | 'tool_call'
+  | 'tool_result'
+  | 'message_sent'
+  | 'message_received'
+  | 'decision'
+  | 'observation'  // From claude-mem
+  | 'error';
+
+export interface Retrospective {
+  summary: string;
+  approach: string;
+  decisions: Decision[];
+  challenges: string[];
+  learnings: string[];
+  suggestions: string[];
+  confidence: number;
+}
+
+export interface Decision {
+  question: string;
+  chosen: string;
+  alternatives: string[];
+  reasoning: string;
+}
+```
+
+### Step 2.4: CLI Commands
+
+```typescript
+// src/cli/index.ts
+
+import { Command } from 'commander';
+
+const program = new Command();
+
+program
+  .name('trajectory')
+  .description('Agent trajectory management')
+  .version('1.0.0');
+
+// Create new trajectory
+program
+  .command('new <title>')
+  .description('Start a new trajectory')
+  .option('--beads <id>', 'Link to Beads task')
+  .option('--linear <id>', 'Link to Linear issue')
+  .option('--github <id>', 'Link to GitHub issue')
+  .action(async (title, options) => {
+    // Implementation
+  });
+
+// Show current trajectory status
+program
+  .command('status')
+  .description('Show active trajectory')
+  .action(async () => {
+    // Implementation
+  });
+
+// Add a chapter
+program
+  .command('chapter <title>')
+  .description('Start a new chapter')
+  .action(async (title) => {
+    // Implementation
+  });
+
+// Record a decision
+program
+  .command('decision <title>')
+  .description('Record a decision')
+  .option('--chosen <choice>', 'What was chosen')
+  .option('--alternatives <alts...>', 'Alternatives considered')
+  .option('--reasoning <reason>', 'Why this choice')
+  .action(async (title, options) => {
+    // Implementation
+  });
+
+// Complete trajectory
+program
+  .command('complete')
+  .description('Complete the active trajectory')
+  .option('--retrospective', 'Prompt for retrospective')
+  .action(async (options) => {
+    // Implementation
+  });
+
+// Import from sources
+program
+  .command('import')
+  .description('Import events from external sources')
+  .option('--relay', 'Import from agent-relay')
+  .option('--claude-mem', 'Import from claude-mem')
+  .option('--since <timestamp>', 'Import since timestamp')
+  .action(async (options) => {
+    // Implementation
+  });
+
+// Export trajectory
+program
+  .command('export <id>')
+  .description('Export trajectory')
+  .option('--format <format>', 'Export format (markdown, json, timeline)')
+  .action(async (id, options) => {
+    // Implementation
+  });
+
+// Search trajectories
+program
+  .command('search <query>')
+  .description('Search trajectories')
+  .action(async (query) => {
+    // Implementation
+  });
+
+program.parse();
+```
+
+---
+
+## Phase 3: agent-relay Integration
+
+### Step 3.1: Import Relay Messages
+
+```typescript
+// src/integrations/relay.ts
+
+import { StoredMessage, MessageQuery } from 'agent-relay';
+import { TrajectoryEvent } from '../core/types.js';
+
+interface RelayImportOptions {
+  sinceTs: number;
+  untilTs?: number;
+  agentName?: string;
+  topic?: string;
+}
+
+export async function importFromRelay(
+  storage: StorageAdapter,
+  options: RelayImportOptions
+): Promise<TrajectoryEvent[]> {
+  const query: MessageQuery = {
+    sinceTs: options.sinceTs,
+    order: 'asc',
+    limit: 1000
+  };
+
+  if (options.agentName) {
+    query.from = options.agentName;
+  }
+  if (options.topic) {
+    query.topic = options.topic;
+  }
+
+  const messages = await storage.getMessages(query);
+
+  return messages
+    .filter(m => !options.untilTs || m.ts <= options.untilTs)
+    .map(messageToEvent);
+}
+
+function messageToEvent(msg: StoredMessage): TrajectoryEvent {
+  return {
+    ts: msg.ts,
+    type: msg.kind === 'thinking' ? 'thinking' :
+          msg.to === '*' ? 'message_sent' :
+          'message_received',
+    content: msg.body,
+    raw: {
+      from: msg.from,
+      to: msg.to,
+      kind: msg.kind,
+      data: msg.data
+    },
+    significance: 'medium',
+    source: 'relay'
+  };
+}
+```
+
+### Step 3.2: Real-time Relay Subscription
+
+```typescript
+// src/integrations/relay-listener.ts
+
+import { RelayClient } from 'agent-relay';
+import { TrajectoryCapture } from '../capture/trajectory-capture.js';
+
+export class RelayListener {
+  private client: RelayClient;
+  private capture: TrajectoryCapture;
+
+  constructor(capture: TrajectoryCapture) {
+    this.capture = capture;
+  }
+
+  async connect(agentName: string): Promise<void> {
+    this.client = new RelayClient({ agentName });
+
+    this.client.on('message', (envelope) => {
+      this.capture.recordEvent({
+        type: envelope.from === agentName ? 'message_sent' : 'message_received',
+        content: envelope.payload.body,
+        raw: envelope,
+        source: 'relay'
+      });
+    });
+
+    await this.client.connect();
+  }
+
+  async disconnect(): Promise<void> {
+    await this.client.disconnect();
+  }
+}
+```
+
+---
+
+## Phase 4: claude-mem Integration
+
+### Step 4.1: Query claude-mem Observations
+
+```typescript
+// src/integrations/claude-mem.ts
+
+import { TrajectoryEvent } from '../core/types.js';
+
+interface ClaudeMemObservation {
+  id: string;
+  timestamp: string;
+  type: 'decision' | 'bugfix' | 'feature' | 'refactor' | 'discovery' | 'change';
+  content: string;
+  concepts: string[];
+  files?: string[];
+  tokens?: number;
+}
+
+interface ClaudeMemImportOptions {
+  sinceTs: number;
+  untilTs?: number;
+  types?: string[];
+  concepts?: string[];
+}
+
+const CLAUDE_MEM_API = 'http://localhost:37777';
+
+export async function importFromClaudeMem(
+  options: ClaudeMemImportOptions
+): Promise<TrajectoryEvent[]> {
+  const params = new URLSearchParams({
+    since: new Date(options.sinceTs).toISOString(),
+  });
+
+  if (options.untilTs) {
+    params.set('until', new Date(options.untilTs).toISOString());
+  }
+  if (options.types?.length) {
+    params.set('types', options.types.join(','));
+  }
+  if (options.concepts?.length) {
+    params.set('concepts', options.concepts.join(','));
+  }
+
+  const response = await fetch(`${CLAUDE_MEM_API}/api/observations?${params}`);
+  const observations: ClaudeMemObservation[] = await response.json();
+
+  return observations.map(observationToEvent);
+}
+
+function observationToEvent(obs: ClaudeMemObservation): TrajectoryEvent {
+  return {
+    ts: new Date(obs.timestamp).getTime(),
+    type: 'observation',
+    content: obs.content,
+    raw: obs,
+    significance: mapTypeToSignificance(obs.type),
+    tags: obs.concepts,
+    source: 'claude-mem'
+  };
+}
+
+function mapTypeToSignificance(type: string): 'low' | 'medium' | 'high' | 'critical' {
+  switch (type) {
+    case 'decision': return 'high';
+    case 'bugfix': return 'high';
+    case 'feature': return 'medium';
+    case 'discovery': return 'medium';
+    case 'refactor': return 'low';
+    case 'change': return 'low';
+    default: return 'medium';
+  }
+}
+
+// Search claude-mem for relevant observations
+export async function searchClaudeMem(query: string): Promise<ClaudeMemObservation[]> {
+  const response = await fetch(`${CLAUDE_MEM_API}/api/search`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query })
+  });
+
+  return response.json();
+}
+```
+
+### Step 4.2: Enrich Trajectories with Observations
+
+```typescript
+// src/integrations/enrichment.ts
+
+import { Trajectory, Chapter } from '../core/types.js';
+import { importFromClaudeMem } from './claude-mem.js';
+import { importFromRelay } from './relay.js';
+
+export async function enrichTrajectory(
+  trajectory: Trajectory,
+  relayStorage?: StorageAdapter
+): Promise<Trajectory> {
+  const startTs = new Date(trajectory.startedAt).getTime();
+  const endTs = trajectory.completedAt
+    ? new Date(trajectory.completedAt).getTime()
+    : Date.now();
+
+  // Import from claude-mem
+  const claudeMemEvents = await importFromClaudeMem({
+    sinceTs: startTs,
+    untilTs: endTs,
+    types: ['decision', 'discovery', 'bugfix']
+  });
+
+  // Import from agent-relay (if available)
+  let relayEvents = [];
+  if (relayStorage) {
+    relayEvents = await importFromRelay(relayStorage, {
+      sinceTs: startTs,
+      untilTs: endTs
+    });
+  }
+
+  // Merge events into chapters by timestamp
+  const allEvents = [...claudeMemEvents, ...relayEvents]
+    .sort((a, b) => a.ts - b.ts);
+
+  // Distribute events to appropriate chapters
+  for (const event of allEvents) {
+    const chapter = findChapterForTimestamp(trajectory.chapters, event.ts);
+    if (chapter) {
+      chapter.events.push(event);
+      chapter.events.sort((a, b) => a.ts - b.ts);
+    }
+  }
+
+  return trajectory;
+}
+
+function findChapterForTimestamp(chapters: Chapter[], ts: number): Chapter | null {
+  for (const chapter of chapters) {
+    const start = new Date(chapter.startedAt).getTime();
+    const end = chapter.endedAt
+      ? new Date(chapter.endedAt).getTime()
+      : Date.now();
+
+    if (ts >= start && ts <= end) {
+      return chapter;
+    }
+  }
+
+  // Return last chapter if no match
+  return chapters[chapters.length - 1] || null;
+}
+```
+
+---
+
+## Phase 5: Hook Integration
+
+### Step 5.1: Trajectory Hooks for Claude Code
+
+```typescript
+// src/hooks/session-start.ts
+
+import { TrajectoryStore } from '../storage/trajectory-store.js';
+
+async function onSessionStart(): Promise<{ context?: string }> {
+  const store = new TrajectoryStore();
+  const active = await store.getActive();
+
+  if (!active) {
+    return {};
+  }
+
+  const context = `
+## Active Trajectory
+
+**Task:** ${active.task.title}
+**Status:** ${active.status}
+**Chapter:** ${active.chapters[active.chapters.length - 1]?.title || 'Starting'}
+
+### Key Decisions So Far
+${active.chapters
+  .flatMap(c => c.events.filter(e => e.type === 'decision'))
+  .map(d => `- ${d.content}`)
+  .join('\n') || 'None yet'}
+
+### Recent Activity
+${active.chapters[active.chapters.length - 1]?.events
+  .slice(-5)
+  .map(e => `- [${e.type}] ${e.content.slice(0, 100)}`)
+  .join('\n') || 'None'}
+
+---
+To record a decision: [[TRAJECTORY:decision]]{"title": "...", "chosen": "...", "alternatives": [...], "reasoning": "..."}[[/TRAJECTORY]]
+To start a new chapter: [[TRAJECTORY:chapter]]{"title": "..."}[[/TRAJECTORY]]
+`.trim();
+
+  return { context };
+}
+```
+
+### Step 5.2: Combined Hook Configuration
+
+```json
+// .claude/settings.json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "command": "node .claude-mem/hooks/session-start.js",
+        "timeout": 5000
+      },
+      {
+        "command": "npx trajectory hook:session-start",
+        "timeout": 3000
+      }
+    ],
+    "PostToolUse": [
+      {
+        "command": "node .claude-mem/hooks/post-tool-use.js",
+        "timeout": 3000
+      }
+    ],
+    "Stop": [
+      {
+        "command": "npx trajectory hook:stop",
+        "timeout": 5000
+      }
+    ],
+    "SessionEnd": [
+      {
+        "command": "node .claude-mem/hooks/session-end.js",
+        "timeout": 5000
+      },
+      {
+        "command": "npx trajectory hook:session-end",
+        "timeout": 5000
+      }
+    ]
+  }
+}
+```
+
+### Step 5.3: Stop Hook - Prompt for Retrospective
+
+```typescript
+// src/hooks/stop.ts
+
+import { TrajectoryStore } from '../storage/trajectory-store.js';
+
+async function onStop(): Promise<{ decision: 'allow' | 'block'; reason?: string }> {
+  const store = new TrajectoryStore();
+  const active = await store.getActive();
+
+  if (!active) {
+    return { decision: 'allow' };
+  }
+
+  // Check if trajectory has a retrospective
+  if (!active.retrospective) {
+    return {
+      decision: 'block',
+      reason: `
+Active trajectory "${active.task.title}" needs a retrospective before completing.
+
+Please output a retrospective:
+
+[[TRAJECTORY:retrospective]]
+{
+  "summary": "What was accomplished?",
+  "approach": "How did you approach it?",
+  "decisions": [
+    {"question": "Key choice made", "chosen": "What you picked", "alternatives": ["Other options"], "reasoning": "Why"}
+  ],
+  "challenges": ["What was difficult?"],
+  "learnings": ["What would you do differently?"],
+  "suggestions": ["Improvements for codebase/process?"],
+  "confidence": 0.85
+}
+[[/TRAJECTORY]]
+
+Or run: trajectory complete --skip-retrospective
+`.trim()
+    };
+  }
+
+  return { decision: 'allow' };
+}
+```
+
+---
+
+## Phase 6: Putting It All Together
+
+### Complete Setup Checklist
+
+```bash
+# 1. Install agent-relay
+npm install -g agent-relay
+
+# 2. Clone and setup claude-mem
+git clone https://github.com/thedotmack/claude-mem .claude-mem
+cd .claude-mem && bun install && bun run start &
+cd ..
+
+# 3. Install agent-trajectories (once published)
+npm install -g agent-trajectories
+
+# 4. Configure hooks
+cat > .claude/settings.json << 'EOF'
+{
+  "hooks": {
+    "SessionStart": [
+      {"command": "node .claude-mem/hooks/session-start.js", "timeout": 5000},
+      {"command": "npx trajectory hook:session-start", "timeout": 3000}
+    ],
+    "PostToolUse": [
+      {"command": "node .claude-mem/hooks/post-tool-use.js", "timeout": 3000}
+    ],
+    "Stop": [
+      {"command": "npx trajectory hook:stop", "timeout": 5000}
+    ],
+    "SessionEnd": [
+      {"command": "node .claude-mem/hooks/session-end.js", "timeout": 5000},
+      {"command": "npx trajectory hook:session-end", "timeout": 5000}
+    ]
+  }
+}
+EOF
+
+# 5. Start the relay daemon
+agent-relay up
+
+# 6. Start working!
+agent-relay -n Alice claude
+```
+
+### Typical Workflow
+
+```bash
+# Start a task
+trajectory new "Implement user authentication" --linear ENG-456
+
+# Work in Claude Code...
+# - claude-mem captures tool observations automatically
+# - agent-relay captures messages automatically
+# - You can add decisions manually via [[TRAJECTORY:decision]]
+
+# Check status
+trajectory status
+
+# Start a new chapter when switching focus
+trajectory chapter "Testing"
+
+# When done, complete with retrospective
+trajectory complete
+
+# View the result
+trajectory export ENG-456 --format markdown
+```
+
+### Data Flow Diagram
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                        AGENT SESSION                             │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│   Agent works...                                                 │
+│        │                                                         │
+│        ├──────────────────┬───────────────────┐                 │
+│        ▼                  ▼                   ▼                 │
+│   ┌─────────┐      ┌───────────┐      ┌────────────┐           │
+│   │ Tool    │      │ ->relay:   │      │[[TRAJECTORY│           │
+│   │ Calls   │      │ messages  │      │ :decision]]│           │
+│   └────┬────┘      └─────┬─────┘      └──────┬─────┘           │
+│        │                 │                   │                  │
+│        ▼                 ▼                   ▼                  │
+│   ┌─────────┐      ┌───────────┐      ┌────────────┐           │
+│   │claude-  │      │agent-relay│      │agent-      │           │
+│   │mem      │      │SQLite     │      │trajectories│           │
+│   │SQLite + │      │           │      │.trajectory/│           │
+│   │Chroma   │      │           │      │            │           │
+│   └────┬────┘      └─────┬─────┘      └──────┬─────┘           │
+│        │                 │                   │                  │
+│        └────────────┬────┴───────────────────┘                  │
+│                     ▼                                           │
+│           ┌─────────────────┐                                   │
+│           │ trajectory      │                                   │
+│           │ complete        │                                   │
+│           │                 │                                   │
+│           │ Enriches with:  │                                   │
+│           │ - relay msgs    │                                   │
+│           │ - claude-mem    │                                   │
+│           │   observations  │                                   │
+│           └────────┬────────┘                                   │
+│                    ▼                                            │
+│           ┌─────────────────┐                                   │
+│           │ .trajectory.json│                                   │
+│           │ .trajectory.md  │                                   │
+│           │                 │                                   │
+│           │ Complete story  │                                   │
+│           │ of the work     │                                   │
+│           └─────────────────┘                                   │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Summary: What Each Piece Does
+
+| Component | Captures | Storage | Query |
+|-----------|----------|---------|-------|
+| **agent-relay** | Agent messages | SQLite | By time, sender, topic |
+| **claude-mem** | Tool observations | SQLite + Chroma | Semantic search |
+| **agent-trajectories** | Task narratives | Files + SQLite | By task, decision, pattern |
+
+| Component | Hooks | Real-time | Export |
+|-----------|-------|-----------|--------|
+| **agent-relay** | Stop (inbox check) | Yes (sockets) | JSON |
+| **claude-mem** | All lifecycle | No | JSON |
+| **agent-trajectories** | Start, Stop, End | Optional | Markdown, JSON, Timeline |
+
+---
+
+## Next Steps
+
+1. **Phase 1:** Get claude-mem working in your project
+2. **Phase 2:** Create agent-trajectories repo with core types
+3. **Phase 3:** Add relay integration
+4. **Phase 4:** Add claude-mem integration
+5. **Phase 5:** Build CLI and hooks
+6. **Phase 6:** Test end-to-end flow
diff --git a/docs/PROPOSAL-trajectories.md b/docs/PROPOSAL-trajectories.md
new file mode 100644
index 000000000..13d5405d8
--- /dev/null
+++ b/docs/PROPOSAL-trajectories.md
@@ -0,0 +1,1582 @@
+# Train of Thought Trajectories: Design Proposal
+
+## Executive Summary
+
+Store the complete "trajectory" of agent work on tasks - prompts, reasoning, inter-agent messages, tool calls, decisions, and retrospectives - as first-class artifacts that travel with the code and provide long-term value for debugging, code review, onboarding, and institutional memory.
+
+**Key principle: Platform agnostic.** Trajectories are a universal format - like Markdown for documentation. They work with any task system (Beads, Linear, Jira, GitHub Issues, plain text) and export to any reading format (Notion-like pages, Linear-like timelines, raw JSON).
+
+---
+
+## The Bigger Picture: Notion for Agents
+
+Trajectories are one piece of a larger vision: **a knowledge workspace where agents can read, write, and learn** - just like Notion is for humans.
+
+### What Notion Does for Humans
+
+| Capability | How Humans Use It |
+|------------|-------------------|
+| **Knowledge base** | Company wiki, documentation, runbooks |
+| **Linked documents** | Connect related ideas, reference past work |
+| **Templates** | Reusable structures for common tasks |
+| **Databases** | Structured data with multiple views |
+| **Search** | Find anything across all content |
+| **Collaboration** | Comments, mentions, shared editing |
+
+### What Agents Need (Agent Notion)
+
+| Capability | Agent Equivalent |
+|------------|------------------|
+| **Trajectory archive** | Past work with full reasoning history |
+| **Codebase knowledge** | Architecture docs, patterns, conventions |
+| **Decision log** | Why things are the way they are |
+| **Team context** | Who knows what, who's working on what |
+| **Pattern library** | Reusable approaches to common problems |
+| **Communication history** | Past agent-to-agent conversations |
+
+### How Agent Notion Helps
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        AGENT NOTION WORKSPACE                          │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  📚 KNOWLEDGE BASE                    🛤️ TRAJECTORIES                   │
+│  ├── Architecture decisions           ├── Active (3)                   │
+│  ├── Code patterns we use             ├── This week (12)               │
+│  ├── API conventions                  └── Archive (156)                │
+│  └── Testing philosophy                                                │
+│                                                                         │
+│  🧠 DECISION LOG                      👥 TEAM CONTEXT                   │
+│  ├── "Why we use Postgres"            ├── Alice: auth expert           │
+│  ├── "Why no Redux"                   ├── Bob: API design              │
+│  └── "Error handling approach"        └── Carol: testing lead          │
+│                                                                         │
+│  📋 PATTERNS                          💬 CONVERSATIONS                  │
+│  ├── API endpoint template            ├── Today's discussions          │
+│  ├── React component pattern          ├── Decisions made               │
+│  └── Test file structure              └── Open questions               │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Use Cases: How Agent Notion Helps
+
+#### 1. New Agent Onboarding
+
+**Without Agent Notion:**
+```
+New agent spawns → Reads codebase → Makes assumptions →
+Possibly repeats past mistakes → Violates conventions
+```
+
+**With Agent Notion:**
+```
+New agent spawns → Queries workspace:
+  "How do we handle authentication in this codebase?"
+  → Gets: trajectory of auth implementation + decision log + patterns
+  → Understands context in seconds
+```
+
+#### 2. Consistent Decision Making
+
+**Without:** Each agent reinvents approaches, leading to inconsistent code.
+
+**With:** Agent queries pattern library:
+```
+Agent: "I need to add a new API endpoint"
+
+Workspace returns:
+- Template: Standard endpoint structure
+- Pattern: Error handling approach
+- Trajectory: How /api/users was built (for reference)
+- Decision: "We use Zod for validation (see decision-2024-03)"
+```
+
+#### 3. Learning from Past Work
+
+**Query:** "How have we solved caching problems before?"
+
+**Returns:**
+- 3 trajectories involving caching
+- Key decisions: Redis for sessions, in-memory for hot data
+- Gotchas: "Cache invalidation was tricky in trajectory-abc, see retrospective"
+
+#### 4. Cross-Agent Collaboration
+
+When Alice asks Bob a question:
+```
+Alice → Bob: "How should I structure the payment webhook handler?"
+
+Bob can reference:
+- Past trajectory where similar webhook was built
+- Pattern for webhook handlers
+- Known issues from retrospectives
+```
+
+The answer becomes **reusable knowledge**, not ephemeral chat.
+
+### Data Model: Agent Workspace
+
+```typescript
+interface AgentWorkspace {
+  projectId: string;
+
+  // The layers of knowledge
+  trajectories: TrajectoryStore;      // Work history
+  decisions: DecisionLog;              // Why things are
+  patterns: PatternLibrary;            // How to do things
+  knowledge: KnowledgeBase;            // What things are
+  conversations: ConversationArchive;  // Who said what
+  team: TeamContext;                   // Who knows what
+
+  // Cross-cutting
+  search: UnifiedSearch;               // Find across all layers
+  links: LinkGraph;                    // Connections between items
+}
+
+interface DecisionLog {
+  decisions: Decision[];
+
+  // Query interface
+  getDecision(topic: string): Decision | null;
+  findRelated(context: string): Decision[];
+}
+
+interface Decision {
+  id: string;
+  title: string;                    // "Use PostgreSQL for primary database"
+  context: string;                  // Why this came up
+  decision: string;                 // What was decided
+  alternatives: Alternative[];      // What was rejected
+  consequences: string[];           // What this means going forward
+  relatedTrajectories: string[];    // Where this was implemented
+  date: string;
+  participants: string[];           // Who was involved
+}
+
+interface PatternLibrary {
+  patterns: Pattern[];
+
+  // Query interface
+  findPattern(task: string): Pattern | null;
+  suggestPatterns(context: string): Pattern[];
+}
+
+interface Pattern {
+  id: string;
+  name: string;                     // "API Endpoint"
+  description: string;              // When to use this
+  template: string;                 // The actual pattern/template
+  examples: string[];               // File paths showing real usage
+  relatedTrajectories: string[];    // Where this was used
+  tags: string[];
+}
+
+interface KnowledgeBase {
+  documents: KnowledgeDoc[];
+
+  // Query interface
+  query(question: string): KnowledgeDoc[];
+  getContext(topic: string): string;
+}
+
+interface KnowledgeDoc {
+  id: string;
+  title: string;
+  content: string;                  // Markdown content
+  source: 'manual' | 'extracted' | 'generated';
+  relatedFiles: string[];           // Code files this relates to
+  lastUpdated: string;
+  tags: string[];
+}
+```
+
+### How It Gets Populated
+
+#### 1. Automatic Extraction
+
+```typescript
+// After each trajectory completes
+async function extractKnowledge(trajectory: Trajectory): Promise<void> {
+  // Extract decisions
+  for (const decision of trajectory.retrospective?.decisions ?? []) {
+    await decisionLog.add({
+      ...decision,
+      relatedTrajectories: [trajectory.id],
+      date: trajectory.completedAt
+    });
+  }
+
+  // Extract patterns (if agent documented any)
+  const patterns = extractPatternsFromTrajectory(trajectory);
+  for (const pattern of patterns) {
+    await patternLibrary.add(pattern);
+  }
+
+  // Update knowledge base with new understanding
+  await knowledgeBase.updateFromTrajectory(trajectory);
+}
+```
+
+#### 2. Agent Contribution
+
+Agents can explicitly add to the workspace:
+
+```
+[[KNOWLEDGE:decision]]
+{
+  "title": "Use React Query for server state",
+  "context": "Needed to manage API data fetching",
+  "decision": "React Query over Redux for server state",
+  "alternatives": ["Redux + RTK Query", "SWR", "Custom hooks"],
+  "reasoning": "Better caching, less boilerplate, team familiarity"
+}
+[[/KNOWLEDGE]]
+
+[[KNOWLEDGE:pattern]]
+{
+  "name": "Feature Flag Check",
+  "description": "How to check feature flags in components",
+  "template": "const isEnabled = useFeatureFlag('flag-name');\nif (!isEnabled) return null;"
+}
+[[/KNOWLEDGE]]
+```
+
+#### 3. Human Curation
+
+Humans can add/edit knowledge directly:
+
+```bash
+# Add a decision
+agent-relay knowledge add-decision "Why we don't use GraphQL" \
+  --context "Evaluated for API layer" \
+  --decision "REST with OpenAPI" \
+  --reasoning "Team experience, tooling maturity"
+
+# Add a pattern
+agent-relay knowledge add-pattern "Error Boundary" \
+  --file templates/error-boundary.tsx
+
+# Add documentation
+agent-relay knowledge add-doc "Architecture Overview" \
+  --file docs/architecture.md
+```
+
+### Query Interface for Agents
+
+Agents query the workspace naturally:
+
+```typescript
+interface WorkspaceQuery {
+  // Natural language queries
+  ask(question: string): Promise<QueryResult>;
+
+  // Specific lookups
+  getTrajectory(id: string): Promise<Trajectory>;
+  getDecision(topic: string): Promise<Decision | null>;
+  getPattern(name: string): Promise<Pattern | null>;
+
+  // Contextual suggestions
+  suggestForTask(taskDescription: string): Promise<Suggestions>;
+}
+
+interface Suggestions {
+  relevantTrajectories: TrajectorySummary[];
+  applicablePatterns: Pattern[];
+  relatedDecisions: Decision[];
+  teamExperts: AgentInfo[];           // Who might help
+  potentialGotchas: string[];          // From past retrospectives
+}
+```
+
+**Example agent interaction:**
+
+```
+Agent starting task: "Add rate limiting to API endpoints"
+
+Agent queries: workspace.suggestForTask("Add rate limiting to API endpoints")
+
+Returns:
+{
+  relevantTrajectories: [
+    { id: "traj-abc", title: "Implemented auth rate limiting", confidence: 0.9 }
+  ],
+  applicablePatterns: [
+    { name: "Middleware Pattern", description: "How we add cross-cutting concerns" }
+  ],
+  relatedDecisions: [
+    { title: "Use Redis for distributed state", relevant: true }
+  ],
+  teamExperts: [
+    { name: "Alice", expertise: "Previously implemented rate limiting" }
+  ],
+  potentialGotchas: [
+    "Previous rate limiting had issues with Redis connection pooling - see traj-abc retrospective"
+  ]
+}
+```
+
+### Storage: Where Does It Live?
+
+```
+.agent-workspace/
+├── trajectories/           # Work history (detailed above)
+├── decisions/
+│   ├── index.json
+│   └── decisions.jsonl     # Append-only decision log
+├── patterns/
+│   ├── index.json
+│   └── api-endpoint.md
+│   └── react-component.md
+├── knowledge/
+│   ├── index.json
+│   ├── architecture.md
+│   └── conventions.md
+├── conversations/
+│   └── 2024-01-15.jsonl    # Daily conversation logs
+└── team/
+    └── context.json        # Team member expertise/status
+```
+
+### The Flywheel Effect
+
+```
+More trajectories → More extracted knowledge → Better agent context →
+Better decisions → Better retrospectives → Richer trajectories → ...
+```
+
+Over time, the workspace becomes increasingly valuable:
+- Agents make fewer mistakes
+- Decisions are more consistent
+- Onboarding is instant
+- Institutional memory persists
+- Humans can audit and understand agent work
+
+---
+
+## Integration: claude-mem
+
+[claude-mem](https://github.com/thedotmack/claude-mem) is a persistent memory system for Claude Code that captures tool usage and observations. It's solving a similar problem at a different layer.
+
+### How They Compare
+
+| Aspect | claude-mem | Trajectories |
+|--------|------------|--------------|
+| **Focus** | Tool observations | Task narratives |
+| **Granularity** | Per-tool-call | Per-task |
+| **Scope** | Single agent | Multi-agent |
+| **Structure** | Observations + concepts | Chapters + decisions |
+| **Query** | Semantic search | Task/decision lookup |
+| **Persistence** | SQLite + Chroma | File + SQLite |
+
+### They're Complementary, Not Competing
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     AGENT MEMORY STACK                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  TRAJECTORIES (Task Layer)                                     │
+│  "The story of the work"                                       │
+│  - Multi-agent coordination                                    │
+│  - Decisions & retrospectives                                  │
+│  - Human-readable narratives                                   │
+│           │                                                     │
+│           │ aggregates                                          │
+│           ▼                                                     │
+│  CLAUDE-MEM (Observation Layer)                                │
+│  "What happened during the work"                               │
+│  - Tool call observations                                      │
+│  - Semantic concepts                                           │
+│  - Session continuity                                          │
+│           │                                                     │
+│           │ captures                                            │
+│           ▼                                                     │
+│  RAW EVENTS (Execution Layer)                                  │
+│  - Tool calls                                                  │
+│  - File changes                                                │
+│  - Messages                                                    │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Integration Strategy
+
+#### 1. Use claude-mem as Observation Source
+
+claude-mem already captures tool observations via hooks. Trajectories can aggregate these:
+
+```typescript
+// When trajectory chapter ends, pull observations from claude-mem
+async function enrichChapterFromClaudeMem(chapter: Chapter): Promise<void> {
+  const observations = await claudeMemClient.search({
+    timeRange: { start: chapter.startedAt, end: chapter.endedAt },
+    types: ['decision', 'discovery', 'bugfix']
+  });
+
+  chapter.events.push(...observations.map(obs => ({
+    ts: obs.timestamp,
+    type: 'observation',
+    content: obs.content,
+    source: 'claude-mem',
+    concepts: obs.concepts
+  })));
+}
+```
+
+#### 2. Shared Storage Layer
+
+Both could use the same SQLite database with different tables:
+
+```sql
+-- claude-mem tables
+CREATE TABLE observations (...);
+CREATE TABLE sessions (...);
+
+-- trajectory tables
+CREATE TABLE trajectories (...);
+CREATE TABLE chapters (...);
+
+-- linking table
+CREATE TABLE trajectory_observations (
+  trajectory_id TEXT,
+  observation_id TEXT,
+  FOREIGN KEY ...
+);
+```
+
+#### 3. Cross-Query Support
+
+Query trajectories, get relevant observations:
+
+```bash
+# "What observations were captured during task bd-123?"
+agent-relay trajectory bd-123 --show-observations
+
+# "What tasks used these concepts?"
+agent-relay search --concept "authentication" --include-trajectories
+```
+
+#### 4. Export/Import
+
+```bash
+# Export claude-mem session as trajectory
+claude-mem export session-123 --format trajectory > traj.json
+
+# Import trajectory into claude-mem for observation search
+agent-relay trajectory export bd-123 --format claude-mem | claude-mem import
+```
+
+### Proposed Hook Integration
+
+claude-mem uses Claude Code hooks. Trajectories can add complementary hooks:
+
+```typescript
+// SessionStart: Load active trajectory context
+hooks.onSessionStart(async () => {
+  const active = await trajectoryStore.getActive();
+  if (active) {
+    return {
+      context: `Active trajectory: ${active.task.title}\n` +
+               `Chapter: ${active.currentChapter.title}\n` +
+               `Decisions so far: ${active.decisions.map(d => d.title).join(', ')}`
+    };
+  }
+});
+
+// SessionEnd: Prompt for trajectory update
+hooks.onSessionEnd(async () => {
+  const active = await trajectoryStore.getActive();
+  if (active) {
+    return {
+      prompt: 'Before ending, update the trajectory with key decisions/learnings.'
+    };
+  }
+});
+```
+
+### Why Both Together
+
+| Use Case | claude-mem | Trajectories | Together |
+|----------|------------|--------------|----------|
+| "What tool did I use for X?" | ✅ | ❌ | ✅ |
+| "Why did we build it this way?" | ❌ | ✅ | ✅ |
+| "What happened in this session?" | ✅ | partial | ✅ |
+| "What's the full story of feature X?" | ❌ | ✅ | ✅ |
+| "What concepts are relevant to Y?" | ✅ | ❌ | ✅ |
+| "Who worked on what?" | ❌ | ✅ | ✅ |
+
+**claude-mem = operational memory** (detailed, semantic, per-agent)
+**Trajectories = narrative memory** (structured, task-centric, multi-agent)
+
+Together they create a complete memory stack.
+
+---
+
+## Architecture: Separate Providers in a Stack
+
+Each layer is a **separate project** that can be used independently or together:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    AGENT INFRASTRUCTURE STACK                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  AGENT-TRAJECTORIES (Layer 3)          ◄── THIS PROJECT │   │
+│  │  github.com/???/agent-trajectories                      │   │
+│  │                                                         │   │
+│  │  ┌─────────────────────────────────────────────────┐   │   │
+│  │  │  Workspace (built-in feature)                   │   │   │
+│  │  │  Patterns, decisions, knowledge extraction      │   │   │
+│  │  └─────────────────────────────────────────────────┘   │   │
+│  │                                                         │   │
+│  │  Task narratives, decisions, retrospectives             │   │
+│  │  Platform-agnostic .trajectory format                   │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                            ▲                                    │
+│                            │ aggregates                         │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  CLAUDE-MEM (Layer 2)                                   │   │
+│  │  github.com/thedotmack/claude-mem                       │   │
+│  │  Tool observations, semantic concepts, sessions         │   │
+│  │  Already exists - we integrate with it                  │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                            ▲                                    │
+│                            │ captures                           │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  AGENT-RELAY (Layer 1)                                  │   │
+│  │  github.com/khaliqgant/agent-relay                      │   │
+│  │  Real-time messaging, message persistence               │   │
+│  │  The communication substrate                            │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Each Project is Independent
+
+| Project | Can Use Alone? | Depends On |
+|---------|----------------|------------|
+| **agent-relay** | ✅ Yes | Nothing |
+| **claude-mem** | ✅ Yes | Nothing (Claude Code hooks) |
+| **agent-trajectories** | ✅ Yes | Nothing (but richer with relay/claude-mem) |
+
+### agent-trajectories Structure
+
+Workspace is a **built-in feature**, not a separate project:
+
+```
+agent-trajectories/
+├── src/
+│   ├── core/              # .trajectory format, types
+│   ├── capture/           # CLI, event capture
+│   ├── adapters/          # beads, linear, github, plain
+│   ├── workspace/         # Patterns, decisions, knowledge (opt-in)
+│   │   ├── decisions.ts   # Decision log
+│   │   ├── patterns.ts    # Pattern library
+│   │   ├── knowledge.ts   # Knowledge base
+│   │   └── extract.ts     # Auto-extraction from trajectories
+│   └── export/            # Markdown, timeline views
+```
+
+**Why combined:**
+1. Workspace is derived data from trajectories - not a separate concern
+2. Flywheel only works if tightly coupled (trajectory complete → extract → enrich next)
+3. Users expect "trajectory complete" → "knowledge extracted" to be automatic
+4. Single install, single config, simpler for users
+
+### Integration Points
+
+```typescript
+// agent-trajectories can pull from multiple sources:
+
+// 1. Messages from agent-relay
+import { RelayClient } from 'agent-relay';
+const messages = await relay.getMessages({ topic: taskId });
+
+// 2. Observations from claude-mem
+import { ClaudeMemClient } from 'claude-mem';
+const observations = await claudeMem.search({ timeRange, types });
+
+// 3. Or work standalone with just explicit agent output
+// [[TRAJECTORY:decision]] ... [[/TRAJECTORY]]
+```
+
+### Why Separate Projects?
+
+1. **Independent adoption** - Use trajectories without relay, or relay without trajectories
+2. **Different maintainers** - claude-mem is already external
+3. **Different release cycles** - Each can evolve independently
+4. **Cleaner dependencies** - No monolith, composable pieces
+5. **Community contributions** - Easier to contribute to focused projects
+
+### The Glue
+
+agent-relay serves as the **communication substrate** - it's what agents use to talk to each other. The other layers build on top:
+
+- claude-mem hooks into Claude Code directly
+- agent-trajectories can consume relay messages as events
+- agent-workspace queries trajectories for patterns
+
+---
+
+## Vision: Notion/Linear for Agent Work
+
+Think of trajectories as **the document layer for agent work**:
+
+| Tool | For Humans | Trajectory Equivalent for Agents |
+|------|------------|----------------------------------|
+| Notion | Knowledge base, docs | Readable narrative of work |
+| Linear | Issue tracking, timelines | Task progress with full context |
+| Git | Version history | Decision history with reasoning |
+
+A trajectory is a **living document** that:
+- Agents write to as they work
+- Humans read to understand
+- Tools index for search and analysis
+- Systems import/export freely
+
+---
+
+## Reading Experience: Multiple Views
+
+The same trajectory data can be rendered in multiple ways for different audiences:
+
+### Notion-style Page (Human Documentation)
+
+A rich, readable document with collapsible sections:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 🛤️ Implement User Authentication                               │
+│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│                                                                 │
+│ 📋 Summary                                                      │
+│ JWT-based auth with refresh tokens. 2h 34m. Confidence: 85%    │
+│                                                                 │
+│ ▶ Key Decisions (3)                                            │
+│ ▶ Chapters (4)                                                 │
+│ ▶ Retrospective                                                │
+│                                                                 │
+│ 🔗 Links: ENG-456 • PR #123 • 3 commits                        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Linear-style Timeline (Progress Tracking)
+
+Chronological view with status:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  ● 10:00  Started: Implement User Authentication               │
+│  │                                                              │
+│  ├─ 10:05  Chapter: Research existing patterns                 │
+│  │         Found 3 auth approaches, chose JWT                  │
+│  │                                                              │
+│  ├─ 10:30  Decision: JWT over sessions                         │
+│  │         "Stateless scaling requirement"                     │
+│  │                                                              │
+│  ├─ 11:00  Chapter: Implementation                             │
+│  │         Modified 8 files                                    │
+│  │                                                              │
+│  ├─ 12:00  Message: @Bob review request                        │
+│  │                                                              │
+│  ○ 12:30  Completed with retrospective                         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Git-integrated View (Code Review)
+
+Embedded in PRs and commits:
+
+```markdown
+## 📍 Trajectory Context
+
+This PR implements [ENG-456] as part of trajectory `traj_abc123`.
+
+**Why this approach:** JWT chosen over sessions for stateless scaling.
+See [full trajectory](link) for decision history.
+
+**Agent confidence:** 85% - solid implementation, suggest load testing
+the refresh token rotation.
+```
+
+### CLI View (Agent/Developer)
+
+```bash
+$ agent-relay trajectory status
+
+Active Trajectory: traj_abc123
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Task:     Implement user authentication
+Source:   linear:ENG-456
+Started:  2h 34m ago
+Agents:   Alice (active), Bob (reviewing)
+Chapters: 4 (current: "Testing")
+Decisions: 3 recorded
+```
+
+---
+
+## The Problem
+
+When an agent completes a task today, the only artifacts are:
+1. **Code changes** - the what, but not the why
+2. **Commit messages** - brief summaries
+3. **PR descriptions** - static snapshots
+4. **Chat logs** - ephemeral, lost when sessions end
+
+The rich context of *how* the work happened disappears:
+- Why was approach A chosen over B?
+- What dead ends were explored?
+- What assumptions were made?
+- How did agents coordinate?
+- What would the agent do differently?
+
+This is the "train of thought trajectory" - the complete story of the work.
+
+---
+
+## Core Concept: Trajectories
+
+A **trajectory** is a structured record of an agent's work on a task:
+
+```typescript
+interface Trajectory {
+  id: string;                    // UUID
+  version: 1;                    // Schema version (for forward compat)
+
+  // Task reference (platform-agnostic)
+  task: TaskReference;
+
+  // Timeline
+  startedAt: string;             // ISO timestamp
+  completedAt?: string;
+  status: 'active' | 'completed' | 'abandoned';
+
+  // Participants
+  agents: AgentParticipation[];  // Who worked on this
+
+  // The trajectory itself
+  chapters: Chapter[];           // Logical segments of work
+
+  // Synthesis
+  retrospective?: Retrospective; // Agent reflection
+
+  // Artifacts
+  commits: string[];             // Git SHAs produced
+  filesChanged: string[];        // Paths modified
+
+  // Metadata
+  projectId: string;
+  tags: string[];                // User-defined tags
+}
+
+/**
+ * Platform-agnostic task reference.
+ * Trajectories work with ANY task system.
+ */
+interface TaskReference {
+  // Human-readable
+  title: string;
+  description?: string;
+
+  // External system reference (optional)
+  source?: {
+    system: 'beads' | 'linear' | 'jira' | 'github' | 'plain' | string;
+    id: string;                  // e.g., "bd-123", "ENG-456", "GH#789"
+    url?: string;                // Link to external system
+  };
+
+  // If no external system, trajectory IS the task
+  // (standalone mode - like a Notion page)
+}
+
+interface Chapter {
+  id: string;
+  title: string;                 // "Initial exploration", "Implementation", etc.
+  agentName: string;
+  startedAt: string;
+  endedAt?: string;
+
+  events: TrajectoryEvent[];     // Ordered list of events
+}
+
+interface TrajectoryEvent {
+  ts: number;
+  type: 'prompt' | 'thinking' | 'tool_call' | 'tool_result' |
+        'message_sent' | 'message_received' | 'decision' | 'error';
+
+  // Type-specific data
+  content: string;               // Human-readable summary
+  raw?: unknown;                 // Full data (optional, for debugging)
+
+  // Annotations
+  significance?: 'low' | 'medium' | 'high' | 'critical';
+  tags?: string[];
+}
+
+interface Retrospective {
+  summary: string;               // What was accomplished
+  approach: string;              // How it was done
+  decisions: Decision[];         // Key decision points
+  challenges: string[];          // What was hard
+  learnings: string[];           // What was learned
+  suggestions: string[];         // What could be improved
+  confidence: number;            // 0-1, agent's confidence in solution
+  timeSpent?: string;            // Duration
+}
+
+interface Decision {
+  question: string;              // What was the choice?
+  chosen: string;                // What was picked
+  alternatives: string[];        // What was rejected
+  reasoning: string;             // Why
+}
+```
+
+---
+
+## Universal File Format: `.trajectory`
+
+Trajectories are stored as **self-contained documents** in a simple, portable format:
+
+### File Structure
+
+```
+my-feature.trajectory.json     # Machine-readable (primary)
+my-feature.trajectory.md       # Human-readable (generated)
+```
+
+Or bundled:
+```
+my-feature.trajectory/
+├── trajectory.json            # Full data
+├── README.md                  # Human summary
+├── chapters/
+│   ├── 01-exploration.md      # Chapter narratives
+│   └── 02-implementation.md
+└── artifacts/                 # Referenced files (optional)
+```
+
+### JSON Format (Primary)
+
+```json
+{
+  "$schema": "https://agent-relay.dev/schemas/trajectory-v1.json",
+  "version": 1,
+  "id": "traj_abc123",
+  "task": {
+    "title": "Implement user authentication",
+    "source": {
+      "system": "linear",
+      "id": "ENG-456",
+      "url": "https://linear.app/team/issue/ENG-456"
+    }
+  },
+  "startedAt": "2024-01-15T10:00:00Z",
+  "status": "completed",
+  "agents": [...],
+  "chapters": [...],
+  "retrospective": {...}
+}
+```
+
+### Markdown Format (Human-Readable)
+
+Auto-generated, Notion-like document:
+
+```markdown
+# 🛤️ Trajectory: Implement user authentication
+
+> **Task:** [ENG-456](https://linear.app/team/issue/ENG-456)
+> **Status:** ✅ Completed
+> **Duration:** 2h 34m
+> **Agents:** Alice, Bob
+> **Confidence:** 85%
+
+---
+
+## 📋 Summary
+
+Implemented JWT-based authentication with refresh tokens. Chose JWTs over
+sessions for stateless scaling. Key challenge was fixing existing type
+definitions that were incorrect.
+
+---
+
+## 🎯 Key Decisions
+
+### JWT vs Sessions
+- **Chose:** JWT with refresh tokens
+- **Rejected:** Server-side sessions
+- **Why:** Stateless scaling requirement, multi-server deployment planned
+
+---
+
+## 📖 Chapters
+
+### 1. Initial Exploration (10:00 - 10:30)
+Researched existing auth patterns in codebase. Found 3 different approaches
+already in use. Decided to follow the pattern in `src/auth/oauth.ts`.
+
+### 2. Implementation (10:30 - 12:00)
+[Detailed narrative...]
+
+---
+
+## 🔄 Retrospective
+
+**What went well:** Clean implementation, good test coverage.
+**Challenges:** UserContext types were wrong, had to fix first.
+**Would do differently:** Check existing types earlier in process.
+```
+
+---
+
+## Task Source Adapters
+
+Trajectories are **decoupled from task systems**. Adapters translate between systems:
+
+```typescript
+interface TaskSourceAdapter {
+  name: string;  // 'beads', 'linear', 'github', etc.
+
+  // Detect if this source is available
+  detect(): Promise<boolean>;
+
+  // Get task details for trajectory
+  getTask(id: string): Promise<TaskReference>;
+
+  // Listen for task state changes (optional)
+  onTaskStart?(callback: (task: TaskReference) => void): void;
+  onTaskComplete?(callback: (taskId: string) => void): void;
+
+  // Sync trajectory status back to source (optional)
+  updateTaskStatus?(taskId: string, status: string): Promise<void>;
+}
+```
+
+### Built-in Adapters
+
+| Adapter | Detection | Features |
+|---------|-----------|----------|
+| `beads` | `.beads/` dir | Full sync, auto-start on `bd update` |
+| `github` | `.git` + `gh` CLI | Link to issues/PRs |
+| `linear` | `LINEAR_API_KEY` env | Two-way sync |
+| `jira` | `JIRA_URL` env | Read-only (start) |
+| `plain` | Always available | Manual task creation |
+
+### Example: Standalone Mode (No External System)
+
+```bash
+# Create a trajectory without any task system
+agent-relay trajectory new "Refactor payment module"
+
+# The trajectory IS the task - like a Notion page
+```
+
+### Example: Beads Integration
+
+```bash
+# Beads task triggers trajectory automatically
+bd update bd-123 --status=in_progress
+# → Trajectory starts, linked to bd-123
+
+bd close bd-123
+# → Trajectory completes, retrospective prompted
+```
+
+### Example: Linear/Jira Integration
+
+```bash
+# Explicit link to external task
+agent-relay trajectory start --linear ENG-456 "Implement feature"
+
+# Or auto-detect from branch name
+git checkout -b feature/ENG-456-auth
+agent-relay trajectory start  # Auto-links to ENG-456
+```
+
+---
+
+## How Trajectories Help
+
+### 1. Code Review
+
+**Before:** Reviewer sees a PR with 500 lines changed. Has to guess at intent.
+
+**After:** Reviewer can:
+- Read the trajectory summary
+- See what alternatives were considered
+- Understand why specific patterns were chosen
+- Ask pointed questions based on documented decisions
+- Trust the agent's confidence score
+
+```markdown
+## Trajectory Summary for bd-123
+
+**Approach:** Used React Query instead of Redux for server state because
+the codebase already has 3 different state management patterns and RQ
+is isolated to this feature.
+
+**Key Decisions:**
+1. Cache invalidation: Chose optimistic updates over refetch because
+   user feedback latency was the primary concern
+2. Error handling: Retry 3x with exponential backoff, then show inline
+   error (not toast) per UX guidelines in docs/STYLE.md
+
+**Challenges:** The existing UserContext wasn't typed properly. Fixed
+types as prerequisite work.
+
+**Confidence:** 0.85 - Solid solution, but cache invalidation edge cases
+should be tested under load.
+```
+
+### 2. Bug Diagnosis
+
+**Scenario:** A bug is found 3 months after the feature shipped.
+
+**Before:** Developer has to:
+- Read git blame
+- Guess at original intent
+- Maybe find a stale PR description
+- Reconstruct reasoning from scratch
+
+**After:** Developer can:
+- Query: "show me the trajectory for the commit that introduced this function"
+- See the original requirements
+- See what edge cases were considered (and maybe missed)
+- See the agent's confidence and caveats
+- Understand the context that led to this code
+
+```bash
+# Find trajectory for a specific change
+agent-relay trajectory --commit abc123
+agent-relay trajectory --file src/auth/session.ts --since 2024-01
+
+# See what the agent was thinking
+agent-relay trajectory bd-456 --show-thinking
+```
+
+### 3. Future Changes
+
+**Scenario:** Need to extend a feature built by a different agent/developer.
+
+**Before:** Start from scratch understanding the code.
+
+**After:**
+- Read the trajectory to understand architectural decisions
+- See what approaches were rejected (and why - so you don't repeat them)
+- Understand the constraints that shaped the original design
+- Build on documented reasoning rather than guessing
+
+### 4. Institutional Memory
+
+Over time, trajectories become a knowledge base:
+- "How have we solved caching problems before?"
+- "What patterns did we use for authentication?"
+- "What libraries did we evaluate for X?"
+
+```bash
+# Search across all trajectories
+agent-relay trajectory search "rate limiting"
+agent-relay trajectory search --tag "api-design"
+```
+
+### 5. Packaging with Code
+
+Trajectories should live **with the code**, not in a separate system:
+
+```
+project/
+├── src/
+├── .beads/
+│   └── issues.jsonl
+├── .trajectories/
+│   ├── index.json              # Index of all trajectories
+│   ├── bd-123.json             # Full trajectory
+│   ├── bd-123.summary.md       # Human-readable summary
+│   └── bd-456.json
+└── README.md
+```
+
+**Git integration:**
+- Trajectories are committed with the code
+- They're part of the repo's history
+- They can be reviewed in PRs
+- They're searchable via git grep
+
+**Alternatively**, for large repos, store only summaries in git and full trajectories in external storage (S3, database) with references:
+
+```json
+{
+  "id": "bd-123",
+  "summary": "...",
+  "fullTrajectoryUrl": "s3://trajectories/project/bd-123.json"
+}
+```
+
+---
+
+## Storage Architecture
+
+### Storage Backends
+
+Trajectories support multiple storage backends:
+
+| Backend | Use Case | Notes |
+|---------|----------|-------|
+| **File system** | Default, git-friendly | `.trajectories/` in repo |
+| **SQLite** | Local indexing, search | Same DB as messages |
+| **PostgreSQL** | Multi-user, cloud | Shared team access |
+| **S3/GCS** | Archive, large teams | Cold storage for old trajectories |
+
+### File System (Default)
+
+```
+.trajectories/
+├── index.json                    # Quick lookup index
+├── active/                       # In-progress trajectories
+│   └── traj_abc123.json
+├── completed/                    # Finished trajectories
+│   ├── 2024-01/
+│   │   ├── traj_def456.json
+│   │   └── traj_def456.md        # Human-readable export
+│   └── 2024-02/
+└── archive/                      # Compressed old trajectories
+```
+
+### SQLite Schema
+
+For search and querying:
+
+```sql
+CREATE TABLE trajectories (
+  id TEXT PRIMARY KEY,
+  task_source TEXT,                -- 'beads', 'linear', 'github', etc.
+  task_id TEXT,                    -- External task ID (nullable for standalone)
+  task_title TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+
+  started_at INTEGER NOT NULL,
+  completed_at INTEGER,
+
+  -- Denormalized for queries
+  agent_names TEXT,                -- JSON array
+  commit_shas TEXT,                -- JSON array
+  files_changed TEXT,              -- JSON array
+
+  -- Full data
+  chapters TEXT NOT NULL,          -- JSON
+  retrospective TEXT,              -- JSON
+
+  -- Metadata
+  version INTEGER DEFAULT 1,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_trajectories_task ON trajectories(task_id);
+CREATE INDEX idx_trajectories_project ON trajectories(project_id);
+CREATE INDEX idx_trajectories_started ON trajectories(started_at);
+```
+
+### New Table: `trajectory_events`
+
+For efficient querying of individual events:
+
+```sql
+CREATE TABLE trajectory_events (
+  id TEXT PRIMARY KEY,
+  trajectory_id TEXT NOT NULL,
+  chapter_id TEXT NOT NULL,
+
+  ts INTEGER NOT NULL,
+  type TEXT NOT NULL,
+  agent_name TEXT NOT NULL,
+
+  content TEXT NOT NULL,
+  raw TEXT,                        -- Full JSON (optional)
+  significance TEXT,
+  tags TEXT,                       -- JSON array
+
+  FOREIGN KEY (trajectory_id) REFERENCES trajectories(id)
+);
+
+CREATE INDEX idx_events_trajectory ON trajectory_events(trajectory_id);
+CREATE INDEX idx_events_type ON trajectory_events(type);
+CREATE INDEX idx_events_ts ON trajectory_events(ts);
+```
+
+### Storage Adapter Extension
+
+```typescript
+interface TrajectoryStorageAdapter extends StorageAdapter {
+  // Trajectory CRUD
+  saveTrajectory(trajectory: Trajectory): Promise<void>;
+  getTrajectory(id: string): Promise<Trajectory | null>;
+  getTrajectoryByTaskId(taskId: string): Promise<Trajectory | null>;
+
+  // Queries
+  listTrajectories(query: TrajectoryQuery): Promise<TrajectorySummary[]>;
+  searchTrajectories(text: string): Promise<TrajectorySummary[]>;
+
+  // Events (for streaming/incremental updates)
+  appendEvent(trajectoryId: string, event: TrajectoryEvent): Promise<void>;
+  getEvents(trajectoryId: string, since?: number): Promise<TrajectoryEvent[]>;
+
+  // Export
+  exportTrajectory(id: string, format: 'json' | 'markdown'): Promise<string>;
+}
+```
+
+---
+
+## Capture Mechanisms
+
+### 1. Automatic Capture (Wrapper-Level)
+
+The tmux wrapper already intercepts output. Extend it to capture:
+
+```typescript
+// In tmux-wrapper.ts
+class TrajectoryCapture {
+  private currentTrajectory?: Trajectory;
+  private currentChapter?: Chapter;
+
+  // Called when agent starts work on a task
+  startTrajectory(taskId: string, taskTitle: string): void;
+
+  // Called for each significant event
+  recordEvent(event: Omit<TrajectoryEvent, 'ts'>): void;
+
+  // Called when switching focus
+  startChapter(title: string): void;
+
+  // Called when task completes
+  endTrajectory(): void;
+}
+```
+
+### 2. Explicit Agent Output
+
+Agents can emit structured trajectory data:
+
+```
+[[TRAJECTORY:event]]
+{
+  "type": "decision",
+  "content": "Chose PostgreSQL over SQLite for production scaling",
+  "significance": "high",
+  "alternatives": ["SQLite with read replicas", "MySQL"],
+  "reasoning": "Team already has PG expertise, and we need JSONB for the schema"
+}
+[[/TRAJECTORY]]
+```
+
+### 3. Message Integration
+
+Inter-agent messages are automatically captured:
+
+```typescript
+// When routing a message
+router.on('message', (envelope) => {
+  trajectoryCapture.recordEvent({
+    type: envelope.from === currentAgent ? 'message_sent' : 'message_received',
+    content: envelope.payload.body,
+    agentName: envelope.from,
+    significance: 'medium'
+  });
+});
+```
+
+### 4. Task System Integration
+
+Trajectories link to external task systems via adapters:
+
+```typescript
+// Any adapter can trigger trajectory lifecycle
+taskAdapter.onTaskStart((task: TaskReference) => {
+  trajectoryCapture.startTrajectory(task);
+});
+
+taskAdapter.onTaskComplete((taskId: string) => {
+  trajectoryCapture.endTrajectory();
+  promptForRetrospective();
+});
+
+// Example: Beads adapter watches for 'bd update/close'
+// Example: Linear adapter polls API or uses webhooks
+// Example: GitHub adapter watches for issue state changes
+```
+
+---
+
+## Retrospectives
+
+Encourage agents to reflect by:
+
+### 1. Automatic Prompting
+
+When an agent completes a task (via any task system or manually), inject:
+
+```
+📝 RETROSPECTIVE REQUEST
+
+You just completed: "Implement user authentication"
+
+Please reflect on your work by outputting a retrospective:
+
+[[RETROSPECTIVE]]
+{
+  "summary": "What did you accomplish?",
+  "approach": "How did you approach it?",
+  "decisions": [
+    {"question": "...", "chosen": "...", "alternatives": [...], "reasoning": "..."}
+  ],
+  "challenges": ["What was difficult?"],
+  "learnings": ["What did you learn?"],
+  "suggestions": ["What could be improved?"],
+  "confidence": 0.85
+}
+[[/RETROSPECTIVE]]
+```
+
+### 2. Structured Templates
+
+Provide templates that make it easy:
+
+```typescript
+const RETROSPECTIVE_TEMPLATE = {
+  prompts: {
+    summary: "Summarize what was accomplished in 1-2 sentences",
+    approach: "Describe the high-level approach taken",
+    decisions: "List the key decisions made and why",
+    challenges: "What was unexpectedly difficult?",
+    learnings: "What would you do differently next time?",
+    suggestions: "Any improvements for the codebase or process?",
+    confidence: "Rate your confidence in the solution (0-1)"
+  }
+};
+```
+
+### 3. Gamification (Optional)
+
+- Track retrospective completion rates per agent
+- Show "trajectory completeness" scores
+- Surface trajectories that lack retrospectives
+
+---
+
+## CLI Commands
+
+```bash
+# Start tracking a task
+agent-relay trajectory start bd-123 "Implement auth module"
+
+# View current trajectory
+agent-relay trajectory status
+
+# Add a decision point manually
+agent-relay trajectory decision "Chose JWT over sessions" \
+  --reasoning "Stateless scaling requirements" \
+  --alternatives "sessions" "oauth tokens"
+
+# Complete and generate retrospective
+agent-relay trajectory complete bd-123
+
+# Export for code review
+agent-relay trajectory export bd-123 --format markdown > trajectory.md
+
+# Search trajectories
+agent-relay trajectory search "authentication"
+agent-relay trajectory list --agent Alice --since 2024-01-01
+
+# View trajectory for a commit
+agent-relay trajectory --commit abc123
+
+# Package trajectories for PR
+agent-relay trajectory bundle bd-123 bd-124 --output pr-trajectories.md
+```
+
+---
+
+## Export Formats
+
+### Markdown (for PRs and docs)
+
+```markdown
+# Trajectory: Implement User Authentication (bd-123)
+
+**Duration:** 2 hours 34 minutes
+**Agents:** Alice (lead), Bob (review)
+**Commits:** abc123, def456
+**Confidence:** 0.85
+
+## Summary
+
+Implemented JWT-based authentication with refresh tokens...
+
+## Key Decisions
+
+### 1. JWT vs Sessions
+**Chose:** JWT with refresh tokens
+**Rejected:** Server-side sessions
+**Reasoning:** Stateless scaling requirement, multiple server deployment planned
+
+### 2. Token Storage
+**Chose:** HttpOnly cookies
+**Rejected:** localStorage
+**Reasoning:** XSS protection more important than API flexibility
+
+## Challenges
+
+- Existing UserContext types were incorrect, required fixing first
+- Rate limiting middleware had race condition, refactored
+
+## Retrospective
+
+The implementation is solid but the refresh token rotation logic
+should be tested more thoroughly under load. Consider adding
+integration tests for the token refresh flow.
+```
+
+### JSON (for tooling)
+
+Full structured format for programmatic access.
+
+### Git Notes (experimental)
+
+Attach trajectory summaries to commits via git notes:
+
+```bash
+git notes add -m "$(agent-relay trajectory export abc123 --format summary)" abc123
+```
+
+---
+
+## Privacy & Security Considerations
+
+1. **Thinking blocks:** May contain sensitive reasoning. Option to redact or summarize.
+
+2. **Credentials:** Trajectory capture must never log secrets. Sanitize:
+   - Environment variables
+   - API keys
+   - Passwords in commands
+
+3. **Retention:** Configurable retention periods. Old trajectories can be:
+   - Archived (compressed, moved to cold storage)
+   - Summarized (keep retrospective, delete events)
+   - Deleted
+
+4. **Access control:** In multi-tenant scenarios, trajectories should respect permissions.
+
+---
+
+## Migration Path
+
+### Phase 1: Foundation
+- Define trajectory JSON schema (v1)
+- File-based storage (`.trajectories/` directory)
+- CLI: `trajectory new`, `trajectory status`, `trajectory complete`
+- Manual capture via `[[TRAJECTORY:*]]` blocks
+
+### Phase 2: Task Adapters
+- Beads adapter (auto-start on `bd update --status=in_progress`)
+- GitHub adapter (link to issues/PRs)
+- Plain adapter (standalone trajectories)
+- Adapter plugin interface for custom systems
+
+### Phase 3: Automatic Capture
+- Message capture from router
+- Retrospective prompting on task complete
+- SQLite indexing for search
+
+### Phase 4: Human-Readable Layer
+- Markdown export (Notion-style pages)
+- Timeline view (Linear-style)
+- PR/commit integration
+- Trajectory viewer in dashboard
+
+### Phase 5: Intelligence
+- Auto-summarization (LLM-generated summaries)
+- Decision extraction from conversation
+- Cross-trajectory search and analysis
+- Similarity detection ("how did we solve this before?")
+
+---
+
+## Open Questions
+
+1. **Storage location:** `.trajectories/` in repo vs external database?
+   - In-repo: Versioned with code, but bloats repo
+   - External: Scalable, but requires infra
+
+2. **Granularity:** How much detail to capture?
+   - Every tool call? Just summaries?
+   - Full thinking blocks? Summarized?
+
+3. **Multi-agent coordination:** How to merge trajectories when agents collaborate?
+   - One trajectory per task, multiple chapters per agent?
+   - Separate trajectories with cross-references?
+
+4. **Real-time vs batch:** Capture incrementally or at end?
+   - Incremental: Survives crashes, but more I/O
+   - Batch: Simpler, but loses data on failure
+
+5. **Retrospective quality:** How to encourage thoughtful retrospectives?
+   - Structured prompts?
+   - Required fields?
+   - Quality scoring?
+
+---
+
+## Success Metrics
+
+1. **Adoption:** % of closed tasks with trajectories
+2. **Completeness:** Avg retrospective quality score
+3. **Utility:** How often trajectories are referenced in code review
+4. **Bug resolution:** Time to understand bugs in code with trajectories vs without
+5. **Onboarding:** Time for new developers to understand features with trajectories
+
+---
+
+## Conclusion
+
+Train of thought trajectories transform ephemeral agent work into durable knowledge. By capturing the *why* alongside the *what*, we create a searchable, reviewable, portable record that:
+
+- Makes code review meaningful
+- Accelerates bug diagnosis
+- Preserves institutional knowledge
+- Enables learning from past work
+- Builds trust in agent-generated code
+
+The key insight is that **the trajectory is as valuable as the code**. Just as we version control source, we should version control the reasoning that produced it.
+
+---
+
+## References & Inspiration
+
+### Industry Context
+
+**Gergely Orosz (Pragmatic Engineer)** on agent trajectories:
+- Tweet: https://x.com/gergelyorosz/status/2002160432841097239
+- From ["How do AI software engineering agents work?"](https://newsletter.pragmaticengineer.com/p/ai-coding-agents):
+  > "The trajectory of the run. Trajectory refers to the full history log of the run. It usually takes the agent about 10 'turns' to reach the point of attempting to submit a solution."
+
+**SWE-agent (Princeton)** - Open-source coding agent that popularized the "trajectory" terminology for agent run histories.
+
+### Related Observations
+
+From Gergely's tweets on AI agents:
+- "A BIG difference with AI agents: they will write more code, faster than before, and ship a LOT more code to prod! So ship more bugs as well."
+- "AI agents being able to run unit tests is SUCH a massive unlock."
+- "Working with multiple AI agents comes VERY natural to senior+ engineers who worked at large companies - you already got used to overseeing parallel work."
+
+These insights reinforce why trajectory capture matters:
+1. **More code, faster** → Need better traceability
+2. **Parallel agent work** → Need coordination history
+3. **Bug diagnosis** → Need to understand what the agent was thinking
diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md
index 31ef4f5ed..2fcf61df1 100644
--- a/docs/PROTOCOL.md
+++ b/docs/PROTOCOL.md
@@ -290,15 +290,15 @@ Client should send fresh HELLO.
 ### Inline Format (single line only)
 
 ```
-@relay:codex-1 Your turn to play
-@thinking:* Considering the Queen...
+->relay:codex-1 Your turn to play
+->thinking:* Considering the Queen...
 ```
 
 ### Rules
 
 1. Block: Only parse when `[[RELAY]]` at start of line
 2. Inline: Only at start of line, not in code fences
-3. Escape: `\@relay:` outputs literal `@relay:`
+3. Escape: `\->relay:` outputs literal `->relay:`
 
 ---
 
diff --git a/docs/SCALING_ANALYSIS.md b/docs/SCALING_ANALYSIS.md
index afb204768..e8b0e9be0 100644
--- a/docs/SCALING_ANALYSIS.md
+++ b/docs/SCALING_ANALYSIS.md
@@ -145,7 +145,7 @@ Let's separate "nice to have" from "essential":
 2. **Know who's busy vs idle** → Activity state in agents output
 3. **Message history** → `agent-relay history` (already proposed)
 4. **Quick attach** → `agent-relay attach Alice`
-5. **Group messaging** → `@relay:@backend` (already proposed)
+5. **Group messaging** → `->relay:@backend` (already proposed)
 
 ### Nice to Have (but complex)
 
@@ -228,7 +228,7 @@ The TUI dashboard is over-engineered. tmux already provides:
 ## Updated Design Recommendation
 
 ### Keep from Phase 5:
-- Agent groups (`@relay:@backend`)
+- Agent groups (`->relay:@backend`)
 - Message priority (`!`, `?`)
 - `agent-relay agents` command
 - `agent-relay history` command
@@ -262,7 +262,7 @@ watch -n2 agent-relay agents
 | See all agents | Open TUI, see list | `agent-relay agents` or `Ctrl+B w` |
 | Switch to Bob | Press 'a', select Bob | `Ctrl+B 1` or `agent-relay attach Bob` |
 | Check if Alice is busy | See "typing..." in TUI | Check status column in agents |
-| Send message to group | Same | Same (`@relay:@backend`) |
+| Send message to group | Same | Same (`->relay:@backend`) |
 | View history | Press 'h' in TUI | `agent-relay history` |
 
 **The simpler approach does everything the TUI does, with 80% less code.**
diff --git a/docs/TMUX_IMPLEMENTATION_NOTES.md b/docs/TMUX_IMPLEMENTATION_NOTES.md
index 82a0614b7..0298299c8 100644
--- a/docs/TMUX_IMPLEMENTATION_NOTES.md
+++ b/docs/TMUX_IMPLEMENTATION_NOTES.md
@@ -47,7 +47,7 @@ The previous tmux implementation had these issues:
 │  TmuxWrapper (this process)      │
 │  - Polls capture-pane @ 100ms    │
 │  - Detects new output (diff)     │
-│  - Parses @relay: commands       │
+│  - Parses ->relay: commands       │
 │  - Writes to stdout for user     │
 │  - Injects messages via send-keys│
 │  - Forwards user stdin to tmux   │
@@ -103,12 +103,12 @@ process.stdin.on('data', (data) => {
    - Solution: Use -S - to get full scrollback, diff against last capture
 
 2. **Binary/escape sequences**: Output might contain control characters
-   - Solution: Strip ANSI codes before parsing @relay:
+   - Solution: Strip ANSI codes before parsing ->relay:
 
 3. **Session death**: tmux session might exit
    - Solution: Monitor with `tmux has-session -t session`
 
-4. **Multiple messages**: Several @relay: in one capture
+4. **Multiple messages**: Several ->relay: in one capture
    - Solution: Track last processed line/position
 
 5. **Stdin race conditions**: User types while we inject
@@ -119,7 +119,7 @@ process.stdin.on('data', (data) => {
 1. **Basic session start**: Does claude actually launch in tmux?
 2. **Output capture**: Can we see claude's output?
 3. **Input injection**: Can we send text and get response?
-4. **@relay detection**: Does parser find @relay: commands?
+4. **->relay detection**: Does parser find ->relay: commands?
 5. **Full game**: Two agents playing tic-tac-toe
 
 ## Rollback Plan
@@ -194,10 +194,10 @@ node dist/cli/index.js send -f Coordinator -t PlayerX -m "Hello from Coordinator
 node dist/cli/index.js start -f
 
 # Terminal 2: PlayerX
-node dist/cli/index.js wrap --tmux2 -n PlayerX -- claude -p "You are PlayerX playing tic-tac-toe. Use @relay:PlayerO to send moves. Start with your first move."
+node dist/cli/index.js wrap --tmux2 -n PlayerX -- claude -p "You are PlayerX playing tic-tac-toe. Use ->relay:PlayerO to send moves. Start with your first move."
 
 # Terminal 3: PlayerO
-node dist/cli/index.js wrap --tmux2 -n PlayerO -- claude -p "You are PlayerO playing tic-tac-toe. Use @relay:PlayerX to send moves. Wait for PlayerX to start."
+node dist/cli/index.js wrap --tmux2 -n PlayerO -- claude -p "You are PlayerO playing tic-tac-toe. Use ->relay:PlayerX to send moves. Wait for PlayerX to start."
 ```
 
 ### Debugging
@@ -253,7 +253,7 @@ The message was successfully typed into the bash terminal via tmux send-keys.
 
 1. Test with Claude CLI (replace bash with claude)
 2. Test full tic-tac-toe game between two agents
-3. Verify @relay: command parsing works in both directions
+3. Verify ->relay: command parsing works in both directions
 4. Check if multi-round injection remains stable (previous implementations failed after 2-3 rounds)
 
 ### Critical Question
@@ -306,10 +306,10 @@ The critical test is whether injection remains stable over multiple rounds:
 node dist/cli/index.js start -f
 
 # Terminal 2: PlayerX
-node dist/cli/index.js wrap --tmux2 -n PlayerX -- claude -p "Play tic-tac-toe. Use @relay:PlayerO to send moves."
+node dist/cli/index.js wrap --tmux2 -n PlayerX -- claude -p "Play tic-tac-toe. Use ->relay:PlayerO to send moves."
 
 # Terminal 3: PlayerO
-node dist/cli/index.js wrap --tmux2 -n PlayerO -- claude -p "Play tic-tac-toe. Use @relay:PlayerX to send moves."
+node dist/cli/index.js wrap --tmux2 -n PlayerO -- claude -p "Play tic-tac-toe. Use ->relay:PlayerX to send moves."
 ```
 
 If this works for a full game (5-9 moves), we've solved the problem.
diff --git a/docs/TMUX_IMPROVEMENTS.md b/docs/TMUX_IMPROVEMENTS.md
index 21de5e271..57a21a8c4 100644
--- a/docs/TMUX_IMPROVEMENTS.md
+++ b/docs/TMUX_IMPROVEMENTS.md
@@ -22,7 +22,7 @@
 │       ├─► setInterval(200ms)                                        │
 │       │       └─► execAsync('tmux capture-pane -p -J -S -')         │
 │       │               └─► parser.parse(output)                      │
-│       │                       └─► detect @relay: patterns           │
+│       │                       └─► detect ->relay: patterns           │
 │       │                               └─► send to daemon            │
 │       │                                                              │
 │       └─► onMessage from daemon                                     │
@@ -234,7 +234,7 @@ tmux send-keys -t $SESSION -l "Message: $MSG"
 
 ```typescript
 // Parser handles real-world terminal mess
-const INLINE_RELAY = /^(?:\s*(?:[>$%#→➜›»●•◦‣⁃\-*⏺◆◇○□■]\s*)*)?@relay:(\S+)\s+(.+)$/;
+const INLINE_RELAY = /^(?:\s*(?:[>$%#→➜›»●•◦‣⁃\-*⏺◆◇○□■]\s*)*)?->relay:(\S+)\s+(.+)$/;
 
 // Strip ANSI codes
 const ANSI_PATTERN = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b\].*?(?:\x07|\x1b\\)|\r/g;
@@ -263,7 +263,7 @@ send-relay-message.sh Bob "Subject" "Body"
 | Aspect | Pattern Parsing (Ours) | API-based (Theirs) |
 |--------|------------------------|-------------------|
 | **Agent effort** | Just output text | Call external script |
-| **Natural** | Yes (`@relay:Bob hi`) | No (shell command) |
+| **Natural** | Yes (`->relay:Bob hi`) | No (shell command) |
 | **Reliable** | ~95% (edge cases) | 100% (structured) |
 | **Multi-line** | Complex (continuation) | Easy (JSON body) |
 | **ANSI codes** | Must strip | N/A |
@@ -430,12 +430,14 @@ async function injectSafe(text: string): Promise<void> {
 Gemini CLI uses `@` for file references:
 ```bash
 gemini> @src/main.ts    # References a file
-gemini> @relay:Bob Hi   # Gemini might try to open file "relay:Bob"!
+gemini> ->relay:Bob Hi   # Gemini might try to open file "relay:Bob"!
 ```
 
 This could explain why Gemini agents have trouble sending relay messages - the CLI intercepts `@` before it reaches the terminal output.
 
-### Proposed Alternative Prefixes
+We've standardized on `->relay:` for all CLIs to keep a single mental model. Keep the prefix configurable so Gemini users can fall back to an alternative if their CLI mangles the arrow sequence.
+
+### Optional Alternative Prefixes
 
 | Prefix | Example | Pros | Cons |
 |--------|---------|------|------|
@@ -455,7 +457,7 @@ Support multiple prefixes with a default that works everywhere:
 ```typescript
 // In config
 {
-  "relayPrefix": "@relay:",     // Default (works for Claude, Codex)
+  "relayPrefix": "->relay:",     // Default (works across Claude/Codex/Gemini)
   // Alternatives:
   // "relayPrefix": ">>",        // For Gemini
   // "relayPrefix": "/relay",    // Slash command style
@@ -463,35 +465,38 @@ Support multiple prefixes with a default that works everywhere:
 }
 
 // In parser.ts
-const prefix = config.relayPrefix || '@relay:';
+const prefix = config.relayPrefix || '->relay:';
 const pattern = new RegExp(`^(?:\\s*)?${escapeRegex(prefix)}(\\S+)\\s+(.+)$`);
 ```
 
 ### Testing Gemini with Alternative Prefix
 
 ```bash
-# Start with alternative prefix
+# Default: unified arrow prefix
+agent-relay -n GeminiAgent gemini
+
+# If Gemini mangles ->relay:, try an alternative prefix
 agent-relay -n GeminiAgent --prefix=">>" gemini
 
 # Agent outputs:
 >>Bob: Can you review this code?
 
 # Instead of:
-@relay:Bob Can you review this code?
+->relay:Bob Can you review this code?
 ```
 
 ### Implementation: CLI Flag
 
 ```typescript
 // In cli/index.ts
-.option('--prefix <pattern>', 'Relay pattern prefix (default: @relay:)')
+.option('--prefix <pattern>', 'Relay pattern prefix (default: ->relay:)')
 
 // In wrapper config
 const wrapperConfig: TmuxWrapperConfig = {
   name: options.name,
   command: mainCommand,
   args: commandArgs,
-  relayPrefix: options.prefix || '@relay:',
+  relayPrefix: options.prefix || '->relay:',
   // ...
 };
 ```
@@ -505,7 +510,7 @@ export class OutputParser {
   private inlinePattern: RegExp;
 
   constructor(options: ParserOptions = {}) {
-    this.prefix = options.prefix || '@relay:';
+    this.prefix = options.prefix || '->relay:';
 
     // Build pattern dynamically
     const escaped = this.escapeRegex(this.prefix);
@@ -523,20 +528,14 @@ export class OutputParser {
 ### Recommendation
 
 1. **Short term:** Add `--prefix` flag to test with Gemini
-2. **Default for Gemini:** Auto-detect and use `>>` or `/relay`
-3. **Long term:** Document which prefix works best per CLI
+2. **Default for all CLIs:** Keep unified `->relay:` prefix; override only when needed
+3. **Long term:** Document recommended fallbacks per CLI if issues appear
 
 ```typescript
 // Auto-detect best prefix for CLI type
 function getDefaultPrefix(cliType: string): string {
-  switch (cliType) {
-    case 'gemini':
-      return '>>';        // Avoid @ conflict
-    case 'claude':
-    case 'codex':
-    default:
-      return '@relay:';   // Original, works fine
-  }
+  // Unified default; users can override via --prefix when necessary
+  return '->relay:';
 }
 ```
 
@@ -570,7 +569,7 @@ Our tmux wrapper uses an **attach-based polling architecture**:
 │                                                              │
 │  Background (every 200ms)                                    │
 │    └─ tmux capture-pane -p -J -S -                          │
-│         └─ Parse for @relay: patterns                       │
+│         └─ Parse for ->relay: patterns                       │
 │         └─ Send detected commands to daemon                 │
 │                                                              │
 │  Message Injection                                           │
@@ -664,12 +663,12 @@ We only need tmux and Node.js. No native compilation (node-pty), no browser comp
 
 ### 3. Pattern-Based Communication
 
-Agents just output `@relay:Name message`. No API calls, no special handling.
+Agents just output `->relay:Name message`. No API calls, no special handling.
 
 ```
 # Our approach - agent outputs text naturally
 Claude: I'll ask Bob for help.
-@relay:Bob Can you review the auth module?
+->relay:Bob Can you review the auth module?
 
 # Alternative - agent calls external script
 Claude: I'll ask Bob for help.
diff --git a/docs/competitive-analysis-mcp-agent-mail.md b/docs/competitive-analysis-mcp-agent-mail.md
index 4e97d5684..5c6329888 100644
--- a/docs/competitive-analysis-mcp-agent-mail.md
+++ b/docs/competitive-analysis-mcp-agent-mail.md
@@ -75,7 +75,7 @@
 │                     Tmux Session                            │
 │  ├─ Agent Process (claude, codex, gemini)                   │
 │  ├─ Silent Polling (capture-pane @ 200ms)                   │
-│  ├─ Pattern Detection (@relay:)                             │
+│  ├─ Pattern Detection (->relay:)                             │
 │  └─ Message Injection (send-keys)                           │
 └────────────────────────────┬────────────────────────────────┘
                              │ Unix Socket IPC
@@ -112,8 +112,8 @@
 
 | Feature | mcp_agent_mail | agent-relay |
 |---------|----------------|-------------|
-| **API** | `send_message()` tool call | `@relay:Name message` pattern |
-| **Broadcast** | `to=["*"]` | `@relay:*` |
+| **API** | `send_message()` tool call | `->relay:Name message` pattern |
+| **Broadcast** | `to=["*"]` | `->relay:*` |
 | **Attachments** | Yes (images, files) | No |
 | **Threading** | Yes (`thread_id`) | No |
 | **Markdown** | Full GFM support | Plain text |
@@ -182,7 +182,7 @@
 |---------|----------------|-------------|
 | **Setup** | Python venv, pip install, .env | npm install, single binary |
 | **Integration** | MCP client required | Pattern in stdout |
-| **Learning Curve** | Steep (40+ tools) | Minimal (@relay:) |
+| **Learning Curve** | Steep (40+ tools) | Minimal (->relay:) |
 | **Debugging** | Structured logging, metrics | Dashboard + logs |
 
 **Winner: agent-relay** - Much simpler to get started.
@@ -272,12 +272,12 @@
 
 1. **Add File Reservation System** (from mcp_agent_mail)
    - Advisory locks with TTL
-   - `@relay:lock src/**/*.ts` pattern
+   - `->relay:lock src/**/*.ts` pattern
    - Pre-commit hook integration
    - Critical for multi-agent file editing
 
 2. **Add Message Threading**
-   - `@relay:Bob [thread:feature-123] message`
+   - `->relay:Bob [thread:feature-123] message`
    - Group related messages
    - Better context tracking
 
@@ -294,12 +294,12 @@
 ### Medium Priority
 
 5. **Add Message Attachments**
-   - `@relay:Bob [attach:path/to/file]`
+   - `->relay:Bob [attach:path/to/file]`
    - Inline small files
    - Reference large files
 
 6. **Add Cross-Project Messaging**
-   - `@relay:Bob@other-project message`
+   - `->relay:Bob@other-project message`
    - Contact request system
    - Product grouping
 
@@ -321,7 +321,7 @@
    - Contact policies
 
 10. **Add Workflow Macros**
-    - `@relay:macro:start-session`
+    - `->relay:macro:start-session`
     - Bundle common patterns
     - Reduce boilerplate
 
@@ -341,7 +341,7 @@ Consider a **hybrid architecture** that combines the best of both:
                              │
 ┌────────────────────────────▼────────────────────────────────┐
 │               PTY Wrapper (fast path)                       │
-│  ├─ Pattern Detection (@relay:)                             │
+│  ├─ Pattern Detection (->relay:)                             │
 │  ├─ Message Injection                                       │
 │  └─ Direct daemon IPC (<5ms)                                │
 └────────────────────────────┬────────────────────────────────┘
diff --git a/examples/.env.example b/examples/.env.example
new file mode 100644
index 000000000..d7d13a08c
--- /dev/null
+++ b/examples/.env.example
@@ -0,0 +1,42 @@
+# Agent Relay Configuration
+# Copy this file to .env in your project root
+
+# ============================================
+# Data Storage
+# ============================================
+
+# Base directory for all agent-relay data
+# Default: ~/.agent-relay (or XDG_DATA_HOME/agent-relay)
+# AGENT_RELAY_DATA_DIR=/path/to/data
+
+# Storage backend type (sqlite, memory)
+# Default: sqlite
+# AGENT_RELAY_STORAGE_TYPE=sqlite
+
+# Custom SQLite database path
+# Default: <data_dir>/messages.sqlite
+# AGENT_RELAY_STORAGE_PATH=/path/to/messages.sqlite
+
+# SQLite driver preference (better-sqlite3, node)
+# Default: better-sqlite3 (falls back to node:sqlite if unavailable)
+# AGENT_RELAY_SQLITE_DRIVER=better-sqlite3
+
+# ============================================
+# Dashboard
+# ============================================
+
+# Web dashboard port
+# Default: 3888
+# AGENT_RELAY_DASHBOARD_PORT=3888
+
+# ============================================
+# Agent Identity
+# ============================================
+
+# Default agent name (used by hooks)
+# If not set, a random name is generated
+# AGENT_RELAY_NAME=MyAgent
+
+# Custom inbox directory for file-based messaging
+# Default: <data_dir>/inbox
+# AGENT_RELAY_INBOX_DIR=/path/to/inbox
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 000000000..3287b24fa
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,71 @@
+# Agent Relay Configuration Examples
+
+This folder contains examples for configuring agent-relay in different environments.
+
+## Configuration Files
+
+| File | Description |
+|------|-------------|
+| `.env.example` | Environment variables for dotenv configuration |
+| `cli-usage.sh` | CLI command examples and options |
+| `programmatic-usage.ts` | Using agent-relay as a Node.js library |
+| `docker-compose.yml` | Docker Compose setup for containerized deployment |
+| `agent-relay.service` | Systemd service file for Linux servers |
+| `team-config.json` | Team configuration with multiple agents |
+
+## Usage Examples
+
+| Directory | Description |
+|-----------|-------------|
+| `basic-chat/` | Simple two-agent chat example |
+| `collaborative-task/` | Multi-agent collaboration workflow |
+
+## Quick Start
+
+### Environment Variables
+
+Copy `.env.example` to your project root as `.env`:
+
+```bash
+cp examples/.env.example .env
+```
+
+Edit the values as needed. Agent-relay uses dotenv to load these automatically.
+
+### CLI Configuration
+
+All configuration can also be passed via CLI flags:
+
+```bash
+# Custom port and agent name
+agent-relay up --port 4000
+agent-relay -n MyAgent claude
+```
+
+### Programmatic Configuration
+
+```typescript
+import { Daemon, getProjectPaths } from 'agent-relay';
+
+const paths = getProjectPaths();
+const daemon = new Daemon({
+  socketPath: paths.socketPath,
+  storagePath: paths.dbPath,
+});
+```
+
+## Configuration Priority
+
+1. CLI flags (highest priority)
+2. Environment variables
+3. Default values (lowest priority)
+
+## Multi-Project Setup
+
+Agent-relay automatically isolates data per project based on the project root directory. Each project gets its own:
+
+- SQLite database
+- Unix socket
+- Message history
+
+Projects are identified by a hash of their root path (detected via `.git`, `package.json`, etc.).
diff --git a/examples/agent-relay.service b/examples/agent-relay.service
new file mode 100644
index 000000000..cc8cfd2b4
--- /dev/null
+++ b/examples/agent-relay.service
@@ -0,0 +1,43 @@
+# Systemd service file for agent-relay daemon
+#
+# Installation:
+#   1. Copy this file to /etc/systemd/system/agent-relay.service
+#   2. Edit the paths and user as needed
+#   3. Run: sudo systemctl daemon-reload
+#   4. Run: sudo systemctl enable agent-relay
+#   5. Run: sudo systemctl start agent-relay
+
+[Unit]
+Description=Agent Relay Daemon
+After=network.target
+
+[Service]
+Type=simple
+User=your-username
+Group=your-username
+
+# Working directory (your project root)
+WorkingDirectory=/path/to/your/project
+
+# Environment configuration
+Environment=NODE_ENV=production
+Environment=AGENT_RELAY_DATA_DIR=/var/lib/agent-relay
+Environment=AGENT_RELAY_DASHBOARD_PORT=3888
+
+# Start the daemon
+ExecStart=/usr/bin/npx agent-relay up --port 3888
+
+# Graceful shutdown
+ExecStop=/usr/bin/npx agent-relay down
+
+# Restart on failure
+Restart=on-failure
+RestartSec=5
+
+# Logging
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=agent-relay
+
+[Install]
+WantedBy=multi-user.target
diff --git a/examples/basic-chat/README.md b/examples/basic-chat/README.md
index 23d4411aa..21024b2ad 100644
--- a/examples/basic-chat/README.md
+++ b/examples/basic-chat/README.md
@@ -23,7 +23,7 @@ npx agent-relay wrap -n Alice "claude"
 ```
 
 Once Claude starts, you can tell it:
-> "Your name is Alice. You're chatting with Bob via agent-relay. Say hello to Bob by typing: @relay:Bob Hello Bob! I'm Alice."
+> "Your name is Alice. You're chatting with Bob via agent-relay. Say hello to Bob by typing: ->relay:Bob Hello Bob! I'm Alice."
 
 ### Terminal 3: Agent Bob
 
@@ -37,13 +37,13 @@ Once Claude starts, you can tell it:
 ## How It Works
 
 1. Each agent is wrapped with `agent-relay wrap`, which:
-   - Intercepts terminal output looking for `@relay:` patterns
+   - Intercepts terminal output looking for `->relay:` patterns
    - Sends matched messages through the daemon to other agents
    - Injects received messages into the agent's terminal
 
 2. Messages use the inline format:
    ```
-   @relay:RecipientName Your message here
+   ->relay:RecipientName Your message here
    ```
 
 3. Received messages appear as:
@@ -71,6 +71,6 @@ agent-relay inbox-write -t Alice -f Bob -m "Hi Alice!" -d /tmp/chat
 
 ## Tips
 
-- Use `@relay:*` to broadcast to all connected agents
-- Use `\@relay:` to output literal text without triggering the relay
+- Use `->relay:*` to broadcast to all connected agents
+- Use `\->relay:` to output literal text without triggering the relay
 - Check daemon status with `npx agent-relay status`
diff --git a/examples/cli-usage.sh b/examples/cli-usage.sh
new file mode 100644
index 000000000..03e0c97d0
--- /dev/null
+++ b/examples/cli-usage.sh
@@ -0,0 +1,77 @@
+#!/bin/bash
+# Agent Relay CLI Usage Examples
+# These are example commands - don't run this file directly
+
+# ============================================
+# Starting the Daemon
+# ============================================
+
+# Start daemon with default settings (port 3888)
+agent-relay up
+
+# Start daemon on custom port
+agent-relay up --port 4000
+
+# Start daemon without web dashboard
+agent-relay up --no-dashboard
+
+# Check if daemon is running
+agent-relay status
+
+# Stop the daemon
+agent-relay down
+
+# ============================================
+# Running Agents
+# ============================================
+
+# Wrap any command with agent-relay
+agent-relay claude
+
+# Specify a custom agent name
+agent-relay -n Alice claude
+
+# Wrap with quiet mode (less output)
+agent-relay -q -n Bob claude
+
+# Custom relay prefix (default: ->relay:)
+agent-relay --prefix ">>msg:" -n Charlie claude
+
+# ============================================
+# Message Management
+# ============================================
+
+# List connected agents
+agent-relay agents
+
+# Show active agents (alias)
+agent-relay who
+
+# Read a truncated message by ID
+agent-relay read abc12345
+
+# View message history
+agent-relay history
+
+# View history with filters
+agent-relay history --since 1h        # Last hour
+agent-relay history --since 30m       # Last 30 minutes
+agent-relay history --limit 50        # Last 50 messages
+agent-relay history --from Alice      # Messages from Alice
+agent-relay history --to Bob          # Messages to Bob
+
+# ============================================
+# Multiple Projects
+# ============================================
+
+# Each project gets isolated data based on project root
+# Just run agent-relay from different project directories
+
+cd /path/to/project-a
+agent-relay up                        # Uses ~/.agent-relay/<hash-of-project-a>/
+
+cd /path/to/project-b
+agent-relay up                        # Uses ~/.agent-relay/<hash-of-project-b>/
+
+# List all known projects
+agent-relay projects
diff --git a/examples/collaborative-task/README.md b/examples/collaborative-task/README.md
index 9199741c9..0dc712383 100644
--- a/examples/collaborative-task/README.md
+++ b/examples/collaborative-task/README.md
@@ -27,7 +27,7 @@ npx agent-relay wrap -n Architect "claude"
 ```
 
 Tell the agent:
-> "You are the Architect. Your job is to design a solution for adding user authentication. Once you have a plan, message Developer with the design using @relay:Developer"
+> "You are the Architect. Your job is to design a solution for adding user authentication. Once you have a plan, message Developer with the design using ->relay:Developer"
 
 ### Terminal 3: Developer
 ```bash
@@ -74,21 +74,21 @@ Agents use structured communication:
 
 ```bash
 # Architect assigns task
-@relay:Developer TASK: Implement user registration endpoint.
+->relay:Developer TASK: Implement user registration endpoint.
 Requirements: POST /api/register, validate email, hash password, return JWT.
 
 # Developer requests review
-@relay:Reviewer REVIEW REQUEST: Please review src/api/register.ts
+->relay:Reviewer REVIEW REQUEST: Please review src/api/register.ts
 
 # Reviewer provides feedback
-@relay:Developer FEEDBACK: Line 23: Use bcrypt instead of md5 for password hashing.
+->relay:Developer FEEDBACK: Line 23: Use bcrypt instead of md5 for password hashing.
 
 # Developer notifies completion
-@relay:Architect DONE: Registration endpoint implemented and reviewed.
+->relay:Architect DONE: Registration endpoint implemented and reviewed.
 ```
 
 ## Tips
 
 - Use clear prefixes (TASK:, REVIEW:, FEEDBACK:, DONE:) for structured communication
-- Broadcast status updates with `@relay:*`
+- Broadcast status updates with `->relay:*`
 - Keep messages concise - agents can read files for details
diff --git a/examples/docker-compose.yml b/examples/docker-compose.yml
new file mode 100644
index 000000000..391e156d3
--- /dev/null
+++ b/examples/docker-compose.yml
@@ -0,0 +1,42 @@
+# Docker Compose example for agent-relay
+# Run with: docker-compose up
+
+version: '3.8'
+
+services:
+  relay-daemon:
+    image: node:20-slim
+    working_dir: /app
+    volumes:
+      - ..:/app
+      - relay-data:/data
+    environment:
+      - AGENT_RELAY_DATA_DIR=/data
+      - AGENT_RELAY_DASHBOARD_PORT=3888
+    ports:
+      - "3888:3888"
+    command: >
+      sh -c "npm install && npm run build && node dist/cli/index.js up --port 3888"
+    healthcheck:
+      test: ["CMD", "node", "-e", "require('net').connect(3888).on('error', () => process.exit(1))"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+  # Example agent container
+  agent-alice:
+    image: node:20-slim
+    working_dir: /app
+    volumes:
+      - ..:/app
+      - relay-data:/data
+    environment:
+      - AGENT_RELAY_DATA_DIR=/data
+    depends_on:
+      relay-daemon:
+        condition: service_healthy
+    command: >
+      sh -c "node dist/cli/index.js -n Alice echo 'Hello from Alice'"
+
+volumes:
+  relay-data:
diff --git a/examples/programmatic-usage.ts b/examples/programmatic-usage.ts
new file mode 100644
index 000000000..d75e78ab6
--- /dev/null
+++ b/examples/programmatic-usage.ts
@@ -0,0 +1,126 @@
+/**
+ * Programmatic Usage Examples
+ *
+ * These examples show how to use agent-relay as a library
+ * in your own Node.js/TypeScript applications.
+ */
+
+import { Daemon } from 'agent-relay';
+import { RelayClient } from 'agent-relay';
+import { TmuxWrapper } from 'agent-relay';
+import { getProjectPaths, ensureProjectDir } from 'agent-relay';
+
+// ============================================
+// Example 1: Start a daemon programmatically
+// ============================================
+
+async function startDaemon() {
+  const paths = ensureProjectDir();
+
+  const daemon = new Daemon({
+    socketPath: paths.socketPath,
+    storagePath: paths.dbPath,
+  });
+
+  await daemon.start();
+  console.log(`Daemon running on ${paths.socketPath}`);
+
+  // Graceful shutdown
+  process.on('SIGINT', async () => {
+    await daemon.stop();
+    process.exit(0);
+  });
+}
+
+// ============================================
+// Example 2: Connect as a client
+// ============================================
+
+async function connectAsClient() {
+  const paths = getProjectPaths();
+
+  const client = new RelayClient({
+    name: 'MyAgent',
+    socketPath: paths.socketPath,
+  });
+
+  // Handle incoming messages
+  client.on('message', (msg) => {
+    console.log(`Received from ${msg.from}: ${msg.body}`);
+  });
+
+  await client.connect();
+
+  // Send a message
+  await client.send({
+    to: 'OtherAgent',
+    body: 'Hello from MyAgent!',
+  });
+
+  // Broadcast to all
+  await client.broadcast('Hello everyone!');
+}
+
+// ============================================
+// Example 3: Wrap a command with TmuxWrapper
+// ============================================
+
+async function wrapCommand() {
+  const paths = getProjectPaths();
+
+  const wrapper = new TmuxWrapper({
+    name: 'Claude',
+    command: 'claude',
+    args: [],
+    socketPath: paths.socketPath,
+    debug: false,
+    useInbox: true,
+    inboxDir: paths.dataDir,
+  });
+
+  process.on('SIGINT', () => {
+    wrapper.stop();
+    process.exit(0);
+  });
+
+  await wrapper.start();
+}
+
+// ============================================
+// Example 4: Custom project paths
+// ============================================
+
+function customPaths() {
+  // Get paths for current directory
+  const currentPaths = getProjectPaths();
+  console.log('Current project:', currentPaths);
+
+  // Get paths for a specific project root
+  const customPaths = getProjectPaths('/path/to/my/project');
+  console.log('Custom project:', customPaths);
+
+  // ProjectPaths structure:
+  // {
+  //   dataDir: string;      // Root directory for project data
+  //   teamDir: string;      // Team data directory
+  //   dbPath: string;       // SQLite database path
+  //   socketPath: string;   // Unix socket path
+  //   projectRoot: string;  // The project root used
+  //   projectId: string;    // Short hash identifier
+  // }
+}
+
+// ============================================
+// Example 5: Environment-based configuration
+// ============================================
+
+function envConfig() {
+  // Set environment variables before importing agent-relay
+  process.env.AGENT_RELAY_DATA_DIR = '/custom/data/dir';
+  process.env.AGENT_RELAY_DASHBOARD_PORT = '4000';
+  process.env.AGENT_RELAY_SQLITE_DRIVER = 'node';
+
+  // Now paths will use the custom data directory
+  const paths = getProjectPaths();
+  console.log(paths.dataDir); // /custom/data/dir/<project-hash>
+}
diff --git a/package-lock.json b/package-lock.json
index b723be462..132d1819a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,13 @@
 {
   "name": "agent-relay",
-  "version": "0.1.0",
+  "version": "1.0.8",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "agent-relay",
-      "version": "0.1.0",
+      "version": "1.0.8",
+      "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
         "better-sqlite3": "^9.4.3",
@@ -30,7 +31,9 @@
         "@typescript-eslint/eslint-plugin": "^8.18.2",
         "@typescript-eslint/parser": "^8.18.2",
         "@vitest/coverage-v8": "^2.1.8",
+        "esbuild": "^0.24.0",
         "eslint": "^8.57.1",
+        "jsdom": "^25.0.1",
         "typescript": "^5.7.2",
         "vitest": "^2.1.8"
       },
@@ -52,6 +55,19 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-3.2.0.tgz",
+      "integrity": "sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw==",
+      "dev": true,
+      "dependencies": {
+        "@csstools/css-calc": "^2.1.3",
+        "@csstools/css-color-parser": "^3.0.9",
+        "@csstools/css-parser-algorithms": "^3.0.4",
+        "@csstools/css-tokenizer": "^3.0.3",
+        "lru-cache": "^10.4.3"
+      }
+    },
     "node_modules/@babel/helper-string-parser": {
       "version": "7.27.1",
       "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
@@ -109,10 +125,120 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@csstools/color-helpers": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-5.1.0.tgz",
+      "integrity": "sha512-S11EXWJyy0Mz5SYvRmY8nJYTFFd1LCNV+7cXyAgQtOOuzb4EsgfqDufL+9esx72/eLhsRdGZwaldu/h+E4t4BA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-2.1.4.tgz",
+      "integrity": "sha512-3N8oaj+0juUw/1H3YwmDDJXCgTB1gKU6Hc/bB502u9zR0q2vd786XJH9QfrKIEgFlZmhZiq6epXl4rHqhzsIgQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^3.0.5",
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-3.1.0.tgz",
+      "integrity": "sha512-nbtKwh3a6xNVIp/VRuXV64yTKnb1IjTAEEh3irzS+HkKjAOYLTGNb9pmVNntZ8iVBHcWDA2Dof0QtPgFI1BaTA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "dependencies": {
+        "@csstools/color-helpers": "^5.1.0",
+        "@csstools/css-calc": "^2.1.4"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^3.0.5",
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "3.0.5",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-3.0.5.tgz",
+      "integrity": "sha512-DaDeUkXZKjdGhgYaHNJTV9pV7Y9B3b644jCLs9Upc3VeNGg6LWARAT6O+Q+/COo+2gg/bM5rhpMAtf70WqfBdQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-3.0.4.tgz",
+      "integrity": "sha512-Vd/9EVDiu6PPJt9yAh6roZP6El1xHrdvIVGjyBsHR0RYwNHgL7FJPyIIW4fANJNG6FtyZfvlRPpFI4ZM/lubvw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@esbuild/aix-ppc64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz",
-      "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.24.2.tgz",
+      "integrity": "sha512-thpVCb/rhxE/BnMLQ7GReQLLN8q9qbHmI55F4489/ByVg2aQaQ6kbcLb6FHkocZzQhxc4gx0sCk0tJkKBFzDhA==",
       "cpu": [
         "ppc64"
       ],
@@ -122,13 +248,13 @@
         "aix"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/android-arm": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz",
-      "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.24.2.tgz",
+      "integrity": "sha512-tmwl4hJkCfNHwFB3nBa8z1Uy3ypZpxqxfTQOcHX+xRByyYgunVbZ9MzUUfb0RxaHIMnbHagwAxuTL+tnNM+1/Q==",
       "cpu": [
         "arm"
       ],
@@ -138,13 +264,13 @@
         "android"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/android-arm64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz",
-      "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.24.2.tgz",
+      "integrity": "sha512-cNLgeqCqV8WxfcTIOeL4OAtSmL8JjcN6m09XIgro1Wi7cF4t/THaWEa7eL5CMoMBdjoHOTh/vwTO/o2TRXIyzg==",
       "cpu": [
         "arm64"
       ],
@@ -154,13 +280,13 @@
         "android"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/android-x64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz",
-      "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.24.2.tgz",
+      "integrity": "sha512-B6Q0YQDqMx9D7rvIcsXfmJfvUYLoP722bgfBlO5cGvNVb5V/+Y7nhBE3mHV9OpxBf4eAS2S68KZztiPaWq4XYw==",
       "cpu": [
         "x64"
       ],
@@ -170,13 +296,13 @@
         "android"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/darwin-arm64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz",
-      "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.24.2.tgz",
+      "integrity": "sha512-kj3AnYWc+CekmZnS5IPu9D+HWtUI49hbnyqk0FLEJDbzCIQt7hg7ucF1SQAilhtYpIujfaHr6O0UHlzzSPdOeA==",
       "cpu": [
         "arm64"
       ],
@@ -186,13 +312,13 @@
         "darwin"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/darwin-x64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz",
-      "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.24.2.tgz",
+      "integrity": "sha512-WeSrmwwHaPkNR5H3yYfowhZcbriGqooyu3zI/3GGpF8AyUdsrrP0X6KumITGA9WOyiJavnGZUwPGvxvwfWPHIA==",
       "cpu": [
         "x64"
       ],
@@ -202,13 +328,13 @@
         "darwin"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/freebsd-arm64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz",
-      "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.24.2.tgz",
+      "integrity": "sha512-UN8HXjtJ0k/Mj6a9+5u6+2eZ2ERD7Edt1Q9IZiB5UZAIdPnVKDoG7mdTVGhHJIeEml60JteamR3qhsr1r8gXvg==",
       "cpu": [
         "arm64"
       ],
@@ -218,13 +344,13 @@
         "freebsd"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/freebsd-x64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz",
-      "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.24.2.tgz",
+      "integrity": "sha512-TvW7wE/89PYW+IevEJXZ5sF6gJRDY/14hyIGFXdIucxCsbRmLUcjseQu1SyTko+2idmCw94TgyaEZi9HUSOe3Q==",
       "cpu": [
         "x64"
       ],
@@ -234,13 +360,13 @@
         "freebsd"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/linux-arm": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz",
-      "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.24.2.tgz",
+      "integrity": "sha512-n0WRM/gWIdU29J57hJyUdIsk0WarGd6To0s+Y+LwvlC55wt+GT/OgkwoXCXvIue1i1sSNWblHEig00GBWiJgfA==",
       "cpu": [
         "arm"
       ],
@@ -250,13 +376,13 @@
         "linux"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/linux-arm64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz",
-      "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.24.2.tgz",
+      "integrity": "sha512-7HnAD6074BW43YvvUmE/35Id9/NB7BeX5EoNkK9obndmZBUk8xmJJeU7DwmUeN7tkysslb2eSl6CTrYz6oEMQg==",
       "cpu": [
         "arm64"
       ],
@@ -266,13 +392,13 @@
         "linux"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/linux-ia32": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz",
-      "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.24.2.tgz",
+      "integrity": "sha512-sfv0tGPQhcZOgTKO3oBE9xpHuUqguHvSo4jl+wjnKwFpapx+vUDcawbwPNuBIAYdRAvIDBfZVvXprIj3HA+Ugw==",
       "cpu": [
         "ia32"
       ],
@@ -282,13 +408,13 @@
         "linux"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/linux-loong64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz",
-      "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.24.2.tgz",
+      "integrity": "sha512-CN9AZr8kEndGooS35ntToZLTQLHEjtVB5n7dl8ZcTZMonJ7CCfStrYhrzF97eAecqVbVJ7APOEe18RPI4KLhwQ==",
       "cpu": [
         "loong64"
       ],
@@ -298,13 +424,13 @@
         "linux"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/linux-mips64el": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz",
-      "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.24.2.tgz",
+      "integrity": "sha512-iMkk7qr/wl3exJATwkISxI7kTcmHKE+BlymIAbHO8xanq/TjHaaVThFF6ipWzPHryoFsesNQJPE/3wFJw4+huw==",
       "cpu": [
         "mips64el"
       ],
@@ -314,13 +440,13 @@
         "linux"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/linux-ppc64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz",
-      "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.24.2.tgz",
+      "integrity": "sha512-shsVrgCZ57Vr2L8mm39kO5PPIb+843FStGt7sGGoqiiWYconSxwTiuswC1VJZLCjNiMLAMh34jg4VSEQb+iEbw==",
       "cpu": [
         "ppc64"
       ],
@@ -330,13 +456,13 @@
         "linux"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/linux-riscv64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz",
-      "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.24.2.tgz",
+      "integrity": "sha512-4eSFWnU9Hhd68fW16GD0TINewo1L6dRrB+oLNNbYyMUAeOD2yCK5KXGK1GH4qD/kT+bTEXjsyTCiJGHPZ3eM9Q==",
       "cpu": [
         "riscv64"
       ],
@@ -346,13 +472,13 @@
         "linux"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/linux-s390x": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz",
-      "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.24.2.tgz",
+      "integrity": "sha512-S0Bh0A53b0YHL2XEXC20bHLuGMOhFDO6GN4b3YjRLK//Ep3ql3erpNcPlEFed93hsQAjAQDNsvcK+hV90FubSw==",
       "cpu": [
         "s390x"
       ],
@@ -362,13 +488,13 @@
         "linux"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/linux-x64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz",
-      "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.24.2.tgz",
+      "integrity": "sha512-8Qi4nQcCTbLnK9WoMjdC9NiTG6/E38RNICU6sUNqK0QFxCYgoARqVqxdFmWkdonVsvGqWhmm7MO0jyTqLqwj0Q==",
       "cpu": [
         "x64"
       ],
@@ -378,13 +504,29 @@
         "linux"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.24.2.tgz",
+      "integrity": "sha512-wuLK/VztRRpMt9zyHSazyCVdCXlpHkKm34WUyinD2lzK07FAHTq0KQvZZlXikNWkDGoT6x3TD51jKQ7gMVpopw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/netbsd-x64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
-      "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.24.2.tgz",
+      "integrity": "sha512-VefFaQUc4FMmJuAxmIHgUmfNiLXY438XrL4GDNV1Y1H/RW3qow68xTwjZKfj/+Plp9NANmzbH5R40Meudu8mmw==",
       "cpu": [
         "x64"
       ],
@@ -394,13 +536,29 @@
         "netbsd"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.24.2.tgz",
+      "integrity": "sha512-YQbi46SBct6iKnszhSvdluqDmxCJA+Pu280Av9WICNwQmMxV7nLRHZfjQzwbPs3jeWnuAhE9Jy0NrnJ12Oz+0A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/openbsd-x64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
-      "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.24.2.tgz",
+      "integrity": "sha512-+iDS6zpNM6EnJyWv0bMGLWSWeXGN/HTaF/LXHXHwejGsVi+ooqDfMCCTerNFxEkM3wYVcExkeGXNqshc9iMaOA==",
       "cpu": [
         "x64"
       ],
@@ -410,13 +568,13 @@
         "openbsd"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/sunos-x64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
-      "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.24.2.tgz",
+      "integrity": "sha512-hTdsW27jcktEvpwNHJU4ZwWFGkz2zRJUz8pvddmXPtXDzVKTTINmlmga3ZzwcuMpUvLw7JkLy9QLKyGpD2Yxig==",
       "cpu": [
         "x64"
       ],
@@ -426,13 +584,13 @@
         "sunos"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/win32-arm64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz",
-      "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.24.2.tgz",
+      "integrity": "sha512-LihEQ2BBKVFLOC9ZItT9iFprsE9tqjDjnbulhHoFxYQtQfai7qfluVODIYxt1PgdoyQkz23+01rzwNwYfutxUQ==",
       "cpu": [
         "arm64"
       ],
@@ -442,13 +600,13 @@
         "win32"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/win32-ia32": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz",
-      "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.24.2.tgz",
+      "integrity": "sha512-q+iGUwfs8tncmFC9pcnD5IvRHAzmbwQ3GPS5/ceCyHdjXubwQWI12MKWSNSMYLJMq23/IUCvJMS76PDqXe1fxA==",
       "cpu": [
         "ia32"
       ],
@@ -458,13 +616,13 @@
         "win32"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@esbuild/win32-x64": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz",
-      "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.24.2.tgz",
+      "integrity": "sha512-7VTgWzgMGvup6aSqDPLiW5zHaxYJGTO4OokMjIlrCtf+VpEL+cXKtCvg723iguPYI5oaUNdS+/V7OU2gvXVWEg==",
       "cpu": [
         "x64"
       ],
@@ -474,7 +632,7 @@
         "win32"
       ],
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/@eslint-community/eslint-utils": {
@@ -1610,6 +1768,15 @@
         "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0"
       }
     },
+    "node_modules/agent-base": {
+      "version": "7.1.4",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
+      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
+      "dev": true,
+      "engines": {
+        "node": ">= 14"
+      }
+    },
     "node_modules/ajv": {
       "version": "6.12.6",
       "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz",
@@ -1669,6 +1836,12 @@
         "node": ">=12"
       }
     },
+    "node_modules/asynckit": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
+      "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==",
+      "dev": true
+    },
     "node_modules/balanced-match": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
@@ -1925,6 +2098,18 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/combined-stream": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
+      "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==",
+      "dev": true,
+      "dependencies": {
+        "delayed-stream": "~1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
     "node_modules/commander": {
       "version": "12.1.0",
       "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
@@ -1995,6 +2180,38 @@
         "node": ">= 8"
       }
     },
+    "node_modules/cssstyle": {
+      "version": "4.6.0",
+      "resolved": "https://registry.npmjs.org/cssstyle/-/cssstyle-4.6.0.tgz",
+      "integrity": "sha512-2z+rWdzbbSZv6/rhtvzvqeZQHrBaqgogqt85sqFNbabZOuFbCVFb8kPeEtZjiKkbrm395irpNKiYeFeLiQnFPg==",
+      "dev": true,
+      "dependencies": {
+        "@asamuzakjp/css-color": "^3.2.0",
+        "rrweb-cssom": "^0.8.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/cssstyle/node_modules/rrweb-cssom": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/rrweb-cssom/-/rrweb-cssom-0.8.0.tgz",
+      "integrity": "sha512-guoltQEx+9aMf2gDZ0s62EcV8lsXR+0w8915TC3ITdn2YueuNjdAYh/levpU9nFaoChh9RUS5ZdQMrKfVEN9tw==",
+      "dev": true
+    },
+    "node_modules/data-urls": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-5.0.0.tgz",
+      "integrity": "sha512-ZYP5VBHshaDAiVZxjbRVcFJpc+4xGgT0bK3vzy1HLN8jTO975HEbuYzZJcHoQEY5K1a0z8YayJkyVETa08eNTg==",
+      "dev": true,
+      "dependencies": {
+        "whatwg-mimetype": "^4.0.0",
+        "whatwg-url": "^14.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/debug": {
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@@ -2011,7 +2228,13 @@
         }
       }
     },
-    "node_modules/decompress-response": {
+    "node_modules/decimal.js": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
+      "dev": true
+    },
+    "node_modules/decompress-response": {
       "version": "6.0.0",
       "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz",
       "integrity": "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==",
@@ -2051,6 +2274,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/delayed-stream": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
+      "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==",
+      "dev": true,
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
     "node_modules/depd": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
@@ -2146,6 +2378,18 @@
         "once": "^1.4.0"
       }
     },
+    "node_modules/entities": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
+      "integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==",
+      "dev": true,
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/es-define-property": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
@@ -2182,42 +2426,59 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/es-set-tostringtag": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz",
+      "integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==",
+      "dev": true,
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "get-intrinsic": "^1.2.6",
+        "has-tostringtag": "^1.0.2",
+        "hasown": "^2.0.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/esbuild": {
-      "version": "0.21.5",
-      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz",
-      "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==",
+      "version": "0.24.2",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.24.2.tgz",
+      "integrity": "sha512-+9egpBW8I3CD5XPe0n6BfT5fxLzxrlDzqydF3aviG+9ni1lDC/OvMHcxqEFV0+LANZG5R1bFMWfUrjVsdwxJvA==",
       "dev": true,
       "hasInstallScript": true,
       "bin": {
         "esbuild": "bin/esbuild"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       },
       "optionalDependencies": {
-        "@esbuild/aix-ppc64": "0.21.5",
-        "@esbuild/android-arm": "0.21.5",
-        "@esbuild/android-arm64": "0.21.5",
-        "@esbuild/android-x64": "0.21.5",
-        "@esbuild/darwin-arm64": "0.21.5",
-        "@esbuild/darwin-x64": "0.21.5",
-        "@esbuild/freebsd-arm64": "0.21.5",
-        "@esbuild/freebsd-x64": "0.21.5",
-        "@esbuild/linux-arm": "0.21.5",
-        "@esbuild/linux-arm64": "0.21.5",
-        "@esbuild/linux-ia32": "0.21.5",
-        "@esbuild/linux-loong64": "0.21.5",
-        "@esbuild/linux-mips64el": "0.21.5",
-        "@esbuild/linux-ppc64": "0.21.5",
-        "@esbuild/linux-riscv64": "0.21.5",
-        "@esbuild/linux-s390x": "0.21.5",
-        "@esbuild/linux-x64": "0.21.5",
-        "@esbuild/netbsd-x64": "0.21.5",
-        "@esbuild/openbsd-x64": "0.21.5",
-        "@esbuild/sunos-x64": "0.21.5",
-        "@esbuild/win32-arm64": "0.21.5",
-        "@esbuild/win32-ia32": "0.21.5",
-        "@esbuild/win32-x64": "0.21.5"
+        "@esbuild/aix-ppc64": "0.24.2",
+        "@esbuild/android-arm": "0.24.2",
+        "@esbuild/android-arm64": "0.24.2",
+        "@esbuild/android-x64": "0.24.2",
+        "@esbuild/darwin-arm64": "0.24.2",
+        "@esbuild/darwin-x64": "0.24.2",
+        "@esbuild/freebsd-arm64": "0.24.2",
+        "@esbuild/freebsd-x64": "0.24.2",
+        "@esbuild/linux-arm": "0.24.2",
+        "@esbuild/linux-arm64": "0.24.2",
+        "@esbuild/linux-ia32": "0.24.2",
+        "@esbuild/linux-loong64": "0.24.2",
+        "@esbuild/linux-mips64el": "0.24.2",
+        "@esbuild/linux-ppc64": "0.24.2",
+        "@esbuild/linux-riscv64": "0.24.2",
+        "@esbuild/linux-s390x": "0.24.2",
+        "@esbuild/linux-x64": "0.24.2",
+        "@esbuild/netbsd-arm64": "0.24.2",
+        "@esbuild/netbsd-x64": "0.24.2",
+        "@esbuild/openbsd-arm64": "0.24.2",
+        "@esbuild/openbsd-x64": "0.24.2",
+        "@esbuild/sunos-x64": "0.24.2",
+        "@esbuild/win32-arm64": "0.24.2",
+        "@esbuild/win32-ia32": "0.24.2",
+        "@esbuild/win32-x64": "0.24.2"
       }
     },
     "node_modules/escape-html": {
@@ -2648,6 +2909,43 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/form-data": {
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz",
+      "integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==",
+      "dev": true,
+      "dependencies": {
+        "asynckit": "^0.4.0",
+        "combined-stream": "^1.0.8",
+        "es-set-tostringtag": "^2.1.0",
+        "hasown": "^2.0.2",
+        "mime-types": "^2.1.12"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/form-data/node_modules/mime-db": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
+      "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
+      "dev": true,
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/form-data/node_modules/mime-types": {
+      "version": "2.1.35",
+      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
+      "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
+      "dev": true,
+      "dependencies": {
+        "mime-db": "1.52.0"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -2861,6 +3159,21 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/has-tostringtag": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz",
+      "integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==",
+      "dev": true,
+      "dependencies": {
+        "has-symbols": "^1.0.3"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
     "node_modules/hasown": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz",
@@ -2873,6 +3186,18 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/html-encoding-sniffer": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-4.0.0.tgz",
+      "integrity": "sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ==",
+      "dev": true,
+      "dependencies": {
+        "whatwg-encoding": "^3.1.1"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/html-escaper": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
@@ -2900,6 +3225,32 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/http-proxy-agent": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
+      "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==",
+      "dev": true,
+      "dependencies": {
+        "agent-base": "^7.1.0",
+        "debug": "^4.3.4"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/https-proxy-agent": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
+      "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
+      "dev": true,
+      "dependencies": {
+        "agent-base": "^7.1.2",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
     "node_modules/iconv-lite": {
       "version": "0.7.1",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.1.tgz",
@@ -3049,6 +3400,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/is-potential-custom-element-name": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
+      "dev": true
+    },
     "node_modules/is-promise": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
@@ -3145,6 +3502,46 @@
         "js-yaml": "bin/js-yaml.js"
       }
     },
+    "node_modules/jsdom": {
+      "version": "25.0.1",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-25.0.1.tgz",
+      "integrity": "sha512-8i7LzZj7BF8uplX+ZyOlIz86V6TAsSs+np6m1kpW9u0JWi4z/1t+FzcK1aek+ybTnAC4KhBL4uXCNT0wcUIeCw==",
+      "dev": true,
+      "dependencies": {
+        "cssstyle": "^4.1.0",
+        "data-urls": "^5.0.0",
+        "decimal.js": "^10.4.3",
+        "form-data": "^4.0.0",
+        "html-encoding-sniffer": "^4.0.0",
+        "http-proxy-agent": "^7.0.2",
+        "https-proxy-agent": "^7.0.5",
+        "is-potential-custom-element-name": "^1.0.1",
+        "nwsapi": "^2.2.12",
+        "parse5": "^7.1.2",
+        "rrweb-cssom": "^0.7.1",
+        "saxes": "^6.0.0",
+        "symbol-tree": "^3.2.4",
+        "tough-cookie": "^5.0.0",
+        "w3c-xmlserializer": "^5.0.0",
+        "webidl-conversions": "^7.0.0",
+        "whatwg-encoding": "^3.1.1",
+        "whatwg-mimetype": "^4.0.0",
+        "whatwg-url": "^14.0.0",
+        "ws": "^8.18.0",
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "canvas": "^2.11.2"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/json-buffer": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz",
@@ -3442,6 +3839,12 @@
         "nan": "^2.17.0"
       }
     },
+    "node_modules/nwsapi": {
+      "version": "2.2.23",
+      "resolved": "https://registry.npmjs.org/nwsapi/-/nwsapi-2.2.23.tgz",
+      "integrity": "sha512-7wfH4sLbt4M0gCDzGE6vzQBo0bfTKjU7Sfpqy/7gs1qBfYz2vEJH6vXcBKpO3+6Yu1telwd0t9HpyOoLEQQbIQ==",
+      "dev": true
+    },
     "node_modules/object-inspect": {
       "version": "1.13.4",
       "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
@@ -3545,6 +3948,18 @@
         "node": ">=6"
       }
     },
+    "node_modules/parse5": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz",
+      "integrity": "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==",
+      "dev": true,
+      "dependencies": {
+        "entities": "^6.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
     "node_modules/parseurl": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
@@ -3948,6 +4363,12 @@
         "node": ">= 18"
       }
     },
+    "node_modules/rrweb-cssom": {
+      "version": "0.7.1",
+      "resolved": "https://registry.npmjs.org/rrweb-cssom/-/rrweb-cssom-0.7.1.tgz",
+      "integrity": "sha512-TrEMa7JGdVm0UThDJSx7ddw5nVm3UJS9o9CCIZ72B1vSyEZoziDqBYP3XIoi/12lKrJR8rE3jeFHMok2F/Mnsg==",
+      "dev": true
+    },
     "node_modules/run-parallel": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz",
@@ -3998,6 +4419,18 @@
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
       "license": "MIT"
     },
+    "node_modules/saxes": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
+      "dev": true,
+      "dependencies": {
+        "xmlchars": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=v12.22.7"
+      }
+    },
     "node_modules/semver": {
       "version": "7.7.3",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz",
@@ -4382,6 +4815,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/symbol-tree": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
+      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
+      "dev": true
+    },
     "node_modules/tar-fs": {
       "version": "2.1.4",
       "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.4.tgz",
@@ -4509,6 +4948,24 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/tldts": {
+      "version": "6.1.86",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-6.1.86.tgz",
+      "integrity": "sha512-WMi/OQ2axVTf/ykqCQgXiIct+mSQDFdH2fkwhPwgEwvJ1kSzZRiinb0zF2Xb8u4+OqPChmyI6MEu4EezNJz+FQ==",
+      "dev": true,
+      "dependencies": {
+        "tldts-core": "^6.1.86"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "6.1.86",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-6.1.86.tgz",
+      "integrity": "sha512-Je6p7pkk+KMzMv2XXKmAE3McmolOQFdxkKw0R8EYNr7sELW46JqnNeTX8ybPiQgvg1ymCoF8LXs5fzFaZvJPTA==",
+      "dev": true
+    },
     "node_modules/toidentifier": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
@@ -4518,6 +4975,30 @@
         "node": ">=0.6"
       }
     },
+    "node_modules/tough-cookie": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-5.1.2.tgz",
+      "integrity": "sha512-FVDYdxtnj0G6Qm/DhNPSb8Ju59ULcup3tuJxkFb5K8Bv2pUXILbf0xZWU8PX8Ov19OXljbUyveOFwRMwkXzO+A==",
+      "dev": true,
+      "dependencies": {
+        "tldts": "^6.1.32"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-5.1.1.tgz",
+      "integrity": "sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw==",
+      "dev": true,
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/ts-api-utils": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.1.0.tgz",
@@ -4729,85 +5210,558 @@
         "url": "https://opencollective.com/vitest"
       }
     },
-    "node_modules/vitest": {
-      "version": "2.1.9",
-      "resolved": "https://registry.npmjs.org/vitest/-/vitest-2.1.9.tgz",
-      "integrity": "sha512-MSmPM9REYqDGBI8439mA4mWhV5sKmDlBKWIYbA3lRb2PTHACE0mgKwA8yQ2xq9vxDTuk4iPrECBAEW2aoFXY0Q==",
+    "node_modules/vite/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==",
+      "cpu": [
+        "ppc64"
+      ],
       "dev": true,
-      "dependencies": {
-        "@vitest/expect": "2.1.9",
-        "@vitest/mocker": "2.1.9",
-        "@vitest/pretty-format": "^2.1.9",
-        "@vitest/runner": "2.1.9",
-        "@vitest/snapshot": "2.1.9",
-        "@vitest/spy": "2.1.9",
-        "@vitest/utils": "2.1.9",
-        "chai": "^5.1.2",
-        "debug": "^4.3.7",
-        "expect-type": "^1.1.0",
-        "magic-string": "^0.30.12",
-        "pathe": "^1.1.2",
-        "std-env": "^3.8.0",
-        "tinybench": "^2.9.0",
-        "tinyexec": "^0.3.1",
-        "tinypool": "^1.0.1",
-        "tinyrainbow": "^1.2.0",
-        "vite": "^5.0.0",
-        "vite-node": "2.1.9",
-        "why-is-node-running": "^2.3.0"
-      },
-      "bin": {
-        "vitest": "vitest.mjs"
-      },
+      "optional": true,
+      "os": [
+        "aix"
+      ],
       "engines": {
-        "node": "^18.0.0 || >=20.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/vitest"
-      },
-      "peerDependencies": {
-        "@edge-runtime/vm": "*",
-        "@types/node": "^18.0.0 || >=20.0.0",
-        "@vitest/browser": "2.1.9",
-        "@vitest/ui": "2.1.9",
-        "happy-dom": "*",
-        "jsdom": "*"
-      },
-      "peerDependenciesMeta": {
-        "@edge-runtime/vm": {
-          "optional": true
-        },
-        "@types/node": {
-          "optional": true
-        },
-        "@vitest/browser": {
-          "optional": true
-        },
-        "@vitest/ui": {
-          "optional": true
-        },
-        "happy-dom": {
-          "optional": true
-        },
-        "jsdom": {
-          "optional": true
-        }
+        "node": ">=12"
       }
     },
-    "node_modules/which": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
-      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+    "node_modules/vite/node_modules/@esbuild/android-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz",
+      "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==",
+      "cpu": [
+        "arm"
+      ],
       "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "isexe": "^2.0.0"
-      },
-      "bin": {
-        "node-which": "bin/node-which"
-      },
+      "optional": true,
+      "os": [
+        "android"
+      ],
       "engines": {
-        "node": ">= 8"
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz",
+      "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/android-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz",
+      "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz",
+      "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/darwin-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz",
+      "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz",
+      "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz",
+      "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz",
+      "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz",
+      "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz",
+      "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-loong64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz",
+      "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz",
+      "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz",
+      "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-s390x": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz",
+      "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/linux-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz",
+      "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/sunos-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
+      "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz",
+      "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz",
+      "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/@esbuild/win32-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz",
+      "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite/node_modules/esbuild": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz",
+      "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.21.5",
+        "@esbuild/android-arm": "0.21.5",
+        "@esbuild/android-arm64": "0.21.5",
+        "@esbuild/android-x64": "0.21.5",
+        "@esbuild/darwin-arm64": "0.21.5",
+        "@esbuild/darwin-x64": "0.21.5",
+        "@esbuild/freebsd-arm64": "0.21.5",
+        "@esbuild/freebsd-x64": "0.21.5",
+        "@esbuild/linux-arm": "0.21.5",
+        "@esbuild/linux-arm64": "0.21.5",
+        "@esbuild/linux-ia32": "0.21.5",
+        "@esbuild/linux-loong64": "0.21.5",
+        "@esbuild/linux-mips64el": "0.21.5",
+        "@esbuild/linux-ppc64": "0.21.5",
+        "@esbuild/linux-riscv64": "0.21.5",
+        "@esbuild/linux-s390x": "0.21.5",
+        "@esbuild/linux-x64": "0.21.5",
+        "@esbuild/netbsd-x64": "0.21.5",
+        "@esbuild/openbsd-x64": "0.21.5",
+        "@esbuild/sunos-x64": "0.21.5",
+        "@esbuild/win32-arm64": "0.21.5",
+        "@esbuild/win32-ia32": "0.21.5",
+        "@esbuild/win32-x64": "0.21.5"
+      }
+    },
+    "node_modules/vitest": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-2.1.9.tgz",
+      "integrity": "sha512-MSmPM9REYqDGBI8439mA4mWhV5sKmDlBKWIYbA3lRb2PTHACE0mgKwA8yQ2xq9vxDTuk4iPrECBAEW2aoFXY0Q==",
+      "dev": true,
+      "dependencies": {
+        "@vitest/expect": "2.1.9",
+        "@vitest/mocker": "2.1.9",
+        "@vitest/pretty-format": "^2.1.9",
+        "@vitest/runner": "2.1.9",
+        "@vitest/snapshot": "2.1.9",
+        "@vitest/spy": "2.1.9",
+        "@vitest/utils": "2.1.9",
+        "chai": "^5.1.2",
+        "debug": "^4.3.7",
+        "expect-type": "^1.1.0",
+        "magic-string": "^0.30.12",
+        "pathe": "^1.1.2",
+        "std-env": "^3.8.0",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^0.3.1",
+        "tinypool": "^1.0.1",
+        "tinyrainbow": "^1.2.0",
+        "vite": "^5.0.0",
+        "vite-node": "2.1.9",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@types/node": "^18.0.0 || >=20.0.0",
+        "@vitest/browser": "2.1.9",
+        "@vitest/ui": "2.1.9",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/w3c-xmlserializer": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
+      "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==",
+      "dev": true,
+      "dependencies": {
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/webidl-conversions": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-7.0.0.tgz",
+      "integrity": "sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==",
+      "dev": true,
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/whatwg-encoding": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-3.1.1.tgz",
+      "integrity": "sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==",
+      "dev": true,
+      "dependencies": {
+        "iconv-lite": "0.6.3"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/whatwg-encoding/node_modules/iconv-lite": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "dev": true,
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-4.0.0.tgz",
+      "integrity": "sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==",
+      "dev": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/whatwg-url": {
+      "version": "14.2.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-14.2.0.tgz",
+      "integrity": "sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==",
+      "dev": true,
+      "dependencies": {
+        "tr46": "^5.1.0",
+        "webidl-conversions": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
       }
     },
     "node_modules/why-is-node-running": {
@@ -4964,6 +5918,21 @@
         }
       }
     },
+    "node_modules/xml-name-validator": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
+      "dev": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/xmlchars": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
+      "dev": true
+    },
     "node_modules/yocto-queue": {
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
diff --git a/package.json b/package.json
index fff3dd7c6..58fc328e9 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Real-time agent-to-agent communication system",
   "type": "module",
   "main": "dist/index.js",
@@ -19,9 +19,14 @@
     "access": "public"
   },
   "scripts": {
-    "build": "npm run clean && tsc",
-    "postbuild": "cp -r src/dashboard/public dist/dashboard/",
+    "postinstall": "npm rebuild better-sqlite3",
+    "build": "npm run clean && tsc && npm run build:frontend",
+    "build:frontend": "esbuild src/dashboard/frontend/app.ts --bundle --outfile=src/dashboard/public/js/app.js --format=esm --target=es2022 --minify --sourcemap",
+    "postbuild": "cp -r src/dashboard/public dist/dashboard/ && chmod +x dist/cli/index.js",
     "dev": "tsc -w",
+    "dev:local": "npm run build && npm link && echo '✓ agent-relay linked globally'",
+    "dev:unlink": "npm unlink -g agent-relay && echo '✓ agent-relay unlinked'",
+    "dev:rebuild": "npm run build && echo '✓ Rebuilt (linked version updated)'",
     "start": "node dist/cli/index.js",
     "daemon": "node dist/daemon/server.js",
     "dashboard": "node dist/dashboard/start.js",
@@ -72,7 +77,9 @@
     "@typescript-eslint/eslint-plugin": "^8.18.2",
     "@typescript-eslint/parser": "^8.18.2",
     "@vitest/coverage-v8": "^2.1.8",
+    "esbuild": "^0.24.0",
     "eslint": "^8.57.1",
+    "jsdom": "^25.0.1",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   },
diff --git a/prpm.lock b/prpm.lock
new file mode 100644
index 000000000..3d1e76251
--- /dev/null
+++ b/prpm.lock
@@ -0,0 +1,77 @@
+{
+  "version": "1.0.0",
+  "lockfileVersion": 1,
+  "packages": {
+    "@prpm/creating-claude-hooks-skill#claude": {
+      "version": "1.0.0",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40prpm%2Fcreating-claude-hooks-skill/1.0.0.tar.gz",
+      "integrity": "sha256-2d10ad7a10204009d73b34172a9f54e5ad0858c76581a9f9579ee0e194f94505",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/creating-claude-hooks-skill/SKILL.md"
+    },
+    "@anthropic/frontend-design#agents.md": {
+      "version": "1.0.0",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40anthropic%2Ffrontend-design/1.0.0.tar.gz",
+      "integrity": "sha256-404d3d731beb8feaf0d7fff7fa967538686246cd930da612db753fa76e5fb057",
+      "format": "agents.md",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".openskills/frontend-design/SKILL.md",
+      "progressiveDisclosure": {
+        "mode": "progressive",
+        "resourceDir": ".openskills/frontend-design",
+        "manifestPath": "AGENTS.md",
+        "resourceName": "frontend-design",
+        "resourceType": "skill",
+        "skillsDir": ".openskills/frontend-design",
+        "skillName": "frontend-design",
+        "eager": false
+      }
+    },
+    "@prpm/creating-skills-skill#claude": {
+      "version": "1.0.4",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40prpm%2Fcreating-skills-skill/1.0.4.tar.gz",
+      "integrity": "sha256-845d12bda6e5b37ed3177e2a867f57319327704b2206d58643d8e06cecb64241",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/creating-skills-skill/SKILL.md"
+    },
+    "@prpm/prpm-json-best-practices-skill#claude": {
+      "version": "1.2.0",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40prpm%2Fprpm-json-best-practices-skill/1.2.0.tar.gz",
+      "integrity": "sha256-13f5c9204ef0db4cd37ef2339fa9cc5743de993c73244230760e73612476d826",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/prpm-json-best-practices-skill"
+    },
+    "@prpm/creating-claude-rules-skill#claude": {
+      "version": "1.0.0",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40prpm%2Fcreating-claude-rules-skill/1.0.0.tar.gz",
+      "integrity": "sha256-5d348d29c6e9abe5b1f0328a3868094b47dddc60192fc6b8f0a364797ce62878",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/creating-claude-rules-skill/SKILL.md"
+    },
+    "@prpm/creating-claude-agents-skill#claude": {
+      "version": "1.0.0",
+      "resolved": "https://registry.prpm.dev/api/v1/packages/%40prpm%2Fcreating-claude-agents-skill/1.0.0.tar.gz",
+      "integrity": "sha256-d1aca9da6acab91815edf1012c94936e151b9aad77adf8ab0e7fedad8b6b8fef",
+      "format": "claude",
+      "subtype": "skill",
+      "sourceFormat": "claude",
+      "sourceSubtype": "skill",
+      "installedPath": ".claude/skills/creating-claude-agents-skill/SKILL.md"
+    }
+  },
+  "generated": "2025-12-22T21:13:52.096Z"
+}
\ No newline at end of file
diff --git a/src/bridge/config.test.ts b/src/bridge/config.test.ts
new file mode 100644
index 000000000..64030f79a
--- /dev/null
+++ b/src/bridge/config.test.ts
@@ -0,0 +1,132 @@
+/**
+ * Unit tests for Bridge Configuration
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {
+  resolvePath,
+  getDefaultLeadName,
+  resolveProjects,
+  validateDaemons,
+} from './config.js';
+
+// Mock fs module
+vi.mock('node:fs');
+vi.mock('../utils/project-namespace.js', () => ({
+  getProjectPaths: vi.fn((projectPath: string) => ({
+    projectId: 'test-project-id',
+    socketPath: `/tmp/agent-relay/test-project-id/relay.sock`,
+    dataDir: `/tmp/agent-relay/test-project-id`,
+    teamDir: `/tmp/agent-relay/test-project-id/team`,
+    dbPath: `/tmp/agent-relay/test-project-id/messages.sqlite`,
+    projectRoot: projectPath,
+  })),
+}));
+
+describe('Bridge Config', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('resolvePath', () => {
+    it('expands ~ to home directory', () => {
+      const homedir = os.homedir();
+      const result = resolvePath('~/projects/test');
+      expect(result).toBe(path.join(homedir, 'projects/test'));
+    });
+
+    it('resolves relative paths to absolute', () => {
+      const result = resolvePath('./relative/path');
+      expect(path.isAbsolute(result)).toBe(true);
+    });
+
+    it('keeps absolute paths unchanged', () => {
+      const result = resolvePath('/absolute/path');
+      expect(result).toBe('/absolute/path');
+    });
+  });
+
+  describe('getDefaultLeadName', () => {
+    it('capitalizes directory name', () => {
+      expect(getDefaultLeadName('/path/to/auth-service')).toBe('Auth-service');
+      expect(getDefaultLeadName('/path/to/frontend')).toBe('Frontend');
+      expect(getDefaultLeadName('/path/to/API')).toBe('API');
+    });
+
+    it('handles single-letter directory names', () => {
+      expect(getDefaultLeadName('/path/to/a')).toBe('A');
+    });
+  });
+
+  describe('resolveProjects', () => {
+    it('creates project configs from CLI paths', () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+
+      const projects = resolveProjects(['/path/to/auth', '/path/to/frontend']);
+
+      expect(projects).toHaveLength(2);
+      expect(projects[0]).toMatchObject({
+        path: '/path/to/auth',
+        leadName: 'Auth',
+        cli: 'claude',
+      });
+      expect(projects[1]).toMatchObject({
+        path: '/path/to/frontend',
+        leadName: 'Frontend',
+        cli: 'claude',
+      });
+    });
+
+    it('applies CLI override to all projects', () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+
+      const projects = resolveProjects(['/path/to/auth'], 'codex');
+
+      expect(projects[0].cli).toBe('codex');
+    });
+
+    it('skips non-existent paths', () => {
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+
+      const projects = resolveProjects(['/nonexistent/path']);
+
+      expect(projects).toHaveLength(0);
+    });
+  });
+
+  describe('validateDaemons', () => {
+    it('separates projects with and without running daemons', () => {
+      vi.mocked(fs.existsSync).mockImplementation((p) => {
+        return String(p).includes('auth');
+      });
+
+      const projects = [
+        { path: '/auth', id: 'auth', socketPath: '/tmp/auth/relay.sock', leadName: 'Auth', cli: 'claude' },
+        { path: '/frontend', id: 'frontend', socketPath: '/tmp/frontend/relay.sock', leadName: 'Frontend', cli: 'claude' },
+      ];
+
+      const { valid, missing } = validateDaemons(projects);
+
+      expect(valid).toHaveLength(1);
+      expect(valid[0].id).toBe('auth');
+      expect(missing).toHaveLength(1);
+      expect(missing[0].id).toBe('frontend');
+    });
+
+    it('returns all valid when all daemons running', () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+
+      const projects = [
+        { path: '/auth', id: 'auth', socketPath: '/tmp/auth/relay.sock', leadName: 'Auth', cli: 'claude' },
+      ];
+
+      const { valid, missing } = validateDaemons(projects);
+
+      expect(valid).toHaveLength(1);
+      expect(missing).toHaveLength(0);
+    });
+  });
+});
diff --git a/src/bridge/config.ts b/src/bridge/config.ts
new file mode 100644
index 000000000..a92bc24ca
--- /dev/null
+++ b/src/bridge/config.ts
@@ -0,0 +1,177 @@
+/**
+ * Bridge Configuration
+ * Handles loading and resolving bridge configuration from files and CLI args.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { getProjectPaths } from '../utils/project-namespace.js';
+import type { ProjectConfig, BridgeConfig } from './types.js';
+
+const CONFIG_PATHS = [
+  path.join(os.homedir(), '.agent-relay', 'bridge.json'),
+  path.join(os.homedir(), '.config', 'agent-relay', 'bridge.json'),
+];
+
+interface BridgeConfigFile {
+  projects?: Record<string, {
+    lead?: string;
+    cli?: string;
+  }>;
+  defaultCli?: string;
+}
+
+/**
+ * Load bridge config from file
+ */
+export function loadBridgeConfig(): BridgeConfigFile | null {
+  for (const configPath of CONFIG_PATHS) {
+    if (fs.existsSync(configPath)) {
+      try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        return JSON.parse(content);
+      } catch (err) {
+        console.error(`[bridge] Failed to parse ${configPath}:`, err);
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve project path (expand ~ and make absolute)
+ */
+export function resolvePath(p: string): string {
+  if (p.startsWith('~')) {
+    p = path.join(os.homedir(), p.slice(1));
+  }
+  return path.resolve(p);
+}
+
+/**
+ * Get default lead name from directory name
+ */
+export function getDefaultLeadName(projectPath: string): string {
+  const dirname = path.basename(projectPath);
+  // Capitalize first letter
+  return dirname.charAt(0).toUpperCase() + dirname.slice(1);
+}
+
+/**
+ * Resolve projects from CLI args and/or config file
+ */
+export function resolveProjects(
+  cliPaths: string[],
+  cliOverride?: string
+): ProjectConfig[] {
+  const config = loadBridgeConfig();
+  const projects: ProjectConfig[] = [];
+
+  // If CLI paths provided, use those
+  if (cliPaths.length > 0) {
+    for (const p of cliPaths) {
+      const projectPath = resolvePath(p);
+
+      if (!fs.existsSync(projectPath)) {
+        console.error(`[bridge] Project path does not exist: ${projectPath}`);
+        continue;
+      }
+
+      const paths = getProjectPaths(projectPath);
+
+      // Check for project-specific config
+      const projectConfig = config?.projects?.[p] || config?.projects?.[projectPath];
+
+      projects.push({
+        path: projectPath,
+        id: paths.projectId,
+        socketPath: paths.socketPath,
+        leadName: projectConfig?.lead || getDefaultLeadName(projectPath),
+        cli: cliOverride || projectConfig?.cli || config?.defaultCli || 'claude',
+      });
+    }
+  }
+  // Otherwise use config file
+  else if (config?.projects) {
+    for (const [p, projectConfig] of Object.entries(config.projects)) {
+      const projectPath = resolvePath(p);
+
+      if (!fs.existsSync(projectPath)) {
+        console.error(`[bridge] Project path does not exist: ${projectPath}`);
+        continue;
+      }
+
+      const paths = getProjectPaths(projectPath);
+
+      projects.push({
+        path: projectPath,
+        id: paths.projectId,
+        socketPath: paths.socketPath,
+        leadName: projectConfig.lead || getDefaultLeadName(projectPath),
+        cli: cliOverride || projectConfig.cli || config.defaultCli || 'claude',
+      });
+    }
+  }
+
+  return projects;
+}
+
+/**
+ * Validate that daemons are running for all projects
+ */
+export function validateDaemons(projects: ProjectConfig[]): {
+  valid: ProjectConfig[];
+  missing: ProjectConfig[];
+} {
+  const valid: ProjectConfig[] = [];
+  const missing: ProjectConfig[] = [];
+
+  for (const project of projects) {
+    if (fs.existsSync(project.socketPath)) {
+      valid.push(project);
+    } else {
+      missing.push(project);
+    }
+  }
+
+  return { valid, missing };
+}
+
+/**
+ * Start daemons for missing projects
+ */
+export async function startMissingDaemons(
+  projects: ProjectConfig[]
+): Promise<void> {
+  const { execAsync } = await import('./utils.js');
+
+  for (const project of projects) {
+    console.log(`[bridge] Starting daemon for ${project.id}...`);
+    try {
+      // Start daemon in background
+      await execAsync(`cd "${project.path}" && agent-relay up &`, {
+        timeout: 5000,
+      });
+      // Wait for socket to appear
+      await waitForSocket(project.socketPath, 10000);
+      console.log(`[bridge] Daemon started for ${project.id}`);
+    } catch (err) {
+      console.error(`[bridge] Failed to start daemon for ${project.id}:`, err);
+    }
+  }
+}
+
+/**
+ * Wait for socket file to exist
+ */
+async function waitForSocket(socketPath: string, timeoutMs: number): Promise<void> {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeoutMs) {
+    if (fs.existsSync(socketPath)) {
+      return;
+    }
+    await new Promise(r => setTimeout(r, 200));
+  }
+  throw new Error(`Timeout waiting for socket: ${socketPath}`);
+}
diff --git a/src/bridge/index.ts b/src/bridge/index.ts
new file mode 100644
index 000000000..f0036fbce
--- /dev/null
+++ b/src/bridge/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Bridge Module
+ * Multi-project orchestration for agent-relay
+ */
+
+export * from './types.js';
+export * from './config.js';
+export * from './multi-project-client.js';
+export * from './spawner.js';
+export * from './utils.js';
diff --git a/src/bridge/multi-project-client.integration.test.ts b/src/bridge/multi-project-client.integration.test.ts
new file mode 100644
index 000000000..a23616bca
--- /dev/null
+++ b/src/bridge/multi-project-client.integration.test.ts
@@ -0,0 +1,238 @@
+/**
+ * Integration tests for MultiProjectClient
+ * Tests actual socket connections with a real daemon
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { Daemon } from '../daemon/server.js';
+import { RelayClient } from '../wrapper/client.js';
+import { MultiProjectClient } from './multi-project-client.js';
+import type { ProjectConfig } from './types.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// Test fixtures
+const TEST_DIR = path.join(os.tmpdir(), 'agent-relay-integration-test');
+const PROJECT_A_DIR = path.join(TEST_DIR, 'project-a');
+const PROJECT_B_DIR = path.join(TEST_DIR, 'project-b');
+
+function createTestDirs(): void {
+  fs.mkdirSync(path.join(PROJECT_A_DIR, 'team'), { recursive: true });
+  fs.mkdirSync(path.join(PROJECT_B_DIR, 'team'), { recursive: true });
+}
+
+function cleanupTestDirs(): void {
+  try {
+    fs.rmSync(TEST_DIR, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors
+  }
+}
+
+describe('MultiProjectClient Integration', () => {
+  let daemonA: Daemon;
+  let daemonB: Daemon;
+  let socketPathA: string;
+  let socketPathB: string;
+
+  beforeAll(async () => {
+    cleanupTestDirs();
+    createTestDirs();
+
+    socketPathA = path.join(PROJECT_A_DIR, 'relay.sock');
+    socketPathB = path.join(PROJECT_B_DIR, 'relay.sock');
+
+    // Start two daemons
+    daemonA = new Daemon({
+      socketPath: socketPathA,
+      pidFilePath: path.join(PROJECT_A_DIR, 'relay.pid'),
+      storagePath: path.join(PROJECT_A_DIR, 'messages.sqlite'),
+      teamDir: path.join(PROJECT_A_DIR, 'team'),
+    });
+
+    daemonB = new Daemon({
+      socketPath: socketPathB,
+      pidFilePath: path.join(PROJECT_B_DIR, 'relay.pid'),
+      storagePath: path.join(PROJECT_B_DIR, 'messages.sqlite'),
+      teamDir: path.join(PROJECT_B_DIR, 'team'),
+    });
+
+    await daemonA.start();
+    await daemonB.start();
+  }, 10000);
+
+  afterAll(async () => {
+    await daemonA?.stop();
+    await daemonB?.stop();
+    cleanupTestDirs();
+  });
+
+  describe('connection management', () => {
+    it('connects to multiple project daemons', async () => {
+      const projects: ProjectConfig[] = [
+        {
+          path: PROJECT_A_DIR,
+          id: 'project-a',
+          socketPath: socketPathA,
+          leadName: 'Alice',
+          cli: 'claude',
+        },
+        {
+          path: PROJECT_B_DIR,
+          id: 'project-b',
+          socketPath: socketPathB,
+          leadName: 'Bob',
+          cli: 'claude',
+        },
+      ];
+
+      const client = new MultiProjectClient(projects);
+
+      await client.connect();
+
+      const connected = client.getConnectedProjects();
+      expect(connected).toContain('project-a');
+      expect(connected).toContain('project-b');
+
+      client.disconnect();
+    });
+
+    it('handles missing daemon gracefully', async () => {
+      const projects: ProjectConfig[] = [
+        {
+          path: PROJECT_A_DIR,
+          id: 'project-a',
+          socketPath: socketPathA,
+          leadName: 'Alice',
+          cli: 'claude',
+        },
+        {
+          path: '/nonexistent',
+          id: 'missing',
+          socketPath: '/nonexistent/relay.sock',
+          leadName: 'Missing',
+          cli: 'claude',
+        },
+      ];
+
+      const client = new MultiProjectClient(projects);
+
+      // Should throw because one project is missing
+      await expect(client.connect()).rejects.toThrow();
+
+      client.disconnect();
+    });
+  });
+
+  describe('message routing', () => {
+    let bridgeClient: MultiProjectClient;
+    let agentAlice: RelayClient;
+    let agentBob: RelayClient;
+
+    beforeEach(async () => {
+      // Set up bridge client
+      const projects: ProjectConfig[] = [
+        {
+          path: PROJECT_A_DIR,
+          id: 'project-a',
+          socketPath: socketPathA,
+          leadName: 'Alice',
+          cli: 'claude',
+        },
+        {
+          path: PROJECT_B_DIR,
+          id: 'project-b',
+          socketPath: socketPathB,
+          leadName: 'Bob',
+          cli: 'claude',
+        },
+      ];
+
+      bridgeClient = new MultiProjectClient(projects);
+      await bridgeClient.connect();
+
+      // Set up agents in each project
+      agentAlice = new RelayClient({
+        agentName: 'Alice',
+        socketPath: socketPathA,
+        reconnect: false,
+      });
+
+      agentBob = new RelayClient({
+        agentName: 'Bob',
+        socketPath: socketPathB,
+        reconnect: false,
+      });
+
+      await agentAlice.connect();
+      await agentBob.connect();
+    });
+
+    afterEach(() => {
+      agentAlice?.disconnect();
+      agentBob?.disconnect();
+      bridgeClient?.disconnect();
+    });
+
+    it('sends message to specific project agent', async () => {
+      const receivedMessages: string[] = [];
+
+      agentAlice.onMessage = (from, payload) => {
+        receivedMessages.push(`${from}: ${payload.body}`);
+      };
+
+      // Bridge sends to Alice in project-a
+      const sent = bridgeClient.sendToProject('project-a', 'Alice', 'Hello Alice!');
+      expect(sent).toBe(true);
+
+      // Wait for message delivery
+      await new Promise(r => setTimeout(r, 100));
+
+      expect(receivedMessages).toContain('__BridgeClient: Hello Alice!');
+    });
+
+    it('sends message to lead by alias', async () => {
+      const receivedMessages: string[] = [];
+
+      agentAlice.onMessage = (from, payload) => {
+        receivedMessages.push(payload.body);
+      };
+
+      // Register Alice as lead for project-a
+      bridgeClient.registerLead('project-a', 'Alice');
+
+      // Send to 'lead' - should resolve to Alice
+      bridgeClient.sendToProject('project-a', 'lead', 'Hello Lead!');
+
+      await new Promise(r => setTimeout(r, 100));
+
+      expect(receivedMessages).toContain('Hello Lead!');
+    });
+
+    it('broadcasts to all leads', async () => {
+      const messagesAlice: string[] = [];
+      const messagesBob: string[] = [];
+
+      agentAlice.onMessage = (from, payload) => {
+        messagesAlice.push(payload.body);
+      };
+
+      agentBob.onMessage = (from, payload) => {
+        messagesBob.push(payload.body);
+      };
+
+      // Register leads
+      bridgeClient.registerLead('project-a', 'Alice');
+      bridgeClient.registerLead('project-b', 'Bob');
+
+      // Broadcast to all leads
+      bridgeClient.broadcastToLeads('Standup time!');
+
+      await new Promise(r => setTimeout(r, 100));
+
+      expect(messagesAlice).toContain('Standup time!');
+      expect(messagesBob).toContain('Standup time!');
+    });
+  });
+});
diff --git a/src/bridge/multi-project-client.test.ts b/src/bridge/multi-project-client.test.ts
new file mode 100644
index 000000000..7969070fe
--- /dev/null
+++ b/src/bridge/multi-project-client.test.ts
@@ -0,0 +1,338 @@
+/**
+ * Unit tests for MultiProjectClient (error paths and state callbacks)
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { EventEmitter } from 'node:events';
+import { MultiProjectClient } from './multi-project-client.js';
+import type { ProjectConfig } from './types.js';
+
+// Shared mock state (hoisted for vi.mock)
+const { existsSyncMock, createConnectionMock, encodeFrameMock } = vi.hoisted(() => ({
+  existsSyncMock: vi.fn(),
+  createConnectionMock: vi.fn(),
+  encodeFrameMock: vi.fn(),
+}));
+let framesToReturn: any[] = [];
+
+// Mock fs and net
+vi.mock('node:fs', () => ({
+  default: {
+    existsSync: existsSyncMock,
+  },
+  existsSync: existsSyncMock,
+}));
+
+vi.mock('node:net', () => ({
+  default: {
+    createConnection: createConnectionMock,
+  },
+  createConnection: createConnectionMock,
+}));
+
+// Mock framing utilities
+vi.mock('../protocol/framing.js', () => ({
+  FrameParser: class {
+    push = vi.fn(() => framesToReturn);
+  },
+  encodeFrame: encodeFrameMock,
+}));
+
+// Simple socket stub
+class MockSocket extends EventEmitter {
+  write = vi.fn();
+  end = vi.fn();
+  destroy = vi.fn();
+}
+
+const projectA: ProjectConfig = {
+  path: '/project/a',
+  id: 'project-a',
+  socketPath: '/project/a/relay.sock',
+  leadName: 'Alice',
+  cli: 'claude',
+};
+
+describe('MultiProjectClient (unit)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useRealTimers();
+    framesToReturn = [];
+    encodeFrameMock.mockImplementation(() => Buffer.from('frame'));
+    existsSyncMock.mockReturnValue(true);
+
+    createConnectionMock.mockImplementation((_path: string, cb?: () => void) => {
+      const socket = new MockSocket();
+      // Fire connect callback asynchronously to mirror net.createConnection timing
+      if (cb) setImmediate(cb);
+      return socket;
+    });
+  });
+
+  it('rejects connect when socket is missing', async () => {
+    existsSyncMock.mockReturnValue(false);
+
+    const client = new MultiProjectClient([projectA]);
+    await expect(client.connect()).rejects.toThrow();
+    expect(createConnectionMock).not.toHaveBeenCalled();
+  });
+
+  it('times out when daemon never becomes ready', async () => {
+    vi.useFakeTimers();
+    const client = new MultiProjectClient([projectA]);
+
+    const connectPromise = client.connect();
+    const rejection = expect(connectPromise).rejects.toThrow('Connection timeout');
+
+    // No WELCOME frame emitted -> timeout triggers
+    await vi.runAllTimersAsync();
+    await rejection;
+  });
+
+  it('invokes state change callbacks on welcome and close', async () => {
+    vi.useFakeTimers();
+    const socket = new MockSocket();
+    createConnectionMock.mockImplementation((_path: string, cb?: () => void) => {
+      if (cb) setImmediate(cb);
+      return socket;
+    });
+
+    framesToReturn = [
+      {
+        type: 'WELCOME',
+        id: 'welcome-1',
+        v: 1,
+        ts: Date.now(),
+        payload: {},
+      },
+    ];
+
+    const client = new MultiProjectClient([projectA]);
+    const states: Array<{ id: string; connected: boolean }> = [];
+    client.onProjectStateChange = (id, connected) => states.push({ id, connected });
+
+    const connectPromise = client.connect();
+
+    // Emit data to produce WELCOME
+    socket.emit('data', Buffer.from('welcome'));
+    await vi.runOnlyPendingTimersAsync();
+    await connectPromise;
+
+    expect(client.getConnectedProjects()).toContain('project-a');
+
+    // Simulate close
+    socket.emit('close');
+
+    expect(states).toEqual([
+      { id: 'project-a', connected: true },
+      { id: 'project-a', connected: false },
+    ]);
+    expect(client.getConnectedProjects()).not.toContain('project-a');
+  });
+
+  it('sendToProject returns false when project missing or not ready', () => {
+    const client = new MultiProjectClient([projectA]);
+
+    expect(client.sendToProject('unknown', 'Bob', 'hi')).toBe(false);
+
+    // Manually insert a connection but mark not ready
+    (client as any).connections.set('project-a', {
+      config: projectA,
+      ready: false,
+    });
+    expect(client.sendToProject('project-a', 'Bob', 'hi')).toBe(false);
+  });
+
+  it('sendToProject returns false when frame encoding throws', () => {
+    const client = new MultiProjectClient([projectA]);
+    const socket = new MockSocket();
+
+    // Insert ready connection
+    (client as any).connections.set('project-a', {
+      config: projectA,
+      socket,
+      ready: true,
+    });
+
+    encodeFrameMock.mockImplementation(() => {
+      throw new Error('encode failed');
+    });
+
+    const result = client.sendToProject('project-a', 'Bob', 'hi');
+    expect(result).toBe(false);
+  });
+
+  it('broadcastToLeads only sends to ready connections and resolves lead alias', () => {
+    const client = new MultiProjectClient([projectA]);
+    const socket = new MockSocket();
+
+    (client as any).connections.set('project-a', {
+      config: projectA,
+      socket,
+      ready: true,
+    });
+    client.registerLead('project-a', 'Alice');
+
+    client.broadcastToLeads('Hello leads');
+
+    expect(encodeFrameMock).toHaveBeenCalled();
+    expect(socket.write).toHaveBeenCalled();
+  });
+
+  it('getConnectedProjects filters by ready state', () => {
+    const client = new MultiProjectClient([projectA]);
+    (client as any).connections.set('project-a', {
+      config: projectA,
+      ready: true,
+    });
+    (client as any).connections.set('project-b', {
+      config: { ...projectA, id: 'project-b', socketPath: '/b.sock', path: '/b' },
+      ready: false,
+    });
+
+    expect(client.getConnectedProjects()).toEqual(['project-a']);
+  });
+
+  describe('reconnection logic', () => {
+    it('schedules reconnection when socket closes and reconnect is enabled', async () => {
+      vi.useFakeTimers();
+      const socket = new MockSocket();
+      createConnectionMock.mockImplementation((_path: string, cb?: () => void) => {
+        if (cb) setImmediate(cb);
+        return socket;
+      });
+
+      framesToReturn = [
+        { type: 'WELCOME', id: 'welcome-1', v: 1, ts: Date.now(), payload: {} },
+      ];
+
+      // Default: reconnect enabled
+      const client = new MultiProjectClient([projectA]);
+      const connectPromise = client.connect();
+
+      socket.emit('data', Buffer.from('welcome'));
+      await vi.runOnlyPendingTimersAsync();
+      await connectPromise;
+
+      // Simulate close
+      socket.emit('close');
+
+      // Should have scheduled reconnection
+      expect((client as any).connections.get('project-a')?.reconnecting).toBe(true);
+
+      client.disconnect();
+    });
+
+    it('does not reconnect when reconnect option is false', async () => {
+      vi.useFakeTimers();
+      const socket = new MockSocket();
+      createConnectionMock.mockImplementation((_path: string, cb?: () => void) => {
+        if (cb) setImmediate(cb);
+        return socket;
+      });
+
+      framesToReturn = [
+        { type: 'WELCOME', id: 'welcome-1', v: 1, ts: Date.now(), payload: {} },
+      ];
+
+      const client = new MultiProjectClient([projectA], { reconnect: false });
+      const connectPromise = client.connect();
+
+      socket.emit('data', Buffer.from('welcome'));
+      await vi.runOnlyPendingTimersAsync();
+      await connectPromise;
+
+      // Simulate close
+      socket.emit('close');
+
+      // Should NOT have scheduled reconnection
+      expect((client as any).connections.get('project-a')?.reconnecting).toBeFalsy();
+
+      client.disconnect();
+    });
+
+    it('uses exponential backoff for reconnection delays', async () => {
+      vi.useFakeTimers();
+      const client = new MultiProjectClient([projectA], {
+        reconnectDelay: 100,
+        maxReconnectDelay: 1000,
+      });
+
+      const conn = {
+        config: projectA,
+        socket: new MockSocket(),
+        parser: { push: vi.fn(() => []) },
+        ready: false,
+        reconnecting: false,
+        reconnectAttempts: 0,
+      };
+      (client as any).connections.set('project-a', conn);
+
+      // First attempt: 100ms
+      (client as any).scheduleReconnect(conn);
+      expect(conn.reconnectAttempts).toBe(1);
+
+      // Manually reset for second attempt
+      conn.reconnecting = false;
+      (client as any).scheduleReconnect(conn);
+      expect(conn.reconnectAttempts).toBe(2);
+
+      // Third attempt: 400ms
+      conn.reconnecting = false;
+      (client as any).scheduleReconnect(conn);
+      expect(conn.reconnectAttempts).toBe(3);
+
+      client.disconnect();
+    });
+
+    it('stops reconnecting after max attempts', async () => {
+      const client = new MultiProjectClient([projectA], {
+        maxReconnectAttempts: 3,
+      });
+
+      const conn = {
+        config: projectA,
+        socket: new MockSocket(),
+        parser: { push: vi.fn(() => []) },
+        ready: false,
+        reconnecting: false,
+        reconnectAttempts: 3,
+      };
+      (client as any).connections.set('project-a', conn);
+
+      // Should not schedule another reconnect
+      (client as any).scheduleReconnect(conn);
+      expect(conn.reconnecting).toBe(false);
+
+      client.disconnect();
+    });
+
+    it('clears reconnect timers on disconnect', async () => {
+      vi.useFakeTimers();
+      const socket = new MockSocket();
+      createConnectionMock.mockImplementation((_path: string, cb?: () => void) => {
+        if (cb) setImmediate(cb);
+        return socket;
+      });
+
+      framesToReturn = [
+        { type: 'WELCOME', id: 'welcome-1', v: 1, ts: Date.now(), payload: {} },
+      ];
+
+      const client = new MultiProjectClient([projectA]);
+      const connectPromise = client.connect();
+
+      socket.emit('data', Buffer.from('welcome'));
+      await vi.runOnlyPendingTimersAsync();
+      await connectPromise;
+
+      // Simulate close to trigger reconnection
+      socket.emit('close');
+
+      // Disconnect should clear the timer
+      client.disconnect();
+
+      expect((client as any).shuttingDown).toBe(true);
+    });
+  });
+});
diff --git a/src/bridge/multi-project-client.ts b/src/bridge/multi-project-client.ts
new file mode 100644
index 000000000..e7b8c41de
--- /dev/null
+++ b/src/bridge/multi-project-client.ts
@@ -0,0 +1,467 @@
+/**
+ * MultiProjectClient
+ * Connects to multiple project daemons simultaneously for cross-project orchestration.
+ */
+
+import net from 'node:net';
+import fs from 'node:fs';
+import path from 'node:path';
+import { v4 as uuid } from 'uuid';
+import {
+  type Envelope,
+  type HelloPayload,
+  type WelcomePayload,
+  type SendPayload,
+  type DeliverEnvelope,
+  PROTOCOL_VERSION,
+} from '../protocol/types.js';
+import { encodeFrame, FrameParser } from '../protocol/framing.js';
+import type { ProjectConfig, LeadInfo } from './types.js';
+
+interface ProjectConnection {
+  config: ProjectConfig;
+  socket: net.Socket;
+  parser: FrameParser;
+  ready: boolean;
+  lead?: LeadInfo;
+  reconnecting?: boolean;
+  reconnectAttempts?: number;
+  reconnectTimer?: ReturnType<typeof setTimeout>;
+}
+
+interface MultiProjectClientOptions {
+  /** Agent name to register as (default: '__BridgeClient'). Must be unique per daemon. */
+  agentName?: string;
+  /** Enable automatic reconnection on disconnect (default: true) */
+  reconnect?: boolean;
+  /** Initial reconnection delay in ms (default: 1000) */
+  reconnectDelay?: number;
+  /** Maximum reconnection delay in ms (default: 30000) */
+  maxReconnectDelay?: number;
+  /** Maximum reconnection attempts before giving up (default: Infinity) */
+  maxReconnectAttempts?: number;
+}
+
+export class MultiProjectClient {
+  private connections: Map<string, ProjectConnection> = new Map();
+  private leads: Map<string, LeadInfo> = new Map();
+  private options: Required<Omit<MultiProjectClientOptions, 'agentName'>> & { agentName: string };
+  private shuttingDown = false;
+
+  /** Handler for incoming messages */
+  onMessage?: (projectId: string, from: string, payload: SendPayload, messageId: string) => void;
+
+  /** Handler for connection state changes */
+  onProjectStateChange?: (projectId: string, connected: boolean) => void;
+
+  constructor(private projects: ProjectConfig[], options: MultiProjectClientOptions = {}) {
+    this.options = {
+      agentName: options.agentName ?? '__BridgeClient',
+      reconnect: options.reconnect ?? true,
+      reconnectDelay: options.reconnectDelay ?? 1000,
+      maxReconnectDelay: options.maxReconnectDelay ?? 30000,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? Infinity,
+    };
+  }
+
+  /**
+   * Connect to all project daemons
+   */
+  async connect(): Promise<void> {
+    const connectPromises = this.projects.map((project) => this.connectToProject(project));
+    await Promise.all(connectPromises);
+  }
+
+  /**
+   * Connect to a single project daemon
+   */
+  private connectToProject(project: ProjectConfig): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // Check socket exists
+      if (!fs.existsSync(project.socketPath)) {
+        console.error(`[bridge] No daemon running for ${project.id} (${project.path})`);
+        console.error(`[bridge] Start with: cd ${project.path} && agent-relay up`);
+        reject(new Error(`No daemon for ${project.id}`));
+        return;
+      }
+
+      const socket = net.createConnection(project.socketPath, () => {
+        this.sendHello(conn);
+      });
+
+      const conn: ProjectConnection = {
+        config: project,
+        socket,
+        parser: new FrameParser(),
+        ready: false,
+      };
+
+      socket.on('data', (data) => this.handleData(conn, data));
+
+      socket.on('close', () => {
+        const wasReady = conn.ready;
+        conn.ready = false;
+        this.onProjectStateChange?.(project.id, false);
+
+        // Attempt reconnection if enabled and not shutting down
+        if (wasReady && this.options.reconnect && !this.shuttingDown) {
+          this.scheduleReconnect(conn);
+        }
+      });
+
+      socket.on('error', (err) => {
+        console.error(`[bridge] Connection error for ${project.id}:`, err.message);
+        if (!conn.ready) {
+          reject(err);
+        }
+      });
+
+      this.connections.set(project.id, conn);
+
+      // Wait for ready
+      const checkReady = setInterval(() => {
+        if (conn.ready) {
+          clearInterval(checkReady);
+          clearTimeout(timeout);
+          resolve();
+        }
+      }, 10);
+
+      const timeout = setTimeout(() => {
+        if (!conn.ready) {
+          clearInterval(checkReady);
+          socket.destroy();
+          reject(new Error(`Connection timeout for ${project.id}`));
+        }
+      }, 5000);
+    });
+  }
+
+  /**
+   * Send HELLO to a project daemon
+   */
+  private sendHello(conn: ProjectConnection): void {
+    const hello: Envelope<HelloPayload> = {
+      v: PROTOCOL_VERSION,
+      type: 'HELLO',
+      id: uuid(),
+      ts: Date.now(),
+      payload: {
+        agent: this.options.agentName,
+        cli: 'bridge',
+        capabilities: {
+          ack: true,
+          resume: false,
+          max_inflight: 256,
+          supports_topics: true,
+        },
+      },
+    };
+
+    this.send(conn, hello);
+  }
+
+  /**
+   * Handle incoming data from a project connection
+   */
+  private handleData(conn: ProjectConnection, data: Buffer): void {
+    try {
+      const frames = conn.parser.push(data);
+      for (const frame of frames) {
+        this.processFrame(conn, frame);
+      }
+    } catch (err) {
+      console.error(`[bridge] Parse error for ${conn.config.id}:`, err);
+    }
+  }
+
+  /**
+   * Process a frame from a project daemon
+   */
+  private processFrame(conn: ProjectConnection, envelope: Envelope): void {
+    switch (envelope.type) {
+      case 'WELCOME':
+        conn.ready = true;
+        console.log(`[bridge] Connected to ${conn.config.id}`);
+        this.onProjectStateChange?.(conn.config.id, true);
+        break;
+
+      case 'DELIVER':
+        this.handleDeliver(conn, envelope as DeliverEnvelope);
+        break;
+
+      case 'PING':
+        this.send(conn, {
+          v: PROTOCOL_VERSION,
+          type: 'PONG',
+          id: uuid(),
+          ts: Date.now(),
+          payload: (envelope.payload as { nonce?: string }) ?? {},
+        });
+        break;
+    }
+  }
+
+  /**
+   * Handle delivered message from a project
+   */
+  private handleDeliver(conn: ProjectConnection, envelope: DeliverEnvelope): void {
+    // Send ACK
+    this.send(conn, {
+      v: PROTOCOL_VERSION,
+      type: 'ACK',
+      id: uuid(),
+      ts: Date.now(),
+      payload: {
+        ack_id: envelope.id,
+        seq: envelope.delivery.seq,
+      },
+    });
+
+    // Notify handler
+    if (this.onMessage && envelope.from) {
+      this.onMessage(conn.config.id, envelope.from, envelope.payload, envelope.id);
+    }
+  }
+
+  /**
+   * Send envelope to a project daemon
+   */
+  private send(conn: ProjectConnection, envelope: Envelope): boolean {
+    if (!conn.socket) return false;
+
+    try {
+      const frame = encodeFrame(envelope);
+      conn.socket.write(frame);
+      return true;
+    } catch (err) {
+      console.error(`[bridge] Send error for ${conn.config.id}:`, err);
+      return false;
+    }
+  }
+
+  /**
+   * Send message to a project
+   * @param projectId - Target project ID
+   * @param to - Agent name within the project (or '*' for broadcast, 'lead' for project lead)
+   * @param body - Message body
+   */
+  sendToProject(projectId: string, to: string, body: string): boolean {
+    const conn = this.connections.get(projectId);
+    if (!conn?.ready) {
+      console.error(`[bridge] Cannot send to ${projectId}: not connected`);
+      return false;
+    }
+
+    // Resolve 'lead' to actual lead name
+    let targetAgent = to;
+    if (to === 'lead') {
+      const lead = this.leads.get(projectId);
+      if (lead) {
+        targetAgent = lead.name;
+      } else {
+        // Fallback to configured lead name
+        targetAgent = conn.config.leadName;
+      }
+    }
+
+    const envelope: Envelope<SendPayload> = {
+      v: PROTOCOL_VERSION,
+      type: 'SEND',
+      id: uuid(),
+      ts: Date.now(),
+      to: targetAgent,
+      payload: {
+        kind: 'message',
+        body,
+      },
+    };
+
+    return this.send(conn, envelope);
+  }
+
+  /**
+   * Broadcast to all leads
+   */
+  broadcastToLeads(body: string): void {
+    for (const [projectId] of this.connections) {
+      this.sendToProject(projectId, 'lead', body);
+    }
+  }
+
+  /**
+   * Broadcast to all agents in all projects
+   */
+  broadcastAll(body: string): void {
+    for (const [projectId, conn] of this.connections) {
+      if (conn.ready) {
+        const envelope: Envelope<SendPayload> = {
+          v: PROTOCOL_VERSION,
+          type: 'SEND',
+          id: uuid(),
+          ts: Date.now(),
+          to: '*',
+          payload: {
+            kind: 'message',
+            body,
+          },
+        };
+        this.send(conn, envelope);
+      }
+    }
+  }
+
+  /**
+   * Register a lead for a project
+   */
+  registerLead(projectId: string, leadName: string): void {
+    this.leads.set(projectId, {
+      name: leadName,
+      projectId,
+      connected: true,
+    });
+  }
+
+  /**
+   * Get all connected projects
+   */
+  getConnectedProjects(): string[] {
+    return Array.from(this.connections.entries())
+      .filter(([_, conn]) => conn.ready)
+      .map(([id]) => id);
+  }
+
+  /**
+   * Get project connection info
+   */
+  getProject(projectId: string): ProjectConfig | undefined {
+    return this.connections.get(projectId)?.config;
+  }
+
+  /**
+   * Schedule a reconnection attempt with exponential backoff
+   */
+  private scheduleReconnect(conn: ProjectConnection): void {
+    if (conn.reconnecting || this.shuttingDown) return;
+
+    const attempts = conn.reconnectAttempts ?? 0;
+    if (attempts >= this.options.maxReconnectAttempts) {
+      console.error(`[bridge] Max reconnection attempts reached for ${conn.config.id}`);
+      return;
+    }
+
+    conn.reconnecting = true;
+    conn.reconnectAttempts = attempts + 1;
+
+    // Calculate delay with exponential backoff
+    const delay = Math.min(
+      this.options.reconnectDelay * Math.pow(2, attempts),
+      this.options.maxReconnectDelay
+    );
+
+    console.log(`[bridge] Reconnecting to ${conn.config.id} in ${delay}ms (attempt ${conn.reconnectAttempts})`);
+
+    conn.reconnectTimer = setTimeout(() => {
+      this.attemptReconnect(conn);
+    }, delay);
+  }
+
+  /**
+   * Attempt to reconnect to a project daemon
+   */
+  private attemptReconnect(conn: ProjectConnection): void {
+    if (this.shuttingDown) {
+      conn.reconnecting = false;
+      return;
+    }
+
+    // Check socket exists
+    if (!fs.existsSync(conn.config.socketPath)) {
+      console.error(`[bridge] No daemon running for ${conn.config.id}, will retry`);
+      conn.reconnecting = false;
+      this.scheduleReconnect(conn);
+      return;
+    }
+
+    const socket = net.createConnection(conn.config.socketPath, () => {
+      this.sendHello(conn);
+    });
+
+    // Update connection with new socket
+    conn.socket = socket;
+    conn.parser = new FrameParser();
+
+    socket.on('data', (data) => this.handleData(conn, data));
+
+    socket.on('close', () => {
+      const wasReady = conn.ready;
+      conn.ready = false;
+      this.onProjectStateChange?.(conn.config.id, false);
+
+      if (wasReady && this.options.reconnect && !this.shuttingDown) {
+        this.scheduleReconnect(conn);
+      }
+    });
+
+    socket.on('error', (err) => {
+      console.error(`[bridge] Reconnection error for ${conn.config.id}:`, err.message);
+      conn.reconnecting = false;
+      if (!this.shuttingDown) {
+        this.scheduleReconnect(conn);
+      }
+    });
+
+    // Reset reconnection state on successful connect
+    const originalReady = conn.ready;
+    const checkReady = setInterval(() => {
+      if (conn.ready && !originalReady) {
+        clearInterval(checkReady);
+        clearTimeout(timeout);
+        conn.reconnecting = false;
+        conn.reconnectAttempts = 0;
+        console.log(`[bridge] Reconnected to ${conn.config.id}`);
+      }
+    }, 10);
+
+    const timeout = setTimeout(() => {
+      if (!conn.ready) {
+        clearInterval(checkReady);
+        socket.destroy();
+        conn.reconnecting = false;
+        console.error(`[bridge] Reconnection timeout for ${conn.config.id}`);
+        if (!this.shuttingDown) {
+          this.scheduleReconnect(conn);
+        }
+      }
+    }, 5000);
+  }
+
+  /**
+   * Disconnect from all projects
+   */
+  disconnect(): void {
+    this.shuttingDown = true;
+
+    for (const [_, conn] of this.connections) {
+      // Clear any pending reconnection timers
+      if (conn.reconnectTimer) {
+        clearTimeout(conn.reconnectTimer);
+      }
+
+      try {
+        this.send(conn, {
+          v: PROTOCOL_VERSION,
+          type: 'BYE',
+          id: uuid(),
+          ts: Date.now(),
+          payload: {},
+        });
+        conn.socket.end();
+      } catch {
+        // Ignore
+      }
+    }
+    this.connections.clear();
+    this.leads.clear();
+  }
+}
diff --git a/src/bridge/spawner.test.ts b/src/bridge/spawner.test.ts
new file mode 100644
index 000000000..c31c379ce
--- /dev/null
+++ b/src/bridge/spawner.test.ts
@@ -0,0 +1,291 @@
+/**
+ * Unit tests for AgentSpawner
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import fs from 'node:fs';
+import { AgentSpawner } from './spawner.js';
+import { execAsync, sleep, escapeForTmux } from './utils.js';
+
+const PROJECT_ROOT = '/project/root';
+
+vi.mock('./utils.js', () => {
+  const execAsync = vi.fn();
+  const sleep = vi.fn();
+  const escapeForTmux = vi.fn((str: string) => `escaped:${str}`);
+  return {
+    execAsync,
+    sleep,
+    escapeForTmux,
+  };
+});
+
+vi.mock('../utils/project-namespace.js', () => {
+  return {
+    getProjectPaths: vi.fn(() => ({
+      dataDir: '/data',
+      teamDir: '/team',
+      dbPath: '/db',
+      socketPath: '/socket',
+      projectRoot: PROJECT_ROOT,
+      projectId: 'project-id',
+    })),
+  };
+});
+
+const execAsyncMock = vi.mocked(execAsync);
+const sleepMock = vi.mocked(sleep);
+const escapeForTmuxMock = vi.mocked(escapeForTmux);
+const existsSyncMock = vi.spyOn(fs, 'existsSync');
+const readFileSyncMock = vi.spyOn(fs, 'readFileSync');
+let waitForAgentRegistrationMock: vi.SpyInstance;
+
+describe('AgentSpawner', () => {
+  const projectRoot = PROJECT_ROOT;
+  const session = 'relay-workers';
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.clearAllMocks();
+    execAsyncMock.mockReset();
+    sleepMock.mockReset();
+    escapeForTmuxMock.mockReset();
+    existsSyncMock.mockReturnValue(true);
+    readFileSyncMock.mockReturnValue(JSON.stringify({ agents: [] }));
+    escapeForTmuxMock.mockImplementation((str: string) => `escaped:${str}`);
+    waitForAgentRegistrationMock = vi
+      .spyOn(AgentSpawner.prototype as any, 'waitForAgentRegistration')
+      .mockResolvedValue(true);
+  });
+
+  it('creates tmux session when missing', async () => {
+    execAsyncMock.mockRejectedValueOnce(new Error('missing'));
+    execAsyncMock.mockResolvedValue({ stdout: '', stderr: '' });
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    await spawner.ensureSession();
+
+    expect(execAsyncMock).toHaveBeenCalledTimes(2);
+    expect(execAsyncMock.mock.calls[0][0]).toBe(`tmux has-session -t ${session} 2>/dev/null`);
+    expect(execAsyncMock.mock.calls[1][0]).toBe(`tmux new-session -d -s ${session} -c "${projectRoot}"`);
+  });
+
+  it('does nothing when tmux session already exists', async () => {
+    execAsyncMock.mockResolvedValue({ stdout: '', stderr: '' });
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    await spawner.ensureSession();
+
+    expect(execAsyncMock).toHaveBeenCalledTimes(1);
+    expect(execAsyncMock).toHaveBeenCalledWith(`tmux has-session -t ${session} 2>/dev/null`);
+  });
+
+  it('spawns a worker and tracks it', async () => {
+    execAsyncMock.mockResolvedValue({ stdout: '/usr/local/bin/agent-relay', stderr: '' });
+    sleepMock.mockResolvedValue();
+    waitForAgentRegistrationMock.mockResolvedValue(true);
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    const result = await spawner.spawn({
+      name: 'Dev1',
+      cli: 'claude',
+      task: 'Finish the report',
+      requestedBy: 'Lead',
+    });
+
+    expect(result).toMatchObject({
+      success: true,
+      name: 'Dev1',
+      window: `${session}:Dev1`,
+    });
+    expect(spawner.hasWorker('Dev1')).toBe(true);
+    expect(execAsyncMock).toHaveBeenNthCalledWith(1, `tmux has-session -t ${session} 2>/dev/null`);
+    expect(execAsyncMock).toHaveBeenNthCalledWith(2, `tmux new-window -t ${session} -n Dev1 -c "${projectRoot}"`);
+    expect(execAsyncMock).toHaveBeenNthCalledWith(3, 'which agent-relay'); // Find full path
+    expect(execAsyncMock).toHaveBeenNthCalledWith(4, `tmux send-keys -t ${session}:Dev1 'unset TMUX && /usr/local/bin/agent-relay -n Dev1 claude --dangerously-skip-permissions' Enter`);
+    expect(execAsyncMock).toHaveBeenNthCalledWith(5, `tmux send-keys -t ${session}:Dev1 -l "escaped:Finish the report"`);
+    expect(execAsyncMock).toHaveBeenNthCalledWith(6, `tmux send-keys -t ${session}:Dev1 Enter`);
+    expect(sleepMock).toHaveBeenCalledWith(100);
+  });
+
+  it('adds --dangerously-skip-permissions for Claude variants', async () => {
+    execAsyncMock.mockResolvedValue({ stdout: '/usr/local/bin/agent-relay', stderr: '' });
+    sleepMock.mockResolvedValue();
+    waitForAgentRegistrationMock.mockResolvedValue(true);
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    await spawner.spawn({
+      name: 'Opus1',
+      cli: 'claude:opus',
+      task: '',
+      requestedBy: 'Lead',
+    });
+
+    // Check that the command includes --dangerously-skip-permissions for claude:opus
+    expect(execAsyncMock).toHaveBeenNthCalledWith(
+      4,
+      `tmux send-keys -t ${session}:Opus1 'unset TMUX && /usr/local/bin/agent-relay -n Opus1 claude:opus --dangerously-skip-permissions' Enter`
+    );
+  });
+
+  it('does NOT add --dangerously-skip-permissions for non-Claude CLIs', async () => {
+    execAsyncMock.mockResolvedValue({ stdout: '/usr/local/bin/agent-relay', stderr: '' });
+    sleepMock.mockResolvedValue();
+    waitForAgentRegistrationMock.mockResolvedValue(true);
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    await spawner.spawn({
+      name: 'Codex1',
+      cli: 'codex',
+      task: '',
+      requestedBy: 'Lead',
+    });
+
+    // Check that the command does NOT include --dangerously-skip-permissions for codex
+    expect(execAsyncMock).toHaveBeenNthCalledWith(
+      4,
+      `tmux send-keys -t ${session}:Codex1 'unset TMUX && /usr/local/bin/agent-relay -n Codex1 codex' Enter`
+    );
+  });
+
+  it('refuses to spawn a duplicate worker', async () => {
+    const spawner = new AgentSpawner(projectRoot, session);
+    spawner['activeWorkers'].set('Dev1', {
+      name: 'Dev1',
+      cli: 'claude',
+      task: 'Existing task',
+      spawnedBy: 'Lead',
+      spawnedAt: Date.now(),
+      window: `${session}:Dev1`,
+    });
+
+    const result = await spawner.spawn({
+      name: 'Dev1',
+      cli: 'claude',
+      task: 'New task',
+      requestedBy: 'Lead',
+    });
+
+    expect(result.success).toBe(false);
+    expect(execAsyncMock).not.toHaveBeenCalled();
+  });
+
+  it('returns failure when spawn command errors', async () => {
+    execAsyncMock
+      .mockResolvedValueOnce({ stdout: '', stderr: '' }) // has-session
+      .mockRejectedValueOnce(new Error('tmux new-window failed')); // new-window fails
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    const result = await spawner.spawn({
+      name: 'Dev2',
+      cli: 'claude',
+      task: 'Task',
+      requestedBy: 'Lead',
+    });
+
+    expect(result.success).toBe(false);
+    expect(spawner.hasWorker('Dev2')).toBe(false);
+  });
+
+  it('cleans up when agent does not register', async () => {
+    execAsyncMock.mockResolvedValue({ stdout: '/usr/local/bin/agent-relay', stderr: '' });
+    waitForAgentRegistrationMock.mockResolvedValue(false);
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    const result = await spawner.spawn({
+      name: 'Late',
+      cli: 'claude',
+      task: 'Task',
+      requestedBy: 'Lead',
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('failed to register');
+    expect(execAsyncMock).toHaveBeenCalledWith(`tmux kill-window -t ${session}:Late`);
+    expect(spawner.hasWorker('Late')).toBe(false);
+  });
+
+  it('releases a worker and removes tracking', async () => {
+    execAsyncMock.mockResolvedValue({ stdout: '', stderr: '' });
+    sleepMock.mockResolvedValue();
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    spawner['activeWorkers'].set('Worker', {
+      name: 'Worker',
+      cli: 'claude',
+      task: 'Task',
+      spawnedBy: 'Lead',
+      spawnedAt: Date.now(),
+      window: `${session}:Worker`,
+    });
+
+    const result = await spawner.release('Worker');
+
+    expect(result).toBe(true);
+    expect(spawner.hasWorker('Worker')).toBe(false);
+    expect(execAsyncMock).toHaveBeenNthCalledWith(1, `tmux send-keys -t ${session}:Worker '/exit' Enter`);
+    expect(execAsyncMock).toHaveBeenNthCalledWith(2, `tmux kill-window -t ${session}:Worker`);
+    expect(sleepMock).toHaveBeenCalledWith(2000);
+  });
+
+  it('returns false when releasing a missing worker', async () => {
+    const spawner = new AgentSpawner(projectRoot, session);
+
+    const result = await spawner.release('Missing');
+
+    expect(result).toBe(false);
+    expect(execAsyncMock).not.toHaveBeenCalled();
+  });
+
+  it('clears worker even when release fails', async () => {
+    execAsyncMock.mockRejectedValue(new Error('tmux error'));
+    sleepMock.mockResolvedValue();
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    spawner['activeWorkers'].set('Failing', {
+      name: 'Failing',
+      cli: 'claude',
+      task: 'Task',
+      spawnedBy: 'Lead',
+      spawnedAt: Date.now(),
+      window: `${session}:Failing`,
+    });
+
+    const result = await spawner.release('Failing');
+
+    expect(result).toBe(true);
+    expect(spawner.hasWorker('Failing')).toBe(false);
+    expect(execAsyncMock).toHaveBeenCalledTimes(2);
+    expect(execAsyncMock.mock.calls[0][0]).toBe(`tmux send-keys -t ${session}:Failing '/exit' Enter`);
+    expect(execAsyncMock.mock.calls[1][0]).toBe(`tmux kill-window -t ${session}:Failing`);
+    expect(sleepMock).toHaveBeenCalledWith(2000);
+  });
+
+  it('releases all workers', async () => {
+    execAsyncMock.mockResolvedValue({ stdout: '', stderr: '' });
+    sleepMock.mockResolvedValue();
+
+    const spawner = new AgentSpawner(projectRoot, session);
+    spawner['activeWorkers'].set('A', {
+      name: 'A',
+      cli: 'claude',
+      task: 'Task A',
+      spawnedBy: 'Lead',
+      spawnedAt: Date.now(),
+      window: `${session}:A`,
+    });
+    spawner['activeWorkers'].set('B', {
+      name: 'B',
+      cli: 'claude',
+      task: 'Task B',
+      spawnedBy: 'Lead',
+      spawnedAt: Date.now(),
+      window: `${session}:B`,
+    });
+
+    await spawner.releaseAll();
+
+    expect(spawner.getActiveWorkers()).toHaveLength(0);
+    expect(execAsyncMock).toHaveBeenCalledTimes(4); // two send-keys and two kill-window
+  });
+});
diff --git a/src/bridge/spawner.ts b/src/bridge/spawner.ts
new file mode 100644
index 000000000..4267b536e
--- /dev/null
+++ b/src/bridge/spawner.ts
@@ -0,0 +1,258 @@
+/**
+ * Agent Spawner
+ * Handles spawning and releasing worker agents via tmux.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execAsync, sleep, escapeForTmux } from './utils.js';
+import { getProjectPaths } from '../utils/project-namespace.js';
+import type { SpawnRequest, SpawnResult, WorkerInfo } from './types.js';
+
+export class AgentSpawner {
+  private activeWorkers: Map<string, WorkerInfo> = new Map();
+  private tmuxSession: string;
+  private agentsPath: string;
+
+  constructor(
+    projectRoot: string,
+    tmuxSession?: string
+  ) {
+    const paths = getProjectPaths(projectRoot);
+    this.projectRoot = paths.projectRoot;
+    this.agentsPath = path.join(paths.teamDir, 'agents.json');
+
+    // Default session name based on project
+    this.tmuxSession = tmuxSession || 'relay-workers';
+  }
+  private projectRoot: string;
+
+  /**
+   * Ensure the worker tmux session exists
+   */
+  async ensureSession(): Promise<void> {
+    try {
+      await execAsync(`tmux has-session -t ${this.tmuxSession} 2>/dev/null`);
+    } catch {
+      // Session doesn't exist, create it
+      await execAsync(
+        `tmux new-session -d -s ${this.tmuxSession} -c "${this.projectRoot}"`
+      );
+      console.log(`[spawner] Created session ${this.tmuxSession}`);
+    }
+  }
+
+  /**
+   * Spawn a new worker agent
+   */
+  async spawn(request: SpawnRequest): Promise<SpawnResult> {
+    const { name, cli, task, requestedBy } = request;
+    const debug = process.env.DEBUG_SPAWN === '1';
+
+    // Check if worker already exists
+    if (this.activeWorkers.has(name)) {
+      return {
+        success: false,
+        name,
+        error: `Worker ${name} already exists`,
+      };
+    }
+
+    try {
+      await this.ensureSession();
+      if (debug) console.log(`[spawner:debug] Session ${this.tmuxSession} ready`);
+
+      // Create new window for worker
+      const windowName = name;
+      const newWindowCmd = `tmux new-window -t ${this.tmuxSession} -n ${windowName} -c "${this.projectRoot}"`;
+      if (debug) console.log(`[spawner:debug] Creating window: ${newWindowCmd}`);
+      await execAsync(newWindowCmd);
+
+      // Build the agent-relay command
+      // Unset TMUX to allow Claude to run inside tmux (it refuses to nest by default)
+      // Use full path to agent-relay to avoid PATH issues with nvm/shell init
+      let agentRelayPath: string;
+      try {
+        const { stdout } = await execAsync('which agent-relay');
+        agentRelayPath = stdout.trim();
+        if (debug) console.log(`[spawner:debug] Found agent-relay at: ${agentRelayPath}`);
+      } catch {
+        // Fallback to npx if which fails
+        agentRelayPath = 'npx agent-relay';
+        if (debug) console.log(`[spawner:debug] Using npx fallback`);
+      }
+
+      // Add --dangerously-skip-permissions for Claude agents to avoid permission dialogs
+      const isClaudeCli = cli.startsWith('claude');
+      const cliWithFlags = isClaudeCli ? `${cli} --dangerously-skip-permissions` : cli;
+      const cmd = `unset TMUX && ${agentRelayPath} -n ${name} ${cliWithFlags}`;
+      if (debug) console.log(`[spawner:debug] Agent command: ${cmd}`);
+
+      // Send the command
+      const sendCmd = `tmux send-keys -t ${this.tmuxSession}:${windowName} '${cmd}' Enter`;
+      if (debug) console.log(`[spawner:debug] Sending: ${sendCmd}`);
+      await execAsync(sendCmd);
+
+      // Wait for the agent to register with the daemon before injecting tasks
+      const registered = await this.waitForAgentRegistration(name, 30_000, 500);
+      if (!registered) {
+        const error = `Worker ${name} failed to register within 30s`;
+        console.error(`[spawner] ${error}`);
+        // Clean up the tmux window to avoid orphaned workers
+        await execAsync(`tmux kill-window -t ${this.tmuxSession}:${windowName}`).catch(() => {});
+        return {
+          success: false,
+          name,
+          error,
+        };
+      }
+
+      // Inject the initial task if provided
+      if (task && task.trim()) {
+        const escapedTask = escapeForTmux(task);
+        if (debug) console.log(`[spawner:debug] Injecting task: ${escapedTask.substring(0, 50)}...`);
+        await execAsync(
+          `tmux send-keys -t ${this.tmuxSession}:${windowName} -l "${escapedTask}"`
+        );
+        await sleep(100);
+        await execAsync(
+          `tmux send-keys -t ${this.tmuxSession}:${windowName} Enter`
+        );
+      }
+
+      // Track the worker
+      const workerInfo: WorkerInfo = {
+        name,
+        cli,
+        task,
+        spawnedBy: requestedBy,
+        spawnedAt: Date.now(),
+        window: `${this.tmuxSession}:${windowName}`,
+      };
+      this.activeWorkers.set(name, workerInfo);
+
+      console.log(`[spawner] Spawned ${name} (${cli}) for ${requestedBy}`);
+
+      return {
+        success: true,
+        name,
+        window: workerInfo.window,
+      };
+    } catch (err: any) {
+      console.error(`[spawner] Failed to spawn ${name}:`, err.message);
+      if (debug) console.error(`[spawner:debug] Full error:`, err);
+      return {
+        success: false,
+        name,
+        error: err.message,
+      };
+    }
+  }
+
+  /**
+   * Release (terminate) a worker
+   */
+  async release(name: string): Promise<boolean> {
+    const worker = this.activeWorkers.get(name);
+    if (!worker) {
+      console.log(`[spawner] Worker ${name} not found`);
+      return false;
+    }
+
+    try {
+      // Send exit command gracefully
+      await execAsync(
+        `tmux send-keys -t ${worker.window} '/exit' Enter`
+      ).catch(() => {});
+
+      // Wait a bit for graceful shutdown
+      await sleep(2000);
+
+      // Kill the window
+      await execAsync(
+        `tmux kill-window -t ${worker.window}`
+      ).catch(() => {});
+
+      this.activeWorkers.delete(name);
+      console.log(`[spawner] Released ${name}`);
+
+      return true;
+    } catch (err: any) {
+      console.error(`[spawner] Failed to release ${name}:`, err.message);
+      // Still remove from tracking
+      this.activeWorkers.delete(name);
+      return false;
+    }
+  }
+
+  /**
+   * Release all workers
+   */
+  async releaseAll(): Promise<void> {
+    const workers = Array.from(this.activeWorkers.keys());
+    for (const name of workers) {
+      await this.release(name);
+    }
+  }
+
+  /**
+   * Get all active workers
+   */
+  getActiveWorkers(): WorkerInfo[] {
+    return Array.from(this.activeWorkers.values());
+  }
+
+  /**
+   * Check if a worker exists
+   */
+  hasWorker(name: string): boolean {
+    return this.activeWorkers.has(name);
+  }
+
+  /**
+   * Get worker info
+   */
+  getWorker(name: string): WorkerInfo | undefined {
+    return this.activeWorkers.get(name);
+  }
+
+  /**
+   * Wait for an agent to appear in the registry (agents.json)
+   */
+  private async waitForAgentRegistration(
+    name: string,
+    timeoutMs = 30_000,
+    pollIntervalMs = 500
+  ): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+      if (this.isAgentRegistered(name)) {
+        return true;
+      }
+
+      await sleep(pollIntervalMs);
+    }
+
+    return false;
+  }
+
+  private isAgentRegistered(name: string): boolean {
+    if (!this.agentsPath) return false;
+    if (!fs.existsSync(this.agentsPath)) return false;
+
+    try {
+      const raw = JSON.parse(fs.readFileSync(this.agentsPath, 'utf-8'));
+      const agents: Array<{ name?: string }> = Array.isArray(raw?.agents)
+        ? raw.agents
+        : raw?.agents && typeof raw.agents === 'object'
+          ? Object.values(raw.agents)
+          : [];
+
+      return agents.some((a) => a?.name === name);
+    } catch (err: any) {
+      console.error('[spawner] Failed to read agents registry:', err.message);
+      return false;
+    }
+  }
+}
diff --git a/src/bridge/types.ts b/src/bridge/types.ts
new file mode 100644
index 000000000..d8772f176
--- /dev/null
+++ b/src/bridge/types.ts
@@ -0,0 +1,60 @@
+/**
+ * Bridge Types
+ * Types for multi-project orchestration
+ */
+
+export interface ProjectConfig {
+  /** Absolute path to project root */
+  path: string;
+  /** Project identifier (derived from path hash) */
+  id: string;
+  /** Socket path for this project's daemon */
+  socketPath: string;
+  /** Lead agent name (auto-generated from dirname if not specified) */
+  leadName: string;
+  /** CLI tool to use (default: claude) */
+  cli: string;
+}
+
+export interface BridgeConfig {
+  /** Projects to bridge */
+  projects: ProjectConfig[];
+  /** CLI override for all projects */
+  cliOverride?: string;
+}
+
+export interface LeadInfo {
+  /** Lead agent name */
+  name: string;
+  /** Project this lead manages */
+  projectId: string;
+  /** Whether lead is currently connected */
+  connected: boolean;
+}
+
+export interface SpawnRequest {
+  /** Worker agent name */
+  name: string;
+  /** CLI tool (e.g., 'claude', 'claude:opus', 'codex') */
+  cli: string;
+  /** Initial task to inject */
+  task: string;
+  /** Who requested the spawn */
+  requestedBy: string;
+}
+
+export interface SpawnResult {
+  success: boolean;
+  name: string;
+  window?: string;
+  error?: string;
+}
+
+export interface WorkerInfo {
+  name: string;
+  cli: string;
+  task: string;
+  spawnedBy: string;
+  spawnedAt: number;
+  window: string;
+}
diff --git a/src/bridge/utils.test.ts b/src/bridge/utils.test.ts
new file mode 100644
index 000000000..a0d900723
--- /dev/null
+++ b/src/bridge/utils.test.ts
@@ -0,0 +1,98 @@
+/**
+ * Unit tests for Bridge Utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseTarget, escapeForShell, escapeForTmux } from './utils.js';
+
+describe('Bridge Utils', () => {
+  describe('parseTarget', () => {
+    it('parses project:agent format', () => {
+      const result = parseTarget('auth:Alice');
+      expect(result).toEqual({
+        projectId: 'auth',
+        agentName: 'Alice',
+      });
+    });
+
+    it('parses wildcard project', () => {
+      const result = parseTarget('*:lead');
+      expect(result).toEqual({
+        projectId: '*',
+        agentName: 'lead',
+      });
+    });
+
+    it('parses wildcard agent', () => {
+      const result = parseTarget('frontend:*');
+      expect(result).toEqual({
+        projectId: 'frontend',
+        agentName: '*',
+      });
+    });
+
+    it('parses double wildcard', () => {
+      const result = parseTarget('*:*');
+      expect(result).toEqual({
+        projectId: '*',
+        agentName: '*',
+      });
+    });
+
+    it('returns null for invalid format (no colon)', () => {
+      const result = parseTarget('invalidformat');
+      expect(result).toBeNull();
+    });
+
+    it('returns null for too many colons', () => {
+      const result = parseTarget('a:b:c');
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('escapeForShell', () => {
+    it('escapes backslashes', () => {
+      expect(escapeForShell('path\\to\\file')).toBe('path\\\\to\\\\file');
+    });
+
+    it('escapes double quotes', () => {
+      expect(escapeForShell('say "hello"')).toBe('say \\"hello\\"');
+    });
+
+    it('escapes dollar signs', () => {
+      expect(escapeForShell('$HOME/path')).toBe('\\$HOME/path');
+    });
+
+    it('escapes backticks', () => {
+      expect(escapeForShell('echo `date`')).toBe('echo \\`date\\`');
+    });
+
+    it('escapes exclamation marks', () => {
+      expect(escapeForShell('Hello!')).toBe('Hello\\!');
+    });
+
+    it('handles multiple special characters', () => {
+      expect(escapeForShell('$var "test" `cmd`')).toBe('\\$var \\"test\\" \\`cmd\\`');
+    });
+  });
+
+  describe('escapeForTmux', () => {
+    it('replaces newlines with spaces', () => {
+      expect(escapeForTmux('line1\nline2\nline3')).toBe('line1 line2 line3');
+    });
+
+    it('replaces carriage returns with spaces', () => {
+      expect(escapeForTmux('line1\r\nline2')).toBe('line1 line2');
+    });
+
+    it('escapes shell special characters', () => {
+      expect(escapeForTmux('$var')).toBe('\\$var');
+    });
+
+    it('handles complex input', () => {
+      const input = 'Hello\nWorld\r\n$test "quoted"';
+      const expected = 'Hello World \\$test \\"quoted\\"';
+      expect(escapeForTmux(input)).toBe(expected);
+    });
+  });
+});
diff --git a/src/bridge/utils.ts b/src/bridge/utils.ts
new file mode 100644
index 000000000..2eea34e32
--- /dev/null
+++ b/src/bridge/utils.ts
@@ -0,0 +1,59 @@
+/**
+ * Bridge Utilities
+ */
+
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+export const execAsync = promisify(exec);
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Parse a cross-project message target
+ * Formats:
+ *   "project:agent" -> { projectId: "project", agentName: "agent" }
+ *   "*:agent" -> { projectId: "*", agentName: "agent" } (all projects)
+ *   "project:*" -> { projectId: "project", agentName: "*" } (broadcast in project)
+ *   "*:*" -> { projectId: "*", agentName: "*" } (broadcast everywhere)
+ */
+export function parseTarget(target: string): { projectId: string; agentName: string } | null {
+  const parts = target.split(':');
+  if (parts.length !== 2) {
+    return null;
+  }
+  return {
+    projectId: parts[0],
+    agentName: parts[1],
+  };
+}
+
+/**
+ * Escape string for shell
+ */
+export function escapeForShell(str: string): string {
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, '\\$')
+    .replace(/`/g, '\\`')
+    .replace(/!/g, '\\!');
+}
+
+/**
+ * Escape string for tmux send-keys
+ */
+export function escapeForTmux(str: string): string {
+  return str
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, '\\$')
+    .replace(/`/g, '\\`')
+    .replace(/!/g, '\\!');
+}
diff --git a/src/cli/index.test.ts b/src/cli/index.test.ts
new file mode 100644
index 000000000..4be6881b5
--- /dev/null
+++ b/src/cli/index.test.ts
@@ -0,0 +1,199 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+
+const execAsync = promisify(exec);
+
+// Path to the compiled CLI
+const CLI_PATH = path.resolve(__dirname, '../../dist/cli/index.js');
+
+// Helper to run CLI commands
+async function runCli(args: string): Promise<{ stdout: string; stderr: string; code: number }> {
+  try {
+    const { stdout, stderr } = await execAsync(`node ${CLI_PATH} ${args}`, {
+      env: { ...process.env, DOTENV_CONFIG_QUIET: 'true' },
+    });
+    return { stdout, stderr, code: 0 };
+  } catch (err: any) {
+    return {
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      code: err.code || 1,
+    };
+  }
+}
+
+describe('CLI', () => {
+  describe('version', () => {
+    it('should show version', async () => {
+      const { stdout } = await runCli('version');
+      expect(stdout).toMatch(/agent-relay v\d+\.\d+\.\d+/);
+    });
+
+    it('should show version with -V flag', async () => {
+      const { stdout } = await runCli('-V');
+      expect(stdout).toMatch(/\d+\.\d+\.\d+/);
+    });
+  });
+
+  describe('help', () => {
+    it('should show help with --help', async () => {
+      const { stdout } = await runCli('--help');
+      expect(stdout).toContain('agent-relay');
+      expect(stdout).toContain('up');
+      expect(stdout).toContain('down');
+      expect(stdout).toContain('status');
+      expect(stdout).toContain('agents');
+      expect(stdout).toContain('who');
+      // gc is hidden (agent-only command)
+    });
+
+    it('should show help when no args', async () => {
+      const { stdout } = await runCli('');
+      expect(stdout).toContain('Usage:');
+    });
+  });
+
+  describe('status', () => {
+    it('should show status when daemon not running', async () => {
+      // This test assumes daemon isn't running on a test socket
+      const { stdout } = await runCli('status');
+      expect(stdout).toMatch(/Status:/i);
+    });
+  });
+
+  describe('gc', () => {
+    it('should show help for gc command', async () => {
+      const { stdout } = await runCli('gc --help');
+      expect(stdout).toContain('orphaned');
+      expect(stdout).toContain('--dry-run');
+      expect(stdout).toContain('--force');
+    });
+
+    it('should handle gc with no sessions', async () => {
+      // In test environment, likely no relay sessions
+      const { stdout } = await runCli('gc --dry-run');
+      expect(stdout).toMatch(/(No relay tmux sessions|orphaned|session)/i);
+    });
+  });
+
+  describe('agents', () => {
+    it('should handle no agents file gracefully', async () => {
+      const { stdout } = await runCli('agents');
+      // Either shows "No agents" message OR a table with NAME/STATUS headers
+      expect(stdout).toMatch(/(No agents|NAME.*STATUS)/i);
+    });
+
+    it('should support --json flag', async () => {
+      const { stdout } = await runCli('agents --json');
+      // Should be valid JSON (empty array or agent list)
+      expect(() => JSON.parse(stdout)).not.toThrow();
+    });
+  });
+
+  describe('who', () => {
+    it('should handle no active agents gracefully', async () => {
+      const { stdout } = await runCli('who');
+      expect(stdout).toMatch(/(No active agents|NAME)/i);
+    });
+
+    it('should support --json flag', async () => {
+      const { stdout } = await runCli('who --json');
+      expect(() => JSON.parse(stdout)).not.toThrow();
+    });
+  });
+
+  describe('read', () => {
+    it('should error when message not found', async () => {
+      const { stderr, code } = await runCli('read nonexistent-message-id');
+      expect(code).not.toBe(0);
+      expect(stderr).toContain('not found');
+    });
+  });
+
+  describe('attach', () => {
+    it('should show help for attach command', async () => {
+      const { stdout } = await runCli('attach --help');
+      expect(stdout).toContain('Attach to a running agent session');
+      expect(stdout).toContain('<name>');
+    });
+
+    it('should error when session does not exist', async () => {
+      const { stderr, code } = await runCli('attach nonexistent-agent');
+      expect(code).not.toBe(0);
+      expect(stderr).toContain('No session found');
+    });
+  });
+
+  describe('kill', () => {
+    it('should show help for kill command', async () => {
+      const { stdout } = await runCli('kill --help');
+      expect(stdout).toContain('Stop a detached agent');
+      expect(stdout).toContain('<name>');
+      expect(stdout).toContain('--force');
+    });
+
+    it('should handle killing nonexistent agent gracefully', async () => {
+      const { stdout } = await runCli('kill nonexistent-agent-12345');
+      expect(stdout).toContain('No running agent found');
+    });
+  });
+
+  describe('detach flag', () => {
+    it('should show -d/--detach in help', async () => {
+      const { stdout } = await runCli('--help');
+      expect(stdout).toContain('-d, --detach');
+      expect(stdout).toContain('background');
+    });
+  });
+
+  describe('history', () => {
+    it('should show history or empty message', async () => {
+      const { stdout, code } = await runCli('history --limit 5');
+      // Should either show messages or "No messages found"
+      expect(code).toBe(0);
+      expect(stdout.length).toBeGreaterThan(0);
+    });
+
+    it('should support --json flag', async () => {
+      const { stdout } = await runCli('history --json --limit 1');
+      expect(() => JSON.parse(stdout)).not.toThrow();
+    });
+  });
+});
+
+describe('CLI Helper Functions', () => {
+  describe('discoverRelaySessions', () => {
+    // These are integration tests that would need tmux running
+    // Skipping in CI but useful for local development
+    it.skip('should discover relay-* tmux sessions', async () => {
+      // Would need to mock tmux or have it running
+    });
+  });
+
+  describe('formatRelativeTime', () => {
+    // Test the time formatting logic indirectly through agents command
+    it('should format relative times in agents output', async () => {
+      const { stdout } = await runCli('agents');
+      // If agents exist, should show relative time
+      if (stdout.includes('ago')) {
+        expect(stdout).toMatch(/\d+[smhd] ago/);
+      }
+    });
+  });
+
+  describe('parseSince', () => {
+    // Test through history command
+    it('should parse duration strings', async () => {
+      // These should not error
+      const { code: code1 } = await runCli('history --since 1h');
+      const { code: code2 } = await runCli('history --since 30m');
+      const { code: code3 } = await runCli('history --since 7d');
+      // Commands should execute (might have no results, but shouldn't crash)
+      expect([0, code1]).toContain(code1);
+    });
+  });
+});
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 1b4be25b4..cd72a6aeb 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -7,11 +7,13 @@
  *   relay -n Name cmd   - Wrap with specific agent name
  *   relay up            - Start daemon + dashboard
  *   relay read <id>     - Read full message by ID
+ *   relay agents        - List connected agents
+ *   relay who           - Show currently active agents
  */
 
 import { Command } from 'commander';
 import { config as dotenvConfig } from 'dotenv';
-import { Daemon, DEFAULT_SOCKET_PATH } from '../daemon/server.js';
+import { Daemon } from '../daemon/server.js';
 import { RelayClient } from '../wrapper/client.js';
 import { generateAgentName } from '../utils/name-generator.js';
 import fs from 'node:fs';
@@ -47,7 +49,8 @@ program
 program
   .option('-n, --name <name>', 'Agent name (auto-generated if not set)')
   .option('-q, --quiet', 'Disable debug output', false)
-  .option('--prefix <pattern>', 'Relay prefix pattern (default: @relay: or >> for Gemini)')
+  .option('-d, --detach', 'Start agent in background (detached mode)')
+  .option('--prefix <pattern>', 'Relay prefix pattern (default: ->relay:)')
   .argument('[command...]', 'Command to wrap (e.g., claude)')
   .action(async (commandParts, options) => {
     // If no command provided, show help
@@ -56,24 +59,75 @@ program
       return;
     }
 
-    const { getProjectPaths } = await import('../utils/project-namespace.js');
-    const paths = getProjectPaths();
+    const { ensureProjectDir } = await import('../utils/project-namespace.js');
+    const { findAgentConfig, isClaudeCli, buildClaudeArgs } = await import('../utils/agent-config.js');
+    const paths = ensureProjectDir();
 
     const [mainCommand, ...commandArgs] = commandParts;
     const agentName = options.name ?? generateAgentName();
 
+    // Handle detached mode - spawn daemon and exit
+    const isDaemonProcess = process.argv.includes('--_daemon');
+    if (options.detach && !isDaemonProcess) {
+      const { spawn } = await import('node:child_process');
+
+      // Build args for the daemon process
+      const daemonArgs = [
+        ...process.argv.slice(2).filter(a => a !== '-d' && a !== '--detach'),
+        '--_daemon',
+        '-n', agentName, // Ensure same name is used
+      ];
+
+      // Spawn detached process
+      const child = spawn(process.argv[0], [process.argv[1], ...daemonArgs], {
+        detached: true,
+        stdio: 'ignore',
+        cwd: process.cwd(),
+        env: process.env,
+      });
+
+      // Write PID file for the wrapper
+      const wrapperPidPath = path.join(paths.dataDir, `wrapper-${agentName}.pid`);
+      fs.writeFileSync(wrapperPidPath, String(child.pid));
+
+      child.unref();
+
+      console.log(`Agent: ${agentName}`);
+      console.log(`Project: ${paths.projectId}`);
+      console.log(`Started in detached mode (PID: ${child.pid})`);
+      console.log(`Attach with: agent-relay attach ${agentName}`);
+      console.log(`Stop with:   agent-relay kill ${agentName}`);
+      return;
+    }
+
     console.error(`Agent: ${agentName}`);
     console.error(`Project: ${paths.projectId}`);
 
+    // Auto-detect agent config and inject --model/--agent for Claude CLI
+    let finalArgs = commandArgs;
+    if (isClaudeCli(mainCommand)) {
+      const config = findAgentConfig(agentName, paths.projectRoot);
+      if (config) {
+        console.error(`Agent config: ${config.configPath}`);
+        if (config.model) {
+          console.error(`Model: ${config.model}`);
+        }
+        finalArgs = buildClaudeArgs(agentName, commandArgs, paths.projectRoot);
+      }
+    }
+
     const { TmuxWrapper } = await import('../wrapper/tmux-wrapper.js');
 
     const wrapper = new TmuxWrapper({
       name: agentName,
       command: mainCommand,
-      args: commandArgs,
+      args: finalArgs,
       socketPath: paths.socketPath,
-      debug: !options.quiet,
+      debug: false,  // Use -q to keep quiet (debug off by default)
       relayPrefix: options.prefix,
+      useInbox: true,
+      inboxDir: paths.dataDir, // Use the project-specific data directory for the inbox
+      detached: isDaemonProcess, // Don't attach if running as daemon
     });
 
     process.on('SIGINT', () => {
@@ -81,9 +135,98 @@ program
       process.exit(0);
     });
 
+    process.on('SIGTERM', () => {
+      wrapper.stop();
+      process.exit(0);
+    });
+
     await wrapper.start();
   });
 
+// Team config types
+interface TeamAgent {
+  name: string;
+  cli: string;
+  role?: string;
+}
+
+interface TeamConfig {
+  team?: string;
+  agents: TeamAgent[];
+  autoSpawn?: boolean;
+}
+
+// Load teams.json from project root or .agent-relay/
+function loadTeamConfig(projectRoot: string): TeamConfig | null {
+  const locations = [
+    path.join(projectRoot, 'teams.json'),
+    path.join(projectRoot, '.agent-relay', 'teams.json'),
+  ];
+
+  for (const configPath of locations) {
+    if (fs.existsSync(configPath)) {
+      try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        return JSON.parse(content) as TeamConfig;
+      } catch (err) {
+        console.error(`Failed to parse ${configPath}:`, err);
+      }
+    }
+  }
+  return null;
+}
+
+// Spawn agents from team config using tmux
+async function spawnTeamAgents(
+  agents: TeamAgent[],
+  socketPath: string,
+  dataDir: string,
+  projectRoot: string,
+  relayPrefix?: string
+): Promise<void> {
+  const { TmuxWrapper } = await import('../wrapper/tmux-wrapper.js');
+  const { findAgentConfig, isClaudeCli, buildClaudeArgs } = await import('../utils/agent-config.js');
+
+  for (const agent of agents) {
+    console.log(`Spawning agent: ${agent.name} (${agent.cli})`);
+
+    // Parse CLI - handle "claude:opus" format
+    const [mainCommand, ...cliArgs] = agent.cli.split(/\s+/);
+
+    // Auto-detect agent config and inject --model/--agent for Claude CLI
+    let finalArgs = cliArgs;
+    if (isClaudeCli(mainCommand)) {
+      const config = findAgentConfig(agent.name, projectRoot);
+      if (config) {
+        console.log(`  Agent config: ${config.configPath}`);
+        if (config.model) {
+          console.log(`  Model: ${config.model}`);
+        }
+        finalArgs = buildClaudeArgs(agent.name, cliArgs, projectRoot);
+      }
+    }
+
+    const wrapper = new TmuxWrapper({
+      name: agent.name,
+      command: mainCommand,
+      args: finalArgs,
+      socketPath,
+      debug: false,
+      relayPrefix,
+      useInbox: true,
+      inboxDir: dataDir,
+      // Note: agents run in tmux which is already background/detached
+    });
+
+    try {
+      await wrapper.start();
+      console.log(`  Started: ${agent.name}`);
+    } catch (err) {
+      console.error(`  Failed to start ${agent.name}:`, err);
+    }
+  }
+}
+
 // up - Start daemon + dashboard
 program
   .command('up')
@@ -91,7 +234,7 @@ program
   .option('--no-dashboard', 'Disable web dashboard')
   .option('--port <port>', 'Dashboard port', DEFAULT_DASHBOARD_PORT)
   .action(async (options) => {
-    const { ensureProjectDir } = await import('../utils/project-namespace.js');
+    const { getProjectPaths, ensureProjectDir } = await import('../utils/project-namespace.js');
 
     const paths = ensureProjectDir();
     const socketPath = paths.socketPath;
@@ -127,7 +270,14 @@ program
       if (options.dashboard !== false) {
         const port = parseInt(options.port, 10);
         const { startDashboard } = await import('../dashboard/server.js');
-        const actualPort = await startDashboard(port, paths.teamDir, dbPath);
+        const actualPort = await startDashboard({
+          port,
+          dataDir: paths.dataDir,
+          teamDir: paths.teamDir,
+          dbPath,
+          enableSpawner: true,
+          projectRoot: paths.projectRoot,
+        });
         console.log(`Dashboard: http://localhost:${actualPort}`);
       }
 
@@ -196,6 +346,159 @@ program
     }
   });
 
+// attach - Attach to a running agent's tmux session
+program
+  .command('attach')
+  .description('Attach to a running agent session')
+  .argument('<name>', 'Agent name to attach to')
+  .action(async (name) => {
+    const sessionName = `relay-${name}`;
+
+    // Check if session exists
+    try {
+      await execAsync(`tmux has-session -t ${sessionName} 2>/dev/null`);
+    } catch {
+      console.error(`No session found for agent: ${name}`);
+      console.error(`Run 'agent-relay status' to see available sessions.`);
+      process.exit(1);
+    }
+
+    // Attach to the session
+    const { spawn } = await import('node:child_process');
+    const attach = spawn('tmux', ['attach-session', '-t', sessionName], {
+      stdio: 'inherit',
+    });
+
+    attach.on('exit', (code) => {
+      process.exit(code ?? 0);
+    });
+
+    attach.on('error', (err) => {
+      console.error(`Failed to attach: ${err.message}`);
+      process.exit(1);
+    });
+  });
+
+// kill - Stop a detached agent
+program
+  .command('kill')
+  .description('Stop a detached agent and its tmux session')
+  .argument('<name>', 'Agent name to kill')
+  .option('--force', 'Force kill without confirmation')
+  .action(async (name, options) => {
+    const { getProjectPaths } = await import('../utils/project-namespace.js');
+    const paths = getProjectPaths();
+
+    const sessionName = `relay-${name}`;
+    const wrapperPidPath = path.join(paths.dataDir, `wrapper-${name}.pid`);
+
+    let killed = false;
+
+    // Kill the wrapper process if PID file exists
+    if (fs.existsSync(wrapperPidPath)) {
+      const pid = Number(fs.readFileSync(wrapperPidPath, 'utf-8').trim());
+      try {
+        process.kill(pid, 'SIGTERM');
+        console.log(`Stopped wrapper process (PID: ${pid})`);
+        killed = true;
+      } catch {
+        // Process may already be dead
+      }
+      fs.unlinkSync(wrapperPidPath);
+    }
+
+    // Kill the tmux session
+    try {
+      await execAsync(`tmux kill-session -t ${sessionName}`);
+      console.log(`Killed tmux session: ${sessionName}`);
+      killed = true;
+    } catch {
+      // Session may not exist
+    }
+
+    if (!killed) {
+      console.log(`No running agent found: ${name}`);
+    }
+  });
+
+// agents - List connected agents (from registry file)
+program
+  .command('agents')
+  .description('List connected agents')
+  .option('--all', 'Include internal/CLI agents')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    const { getProjectPaths } = await import('../utils/project-namespace.js');
+    const paths = getProjectPaths();
+    const agentsPath = path.join(paths.teamDir, 'agents.json');
+
+    const allAgents = loadAgents(agentsPath);
+    const agents = options.all
+      ? allAgents
+      : allAgents.filter(isVisibleAgent);
+
+    if (options.json) {
+      console.log(JSON.stringify(agents.map(a => ({ ...a, status: getAgentStatus(a) })), null, 2));
+      return;
+    }
+
+    if (!agents.length) {
+      const hint = options.all ? '' : ' (use --all to include internal/cli agents)';
+      console.log(`No agents found. Ensure the daemon is running and agents are connected${hint}.`);
+      return;
+    }
+
+    console.log('NAME            STATUS   CLI       LAST SEEN');
+    console.log('---------------------------------------------');
+    agents.forEach((agent) => {
+      const name = (agent.name ?? 'unknown').padEnd(15);
+      const status = getAgentStatus(agent).padEnd(8);
+      const cli = (agent.cli ?? '-').padEnd(8);
+      const lastSeen = formatRelativeTime(agent.lastSeen);
+      console.log(`${name} ${status} ${cli} ${lastSeen}`);
+    });
+  });
+
+// who - Show currently active agents (online within last 30s)
+program
+  .command('who')
+  .description('Show currently active agents (last seen within 30 seconds)')
+  .option('--all', 'Include internal/CLI agents')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    const { getProjectPaths } = await import('../utils/project-namespace.js');
+    const paths = getProjectPaths();
+    const agentsPath = path.join(paths.teamDir, 'agents.json');
+
+    const allAgents = loadAgents(agentsPath);
+    const visibleAgents = options.all
+      ? allAgents
+      : allAgents.filter(a => !isInternalAgent(a.name));
+
+    const onlineAgents = visibleAgents.filter(isAgentOnline);
+
+    if (options.json) {
+      console.log(JSON.stringify(onlineAgents.map(a => ({ ...a, status: getAgentStatus(a) })), null, 2));
+      return;
+    }
+
+    if (!onlineAgents.length) {
+      const hint = options.all ? '' : ' (use --all to include internal/cli agents)';
+      console.log(`No active agents found${hint}.`);
+      return;
+    }
+
+    console.log('NAME            STATUS   CLI       LAST SEEN');
+    console.log('---------------------------------------------');
+    onlineAgents.forEach((agent) => {
+      const name = (agent.name ?? 'unknown').padEnd(15);
+      const status = getAgentStatus(agent).padEnd(8);
+      const cli = (agent.cli ?? '-').padEnd(8);
+      const lastSeen = formatRelativeTime(agent.lastSeen);
+      console.log(`${name} ${status} ${cli} ${lastSeen}`);
+    });
+  });
+
 // read - Read full message by ID (for truncated messages)
 program
   .command('read')
@@ -227,6 +530,68 @@ program
     await adapter.close?.();
   });
 
+// ============================================
+// Hidden commands (for agents, not in --help)
+// ============================================
+
+// history - Show recent messages (hidden from help, for agent use)
+program
+  .command('history', { hidden: true })
+  .description('Show recent messages')
+  .option('-n, --limit <count>', 'Number of messages to show', '50')
+  .option('-f, --from <agent>', 'Filter by sender')
+  .option('-t, --to <agent>', 'Filter by recipient')
+  .option('--since <time>', 'Since time (e.g., "1h", "2024-01-01")')
+  .option('--json', 'Output as JSON')
+  .action(async (options: { limit?: string; from?: string; to?: string; since?: string; json?: boolean }) => {
+    const { getProjectPaths } = await import('../utils/project-namespace.js');
+    const { createStorageAdapter } = await import('../storage/adapter.js');
+
+    const paths = getProjectPaths();
+    const adapter = await createStorageAdapter(paths.dbPath);
+    const limit = Number.parseInt(options.limit ?? '50', 10) || 50;
+    const sinceTs = parseSince(options.since);
+
+    try {
+      const messages = await adapter.getMessages({
+        limit,
+        from: options.from,
+        to: options.to,
+        sinceTs,
+        order: 'desc',
+      });
+
+      if (options.json) {
+        const payload = messages.map((m) => ({
+          id: m.id,
+          ts: m.ts,
+          timestamp: new Date(m.ts).toISOString(),
+          from: m.from,
+          to: m.to,
+          topic: m.topic,
+          thread: m.thread,
+          kind: m.kind,
+          body: m.body,
+        }));
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      if (!messages.length) {
+        console.log('No messages found.');
+        return;
+      }
+
+      messages.forEach((msg) => {
+        const ts = new Date(msg.ts).toISOString();
+        const body = msg.body.length > 120 ? `${msg.body.slice(0, 117)}...` : msg.body;
+        console.log(`${ts} ${msg.from} -> ${msg.to}:${body}`);
+      });
+    } finally {
+      await adapter.close?.();
+    }
+  });
+
 // version - Show version info
 program
   .command('version')
@@ -235,6 +600,406 @@ program
     console.log(`agent-relay v${VERSION}`);
   });
 
+// bridge - Multi-project orchestration
+program
+  .command('bridge')
+  .description('Bridge multiple projects as orchestrator')
+  .argument('[projects...]', 'Project paths to bridge')
+  .option('--cli <tool>', 'CLI tool override for all projects')
+  .action(async (projectPaths: string[], options) => {
+    const { resolveProjects, validateDaemons } = await import('../bridge/config.js');
+    const { MultiProjectClient } = await import('../bridge/multi-project-client.js');
+    const { getProjectPaths } = await import('../utils/project-namespace.js');
+    const fs = await import('node:fs');
+    const pathModule = await import('node:path');
+
+    // Resolve projects from args or config
+    const projects = resolveProjects(projectPaths, options.cli);
+
+    if (projects.length === 0) {
+      console.error('No projects specified.');
+      console.error('Usage: agent-relay bridge ~/project1 ~/project2');
+      console.error('   or: Create ~/.agent-relay/bridge.json with project config');
+      process.exit(1);
+    }
+
+    console.log('Bridge Mode - Multi-Project Orchestration');
+    console.log('─'.repeat(40));
+
+    // Check which daemons are running
+    const { valid, missing } = validateDaemons(projects);
+
+    if (missing.length > 0) {
+      console.error('\nMissing daemons for:');
+      for (const p of missing) {
+        console.error(`  - ${p.path}`);
+        console.error(`    Run: cd "${p.path}" && agent-relay up`);
+      }
+      console.error('');
+    }
+
+    if (valid.length === 0) {
+      console.error('No projects have running daemons. Start them first.');
+      process.exit(1);
+    }
+
+    console.log('\nConnecting to projects:');
+    for (const p of valid) {
+      console.log(`  - ${p.id} (${p.path})`);
+      console.log(`    Lead: ${p.leadName}, CLI: ${p.cli}`);
+    }
+    console.log('');
+
+    // Get data directories for ALL bridged projects (so each project's dashboard can show bridge state)
+    const bridgeStatePaths: string[] = valid.map(p => {
+      const projectPaths = getProjectPaths(p.path);
+      // Ensure directory exists
+      if (!fs.existsSync(projectPaths.dataDir)) {
+        fs.mkdirSync(projectPaths.dataDir, { recursive: true });
+      }
+      return pathModule.join(projectPaths.dataDir, 'bridge-state.json');
+    });
+
+    // Bridge state tracking
+    interface BridgeProject {
+      id: string;
+      name: string;
+      path: string;
+      connected: boolean;
+      reconnecting?: boolean;
+      lead?: { name: string; connected: boolean };
+      agents: Array<{ name: string; status: string; task?: string }>;
+    }
+    interface BridgeMessage {
+      id: string;
+      from: string;
+      to: string;
+      body: string;
+      sourceProject: string;
+      targetProject?: string;
+      timestamp: string;
+    }
+    interface BridgeState {
+      projects: BridgeProject[];
+      messages: BridgeMessage[];
+      connected: boolean;
+      startedAt: string;
+    }
+
+    const bridgeState: BridgeState = {
+      projects: valid.map(p => ({
+        id: p.id,
+        name: pathModule.basename(p.path),
+        path: p.path,
+        connected: false,
+        lead: { name: p.leadName, connected: false },
+        agents: [],
+      })),
+      messages: [],
+      connected: false,
+      startedAt: new Date().toISOString(),
+    };
+
+    // Write bridge state to ALL project data directories
+    const writeBridgeState = (): void => {
+      const stateJson = JSON.stringify(bridgeState, null, 2);
+      for (const statePath of bridgeStatePaths) {
+        try {
+          fs.writeFileSync(statePath, stateJson);
+        } catch (err) {
+          console.error(`[bridge] Failed to write state to ${statePath}:`, err);
+        }
+      }
+    };
+
+    // Initial state write
+    writeBridgeState();
+    console.log(`Bridge state written to ${bridgeStatePaths.length} project(s)`);
+
+    // Connect to all project daemons
+    const client = new MultiProjectClient(valid);
+
+    // Track connection state changes (daemon connection, not agent registration)
+    // Also track "reconnecting" state for UI feedback
+    const wasConnected = new Map<string, boolean>();
+
+    client.onProjectStateChange = (projectId, connected) => {
+      const project = bridgeState.projects.find(p => p.id === projectId);
+      if (project) {
+        const hadConnection = wasConnected.get(projectId) || false;
+        project.connected = connected;
+        // Set reconnecting if we lost connection (had it before, now disconnected)
+        project.reconnecting = !connected && hadConnection;
+        wasConnected.set(projectId, connected);
+        // Note: lead.connected should only be true when an actual lead agent registers
+        // The bridge connecting to daemon doesn't mean a lead agent is active
+      }
+      bridgeState.connected = bridgeState.projects.some(p => p.connected);
+      writeBridgeState();
+    };
+
+    try {
+      await client.connect();
+    } catch (err) {
+      console.error('Failed to connect to all projects');
+      writeBridgeState(); // Write final state before exit
+      process.exit(1);
+    }
+
+    bridgeState.connected = true;
+    writeBridgeState();
+
+    console.log('Connected to all projects.');
+    console.log('');
+    console.log('Cross-project messaging:');
+    console.log('  @relay:projectId:agent Message');
+    console.log('  @relay:*:lead Broadcast to all leads');
+    console.log('');
+
+    // Handle messages from projects
+    client.onMessage = (projectId, from, payload, messageId) => {
+      console.log(`[${projectId}] ${from}: ${payload.body.substring(0, 80)}...`);
+
+      // Track message in bridge state
+      bridgeState.messages.push({
+        id: messageId,
+        from,
+        to: '*', // Incoming messages are from agents
+        body: payload.body,
+        sourceProject: projectId,
+        timestamp: new Date().toISOString(),
+      });
+
+      // Keep last 100 messages
+      if (bridgeState.messages.length > 100) {
+        bridgeState.messages = bridgeState.messages.slice(-100);
+      }
+
+      writeBridgeState();
+    };
+
+    // Clean up on exit
+    const cleanup = (): void => {
+      bridgeState.connected = false;
+      bridgeState.projects.forEach(p => {
+        p.connected = false;
+        if (p.lead) p.lead.connected = false;
+      });
+      writeBridgeState();
+    };
+
+    // Keep running
+    process.on('SIGINT', () => {
+      console.log('\nDisconnecting...');
+      cleanup();
+      client.disconnect();
+      process.exit(0);
+    });
+
+    // Start a simple REPL for sending messages
+    const readline = await import('node:readline');
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    console.log('Enter messages as: projectId:agent message');
+    console.log('Or: *:lead message (broadcast to all leads)');
+    console.log('Type "quit" to exit.\n');
+
+    const promptForInput = (): void => {
+      rl.question('> ', (input) => {
+        if (input.toLowerCase() === 'quit') {
+          client.disconnect();
+          rl.close();
+          process.exit(0);
+        }
+
+        // Parse input: projectId:agent message
+        const match = input.match(/^(\S+):(\S+)\s+(.+)$/);
+        if (match) {
+          const [, projectId, agent, message] = match;
+          if (projectId === '*' && agent === 'lead') {
+            client.broadcastToLeads(message);
+            console.log('→ Broadcast to all leads');
+          } else if (projectId === '*') {
+            client.broadcastAll(message);
+            console.log('→ Broadcast to all');
+          } else {
+            const sent = client.sendToProject(projectId, agent, message);
+            if (sent) {
+              console.log(`→ ${projectId}:${agent}`);
+            }
+          }
+        } else {
+          console.log('Format: projectId:agent message');
+        }
+
+        promptForInput();
+      });
+    };
+
+    promptForInput();
+  });
+
+// lead - Start as project lead with spawn capability
+program
+  .command('lead')
+  .description('Start as project lead with spawn capability')
+  .argument('<name>', 'Your agent name')
+  .argument('[cli]', 'CLI tool to use', 'claude')
+  .action(async (name: string, cli: string) => {
+    const { getProjectPaths } = await import('../utils/project-namespace.js');
+    const { AgentSpawner } = await import('../bridge/spawner.js');
+    const { TmuxWrapper } = await import('../wrapper/tmux-wrapper.js');
+    const { findAgentConfig, isClaudeCli, buildClaudeArgs } = await import('../utils/agent-config.js');
+
+    const paths = getProjectPaths();
+
+    console.log('Lead Mode - Project Lead with Spawn Capability');
+    console.log('─'.repeat(40));
+    console.log(`Agent: ${name}`);
+    console.log(`Project: ${paths.projectId}`);
+    console.log(`CLI: ${cli}`);
+
+    // Create spawner for this project
+    const spawner = new AgentSpawner(paths.projectRoot);
+
+    // Parse CLI - split on whitespace for args
+    const [mainCommand, ...cliArgs] = cli.split(/\s+/);
+
+    // Auto-detect agent config and inject --model/--agent for Claude CLI
+    let finalArgs = cliArgs;
+    if (isClaudeCli(mainCommand)) {
+      const config = findAgentConfig(name, paths.projectRoot);
+      if (config) {
+        console.log(`Agent config: ${config.configPath}`);
+        if (config.model) {
+          console.log(`Model: ${config.model}`);
+        }
+        finalArgs = buildClaudeArgs(name, cliArgs, paths.projectRoot);
+      }
+    }
+
+    console.log('');
+    console.log('Spawn workers with:');
+    console.log('  ->relay:spawn WorkerName cli "task"');
+    console.log('Release workers with:');
+    console.log('  ->relay:release WorkerName');
+    console.log('');
+
+    const wrapper = new TmuxWrapper({
+      name,
+      command: mainCommand,
+      args: finalArgs.length > 0 ? finalArgs : undefined,
+      socketPath: paths.socketPath,
+      debug: true,
+      // Wire up spawn/release callbacks
+      onSpawn: async (workerName: string, workerCli: string, task: string) => {
+        console.log(`[lead] Spawning ${workerName} (${workerCli})...`);
+        const result = await spawner.spawn({
+          name: workerName,
+          cli: workerCli,
+          task,
+          requestedBy: name,
+        });
+        if (result.success) {
+          console.log(`[lead] ✓ Spawned ${workerName} in ${result.window}`);
+        } else {
+          console.error(`[lead] ✗ Failed to spawn ${workerName}: ${result.error}`);
+        }
+      },
+      onRelease: async (workerName: string) => {
+        console.log(`[lead] Releasing ${workerName}...`);
+        const released = await spawner.release(workerName);
+        if (released) {
+          console.log(`[lead] ✓ Released ${workerName}`);
+        } else {
+          console.error(`[lead] ✗ Worker ${workerName} not found`);
+        }
+      },
+    });
+
+    process.on('SIGINT', async () => {
+      console.log('\nReleasing workers...');
+      await spawner.releaseAll();
+      wrapper.stop();
+      process.exit(0);
+    });
+
+    await wrapper.start();
+  });
+
+// gc - Clean up orphaned tmux sessions (hidden - for agent use)
+program
+  .command('gc', { hidden: true })
+  .description('Clean up orphaned tmux sessions (sessions with no connected agent)')
+  .option('--dry-run', 'Show what would be cleaned without actually doing it')
+  .option('--force', 'Kill all relay sessions regardless of connection status')
+  .action(async (options: { dryRun?: boolean; force?: boolean }) => {
+    const { getProjectPaths } = await import('../utils/project-namespace.js');
+    const paths = getProjectPaths();
+    const agentsPath = path.join(paths.teamDir, 'agents.json');
+
+    // Get all relay tmux sessions
+    const sessions = await discoverRelaySessions();
+    if (!sessions.length) {
+      console.log('No relay tmux sessions found.');
+      return;
+    }
+
+    // Get connected agents
+    const connectedAgents = new Set<string>();
+    if (!options.force) {
+      const agents = loadAgents(agentsPath);
+      // Consider an agent "connected" if last seen within 30 seconds
+      const staleThresholdMs = 30_000;
+      const now = Date.now();
+      agents.forEach(a => {
+        if (a.name && a.lastSeen) {
+          const lastSeenTs = Date.parse(a.lastSeen);
+          if (!Number.isNaN(lastSeenTs) && now - lastSeenTs < staleThresholdMs) {
+            connectedAgents.add(a.name);
+          }
+        }
+      });
+    }
+
+    // Find orphaned sessions
+    const orphaned = sessions.filter(s =>
+      options.force || (s.agentName && !connectedAgents.has(s.agentName))
+    );
+
+    if (!orphaned.length) {
+      console.log(`All ${sessions.length} session(s) have active agents.`);
+      return;
+    }
+
+    console.log(`Found ${orphaned.length} orphaned session(s):`);
+    for (const session of orphaned) {
+      console.log(`  - ${session.sessionName} (agent: ${session.agentName ?? 'unknown'})`);
+    }
+
+    if (options.dryRun) {
+      console.log('\nDry run - no sessions killed.');
+      return;
+    }
+
+    // Kill orphaned sessions
+    let killed = 0;
+    for (const session of orphaned) {
+      try {
+        await execAsync(`tmux kill-session -t ${session.sessionName}`);
+        killed++;
+        console.log(`Killed: ${session.sessionName}`);
+      } catch (err) {
+        console.error(`Failed to kill ${session.sessionName}: ${(err as Error).message}`);
+      }
+    }
+
+    console.log(`\nCleaned up ${killed}/${orphaned.length} session(s).`);
+  });
+
 interface RelaySessionInfo {
   sessionName: string;
   agentName?: string;
@@ -251,7 +1016,7 @@ async function discoverRelaySessions(): Promise<RelaySessionInfo[]> {
 
     const relaySessions = sessionNames
       .map(name => {
-        const match = name.match(/^relay-(.+)-\d+$/);
+        const match = name.match(/^relay-(.+)$/);
         if (!match) return undefined;
         return { sessionName: name, agentName: match[1] };
       })
@@ -292,4 +1057,364 @@ function logRelaySessions(sessions: RelaySessionInfo[]): void {
   });
 }
 
+interface RegistryAgent {
+  id?: string;
+  name?: string;
+  cli?: string;
+  workingDirectory?: string;
+  firstSeen?: string;
+  lastSeen?: string;
+  messagesSent?: number;
+  messagesReceived?: number;
+}
+
+function loadAgents(agentsPath: string): RegistryAgent[] {
+  if (!fs.existsSync(agentsPath)) {
+    return [];
+  }
+
+  try {
+    const raw = JSON.parse(fs.readFileSync(agentsPath, 'utf-8'));
+    const agentsArray = Array.isArray(raw?.agents)
+      ? raw.agents
+      : raw?.agents
+        ? Object.values(raw.agents)
+        : [];
+
+    return agentsArray
+      .filter((a: any) => a?.name)
+      .map((a: any) => ({
+        id: a.id,
+        name: a.name,
+        cli: a.cli,
+        workingDirectory: a.workingDirectory,
+        firstSeen: a.firstSeen,
+        lastSeen: a.lastSeen,
+        messagesSent: typeof a.messagesSent === 'number' ? a.messagesSent : 0,
+        messagesReceived: typeof a.messagesReceived === 'number' ? a.messagesReceived : 0,
+      }));
+  } catch (err) {
+    console.error('Failed to read agents.json:', (err as Error).message);
+    return [];
+  }
+}
+
+const STALE_THRESHOLD_MS = 30_000;
+
+// Internal agents that should be hidden from `agents` and `who` by default
+const INTERNAL_AGENTS = new Set(['cli', 'Dashboard']);
+
+function isInternalAgent(name: string | undefined): boolean {
+  if (!name) return true;
+  if (name.startsWith('__')) return true;
+  return INTERNAL_AGENTS.has(name);
+}
+
+function getAgentStatus(agent: RegistryAgent): 'ONLINE' | 'STALE' | 'UNKNOWN' {
+  if (!agent.lastSeen) return 'UNKNOWN';
+  const ts = Date.parse(agent.lastSeen);
+  if (Number.isNaN(ts)) return 'UNKNOWN';
+  return Date.now() - ts < STALE_THRESHOLD_MS ? 'ONLINE' : 'STALE';
+}
+
+function isAgentOnline(agent: RegistryAgent): boolean {
+  return getAgentStatus(agent) === 'ONLINE';
+}
+
+// Visible agents: not internal and not stale (used by `agents` command)
+function isVisibleAgent(agent: RegistryAgent): boolean {
+  if (isInternalAgent(agent.name)) return false;
+  if (getAgentStatus(agent) === 'STALE') return false;
+  return true;
+}
+
+function formatRelativeTime(iso?: string): string {
+  if (!iso) return 'unknown';
+  const ts = Date.parse(iso);
+  if (Number.isNaN(ts)) return 'unknown';
+  const diffMs = Date.now() - ts;
+  const diffSec = Math.floor(diffMs / 1000);
+  if (diffSec < 60) return `${diffSec}s ago`;
+  const diffMin = Math.floor(diffSec / 60);
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHours = Math.floor(diffMin / 60);
+  if (diffHours < 48) return `${diffHours}h ago`;
+  const diffDays = Math.floor(diffHours / 24);
+  return `${diffDays}d ago`;
+}
+
+function parseSince(input?: string): number | undefined {
+  if (!input) return undefined;
+  const trimmed = String(input).trim();
+  if (!trimmed) return undefined;
+
+  const durationMatch = trimmed.match(/^(-?\d+)([smhd])$/i);
+  if (durationMatch) {
+    const value = Number(durationMatch[1]);
+    const unit = durationMatch[2].toLowerCase();
+    const multipliers: Record<string, number> = {
+      s: 1000,
+      m: 60_000,
+      h: 3_600_000,
+      d: 86_400_000,
+    };
+    return Date.now() - value * multipliers[unit];
+  }
+
+  const parsed = Date.parse(trimmed);
+  if (Number.isNaN(parsed)) return undefined;
+  return parsed;
+}
+
+// ============================================
+// Spawn/Worker debugging commands
+// ============================================
+
+const WORKER_SESSION = 'relay-workers';
+
+// workers - List spawned workers
+program
+  .command('workers')
+  .description('List spawned worker agents (from tmux)')
+  .option('--json', 'Output as JSON')
+  .action(async (options: { json?: boolean }) => {
+    try {
+      // Check if worker session exists
+      try {
+        await execAsync(`tmux has-session -t ${WORKER_SESSION} 2>/dev/null`);
+      } catch {
+        if (options.json) {
+          console.log(JSON.stringify({ workers: [], session: null }));
+        } else {
+          console.log('No spawned workers (session does not exist)');
+        }
+        return;
+      }
+
+      // List windows in the worker session
+      const { stdout } = await execAsync(
+        `tmux list-windows -t ${WORKER_SESSION} -F "#{window_index}|#{window_name}|#{pane_current_command}|#{window_activity}"`
+      );
+
+      const workers = stdout
+        .split('\n')
+        .filter(Boolean)
+        .map(line => {
+          const [index, name, command, activity] = line.split('|');
+          const activityTs = parseInt(activity, 10) * 1000;
+          const lastActive = isNaN(activityTs) ? undefined : new Date(activityTs).toISOString();
+          return {
+            index: parseInt(index, 10),
+            name,
+            command,
+            lastActive,
+            window: `${WORKER_SESSION}:${name}`,
+          };
+        })
+        // Filter out the default zsh window
+        .filter(w => w.name !== 'zsh' && w.command !== 'zsh');
+
+      if (options.json) {
+        console.log(JSON.stringify({ workers, session: WORKER_SESSION }, null, 2));
+        return;
+      }
+
+      if (!workers.length) {
+        console.log('No spawned workers');
+        return;
+      }
+
+      console.log('SPAWNED WORKERS');
+      console.log('─'.repeat(50));
+      console.log('NAME            COMMAND       WINDOW');
+      console.log('─'.repeat(50));
+      workers.forEach(w => {
+        const name = w.name.padEnd(15);
+        const cmd = (w.command || '-').padEnd(12);
+        console.log(`${name} ${cmd}  ${w.window}`);
+      });
+      console.log('');
+      console.log('Commands:');
+      console.log('  agent-relay workers:logs <name>   - View worker output');
+      console.log('  agent-relay workers:attach <name> - Attach to worker tmux');
+      console.log('  agent-relay workers:kill <name>   - Kill a worker');
+    } catch (err) {
+      console.error('Failed to list workers:', (err as Error).message);
+    }
+  });
+
+// workers:logs - Show tmux pane output for a worker
+program
+  .command('workers:logs')
+  .description('Show recent output from a spawned worker')
+  .argument('<name>', 'Worker name')
+  .option('-n, --lines <n>', 'Number of lines to show', '50')
+  .option('-f, --follow', 'Follow output (like tail -f)')
+  .action(async (name: string, options: { lines?: string; follow?: boolean }) => {
+    const window = `${WORKER_SESSION}:${name}`;
+
+    try {
+      // Check if window exists
+      await execAsync(`tmux has-session -t ${window} 2>/dev/null`);
+    } catch {
+      console.error(`Worker "${name}" not found`);
+      console.log(`Run 'agent-relay workers' to see available workers`);
+      process.exit(1);
+    }
+
+    if (options.follow) {
+      console.log(`Following output from ${window} (Ctrl+C to stop)...`);
+      console.log('─'.repeat(50));
+
+      // Use a polling approach to follow
+      let lastContent = '';
+      const poll = async () => {
+        try {
+          const { stdout } = await execAsync(`tmux capture-pane -t ${window} -p -S -100`);
+          if (stdout !== lastContent) {
+            // Print only new lines
+            const newContent = stdout.replace(lastContent, '');
+            if (newContent.trim()) {
+              process.stdout.write(newContent);
+            }
+            lastContent = stdout;
+          }
+        } catch {
+          console.error('\nWorker disconnected');
+          process.exit(1);
+        }
+      };
+
+      const interval = setInterval(poll, 500);
+      process.on('SIGINT', () => {
+        clearInterval(interval);
+        console.log('\nStopped following');
+        process.exit(0);
+      });
+
+      await poll(); // Initial fetch
+      await new Promise(() => {}); // Keep running
+    } else {
+      try {
+        const lines = parseInt(options.lines || '50', 10);
+        const { stdout } = await execAsync(`tmux capture-pane -t ${window} -p -S -${lines}`);
+        console.log(`Output from ${window} (last ${lines} lines):`);
+        console.log('─'.repeat(50));
+        console.log(stdout || '(empty)');
+      } catch (err) {
+        console.error('Failed to capture output:', (err as Error).message);
+      }
+    }
+  });
+
+// workers:attach - Attach to a worker's tmux window
+program
+  .command('workers:attach')
+  .description('Attach to a spawned worker tmux window')
+  .argument('<name>', 'Worker name')
+  .action(async (name: string) => {
+    const window = `${WORKER_SESSION}:${name}`;
+
+    try {
+      // Check if window exists
+      await execAsync(`tmux has-session -t ${window} 2>/dev/null`);
+    } catch {
+      console.error(`Worker "${name}" not found`);
+      console.log(`Run 'agent-relay workers' to see available workers`);
+      process.exit(1);
+    }
+
+    console.log(`Attaching to ${window}...`);
+    console.log('(Use Ctrl+B D to detach)');
+
+    // Spawn tmux attach as a child process with stdio inherited
+    const { spawn } = await import('child_process');
+    const child = spawn('tmux', ['attach-session', '-t', window], {
+      stdio: 'inherit',
+    });
+
+    child.on('exit', (code) => {
+      process.exit(code || 0);
+    });
+  });
+
+// workers:kill - Kill a spawned worker
+program
+  .command('workers:kill')
+  .description('Kill a spawned worker')
+  .argument('<name>', 'Worker name')
+  .option('--force', 'Skip graceful shutdown, kill immediately')
+  .action(async (name: string, options: { force?: boolean }) => {
+    const window = `${WORKER_SESSION}:${name}`;
+
+    try {
+      // Check if window exists
+      await execAsync(`tmux has-session -t ${window} 2>/dev/null`);
+    } catch {
+      console.error(`Worker "${name}" not found`);
+      console.log(`Run 'agent-relay workers' to see available workers`);
+      process.exit(1);
+    }
+
+    if (!options.force) {
+      // Try graceful shutdown first
+      console.log(`Sending /exit to ${name}...`);
+      try {
+        await execAsync(`tmux send-keys -t ${window} '/exit' Enter`);
+        // Wait for graceful shutdown
+        await new Promise(r => setTimeout(r, 2000));
+      } catch {
+        // Ignore errors, will force kill below
+      }
+    }
+
+    // Kill the window
+    try {
+      await execAsync(`tmux kill-window -t ${window}`);
+      console.log(`Killed worker: ${name}`);
+    } catch (err) {
+      console.error(`Failed to kill ${name}:`, (err as Error).message);
+      process.exit(1);
+    }
+  });
+
+// workers:session - Show tmux session info
+program
+  .command('workers:session')
+  .description('Show worker tmux session details')
+  .action(async () => {
+    try {
+      // Check if session exists
+      try {
+        await execAsync(`tmux has-session -t ${WORKER_SESSION} 2>/dev/null`);
+      } catch {
+        console.log(`Session "${WORKER_SESSION}" does not exist`);
+        console.log('Spawn a worker to create it.');
+        return;
+      }
+
+      console.log(`Session: ${WORKER_SESSION}`);
+      console.log('─'.repeat(50));
+
+      // Get session info
+      const { stdout: sessionInfo } = await execAsync(
+        `tmux display-message -t ${WORKER_SESSION} -p "Created: #{session_created_string}\\nWindows: #{session_windows}\\nAttached: #{?session_attached,yes,no}"`
+      );
+      console.log(sessionInfo);
+
+      // List windows
+      console.log('\nWindows:');
+      const { stdout: windows } = await execAsync(
+        `tmux list-windows -t ${WORKER_SESSION} -F "  #{window_index}: #{window_name} (#{pane_current_command})"`
+      );
+      console.log(windows || '  (none)');
+
+      console.log('\nQuick commands:');
+      console.log(`  tmux attach -t ${WORKER_SESSION}     # Attach to session`);
+      console.log(`  tmux kill-session -t ${WORKER_SESSION}  # Kill entire session`);
+    } catch (err) {
+      console.error('Failed:', (err as Error).message);
+    }
+  });
+
 program.parse();
diff --git a/src/daemon/agent-registry.test.ts b/src/daemon/agent-registry.test.ts
new file mode 100644
index 000000000..a39445939
--- /dev/null
+++ b/src/daemon/agent-registry.test.ts
@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, it, expect } from 'vitest';
+import { AgentRegistry } from './registry.js';
+
+function makeTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'agent-registry-'));
+}
+
+describe('AgentRegistry', () => {
+  it('creates and persists agent records', () => {
+    const dir = makeTempDir();
+    const registry = new AgentRegistry(dir);
+
+    const created = registry.register({
+      name: 'alice',
+      cli: 'claude',
+      workingDirectory: '/tmp/alice',
+    });
+
+    expect(created.id).toBeTruthy();
+    expect(created.firstSeen).toBeTruthy();
+    expect(created.messagesSent).toBe(0);
+    expect(created.messagesReceived).toBe(0);
+
+    registry.recordSend('alice');
+    registry.recordReceive('alice');
+
+    const agentsPath = path.join(dir, 'agents.json');
+    const fileData = JSON.parse(fs.readFileSync(agentsPath, 'utf-8'));
+    const fileAgent = fileData.agents.find((a: any) => a.name === 'alice');
+    expect(fileAgent.messagesSent).toBe(1);
+    expect(fileAgent.messagesReceived).toBe(1);
+
+    const registryReloaded = new AgentRegistry(dir);
+    const [loaded] = registryReloaded.getAgents();
+    expect(loaded.name).toBe('alice');
+    expect(loaded.messagesSent).toBe(1);
+    expect(loaded.messagesReceived).toBe(1);
+  });
+
+  it('updates metadata on re-register', () => {
+    const dir = makeTempDir();
+    const registry = new AgentRegistry(dir);
+
+    registry.register({
+      name: 'bob',
+      cli: 'claude',
+      workingDirectory: '/tmp/one',
+    });
+    const first = registry.getAgents()[0];
+
+    registry.register({
+      name: 'bob',
+      cli: 'gemini',
+      workingDirectory: '/tmp/two',
+    });
+    const [updated] = registry.getAgents();
+
+    expect(updated.firstSeen).toBe(first.firstSeen);
+    expect(updated.cli).toBe('gemini');
+    expect(updated.workingDirectory).toBe('/tmp/two');
+    expect(new Date(updated.lastSeen).getTime()).toBeGreaterThanOrEqual(new Date(first.lastSeen).getTime());
+  });
+
+  it('handles malformed agents.json gracefully', () => {
+    const dir = makeTempDir();
+    const agentsPath = path.join(dir, 'agents.json');
+    fs.writeFileSync(agentsPath, '{bad json', 'utf-8');
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const registry = new AgentRegistry(dir);
+    expect(registry.getAgents()).toEqual([]);
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  it('logs write failures without throwing', () => {
+    const dir = makeTempDir();
+    const registry = new AgentRegistry(dir);
+    registry.register({ name: 'carol' });
+
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const writeSpy = vi.spyOn(fs, 'writeFileSync').mockImplementationOnce(() => {
+      throw new Error('disk full');
+    });
+
+    // Trigger a save
+    registry.recordSend('carol');
+
+    expect(errorSpy).toHaveBeenCalled();
+    writeSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+});
diff --git a/src/daemon/agent-registry.ts b/src/daemon/agent-registry.ts
new file mode 100644
index 000000000..2138f27d5
--- /dev/null
+++ b/src/daemon/agent-registry.ts
@@ -0,0 +1,201 @@
+/**
+ * Agent Registry
+ * Persists agent metadata across daemon restarts.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { v4 as uuid } from 'uuid';
+
+export interface AgentRecord {
+  id: string;
+  name: string;
+  cli?: string;
+  program?: string;
+  model?: string;
+  task?: string;
+  workingDirectory?: string;
+  firstSeen: string;
+  lastSeen: string;
+  messagesSent: number;
+  messagesReceived: number;
+}
+
+type AgentInput = {
+  name: string;
+  cli?: string;
+  program?: string;
+  model?: string;
+  task?: string;
+  workingDirectory?: string;
+};
+
+export class AgentRegistry {
+  private registryPath: string;
+  private agents: Map<string, AgentRecord> = new Map(); // name -> record
+
+  constructor(teamDir: string) {
+    this.registryPath = path.join(teamDir, 'agents.json');
+    this.ensureDir(teamDir);
+    this.load();
+  }
+
+  /**
+   * Register or update an agent (public alias for registerOrUpdate to match docs).
+   */
+  register(agent: AgentInput): AgentRecord {
+    return this.registerOrUpdate(agent);
+  }
+
+  /**
+   * Register or update an agent, refreshing lastSeen and metadata.
+   */
+  registerOrUpdate(agent: AgentInput): AgentRecord {
+    const now = new Date().toISOString();
+    const existing = this.agents.get(agent.name);
+
+    if (existing) {
+      const updated: AgentRecord = {
+        ...existing,
+        cli: agent.cli ?? existing.cli,
+        program: agent.program ?? existing.program,
+        model: agent.model ?? existing.model,
+        task: agent.task ?? existing.task,
+        workingDirectory: agent.workingDirectory ?? existing.workingDirectory,
+        lastSeen: now,
+      };
+      this.agents.set(agent.name, updated);
+      this.save();
+      return updated;
+    }
+
+    const record: AgentRecord = {
+      id: `agent-${uuid()}`,
+      name: agent.name,
+      cli: agent.cli,
+      program: agent.program,
+      model: agent.model,
+      task: agent.task,
+      workingDirectory: agent.workingDirectory,
+      firstSeen: now,
+      lastSeen: now,
+      messagesSent: 0,
+      messagesReceived: 0,
+    };
+
+    this.agents.set(agent.name, record);
+    this.save();
+    return record;
+  }
+
+  /**
+   * Increment sent counter for an agent.
+   */
+  recordSend(agentName: string): void {
+    const record = this.ensureRecord(agentName);
+    record.messagesSent += 1;
+    record.lastSeen = new Date().toISOString();
+    this.agents.set(agentName, record);
+    this.save();
+  }
+
+  /**
+   * Increment received counter for an agent.
+   */
+  recordReceive(agentName: string): void {
+    const record = this.ensureRecord(agentName);
+    record.messagesReceived += 1;
+    record.lastSeen = new Date().toISOString();
+    this.agents.set(agentName, record);
+    this.save();
+  }
+
+  /**
+   * Touch lastSeen for an agent (e.g., on disconnect).
+   */
+  touch(agentName: string): void {
+    const record = this.ensureRecord(agentName);
+    record.lastSeen = new Date().toISOString();
+    this.agents.set(agentName, record);
+    this.save();
+  }
+
+  /**
+   * Get a snapshot of all agents.
+   */
+  getAgents(): AgentRecord[] {
+    return Array.from(this.agents.values());
+  }
+
+  private ensureRecord(agentName: string): AgentRecord {
+    const existing = this.agents.get(agentName);
+    if (existing) return existing;
+
+    const now = new Date().toISOString();
+    const record: AgentRecord = {
+      id: `agent-${uuid()}`,
+      name: agentName,
+      firstSeen: now,
+      lastSeen: now,
+      messagesSent: 0,
+      messagesReceived: 0,
+    };
+
+    this.agents.set(agentName, record);
+    return record;
+  }
+
+  private ensureDir(dir: string): void {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  load(): void {
+    if (!fs.existsSync(this.registryPath)) {
+      return;
+    }
+
+    try {
+      const data = JSON.parse(fs.readFileSync(this.registryPath, 'utf-8'));
+      const rawAgents = Array.isArray(data?.agents)
+        ? data.agents
+        : typeof data?.agents === 'object' && data?.agents !== null
+          ? Object.values(data.agents)
+          : [];
+
+      for (const raw of rawAgents) {
+        if (!raw?.name) continue;
+        const record: AgentRecord = {
+          id: raw.id ?? `agent-${uuid()}`,
+          name: raw.name,
+          cli: raw.cli,
+          program: raw.program,
+          model: raw.model,
+          task: raw.task,
+          workingDirectory: raw.workingDirectory,
+          firstSeen: raw.firstSeen ?? new Date().toISOString(),
+          lastSeen: raw.lastSeen ?? new Date().toISOString(),
+          messagesSent: typeof raw.messagesSent === 'number' ? raw.messagesSent : 0,
+          messagesReceived: typeof raw.messagesReceived === 'number' ? raw.messagesReceived : 0,
+        };
+        this.agents.set(record.name, record);
+      }
+    } catch (err) {
+      console.error('[registry] Failed to load agents.json:', err);
+    }
+  }
+
+  save(): void {
+    try {
+      const data = JSON.stringify({ agents: this.getAgents() }, null, 2);
+      // Write atomically: write to temp file first, then rename
+      // This prevents race conditions where readers see partial/empty data
+      const tempPath = `${this.registryPath}.tmp`;
+      fs.writeFileSync(tempPath, data, 'utf-8');
+      fs.renameSync(tempPath, this.registryPath);
+    } catch (err) {
+      console.error('[registry] Failed to write agents.json:', err);
+    }
+  }
+}
diff --git a/src/daemon/connection.test.ts b/src/daemon/connection.test.ts
index 935d77741..0f9f2247e 100644
--- a/src/daemon/connection.test.ts
+++ b/src/daemon/connection.test.ts
@@ -81,4 +81,120 @@ describe('Connection', () => {
     expect(onError).toHaveBeenCalledTimes(1);
     expect(socket.destroyed).toBe(true);
   });
+
+  describe('heartbeat timeout configuration', () => {
+    it('uses configurable heartbeatTimeoutMultiplier', async () => {
+      const socket = new MockSocket();
+      // 10ms heartbeat * 2 multiplier = 20ms timeout
+      const connection = new Connection(socket as unknown as Socket, {
+        heartbeatMs: 10,
+        heartbeatTimeoutMultiplier: 2,
+      });
+      const onError = vi.fn();
+      connection.onError = onError;
+
+      socket.emit('data', encodeFrame(makeHello('agent-a')));
+      expect(connection.state).toBe('ACTIVE');
+
+      // Wait less than timeout (20ms) - should still be alive
+      await new Promise((r) => setTimeout(r, 15));
+      expect(onError).not.toHaveBeenCalled();
+      expect(connection.state).toBe('ACTIVE');
+
+      // Wait past timeout - should be dead
+      await new Promise((r) => setTimeout(r, 30));
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect(socket.destroyed).toBe(true);
+    });
+
+    it('survives with slow but timely pong responses', async () => {
+      const socket = new MockSocket();
+      // 20ms heartbeat * 3 multiplier = 60ms timeout
+      const connection = new Connection(socket as unknown as Socket, {
+        heartbeatMs: 20,
+        heartbeatTimeoutMultiplier: 3,
+      });
+      const onError = vi.fn();
+      const onPong = vi.fn();
+      connection.onError = onError;
+      connection.onPong = onPong;
+
+      socket.emit('data', encodeFrame(makeHello('agent-a')));
+      expect(connection.state).toBe('ACTIVE');
+
+      // Simulate slow but valid pong responses every 40ms (within 60ms timeout)
+      for (let i = 0; i < 3; i++) {
+        await new Promise((r) => setTimeout(r, 40));
+        // Send PONG before timeout expires
+        socket.emit('data', encodeFrame({
+          v: PROTOCOL_VERSION,
+          type: 'PONG',
+          id: `pong-${i}`,
+          ts: Date.now(),
+          payload: { nonce: 'test' },
+        }));
+      }
+
+      // Connection should still be alive after multiple slow pongs
+      expect(onError).not.toHaveBeenCalled();
+      expect(connection.state).toBe('ACTIVE');
+      expect(onPong).toHaveBeenCalledTimes(3);
+    });
+
+    it('dies when pong arrives too late', async () => {
+      const socket = new MockSocket();
+      // 10ms heartbeat * 2 multiplier = 20ms timeout
+      const connection = new Connection(socket as unknown as Socket, {
+        heartbeatMs: 10,
+        heartbeatTimeoutMultiplier: 2,
+      });
+      const onError = vi.fn();
+      connection.onError = onError;
+
+      socket.emit('data', encodeFrame(makeHello('agent-a')));
+      expect(connection.state).toBe('ACTIVE');
+
+      // Wait past timeout before sending pong
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Connection should already be dead
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect(socket.destroyed).toBe(true);
+
+      // Late pong should have no effect (connection already dead)
+      socket.emit('data', encodeFrame({
+        v: PROTOCOL_VERSION,
+        type: 'PONG',
+        id: 'late-pong',
+        ts: Date.now(),
+        payload: { nonce: 'test' },
+      }));
+
+      // Error count should not increase
+      expect(onError).toHaveBeenCalledTimes(1);
+    });
+
+    it('uses default multiplier of 6 when not specified', async () => {
+      const socket = new MockSocket();
+      // 10ms heartbeat * 6 (default) = 60ms timeout
+      const connection = new Connection(socket as unknown as Socket, {
+        heartbeatMs: 10,
+        // heartbeatTimeoutMultiplier not specified - should default to 6
+      });
+      const onError = vi.fn();
+      connection.onError = onError;
+
+      socket.emit('data', encodeFrame(makeHello('agent-a')));
+      expect(connection.state).toBe('ACTIVE');
+
+      // Wait 40ms - should still be alive (timeout is 60ms)
+      await new Promise((r) => setTimeout(r, 40));
+      expect(onError).not.toHaveBeenCalled();
+      expect(connection.state).toBe('ACTIVE');
+
+      // Wait total of 80ms - should be dead
+      await new Promise((r) => setTimeout(r, 50));
+      expect(onError).toHaveBeenCalledTimes(1);
+    });
+  });
 });
diff --git a/src/daemon/connection.ts b/src/daemon/connection.ts
index 9a3c417bb..2e4823cea 100644
--- a/src/daemon/connection.ts
+++ b/src/daemon/connection.ts
@@ -27,11 +27,15 @@ export type ConnectionState = 'CONNECTING' | 'HANDSHAKING' | 'ACTIVE' | 'CLOSING
 export interface ConnectionConfig {
   maxFrameBytes: number;
   heartbeatMs: number;
+  /** Multiplier for heartbeat timeout (timeout = heartbeatMs * multiplier). Default: 6 (30s with 5s heartbeat) */
+  heartbeatTimeoutMultiplier: number;
 }
 
 export const DEFAULT_CONFIG: ConnectionConfig = {
   maxFrameBytes: 1024 * 1024,
   heartbeatMs: 5000,
+  // 6x multiplier = 30 second timeout, more tolerant for AI agents processing long responses
+  heartbeatTimeoutMultiplier: 6,
 };
 
 export class Connection {
@@ -43,6 +47,10 @@ export class Connection {
   private _state: ConnectionState = 'CONNECTING';
   private _agentName?: string;
   private _cli?: string;
+  private _program?: string;
+  private _model?: string;
+  private _task?: string;
+  private _workingDirectory?: string;
   private _sessionId: string;
   private _resumeToken: string;
 
@@ -58,6 +66,7 @@ export class Connection {
   onError?: (error: Error) => void;
   onActive?: () => void; // Fires when connection transitions to ACTIVE state
   onAck?: (envelope: Envelope<AckPayload>) => void;
+  onPong?: () => void; // Fires on successful heartbeat response
 
   constructor(socket: net.Socket, config: Partial<ConnectionConfig> = {}) {
     this.id = uuid();
@@ -83,6 +92,22 @@ export class Connection {
     return this._cli;
   }
 
+  get program(): string | undefined {
+    return this._program;
+  }
+
+  get model(): string | undefined {
+    return this._model;
+  }
+
+  get task(): string | undefined {
+    return this._task;
+  }
+
+  get workingDirectory(): string | undefined {
+    return this._workingDirectory;
+  }
+
   get sessionId(): string {
     return this._sessionId;
   }
@@ -139,6 +164,10 @@ export class Connection {
 
     this._agentName = envelope.payload.agent;
     this._cli = envelope.payload.cli;
+    this._program = envelope.payload.program;
+    this._model = envelope.payload.model;
+    this._task = envelope.payload.task;
+    this._workingDirectory = envelope.payload.workingDirectory;
 
     // Check for session resume
     if (envelope.payload.session?.resume_token) {
@@ -147,6 +176,9 @@ export class Connection {
     }
 
     // Send WELCOME
+    // Note: resume_token is omitted because session resume is not yet implemented.
+    // Sending a token would cause clients to attempt resume on reconnect,
+    // triggering a RESUME_TOO_OLD -> new token -> reconnect loop.
     const welcome: Envelope<WelcomePayload> = {
       v: PROTOCOL_VERSION,
       type: 'WELCOME',
@@ -154,7 +186,6 @@ export class Connection {
       ts: Date.now(),
       payload: {
         session_id: this._sessionId,
-        resume_token: this._resumeToken,
         server: {
           max_frame_bytes: this.config.maxFrameBytes,
           heartbeat_ms: this.config.heartbeatMs,
@@ -188,6 +219,9 @@ export class Connection {
   private handlePong(_envelope: Envelope<PongPayload>): void {
     // Note: envelope.payload.nonce could be used for RTT calculation in the future
     this.lastPongReceived = Date.now();
+    if (this.onPong) {
+      this.onPong();
+    }
   }
 
   private startHeartbeat(): void {
@@ -196,9 +230,10 @@ export class Connection {
 
       const now = Date.now();
 
-      // Check for missed pong
-      if (this.lastPongReceived && now - this.lastPongReceived > this.config.heartbeatMs * 2) {
-        this.handleError(new Error('Heartbeat timeout'));
+      // Check for missed pong - use configurable timeout multiplier
+      const timeoutMs = this.config.heartbeatMs * this.config.heartbeatTimeoutMultiplier;
+      if (this.lastPongReceived && now - this.lastPongReceived > timeoutMs) {
+        this.handleError(new Error(`Heartbeat timeout (no pong in ${timeoutMs}ms)`));
         return;
       }
 
diff --git a/src/daemon/index.ts b/src/daemon/index.ts
index 53d41273f..818fb886d 100644
--- a/src/daemon/index.ts
+++ b/src/daemon/index.ts
@@ -1,3 +1,5 @@
 export * from './server.js';
 export * from './router.js';
 export * from './connection.js';
+export * from './agent-registry.js';
+export * from './registry.js';
diff --git a/src/daemon/registry.ts b/src/daemon/registry.ts
new file mode 100644
index 000000000..9102fa525
--- /dev/null
+++ b/src/daemon/registry.ts
@@ -0,0 +1,8 @@
+/**
+ * Agent Registry (public entrypoint)
+ * Persists agent metadata across daemon restarts.
+ *
+ * This file mirrors docs/TMUX_IMPROVEMENTS.md guidance and re-exports the
+ * implementation from agent-registry.ts so both import paths work.
+ */
+export { AgentRegistry, type AgentRecord } from './agent-registry.js';
diff --git a/src/daemon/router.ts b/src/daemon/router.ts
index ac9fbffb0..d5279d697 100644
--- a/src/daemon/router.ts
+++ b/src/daemon/router.ts
@@ -7,16 +7,23 @@ import { v4 as uuid } from 'uuid';
 import {
   type Envelope,
   type SendPayload,
+  type SendMeta,
+  type SendEnvelope,
   type DeliverEnvelope,
   type AckPayload,
   PROTOCOL_VERSION,
 } from '../protocol/types.js';
 import type { StorageAdapter } from '../storage/adapter.js';
+import type { AgentRegistry } from './agent-registry.js';
 
 export interface RoutableConnection {
   id: string;
   agentName?: string;
   cli?: string;
+  program?: string;
+  model?: string;
+  task?: string;
+  workingDirectory?: string;
   sessionId: string;
   close(): void;
   send(envelope: Envelope): boolean;
@@ -53,10 +60,12 @@ export class Router {
   private subscriptions: Map<string, Set<string>> = new Map(); // topic -> Set<agentName>
   private pendingDeliveries: Map<string, PendingDelivery> = new Map(); // deliverId -> pending
   private deliveryOptions: DeliveryReliabilityOptions;
+  private registry?: AgentRegistry;
 
-  constructor(options: { storage?: StorageAdapter; delivery?: Partial<DeliveryReliabilityOptions> } = {}) {
+  constructor(options: { storage?: StorageAdapter; delivery?: Partial<DeliveryReliabilityOptions>; registry?: AgentRegistry } = {}) {
     this.storage = options.storage;
     this.deliveryOptions = { ...DEFAULT_DELIVERY_OPTIONS, ...options.delivery };
+    this.registry = options.registry;
   }
 
   /**
@@ -73,6 +82,14 @@ export class Router {
         this.connections.delete(existing.id);
       }
       this.agents.set(connection.agentName, connection);
+      this.registry?.registerOrUpdate({
+        name: connection.agentName,
+        cli: connection.cli,
+        program: connection.program,
+        model: connection.model,
+        task: connection.task,
+        workingDirectory: connection.workingDirectory,
+      });
     }
   }
 
@@ -124,17 +141,19 @@ export class Router {
   /**
    * Route a SEND message to its destination(s).
    */
-  route(from: RoutableConnection, envelope: Envelope<SendPayload>): void {
+  route(from: RoutableConnection, envelope: SendEnvelope): void {
     const senderName = from.agentName;
     if (!senderName) {
       console.log(`[router] Dropping message - sender has no name`);
       return;
     }
 
+    this.registry?.recordSend(senderName);
+
     const to = envelope.to;
     const topic = envelope.topic;
 
-    console.log(`[router] ${senderName} -> ${to}: ${envelope.payload.body?.substring(0, 50)}...`);
+    console.log(`[router] ${senderName} -> ${to}:${envelope.payload.body?.substring(0, 50)}...`);
 
     if (to === '*') {
       // Broadcast to all (except sender)
@@ -151,7 +170,7 @@ export class Router {
   private sendDirect(
     from: string,
     to: string,
-    envelope: Envelope<SendPayload>
+    envelope: SendEnvelope
   ): boolean {
     const target = this.agents.get(to);
     if (!target) {
@@ -165,6 +184,7 @@ export class Router {
     this.persistDeliverEnvelope(deliver);
     if (sent) {
       this.trackDelivery(target, deliver);
+      this.registry?.recordReceive(to);
     }
     return sent;
   }
@@ -174,7 +194,7 @@ export class Router {
    */
   private broadcast(
     from: string,
-    envelope: Envelope<SendPayload>,
+    envelope: SendEnvelope,
     topic?: string
   ): void {
     const recipients = topic
@@ -191,6 +211,7 @@ export class Router {
         this.persistDeliverEnvelope(deliver);
         if (sent) {
           this.trackDelivery(target, deliver);
+          this.registry?.recordReceive(agentName);
         }
       }
     }
@@ -202,7 +223,7 @@ export class Router {
   private createDeliverEnvelope(
     from: string,
     to: string,
-    original: Envelope<SendPayload>,
+    original: SendEnvelope,
     target: RoutableConnection
   ): DeliverEnvelope {
     return {
@@ -214,6 +235,7 @@ export class Router {
       to,
       topic: original.topic,
       payload: original.payload,
+      payload_meta: original.payload_meta,
       delivery: {
         seq: target.getNextSeq(original.topic ?? 'default', from),
         session_id: target.sessionId,
@@ -239,6 +261,8 @@ export class Router {
       deliverySeq: envelope.delivery.seq,
       deliverySessionId: envelope.delivery.session_id,
       sessionId: envelope.delivery.session_id,
+      status: 'unread',
+      is_urgent: false,
     }).catch((err) => {
       console.error('[router] Failed to persist message', err);
     });
diff --git a/src/daemon/server.ts b/src/daemon/server.ts
index 92f42a39f..5ca7b4e0b 100644
--- a/src/daemon/server.ts
+++ b/src/daemon/server.ts
@@ -10,6 +10,9 @@ import { Connection, type ConnectionConfig, DEFAULT_CONFIG } from './connection.
 import { Router } from './router.js';
 import type { Envelope, SendPayload } from '../protocol/types.js';
 import { createStorageAdapter, type StorageAdapter, type StorageConfig } from '../storage/adapter.js';
+import { SqliteStorageAdapter } from '../storage/sqlite-adapter.js';
+import { getProjectPaths } from '../utils/project-namespace.js';
+import { AgentRegistry } from './agent-registry.js';
 
 export interface DaemonConfig extends ConnectionConfig {
   socketPath: string;
@@ -38,6 +41,7 @@ export class Daemon {
   private connections: Set<Connection> = new Set();
   private storage?: StorageAdapter;
   private storageInitialized = false;
+  private registry?: AgentRegistry;
 
   constructor(config: Partial<DaemonConfig> = {}) {
     this.config = { ...DEFAULT_DAEMON_CONFIG, ...config };
@@ -48,6 +52,9 @@ export class Daemon {
     if (!this.config.teamDir) {
       this.config.teamDir = path.dirname(this.config.socketPath);
     }
+    if (this.config.teamDir) {
+      this.registry = new AgentRegistry(this.config.teamDir);
+    }
     // Storage is initialized lazily in start() to support async createStorageAdapter
     this.server = net.createServer(this.handleConnection.bind(this));
   }
@@ -56,18 +63,17 @@ export class Daemon {
    * Write current agents to agents.json for dashboard consumption.
    */
   private writeAgentsFile(): void {
-    if (!this.config.teamDir) return;
-    const agentsPath = path.join(this.config.teamDir, 'agents.json');
-    const agents = this.router.getAgents().map(name => {
-      const connection = this.router.getConnection(name);
-      return {
-        name,
-        cli: connection?.cli,
-        connectedAt: new Date().toISOString(),
-      };
-    });
+    if (!this.registry) return;
+    // The registry persists on every update; this is a no-op helper for symmetry.
+    const agents = this.registry.getAgents();
     try {
-      fs.writeFileSync(agentsPath, JSON.stringify({ agents }, null, 2));
+      const targetPath = path.join(this.config.teamDir ?? path.dirname(this.config.socketPath), 'agents.json');
+      const data = JSON.stringify({ agents }, null, 2);
+      // Write atomically: write to temp file first, then rename
+      // This prevents race conditions where readers see partial/empty data
+      const tempPath = `${targetPath}.tmp`;
+      fs.writeFileSync(tempPath, data, 'utf-8');
+      fs.renameSync(tempPath, targetPath);
     } catch (err) {
       console.error('[daemon] Failed to write agents.json:', err);
     }
@@ -89,7 +95,7 @@ export class Daemon {
       this.storage = await createStorageAdapter(storagePath, this.config.storageConfig);
     }
 
-    this.router = new Router({ storage: this.storage });
+    this.router = new Router({ storage: this.storage, registry: this.registry });
     this.storageInitialized = true;
   }
 
@@ -183,12 +189,40 @@ export class Daemon {
       this.router.handleAck(connection, envelope);
     };
 
+    // Update lastSeen on successful heartbeat to keep agent status fresh
+    connection.onPong = () => {
+      if (connection.agentName) {
+        this.registry?.touch(connection.agentName);
+      }
+    };
+
     // Register agent when connection becomes active (after successful handshake)
     connection.onActive = () => {
-      if (connection.agentName) {
-        this.router.register(connection);
-        console.log(`[daemon] Agent registered: ${connection.agentName}`);
-        this.writeAgentsFile();
+        if (connection.agentName) {
+          this.router.register(connection);
+          console.log(`[daemon] Agent registered: ${connection.agentName}`);
+          // Registry handles persistence internally via save()
+          this.registry?.registerOrUpdate({
+            name: connection.agentName,
+            cli: connection.cli,
+            program: connection.program,
+            model: connection.model,
+            task: connection.task,
+            workingDirectory: connection.workingDirectory,
+          });
+
+        // Record session start
+        if (this.storage instanceof SqliteStorageAdapter) {
+          const projectPaths = getProjectPaths();
+          this.storage.startSession({
+            id: connection.sessionId,
+            agentName: connection.agentName,
+            cli: connection.cli,
+            projectId: projectPaths.projectId,
+            projectRoot: projectPaths.projectRoot,
+            startedAt: Date.now(),
+          }).catch(err => console.error('[daemon] Failed to record session start:', err));
+        }
       }
     };
 
@@ -196,14 +230,32 @@ export class Daemon {
       console.log(`[daemon] Connection closed: ${connection.agentName ?? connection.id}`);
       this.connections.delete(connection);
       this.router.unregister(connection);
-      this.writeAgentsFile();
+      // Registry handles persistence internally via touch() -> save()
+      if (connection.agentName) {
+        this.registry?.touch(connection.agentName);
+      }
+
+      // Record session end (disconnect - agent may still mark it closed explicitly)
+      if (this.storage instanceof SqliteStorageAdapter) {
+        this.storage.endSession(connection.sessionId, { closedBy: 'disconnect' })
+          .catch(err => console.error('[daemon] Failed to record session end:', err));
+      }
     };
 
     connection.onError = (error: Error) => {
       console.error(`[daemon] Connection error: ${error.message}`);
       this.connections.delete(connection);
       this.router.unregister(connection);
-      this.writeAgentsFile();
+      // Registry handles persistence internally via touch() -> save()
+      if (connection.agentName) {
+        this.registry?.touch(connection.agentName);
+      }
+
+      // Record session end on error
+      if (this.storage instanceof SqliteStorageAdapter) {
+        this.storage.endSession(connection.sessionId, { closedBy: 'error' })
+          .catch(err => console.error('[daemon] Failed to record session end:', err));
+      }
     };
   }
 
diff --git a/src/dashboard/frontend/app.ts b/src/dashboard/frontend/app.ts
new file mode 100644
index 000000000..38d972060
--- /dev/null
+++ b/src/dashboard/frontend/app.ts
@@ -0,0 +1,383 @@
+/**
+ * Dashboard Application Entry Point
+ */
+
+import { subscribe, state } from './state.js';
+import { connect, sendMessage } from './websocket.js';
+import {
+  initElements,
+  getElements,
+  updateConnectionStatus,
+  renderAgents,
+  renderMessages,
+  selectChannel,
+  updateOnlineCount,
+  openCommandPalette,
+  closeCommandPalette,
+  filterPaletteResults,
+  handlePaletteKeydown,
+  initPaletteChannels,
+  closeThreadPanel,
+  renderThreadMessages,
+  showMentionAutocomplete,
+  hideMentionAutocomplete,
+  isMentionAutocompleteVisible,
+  navigateMentionAutocomplete,
+  completeMention,
+  getCurrentMentionQuery,
+  openSpawnModal,
+  closeSpawnModal,
+  spawnAgent,
+  fetchSpawnedAgents,
+} from './components.js';
+import { state } from './state.js';
+
+/**
+ * Initialize the dashboard application
+ */
+export function initApp(): void {
+  const elements = initElements();
+
+  // Subscribe to state changes
+  subscribe(() => {
+    updateConnectionStatus();
+    renderAgents();
+    renderMessages();
+    updateOnlineCount();
+  });
+
+  // Set up event listeners
+  setupEventListeners(elements);
+
+  // Connect to WebSocket
+  connect();
+
+  // Fetch initial spawned agents list
+  fetchSpawnedAgents();
+}
+
+/**
+ * Set up all event listeners
+ */
+function setupEventListeners(elements: ReturnType<typeof getElements>): void {
+  // Channel clicks
+  elements.channelsList.querySelectorAll<HTMLElement>('.channel-item').forEach((item) => {
+    item.addEventListener('click', () => {
+      const channel = item.dataset.channel;
+      if (channel) {
+        selectChannel(channel);
+      }
+    });
+  });
+
+  // Send button
+  elements.sendBtn.addEventListener('click', handleSend);
+
+  // Keyboard shortcuts for composer
+  elements.messageInput.addEventListener('keydown', (e: KeyboardEvent) => {
+    // Handle mention autocomplete keys first
+    if (isMentionAutocompleteVisible()) {
+      if (e.key === 'Tab' || e.key === 'Enter') {
+        e.preventDefault();
+        completeMention();
+        return;
+      }
+      if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        navigateMentionAutocomplete('up');
+        return;
+      }
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        navigateMentionAutocomplete('down');
+        return;
+      }
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        hideMentionAutocomplete();
+        return;
+      }
+    }
+
+    // Enter to send (Slack-style), Shift+Enter for newline
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      handleSend();
+    }
+    // Shift+Enter allows default behavior (inserts newline)
+  });
+
+  // Auto-resize textarea and handle @-mention autocomplete
+  elements.messageInput.addEventListener('input', () => {
+    elements.messageInput.style.height = 'auto';
+    elements.messageInput.style.height =
+      Math.min(elements.messageInput.scrollHeight, 200) + 'px';
+
+    // Check for @-mention at start of input
+    const query = getCurrentMentionQuery();
+    if (query !== null) {
+      showMentionAutocomplete(query);
+    } else {
+      hideMentionAutocomplete();
+    }
+  });
+
+  // Hide mention autocomplete when input loses focus (with delay to allow clicks)
+  elements.messageInput.addEventListener('blur', () => {
+    setTimeout(() => {
+      hideMentionAutocomplete();
+    }, 150);
+  });
+
+  // Bold button - wrap selected text with ** or insert **bold**
+  elements.boldBtn.addEventListener('click', () => {
+    const input = elements.messageInput;
+    const start = input.selectionStart;
+    const end = input.selectionEnd;
+    const text = input.value;
+
+    if (start === end) {
+      // No selection - insert **bold** placeholder
+      const before = text.substring(0, start);
+      const after = text.substring(end);
+      input.value = before + '**bold**' + after;
+      input.selectionStart = start + 2;
+      input.selectionEnd = start + 6;
+    } else {
+      // Wrap selection with **
+      const before = text.substring(0, start);
+      const selected = text.substring(start, end);
+      const after = text.substring(end);
+      input.value = before + '**' + selected + '**' + after;
+      input.selectionStart = start;
+      input.selectionEnd = end + 4;
+    }
+    input.focus();
+  });
+
+  // Emoji button - insert common emojis via simple picker
+  elements.emojiBtn.addEventListener('click', () => {
+    const emojis = ['👍', '👎', '✅', '❌', '🎉', '🔥', '💡', '⚠️', '📝', '🚀'];
+    const emoji = emojis[Math.floor(Math.random() * emojis.length)];
+    const input = elements.messageInput;
+    const start = input.selectionStart;
+    const text = input.value;
+    input.value = text.substring(0, start) + emoji + text.substring(start);
+    input.selectionStart = input.selectionEnd = start + emoji.length;
+    input.focus();
+  });
+
+  // Command palette
+  elements.searchTrigger.addEventListener('click', openCommandPalette);
+
+  document.addEventListener('keydown', (e: KeyboardEvent) => {
+    if ((e.ctrlKey || e.metaKey) && e.key === 'k') {
+      e.preventDefault();
+      if (elements.commandPaletteOverlay.classList.contains('visible')) {
+        closeCommandPalette();
+      } else {
+        openCommandPalette();
+      }
+    }
+
+    if (e.key === 'Escape') {
+      closeCommandPalette();
+    }
+  });
+
+  elements.commandPaletteOverlay.addEventListener('click', (e: MouseEvent) => {
+    if (e.target === elements.commandPaletteOverlay) {
+      closeCommandPalette();
+    }
+  });
+
+  elements.paletteSearch.addEventListener('input', (e: Event) => {
+    const target = e.target as HTMLInputElement;
+    filterPaletteResults(target.value);
+  });
+
+  elements.paletteSearch.addEventListener('keydown', handlePaletteKeydown);
+
+  // Command execution
+  document.querySelectorAll<HTMLElement>('.palette-item[data-command]').forEach((item) => {
+    item.addEventListener('click', () => {
+      const command = item.dataset.command;
+
+      if (command === 'broadcast') {
+        // Pre-fill message input with @* for broadcast
+        elements.messageInput.value = '@* ';
+        elements.messageInput.focus();
+      } else if (command === 'clear') {
+        elements.messagesList.innerHTML = '';
+      }
+
+      closeCommandPalette();
+    });
+  });
+
+  // Initialize palette channel click handlers
+  initPaletteChannels();
+
+  // Thread panel close button
+  elements.threadPanelClose.addEventListener('click', closeThreadPanel);
+
+  // Thread panel send button
+  elements.threadSendBtn.addEventListener('click', handleThreadSend);
+
+  // Thread message input keyboard shortcuts (Slack-style)
+  elements.threadMessageInput.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      handleThreadSend();
+    }
+    // Shift+Enter allows default behavior (inserts newline)
+  });
+
+  // Close thread panel on Escape
+  document.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key === 'Escape' && elements.threadPanelOverlay.classList.contains('visible')) {
+      closeThreadPanel();
+    }
+  });
+
+  // Spawn modal event listeners
+  elements.spawnBtn.addEventListener('click', openSpawnModal);
+
+  elements.spawnModalClose.addEventListener('click', closeSpawnModal);
+
+  // Cancel button in spawn modal
+  document.getElementById('spawn-cancel-btn')?.addEventListener('click', closeSpawnModal);
+
+  // Close spawn modal on overlay click
+  elements.spawnModalOverlay.addEventListener('click', (e: MouseEvent) => {
+    if (e.target === elements.spawnModalOverlay) {
+      closeSpawnModal();
+    }
+  });
+
+  // Close spawn modal on Escape
+  document.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key === 'Escape' && elements.spawnModalOverlay.classList.contains('visible')) {
+      closeSpawnModal();
+    }
+  });
+
+  // Submit spawn form
+  elements.spawnSubmitBtn.addEventListener('click', spawnAgent);
+
+  // Enter key in spawn name input triggers submit
+  elements.spawnNameInput.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      spawnAgent();
+    }
+  });
+}
+
+/**
+ * Parse @mention from message text
+ * Formats: "@AgentName message" or "@* message" for broadcast
+ * Returns { to, message } or null if no valid mention found
+ */
+function parseMention(text: string): { to: string; message: string } | null {
+  const trimmed = text.trim();
+
+  // Match @mention at the start of the message
+  // @* for broadcast, @AgentName for direct message
+  const match = trimmed.match(/^@(\*|[^\s]+)\s+(.+)$/s);
+
+  if (!match) {
+    return null;
+  }
+
+  return {
+    to: match[1],
+    message: match[2].trim(),
+  };
+}
+
+/**
+ * Handle send button click
+ */
+async function handleSend(): Promise<void> {
+  const elements = getElements();
+  const rawMessage = elements.messageInput.value.trim();
+
+  if (!rawMessage) {
+    return;
+  }
+
+  let to: string;
+  let message: string;
+
+  // Check if we're in a DM (not general channel)
+  const isInDM = state.currentChannel !== 'general';
+
+  // Parse @mention from the message
+  const parsed = parseMention(rawMessage);
+
+  if (parsed) {
+    // Message has explicit @mention - use it
+    to = parsed.to;
+    message = parsed.message;
+  } else if (isInDM) {
+    // In DM context - send to current channel without requiring @
+    to = state.currentChannel;
+    message = rawMessage;
+  } else {
+    // In general channel without @mention - require it
+    alert('Message must start with @recipient (e.g., "@Lead hello" or "@* broadcast")');
+    return;
+  }
+
+  elements.sendBtn.disabled = true;
+
+  const result = await sendMessage(to, message);
+
+  if (result.success) {
+    elements.messageInput.value = '';
+    elements.messageInput.style.height = 'auto';
+  } else {
+    alert(result.error);
+  }
+
+  elements.sendBtn.disabled = false;
+}
+
+/**
+ * Handle thread panel send button click
+ */
+async function handleThreadSend(): Promise<void> {
+  const elements = getElements();
+  const message = elements.threadMessageInput.value.trim();
+  const threadId = state.currentThread;
+
+  if (!message || !threadId) {
+    return;
+  }
+
+  // For thread replies, send to broadcast or use original recipient
+  // For now, send as broadcast with thread ID
+  elements.threadSendBtn.disabled = true;
+
+  const result = await sendMessage('*', message, threadId);
+
+  if (result.success) {
+    elements.threadMessageInput.value = '';
+    // Re-render thread messages to show the new message
+    renderThreadMessages(threadId);
+  } else {
+    alert(result.error);
+  }
+
+  elements.threadSendBtn.disabled = false;
+}
+
+// Auto-initialize when DOM is ready
+if (typeof document !== 'undefined') {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initApp);
+  } else {
+    initApp();
+  }
+}
diff --git a/src/dashboard/frontend/components.ts b/src/dashboard/frontend/components.ts
new file mode 100644
index 000000000..16d2383f9
--- /dev/null
+++ b/src/dashboard/frontend/components.ts
@@ -0,0 +1,957 @@
+/**
+ * Dashboard UI Components
+ */
+
+import type { Agent, Message, DOMElements, ChannelType, SpawnedAgent } from './types.js';
+import { state, getFilteredMessages, setCurrentChannel, setCurrentThread, getThreadMessages, getThreadReplyCount } from './state.js';
+import {
+  escapeHtml,
+  formatTime,
+  formatDate,
+  getAvatarColor,
+  getInitials,
+  formatMessageBody,
+  isAgentOnline,
+} from './utils.js';
+
+// Track spawned agents
+let spawnedAgents: SpawnedAgent[] = [];
+
+let elements: DOMElements;
+let paletteSelectedIndex = -1;
+
+/**
+ * Initialize DOM element references
+ */
+export function initElements(): DOMElements {
+  elements = {
+    connectionDot: document.getElementById('connection-dot')!,
+    channelsList: document.getElementById('channels-list')!,
+    agentsList: document.getElementById('agents-list')!,
+    messagesList: document.getElementById('messages-list')!,
+    currentChannelName: document.getElementById('current-channel-name')!,
+    channelTopic: document.getElementById('channel-topic')!,
+    onlineCount: document.getElementById('online-count')!,
+    messageInput: document.getElementById('message-input') as HTMLTextAreaElement,
+    sendBtn: document.getElementById('send-btn') as HTMLButtonElement,
+    boldBtn: document.getElementById('bold-btn') as HTMLButtonElement,
+    emojiBtn: document.getElementById('emoji-btn') as HTMLButtonElement,
+    searchTrigger: document.getElementById('search-trigger')!,
+    commandPaletteOverlay: document.getElementById('command-palette-overlay')!,
+    paletteSearch: document.getElementById('palette-search') as HTMLInputElement,
+    paletteResults: document.getElementById('palette-results')!,
+    paletteChannelsSection: document.getElementById('palette-channels-section')!,
+    paletteAgentsSection: document.getElementById('palette-agents-section')!,
+    paletteMessagesSection: document.getElementById('palette-messages-section')!,
+    typingIndicator: document.getElementById('typing-indicator')!,
+    threadPanelOverlay: document.getElementById('thread-panel-overlay')!,
+    threadPanelId: document.getElementById('thread-panel-id')!,
+    threadPanelClose: document.getElementById('thread-panel-close') as HTMLButtonElement,
+    threadMessages: document.getElementById('thread-messages')!,
+    threadMessageInput: document.getElementById('thread-message-input') as HTMLTextAreaElement,
+    threadSendBtn: document.getElementById('thread-send-btn') as HTMLButtonElement,
+    mentionAutocomplete: document.getElementById('mention-autocomplete')!,
+    mentionAutocompleteList: document.getElementById('mention-autocomplete-list')!,
+    // Spawn modal elements
+    spawnBtn: document.getElementById('spawn-btn') as HTMLButtonElement,
+    spawnModalOverlay: document.getElementById('spawn-modal-overlay')!,
+    spawnModalClose: document.getElementById('spawn-modal-close') as HTMLButtonElement,
+    spawnNameInput: document.getElementById('spawn-name-input') as HTMLInputElement,
+    spawnCliInput: document.getElementById('spawn-cli-input') as HTMLInputElement,
+    spawnTaskInput: document.getElementById('spawn-task-input') as HTMLTextAreaElement,
+    spawnSubmitBtn: document.getElementById('spawn-submit-btn') as HTMLButtonElement,
+    spawnStatus: document.getElementById('spawn-status')!,
+  };
+  return elements;
+}
+
+/**
+ * Get DOM elements
+ */
+export function getElements(): DOMElements {
+  return elements;
+}
+
+/**
+ * Update connection status indicator
+ */
+export function updateConnectionStatus(): void {
+  if (state.isConnected) {
+    elements.connectionDot.classList.remove('offline');
+  } else {
+    elements.connectionDot.classList.add('offline');
+  }
+}
+
+/**
+ * Render agents list in sidebar
+ */
+export function renderAgents(): void {
+  console.log('[UI] renderAgents called, agents:', state.agents.length, state.agents.map(a => a.name));
+
+  // Create a set of spawned agent names for quick lookup
+  const spawnedNames = new Set(spawnedAgents.map(a => a.name));
+
+  const html = state.agents
+    .map((agent) => {
+      const online = isAgentOnline(agent.lastSeen || agent.lastActive);
+      const presenceClass = online ? 'online' : '';
+      const isActive = state.currentChannel === agent.name;
+      const needsAttentionClass = agent.needsAttention ? 'needs-attention' : '';
+      const isSpawned = spawnedNames.has(agent.name);
+
+      // Spawned icon SVG (play/launch icon)
+      const spawnedIcon = isSpawned ? `
+        <svg class="spawned-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" title="Spawned from dashboard">
+          <polygon points="5 3 19 12 5 21 5 3"/>
+        </svg>
+      ` : '';
+
+      // Release button for spawned agents
+      const releaseBtn = isSpawned ? `
+        <button class="release-btn" title="Release agent" data-release="${escapeHtml(agent.name)}">
+          <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
+            <line x1="18" y1="6" x2="6" y2="18"/>
+            <line x1="6" y1="6" x2="18" y2="18"/>
+          </svg>
+        </button>
+      ` : '';
+
+      return `
+      <li class="channel-item ${isActive ? 'active' : ''} ${needsAttentionClass}" data-agent="${escapeHtml(agent.name)}" ${isSpawned ? 'title="Spawned from dashboard"' : ''}>
+        <div class="agent-avatar" style="background: ${isSpawned ? 'var(--accent-green)' : getAvatarColor(agent.name)}">
+          ${getInitials(agent.name)}
+          <span class="presence-indicator ${presenceClass}"></span>
+        </div>
+        <span class="channel-name">${escapeHtml(agent.name)}</span>
+        ${spawnedIcon}
+        ${agent.needsAttention ? '<span class="attention-badge">Needs Input</span>' : ''}
+        ${releaseBtn}
+      </li>
+    `;
+    })
+    .join('');
+
+  elements.agentsList.innerHTML =
+    html ||
+    '<li class="channel-item" style="color: var(--text-muted); cursor: default;">No agents connected</li>';
+
+  // Add click handlers for agent selection
+  elements.agentsList.querySelectorAll<HTMLElement>('.channel-item[data-agent]').forEach((item) => {
+    item.addEventListener('click', (e) => {
+      // Don't select channel if clicking release button
+      if ((e.target as HTMLElement).closest('.release-btn')) {
+        return;
+      }
+      const agentName = item.dataset.agent;
+      if (agentName) {
+        selectChannel(agentName);
+      }
+    });
+  });
+
+  // Add release button click handlers
+  elements.agentsList.querySelectorAll<HTMLButtonElement>('.release-btn[data-release]').forEach((btn) => {
+    btn.addEventListener('click', async (e) => {
+      e.stopPropagation();
+      const agentName = btn.dataset.release;
+      if (agentName && confirm(`Release agent "${agentName}"? This will terminate the agent.`)) {
+        await releaseAgent(agentName);
+      }
+    });
+  });
+
+  // Update command palette agents
+  updatePaletteAgents();
+}
+
+/**
+ * Render messages list
+ */
+export function renderMessages(): void {
+  const filtered = getFilteredMessages();
+
+  if (filtered.length === 0) {
+    elements.messagesList.innerHTML = `
+      <div class="empty-state">
+        <svg class="empty-state-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+          <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+        </svg>
+        <div class="empty-state-title">No messages yet</div>
+        <div class="empty-state-text">
+          ${
+            state.currentChannel === 'general'
+              ? 'Messages between agents will appear here'
+              : `Messages with ${state.currentChannel} will appear here`
+          }
+        </div>
+      </div>
+    `;
+    return;
+  }
+
+  let html = '';
+  let lastDate: string | null = null;
+
+  filtered.forEach((msg) => {
+    const msgDate = new Date(msg.timestamp).toDateString();
+
+    // Add date divider if needed
+    if (msgDate !== lastDate) {
+      html += `
+        <div class="date-divider">
+          <span class="date-divider-text">${formatDate(msg.timestamp)}</span>
+        </div>
+      `;
+      lastDate = msgDate;
+    }
+
+    const isBroadcast = msg.to === '*';
+    const avatarColor = getAvatarColor(msg.from);
+    const replyCount = getThreadReplyCount(msg.id);
+
+    // Format: @From → @To: message (like Slack)
+    // For cross-project messages, show project badge before agent name
+    const recipientDisplay = isBroadcast
+      ? '@everyone'
+      : msg.project
+        ? `<span class="project-badge">${escapeHtml(msg.project)}</span>@${escapeHtml(msg.to)}`
+        : `@${escapeHtml(msg.to)}`;
+
+    html += `
+      <div class="message ${isBroadcast ? 'broadcast' : ''}" data-id="${escapeHtml(msg.id)}">
+        <div class="message-avatar" style="background: ${avatarColor}">
+          ${getInitials(msg.from)}
+        </div>
+        <div class="message-content">
+          <div class="message-header">
+            <span class="message-sender">@${escapeHtml(msg.from)}</span>
+            <span class="message-recipient">
+              → <span class="target">${recipientDisplay}</span>
+            </span>
+            <span class="message-timestamp">${formatTime(msg.timestamp)}</span>
+          </div>
+          <div class="message-body">${formatMessageBody(msg.content)}</div>
+          ${
+            msg.thread
+              ? `
+            <div class="thread-indicator" data-thread="${escapeHtml(msg.thread)}">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+              </svg>
+              Thread: ${escapeHtml(msg.thread)}
+            </div>
+          `
+              : ''
+          }
+          ${
+            replyCount > 0
+              ? `
+            <div class="reply-count-badge" data-thread="${escapeHtml(msg.id)}">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+              </svg>
+              ${replyCount} ${replyCount === 1 ? 'reply' : 'replies'}
+            </div>
+          `
+              : ''
+          }
+        </div>
+        <div class="message-actions">
+          <button class="message-action-btn" data-action="reply" title="Reply in thread">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+            </svg>
+          </button>
+          <button class="message-action-btn" title="Add reaction">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <circle cx="12" cy="12" r="10"/>
+              <path d="M8 14s1.5 2 4 2 4-2 4-2"/>
+              <line x1="9" y1="9" x2="9.01" y2="9"/>
+              <line x1="15" y1="9" x2="15.01" y2="9"/>
+            </svg>
+          </button>
+        </div>
+      </div>
+    `;
+  });
+
+  elements.messagesList.innerHTML = html;
+
+  // Note: Auto-scroll removed - interferes with manual scrolling through history
+
+  // Attach thread click handlers
+  attachThreadHandlers();
+}
+
+/**
+ * Select a channel and update UI
+ */
+export function selectChannel(channel: ChannelType): void {
+  setCurrentChannel(channel);
+
+  // Update sidebar active states
+  elements.channelsList.querySelectorAll<HTMLElement>('.channel-item').forEach((item) => {
+    item.classList.toggle('active', item.dataset.channel === channel);
+  });
+  elements.agentsList.querySelectorAll<HTMLElement>('.channel-item').forEach((item) => {
+    item.classList.toggle('active', item.dataset.agent === channel);
+  });
+
+  // Update header
+  const prefixEl = document.querySelector('.channel-header-name .prefix');
+  if (channel === 'general') {
+    elements.currentChannelName.innerHTML = 'general';
+    elements.channelTopic.textContent = 'All agent communications';
+    if (prefixEl) prefixEl.textContent = '#';
+  } else {
+    elements.currentChannelName.innerHTML = escapeHtml(channel);
+    const agent = state.agents.find((a) => a.name === channel);
+    elements.channelTopic.textContent = agent?.status || 'Direct messages';
+    if (prefixEl) prefixEl.textContent = '@';
+  }
+
+  // Update composer placeholder - DM mode doesn't require @mention
+  elements.messageInput.placeholder =
+    channel === 'general'
+      ? '@AgentName message... (or @* to broadcast)'
+      : `Message ${channel}... (@ not required)`;
+
+  // Re-render messages
+  renderMessages();
+}
+
+/**
+ * Update online count display
+ */
+export function updateOnlineCount(): void {
+  const online = state.agents.filter((a) => isAgentOnline(a.lastSeen || a.lastActive)).length;
+  elements.onlineCount.textContent = `${online} online`;
+}
+
+/**
+ * Update agents in command palette
+ */
+export function updatePaletteAgents(): void {
+  const html = state.agents
+    .map((agent) => {
+      const online = isAgentOnline(agent.lastSeen || agent.lastActive);
+      return `
+      <div class="palette-item" data-jump-agent="${escapeHtml(agent.name)}">
+        <div class="palette-item-icon">
+          <div class="agent-avatar" style="background: ${getAvatarColor(agent.name)}; width: 20px; height: 20px; font-size: 9px;">
+            ${getInitials(agent.name)}
+            <span class="presence-indicator ${online ? 'online' : ''}"></span>
+          </div>
+        </div>
+        <div class="palette-item-content">
+          <div class="palette-item-title">${escapeHtml(agent.name)}</div>
+          <div class="palette-item-subtitle">${online ? 'Online' : 'Offline'}</div>
+        </div>
+      </div>
+    `;
+    })
+    .join('');
+
+  const section = elements.paletteAgentsSection;
+  const items = section.querySelectorAll('.palette-item');
+  items.forEach((item) => item.remove());
+  section.insertAdjacentHTML('beforeend', html);
+
+  // Add click handlers
+  section.querySelectorAll<HTMLElement>('.palette-item[data-jump-agent]').forEach((item) => {
+    item.addEventListener('click', () => {
+      const agentName = item.dataset.jumpAgent;
+      if (agentName) {
+        selectChannel(agentName);
+        closeCommandPalette();
+      }
+    });
+  });
+}
+
+/**
+ * Initialize channel click handlers in command palette
+ */
+export function initPaletteChannels(): void {
+  elements.paletteChannelsSection
+    .querySelectorAll<HTMLElement>('.palette-item[data-jump-channel]')
+    .forEach((item) => {
+      item.addEventListener('click', () => {
+        const channelName = item.dataset.jumpChannel;
+        if (channelName) {
+          selectChannel(channelName);
+          closeCommandPalette();
+        }
+      });
+    });
+}
+
+/**
+ * Open command palette
+ */
+export function openCommandPalette(): void {
+  elements.commandPaletteOverlay.classList.add('visible');
+  elements.paletteSearch.value = '';
+  elements.paletteSearch.focus();
+  paletteSelectedIndex = -1;
+  filterPaletteResults('');
+}
+
+/**
+ * Get all visible palette items
+ */
+export function getVisiblePaletteItems(): HTMLElement[] {
+  const allItems = Array.from(
+    elements.paletteResults.querySelectorAll<HTMLElement>('.palette-item')
+  );
+  return allItems.filter((item) => item.style.display !== 'none');
+}
+
+/**
+ * Update the selected palette item visually
+ */
+export function updatePaletteSelection(): void {
+  const items = getVisiblePaletteItems();
+
+  // Remove selection from all items
+  items.forEach((item) => item.classList.remove('selected'));
+
+  // Add selection to current item
+  if (paletteSelectedIndex >= 0 && paletteSelectedIndex < items.length) {
+    const selectedItem = items[paletteSelectedIndex];
+    selectedItem.classList.add('selected');
+
+    // Scroll into view if needed
+    selectedItem.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+  }
+}
+
+/**
+ * Handle keyboard navigation in command palette
+ */
+export function handlePaletteKeydown(e: KeyboardEvent): void {
+  const items = getVisiblePaletteItems();
+
+  if (items.length === 0) return;
+
+  switch (e.key) {
+    case 'ArrowDown':
+      e.preventDefault();
+      paletteSelectedIndex = paletteSelectedIndex < items.length - 1
+        ? paletteSelectedIndex + 1
+        : 0;
+      updatePaletteSelection();
+      break;
+
+    case 'ArrowUp':
+      e.preventDefault();
+      paletteSelectedIndex = paletteSelectedIndex > 0
+        ? paletteSelectedIndex - 1
+        : items.length - 1;
+      updatePaletteSelection();
+      break;
+
+    case 'Enter':
+      e.preventDefault();
+      if (paletteSelectedIndex >= 0 && paletteSelectedIndex < items.length) {
+        executePaletteItem(items[paletteSelectedIndex]);
+      }
+      break;
+  }
+}
+
+/**
+ * Execute the action for a palette item
+ */
+export function executePaletteItem(item: HTMLElement): void {
+  // Check for command
+  const command = item.dataset.command;
+  if (command) {
+    if (command === 'broadcast') {
+      // Pre-fill message input with @* for broadcast
+      elements.messageInput.value = '@* ';
+      elements.messageInput.focus();
+    } else if (command === 'clear') {
+      elements.messagesList.innerHTML = '';
+    }
+    closeCommandPalette();
+    return;
+  }
+
+  // Check for channel jump
+  const channel = item.dataset.jumpChannel;
+  if (channel) {
+    selectChannel(channel);
+    closeCommandPalette();
+    return;
+  }
+
+  // Check for agent jump
+  const agent = item.dataset.jumpAgent;
+  if (agent) {
+    selectChannel(agent);
+    closeCommandPalette();
+    return;
+  }
+
+  // Check for message jump
+  const messageId = item.dataset.jumpMessage;
+  if (messageId) {
+    // Find and scroll to the message
+    const messageEl = elements.messagesList.querySelector(`[data-id="${messageId}"]`);
+    if (messageEl) {
+      messageEl.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      messageEl.classList.add('highlighted');
+      setTimeout(() => messageEl.classList.remove('highlighted'), 2000);
+    }
+    closeCommandPalette();
+    return;
+  }
+}
+
+/**
+ * Close command palette
+ */
+export function closeCommandPalette(): void {
+  elements.commandPaletteOverlay.classList.remove('visible');
+}
+
+/**
+ * Filter command palette results based on query
+ */
+export function filterPaletteResults(query: string): void {
+  const q = query.toLowerCase();
+
+  // Reset selection when filtering
+  paletteSelectedIndex = -1;
+
+  // Filter command items
+  document.querySelectorAll<HTMLElement>('.palette-item[data-command]').forEach((item) => {
+    const titleEl = item.querySelector('.palette-item-title');
+    const title = titleEl?.textContent?.toLowerCase() || '';
+    item.style.display = title.includes(q) ? 'flex' : 'none';
+  });
+
+  // Filter channel items
+  document.querySelectorAll<HTMLElement>('.palette-item[data-jump-channel]').forEach((item) => {
+    const titleEl = item.querySelector('.palette-item-title');
+    const title = titleEl?.textContent?.toLowerCase() || '';
+    item.style.display = title.includes(q) ? 'flex' : 'none';
+  });
+
+  // Filter agent items
+  document.querySelectorAll<HTMLElement>('.palette-item[data-jump-agent]').forEach((item) => {
+    const name = item.dataset.jumpAgent?.toLowerCase() || '';
+    item.style.display = name.includes(q) ? 'flex' : 'none';
+  });
+
+  // Show message search if query is long enough
+  if (q.length >= 2) {
+    const matches = state.messages.filter((m) => m.content.toLowerCase().includes(q)).slice(0, 5);
+
+    if (matches.length > 0) {
+      elements.paletteMessagesSection.style.display = 'block';
+      const items = matches
+        .map(
+          (m) => `
+        <div class="palette-item" data-jump-message="${escapeHtml(m.id)}">
+          <div class="palette-item-icon">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+            </svg>
+          </div>
+          <div class="palette-item-content">
+            <div class="palette-item-title">${escapeHtml(m.from)}</div>
+            <div class="palette-item-subtitle">${escapeHtml(m.content.substring(0, 60))}${m.content.length > 60 ? '...' : ''}</div>
+          </div>
+        </div>
+      `
+        )
+        .join('');
+
+      const existingItems = elements.paletteMessagesSection.querySelectorAll('.palette-item');
+      existingItems.forEach((item) => item.remove());
+      elements.paletteMessagesSection.insertAdjacentHTML('beforeend', items);
+    } else {
+      elements.paletteMessagesSection.style.display = 'none';
+    }
+  } else {
+    elements.paletteMessagesSection.style.display = 'none';
+  }
+}
+
+/**
+ * Open thread panel for a specific thread
+ */
+export function openThreadPanel(threadId: string): void {
+  setCurrentThread(threadId);
+  elements.threadPanelId.textContent = threadId;
+  elements.threadPanelOverlay.classList.add('visible');
+  elements.threadMessageInput.value = '';
+  renderThreadMessages(threadId);
+  elements.threadMessageInput.focus();
+}
+
+/**
+ * Close thread panel
+ */
+export function closeThreadPanel(): void {
+  setCurrentThread(null);
+  elements.threadPanelOverlay.classList.remove('visible');
+}
+
+/**
+ * Render messages in thread panel
+ */
+export function renderThreadMessages(threadId: string): void {
+  const messages = getThreadMessages(threadId);
+
+  if (messages.length === 0) {
+    elements.threadMessages.innerHTML = `
+      <div class="thread-empty">
+        <p>No messages in this thread yet.</p>
+        <p style="font-size: 12px; margin-top: 8px;">Start the conversation below!</p>
+      </div>
+    `;
+    return;
+  }
+
+  const html = messages
+    .map((msg) => `
+      <div class="thread-message">
+        <div class="thread-message-header">
+          <div class="thread-message-avatar" style="background: ${getAvatarColor(msg.from)}">
+            ${getInitials(msg.from)}
+          </div>
+          <span class="thread-message-sender">${escapeHtml(msg.from)}</span>
+          <span class="thread-message-time">${formatTime(msg.timestamp)}</span>
+        </div>
+        <div class="thread-message-body">${formatMessageBody(msg.content)}</div>
+      </div>
+    `)
+    .join('');
+
+  elements.threadMessages.innerHTML = html;
+
+  // Scroll to bottom
+  elements.threadMessages.scrollTop = elements.threadMessages.scrollHeight;
+}
+
+/**
+ * Attach thread click handlers to messages (call after renderMessages)
+ */
+export function attachThreadHandlers(): void {
+  // Thread indicator clicks
+  elements.messagesList.querySelectorAll<HTMLElement>('.thread-indicator').forEach((el) => {
+    el.style.cursor = 'pointer';
+    el.addEventListener('click', (e) => {
+      e.stopPropagation();
+      const threadId = el.dataset.thread;
+      if (threadId) {
+        openThreadPanel(threadId);
+      }
+    });
+  });
+
+  // Reply count badge clicks
+  elements.messagesList.querySelectorAll<HTMLElement>('.reply-count-badge').forEach((el) => {
+    el.addEventListener('click', (e) => {
+      e.stopPropagation();
+      const threadId = el.dataset.thread;
+      if (threadId) {
+        openThreadPanel(threadId);
+      }
+    });
+  });
+
+  // Reply in thread button clicks
+  elements.messagesList.querySelectorAll<HTMLElement>('.message-action-btn[data-action="reply"]').forEach((el) => {
+    el.addEventListener('click', (e) => {
+      e.stopPropagation();
+      const messageId = el.closest('.message')?.getAttribute('data-id');
+      if (messageId) {
+        // Use message ID as thread ID for new threads
+        openThreadPanel(messageId);
+      }
+    });
+  });
+}
+
+/**
+ * @-Mention Autocomplete State
+ */
+let mentionSelectedIndex = 0;
+let mentionFilteredAgents: typeof state.agents = [];
+
+/**
+ * Show mention autocomplete dropdown with filtered agents
+ */
+export function showMentionAutocomplete(filter: string): void {
+  const filterLower = filter.toLowerCase();
+
+  // Filter agents by name, include broadcast option
+  mentionFilteredAgents = state.agents.filter(agent =>
+    agent.name.toLowerCase().includes(filterLower)
+  );
+
+  // Reset selection
+  mentionSelectedIndex = 0;
+
+  // Build HTML for agent list
+  let html = '';
+
+  // Add broadcast option if filter matches
+  if ('*'.includes(filterLower) || 'everyone'.includes(filterLower) || 'all'.includes(filterLower) || 'broadcast'.includes(filterLower)) {
+    html += `
+      <div class="mention-autocomplete-item ${mentionSelectedIndex === 0 && mentionFilteredAgents.length === 0 ? 'selected' : ''}" data-mention="*">
+        <div class="agent-avatar" style="background: var(--accent-yellow);">*</div>
+        <span class="mention-autocomplete-name">@everyone</span>
+        <span class="mention-autocomplete-role">Broadcast to all</span>
+      </div>
+    `;
+  }
+
+  // Add agents
+  mentionFilteredAgents.forEach((agent, index) => {
+    const isSelected = index === mentionSelectedIndex;
+    html += `
+      <div class="mention-autocomplete-item ${isSelected ? 'selected' : ''}" data-mention="${escapeHtml(agent.name)}">
+        <div class="agent-avatar" style="background: ${getAvatarColor(agent.name)}">
+          ${getInitials(agent.name)}
+        </div>
+        <span class="mention-autocomplete-name">@${escapeHtml(agent.name)}</span>
+        <span class="mention-autocomplete-role">${escapeHtml(agent.role || 'Agent')}</span>
+      </div>
+    `;
+  });
+
+  if (html === '') {
+    html = '<div class="mention-autocomplete-item" style="color: var(--text-muted); cursor: default;">No matching agents</div>';
+  }
+
+  elements.mentionAutocompleteList.innerHTML = html;
+  elements.mentionAutocomplete.classList.add('visible');
+
+  // Add click handlers to items
+  elements.mentionAutocompleteList.querySelectorAll<HTMLElement>('.mention-autocomplete-item[data-mention]').forEach((item) => {
+    item.addEventListener('click', () => {
+      const mention = item.dataset.mention;
+      if (mention) {
+        completeMention(mention);
+      }
+    });
+  });
+}
+
+/**
+ * Hide mention autocomplete dropdown
+ */
+export function hideMentionAutocomplete(): void {
+  elements.mentionAutocomplete.classList.remove('visible');
+  mentionFilteredAgents = [];
+  mentionSelectedIndex = 0;
+}
+
+/**
+ * Check if mention autocomplete is visible
+ */
+export function isMentionAutocompleteVisible(): boolean {
+  return elements.mentionAutocomplete.classList.contains('visible');
+}
+
+/**
+ * Navigate mention autocomplete selection
+ */
+export function navigateMentionAutocomplete(direction: 'up' | 'down'): void {
+  const items = elements.mentionAutocompleteList.querySelectorAll<HTMLElement>('.mention-autocomplete-item[data-mention]');
+  if (items.length === 0) return;
+
+  // Remove current selection
+  items[mentionSelectedIndex]?.classList.remove('selected');
+
+  // Update index
+  if (direction === 'down') {
+    mentionSelectedIndex = (mentionSelectedIndex + 1) % items.length;
+  } else {
+    mentionSelectedIndex = (mentionSelectedIndex - 1 + items.length) % items.length;
+  }
+
+  // Add new selection
+  items[mentionSelectedIndex]?.classList.add('selected');
+  items[mentionSelectedIndex]?.scrollIntoView({ block: 'nearest' });
+}
+
+/**
+ * Complete the current mention selection
+ */
+export function completeMention(mention?: string): void {
+  const items = elements.mentionAutocompleteList.querySelectorAll<HTMLElement>('.mention-autocomplete-item[data-mention]');
+
+  // Use provided mention or get from selected item
+  let selectedMention = mention;
+  if (!selectedMention && items.length > 0) {
+    selectedMention = items[mentionSelectedIndex]?.dataset.mention;
+  }
+
+  if (!selectedMention) {
+    hideMentionAutocomplete();
+    return;
+  }
+
+  // Replace the @... text with the completed mention
+  const input = elements.messageInput;
+  const value = input.value;
+
+  // Find the @ position (should be at start or after whitespace)
+  const atMatch = value.match(/^@\S*/);
+  if (atMatch) {
+    // Replace the @partial with @CompletedName
+    const completedText = `@${selectedMention} `;
+    input.value = completedText + value.substring(atMatch[0].length);
+    input.selectionStart = input.selectionEnd = completedText.length;
+  }
+
+  hideMentionAutocomplete();
+  input.focus();
+}
+
+/**
+ * Get the current @mention being typed (if any)
+ */
+export function getCurrentMentionQuery(): string | null {
+  const input = elements.messageInput;
+  const value = input.value;
+  const cursorPos = input.selectionStart;
+
+  // Check if cursor is within an @mention at the start
+  const atMatch = value.match(/^@(\S*)/);
+  if (atMatch && cursorPos <= atMatch[0].length) {
+    return atMatch[1]; // Return the text after @
+  }
+
+  return null;
+}
+
+// ========================================
+// Spawn Modal Functions
+// ========================================
+
+/**
+ * Open the spawn agent modal
+ */
+export function openSpawnModal(): void {
+  elements.spawnModalOverlay.classList.add('visible');
+  elements.spawnNameInput.value = '';
+  elements.spawnCliInput.value = 'claude';
+  elements.spawnTaskInput.value = '';
+  elements.spawnStatus.textContent = '';
+  elements.spawnStatus.className = 'spawn-status';
+  elements.spawnNameInput.focus();
+}
+
+/**
+ * Close the spawn agent modal
+ */
+export function closeSpawnModal(): void {
+  elements.spawnModalOverlay.classList.remove('visible');
+}
+
+/**
+ * Spawn a new agent via the API
+ */
+export async function spawnAgent(): Promise<{ success: boolean; error?: string }> {
+  const name = elements.spawnNameInput.value.trim();
+  const cli = elements.spawnCliInput.value.trim() || 'claude';
+  const task = elements.spawnTaskInput.value.trim();
+
+  if (!name) {
+    elements.spawnStatus.textContent = 'Agent name is required';
+    elements.spawnStatus.className = 'spawn-status error';
+    return { success: false, error: 'Agent name is required' };
+  }
+
+  elements.spawnSubmitBtn.disabled = true;
+  elements.spawnStatus.textContent = 'Spawning agent...';
+  elements.spawnStatus.className = 'spawn-status loading';
+
+  try {
+    const response = await fetch('/api/spawn', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name, cli, task }),
+    });
+
+    const result = await response.json();
+
+    if (response.ok && result.success) {
+      elements.spawnStatus.textContent = `Agent "${name}" spawned successfully!`;
+      elements.spawnStatus.className = 'spawn-status success';
+
+      // Refresh spawned agents list
+      await fetchSpawnedAgents();
+
+      // Close modal after brief delay
+      setTimeout(() => {
+        closeSpawnModal();
+      }, 1000);
+
+      return { success: true };
+    } else {
+      throw new Error(result.error || 'Failed to spawn agent');
+    }
+  } catch (err: any) {
+    elements.spawnStatus.textContent = err.message || 'Failed to spawn agent';
+    elements.spawnStatus.className = 'spawn-status error';
+    return { success: false, error: err.message };
+  } finally {
+    elements.spawnSubmitBtn.disabled = false;
+  }
+}
+
+/**
+ * Fetch list of spawned agents from API
+ */
+export async function fetchSpawnedAgents(): Promise<void> {
+  try {
+    const response = await fetch('/api/spawned');
+    const result = await response.json();
+
+    if (result.success && Array.isArray(result.agents)) {
+      spawnedAgents = result.agents;
+      // Re-render agents to show spawned status
+      renderAgents();
+    }
+  } catch (err) {
+    console.error('[UI] Failed to fetch spawned agents:', err);
+  }
+}
+
+/**
+ * Release a spawned agent
+ */
+export async function releaseAgent(name: string): Promise<void> {
+  try {
+    const response = await fetch(`/api/spawned/${encodeURIComponent(name)}`, {
+      method: 'DELETE',
+    });
+
+    const result = await response.json();
+
+    if (result.success) {
+      // Refresh the list
+      await fetchSpawnedAgents();
+    } else {
+      console.error('[UI] Failed to release agent:', result.error);
+    }
+  } catch (err) {
+    console.error('[UI] Failed to release agent:', err);
+  }
+}
+
+/**
+ * Get spawned agents list
+ */
+export function getSpawnedAgents(): SpawnedAgent[] {
+  return spawnedAgents;
+}
diff --git a/src/dashboard/frontend/index.ts b/src/dashboard/frontend/index.ts
new file mode 100644
index 000000000..9bd7a2f01
--- /dev/null
+++ b/src/dashboard/frontend/index.ts
@@ -0,0 +1,60 @@
+/**
+ * Dashboard Frontend Module
+ *
+ * A Slack-like real-time dashboard for Agent Relay communications.
+ */
+
+// Re-export all types
+export type {
+  Agent,
+  Message,
+  DashboardData,
+  SessionInfo,
+  AgentSummary,
+  ChannelType,
+  AppState,
+  DOMElements,
+} from './types.js';
+
+// Re-export state management
+export {
+  state,
+  subscribe,
+  setAgents,
+  setMessages,
+  setCurrentChannel,
+  setConnectionStatus,
+  getFilteredMessages,
+} from './state.js';
+
+// Re-export utilities
+export {
+  STALE_THRESHOLD_MS,
+  isAgentOnline,
+  escapeHtml,
+  formatTime,
+  formatDate,
+  getAvatarColor,
+  getInitials,
+  formatMessageBody,
+} from './utils.js';
+
+// Re-export WebSocket functionality
+export { connect, sendMessage, onData } from './websocket.js';
+
+// Re-export UI components
+export {
+  initElements,
+  getElements,
+  updateConnectionStatus,
+  renderAgents,
+  renderMessages,
+  selectChannel,
+  updateOnlineCount,
+  openCommandPalette,
+  closeCommandPalette,
+  filterPaletteResults,
+} from './components.js';
+
+// Re-export app initialization
+export { initApp } from './app.js';
diff --git a/src/dashboard/frontend/state.test.ts b/src/dashboard/frontend/state.test.ts
new file mode 100644
index 000000000..d8ab9270a
--- /dev/null
+++ b/src/dashboard/frontend/state.test.ts
@@ -0,0 +1,227 @@
+/**
+ * Tests for Dashboard State Management
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  state,
+  subscribe,
+  setAgents,
+  setMessages,
+  setCurrentChannel,
+  setConnectionStatus,
+  setWebSocket,
+  incrementReconnectAttempts,
+  getFilteredMessages,
+} from './state.js';
+import type { Agent, Message } from './types.js';
+
+describe('state', () => {
+  // Reset state before each test
+  beforeEach(() => {
+    state.agents = [];
+    state.messages = [];
+    state.currentChannel = 'general';
+    state.isConnected = false;
+    state.ws = null;
+    state.reconnectAttempts = 0;
+  });
+
+  describe('initial state', () => {
+    it('should have empty agents array', () => {
+      expect(state.agents).toEqual([]);
+    });
+
+    it('should have empty messages array', () => {
+      expect(state.messages).toEqual([]);
+    });
+
+    it('should have general as default channel', () => {
+      expect(state.currentChannel).toBe('general');
+    });
+
+    it('should be disconnected by default', () => {
+      expect(state.isConnected).toBe(false);
+    });
+
+    it('should have null websocket', () => {
+      expect(state.ws).toBeNull();
+    });
+
+    it('should have zero reconnect attempts', () => {
+      expect(state.reconnectAttempts).toBe(0);
+    });
+  });
+
+  describe('subscribe', () => {
+    it('should call listener when state changes', () => {
+      const listener = vi.fn();
+      subscribe(listener);
+
+      setAgents([{ name: 'Alice' } as Agent]);
+
+      expect(listener).toHaveBeenCalled();
+    });
+
+    it('should return unsubscribe function', () => {
+      const listener = vi.fn();
+      const unsubscribe = subscribe(listener);
+
+      unsubscribe();
+      setAgents([{ name: 'Bob' } as Agent]);
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('should support multiple listeners', () => {
+      const listener1 = vi.fn();
+      const listener2 = vi.fn();
+
+      subscribe(listener1);
+      subscribe(listener2);
+
+      setAgents([{ name: 'Charlie' } as Agent]);
+
+      expect(listener1).toHaveBeenCalled();
+      expect(listener2).toHaveBeenCalled();
+    });
+  });
+
+  describe('setAgents', () => {
+    it('should update agents array', () => {
+      const agents: Agent[] = [
+        { name: 'Alice', role: 'Developer', cli: 'claude', messageCount: 5 },
+        { name: 'Bob', role: 'Reviewer', cli: 'gemini', messageCount: 3 },
+      ];
+
+      setAgents(agents);
+
+      expect(state.agents).toEqual(agents);
+      expect(state.agents).toHaveLength(2);
+    });
+
+    it('should replace existing agents', () => {
+      setAgents([{ name: 'Alice' } as Agent]);
+      setAgents([{ name: 'Bob' } as Agent]);
+
+      expect(state.agents).toHaveLength(1);
+      expect(state.agents[0].name).toBe('Bob');
+    });
+  });
+
+  describe('setMessages', () => {
+    it('should update messages array', () => {
+      const messages: Message[] = [
+        { id: '1', from: 'Alice', to: 'Bob', content: 'Hello', timestamp: '2025-01-15T12:00:00Z' },
+      ];
+
+      setMessages(messages);
+
+      expect(state.messages).toEqual(messages);
+    });
+
+    it('should replace existing messages', () => {
+      setMessages([{ id: '1' } as Message]);
+      setMessages([{ id: '2' } as Message]);
+
+      expect(state.messages).toHaveLength(1);
+      expect(state.messages[0].id).toBe('2');
+    });
+  });
+
+  describe('setCurrentChannel', () => {
+    it('should update current channel', () => {
+      setCurrentChannel('Alice');
+      expect(state.currentChannel).toBe('Alice');
+    });
+
+    it('should accept agent names as channels', () => {
+      setCurrentChannel('Bob');
+      expect(state.currentChannel).toBe('Bob');
+    });
+  });
+
+  describe('setConnectionStatus', () => {
+    it('should set connected status', () => {
+      setConnectionStatus(true);
+      expect(state.isConnected).toBe(true);
+    });
+
+    it('should set disconnected status', () => {
+      state.isConnected = true;
+      setConnectionStatus(false);
+      expect(state.isConnected).toBe(false);
+    });
+
+    it('should reset reconnect attempts when connected', () => {
+      state.reconnectAttempts = 5;
+      setConnectionStatus(true);
+      expect(state.reconnectAttempts).toBe(0);
+    });
+
+    it('should not reset reconnect attempts when disconnected', () => {
+      state.reconnectAttempts = 5;
+      setConnectionStatus(false);
+      expect(state.reconnectAttempts).toBe(5);
+    });
+  });
+
+  describe('incrementReconnectAttempts', () => {
+    it('should increment reconnect attempts', () => {
+      expect(state.reconnectAttempts).toBe(0);
+
+      incrementReconnectAttempts();
+      expect(state.reconnectAttempts).toBe(1);
+
+      incrementReconnectAttempts();
+      expect(state.reconnectAttempts).toBe(2);
+    });
+  });
+
+  describe('setWebSocket', () => {
+    it('should set websocket instance', () => {
+      const mockWs = {} as WebSocket;
+      setWebSocket(mockWs);
+      expect(state.ws).toBe(mockWs);
+    });
+
+    it('should allow setting to null', () => {
+      state.ws = {} as WebSocket;
+      setWebSocket(null);
+      expect(state.ws).toBeNull();
+    });
+  });
+
+  describe('getFilteredMessages', () => {
+    const messages: Message[] = [
+      { id: '1', from: 'Alice', to: 'Bob', content: 'Direct message', timestamp: '2025-01-15T12:00:00Z' },
+      { id: '2', from: 'Bob', to: '*', content: 'Broadcast', timestamp: '2025-01-15T12:01:00Z' },
+      { id: '3', from: 'Charlie', to: 'Alice', content: 'To Alice', timestamp: '2025-01-15T12:02:00Z' },
+      { id: '4', from: 'Alice', to: '*', content: 'Alice broadcast', timestamp: '2025-01-15T12:03:00Z' },
+    ];
+
+    beforeEach(() => {
+      setMessages(messages);
+    });
+
+    it('should return all messages for general channel', () => {
+      setCurrentChannel('general');
+      const filtered = getFilteredMessages();
+      expect(filtered).toHaveLength(4);
+    });
+
+    it('should return messages to/from agent for agent channel', () => {
+      setCurrentChannel('Alice');
+      const filtered = getFilteredMessages();
+      // Messages where Alice is sender or recipient
+      expect(filtered).toHaveLength(3);
+      expect(filtered.every((m) => m.from === 'Alice' || m.to === 'Alice')).toBe(true);
+    });
+
+    it('should return empty array when no matching messages', () => {
+      setCurrentChannel('Unknown');
+      const filtered = getFilteredMessages();
+      expect(filtered).toHaveLength(0);
+    });
+  });
+});
diff --git a/src/dashboard/frontend/state.ts b/src/dashboard/frontend/state.ts
new file mode 100644
index 000000000..eb9c1dacf
--- /dev/null
+++ b/src/dashboard/frontend/state.ts
@@ -0,0 +1,130 @@
+/**
+ * Dashboard State Management
+ */
+
+import type { Agent, Message, AppState, ChannelType } from './types.js';
+
+/**
+ * Global application state
+ */
+export const state: AppState = {
+  agents: [],
+  messages: [],
+  currentChannel: 'general',
+  currentThread: null,
+  isConnected: false,
+  ws: null,
+  reconnectAttempts: 0,
+};
+
+/**
+ * State update callbacks
+ */
+type StateListener = () => void;
+const listeners: StateListener[] = [];
+
+/**
+ * Subscribe to state changes
+ */
+export function subscribe(listener: StateListener): () => void {
+  listeners.push(listener);
+  return () => {
+    const index = listeners.indexOf(listener);
+    if (index > -1) {
+      listeners.splice(index, 1);
+    }
+  };
+}
+
+/**
+ * Notify all listeners of state change
+ */
+function notifyListeners(): void {
+  listeners.forEach((listener) => listener());
+}
+
+/**
+ * Update agents in state
+ */
+export function setAgents(agents: Agent[]): void {
+  state.agents = agents;
+  notifyListeners();
+}
+
+/**
+ * Update messages in state
+ */
+export function setMessages(messages: Message[]): void {
+  state.messages = messages;
+  notifyListeners();
+}
+
+/**
+ * Set current channel/conversation
+ */
+export function setCurrentChannel(channel: ChannelType): void {
+  state.currentChannel = channel;
+  notifyListeners();
+}
+
+/**
+ * Update connection status
+ */
+export function setConnectionStatus(connected: boolean): void {
+  state.isConnected = connected;
+  if (connected) {
+    state.reconnectAttempts = 0;
+  }
+  notifyListeners();
+}
+
+/**
+ * Increment reconnect attempts
+ */
+export function incrementReconnectAttempts(): void {
+  state.reconnectAttempts++;
+}
+
+/**
+ * Set WebSocket instance
+ */
+export function setWebSocket(ws: WebSocket | null): void {
+  state.ws = ws;
+}
+
+/**
+ * Filter messages based on current channel
+ */
+export function getFilteredMessages(): Message[] {
+  const { messages, currentChannel } = state;
+
+  if (currentChannel === 'general') {
+    return messages;
+  }
+
+  // Filter for specific agent - show messages to/from that agent
+  return messages.filter(
+    (m) => m.from === currentChannel || m.to === currentChannel
+  );
+}
+
+/**
+ * Set current thread for thread panel
+ */
+export function setCurrentThread(thread: string | null): void {
+  state.currentThread = thread;
+}
+
+/**
+ * Get messages for a specific thread
+ */
+export function getThreadMessages(threadId: string): Message[] {
+  return state.messages.filter((m) => m.thread === threadId);
+}
+
+/**
+ * Get reply count for a thread
+ */
+export function getThreadReplyCount(threadId: string): number {
+  return state.messages.filter((m) => m.thread === threadId).length;
+}
diff --git a/src/dashboard/frontend/tsconfig.json b/src/dashboard/frontend/tsconfig.json
new file mode 100644
index 000000000..e48731ac7
--- /dev/null
+++ b/src/dashboard/frontend/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "outDir": "../../../dist/dashboard/frontend",
+    "rootDir": ".",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "target": "ES2022",
+    "declaration": false,
+    "declarationMap": false,
+    "noEmit": true
+  },
+  "include": ["./**/*.ts"],
+  "exclude": ["./**/*.test.ts"]
+}
diff --git a/src/dashboard/frontend/types.ts b/src/dashboard/frontend/types.ts
new file mode 100644
index 000000000..0950ccecf
--- /dev/null
+++ b/src/dashboard/frontend/types.ts
@@ -0,0 +1,113 @@
+/**
+ * Dashboard Frontend Types
+ */
+
+export interface Agent {
+  name: string;
+  role: string;
+  cli: string;
+  messageCount: number;
+  status?: string;
+  lastActive?: string;
+  lastSeen?: string;
+  needsAttention?: boolean;
+}
+
+export interface Message {
+  id: string;
+  from: string;
+  to: string;
+  content: string;
+  timestamp: string;
+  thread?: string;
+  project?: string;  // For cross-project messages
+}
+
+export interface DashboardData {
+  agents: Agent[];
+  messages: Message[];
+  activity: Message[];
+  sessions: SessionInfo[];
+  summaries: AgentSummary[];
+}
+
+export interface SessionInfo {
+  id: string;
+  agentName: string;
+  cli?: string;
+  startedAt: string;
+  endedAt?: string;
+  duration?: string;
+  messageCount: number;
+  summary?: string;
+  isActive: boolean;
+  closedBy?: 'agent' | 'disconnect' | 'error';
+}
+
+export interface AgentSummary {
+  agentName: string;
+  lastUpdated: string;
+  currentTask?: string;
+  completedTasks?: string[];
+  context?: string;
+}
+
+export type ChannelType = 'general' | string;
+
+export interface AppState {
+  agents: Agent[];
+  messages: Message[];
+  currentChannel: ChannelType;
+  currentThread: string | null;
+  isConnected: boolean;
+  ws: WebSocket | null;
+  reconnectAttempts: number;
+}
+
+export interface DOMElements {
+  connectionDot: HTMLElement;
+  channelsList: HTMLElement;
+  agentsList: HTMLElement;
+  messagesList: HTMLElement;
+  currentChannelName: HTMLElement;
+  channelTopic: HTMLElement;
+  onlineCount: HTMLElement;
+  messageInput: HTMLTextAreaElement;
+  sendBtn: HTMLButtonElement;
+  boldBtn: HTMLButtonElement;
+  emojiBtn: HTMLButtonElement;
+  searchTrigger: HTMLElement;
+  commandPaletteOverlay: HTMLElement;
+  paletteSearch: HTMLInputElement;
+  paletteResults: HTMLElement;
+  paletteChannelsSection: HTMLElement;
+  paletteAgentsSection: HTMLElement;
+  paletteMessagesSection: HTMLElement;
+  typingIndicator: HTMLElement;
+  threadPanelOverlay: HTMLElement;
+  threadPanelId: HTMLElement;
+  threadPanelClose: HTMLButtonElement;
+  threadMessages: HTMLElement;
+  threadMessageInput: HTMLTextAreaElement;
+  threadSendBtn: HTMLButtonElement;
+  mentionAutocomplete: HTMLElement;
+  mentionAutocompleteList: HTMLElement;
+  // Spawn modal elements
+  spawnBtn: HTMLButtonElement;
+  spawnModalOverlay: HTMLElement;
+  spawnModalClose: HTMLButtonElement;
+  spawnNameInput: HTMLInputElement;
+  spawnCliInput: HTMLInputElement;
+  spawnTaskInput: HTMLTextAreaElement;
+  spawnSubmitBtn: HTMLButtonElement;
+  spawnStatus: HTMLElement;
+}
+
+export interface SpawnedAgent {
+  name: string;
+  cli: string;
+  task: string;
+  spawnedBy: string;
+  spawnedAt: number;
+  window: string;
+}
diff --git a/src/dashboard/frontend/utils.test.ts b/src/dashboard/frontend/utils.test.ts
new file mode 100644
index 000000000..757ee74a4
--- /dev/null
+++ b/src/dashboard/frontend/utils.test.ts
@@ -0,0 +1,238 @@
+/**
+ * Tests for Dashboard Utility Functions
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  STALE_THRESHOLD_MS,
+  isAgentOnline,
+  escapeHtml,
+  formatTime,
+  formatDate,
+  getAvatarColor,
+  getInitials,
+  formatMessageBody,
+} from './utils.js';
+
+describe('utils', () => {
+  describe('STALE_THRESHOLD_MS', () => {
+    it('should be 30 seconds', () => {
+      expect(STALE_THRESHOLD_MS).toBe(30000);
+    });
+  });
+
+  describe('isAgentOnline', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2025-01-15T12:00:00.000Z'));
+    });
+
+    it('should return false for undefined lastSeen', () => {
+      expect(isAgentOnline(undefined)).toBe(false);
+    });
+
+    it('should return false for empty string', () => {
+      expect(isAgentOnline('')).toBe(false);
+    });
+
+    it('should return false for invalid date string', () => {
+      expect(isAgentOnline('not-a-date')).toBe(false);
+    });
+
+    it('should return true for recent timestamp (within 30s)', () => {
+      const recentTime = new Date(Date.now() - 10000).toISOString(); // 10 seconds ago
+      expect(isAgentOnline(recentTime)).toBe(true);
+    });
+
+    it('should return false for stale timestamp (over 30s)', () => {
+      const staleTime = new Date(Date.now() - 60000).toISOString(); // 60 seconds ago
+      expect(isAgentOnline(staleTime)).toBe(false);
+    });
+
+    it('should return true for exactly at threshold', () => {
+      const atThreshold = new Date(Date.now() - STALE_THRESHOLD_MS + 1).toISOString();
+      expect(isAgentOnline(atThreshold)).toBe(true);
+    });
+
+    it('should return false for exactly past threshold', () => {
+      const pastThreshold = new Date(Date.now() - STALE_THRESHOLD_MS - 1).toISOString();
+      expect(isAgentOnline(pastThreshold)).toBe(false);
+    });
+  });
+
+  describe('escapeHtml', () => {
+    it('should return empty string for undefined', () => {
+      expect(escapeHtml(undefined)).toBe('');
+    });
+
+    it('should return empty string for empty string', () => {
+      expect(escapeHtml('')).toBe('');
+    });
+
+    it('should escape HTML special characters', () => {
+      expect(escapeHtml('<script>alert("xss")</script>')).toBe(
+        '&lt;script&gt;alert("xss")&lt;/script&gt;'
+      );
+    });
+
+    it('should escape ampersands', () => {
+      expect(escapeHtml('foo & bar')).toBe('foo &amp; bar');
+    });
+
+    it('should escape quotes', () => {
+      expect(escapeHtml('say "hello"')).toBe('say "hello"');
+    });
+
+    it('should handle mixed content', () => {
+      expect(escapeHtml('<div class="test">Hello & goodbye</div>')).toBe(
+        '&lt;div class="test"&gt;Hello &amp; goodbye&lt;/div&gt;'
+      );
+    });
+
+    it('should preserve normal text', () => {
+      expect(escapeHtml('Hello World')).toBe('Hello World');
+    });
+  });
+
+  describe('formatTime', () => {
+    it('should format timestamp to locale time', () => {
+      const timestamp = '2025-01-15T14:30:00.000Z';
+      const result = formatTime(timestamp);
+      // Result depends on locale, but should contain hour and minute
+      expect(result).toMatch(/\d{1,2}:\d{2}/);
+    });
+
+    it('should handle midnight', () => {
+      const timestamp = '2025-01-15T00:00:00.000Z';
+      const result = formatTime(timestamp);
+      expect(result).toBeTruthy();
+    });
+  });
+
+  describe('formatDate', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2025-01-15T12:00:00.000Z'));
+    });
+
+    it('should return "Today" for today\'s date', () => {
+      const today = '2025-01-15T10:00:00.000Z';
+      expect(formatDate(today)).toBe('Today');
+    });
+
+    it('should return "Yesterday" for yesterday\'s date', () => {
+      const yesterday = '2025-01-14T10:00:00.000Z';
+      expect(formatDate(yesterday)).toBe('Yesterday');
+    });
+
+    it('should return formatted date for older dates', () => {
+      const oldDate = '2025-01-10T10:00:00.000Z';
+      const result = formatDate(oldDate);
+      // Should include weekday, month, and day
+      expect(result).toContain('January');
+      expect(result).toContain('10');
+    });
+  });
+
+  describe('getAvatarColor', () => {
+    it('should return a valid hex color', () => {
+      const color = getAvatarColor('Alice');
+      expect(color).toMatch(/^#[0-9a-f]{6}$/i);
+    });
+
+    it('should return consistent color for same name', () => {
+      const color1 = getAvatarColor('Bob');
+      const color2 = getAvatarColor('Bob');
+      expect(color1).toBe(color2);
+    });
+
+    it('should return different colors for different names', () => {
+      const color1 = getAvatarColor('Alice');
+      const color2 = getAvatarColor('Charlie');
+      // Not guaranteed to be different, but likely
+      expect(typeof color1).toBe('string');
+      expect(typeof color2).toBe('string');
+    });
+
+    it('should handle empty string', () => {
+      const color = getAvatarColor('');
+      expect(color).toMatch(/^#[0-9a-f]{6}$/i);
+    });
+
+    it('should handle special characters', () => {
+      const color = getAvatarColor('Agent-123_test');
+      expect(color).toMatch(/^#[0-9a-f]{6}$/i);
+    });
+  });
+
+  describe('getInitials', () => {
+    it('should return first 2 characters uppercase', () => {
+      expect(getInitials('Alice')).toBe('AL');
+    });
+
+    it('should handle lowercase names', () => {
+      expect(getInitials('bob')).toBe('BO');
+    });
+
+    it('should handle single character names', () => {
+      expect(getInitials('A')).toBe('A');
+    });
+
+    it('should handle long names', () => {
+      expect(getInitials('Alexander')).toBe('AL');
+    });
+
+    it('should handle names with numbers', () => {
+      expect(getInitials('Agent123')).toBe('AG');
+    });
+  });
+
+  describe('formatMessageBody', () => {
+    it('should return empty string for undefined', () => {
+      expect(formatMessageBody(undefined)).toBe('');
+    });
+
+    it('should return empty string for empty string', () => {
+      expect(formatMessageBody('')).toBe('');
+    });
+
+    it('should escape HTML', () => {
+      expect(formatMessageBody('<script>alert(1)</script>')).toContain('&lt;script&gt;');
+    });
+
+    it('should convert inline code with backticks', () => {
+      const result = formatMessageBody('Use `console.log()` for debugging');
+      expect(result).toContain('<code>console.log()</code>');
+    });
+
+    it('should convert code blocks with triple backticks', () => {
+      const result = formatMessageBody('```\nconst x = 1;\n```');
+      expect(result).toContain('<pre>');
+      expect(result).toContain('const x = 1;');
+      expect(result).toContain('</pre>');
+    });
+
+    it('should handle mixed content', () => {
+      const result = formatMessageBody('Hello `world` and ```code block```');
+      expect(result).toContain('<code>world</code>');
+      expect(result).toContain('<pre>code block</pre>');
+    });
+
+    it('should preserve plain text', () => {
+      expect(formatMessageBody('Hello World')).toBe('Hello World');
+    });
+
+    it('should convert newlines to <br> tags', () => {
+      expect(formatMessageBody('Hello\nWorld')).toBe('Hello<br>World');
+    });
+
+    it('should handle multiple newlines', () => {
+      expect(formatMessageBody('Line1\nLine2\nLine3')).toBe('Line1<br>Line2<br>Line3');
+    });
+
+    it('should handle newlines with other content', () => {
+      const result = formatMessageBody('Check this:\n- Item 1\n- Item 2');
+      expect(result).toBe('Check this:<br>- Item 1<br>- Item 2');
+    });
+  });
+});
diff --git a/src/dashboard/frontend/utils.ts b/src/dashboard/frontend/utils.ts
new file mode 100644
index 000000000..3a19aec70
--- /dev/null
+++ b/src/dashboard/frontend/utils.ts
@@ -0,0 +1,104 @@
+/**
+ * Dashboard Utility Functions
+ */
+
+/** Threshold for considering an agent offline (30 seconds) */
+export const STALE_THRESHOLD_MS = 30000;
+
+/**
+ * Check if an agent is online based on last seen timestamp
+ */
+export function isAgentOnline(lastSeen: string | undefined): boolean {
+  if (!lastSeen) return false;
+  const ts = Date.parse(lastSeen);
+  if (Number.isNaN(ts)) return false;
+  return Date.now() - ts < STALE_THRESHOLD_MS;
+}
+
+/**
+ * Escape HTML to prevent XSS
+ */
+export function escapeHtml(text: string | undefined): string {
+  if (!text) return '';
+  const div = document.createElement('div');
+  div.textContent = text;
+  return div.innerHTML;
+}
+
+/**
+ * Format timestamp to locale time string
+ */
+export function formatTime(timestamp: string): string {
+  const date = new Date(timestamp);
+  return date.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
+}
+
+/**
+ * Format timestamp to human-readable date
+ */
+export function formatDate(timestamp: string): string {
+  const date = new Date(timestamp);
+  const today = new Date();
+  const yesterday = new Date(today);
+  yesterday.setDate(yesterday.getDate() - 1);
+
+  if (date.toDateString() === today.toDateString()) {
+    return 'Today';
+  } else if (date.toDateString() === yesterday.toDateString()) {
+    return 'Yesterday';
+  } else {
+    return date.toLocaleDateString([], {
+      weekday: 'long',
+      month: 'long',
+      day: 'numeric',
+    });
+  }
+}
+
+/**
+ * Generate a consistent color for an agent based on their name
+ */
+export function getAvatarColor(name: string): string {
+  const colors = [
+    '#e01e5a',
+    '#2bac76',
+    '#e8a427',
+    '#1264a3',
+    '#7c3aed',
+    '#0d9488',
+    '#dc2626',
+    '#9333ea',
+    '#ea580c',
+    '#0891b2',
+  ];
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = name.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return colors[Math.abs(hash) % colors.length];
+}
+
+/**
+ * Get initials from a name (first 2 characters, uppercase)
+ */
+export function getInitials(name: string): string {
+  return name.substring(0, 2).toUpperCase();
+}
+
+/**
+ * Format message body with basic markdown-like formatting
+ */
+export function formatMessageBody(content: string | undefined): string {
+  if (!content) return '';
+
+  let escaped = escapeHtml(content);
+
+  // Simple code block detection
+  escaped = escaped.replace(/```([\s\S]*?)```/g, '<pre>$1</pre>');
+  escaped = escaped.replace(/`([^`]+)`/g, '<code>$1</code>');
+
+  // Convert newlines to <br> for proper multi-line display
+  escaped = escaped.replace(/\n/g, '<br>');
+
+  return escaped;
+}
diff --git a/src/dashboard/frontend/websocket.ts b/src/dashboard/frontend/websocket.ts
new file mode 100644
index 000000000..c6cb7aa80
--- /dev/null
+++ b/src/dashboard/frontend/websocket.ts
@@ -0,0 +1,111 @@
+/**
+ * WebSocket Connection Handler
+ */
+
+import type { DashboardData } from './types.js';
+import {
+  state,
+  setAgents,
+  setMessages,
+  setConnectionStatus,
+  setWebSocket,
+  incrementReconnectAttempts,
+} from './state.js';
+
+type DataHandler = (data: DashboardData) => void;
+
+let dataHandler: DataHandler | null = null;
+
+/**
+ * Set the handler for incoming data
+ */
+export function onData(handler: DataHandler): void {
+  dataHandler = handler;
+}
+
+/**
+ * Connect to the WebSocket server
+ */
+export function connect(): void {
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  const ws = new WebSocket(`${protocol}//${window.location.host}/ws`);
+
+  ws.onopen = (): void => {
+    setConnectionStatus(true);
+  };
+
+  ws.onclose = (): void => {
+    setConnectionStatus(false);
+    // Reconnect with exponential backoff
+    const delay = Math.min(1000 * Math.pow(2, state.reconnectAttempts), 30000);
+    incrementReconnectAttempts();
+    setTimeout(connect, delay);
+  };
+
+  ws.onerror = (error): void => {
+    console.error('WebSocket error:', error);
+  };
+
+  ws.onmessage = (event: MessageEvent): void => {
+    try {
+      const data: DashboardData = JSON.parse(event.data as string);
+      handleData(data);
+    } catch (e) {
+      console.error('Failed to parse message:', e);
+    }
+  };
+
+  setWebSocket(ws);
+}
+
+/**
+ * Handle incoming dashboard data
+ */
+function handleData(data: DashboardData): void {
+  console.log('[WS] Received data:', { agentCount: data.agents?.length, messageCount: data.messages?.length });
+
+  if (data.agents) {
+    console.log('[WS] Setting agents:', data.agents.map(a => a.name));
+    setAgents(data.agents);
+  }
+
+  if (data.messages) {
+    setMessages(data.messages);
+  }
+
+  if (dataHandler) {
+    dataHandler(data);
+  }
+}
+
+/**
+ * Send a message via the REST API
+ */
+export async function sendMessage(
+  to: string,
+  message: string,
+  thread?: string
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const body: { to: string; message: string; thread?: string } = { to, message };
+    if (thread) {
+      body.thread = thread;
+    }
+
+    const response = await fetch('/api/send', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+
+    const result = await response.json();
+
+    if (response.ok && result.success) {
+      return { success: true };
+    } else {
+      return { success: false, error: result.error || 'Failed to send message' };
+    }
+  } catch (err) {
+    return { success: false, error: 'Network error - could not send message' };
+  }
+}
diff --git a/src/dashboard/metrics.ts b/src/dashboard/metrics.ts
new file mode 100644
index 000000000..9c387ac0b
--- /dev/null
+++ b/src/dashboard/metrics.ts
@@ -0,0 +1,308 @@
+/**
+ * Metrics collection and computation for the Agent Relay dashboard.
+ * Provides real-time metrics for monitoring: throughput, agent health, error rates.
+ */
+
+import type { StorageAdapter, StoredMessage } from '../storage/adapter.js';
+
+export interface AgentMetrics {
+  name: string;
+  messagesSent: number;
+  messagesReceived: number;
+  firstSeen: string;
+  lastSeen: string;
+  isOnline: boolean;
+  uptimeSeconds: number;
+}
+
+export interface ThroughputMetrics {
+  messagesLastMinute: number;
+  messagesLastHour: number;
+  messagesLast24Hours: number;
+  avgMessagesPerMinute: number;
+}
+
+export interface SessionMetrics {
+  totalSessions: number;
+  activeSessions: number;
+  closedByAgent: number;
+  closedByDisconnect: number;
+  closedByError: number;
+  errorRate: number; // Percentage of sessions closed by error
+  recentSessions: Array<{
+    id: string;
+    agentName: string;
+    startedAt: string;
+    endedAt?: string;
+    closedBy?: 'agent' | 'disconnect' | 'error';
+    messageCount: number;
+  }>;
+}
+
+export interface SystemMetrics {
+  totalAgents: number;
+  onlineAgents: number;
+  offlineAgents: number;
+  totalMessages: number;
+  throughput: ThroughputMetrics;
+  sessions: SessionMetrics;
+  agents: AgentMetrics[];
+  timestamp: string;
+}
+
+export interface PrometheusMetric {
+  name: string;
+  help: string;
+  type: 'counter' | 'gauge' | 'histogram';
+  values: Array<{ labels: Record<string, string>; value: number }>;
+}
+
+// Consider agents offline after 5 minutes of inactivity
+const OFFLINE_THRESHOLD_MS = 5 * 60 * 1000;
+
+/**
+ * Compute agent-level metrics from registry data
+ */
+export function computeAgentMetrics(
+  agents: Array<{
+    name: string;
+    messagesSent: number;
+    messagesReceived: number;
+    firstSeen: string;
+    lastSeen: string;
+  }>
+): AgentMetrics[] {
+  const now = Date.now();
+
+  return agents.map((agent) => {
+    const lastSeenTime = new Date(agent.lastSeen).getTime();
+    const firstSeenTime = new Date(agent.firstSeen).getTime();
+    const isOnline = now - lastSeenTime < OFFLINE_THRESHOLD_MS;
+    const uptimeSeconds = Math.floor((now - firstSeenTime) / 1000);
+
+    return {
+      name: agent.name,
+      messagesSent: agent.messagesSent,
+      messagesReceived: agent.messagesReceived,
+      firstSeen: agent.firstSeen,
+      lastSeen: agent.lastSeen,
+      isOnline,
+      uptimeSeconds,
+    };
+  });
+}
+
+/**
+ * Compute throughput metrics from message history
+ */
+export function computeThroughputMetrics(messages: Array<{ timestamp: string }>): ThroughputMetrics {
+  const now = Date.now();
+  const oneMinuteAgo = now - 60 * 1000;
+  const oneHourAgo = now - 60 * 60 * 1000;
+  const oneDayAgo = now - 24 * 60 * 60 * 1000;
+
+  let lastMinute = 0;
+  let lastHour = 0;
+  let last24Hours = 0;
+
+  for (const msg of messages) {
+    const ts = new Date(msg.timestamp).getTime();
+    if (ts >= oneMinuteAgo) lastMinute++;
+    if (ts >= oneHourAgo) lastHour++;
+    if (ts >= oneDayAgo) last24Hours++;
+  }
+
+  // Calculate average messages per minute over the last hour
+  const avgMessagesPerMinute = lastHour / 60;
+
+  return {
+    messagesLastMinute: lastMinute,
+    messagesLastHour: lastHour,
+    messagesLast24Hours: last24Hours,
+    avgMessagesPerMinute: Math.round(avgMessagesPerMinute * 100) / 100,
+  };
+}
+
+/**
+ * Compute session lifecycle metrics from session history
+ */
+export function computeSessionMetrics(
+  sessions: Array<{
+    id: string;
+    agentName: string;
+    startedAt: number;
+    endedAt?: number;
+    closedBy?: 'agent' | 'disconnect' | 'error';
+    messageCount: number;
+  }>
+): SessionMetrics {
+  let activeSessions = 0;
+  let closedByAgent = 0;
+  let closedByDisconnect = 0;
+  let closedByError = 0;
+
+  for (const session of sessions) {
+    if (!session.endedAt) {
+      activeSessions++;
+    } else {
+      switch (session.closedBy) {
+        case 'agent':
+          closedByAgent++;
+          break;
+        case 'disconnect':
+          closedByDisconnect++;
+          break;
+        case 'error':
+          closedByError++;
+          break;
+        default:
+          // Ended but no closedBy - treat as disconnect
+          closedByDisconnect++;
+      }
+    }
+  }
+
+  const closedSessions = closedByAgent + closedByDisconnect + closedByError;
+  const errorRate = closedSessions > 0 ? (closedByError / closedSessions) * 100 : 0;
+
+  // Format recent sessions for display (most recent 10)
+  const recentSessions = sessions
+    .slice(0, 10)
+    .map((s) => ({
+      id: s.id,
+      agentName: s.agentName,
+      startedAt: new Date(s.startedAt).toISOString(),
+      endedAt: s.endedAt ? new Date(s.endedAt).toISOString() : undefined,
+      closedBy: s.closedBy,
+      messageCount: s.messageCount,
+    }));
+
+  return {
+    totalSessions: sessions.length,
+    activeSessions,
+    closedByAgent,
+    closedByDisconnect,
+    closedByError,
+    errorRate: Math.round(errorRate * 100) / 100,
+    recentSessions,
+  };
+}
+
+/**
+ * Compute full system metrics
+ */
+export function computeSystemMetrics(
+  agents: Array<{
+    name: string;
+    messagesSent: number;
+    messagesReceived: number;
+    firstSeen: string;
+    lastSeen: string;
+  }>,
+  messages: Array<{ timestamp: string }>,
+  sessions: Array<{
+    id: string;
+    agentName: string;
+    startedAt: number;
+    endedAt?: number;
+    closedBy?: 'agent' | 'disconnect' | 'error';
+    messageCount: number;
+  }> = []
+): SystemMetrics {
+  const agentMetrics = computeAgentMetrics(agents);
+  const throughput = computeThroughputMetrics(messages);
+  const sessionMetrics = computeSessionMetrics(sessions);
+
+  const onlineAgents = agentMetrics.filter((a) => a.isOnline).length;
+  const totalMessages = agents.reduce((sum, a) => sum + a.messagesSent + a.messagesReceived, 0) / 2; // Divide by 2 since each message is counted twice (sent + received)
+
+  return {
+    totalAgents: agents.length,
+    onlineAgents,
+    offlineAgents: agents.length - onlineAgents,
+    totalMessages: Math.round(totalMessages),
+    throughput,
+    sessions: sessionMetrics,
+    agents: agentMetrics,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Format metrics in Prometheus exposition format
+ */
+export function formatPrometheusMetrics(metrics: SystemMetrics): string {
+  const lines: string[] = [];
+
+  // Agent counts
+  lines.push('# HELP agent_relay_agents_total Total number of registered agents');
+  lines.push('# TYPE agent_relay_agents_total gauge');
+  lines.push(`agent_relay_agents_total ${metrics.totalAgents}`);
+
+  lines.push('# HELP agent_relay_agents_online Number of online agents');
+  lines.push('# TYPE agent_relay_agents_online gauge');
+  lines.push(`agent_relay_agents_online ${metrics.onlineAgents}`);
+
+  // Message throughput
+  lines.push('# HELP agent_relay_messages_total Total messages processed');
+  lines.push('# TYPE agent_relay_messages_total counter');
+  lines.push(`agent_relay_messages_total ${metrics.totalMessages}`);
+
+  lines.push('# HELP agent_relay_messages_last_minute Messages in last minute');
+  lines.push('# TYPE agent_relay_messages_last_minute gauge');
+  lines.push(`agent_relay_messages_last_minute ${metrics.throughput.messagesLastMinute}`);
+
+  lines.push('# HELP agent_relay_messages_last_hour Messages in last hour');
+  lines.push('# TYPE agent_relay_messages_last_hour gauge');
+  lines.push(`agent_relay_messages_last_hour ${metrics.throughput.messagesLastHour}`);
+
+  lines.push('# HELP agent_relay_messages_avg_per_minute Average messages per minute');
+  lines.push('# TYPE agent_relay_messages_avg_per_minute gauge');
+  lines.push(`agent_relay_messages_avg_per_minute ${metrics.throughput.avgMessagesPerMinute}`);
+
+  // Per-agent metrics
+  lines.push('# HELP agent_relay_agent_messages_sent Messages sent by agent');
+  lines.push('# TYPE agent_relay_agent_messages_sent counter');
+  for (const agent of metrics.agents) {
+    lines.push(`agent_relay_agent_messages_sent{agent="${agent.name}"} ${agent.messagesSent}`);
+  }
+
+  lines.push('# HELP agent_relay_agent_messages_received Messages received by agent');
+  lines.push('# TYPE agent_relay_agent_messages_received counter');
+  for (const agent of metrics.agents) {
+    lines.push(`agent_relay_agent_messages_received{agent="${agent.name}"} ${agent.messagesReceived}`);
+  }
+
+  lines.push('# HELP agent_relay_agent_online Agent online status (1=online, 0=offline)');
+  lines.push('# TYPE agent_relay_agent_online gauge');
+  for (const agent of metrics.agents) {
+    lines.push(`agent_relay_agent_online{agent="${agent.name}"} ${agent.isOnline ? 1 : 0}`);
+  }
+
+  lines.push('# HELP agent_relay_agent_uptime_seconds Agent uptime in seconds');
+  lines.push('# TYPE agent_relay_agent_uptime_seconds gauge');
+  for (const agent of metrics.agents) {
+    lines.push(`agent_relay_agent_uptime_seconds{agent="${agent.name}"} ${agent.uptimeSeconds}`);
+  }
+
+  // Session lifecycle metrics
+  lines.push('# HELP agent_relay_sessions_total Total number of sessions');
+  lines.push('# TYPE agent_relay_sessions_total counter');
+  lines.push(`agent_relay_sessions_total ${metrics.sessions.totalSessions}`);
+
+  lines.push('# HELP agent_relay_sessions_active Number of active sessions');
+  lines.push('# TYPE agent_relay_sessions_active gauge');
+  lines.push(`agent_relay_sessions_active ${metrics.sessions.activeSessions}`);
+
+  lines.push('# HELP agent_relay_sessions_closed_total Sessions closed by type');
+  lines.push('# TYPE agent_relay_sessions_closed_total counter');
+  lines.push(`agent_relay_sessions_closed_total{closed_by="agent"} ${metrics.sessions.closedByAgent}`);
+  lines.push(`agent_relay_sessions_closed_total{closed_by="disconnect"} ${metrics.sessions.closedByDisconnect}`);
+  lines.push(`agent_relay_sessions_closed_total{closed_by="error"} ${metrics.sessions.closedByError}`);
+
+  lines.push('# HELP agent_relay_sessions_error_rate Percentage of sessions closed by error');
+  lines.push('# TYPE agent_relay_sessions_error_rate gauge');
+  lines.push(`agent_relay_sessions_error_rate ${metrics.sessions.errorRate}`);
+
+  return lines.join('\n') + '\n';
+}
diff --git a/src/dashboard/needs-attention.test.ts b/src/dashboard/needs-attention.test.ts
new file mode 100644
index 000000000..875262275
--- /dev/null
+++ b/src/dashboard/needs-attention.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+import { computeNeedsAttention, type AttentionMessage } from './needs-attention.js';
+
+const baseTs = Date.now();
+
+const msg = (overrides: Partial<AttentionMessage>): AttentionMessage => ({
+  from: 'A',
+  to: 'B',
+  timestamp: new Date(baseTs).toISOString(),
+  ...overrides,
+});
+
+describe('computeNeedsAttention', () => {
+  it('flags agents with inbound messages and no reply', () => {
+    const messages: AttentionMessage[] = [
+      msg({ from: 'Alice', to: 'Bob', timestamp: new Date(baseTs).toISOString() }),
+    ];
+
+    const result = computeNeedsAttention(messages);
+    expect(result.has('Bob')).toBe(true);
+    expect(result.has('Alice')).toBe(false);
+  });
+
+  it('clears attention when agent replies to sender', () => {
+    const messages: AttentionMessage[] = [
+      msg({ from: 'Alice', to: 'Bob', timestamp: new Date(baseTs).toISOString() }),
+      msg({ from: 'Bob', to: 'Alice', timestamp: new Date(baseTs + 1000).toISOString() }),
+    ];
+
+    const result = computeNeedsAttention(messages);
+    expect(result.has('Bob')).toBe(false);
+  });
+
+  it('tracks per-sender so replying elsewhere does not clear attention', () => {
+    const messages: AttentionMessage[] = [
+      msg({ from: 'Alice', to: 'Bob', timestamp: new Date(baseTs).toISOString() }),
+      msg({ from: 'Bob', to: 'Carol', timestamp: new Date(baseTs + 1000).toISOString() }),
+    ];
+
+    const result = computeNeedsAttention(messages);
+    expect(result.has('Bob')).toBe(true);
+  });
+
+  it('uses thread ID as the conversation key (broadcast replies count)', () => {
+    const threadId = 'thread-123';
+    const messages: AttentionMessage[] = [
+      msg({ from: 'Alice', to: 'Bob', thread: threadId, timestamp: new Date(baseTs).toISOString() }),
+      msg({ from: 'Bob', to: '*', thread: threadId, timestamp: new Date(baseTs + 2000).toISOString() }),
+    ];
+
+    const result = computeNeedsAttention(messages);
+    expect(result.has('Bob')).toBe(false);
+  });
+
+  it('broadcasts clear attention (agent is actively participating)', () => {
+    const messages: AttentionMessage[] = [
+      msg({ from: 'Alice', to: 'Bob', timestamp: new Date(baseTs).toISOString() }),
+      msg({ from: 'Bob', to: '*', timestamp: new Date(baseTs + 1000).toISOString() }),
+    ];
+
+    const result = computeNeedsAttention(messages);
+    // Broadcasting shows the agent is active and engaged
+    expect(result.has('Bob')).toBe(false);
+  });
+
+  it('ignores messages older than 30 minutes', () => {
+    const thirtyOneMinutesAgo = baseTs - 31 * 60 * 1000;
+    const messages: AttentionMessage[] = [
+      msg({ from: 'Alice', to: 'Bob', timestamp: new Date(thirtyOneMinutesAgo).toISOString() }),
+    ];
+
+    const result = computeNeedsAttention(messages);
+    // Old message should not trigger attention
+    expect(result.has('Bob')).toBe(false);
+  });
+
+  it('still flags recent messages within the time window', () => {
+    const fiveMinutesAgo = baseTs - 5 * 60 * 1000;
+    const messages: AttentionMessage[] = [
+      msg({ from: 'Alice', to: 'Bob', timestamp: new Date(fiveMinutesAgo).toISOString() }),
+    ];
+
+    const result = computeNeedsAttention(messages);
+    // Recent message should trigger attention
+    expect(result.has('Bob')).toBe(true);
+  });
+});
diff --git a/src/dashboard/needs-attention.ts b/src/dashboard/needs-attention.ts
new file mode 100644
index 000000000..4a35c2352
--- /dev/null
+++ b/src/dashboard/needs-attention.ts
@@ -0,0 +1,93 @@
+/**
+ * Derive which agents currently need attention based on message history.
+ *
+ * Heuristic:
+ * - Track the most recent inbound message to an agent for each conversation key.
+ * - Conversation key is thread ID if present, otherwise the counterparty agent.
+ * - Track the most recent outbound message from the agent for the same key.
+ * - An agent needs attention if their latest inbound message for any key is newer
+ *   than their latest outbound message for that key.
+ */
+
+export interface AttentionMessage {
+  from: string;
+  to: string;
+  timestamp: string;
+  thread?: string;
+}
+
+type TimestampMap = Map<string, number>;
+
+// Only consider messages from the last 30 minutes for "needs attention"
+const ATTENTION_WINDOW_MS = 30 * 60 * 1000;
+
+function updateLatest(map: Map<string, TimestampMap>, agent: string, key: string, ts: number): void {
+  const agentMap = map.get(agent) ?? new Map<string, number>();
+  const prev = agentMap.get(key) ?? -Infinity;
+  if (ts > prev) {
+    agentMap.set(key, ts);
+    map.set(agent, agentMap);
+  }
+}
+
+/**
+ * Compute which agents have pending inbound messages they haven't answered.
+ * Only considers messages within the attention window (last 30 minutes).
+ */
+export function computeNeedsAttention(messages: AttentionMessage[]): Set<string> {
+  const latestInbound: Map<string, TimestampMap> = new Map();  // agent -> (key -> ts)
+  const latestOutbound: Map<string, TimestampMap> = new Map(); // agent -> (key -> ts)
+  const now = Date.now();
+  const cutoffTime = now - ATTENTION_WINDOW_MS;
+
+  for (const message of messages) {
+    const ts = Date.parse(message.timestamp);
+    if (Number.isNaN(ts)) continue;
+
+    // Inbound: messages directed to a specific agent (ignore broadcasts)
+    if (message.to && message.to !== '*') {
+      const inboundKey = message.thread ? `thread:${message.thread}` : `sender:${message.from}`;
+      updateLatest(latestInbound, message.to, inboundKey, ts);
+    }
+
+    // Outbound: track replies by thread (preferred) or by target agent
+    // Also treat broadcasts as clearing attention for all prior senders
+    if (message.from) {
+      const outboundKey = message.thread
+        ? `thread:${message.thread}`
+        : (message.to && message.to !== '*')
+          ? `sender:${message.to}`
+          : null;
+
+      if (outboundKey) {
+        updateLatest(latestOutbound, message.from, outboundKey, ts);
+      }
+
+      // Broadcasts clear attention: agent is actively participating
+      // Track as a "catch-all" outbound timestamp for this agent
+      if (message.to === '*') {
+        updateLatest(latestOutbound, message.from, '__broadcast__', ts);
+      }
+    }
+  }
+
+  const needsAttention = new Set<string>();
+
+  latestInbound.forEach((keyMap, agent) => {
+    keyMap.forEach((inboundTs, key) => {
+      // Skip if inbound message is too old (outside attention window)
+      if (inboundTs < cutoffTime) return;
+
+      const outboundTs = latestOutbound.get(agent)?.get(key) ?? -Infinity;
+      // Also check if agent sent a broadcast after the inbound message
+      const broadcastTs = latestOutbound.get(agent)?.get('__broadcast__') ?? -Infinity;
+      const latestReply = Math.max(outboundTs, broadcastTs);
+
+      if (inboundTs > latestReply) {
+        needsAttention.add(agent);
+      }
+    });
+  });
+
+  return needsAttention;
+}
diff --git a/src/dashboard/public/bridge.html b/src/dashboard/public/bridge.html
new file mode 100644
index 000000000..1f55accd9
--- /dev/null
+++ b/src/dashboard/public/bridge.html
@@ -0,0 +1,1272 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Agent Relay - Bridge</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <style>
+    /* ========================================
+       Design Tokens (matching index.html)
+       ======================================== */
+    :root {
+      --bg-workspace: #1a1d21;
+      --bg-sidebar: #19171d;
+      --bg-channel-active: #1164a3;
+      --bg-channel-hover: rgba(255, 255, 255, 0.04);
+      --bg-main: #222529;
+      --bg-message-hover: rgba(255, 255, 255, 0.03);
+      --bg-input: rgba(255, 255, 255, 0.04);
+      --bg-modal: #2a2d32;
+      --bg-card: #2a2d32;
+      --bg-card-hover: #32363c;
+      --text-primary: #d1d2d3;
+      --text-secondary: #ababad;
+      --text-muted: #8d8d8e;
+      --text-channel: #bcabbc;
+      --text-channel-active: #ffffff;
+      --text-link: #1d9bd1;
+      --accent-primary: #1264a3;
+      --accent-green: #2bac76;
+      --accent-yellow: #e8a427;
+      --accent-red: #e01e5a;
+      --accent-purple: #7c3aed;
+      --status-online: #2bac76;
+      --status-away: #e8a427;
+      --status-offline: #616061;
+      --border-subtle: rgba(255, 255, 255, 0.1);
+      --border-divider: rgba(255, 255, 255, 0.06);
+      --sidebar-width: 260px;
+      --header-height: 49px;
+      --font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      --font-mono: 'JetBrains Mono', ui-monospace, monospace;
+      --transition-fast: 0.1s ease;
+      --transition-normal: 0.2s ease;
+      --shadow-modal: 0 18px 50px rgba(0, 0, 0, 0.6);
+    }
+
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    html, body { height: 100%; overflow: hidden; }
+    body {
+      font-family: var(--font-family);
+      font-size: 15px;
+      line-height: 1.46668;
+      color: var(--text-primary);
+      background: var(--bg-workspace);
+      -webkit-font-smoothing: antialiased;
+    }
+
+    .app-container { display: flex; height: 100vh; width: 100vw; }
+
+    /* Sidebar */
+    .sidebar {
+      width: var(--sidebar-width);
+      background: var(--bg-sidebar);
+      display: flex;
+      flex-direction: column;
+      flex-shrink: 0;
+      border-right: 1px solid var(--border-divider);
+    }
+
+    .workspace-header {
+      height: var(--header-height);
+      padding: 0 16px;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      border-bottom: 1px solid var(--border-divider);
+      flex-shrink: 0;
+    }
+
+    .workspace-name {
+      font-size: 18px;
+      font-weight: 700;
+      color: var(--text-primary);
+      display: flex;
+      align-items: center;
+      gap: 6px;
+    }
+
+    .workspace-name .status-dot {
+      width: 10px;
+      height: 10px;
+      border-radius: 50%;
+      background: var(--status-online);
+      flex-shrink: 0;
+    }
+
+    .workspace-name .status-dot.offline { background: var(--status-offline); }
+
+    .sidebar-content {
+      flex: 1;
+      overflow-y: auto;
+      padding: 12px 0;
+    }
+
+    .section { margin-bottom: 8px; }
+
+    .section-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 0 16px 0 12px;
+      height: 26px;
+    }
+
+    .section-title {
+      display: flex;
+      align-items: center;
+      gap: 4px;
+      font-size: 15px;
+      color: var(--text-channel);
+    }
+
+    .section-title svg { width: 10px; height: 10px; opacity: 0.7; }
+
+    .section-add-btn {
+      width: 20px;
+      height: 20px;
+      border: none;
+      background: transparent;
+      color: var(--text-muted);
+      border-radius: 4px;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: all var(--transition-fast);
+    }
+
+    .section-add-btn:hover { background: rgba(255, 255, 255, 0.1); color: var(--text-primary); }
+
+    .channel-list { list-style: none; padding: 4px 8px; }
+
+    .channel-item {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 6px 8px;
+      border-radius: 6px;
+      cursor: pointer;
+      transition: background var(--transition-fast);
+      color: var(--text-channel);
+      font-size: 15px;
+    }
+
+    .channel-item:hover { background: var(--bg-channel-hover); }
+    .channel-item.active { background: var(--bg-channel-active); color: var(--text-channel-active); }
+
+    .project-status-dot {
+      width: 9px;
+      height: 9px;
+      border-radius: 50%;
+      background: var(--status-offline);
+      flex-shrink: 0;
+    }
+
+    .channel-item.connected .project-status-dot { background: var(--status-online); }
+    .channel-item.reconnecting .project-status-dot { background: var(--status-away); }
+
+    .channel-name { flex: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+
+    .agent-avatar {
+      width: 24px;
+      height: 24px;
+      border-radius: 4px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 11px;
+      font-weight: 600;
+      color: white;
+      flex-shrink: 0;
+      position: relative;
+    }
+
+    .presence-indicator {
+      position: absolute;
+      bottom: -2px;
+      right: -2px;
+      width: 9px;
+      height: 9px;
+      border-radius: 50%;
+      background: var(--status-offline);
+      border: 2px solid var(--bg-sidebar);
+    }
+
+    .presence-indicator.online { background: var(--status-online); }
+
+    .sidebar-footer {
+      padding: 12px 16px;
+      border-top: 1px solid var(--border-divider);
+    }
+
+    .nav-link {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 6px 8px;
+      color: var(--text-channel);
+      text-decoration: none;
+      font-size: 15px;
+      border-radius: 6px;
+      transition: background var(--transition-fast);
+    }
+
+    .nav-link:hover { background: var(--bg-channel-hover); }
+    .nav-link svg { width: 18px; height: 18px; opacity: 0.7; }
+
+    /* Main Panel */
+    .main-panel {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      min-width: 0;
+      background: var(--bg-main);
+    }
+
+    .channel-header {
+      height: var(--header-height);
+      padding: 0 20px;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      border-bottom: 1px solid var(--border-divider);
+      flex-shrink: 0;
+    }
+
+    .channel-header-name {
+      display: flex;
+      align-items: center;
+      gap: 4px;
+      font-size: 18px;
+      font-weight: 700;
+      color: var(--text-primary);
+    }
+
+    .channel-header-name .prefix { color: var(--text-muted); font-weight: 400; }
+
+    .channel-stats {
+      display: flex;
+      gap: 12px;
+      font-size: 13px;
+      color: var(--text-muted);
+    }
+
+    .stat-badge {
+      display: flex;
+      align-items: center;
+      gap: 4px;
+    }
+
+    .stat-badge .value {
+      font-weight: 600;
+      color: var(--text-secondary);
+      font-family: var(--font-mono);
+    }
+
+    /* Messages Area - Dashboard Style */
+    .messages-area {
+      flex: 1;
+      overflow-y: auto;
+      padding: 20px;
+    }
+
+    .messages-list { display: flex; flex-direction: column; gap: 1px; }
+
+    .message {
+      display: flex;
+      gap: 12px;
+      padding: 8px 20px;
+      transition: background var(--transition-fast);
+    }
+
+    .message:hover { background: var(--bg-message-hover); }
+
+    .message-avatar {
+      width: 36px;
+      height: 36px;
+      border-radius: 4px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 14px;
+      font-weight: 600;
+      color: white;
+      flex-shrink: 0;
+    }
+
+    .message-content { flex: 1; min-width: 0; }
+
+    .message-header {
+      display: flex;
+      align-items: baseline;
+      gap: 8px;
+      margin-bottom: 4px;
+    }
+
+    .message-sender { font-weight: 700; color: var(--text-primary); }
+    .message-recipient { font-size: 13px; color: var(--text-muted); }
+    .message-recipient .target { color: var(--text-secondary); }
+    .message-timestamp { font-size: 12px; color: var(--text-muted); margin-left: auto; }
+
+    .message-body {
+      font-size: 15px;
+      color: var(--text-primary);
+      line-height: 1.46668;
+      word-wrap: break-word;
+      white-space: pre-wrap;
+    }
+
+    .project-badge {
+      display: inline-block;
+      padding: 1px 5px;
+      background: var(--accent-purple);
+      color: white;
+      font-size: 11px;
+      border-radius: 3px;
+      margin-right: 4px;
+      font-weight: 500;
+    }
+
+    /* Overview Cards (for All Projects view) */
+    .cards-container { flex: 1; overflow-y: auto; padding: 20px; }
+
+    .cards-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(340px, 1fr));
+      gap: 16px;
+    }
+
+    .project-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border-divider);
+      border-radius: 8px;
+      padding: 16px;
+      cursor: pointer;
+      transition: all var(--transition-normal);
+    }
+
+    .project-card:hover { background: var(--bg-card-hover); border-color: var(--border-subtle); }
+    .project-card.offline { opacity: 0.6; }
+
+    .card-header {
+      display: flex;
+      align-items: flex-start;
+      justify-content: space-between;
+      margin-bottom: 12px;
+    }
+
+    .card-title-group { display: flex; align-items: center; gap: 10px; }
+
+    .card-icon {
+      width: 36px;
+      height: 36px;
+      background: var(--accent-primary);
+      border-radius: 8px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: white;
+    }
+
+    .card-icon svg { width: 18px; height: 18px; }
+    .card-title { font-size: 16px; font-weight: 600; color: var(--text-primary); }
+    .card-path { font-size: 12px; font-family: var(--font-mono); color: var(--text-muted); margin-top: 2px; }
+
+    .card-status {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 8px;
+      border-radius: 12px;
+      font-size: 12px;
+      font-weight: 500;
+    }
+
+    .card-status.online { background: rgba(43, 172, 118, 0.15); color: var(--status-online); }
+    .card-status.offline { background: rgba(97, 96, 97, 0.15); color: var(--status-offline); }
+    .card-status.reconnecting { background: rgba(232, 164, 39, 0.15); color: var(--status-away); }
+    .card-status .dot { width: 6px; height: 6px; background: currentColor; border-radius: 50%; }
+
+    .agents-section { margin-top: 12px; padding-top: 12px; border-top: 1px solid var(--border-divider); }
+
+    .agents-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; }
+    .agents-label { font-size: 12px; font-weight: 600; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.5px; }
+    .agents-count { font-size: 12px; font-family: var(--font-mono); color: var(--text-muted); }
+
+    .card-agents-list { display: flex; flex-direction: column; gap: 6px; }
+
+    .card-agent-item {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 6px 8px;
+      background: rgba(255, 255, 255, 0.03);
+      border-radius: 6px;
+    }
+
+    .card-agent-dot { width: 8px; height: 8px; background: var(--status-online); border-radius: 50%; }
+    .card-agent-name { font-size: 14px; font-weight: 500; color: var(--text-primary); }
+    .card-agent-cli { margin-left: auto; font-size: 12px; font-family: var(--font-mono); color: var(--text-muted); }
+
+    .no-agents {
+      padding: 12px;
+      text-align: center;
+      font-size: 13px;
+      color: var(--text-muted);
+      background: rgba(255, 255, 255, 0.02);
+      border-radius: 6px;
+    }
+
+    /* Empty State */
+    .empty-state {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      height: 100%;
+      padding: 48px;
+      text-align: center;
+    }
+
+    .empty-state-icon {
+      width: 64px;
+      height: 64px;
+      margin-bottom: 16px;
+      color: var(--text-muted);
+    }
+
+    .empty-state-title { font-size: 18px; font-weight: 600; color: var(--text-primary); margin-bottom: 8px; }
+    .empty-state-text { font-size: 14px; color: var(--text-muted); max-width: 300px; }
+
+    /* Composer */
+    .message-composer {
+      padding: 16px 20px;
+      border-top: 1px solid var(--border-divider);
+      background: var(--bg-main);
+    }
+
+    .composer-container {
+      background: var(--bg-input);
+      border: 1px solid var(--border-subtle);
+      border-radius: 8px;
+      padding: 12px;
+    }
+
+    .composer-input {
+      width: 100%;
+      background: transparent;
+      border: none;
+      color: var(--text-primary);
+      font-family: var(--font-family);
+      font-size: 15px;
+      resize: none;
+      outline: none;
+      min-height: 24px;
+      max-height: 200px;
+    }
+
+    .composer-input::placeholder { color: var(--text-muted); }
+
+    .composer-row {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      margin-bottom: 8px;
+    }
+
+    .composer-select {
+      padding: 6px 10px;
+      font-size: 13px;
+      font-family: var(--font-family);
+      color: var(--text-primary);
+      background: var(--bg-main);
+      border: 1px solid var(--border-subtle);
+      border-radius: 4px;
+      cursor: pointer;
+    }
+
+    .composer-select:hover { border-color: var(--accent-primary); }
+    .composer-select:focus { outline: none; border-color: var(--accent-primary); }
+    .composer-select:disabled { opacity: 0.5; cursor: not-allowed; }
+
+    .composer-actions {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-top: 8px;
+    }
+
+    .composer-status { font-size: 12px; color: var(--text-muted); }
+    .composer-status.success { color: var(--status-online); }
+    .composer-status.error { color: var(--accent-red); }
+
+    .composer-send {
+      padding: 6px 16px;
+      background: var(--accent-green);
+      color: white;
+      border: none;
+      border-radius: 4px;
+      font-size: 13px;
+      font-weight: 600;
+      cursor: pointer;
+      transition: background var(--transition-fast);
+    }
+
+    .composer-send:hover:not(:disabled) { background: #249966; }
+    .composer-send:disabled { opacity: 0.5; cursor: not-allowed; }
+
+    /* Spawn Modal */
+    .spawn-modal-overlay {
+      position: fixed;
+      inset: 0;
+      background: rgba(0, 0, 0, 0.6);
+      display: none;
+      align-items: center;
+      justify-content: center;
+      z-index: 1000;
+    }
+
+    .spawn-modal-overlay.visible { display: flex; }
+
+    .spawn-modal {
+      width: 480px;
+      max-width: 90vw;
+      background: var(--bg-modal);
+      border-radius: 12px;
+      box-shadow: var(--shadow-modal);
+      overflow: hidden;
+      animation: modalSlideIn 0.2s ease-out;
+    }
+
+    @keyframes modalSlideIn {
+      from { opacity: 0; transform: translateY(-20px) scale(0.95); }
+      to { opacity: 1; transform: translateY(0) scale(1); }
+    }
+
+    .spawn-modal-header {
+      padding: 16px 20px;
+      border-bottom: 1px solid var(--border-divider);
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+    }
+
+    .spawn-modal-title {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      font-size: 18px;
+      font-weight: 600;
+      color: var(--text-primary);
+    }
+
+    .spawn-modal-title svg { color: var(--accent-green); }
+
+    .spawn-modal-close {
+      width: 32px;
+      height: 32px;
+      border: none;
+      background: transparent;
+      color: var(--text-muted);
+      border-radius: 6px;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: all var(--transition-fast);
+    }
+
+    .spawn-modal-close:hover { background: rgba(255, 255, 255, 0.1); color: var(--text-primary); }
+
+    .spawn-modal-body { padding: 20px; }
+
+    .spawn-form-group { margin-bottom: 16px; }
+    .spawn-form-group:last-child { margin-bottom: 0; }
+    .spawn-form-group label { display: block; font-size: 13px; font-weight: 600; color: var(--text-secondary); margin-bottom: 6px; }
+
+    .spawn-input, .spawn-textarea, .spawn-select {
+      width: 100%;
+      padding: 10px 12px;
+      background: var(--bg-input);
+      border: 1px solid var(--border-subtle);
+      border-radius: 6px;
+      color: var(--text-primary);
+      font-family: var(--font-family);
+      font-size: 14px;
+      transition: border-color var(--transition-fast);
+    }
+
+    .spawn-input:focus, .spawn-textarea:focus, .spawn-select:focus { outline: none; border-color: var(--accent-primary); }
+    .spawn-input::placeholder, .spawn-textarea::placeholder { color: var(--text-muted); }
+    .spawn-textarea { resize: vertical; min-height: 80px; line-height: 1.4; }
+    .spawn-hint { display: block; font-size: 12px; color: var(--text-muted); margin-top: 4px; }
+    .spawn-status { min-height: 20px; font-size: 13px; margin-top: 12px; }
+    .spawn-status.success { color: var(--accent-green); }
+    .spawn-status.error { color: var(--accent-red); }
+    .spawn-status.loading { color: var(--text-muted); }
+
+    .spawn-modal-footer {
+      padding: 16px 20px;
+      border-top: 1px solid var(--border-divider);
+      display: flex;
+      justify-content: flex-end;
+      gap: 10px;
+    }
+
+    .spawn-cancel-btn {
+      padding: 8px 16px;
+      background: transparent;
+      border: 1px solid var(--border-subtle);
+      border-radius: 6px;
+      color: var(--text-secondary);
+      font-size: 14px;
+      font-weight: 500;
+      cursor: pointer;
+      transition: all var(--transition-fast);
+    }
+
+    .spawn-cancel-btn:hover { background: rgba(255, 255, 255, 0.05); color: var(--text-primary); }
+
+    .spawn-submit-btn {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      padding: 8px 16px;
+      background: var(--accent-green);
+      border: none;
+      border-radius: 6px;
+      color: white;
+      font-size: 14px;
+      font-weight: 600;
+      cursor: pointer;
+      transition: all var(--transition-fast);
+    }
+
+    .spawn-submit-btn:hover:not(:disabled) { background: #249966; }
+    .spawn-submit-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+
+    /* Scrollbars */
+    ::-webkit-scrollbar { width: 8px; }
+    ::-webkit-scrollbar-track { background: transparent; }
+    ::-webkit-scrollbar-thumb { background: rgba(255, 255, 255, 0.1); border-radius: 4px; }
+    ::-webkit-scrollbar-thumb:hover { background: rgba(255, 255, 255, 0.2); }
+  </style>
+</head>
+<body>
+  <div class="app-container">
+    <!-- Sidebar -->
+    <aside class="sidebar">
+      <div class="workspace-header">
+        <div class="workspace-name">
+          <span class="status-dot" id="status-dot"></span>
+          Bridge
+        </div>
+      </div>
+
+      <div class="sidebar-content">
+        <!-- Projects Section -->
+        <div class="section">
+          <div class="section-header">
+            <div class="section-title">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M6 9l6 6 6-6"/>
+              </svg>
+              Projects
+            </div>
+          </div>
+          <ul class="channel-list" id="projects-list">
+            <li class="channel-item active" data-project="all">
+              <span class="project-status-dot" style="background: var(--accent-purple);"></span>
+              <span class="channel-name">All Projects</span>
+            </li>
+            <!-- Projects injected here -->
+          </ul>
+        </div>
+
+        <!-- Agents Section (shown when project selected) -->
+        <div class="section" id="agents-section" style="display: none;">
+          <div class="section-header">
+            <div class="section-title">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M6 9l6 6 6-6"/>
+              </svg>
+              Agents
+            </div>
+            <button class="section-add-btn" id="spawn-btn" title="Spawn new agent">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <line x1="12" y1="5" x2="12" y2="19"/>
+                <line x1="5" y1="12" x2="19" y2="12"/>
+              </svg>
+            </button>
+          </div>
+          <ul class="channel-list" id="agents-list">
+            <!-- Agents injected here -->
+          </ul>
+        </div>
+      </div>
+
+      <div class="sidebar-footer">
+        <a href="/" class="nav-link">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>
+            <polyline points="9 22 9 12 15 12 15 22"/>
+          </svg>
+          Local Dashboard
+        </a>
+      </div>
+    </aside>
+
+    <!-- Main Panel -->
+    <main class="main-panel">
+      <header class="channel-header">
+        <div class="channel-header-name">
+          <span class="prefix" id="header-prefix">#</span>
+          <span id="header-name">All Projects</span>
+        </div>
+        <div class="channel-stats">
+          <div class="stat-badge">
+            <span class="value" id="stat-projects">0</span>
+            <span>projects</span>
+          </div>
+          <div class="stat-badge">
+            <span class="value" id="stat-agents">0</span>
+            <span>agents</span>
+          </div>
+        </div>
+      </header>
+
+      <!-- Cards View (for All Projects) -->
+      <div class="cards-container" id="cards-view">
+        <div class="cards-grid" id="cards-grid">
+          <div class="empty-state" id="empty-state">
+            <svg class="empty-state-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+              <path d="M9 3H5a2 2 0 0 0-2 2v4m6-6h10a2 2 0 0 1 2 2v4M9 3v18m0 0h10a2 2 0 0 0 2-2v-4M9 21H5a2 2 0 0 1-2-2v-4m0-6v6"/>
+            </svg>
+            <div class="empty-state-title">No Projects Connected</div>
+            <div class="empty-state-text">Start the bridge to orchestrate multiple projects</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Messages View (for individual project) -->
+      <div class="messages-area" id="messages-view" style="display: none;">
+        <div class="messages-list" id="messages-list">
+          <div class="empty-state">
+            <svg class="empty-state-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+              <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+            </svg>
+            <div class="empty-state-title">No messages yet</div>
+            <div class="empty-state-text">Messages in this project will appear here</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Message Composer (for individual project) -->
+      <div class="message-composer" id="composer" style="display: none;">
+        <div class="composer-container">
+          <div class="composer-row">
+            <span style="font-size: 13px; color: var(--text-muted);">To:</span>
+            <select class="composer-select" id="composer-agent">
+              <option value="">Select agent...</option>
+              <option value="*">* (Broadcast)</option>
+            </select>
+          </div>
+          <textarea class="composer-input" id="composer-message" placeholder="Type a message..." rows="1"></textarea>
+          <div class="composer-actions">
+            <span class="composer-status" id="composer-status"></span>
+            <button class="composer-send" id="composer-send" disabled>Send</button>
+          </div>
+        </div>
+      </div>
+    </main>
+  </div>
+
+  <!-- Spawn Agent Modal -->
+  <div class="spawn-modal-overlay" id="spawn-modal-overlay">
+    <div class="spawn-modal">
+      <div class="spawn-modal-header">
+        <div class="spawn-modal-title">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2"/>
+            <circle cx="12" cy="7" r="4"/>
+            <line x1="12" y1="11" x2="12" y2="17"/>
+            <line x1="9" y1="14" x2="15" y2="14"/>
+          </svg>
+          Spawn New Agent
+        </div>
+        <button class="spawn-modal-close" id="spawn-modal-close">
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <line x1="18" y1="6" x2="6" y2="18"/>
+            <line x1="6" y1="6" x2="18" y2="18"/>
+          </svg>
+        </button>
+      </div>
+      <div class="spawn-modal-body">
+        <div class="spawn-form-group">
+          <label>Project</label>
+          <select class="spawn-select" id="spawn-project">
+            <option value="">Select project...</option>
+          </select>
+        </div>
+        <div class="spawn-form-group">
+          <label>Agent Name</label>
+          <input type="text" class="spawn-input" id="spawn-name" placeholder="e.g., Developer, Reviewer" autocomplete="off"/>
+        </div>
+        <div class="spawn-form-group">
+          <label>CLI Command</label>
+          <input type="text" class="spawn-input" id="spawn-cli" value="claude" placeholder="e.g., claude, aider"/>
+          <span class="spawn-hint">The AI CLI tool to wrap</span>
+        </div>
+        <div class="spawn-form-group">
+          <label>Initial Task (optional)</label>
+          <textarea class="spawn-textarea" id="spawn-task" placeholder="Enter an initial task..." rows="3"></textarea>
+        </div>
+        <div class="spawn-status" id="spawn-status"></div>
+      </div>
+      <div class="spawn-modal-footer">
+        <button class="spawn-cancel-btn" id="spawn-cancel">Cancel</button>
+        <button class="spawn-submit-btn" id="spawn-submit">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <polygon points="5 3 19 12 5 21 5 3"/>
+          </svg>
+          Spawn Agent
+        </button>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    // State
+    let currentData = { projects: [], messages: [] };
+    let selectedProjectId = null;
+
+    // Elements
+    const statusDot = document.getElementById('status-dot');
+    const projectsList = document.getElementById('projects-list');
+    const agentsSection = document.getElementById('agents-section');
+    const agentsList = document.getElementById('agents-list');
+    const cardsView = document.getElementById('cards-view');
+    const cardsGrid = document.getElementById('cards-grid');
+    const messagesView = document.getElementById('messages-view');
+    const messagesList = document.getElementById('messages-list');
+    const composer = document.getElementById('composer');
+    const headerPrefix = document.getElementById('header-prefix');
+    const headerName = document.getElementById('header-name');
+
+    // Composer elements
+    const composerAgent = document.getElementById('composer-agent');
+    const composerMessage = document.getElementById('composer-message');
+    const composerSend = document.getElementById('composer-send');
+    const composerStatus = document.getElementById('composer-status');
+
+    // Spawn modal elements
+    const spawnModalOverlay = document.getElementById('spawn-modal-overlay');
+    const spawnBtn = document.getElementById('spawn-btn');
+    const spawnModalClose = document.getElementById('spawn-modal-close');
+    const spawnCancel = document.getElementById('spawn-cancel');
+    const spawnSubmit = document.getElementById('spawn-submit');
+    const spawnProject = document.getElementById('spawn-project');
+    const spawnName = document.getElementById('spawn-name');
+    const spawnCli = document.getElementById('spawn-cli');
+    const spawnTask = document.getElementById('spawn-task');
+    const spawnStatus = document.getElementById('spawn-status');
+
+    // Helpers
+    function escapeHtml(text) {
+      if (!text) return '';
+      const div = document.createElement('div');
+      div.textContent = text;
+      return div.innerHTML;
+    }
+
+    function formatTime(ts) {
+      if (!ts) return '';
+      return new Date(ts).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+    }
+
+    function getAvatarColor(name) {
+      const colors = ['#e01e5a', '#36c5f0', '#2eb67d', '#ecb22e', '#7c3aed', '#1264a3'];
+      let hash = 0;
+      for (let i = 0; i < name.length; i++) hash = name.charCodeAt(i) + ((hash << 5) - hash);
+      return colors[Math.abs(hash) % colors.length];
+    }
+
+    function getInitials(name) {
+      return name.split(/[\s_-]+/).map(w => w[0]).join('').substring(0, 2).toUpperCase();
+    }
+
+    // Select project
+    function selectProject(projectId) {
+      selectedProjectId = projectId;
+
+      // Update sidebar active state
+      projectsList.querySelectorAll('.channel-item').forEach(item => {
+        item.classList.toggle('active', item.dataset.project === projectId);
+      });
+
+      if (projectId === 'all' || !projectId) {
+        // Show all projects view
+        headerPrefix.textContent = '#';
+        headerName.textContent = 'All Projects';
+        cardsView.style.display = 'block';
+        messagesView.style.display = 'none';
+        composer.style.display = 'none';
+        agentsSection.style.display = 'none';
+        renderProjectCards(currentData.projects);
+      } else {
+        // Show project detail view
+        const project = (currentData.projects || []).find(p => p.id === projectId);
+        if (project) {
+          headerPrefix.textContent = '@';
+          headerName.textContent = project.name || project.id;
+          cardsView.style.display = 'none';
+          messagesView.style.display = 'block';
+          composer.style.display = 'block';
+          agentsSection.style.display = 'block';
+          renderAgentsList(project.agents || []);
+          renderProjectMessages(projectId);
+          updateComposerAgents(project.agents || []);
+        }
+      }
+    }
+
+    // Render sidebar projects
+    function renderSidebarProjects(projects) {
+      const allItem = '<li class="channel-item ' + (selectedProjectId === 'all' ? 'active' : '') + '" data-project="all"><span class="project-status-dot" style="background: var(--accent-purple);"></span><span class="channel-name">All Projects</span></li>';
+
+      const projectItems = (projects || []).map(p => {
+        const statusClass = p.connected ? 'connected' : (p.reconnecting ? 'reconnecting' : '');
+        const activeClass = selectedProjectId === p.id ? 'active' : '';
+        return `
+          <li class="channel-item ${statusClass} ${activeClass}" data-project="${escapeHtml(p.id)}">
+            <span class="project-status-dot"></span>
+            <span class="channel-name">${escapeHtml(p.name || p.id)}</span>
+          </li>
+        `;
+      }).join('');
+
+      projectsList.innerHTML = allItem + projectItems;
+
+      // Update stats
+      document.getElementById('stat-projects').textContent = projects?.length || 0;
+      let totalAgents = 0;
+      (projects || []).forEach(p => totalAgents += (p.agents || []).length);
+      document.getElementById('stat-agents').textContent = totalAgents;
+    }
+
+    // Render agents list for selected project
+    function renderAgentsList(agents) {
+      if (!agents || agents.length === 0) {
+        agentsList.innerHTML = '<li class="channel-item" style="color: var(--text-muted); cursor: default;">No agents</li>';
+        return;
+      }
+
+      agentsList.innerHTML = agents.map(a => `
+        <li class="channel-item" data-agent="${escapeHtml(a.name)}">
+          <div class="agent-avatar" style="background: ${getAvatarColor(a.name)}">
+            ${getInitials(a.name)}
+            <span class="presence-indicator online"></span>
+          </div>
+          <span class="channel-name">${escapeHtml(a.name)}</span>
+        </li>
+      `).join('');
+    }
+
+    // Render project cards
+    function renderProjectCards(projects) {
+      if (!projects || projects.length === 0) {
+        cardsGrid.innerHTML = document.getElementById('empty-state').outerHTML;
+        return;
+      }
+
+      cardsGrid.innerHTML = projects.map(p => {
+        const agents = p.agents || [];
+        const agentsHtml = agents.length > 0
+          ? agents.map(a => `
+              <div class="card-agent-item">
+                <span class="card-agent-dot"></span>
+                <span class="card-agent-name">${escapeHtml(a.name)}</span>
+                <span class="card-agent-cli">${escapeHtml(a.cli || '')}</span>
+              </div>
+            `).join('')
+          : '<div class="no-agents">No agents connected</div>';
+
+        return `
+          <div class="project-card ${p.connected ? '' : 'offline'}" data-project-id="${escapeHtml(p.id)}">
+            <div class="card-header">
+              <div class="card-title-group">
+                <div class="card-icon">
+                  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                    <path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"/>
+                  </svg>
+                </div>
+                <div>
+                  <div class="card-title">${escapeHtml(p.name || p.id)}</div>
+                  <div class="card-path">${escapeHtml(p.path || '')}</div>
+                </div>
+              </div>
+              <div class="card-status ${p.connected ? 'online' : p.reconnecting ? 'reconnecting' : 'offline'}">
+                <span class="dot"></span>
+                <span>${p.connected ? 'Online' : p.reconnecting ? 'Reconnecting...' : 'Offline'}</span>
+              </div>
+            </div>
+            <div class="agents-section">
+              <div class="agents-header">
+                <span class="agents-label">Agents</span>
+                <span class="agents-count">${agents.length} active</span>
+              </div>
+              <div class="card-agents-list">${agentsHtml}</div>
+            </div>
+          </div>
+        `;
+      }).join('');
+    }
+
+    // Render messages for a project
+    function renderProjectMessages(projectId) {
+      // Filter messages for this project
+      const messages = (currentData.messages || []).filter(m =>
+        m.sourceProject === projectId || m.targetProject === projectId || !m.sourceProject
+      );
+
+      if (messages.length === 0) {
+        messagesList.innerHTML = `
+          <div class="empty-state">
+            <svg class="empty-state-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+              <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+            </svg>
+            <div class="empty-state-title">No messages yet</div>
+            <div class="empty-state-text">Messages in this project will appear here</div>
+          </div>
+        `;
+        return;
+      }
+
+      messagesList.innerHTML = messages.slice(-50).map(m => {
+        const isBroadcast = m.to === '*';
+        const recipientDisplay = isBroadcast ? '@everyone' : `@${escapeHtml(m.to || '')}`;
+        const projectBadge = m.sourceProject && m.sourceProject !== projectId
+          ? `<span class="project-badge">${escapeHtml(m.sourceProject)}</span>`
+          : '';
+
+        return `
+          <div class="message">
+            <div class="message-avatar" style="background: ${getAvatarColor(m.from || 'Unknown')}">
+              ${getInitials(m.from || '?')}
+            </div>
+            <div class="message-content">
+              <div class="message-header">
+                <span class="message-sender">${projectBadge}@${escapeHtml(m.from || 'Unknown')}</span>
+                <span class="message-recipient">→ <span class="target">${recipientDisplay}</span></span>
+                <span class="message-timestamp">${formatTime(m.timestamp)}</span>
+              </div>
+              <div class="message-body">${escapeHtml(m.body || '')}</div>
+            </div>
+          </div>
+        `;
+      }).join('');
+
+      // Scroll to bottom
+      messagesView.scrollTop = messagesView.scrollHeight;
+    }
+
+    // Update composer agents dropdown
+    function updateComposerAgents(agents) {
+      composerAgent.innerHTML = '<option value="">Select agent...</option><option value="*">* (Broadcast)</option>' +
+        (agents || []).map(a => `<option value="${escapeHtml(a.name)}">${escapeHtml(a.name)}</option>`).join('');
+    }
+
+    // Send message
+    async function sendMessage() {
+      if (!selectedProjectId || selectedProjectId === 'all') return;
+
+      const to = composerAgent.value;
+      const message = composerMessage.value.trim();
+      if (!to || !message) return;
+
+      composerSend.disabled = true;
+      composerStatus.textContent = 'Sending...';
+      composerStatus.className = 'composer-status';
+
+      try {
+        const response = await fetch('/api/bridge/send', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ projectId: selectedProjectId, to, message })
+        });
+
+        const result = await response.json();
+        if (response.ok && result.success) {
+          composerMessage.value = '';
+          composerStatus.textContent = 'Sent!';
+          composerStatus.className = 'composer-status success';
+          setTimeout(() => { composerStatus.textContent = ''; }, 2000);
+        } else {
+          throw new Error(result.error || 'Failed');
+        }
+      } catch (err) {
+        composerStatus.textContent = err.message;
+        composerStatus.className = 'composer-status error';
+      }
+
+      composerSend.disabled = false;
+    }
+
+    // Spawn modal
+    function openSpawnModal() {
+      // Populate project dropdown
+      const connectedProjects = (currentData.projects || []).filter(p => p.connected);
+      spawnProject.innerHTML = '<option value="">Select project...</option>' +
+        connectedProjects.map(p => `<option value="${escapeHtml(p.id)}">${escapeHtml(p.name || p.id)}</option>`).join('');
+
+      // Pre-select current project if viewing one
+      if (selectedProjectId && selectedProjectId !== 'all') {
+        spawnProject.value = selectedProjectId;
+      }
+
+      spawnName.value = '';
+      spawnCli.value = 'claude';
+      spawnTask.value = '';
+      spawnStatus.textContent = '';
+      spawnModalOverlay.classList.add('visible');
+      spawnName.focus();
+    }
+
+    function closeSpawnModal() {
+      spawnModalOverlay.classList.remove('visible');
+    }
+
+    async function submitSpawn() {
+      const projectId = spawnProject.value;
+      const name = spawnName.value.trim();
+      const cli = spawnCli.value.trim() || 'claude';
+      const task = spawnTask.value.trim();
+
+      if (!projectId) {
+        spawnStatus.textContent = 'Please select a project';
+        spawnStatus.className = 'spawn-status error';
+        return;
+      }
+      if (!name) {
+        spawnStatus.textContent = 'Agent name is required';
+        spawnStatus.className = 'spawn-status error';
+        return;
+      }
+
+      spawnSubmit.disabled = true;
+      spawnStatus.textContent = 'Spawning...';
+      spawnStatus.className = 'spawn-status loading';
+
+      try {
+        // Note: This calls the local dashboard's spawn API
+        // For bridge-level spawning, we'd need project-specific spawn endpoints
+        const response = await fetch('/api/spawn', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name, cli, task })
+        });
+
+        const result = await response.json();
+        if (response.ok && result.success) {
+          spawnStatus.textContent = `Agent "${name}" spawned!`;
+          spawnStatus.className = 'spawn-status success';
+          setTimeout(closeSpawnModal, 1000);
+        } else {
+          throw new Error(result.error || 'Failed to spawn');
+        }
+      } catch (err) {
+        spawnStatus.textContent = err.message;
+        spawnStatus.className = 'spawn-status error';
+      }
+
+      spawnSubmit.disabled = false;
+    }
+
+    // Event listeners
+    projectsList.addEventListener('click', (e) => {
+      const item = e.target.closest('.channel-item');
+      if (item) selectProject(item.dataset.project);
+    });
+
+    cardsGrid.addEventListener('click', (e) => {
+      const card = e.target.closest('.project-card');
+      if (card) selectProject(card.dataset.projectId);
+    });
+
+    composerAgent.addEventListener('change', () => {
+      composerSend.disabled = !composerAgent.value || !composerMessage.value.trim();
+    });
+
+    composerMessage.addEventListener('input', () => {
+      composerSend.disabled = !composerAgent.value || !composerMessage.value.trim();
+    });
+
+    composerMessage.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && !e.shiftKey && !composerSend.disabled) {
+        e.preventDefault();
+        sendMessage();
+      }
+    });
+
+    composerSend.addEventListener('click', sendMessage);
+
+    spawnBtn.addEventListener('click', openSpawnModal);
+    spawnModalClose.addEventListener('click', closeSpawnModal);
+    spawnCancel.addEventListener('click', closeSpawnModal);
+    spawnSubmit.addEventListener('click', submitSpawn);
+    spawnModalOverlay.addEventListener('click', (e) => {
+      if (e.target === spawnModalOverlay) closeSpawnModal();
+    });
+
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape' && spawnModalOverlay.classList.contains('visible')) {
+        closeSpawnModal();
+      }
+    });
+
+    // Main render
+    function render(data) {
+      currentData = data;
+      renderSidebarProjects(data.projects);
+
+      if (selectedProjectId === 'all' || !selectedProjectId) {
+        renderProjectCards(data.projects);
+      } else {
+        const project = (data.projects || []).find(p => p.id === selectedProjectId);
+        if (project) {
+          renderAgentsList(project.agents || []);
+          renderProjectMessages(selectedProjectId);
+          updateComposerAgents(project.agents || []);
+        }
+      }
+    }
+
+    // WebSocket connection
+    function connect() {
+      const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const ws = new WebSocket(`${protocol}//${window.location.host}/ws/bridge`);
+
+      ws.onopen = () => statusDot.classList.remove('offline');
+      ws.onclose = () => { statusDot.classList.add('offline'); setTimeout(connect, 3000); };
+      ws.onerror = () => statusDot.classList.add('offline');
+
+      ws.onmessage = (e) => {
+        try {
+          const data = JSON.parse(e.data);
+          render(data);
+        } catch (err) {
+          console.error('Parse error:', err);
+        }
+      };
+    }
+
+    // Initialize
+    selectProject('all');
+    connect();
+  </script>
+</body>
+</html>
diff --git a/src/dashboard/public/index.html b/src/dashboard/public/index.html
index 76ea7bcb3..224ccacdf 100644
--- a/src/dashboard/public/index.html
+++ b/src/dashboard/public/index.html
@@ -1,515 +1,2008 @@
 <!DOCTYPE html>
-<html>
+<html lang="en">
 <head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Agent Relay</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
   <style>
+    /* ========================================
+       Design Tokens
+       ======================================== */
     :root {
-        --bg-primary: #09090b;
-        --bg-secondary: #18181b;
-        --bg-card: #18181b;
-        --bg-elevated: #27272a;
-        --border-color: #27272a;
-        --border-hover: #3f3f46;
-        --primary: #3b82f6;
-        --primary-muted: rgba(59, 130, 246, 0.15);
-        --text: #fafafa;
-        --text-secondary: #a1a1aa;
-        --text-muted: #71717a;
-        --success: #22c55e;
-        --success-muted: rgba(34, 197, 94, 0.15);
-        --error: #ef4444;
-        --error-muted: rgba(239, 68, 68, 0.15);
-        --warning: #f59e0b;
-        --warning-muted: rgba(245, 158, 11, 0.15);
-    }
-
-    * { box-sizing: border-box; margin: 0; padding: 0; }
+      /* Background colors */
+      --bg-workspace: #1a1d21;
+      --bg-sidebar: #19171d;
+      --bg-channel-active: #1164a3;
+      --bg-channel-hover: rgba(255, 255, 255, 0.04);
+      --bg-main: #222529;
+      --bg-message-hover: rgba(255, 255, 255, 0.03);
+      --bg-composer: #222529;
+      --bg-input: #222529;
+      --bg-modal: #1a1d21;
+      --bg-tooltip: #1d1c21;
+
+      /* Text colors */
+      --text-primary: #d1d2d3;
+      --text-secondary: #ababad;
+      --text-muted: #8d8d8e;
+      --text-channel: #bcabbc;
+      --text-channel-active: #ffffff;
+      --text-link: #1d9bd1;
+
+      /* Accent colors */
+      --accent-primary: #1264a3;
+      --accent-green: #2bac76;
+      --accent-yellow: #e8a427;
+      --accent-red: #e01e5a;
+      --accent-purple: #7c3aed;
+
+      /* Status colors */
+      --status-online: #2bac76;
+      --status-away: #e8a427;
+      --status-offline: #616061;
+      --status-busy: #e01e5a;
+
+      /* Border colors */
+      --border-subtle: rgba(255, 255, 255, 0.1);
+      --border-divider: rgba(255, 255, 255, 0.06);
+
+      /* Badge colors */
+      --badge-bg: #e01e5a;
+      --badge-text: #ffffff;
+
+      /* Shadows */
+      --shadow-modal: 0 18px 50px rgba(0, 0, 0, 0.6);
+      --shadow-message: 0 1px 2px rgba(0, 0, 0, 0.1);
+
+      /* Dimensions */
+      --sidebar-width: 260px;
+      --header-height: 49px;
+      --composer-min-height: 44px;
+
+      /* Typography */
+      --font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      --font-mono: 'JetBrains Mono', ui-monospace, monospace;
+
+      /* Transitions */
+      --transition-fast: 0.1s ease;
+      --transition-normal: 0.2s ease;
+    }
+
+    /* ========================================
+       Reset & Base
+       ======================================== */
+    *, *::before, *::after {
+      box-sizing: border-box;
+      margin: 0;
+      padding: 0;
+    }
+
+    html, body {
+      height: 100%;
+      overflow: hidden;
+    }
 
     body {
-      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
-      background: var(--bg-primary);
-      color: var(--text);
-      min-height: 100vh;
-      overflow-x: hidden;
+      font-family: var(--font-family);
+      font-size: 15px;
+      line-height: 1.46668;
+      color: var(--text-primary);
+      background: var(--bg-workspace);
+      -webkit-font-smoothing: antialiased;
+      -moz-osx-font-smoothing: grayscale;
     }
 
-    .container {
-      max-width: 1400px;
-      margin: 0 auto;
-      display: grid;
-      grid-template-columns: 320px 1fr;
-      gap: 1px;
+    /* ========================================
+       Layout Structure
+       ======================================== */
+    .app-container {
+      display: flex;
       height: 100vh;
-      background: var(--border-color);
+      width: 100vw;
     }
 
+    /* Sidebar */
     .sidebar {
+      width: var(--sidebar-width);
+      background: var(--bg-sidebar);
       display: flex;
       flex-direction: column;
-      background: var(--bg-primary);
-      overflow: hidden;
+      flex-shrink: 0;
+      border-right: 1px solid var(--border-divider);
     }
 
-    .main-content {
+    /* Main Content */
+    .main-panel {
+      flex: 1;
       display: flex;
       flex-direction: column;
-      background: var(--bg-primary);
-      overflow: hidden;
+      min-width: 0;
+      background: var(--bg-main);
     }
 
-    .header {
+    /* ========================================
+       Sidebar Components
+       ======================================== */
+
+    /* Workspace Header */
+    .workspace-header {
+      height: var(--header-height);
+      padding: 0 16px;
       display: flex;
-      justify-content: space-between;
       align-items: center;
-      padding: 16px 20px;
-      border-bottom: 1px solid var(--border-color);
+      justify-content: space-between;
+      border-bottom: 1px solid var(--border-divider);
+      flex-shrink: 0;
     }
 
-    .logo {
+    .workspace-name {
+      font-size: 18px;
+      font-weight: 700;
+      color: var(--text-primary);
       display: flex;
       align-items: center;
-      gap: 10px;
+      gap: 6px;
     }
 
-    .logo-icon {
-      width: 32px;
-      height: 32px;
-      background: var(--primary);
-      border-radius: 8px;
+    .workspace-name .status-dot {
+      width: 10px;
+      height: 10px;
+      border-radius: 50%;
+      background: var(--status-online);
+      flex-shrink: 0;
+    }
+
+    .workspace-name .status-dot.offline {
+      background: var(--status-offline);
+    }
+
+    .compose-new-btn {
+      width: 36px;
+      height: 36px;
+      border-radius: 50%;
+      background: rgba(255, 255, 255, 0.1);
+      border: none;
+      color: var(--text-primary);
+      cursor: pointer;
       display: flex;
       align-items: center;
       justify-content: center;
-      color: white;
-      font-weight: 600;
-      font-size: 14px;
+      transition: background var(--transition-fast);
     }
 
-    h1 {
-      font-size: 1rem;
-      font-weight: 600;
-      color: var(--text);
+    .compose-new-btn:hover {
+      background: rgba(255, 255, 255, 0.2);
     }
 
-    h2 {
-      font-size: 0.875rem;
-      font-weight: 500;
-      color: var(--text-secondary);
+    /* Command Palette Trigger */
+    .search-bar {
+      margin: 12px 12px 8px;
+      padding: 6px 12px;
+      background: rgba(255, 255, 255, 0.06);
+      border: 1px solid transparent;
+      border-radius: 6px;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      cursor: pointer;
+      transition: all var(--transition-fast);
+    }
+
+    .search-bar:hover {
+      background: rgba(255, 255, 255, 0.1);
+    }
+
+    .search-bar svg {
+      width: 16px;
+      height: 16px;
+      color: var(--text-muted);
+    }
+
+    .search-bar span {
+      font-size: 13px;
+      color: var(--text-muted);
+      flex: 1;
+    }
+
+    .search-bar kbd {
+      font-family: var(--font-family);
+      font-size: 11px;
+      color: var(--text-muted);
+      background: rgba(255, 255, 255, 0.1);
+      padding: 2px 6px;
+      border-radius: 4px;
     }
 
-    .agents-section {
+    /* Sidebar Sections */
+    .sidebar-content {
       flex: 1;
       overflow-y: auto;
-      padding: 12px;
+      padding: 8px 0;
     }
 
-    .agents-header {
-      padding: 8px 8px 12px;
-      font-size: 0.75rem;
-      font-weight: 500;
+    .section-header {
+      padding: 8px 16px 4px;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      cursor: pointer;
+    }
+
+    .section-title {
+      font-size: 15px;
+      font-weight: 600;
+      color: var(--text-channel);
+      display: flex;
+      align-items: center;
+      gap: 4px;
+    }
+
+    .section-title svg {
+      width: 12px;
+      height: 12px;
+      transition: transform var(--transition-fast);
+    }
+
+    .section-header.collapsed .section-title svg {
+      transform: rotate(-90deg);
+    }
+
+    .section-add-btn {
+      width: 24px;
+      height: 24px;
+      border: none;
+      background: transparent;
       color: var(--text-muted);
-      text-transform: uppercase;
-      letter-spacing: 0.05em;
+      cursor: pointer;
+      border-radius: 4px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      opacity: 0;
+      transition: all var(--transition-fast);
     }
 
-    .agent-card {
-      padding: 12px;
-      border-radius: 8px;
-      margin-bottom: 4px;
-      transition: background 0.15s;
-      cursor: default;
+    .section-header:hover .section-add-btn {
+      opacity: 1;
+    }
+
+    .section-add-btn:hover {
+      background: rgba(255, 255, 255, 0.1);
+      color: var(--text-primary);
     }
 
-    .agent-card:hover {
-      background: var(--bg-secondary);
+    /* Channel/Agent List */
+    .channel-list {
+      list-style: none;
     }
 
-    .agent-card.active {
-      background: var(--bg-elevated);
+    /* Sidebar Footer */
+    .sidebar-footer {
+      padding: 12px 16px;
+      border-top: 1px solid var(--border-divider);
     }
 
-    .agent-header {
+    .nav-link {
       display: flex;
-      justify-content: space-between;
       align-items: center;
-      margin-bottom: 8px;
+      gap: 8px;
+      padding: 8px 12px;
+      color: var(--text-muted);
+      text-decoration: none;
+      font-size: 13px;
+      border-radius: 6px;
+      transition: all var(--transition-fast);
     }
 
-    .agent-name {
-      font-weight: 600;
-      font-size: 0.875rem;
-      color: var(--text);
+    .nav-link:hover {
+      background: var(--bg-channel-hover);
+      color: var(--text-primary);
+    }
+
+    .nav-link svg {
+      width: 16px;
+      height: 16px;
     }
 
-    .agent-meta {
+    .channel-item {
       display: flex;
       align-items: center;
-      gap: 6px;
-      margin-bottom: 10px;
+      padding: 6px 20px 6px 16px;
+      cursor: pointer;
+      transition: background var(--transition-fast);
+      gap: 8px;
+      position: relative;
+    }
+
+    .channel-item:hover {
+      background: var(--bg-channel-hover);
+    }
+
+    .channel-item.active {
+      background: var(--bg-channel-active);
+    }
+
+    .channel-item.active .channel-name,
+    .channel-item.active .channel-prefix {
+      color: var(--text-channel-active);
     }
 
-    .agent-role {
-      font-size: 0.75rem;
+    .channel-prefix {
+      font-size: 15px;
       color: var(--text-muted);
+      width: 18px;
+      text-align: center;
+      flex-shrink: 0;
     }
 
-    .cli-badge {
-      background: var(--bg-elevated);
-      color: var(--text-secondary);
-      padding: 2px 6px;
-      border-radius: 4px;
-      font-size: 0.7rem;
-      font-weight: 500;
+    .channel-name {
+      font-size: 15px;
+      color: var(--text-channel);
+      flex: 1;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .channel-item.unread .channel-name {
+      font-weight: 600;
+      color: var(--text-primary);
     }
 
-    .agent-status {
+    .unread-badge {
+      min-width: 18px;
+      height: 18px;
+      padding: 0 5px;
+      background: var(--badge-bg);
+      color: var(--badge-text);
+      font-size: 12px;
+      font-weight: 600;
+      border-radius: 9px;
       display: flex;
       align-items: center;
-      gap: 6px;
-      font-size: 0.8rem;
-      color: var(--text-secondary);
+      justify-content: center;
     }
 
-    .status-dot {
-      width: 6px;
-      height: 6px;
+    /* Agent item with presence */
+    .agent-avatar {
+      width: 20px;
+      height: 20px;
+      border-radius: 4px;
+      background: var(--accent-purple);
+      color: white;
+      font-size: 10px;
+      font-weight: 600;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      position: relative;
+      flex-shrink: 0;
+    }
+
+    .presence-indicator {
+      position: absolute;
+      bottom: -2px;
+      right: -2px;
+      width: 10px;
+      height: 10px;
       border-radius: 50%;
-      background: var(--success);
+      border: 2px solid var(--bg-sidebar);
+      background: var(--status-offline);
     }
 
-    .badge {
-      background: var(--primary-muted);
-      color: var(--primary);
-      padding: 2px 8px;
-      border-radius: 10px;
-      font-size: 0.7rem;
+    .presence-indicator.online {
+      background: var(--status-online);
+    }
+
+    .presence-indicator.away {
+      background: var(--status-away);
+    }
+
+    .presence-indicator.busy {
+      background: var(--status-busy);
+    }
+
+    /* Needs Attention Indicator */
+    .channel-item.needs-attention {
+      background: rgba(232, 164, 39, 0.1);
+    }
+
+    .channel-item.needs-attention::after {
+      content: '';
+      position: absolute;
+      top: 50%;
+      right: 12px;
+      transform: translateY(-50%);
+      width: 8px;
+      height: 8px;
+      background: var(--accent-yellow);
+      border-radius: 50%;
+      animation: attentionPulse 1.5s ease-in-out infinite;
+    }
+
+    .attention-badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      padding: 2px 6px;
+      margin-left: 8px;
+      background: var(--accent-yellow);
+      color: #1a1d21;
+      font-size: 10px;
       font-weight: 600;
+      border-radius: 4px;
+      text-transform: uppercase;
+      letter-spacing: 0.02em;
+    }
+
+    @keyframes attentionPulse {
+      0%, 100% {
+        opacity: 1;
+        transform: translateY(-50%) scale(1);
+      }
+      50% {
+        opacity: 0.5;
+        transform: translateY(-50%) scale(1.2);
+      }
+    }
+
+    /* ========================================
+       Main Panel Components
+       ======================================== */
+
+    /* Channel Header */
+    .channel-header {
+      height: var(--header-height);
+      padding: 0 20px;
+      display: flex;
+      align-items: center;
+      border-bottom: 1px solid var(--border-divider);
+      flex-shrink: 0;
+      gap: 8px;
     }
 
-    /* Activity Log */
-    .activity-log {
+    .channel-header-name {
+      font-size: 18px;
+      font-weight: 700;
+      color: var(--text-primary);
       display: flex;
-      flex-direction: column;
+      align-items: center;
+      gap: 6px;
+    }
+
+    .channel-header-name .prefix {
+      color: var(--text-muted);
+      font-weight: 500;
+    }
+
+    .header-divider {
+      width: 1px;
+      height: 20px;
+      background: var(--border-subtle);
+      margin: 0 8px;
+    }
+
+    .channel-topic {
+      font-size: 13px;
+      color: var(--text-muted);
       flex: 1;
+      white-space: nowrap;
       overflow: hidden;
+      text-overflow: ellipsis;
     }
 
-    .log-header {
-      padding: 16px 20px;
-      border-bottom: 1px solid var(--border-color);
+    .header-actions {
       display: flex;
-      justify-content: space-between;
       align-items: center;
+      gap: 4px;
     }
 
-    .live-indicator {
+    .header-action-btn {
+      width: 28px;
+      height: 28px;
+      border: none;
+      background: transparent;
+      color: var(--text-muted);
+      border-radius: 4px;
+      cursor: pointer;
       display: flex;
       align-items: center;
-      gap: 6px;
-      font-size: 0.75rem;
+      justify-content: center;
+      transition: all var(--transition-fast);
+    }
+
+    .header-action-btn:hover {
+      background: rgba(255, 255, 255, 0.1);
+      color: var(--text-primary);
+    }
+
+    .online-count {
+      font-size: 13px;
       color: var(--text-muted);
+      display: flex;
+      align-items: center;
+      gap: 4px;
     }
 
-    .live-dot {
-      width: 6px;
-      height: 6px;
+    .online-count .dot {
+      width: 8px;
+      height: 8px;
       border-radius: 50%;
-      background: var(--success);
+      background: var(--status-online);
     }
 
-    .log-content {
+    /* Message List */
+    .messages-container {
+      flex: 1;
       overflow-y: auto;
+      overflow-x: hidden;
+      display: flex;
+      flex-direction: column;
+    }
+
+    .messages-list {
       flex: 1;
+      padding: 16px 0;
+    }
+
+    /* Date Divider */
+    .date-divider {
       display: flex;
-      flex-direction: column-reverse;
+      align-items: center;
+      margin: 16px 20px;
+    }
+
+    .date-divider::before,
+    .date-divider::after {
+      content: '';
+      flex: 1;
+      height: 1px;
+      background: var(--border-divider);
+    }
+
+    .date-divider-text {
+      padding: 4px 16px;
+      font-size: 13px;
+      font-weight: 600;
+      color: var(--text-secondary);
+      background: var(--bg-main);
+      border: 1px solid var(--border-divider);
+      border-radius: 24px;
     }
 
+    /* Message */
     .message {
-      padding: 16px 20px;
-      border-bottom: 1px solid var(--border-color);
+      padding: 8px 20px;
       display: flex;
-      gap: 12px;
-      transition: background 0.15s;
+      gap: 8px;
+      transition: background var(--transition-fast);
+      position: relative;
     }
 
     .message:hover {
-      background: var(--bg-secondary);
+      background: var(--bg-message-hover);
     }
 
-    .message:last-child { border-bottom: none; }
+    .message:hover .message-actions {
+      opacity: 1;
+    }
 
-    .msg-avatar {
+    .message-avatar {
       width: 36px;
       height: 36px;
-      border-radius: 8px;
-      background: var(--bg-elevated);
-      color: var(--text-secondary);
+      border-radius: 4px;
+      flex-shrink: 0;
       display: flex;
       align-items: center;
       justify-content: center;
       font-weight: 600;
-      font-size: 0.8rem;
-      flex-shrink: 0;
+      font-size: 14px;
+      color: white;
     }
 
-    .msg-body { flex: 1; min-width: 0; }
+    .message-content {
+      flex: 1;
+      min-width: 0;
+    }
 
-    .msg-meta {
+    .message-header {
       display: flex;
-      align-items: center;
+      align-items: baseline;
       gap: 8px;
-      margin-bottom: 6px;
+      margin-bottom: 4px;
     }
 
-    .msg-sender {
-      font-weight: 600;
-      font-size: 0.875rem;
-      color: var(--text);
+    .message-sender {
+      font-size: 15px;
+      font-weight: 700;
+      color: var(--text-primary);
     }
 
-    .msg-arrow {
+    .message-recipient {
+      font-size: 13px;
       color: var(--text-muted);
-      font-size: 0.75rem;
     }
 
-    .msg-target {
-      color: var(--primary);
-      font-weight: 500;
-      font-size: 0.875rem;
+    .message-recipient .target {
+      color: var(--text-link);
+    }
+
+    .project-badge {
+      display: inline-block;
+      background: var(--accent-primary);
+      color: white;
+      font-size: 10px;
+      font-weight: 600;
+      padding: 2px 6px;
+      border-radius: 4px;
+      margin-right: 4px;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
     }
 
-    .msg-time {
+    .message-timestamp {
+      font-size: 12px;
       color: var(--text-muted);
-      font-size: 0.75rem;
-      margin-left: auto;
     }
 
-    .msg-text {
-      font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
-      font-size: 0.8rem;
+    .message-body {
+      font-size: 15px;
+      line-height: 1.46668;
+      color: var(--text-primary);
+      word-wrap: break-word;
       white-space: pre-wrap;
-      color: var(--text-secondary);
-      background: var(--bg-secondary);
+    }
+
+    .message-body code {
+      font-family: var(--font-mono);
+      font-size: 13px;
+      background: rgba(255, 255, 255, 0.06);
+      padding: 2px 4px;
+      border-radius: 3px;
+    }
+
+    .message-body pre {
+      font-family: var(--font-mono);
+      font-size: 13px;
+      background: rgba(0, 0, 0, 0.3);
       padding: 12px;
-      border-radius: 6px;
-      line-height: 1.5;
+      border-radius: 4px;
+      margin: 8px 0;
+      overflow-x: auto;
     }
 
-    /* Connection Status */
-    #connection-status {
-      font-size: 0.75rem;
-      font-weight: 500;
-      padding: 4px 10px;
+    /* Broadcast message styling */
+    .message.broadcast {
+      border-left: 3px solid var(--accent-yellow);
+      margin-left: 17px;
+      padding-left: 17px;
+    }
+
+    .message.broadcast .message-recipient .target {
+      color: var(--accent-yellow);
+    }
+
+    /* Message Actions (hover toolbar) */
+    .message-actions {
+      position: absolute;
+      top: -16px;
+      right: 20px;
+      background: var(--bg-tooltip);
+      border: 1px solid var(--border-subtle);
       border-radius: 6px;
-      background: var(--success-muted);
-      color: var(--success);
+      padding: 4px;
       display: flex;
-      align-items: center;
-      gap: 6px;
-      transition: all 0.15s;
+      gap: 2px;
+      opacity: 0;
+      transition: opacity var(--transition-fast);
+      box-shadow: var(--shadow-message);
     }
 
-    #connection-status .dot {
-      width: 6px;
-      height: 6px;
-      border-radius: 50%;
-      background: var(--success);
+    .message-action-btn {
+      width: 28px;
+      height: 28px;
+      border: none;
+      background: transparent;
+      color: var(--text-muted);
+      border-radius: 4px;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: all var(--transition-fast);
     }
 
-    .disconnected {
-      background: var(--error-muted) !important;
-      color: var(--error) !important;
+    .message-action-btn:hover {
+      background: rgba(255, 255, 255, 0.1);
+      color: var(--text-primary);
     }
 
-    .disconnected .dot {
-      background: var(--error) !important;
+    /* Thread Indicator */
+    .thread-indicator {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      margin-top: 6px;
+      padding: 4px 8px;
+      background: rgba(255, 255, 255, 0.04);
+      border-radius: 4px;
+      font-size: 13px;
+      color: var(--text-link);
+      cursor: pointer;
+      transition: background var(--transition-fast);
     }
 
-    .empty-state {
-      text-align: center;
-      padding: 48px 24px;
-      color: var(--text-muted);
+    .thread-indicator:hover {
+      background: rgba(255, 255, 255, 0.08);
     }
 
-    .empty-state-text {
-      font-size: 0.875rem;
-      line-height: 1.6;
+    .thread-indicator svg {
+      width: 14px;
+      height: 14px;
     }
 
-    /* Scrollbar */
-    ::-webkit-scrollbar { width: 6px; }
-    ::-webkit-scrollbar-track { background: transparent; }
-    ::-webkit-scrollbar-thumb {
-      background: var(--border-hover);
-      border-radius: 3px;
+    /* Typing Indicator */
+    .typing-indicator {
+      padding: 8px 20px;
+      font-size: 13px;
+      color: var(--text-muted);
+      display: none;
     }
-    ::-webkit-scrollbar-thumb:hover {
+
+    .typing-indicator.visible {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .typing-dots {
+      display: flex;
+      gap: 3px;
+    }
+
+    .typing-dots span {
+      width: 6px;
+      height: 6px;
       background: var(--text-muted);
+      border-radius: 50%;
+      animation: typingBounce 1.4s infinite;
+    }
+
+    .typing-dots span:nth-child(2) { animation-delay: 0.2s; }
+    .typing-dots span:nth-child(3) { animation-delay: 0.4s; }
+
+    @keyframes typingBounce {
+      0%, 60%, 100% { transform: translateY(0); }
+      30% { transform: translateY(-4px); }
+    }
+
+    /* ========================================
+       Composer
+       ======================================== */
+    .composer {
+      padding: 0 20px 20px;
+      flex-shrink: 0;
+      position: relative;
+      z-index: 10;
+    }
+
+    .composer-container {
+      background: var(--bg-input);
+      border: 1px solid var(--border-subtle);
+      border-radius: 8px;
+      overflow: visible;
+      transition: border-color var(--transition-fast);
+      position: relative;
+    }
+
+    .composer-container:focus-within {
+      border-color: var(--accent-primary);
+    }
+
+    .composer-input-row {
+      display: flex;
+      align-items: flex-end;
+    }
+
+    .composer-toolbar {
+      padding: 8px 12px;
+      display: flex;
+      align-items: center;
+      gap: 4px;
+      border-right: 1px solid var(--border-divider);
+    }
+
+    .toolbar-btn {
+      width: 28px;
+      height: 28px;
+      border: none;
+      background: transparent;
+      color: var(--text-muted);
+      border-radius: 4px;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: all var(--transition-fast);
+    }
+
+    .toolbar-btn:hover {
+      background: rgba(255, 255, 255, 0.1);
+      color: var(--text-primary);
+    }
+
+    .composer-input {
+      flex: 1;
+      padding: 12px;
+      background: transparent;
+      border: none;
+      color: var(--text-primary);
+      font-family: var(--font-family);
+      font-size: 15px;
+      line-height: 1.46668;
+      resize: none;
+      outline: none;
+      min-height: var(--composer-min-height);
+      max-height: 200px;
+    }
+
+    .composer-input::placeholder {
+      color: var(--text-muted);
+    }
+
+    .composer-send {
+      padding: 8px 12px;
+      display: flex;
+      align-items: center;
+    }
+
+    .send-btn {
+      width: 32px;
+      height: 32px;
+      border: none;
+      background: var(--accent-primary);
+      color: white;
+      border-radius: 4px;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: all var(--transition-fast);
+    }
+
+    .send-btn:hover {
+      background: #0b5d99;
+    }
+
+    .send-btn:disabled {
+      background: var(--border-subtle);
+      cursor: not-allowed;
+    }
+
+    .composer-hint {
+      padding: 8px 12px 0;
+      font-size: 12px;
+      color: var(--text-muted);
+      text-align: right;
+    }
+
+    .composer-hint kbd {
+      font-family: var(--font-family);
+      background: rgba(255, 255, 255, 0.06);
+      padding: 2px 5px;
+      border-radius: 3px;
+      font-size: 11px;
+    }
+
+    /* ========================================
+       @-Mention Autocomplete
+       ======================================== */
+    .mention-autocomplete {
+      position: absolute;
+      bottom: 100%;
+      left: 0;
+      right: 0;
+      margin-bottom: 8px;
+      background: var(--bg-modal);
+      border: 1px solid var(--border-subtle);
+      border-radius: 8px;
+      box-shadow: var(--shadow-modal);
+      max-height: 240px;
+      overflow-y: auto;
+      display: none;
+      z-index: 500;
+    }
+
+    .mention-autocomplete.visible {
+      display: block;
+      animation: autocompleteSlideIn 0.1s ease-out;
+    }
+
+    @keyframes autocompleteSlideIn {
+      from {
+        opacity: 0;
+        transform: translateY(4px);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0);
+      }
+    }
+
+    .mention-autocomplete-header {
+      padding: 8px 12px 4px;
+      font-size: 11px;
+      font-weight: 600;
+      color: var(--text-muted);
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      border-bottom: 1px solid var(--border-divider);
+    }
+
+    .mention-autocomplete-item {
+      padding: 8px 12px;
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      cursor: pointer;
+      transition: background var(--transition-fast);
+    }
+
+    .mention-autocomplete-item:hover,
+    .mention-autocomplete-item.selected {
+      background: rgba(255, 255, 255, 0.08);
+    }
+
+    .mention-autocomplete-item .agent-avatar {
+      width: 24px;
+      height: 24px;
+      font-size: 10px;
+    }
+
+    .mention-autocomplete-name {
+      font-size: 14px;
+      font-weight: 500;
+      color: var(--text-primary);
+    }
+
+    .mention-autocomplete-role {
+      font-size: 12px;
+      color: var(--text-muted);
+      margin-left: auto;
+    }
+
+    .mention-autocomplete-hint {
+      padding: 6px 12px;
+      font-size: 11px;
+      color: var(--text-muted);
+      border-top: 1px solid var(--border-divider);
+      display: flex;
+      gap: 12px;
+    }
+
+    .mention-autocomplete-hint kbd {
+      font-family: var(--font-family);
+      background: rgba(255, 255, 255, 0.1);
+      padding: 1px 5px;
+      border-radius: 3px;
+      font-size: 10px;
+    }
+
+    /* ========================================
+       Command Palette
+       ======================================== */
+    .command-palette-overlay {
+      position: fixed;
+      inset: 0;
+      background: rgba(0, 0, 0, 0.6);
+      display: none;
+      align-items: flex-start;
+      justify-content: center;
+      padding-top: 15vh;
+      z-index: 1000;
+    }
+
+    .command-palette-overlay.visible {
+      display: flex;
+    }
+
+    .command-palette {
+      width: 600px;
+      max-width: 90vw;
+      background: var(--bg-modal);
+      border-radius: 8px;
+      box-shadow: var(--shadow-modal);
+      overflow: hidden;
+      animation: paletteSlideIn 0.15s ease-out;
+    }
+
+    @keyframes paletteSlideIn {
+      from {
+        opacity: 0;
+        transform: translateY(-10px) scale(0.98);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0) scale(1);
+      }
+    }
+
+    .palette-search {
+      padding: 16px;
+      border-bottom: 1px solid var(--border-divider);
+    }
+
+    .palette-search-input {
+      width: 100%;
+      background: transparent;
+      border: none;
+      color: var(--text-primary);
+      font-family: var(--font-family);
+      font-size: 18px;
+      outline: none;
+    }
+
+    .palette-search-input::placeholder {
+      color: var(--text-muted);
+    }
+
+    .palette-results {
+      max-height: 400px;
+      overflow-y: auto;
+    }
+
+    .palette-section {
+      padding: 8px 0;
+    }
+
+    .palette-section-title {
+      padding: 8px 16px 4px;
+      font-size: 12px;
+      font-weight: 600;
+      color: var(--text-muted);
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+    }
+
+    .palette-item {
+      padding: 10px 16px;
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      cursor: pointer;
+      transition: background var(--transition-fast);
+    }
+
+    .palette-item:hover,
+    .palette-item.selected {
+      background: rgba(255, 255, 255, 0.06);
+    }
+
+    .palette-item-icon {
+      width: 20px;
+      height: 20px;
+      color: var(--text-muted);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+
+    .palette-item-content {
+      flex: 1;
+    }
+
+    .palette-item-title {
+      font-size: 14px;
+      color: var(--text-primary);
+    }
+
+    .palette-item-subtitle {
+      font-size: 12px;
+      color: var(--text-muted);
+    }
+
+    .palette-item-shortcut {
+      font-size: 12px;
+      color: var(--text-muted);
+    }
+
+    .palette-item-shortcut kbd {
+      font-family: var(--font-family);
+      background: rgba(255, 255, 255, 0.1);
+      padding: 2px 6px;
+      border-radius: 3px;
+      margin-left: 4px;
+    }
+
+    /* ========================================
+       Thread Panel
+       ======================================== */
+    .thread-panel-overlay {
+      position: fixed;
+      top: 0;
+      right: 0;
+      bottom: 0;
+      width: 400px;
+      background: var(--bg-modal);
+      border-left: 1px solid var(--border-divider);
+      display: none;
+      flex-direction: column;
+      z-index: 100;
+      box-shadow: -4px 0 20px rgba(0, 0, 0, 0.3);
+      animation: threadSlideIn 0.2s ease-out;
+    }
+
+    .thread-panel-overlay.visible {
+      display: flex;
+    }
+
+    @keyframes threadSlideIn {
+      from {
+        transform: translateX(100%);
+        opacity: 0;
+      }
+      to {
+        transform: translateX(0);
+        opacity: 1;
+      }
+    }
+
+    .thread-panel {
+      display: flex;
+      flex-direction: column;
+      height: 100%;
+    }
+
+    .thread-panel-header {
+      padding: 16px;
+      border-bottom: 1px solid var(--border-divider);
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      flex-shrink: 0;
+    }
+
+    .thread-panel-title {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      font-size: 16px;
+      font-weight: 600;
+      color: var(--text-primary);
+    }
+
+    .thread-panel-title .thread-id {
+      font-size: 13px;
+      font-weight: 500;
+      color: var(--text-link);
+      background: rgba(29, 155, 209, 0.1);
+      padding: 2px 8px;
+      border-radius: 4px;
+    }
+
+    .thread-panel-close {
+      width: 32px;
+      height: 32px;
+      border: none;
+      background: transparent;
+      color: var(--text-muted);
+      border-radius: 4px;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: all var(--transition-fast);
+    }
+
+    .thread-panel-close:hover {
+      background: rgba(255, 255, 255, 0.1);
+      color: var(--text-primary);
+    }
+
+    .thread-messages {
+      flex: 1;
+      overflow-y: auto;
+      padding: 16px;
+    }
+
+    .thread-message {
+      padding: 12px;
+      background: rgba(255, 255, 255, 0.02);
+      border-radius: 8px;
+      margin-bottom: 12px;
+    }
+
+    .thread-message:last-child {
+      margin-bottom: 0;
+    }
+
+    .thread-message-header {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      margin-bottom: 6px;
+    }
+
+    .thread-message-avatar {
+      width: 28px;
+      height: 28px;
+      border-radius: 4px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-weight: 600;
+      font-size: 11px;
+      color: white;
+    }
+
+    .thread-message-sender {
+      font-weight: 600;
+      color: var(--text-primary);
+      font-size: 14px;
+    }
+
+    .thread-message-time {
+      font-size: 12px;
+      color: var(--text-muted);
+    }
+
+    .thread-message-body {
+      font-size: 14px;
+      color: var(--text-primary);
+      line-height: 1.4;
+      word-wrap: break-word;
+      white-space: pre-wrap;
+    }
+
+    .thread-composer {
+      padding: 16px;
+      border-top: 1px solid var(--border-divider);
+      display: flex;
+      gap: 8px;
+      align-items: flex-end;
+      flex-shrink: 0;
+    }
+
+    .thread-composer-input {
+      flex: 1;
+      padding: 10px 12px;
+      background: var(--bg-input);
+      border: 1px solid var(--border-subtle);
+      border-radius: 6px;
+      color: var(--text-primary);
+      font-family: var(--font-family);
+      font-size: 14px;
+      resize: none;
+      outline: none;
+      min-height: 40px;
+      max-height: 120px;
+    }
+
+    .thread-composer-input:focus {
+      border-color: var(--accent-primary);
+    }
+
+    .thread-composer-input::placeholder {
+      color: var(--text-muted);
+    }
+
+    .thread-send-btn {
+      width: 36px;
+      height: 36px;
+      border: none;
+      background: var(--accent-primary);
+      color: white;
+      border-radius: 6px;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: all var(--transition-fast);
+      flex-shrink: 0;
+    }
+
+    .thread-send-btn:hover {
+      background: #0b5d99;
     }
 
-    .last-active {
+    .thread-empty {
+      text-align: center;
+      padding: 32px;
+      color: var(--text-muted);
+    }
+
+    /* Reply count badge on messages */
+    .reply-count-badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
       margin-top: 8px;
-      font-size: 0.7rem;
+      padding: 4px 8px;
+      background: rgba(29, 155, 209, 0.1);
+      border-radius: 4px;
+      font-size: 12px;
+      color: var(--text-link);
+      cursor: pointer;
+      transition: background var(--transition-fast);
+    }
+
+    .reply-count-badge:hover {
+      background: rgba(29, 155, 209, 0.2);
+    }
+
+    .reply-count-badge svg {
+      width: 14px;
+      height: 14px;
+    }
+
+    /* ========================================
+       Empty States
+       ======================================== */
+    .empty-state {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      padding: 48px 24px;
+      text-align: center;
+    }
+
+    .empty-state-icon {
+      width: 64px;
+      height: 64px;
+      margin-bottom: 16px;
       color: var(--text-muted);
     }
+
+    .empty-state-title {
+      font-size: 18px;
+      font-weight: 600;
+      color: var(--text-primary);
+      margin-bottom: 8px;
+    }
+
+    .empty-state-text {
+      font-size: 14px;
+      color: var(--text-muted);
+      max-width: 300px;
+    }
+
+    /* ========================================
+       Scrollbars
+       ======================================== */
+    ::-webkit-scrollbar {
+      width: 8px;
+      height: 8px;
+    }
+
+    ::-webkit-scrollbar-track {
+      background: transparent;
+    }
+
+    ::-webkit-scrollbar-thumb {
+      background: rgba(255, 255, 255, 0.2);
+      border-radius: 4px;
+    }
+
+    ::-webkit-scrollbar-thumb:hover {
+      background: rgba(255, 255, 255, 0.3);
+    }
+
+    /* ========================================
+       Utilities
+       ======================================== */
+    .visually-hidden {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      border: 0;
+    }
+
+    /* ========================================
+       Spawn Modal
+       ======================================== */
+    .spawn-modal-overlay {
+      position: fixed;
+      inset: 0;
+      background: rgba(0, 0, 0, 0.6);
+      display: none;
+      align-items: center;
+      justify-content: center;
+      z-index: 1000;
+    }
+
+    .spawn-modal-overlay.visible {
+      display: flex;
+    }
+
+    .spawn-modal {
+      width: 480px;
+      max-width: 90vw;
+      background: var(--bg-modal);
+      border-radius: 12px;
+      box-shadow: var(--shadow-modal);
+      overflow: hidden;
+      animation: modalSlideIn 0.2s ease-out;
+    }
+
+    @keyframes modalSlideIn {
+      from {
+        opacity: 0;
+        transform: translateY(-20px) scale(0.95);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0) scale(1);
+      }
+    }
+
+    .spawn-modal-header {
+      padding: 16px 20px;
+      border-bottom: 1px solid var(--border-divider);
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+    }
+
+    .spawn-modal-title {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      font-size: 18px;
+      font-weight: 600;
+      color: var(--text-primary);
+    }
+
+    .spawn-modal-title svg {
+      color: var(--accent-green);
+    }
+
+    .spawn-modal-close {
+      width: 32px;
+      height: 32px;
+      border: none;
+      background: transparent;
+      color: var(--text-muted);
+      border-radius: 6px;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: all var(--transition-fast);
+    }
+
+    .spawn-modal-close:hover {
+      background: rgba(255, 255, 255, 0.1);
+      color: var(--text-primary);
+    }
+
+    .spawn-modal-body {
+      padding: 20px;
+    }
+
+    .spawn-form-group {
+      margin-bottom: 16px;
+    }
+
+    .spawn-form-group:last-child {
+      margin-bottom: 0;
+    }
+
+    .spawn-form-group label {
+      display: block;
+      font-size: 13px;
+      font-weight: 600;
+      color: var(--text-secondary);
+      margin-bottom: 6px;
+    }
+
+    .spawn-input,
+    .spawn-textarea {
+      width: 100%;
+      padding: 10px 12px;
+      background: var(--bg-input);
+      border: 1px solid var(--border-subtle);
+      border-radius: 6px;
+      color: var(--text-primary);
+      font-family: var(--font-family);
+      font-size: 14px;
+      transition: border-color var(--transition-fast);
+    }
+
+    .spawn-input:focus,
+    .spawn-textarea:focus {
+      outline: none;
+      border-color: var(--accent-primary);
+    }
+
+    .spawn-input::placeholder,
+    .spawn-textarea::placeholder {
+      color: var(--text-muted);
+    }
+
+    .spawn-textarea {
+      resize: vertical;
+      min-height: 80px;
+      line-height: 1.4;
+    }
+
+    .spawn-hint {
+      display: block;
+      font-size: 12px;
+      color: var(--text-muted);
+      margin-top: 4px;
+    }
+
+    .spawn-status {
+      min-height: 20px;
+      font-size: 13px;
+      margin-top: 12px;
+    }
+
+    .spawn-status.success {
+      color: var(--accent-green);
+    }
+
+    .spawn-status.error {
+      color: var(--accent-red);
+    }
+
+    .spawn-status.loading {
+      color: var(--text-muted);
+    }
+
+    .spawn-modal-footer {
+      padding: 16px 20px;
+      border-top: 1px solid var(--border-divider);
+      display: flex;
+      justify-content: flex-end;
+      gap: 10px;
+    }
+
+    .spawn-cancel-btn {
+      padding: 8px 16px;
+      background: transparent;
+      border: 1px solid var(--border-subtle);
+      border-radius: 6px;
+      color: var(--text-secondary);
+      font-size: 14px;
+      font-weight: 500;
+      cursor: pointer;
+      transition: all var(--transition-fast);
+    }
+
+    .spawn-cancel-btn:hover {
+      background: rgba(255, 255, 255, 0.05);
+      color: var(--text-primary);
+    }
+
+    .spawn-submit-btn {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      padding: 8px 16px;
+      background: var(--accent-green);
+      border: none;
+      border-radius: 6px;
+      color: white;
+      font-size: 14px;
+      font-weight: 600;
+      cursor: pointer;
+      transition: all var(--transition-fast);
+    }
+
+    .spawn-submit-btn:hover:not(:disabled) {
+      background: #249966;
+    }
+
+    .spawn-submit-btn:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+
+    /* Spawned Agent Indicator */
+    .channel-item .spawned-icon {
+      width: 14px;
+      height: 14px;
+      color: var(--accent-green);
+      flex-shrink: 0;
+    }
+
+    .channel-item .release-btn {
+      opacity: 0;
+      width: 18px;
+      height: 18px;
+      border: none;
+      background: var(--accent-red);
+      color: white;
+      border-radius: 4px;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: opacity var(--transition-fast);
+      flex-shrink: 0;
+    }
+
+    .channel-item:hover .release-btn {
+      opacity: 1;
+    }
+
+    .channel-item .release-btn:hover {
+      background: #c41a4f;
+    }
   </style>
 </head>
 <body>
-  <div class="container">
-    <div class="sidebar">
-        <div class="header">
-            <div class="logo">
-                <div class="logo-icon">AR</div>
-                <h1>Agent Relay</h1>
-            </div>
-            <div id="connection-status">
-                <span class="dot"></span>
-                <span>Connected</span>
+  <div class="app-container">
+    <!-- Sidebar -->
+    <aside class="sidebar">
+      <div class="workspace-header">
+        <div class="workspace-name">
+          <span class="status-dot" id="connection-dot"></span>
+          Agent Relay
+        </div>
+        <button class="compose-new-btn" title="New message">
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M12 20h9"/>
+            <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z"/>
+          </svg>
+        </button>
+      </div>
+
+      <div class="search-bar" id="search-trigger">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <circle cx="11" cy="11" r="8"/>
+          <path d="M21 21l-4.35-4.35"/>
+        </svg>
+        <span>Search</span>
+        <kbd>Ctrl K</kbd>
+      </div>
+
+      <div class="sidebar-content">
+        <!-- Channels Section -->
+        <div class="section">
+          <div class="section-header" id="channels-header">
+            <div class="section-title">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M6 9l6 6 6-6"/>
+              </svg>
+              Channels
             </div>
+          </div>
+          <ul class="channel-list" id="channels-list">
+            <li class="channel-item active" data-channel="general">
+              <span class="channel-prefix">#</span>
+              <span class="channel-name">general</span>
+            </li>
+          </ul>
         </div>
-        <div class="agents-section">
-            <div class="agents-header">Agents</div>
-            <div id="agents">
-               <!-- Agents injected here -->
+
+        <!-- Agents Section -->
+        <div class="section">
+          <div class="section-header" id="agents-header">
+            <div class="section-title">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M6 9l6 6 6-6"/>
+              </svg>
+              Agents
             </div>
+            <button class="section-add-btn" id="spawn-btn" title="Spawn new agent" style="opacity: 1;">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <line x1="12" y1="5" x2="12" y2="19"/>
+                <line x1="5" y1="12" x2="19" y2="12"/>
+              </svg>
+            </button>
+          </div>
+          <ul class="channel-list" id="agents-list">
+            <!-- Agents injected here -->
+          </ul>
         </div>
-    </div>
 
-    <div class="main-content">
-        <div class="activity-log">
-            <div class="log-header">
-                <h2>Activity</h2>
-                <div class="live-indicator">
-                    <span class="live-dot"></span>
-                    <span>Live</span>
-                </div>
+      </div>
+
+      <div class="sidebar-footer">
+        <a href="/metrics" class="nav-link">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M3 3v18h18"/>
+            <path d="M18 17V9"/>
+            <path d="M13 17V5"/>
+            <path d="M8 17v-3"/>
+          </svg>
+          Metrics
+        </a>
+        <a href="/bridge" class="nav-link">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <rect x="3" y="3" width="7" height="7"/>
+            <rect x="14" y="3" width="7" height="7"/>
+            <rect x="14" y="14" width="7" height="7"/>
+            <rect x="3" y="14" width="7" height="7"/>
+          </svg>
+          Bridge View
+        </a>
+      </div>
+    </aside>
+
+    <!-- Main Panel -->
+    <main class="main-panel">
+      <header class="channel-header">
+        <div class="channel-header-name">
+          <span class="prefix">#</span>
+          <span id="current-channel-name">general</span>
+        </div>
+        <div class="header-divider"></div>
+        <div class="channel-topic" id="channel-topic">All agent communications</div>
+        <div class="header-actions">
+          <div class="online-count">
+            <span class="dot"></span>
+            <span id="online-count">0 online</span>
+          </div>
+        </div>
+      </header>
+
+      <div class="messages-container">
+        <div class="messages-list" id="messages-list">
+          <!-- Messages injected here -->
+        </div>
+        <div class="typing-indicator" id="typing-indicator">
+          <div class="typing-dots">
+            <span></span>
+            <span></span>
+            <span></span>
+          </div>
+          <span id="typing-text">Someone is typing...</span>
+        </div>
+      </div>
+
+      <div class="composer">
+        <div class="composer-container" style="position: relative;">
+          <!-- @-Mention Autocomplete Dropdown -->
+          <div class="mention-autocomplete" id="mention-autocomplete">
+            <div class="mention-autocomplete-header">Agents</div>
+            <div id="mention-autocomplete-list">
+              <!-- Agent items will be injected here -->
             </div>
-            <div class="log-content" id="log">
-                <!-- Messages injected here -->
+            <div class="mention-autocomplete-hint">
+              <span><kbd>Tab</kbd> or <kbd>Enter</kbd> to select</span>
+              <span><kbd>↑↓</kbd> to navigate</span>
+              <span><kbd>Esc</kbd> to close</span>
             </div>
+          </div>
+          <div class="composer-input-row">
+            <div class="composer-toolbar">
+              <button class="toolbar-btn" id="bold-btn" title="Bold (Ctrl+B)">
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                  <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z"/>
+                  <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z"/>
+                </svg>
+              </button>
+              <button class="toolbar-btn" id="emoji-btn" title="Add emoji">
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                  <circle cx="12" cy="12" r="10"/>
+                  <path d="M8 14s1.5 2 4 2 4-2 4-2"/>
+                  <line x1="9" y1="9" x2="9.01" y2="9"/>
+                  <line x1="15" y1="9" x2="15.01" y2="9"/>
+                </svg>
+              </button>
+            </div>
+            <textarea
+              id="message-input"
+              class="composer-input"
+              placeholder="@AgentName message... (or @* to broadcast)"
+              rows="1"
+            ></textarea>
+            <div class="composer-send">
+              <button class="send-btn" id="send-btn" title="Send message">
+                <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                  <line x1="22" y1="2" x2="11" y2="13"/>
+                  <polygon points="22 2 15 22 11 13 2 9 22 2"/>
+                </svg>
+              </button>
+            </div>
+          </div>
         </div>
-    </div>
+        <div class="composer-hint">
+          <kbd>Ctrl</kbd> + <kbd>Enter</kbd> to send
+        </div>
+      </div>
+    </main>
   </div>
 
-  <script>
-    const agentsContainer = document.getElementById('agents');
-    const logContainer = document.getElementById('log');
-    const statusDiv = document.getElementById('connection-status');
-
-    // Track last data hash to prevent unnecessary re-renders
-    let lastDataHash = '';
-
-    function connect() {
-        const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-        const ws = new WebSocket(`${protocol}//${window.location.host}/ws`);
-
-        ws.onopen = () => {
-            statusDiv.innerHTML = '<span class="dot"></span><span>Live</span>';
-            statusDiv.classList.remove('disconnected');
-        };
-
-        ws.onclose = () => {
-            statusDiv.innerHTML = '<span class="dot"></span><span>Offline</span>';
-            statusDiv.classList.add('disconnected');
-            setTimeout(connect, 3000);
-        };
-
-        ws.onmessage = (e) => {
-            // Skip re-render if data hasn't changed
-            const dataHash = e.data;
-            if (dataHash === lastDataHash) return;
-            lastDataHash = dataHash;
-
-            const data = JSON.parse(e.data);
-            render(data);
-        };
-    }
-
-    function render(data) {
-        // Render Agents
-        if (data.agents && data.agents.length > 0) {
-            const newAgentsHTML = data.agents.map((a, i) => `
-                <div class="agent-card ${a.messageCount > 0 ? 'active' : ''}">
-                    <div class="agent-header">
-                        <div class="agent-name">${a.name}</div>
-                        ${a.messageCount > 0 ? `<span class="badge">${a.messageCount}</span>` : ''}
-                    </div>
-                    <div class="agent-meta">
-                        <span class="cli-badge">${a.cli}</span>
-                    </div>
-                    <div class="agent-status">
-                        <span class="status-dot"></span>
-                        ${a.status && a.status !== 'Idle' ? a.status : 'Ready'}
-                    </div>
-                    <div class="last-active">
-                        ${a.lastActive ? timeAgo(new Date(a.lastActive)) : 'No activity'}
-                    </div>
-                </div>
-            `).join('');
-
-            if (agentsContainer.innerHTML !== newAgentsHTML) {
-                agentsContainer.innerHTML = newAgentsHTML;
-            }
-        } else if (!agentsContainer.querySelector('.empty-state')) {
-            agentsContainer.innerHTML = `
-                <div class="empty-state">
-                    <div class="empty-state-text">Waiting for agents...</div>
-                </div>
-            `;
-        }
-
-        // Render Messages (Activity Log)
-        if (data.messages && data.messages.length > 0) {
-            const currentCount = logContainer.querySelectorAll('.message').length;
-            const newCount = data.messages.length;
-
-            if (currentCount !== newCount) {
-                logContainer.innerHTML = data.messages.map(m => createMessageHTML(m)).join('');
-            }
-        } else if (!logContainer.querySelector('.empty-state')) {
-            logContainer.innerHTML = `
-                <div class="empty-state">
-                    <div class="empty-state-text">No messages yet</div>
-                </div>
-            `;
-        }
-    }
-
-    function createMessageHTML(m) {
-        const initials = m.from.substring(0, 2).toUpperCase();
-        return `
-            <div class="message">
-                <div class="msg-avatar">${initials}</div>
-                <div class="msg-body">
-                    <div class="msg-meta">
-                        <span class="msg-sender">${m.from}</span>
-                        <span class="msg-arrow">→</span>
-                        <span class="msg-target">${m.to}</span>
-                        <span class="msg-time">${new Date(m.timestamp).toLocaleTimeString()}</span>
-                    </div>
-                    <div class="msg-text">${escapeHtml(m.content)}</div>
-                </div>
+  <!-- Command Palette -->
+  <div class="command-palette-overlay" id="command-palette-overlay">
+    <div class="command-palette">
+      <div class="palette-search">
+        <input
+          type="text"
+          class="palette-search-input"
+          id="palette-search"
+          placeholder="Search messages, agents, or type a command..."
+          autocomplete="off"
+        >
+      </div>
+      <div class="palette-results" id="palette-results">
+        <div class="palette-section">
+          <div class="palette-section-title">Commands</div>
+          <div class="palette-item" data-command="broadcast">
+            <div class="palette-item-icon">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5"/>
+                <path d="M15.54 8.46a5 5 0 0 1 0 7.07"/>
+                <path d="M19.07 4.93a10 10 0 0 1 0 14.14"/>
+              </svg>
             </div>
-        `;
-    }
+            <div class="palette-item-content">
+              <div class="palette-item-title">/broadcast</div>
+              <div class="palette-item-subtitle">Send message to all agents</div>
+            </div>
+          </div>
+          <div class="palette-item" data-command="status">
+            <div class="palette-item-icon">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <circle cx="12" cy="12" r="10"/>
+                <path d="M12 6v6l4 2"/>
+              </svg>
+            </div>
+            <div class="palette-item-content">
+              <div class="palette-item-title">/status</div>
+              <div class="palette-item-subtitle">Set your status message</div>
+            </div>
+          </div>
+          <div class="palette-item" data-command="clear">
+            <div class="palette-item-icon">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M3 6h18"/>
+                <path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/>
+              </svg>
+            </div>
+            <div class="palette-item-content">
+              <div class="palette-item-title">/clear</div>
+              <div class="palette-item-subtitle">Clear message view</div>
+            </div>
+          </div>
+        </div>
+        <div class="palette-section" id="palette-channels-section">
+          <div class="palette-section-title">Channels</div>
+          <div class="palette-item" data-jump-channel="general">
+            <div class="palette-item-icon">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M4 9l4-4 4 4"/>
+                <path d="M12 15l4 4 4-4"/>
+                <line x1="8" y1="5" x2="8" y2="19"/>
+                <line x1="16" y1="5" x2="16" y2="19"/>
+              </svg>
+            </div>
+            <div class="palette-item-content">
+              <div class="palette-item-title">#general</div>
+              <div class="palette-item-subtitle">All agent communications</div>
+            </div>
+          </div>
+        </div>
+        <div class="palette-section" id="palette-agents-section">
+          <div class="palette-section-title">Jump to Agent</div>
+          <!-- Agents will be injected here -->
+        </div>
+        <div class="palette-section" id="palette-messages-section" style="display: none;">
+          <div class="palette-section-title">Recent Messages</div>
+          <!-- Filtered messages will be injected here -->
+        </div>
+      </div>
+    </div>
+  </div>
 
-    function escapeHtml(text) {
-        if (!text) return '';
-        const div = document.createElement('div');
-        div.textContent = text;
-        return div.innerHTML;
-    }
+  <!-- Thread Panel -->
+  <div class="thread-panel-overlay" id="thread-panel-overlay">
+    <div class="thread-panel">
+      <div class="thread-panel-header">
+        <div class="thread-panel-title">
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+          </svg>
+          <span>Thread</span>
+          <span class="thread-id" id="thread-panel-id"></span>
+        </div>
+        <button class="thread-panel-close" id="thread-panel-close" title="Close thread">
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <line x1="18" y1="6" x2="6" y2="18"/>
+            <line x1="6" y1="6" x2="18" y2="18"/>
+          </svg>
+        </button>
+      </div>
+      <div class="thread-messages" id="thread-messages">
+        <!-- Thread messages will be injected here -->
+      </div>
+      <div class="thread-composer">
+        <textarea
+          id="thread-message-input"
+          class="thread-composer-input"
+          placeholder="Reply in thread..."
+          rows="1"
+        ></textarea>
+        <button class="thread-send-btn" id="thread-send-btn" title="Send reply">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <line x1="22" y1="2" x2="11" y2="13"/>
+            <polygon points="22 2 15 22 11 13 2 9 22 2"/>
+          </svg>
+        </button>
+      </div>
+    </div>
+  </div>
 
-    function timeAgo(date) {
-        const seconds = Math.floor((new Date() - date) / 1000);
-        if (seconds < 60) return 'just now';
-        const minutes = Math.floor(seconds / 60);
-        if (minutes < 60) return `${minutes}m ago`;
-        const hours = Math.floor(minutes / 60);
-        if (hours < 24) return `${hours}h ago`;
-        return `${Math.floor(hours / 24)}d ago`;
-    }
+  <!-- Spawn Agent Modal -->
+  <div class="spawn-modal-overlay" id="spawn-modal-overlay">
+    <div class="spawn-modal">
+      <div class="spawn-modal-header">
+        <div class="spawn-modal-title">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2"/>
+            <circle cx="12" cy="7" r="4"/>
+            <line x1="12" y1="11" x2="12" y2="17"/>
+            <line x1="9" y1="14" x2="15" y2="14"/>
+          </svg>
+          Spawn New Agent
+        </div>
+        <button class="spawn-modal-close" id="spawn-modal-close" title="Close">
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <line x1="18" y1="6" x2="6" y2="18"/>
+            <line x1="6" y1="6" x2="18" y2="18"/>
+          </svg>
+        </button>
+      </div>
+      <div class="spawn-modal-body">
+        <div class="spawn-form-group">
+          <label for="spawn-name-input">Agent Name</label>
+          <input
+            type="text"
+            id="spawn-name-input"
+            class="spawn-input"
+            placeholder="e.g., Developer, Reviewer, Tester"
+            autocomplete="off"
+          />
+        </div>
+        <div class="spawn-form-group">
+          <label for="spawn-cli-input">CLI Command</label>
+          <input
+            type="text"
+            id="spawn-cli-input"
+            class="spawn-input"
+            value="claude"
+            placeholder="e.g., claude, aider, cursor"
+          />
+          <span class="spawn-hint">The AI CLI tool to wrap</span>
+        </div>
+        <div class="spawn-form-group">
+          <label for="spawn-task-input">Initial Task (optional)</label>
+          <textarea
+            id="spawn-task-input"
+            class="spawn-textarea"
+            placeholder="Enter an initial task to send to the agent..."
+            rows="4"
+          ></textarea>
+          <span class="spawn-hint">This will be injected into the agent's terminal</span>
+        </div>
+        <div class="spawn-status" id="spawn-status"></div>
+      </div>
+      <div class="spawn-modal-footer">
+        <button class="spawn-cancel-btn" id="spawn-cancel-btn">Cancel</button>
+        <button class="spawn-submit-btn" id="spawn-submit-btn">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <polygon points="5 3 19 12 5 21 5 3"/>
+          </svg>
+          Spawn Agent
+        </button>
+      </div>
+    </div>
+  </div>
 
-    connect();
-  </script>
+  <!-- Dashboard Application (TypeScript bundled) -->
+  <script type="module" src="/js/app.js"></script>
 </body>
 </html>
diff --git a/src/dashboard/public/js/app.js b/src/dashboard/public/js/app.js
new file mode 100644
index 000000000..cfe9d7e31
--- /dev/null
+++ b/src/dashboard/public/js/app.js
@@ -0,0 +1,140 @@
+var i={agents:[],messages:[],currentChannel:"general",currentThread:null,isConnected:!1,ws:null,reconnectAttempts:0},E=[];function V(t){return E.push(t),()=>{let e=E.indexOf(t);e>-1&&E.splice(e,1)}}function w(){E.forEach(t=>t())}function F(t){i.agents=t,w()}function U(t){i.messages=t,w()}function z(t){i.currentChannel=t,w()}function x(t){i.isConnected=t,t&&(i.reconnectAttempts=0),w()}function W(){i.reconnectAttempts++}function _(t){i.ws=t}function J(){let{messages:t,currentChannel:e}=i;return e==="general"?t:t.filter(n=>n.from===e||n.to===e)}function A(t){i.currentThread=t}function Q(t){return i.messages.filter(e=>e.thread===t)}function Y(t){return i.messages.filter(e=>e.thread===t).length}var G=null;function I(){let t=window.location.protocol==="https:"?"wss:":"ws:",e=new WebSocket(`${t}//${window.location.host}/ws`);e.onopen=()=>{x(!0)},e.onclose=()=>{x(!1);let n=Math.min(1e3*Math.pow(2,i.reconnectAttempts),3e4);W(),setTimeout(I,n)},e.onerror=n=>{console.error("WebSocket error:",n)},e.onmessage=n=>{try{let s=JSON.parse(n.data);he(s)}catch(s){console.error("Failed to parse message:",s)}},_(e)}function he(t){console.log("[WS] Received data:",{agentCount:t.agents?.length,messageCount:t.messages?.length}),t.agents&&(console.log("[WS] Setting agents:",t.agents.map(e=>e.name)),F(t.agents)),t.messages&&U(t.messages),G&&G(t)}async function T(t,e,n){try{let s={to:t,message:e};n&&(s.thread=n);let o=await fetch("/api/send",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(s)}),r=await o.json();return o.ok&&r.success?{success:!0}:{success:!1,error:r.error||"Failed to send message"}}catch{return{success:!1,error:"Network error - could not send message"}}}function L(t){if(!t)return!1;let e=Date.parse(t);return Number.isNaN(e)?!1:Date.now()-e<3e4}function l(t){if(!t)return"";let e=document.createElement("div");return e.textContent=t,e.innerHTML}function C(t){return new Date(t).toLocaleTimeString([],{hour:"numeric",minute:"2-digit"})}function X(t){let e=new Date(t),n=new Date,s=new Date(n);return s.setDate(s.getDate()-1),e.toDateString()===n.toDateString()?"Today":e.toDateString()===s.toDateString()?"Yesterday":e.toLocaleDateString([],{weekday:"long",month:"long",day:"numeric"})}function h(t){let e=["#e01e5a","#2bac76","#e8a427","#1264a3","#7c3aed","#0d9488","#dc2626","#9333ea","#ea580c","#0891b2"],n=0;for(let s=0;s<t.length;s++)n=t.charCodeAt(s)+((n<<5)-n);return e[Math.abs(n)%e.length]}function v(t){return t.substring(0,2).toUpperCase()}function k(t){if(!t)return"";let e=l(t);return e=e.replace(/```([\s\S]*?)```/g,"<pre>$1</pre>"),e=e.replace(/`([^`]+)`/g,"<code>$1</code>"),e=e.replace(/\n/g,"<br>"),e}var ee=[],a,c=-1;function te(){return a={connectionDot:document.getElementById("connection-dot"),channelsList:document.getElementById("channels-list"),agentsList:document.getElementById("agents-list"),messagesList:document.getElementById("messages-list"),currentChannelName:document.getElementById("current-channel-name"),channelTopic:document.getElementById("channel-topic"),onlineCount:document.getElementById("online-count"),messageInput:document.getElementById("message-input"),sendBtn:document.getElementById("send-btn"),boldBtn:document.getElementById("bold-btn"),emojiBtn:document.getElementById("emoji-btn"),searchTrigger:document.getElementById("search-trigger"),commandPaletteOverlay:document.getElementById("command-palette-overlay"),paletteSearch:document.getElementById("palette-search"),paletteResults:document.getElementById("palette-results"),paletteChannelsSection:document.getElementById("palette-channels-section"),paletteAgentsSection:document.getElementById("palette-agents-section"),paletteMessagesSection:document.getElementById("palette-messages-section"),typingIndicator:document.getElementById("typing-indicator"),threadPanelOverlay:document.getElementById("thread-panel-overlay"),threadPanelId:document.getElementById("thread-panel-id"),threadPanelClose:document.getElementById("thread-panel-close"),threadMessages:document.getElementById("thread-messages"),threadMessageInput:document.getElementById("thread-message-input"),threadSendBtn:document.getElementById("thread-send-btn"),mentionAutocomplete:document.getElementById("mention-autocomplete"),mentionAutocompleteList:document.getElementById("mention-autocomplete-list"),spawnBtn:document.getElementById("spawn-btn"),spawnModalOverlay:document.getElementById("spawn-modal-overlay"),spawnModalClose:document.getElementById("spawn-modal-close"),spawnNameInput:document.getElementById("spawn-name-input"),spawnCliInput:document.getElementById("spawn-cli-input"),spawnTaskInput:document.getElementById("spawn-task-input"),spawnSubmitBtn:document.getElementById("spawn-submit-btn"),spawnStatus:document.getElementById("spawn-status")},a}function H(){return a}function ne(){i.isConnected?a.connectionDot.classList.remove("offline"):a.connectionDot.classList.add("offline")}function $(){console.log("[UI] renderAgents called, agents:",i.agents.length,i.agents.map(n=>n.name));let t=new Set(ee.map(n=>n.name)),e=i.agents.map(n=>{let o=L(n.lastSeen||n.lastActive)?"online":"",r=i.currentChannel===n.name,d=n.needsAttention?"needs-attention":"",p=t.has(n.name),S=p?`
+        <svg class="spawned-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" title="Spawned from dashboard">
+          <polygon points="5 3 19 12 5 21 5 3"/>
+        </svg>
+      `:"",ge=p?`
+        <button class="release-btn" title="Release agent" data-release="${l(n.name)}">
+          <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
+            <line x1="18" y1="6" x2="6" y2="18"/>
+            <line x1="6" y1="6" x2="18" y2="18"/>
+          </svg>
+        </button>
+      `:"";return`
+      <li class="channel-item ${r?"active":""} ${d}" data-agent="${l(n.name)}" ${p?'title="Spawned from dashboard"':""}>
+        <div class="agent-avatar" style="background: ${p?"var(--accent-green)":h(n.name)}">
+          ${v(n.name)}
+          <span class="presence-indicator ${o}"></span>
+        </div>
+        <span class="channel-name">${l(n.name)}</span>
+        ${S}
+        ${n.needsAttention?'<span class="attention-badge">Needs Input</span>':""}
+        ${ge}
+      </li>
+    `}).join("");a.agentsList.innerHTML=e||'<li class="channel-item" style="color: var(--text-muted); cursor: default;">No agents connected</li>',a.agentsList.querySelectorAll(".channel-item[data-agent]").forEach(n=>{n.addEventListener("click",s=>{if(s.target.closest(".release-btn"))return;let o=n.dataset.agent;o&&g(o)})}),a.agentsList.querySelectorAll(".release-btn[data-release]").forEach(n=>{n.addEventListener("click",async s=>{s.stopPropagation();let o=n.dataset.release;o&&confirm(`Release agent "${o}"? This will terminate the agent.`)&&await Ee(o)})}),ve()}function D(){let t=J();if(t.length===0){a.messagesList.innerHTML=`
+      <div class="empty-state">
+        <svg class="empty-state-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+          <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+        </svg>
+        <div class="empty-state-title">No messages yet</div>
+        <div class="empty-state-text">
+          ${i.currentChannel==="general"?"Messages between agents will appear here":`Messages with ${i.currentChannel} will appear here`}
+        </div>
+      </div>
+    `;return}let e="",n=null;t.forEach(s=>{let o=new Date(s.timestamp).toDateString();o!==n&&(e+=`
+        <div class="date-divider">
+          <span class="date-divider-text">${X(s.timestamp)}</span>
+        </div>
+      `,n=o);let r=s.to==="*",d=h(s.from),p=Y(s.id),S=r?"@everyone":s.project?`<span class="project-badge">${l(s.project)}</span>@${l(s.to)}`:`@${l(s.to)}`;e+=`
+      <div class="message ${r?"broadcast":""}" data-id="${l(s.id)}">
+        <div class="message-avatar" style="background: ${d}">
+          ${v(s.from)}
+        </div>
+        <div class="message-content">
+          <div class="message-header">
+            <span class="message-sender">@${l(s.from)}</span>
+            <span class="message-recipient">
+              \u2192 <span class="target">${S}</span>
+            </span>
+            <span class="message-timestamp">${C(s.timestamp)}</span>
+          </div>
+          <div class="message-body">${k(s.content)}</div>
+          ${s.thread?`
+            <div class="thread-indicator" data-thread="${l(s.thread)}">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+              </svg>
+              Thread: ${l(s.thread)}
+            </div>
+          `:""}
+          ${p>0?`
+            <div class="reply-count-badge" data-thread="${l(s.id)}">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+              </svg>
+              ${p} ${p===1?"reply":"replies"}
+            </div>
+          `:""}
+        </div>
+        <div class="message-actions">
+          <button class="message-action-btn" data-action="reply" title="Reply in thread">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+            </svg>
+          </button>
+          <button class="message-action-btn" title="Add reaction">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <circle cx="12" cy="12" r="10"/>
+              <path d="M8 14s1.5 2 4 2 4-2 4-2"/>
+              <line x1="9" y1="9" x2="9.01" y2="9"/>
+              <line x1="15" y1="9" x2="15.01" y2="9"/>
+            </svg>
+          </button>
+        </div>
+      </div>
+    `}),a.messagesList.innerHTML=e,ye()}function g(t){z(t),a.channelsList.querySelectorAll(".channel-item").forEach(n=>{n.classList.toggle("active",n.dataset.channel===t)}),a.agentsList.querySelectorAll(".channel-item").forEach(n=>{n.classList.toggle("active",n.dataset.agent===t)});let e=document.querySelector(".channel-header-name .prefix");if(t==="general")a.currentChannelName.innerHTML="general",a.channelTopic.textContent="All agent communications",e&&(e.textContent="#");else{a.currentChannelName.innerHTML=l(t);let n=i.agents.find(s=>s.name===t);a.channelTopic.textContent=n?.status||"Direct messages",e&&(e.textContent="@")}a.messageInput.placeholder=t==="general"?"@AgentName message... (or @* to broadcast)":`Message ${t}... (@ not required)`,D()}function se(){let t=i.agents.filter(e=>L(e.lastSeen||e.lastActive)).length;a.onlineCount.textContent=`${t} online`}function ve(){let t=i.agents.map(s=>{let o=L(s.lastSeen||s.lastActive);return`
+      <div class="palette-item" data-jump-agent="${l(s.name)}">
+        <div class="palette-item-icon">
+          <div class="agent-avatar" style="background: ${h(s.name)}; width: 20px; height: 20px; font-size: 9px;">
+            ${v(s.name)}
+            <span class="presence-indicator ${o?"online":""}"></span>
+          </div>
+        </div>
+        <div class="palette-item-content">
+          <div class="palette-item-title">${l(s.name)}</div>
+          <div class="palette-item-subtitle">${o?"Online":"Offline"}</div>
+        </div>
+      </div>
+    `}).join(""),e=a.paletteAgentsSection;e.querySelectorAll(".palette-item").forEach(s=>s.remove()),e.insertAdjacentHTML("beforeend",t),e.querySelectorAll(".palette-item[data-jump-agent]").forEach(s=>{s.addEventListener("click",()=>{let o=s.dataset.jumpAgent;o&&(g(o),m())})})}function ae(){a.paletteChannelsSection.querySelectorAll(".palette-item[data-jump-channel]").forEach(t=>{t.addEventListener("click",()=>{let e=t.dataset.jumpChannel;e&&(g(e),m())})})}function P(){a.commandPaletteOverlay.classList.add("visible"),a.paletteSearch.value="",a.paletteSearch.focus(),c=-1,j("")}function oe(){return Array.from(a.paletteResults.querySelectorAll(".palette-item")).filter(e=>e.style.display!=="none")}function Z(){let t=oe();if(t.forEach(e=>e.classList.remove("selected")),c>=0&&c<t.length){let e=t[c];e.classList.add("selected"),e.scrollIntoView({block:"nearest",behavior:"smooth"})}}function re(t){let e=oe();if(e.length!==0)switch(t.key){case"ArrowDown":t.preventDefault(),c=c<e.length-1?c+1:0,Z();break;case"ArrowUp":t.preventDefault(),c=c>0?c-1:e.length-1,Z();break;case"Enter":t.preventDefault(),c>=0&&c<e.length&&fe(e[c]);break}}function fe(t){let e=t.dataset.command;if(e){e==="broadcast"?(a.messageInput.value="@* ",a.messageInput.focus()):e==="clear"&&(a.messagesList.innerHTML=""),m();return}let n=t.dataset.jumpChannel;if(n){g(n),m();return}let s=t.dataset.jumpAgent;if(s){g(s),m();return}let o=t.dataset.jumpMessage;if(o){let r=a.messagesList.querySelector(`[data-id="${o}"]`);r&&(r.scrollIntoView({behavior:"smooth",block:"center"}),r.classList.add("highlighted"),setTimeout(()=>r.classList.remove("highlighted"),2e3)),m();return}}function m(){a.commandPaletteOverlay.classList.remove("visible")}function j(t){let e=t.toLowerCase();if(c=-1,document.querySelectorAll(".palette-item[data-command]").forEach(n=>{let o=n.querySelector(".palette-item-title")?.textContent?.toLowerCase()||"";n.style.display=o.includes(e)?"flex":"none"}),document.querySelectorAll(".palette-item[data-jump-channel]").forEach(n=>{let o=n.querySelector(".palette-item-title")?.textContent?.toLowerCase()||"";n.style.display=o.includes(e)?"flex":"none"}),document.querySelectorAll(".palette-item[data-jump-agent]").forEach(n=>{let s=n.dataset.jumpAgent?.toLowerCase()||"";n.style.display=s.includes(e)?"flex":"none"}),e.length>=2){let n=i.messages.filter(s=>s.content.toLowerCase().includes(e)).slice(0,5);if(n.length>0){a.paletteMessagesSection.style.display="block";let s=n.map(r=>`
+        <div class="palette-item" data-jump-message="${l(r.id)}">
+          <div class="palette-item-icon">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>
+            </svg>
+          </div>
+          <div class="palette-item-content">
+            <div class="palette-item-title">${l(r.from)}</div>
+            <div class="palette-item-subtitle">${l(r.content.substring(0,60))}${r.content.length>60?"...":""}</div>
+          </div>
+        </div>
+      `).join("");a.paletteMessagesSection.querySelectorAll(".palette-item").forEach(r=>r.remove()),a.paletteMessagesSection.insertAdjacentHTML("beforeend",s)}else a.paletteMessagesSection.style.display="none"}else a.paletteMessagesSection.style.display="none"}function B(t){A(t),a.threadPanelId.textContent=t,a.threadPanelOverlay.classList.add("visible"),a.threadMessageInput.value="",N(t),a.threadMessageInput.focus()}function O(){A(null),a.threadPanelOverlay.classList.remove("visible")}function N(t){let e=Q(t);if(e.length===0){a.threadMessages.innerHTML=`
+      <div class="thread-empty">
+        <p>No messages in this thread yet.</p>
+        <p style="font-size: 12px; margin-top: 8px;">Start the conversation below!</p>
+      </div>
+    `;return}let n=e.map(s=>`
+      <div class="thread-message">
+        <div class="thread-message-header">
+          <div class="thread-message-avatar" style="background: ${h(s.from)}">
+            ${v(s.from)}
+          </div>
+          <span class="thread-message-sender">${l(s.from)}</span>
+          <span class="thread-message-time">${C(s.timestamp)}</span>
+        </div>
+        <div class="thread-message-body">${k(s.content)}</div>
+      </div>
+    `).join("");a.threadMessages.innerHTML=n,a.threadMessages.scrollTop=a.threadMessages.scrollHeight}function ye(){a.messagesList.querySelectorAll(".thread-indicator").forEach(t=>{t.style.cursor="pointer",t.addEventListener("click",e=>{e.stopPropagation();let n=t.dataset.thread;n&&B(n)})}),a.messagesList.querySelectorAll(".reply-count-badge").forEach(t=>{t.addEventListener("click",e=>{e.stopPropagation();let n=t.dataset.thread;n&&B(n)})}),a.messagesList.querySelectorAll('.message-action-btn[data-action="reply"]').forEach(t=>{t.addEventListener("click",e=>{e.stopPropagation();let n=t.closest(".message")?.getAttribute("data-id");n&&B(n)})})}var u=0,M=[];function ie(t){let e=t.toLowerCase();M=i.agents.filter(s=>s.name.toLowerCase().includes(e)),u=0;let n="";("*".includes(e)||"everyone".includes(e)||"all".includes(e)||"broadcast".includes(e))&&(n+=`
+      <div class="mention-autocomplete-item ${u===0&&M.length===0?"selected":""}" data-mention="*">
+        <div class="agent-avatar" style="background: var(--accent-yellow);">*</div>
+        <span class="mention-autocomplete-name">@everyone</span>
+        <span class="mention-autocomplete-role">Broadcast to all</span>
+      </div>
+    `),M.forEach((s,o)=>{n+=`
+      <div class="mention-autocomplete-item ${o===u?"selected":""}" data-mention="${l(s.name)}">
+        <div class="agent-avatar" style="background: ${h(s.name)}">
+          ${v(s.name)}
+        </div>
+        <span class="mention-autocomplete-name">@${l(s.name)}</span>
+        <span class="mention-autocomplete-role">${l(s.role||"Agent")}</span>
+      </div>
+    `}),n===""&&(n='<div class="mention-autocomplete-item" style="color: var(--text-muted); cursor: default;">No matching agents</div>'),a.mentionAutocompleteList.innerHTML=n,a.mentionAutocomplete.classList.add("visible"),a.mentionAutocompleteList.querySelectorAll(".mention-autocomplete-item[data-mention]").forEach(s=>{s.addEventListener("click",()=>{let o=s.dataset.mention;o&&R(o)})})}function f(){a.mentionAutocomplete.classList.remove("visible"),M=[],u=0}function le(){return a.mentionAutocomplete.classList.contains("visible")}function q(t){let e=a.mentionAutocompleteList.querySelectorAll(".mention-autocomplete-item[data-mention]");e.length!==0&&(e[u]?.classList.remove("selected"),t==="down"?u=(u+1)%e.length:u=(u-1+e.length)%e.length,e[u]?.classList.add("selected"),e[u]?.scrollIntoView({block:"nearest"}))}function R(t){let e=a.mentionAutocompleteList.querySelectorAll(".mention-autocomplete-item[data-mention]"),n=t;if(!n&&e.length>0&&(n=e[u]?.dataset.mention),!n){f();return}let s=a.messageInput,o=s.value,r=o.match(/^@\S*/);if(r){let d=`@${n} `;s.value=d+o.substring(r[0].length),s.selectionStart=s.selectionEnd=d.length}f(),s.focus()}function ce(){let t=a.messageInput,e=t.value,n=t.selectionStart,s=e.match(/^@(\S*)/);return s&&n<=s[0].length?s[1]:null}function de(){a.spawnModalOverlay.classList.add("visible"),a.spawnNameInput.value="",a.spawnCliInput.value="claude",a.spawnTaskInput.value="",a.spawnStatus.textContent="",a.spawnStatus.className="spawn-status",a.spawnNameInput.focus()}function y(){a.spawnModalOverlay.classList.remove("visible")}async function K(){let t=a.spawnNameInput.value.trim(),e=a.spawnCliInput.value.trim()||"claude",n=a.spawnTaskInput.value.trim();if(!t)return a.spawnStatus.textContent="Agent name is required",a.spawnStatus.className="spawn-status error",{success:!1,error:"Agent name is required"};a.spawnSubmitBtn.disabled=!0,a.spawnStatus.textContent="Spawning agent...",a.spawnStatus.className="spawn-status loading";try{let s=await fetch("/api/spawn",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({name:t,cli:e,task:n})}),o=await s.json();if(s.ok&&o.success)return a.spawnStatus.textContent=`Agent "${t}" spawned successfully!`,a.spawnStatus.className="spawn-status success",await b(),setTimeout(()=>{y()},1e3),{success:!0};throw new Error(o.error||"Failed to spawn agent")}catch(s){return a.spawnStatus.textContent=s.message||"Failed to spawn agent",a.spawnStatus.className="spawn-status error",{success:!1,error:s.message}}finally{a.spawnSubmitBtn.disabled=!1}}async function b(){try{let e=await(await fetch("/api/spawned")).json();e.success&&Array.isArray(e.agents)&&(ee=e.agents,$())}catch(t){console.error("[UI] Failed to fetch spawned agents:",t)}}async function Ee(t){try{let n=await(await fetch(`/api/spawned/${encodeURIComponent(t)}`,{method:"DELETE"})).json();n.success?await b():console.error("[UI] Failed to release agent:",n.error)}catch(e){console.error("[UI] Failed to release agent:",e)}}function ue(){let t=te();V(()=>{ne(),$(),D(),se()}),we(t),I(),b()}function we(t){t.channelsList.querySelectorAll(".channel-item").forEach(e=>{e.addEventListener("click",()=>{let n=e.dataset.channel;n&&g(n)})}),t.sendBtn.addEventListener("click",me),t.messageInput.addEventListener("keydown",e=>{if(le()){if(e.key==="Tab"||e.key==="Enter"){e.preventDefault(),R();return}if(e.key==="ArrowUp"){e.preventDefault(),q("up");return}if(e.key==="ArrowDown"){e.preventDefault(),q("down");return}if(e.key==="Escape"){e.preventDefault(),f();return}}e.key==="Enter"&&!e.shiftKey&&(e.preventDefault(),me())}),t.messageInput.addEventListener("input",()=>{t.messageInput.style.height="auto",t.messageInput.style.height=Math.min(t.messageInput.scrollHeight,200)+"px";let e=ce();e!==null?ie(e):f()}),t.messageInput.addEventListener("blur",()=>{setTimeout(()=>{f()},150)}),t.boldBtn.addEventListener("click",()=>{let e=t.messageInput,n=e.selectionStart,s=e.selectionEnd,o=e.value;if(n===s){let r=o.substring(0,n),d=o.substring(s);e.value=r+"**bold**"+d,e.selectionStart=n+2,e.selectionEnd=n+6}else{let r=o.substring(0,n),d=o.substring(n,s),p=o.substring(s);e.value=r+"**"+d+"**"+p,e.selectionStart=n,e.selectionEnd=s+4}e.focus()}),t.emojiBtn.addEventListener("click",()=>{let e=["\u{1F44D}","\u{1F44E}","\u2705","\u274C","\u{1F389}","\u{1F525}","\u{1F4A1}","\u26A0\uFE0F","\u{1F4DD}","\u{1F680}"],n=e[Math.floor(Math.random()*e.length)],s=t.messageInput,o=s.selectionStart,r=s.value;s.value=r.substring(0,o)+n+r.substring(o),s.selectionStart=s.selectionEnd=o+n.length,s.focus()}),t.searchTrigger.addEventListener("click",P),document.addEventListener("keydown",e=>{(e.ctrlKey||e.metaKey)&&e.key==="k"&&(e.preventDefault(),t.commandPaletteOverlay.classList.contains("visible")?m():P()),e.key==="Escape"&&m()}),t.commandPaletteOverlay.addEventListener("click",e=>{e.target===t.commandPaletteOverlay&&m()}),t.paletteSearch.addEventListener("input",e=>{let n=e.target;j(n.value)}),t.paletteSearch.addEventListener("keydown",re),document.querySelectorAll(".palette-item[data-command]").forEach(e=>{e.addEventListener("click",()=>{let n=e.dataset.command;n==="broadcast"?(t.messageInput.value="@* ",t.messageInput.focus()):n==="clear"&&(t.messagesList.innerHTML=""),m()})}),ae(),t.threadPanelClose.addEventListener("click",O),t.threadSendBtn.addEventListener("click",pe),t.threadMessageInput.addEventListener("keydown",e=>{e.key==="Enter"&&!e.shiftKey&&(e.preventDefault(),pe())}),document.addEventListener("keydown",e=>{e.key==="Escape"&&t.threadPanelOverlay.classList.contains("visible")&&O()}),t.spawnBtn.addEventListener("click",de),t.spawnModalClose.addEventListener("click",y),document.getElementById("spawn-cancel-btn")?.addEventListener("click",y),t.spawnModalOverlay.addEventListener("click",e=>{e.target===t.spawnModalOverlay&&y()}),document.addEventListener("keydown",e=>{e.key==="Escape"&&t.spawnModalOverlay.classList.contains("visible")&&y()}),t.spawnSubmitBtn.addEventListener("click",K),t.spawnNameInput.addEventListener("keydown",e=>{e.key==="Enter"&&!e.shiftKey&&(e.preventDefault(),K())})}function Le(t){let n=t.trim().match(/^@(\*|[^\s]+)\s+(.+)$/s);return n?{to:n[1],message:n[2].trim()}:null}async function me(){let t=H(),e=t.messageInput.value.trim();if(!e)return;let n,s,o=i.currentChannel!=="general",r=Le(e);if(r)n=r.to,s=r.message;else if(o)n=i.currentChannel,s=e;else{alert('Message must start with @recipient (e.g., "@Lead hello" or "@* broadcast")');return}t.sendBtn.disabled=!0;let d=await T(n,s);d.success?(t.messageInput.value="",t.messageInput.style.height="auto"):alert(d.error),t.sendBtn.disabled=!1}async function pe(){let t=H(),e=t.threadMessageInput.value.trim(),n=i.currentThread;if(!e||!n)return;t.threadSendBtn.disabled=!0;let s=await T("*",e,n);s.success?(t.threadMessageInput.value="",N(n)):alert(s.error),t.threadSendBtn.disabled=!1}typeof document<"u"&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",ue):ue());export{ue as initApp};
+//# sourceMappingURL=app.js.map
diff --git a/src/dashboard/public/js/app.js.map b/src/dashboard/public/js/app.js.map
new file mode 100644
index 000000000..ecdebdb10
--- /dev/null
+++ b/src/dashboard/public/js/app.js.map
@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../frontend/state.ts", "../../frontend/websocket.ts", "../../frontend/utils.ts", "../../frontend/components.ts", "../../frontend/app.ts"],
+  "sourcesContent": ["/**\n * Dashboard State Management\n */\n\nimport type { Agent, Message, AppState, ChannelType } from './types.js';\n\n/**\n * Global application state\n */\nexport const state: AppState = {\n  agents: [],\n  messages: [],\n  currentChannel: 'general',\n  currentThread: null,\n  isConnected: false,\n  ws: null,\n  reconnectAttempts: 0,\n};\n\n/**\n * State update callbacks\n */\ntype StateListener = () => void;\nconst listeners: StateListener[] = [];\n\n/**\n * Subscribe to state changes\n */\nexport function subscribe(listener: StateListener): () => void {\n  listeners.push(listener);\n  return () => {\n    const index = listeners.indexOf(listener);\n    if (index > -1) {\n      listeners.splice(index, 1);\n    }\n  };\n}\n\n/**\n * Notify all listeners of state change\n */\nfunction notifyListeners(): void {\n  listeners.forEach((listener) => listener());\n}\n\n/**\n * Update agents in state\n */\nexport function setAgents(agents: Agent[]): void {\n  state.agents = agents;\n  notifyListeners();\n}\n\n/**\n * Update messages in state\n */\nexport function setMessages(messages: Message[]): void {\n  state.messages = messages;\n  notifyListeners();\n}\n\n/**\n * Set current channel/conversation\n */\nexport function setCurrentChannel(channel: ChannelType): void {\n  state.currentChannel = channel;\n  notifyListeners();\n}\n\n/**\n * Update connection status\n */\nexport function setConnectionStatus(connected: boolean): void {\n  state.isConnected = connected;\n  if (connected) {\n    state.reconnectAttempts = 0;\n  }\n  notifyListeners();\n}\n\n/**\n * Increment reconnect attempts\n */\nexport function incrementReconnectAttempts(): void {\n  state.reconnectAttempts++;\n}\n\n/**\n * Set WebSocket instance\n */\nexport function setWebSocket(ws: WebSocket | null): void {\n  state.ws = ws;\n}\n\n/**\n * Filter messages based on current channel\n */\nexport function getFilteredMessages(): Message[] {\n  const { messages, currentChannel } = state;\n\n  if (currentChannel === 'general') {\n    return messages;\n  }\n\n  // Filter for specific agent - show messages to/from that agent\n  return messages.filter(\n    (m) => m.from === currentChannel || m.to === currentChannel\n  );\n}\n\n/**\n * Set current thread for thread panel\n */\nexport function setCurrentThread(thread: string | null): void {\n  state.currentThread = thread;\n}\n\n/**\n * Get messages for a specific thread\n */\nexport function getThreadMessages(threadId: string): Message[] {\n  return state.messages.filter((m) => m.thread === threadId);\n}\n\n/**\n * Get reply count for a thread\n */\nexport function getThreadReplyCount(threadId: string): number {\n  return state.messages.filter((m) => m.thread === threadId).length;\n}\n", "/**\n * WebSocket Connection Handler\n */\n\nimport type { DashboardData } from './types.js';\nimport {\n  state,\n  setAgents,\n  setMessages,\n  setConnectionStatus,\n  setWebSocket,\n  incrementReconnectAttempts,\n} from './state.js';\n\ntype DataHandler = (data: DashboardData) => void;\n\nlet dataHandler: DataHandler | null = null;\n\n/**\n * Set the handler for incoming data\n */\nexport function onData(handler: DataHandler): void {\n  dataHandler = handler;\n}\n\n/**\n * Connect to the WebSocket server\n */\nexport function connect(): void {\n  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';\n  const ws = new WebSocket(`${protocol}//${window.location.host}/ws`);\n\n  ws.onopen = (): void => {\n    setConnectionStatus(true);\n  };\n\n  ws.onclose = (): void => {\n    setConnectionStatus(false);\n    // Reconnect with exponential backoff\n    const delay = Math.min(1000 * Math.pow(2, state.reconnectAttempts), 30000);\n    incrementReconnectAttempts();\n    setTimeout(connect, delay);\n  };\n\n  ws.onerror = (error): void => {\n    console.error('WebSocket error:', error);\n  };\n\n  ws.onmessage = (event: MessageEvent): void => {\n    try {\n      const data: DashboardData = JSON.parse(event.data as string);\n      handleData(data);\n    } catch (e) {\n      console.error('Failed to parse message:', e);\n    }\n  };\n\n  setWebSocket(ws);\n}\n\n/**\n * Handle incoming dashboard data\n */\nfunction handleData(data: DashboardData): void {\n  console.log('[WS] Received data:', { agentCount: data.agents?.length, messageCount: data.messages?.length });\n\n  if (data.agents) {\n    console.log('[WS] Setting agents:', data.agents.map(a => a.name));\n    setAgents(data.agents);\n  }\n\n  if (data.messages) {\n    setMessages(data.messages);\n  }\n\n  if (dataHandler) {\n    dataHandler(data);\n  }\n}\n\n/**\n * Send a message via the REST API\n */\nexport async function sendMessage(\n  to: string,\n  message: string,\n  thread?: string\n): Promise<{ success: boolean; error?: string }> {\n  try {\n    const body: { to: string; message: string; thread?: string } = { to, message };\n    if (thread) {\n      body.thread = thread;\n    }\n\n    const response = await fetch('/api/send', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(body),\n    });\n\n    const result = await response.json();\n\n    if (response.ok && result.success) {\n      return { success: true };\n    } else {\n      return { success: false, error: result.error || 'Failed to send message' };\n    }\n  } catch (err) {\n    return { success: false, error: 'Network error - could not send message' };\n  }\n}\n", "/**\n * Dashboard Utility Functions\n */\n\n/** Threshold for considering an agent offline (30 seconds) */\nexport const STALE_THRESHOLD_MS = 30000;\n\n/**\n * Check if an agent is online based on last seen timestamp\n */\nexport function isAgentOnline(lastSeen: string | undefined): boolean {\n  if (!lastSeen) return false;\n  const ts = Date.parse(lastSeen);\n  if (Number.isNaN(ts)) return false;\n  return Date.now() - ts < STALE_THRESHOLD_MS;\n}\n\n/**\n * Escape HTML to prevent XSS\n */\nexport function escapeHtml(text: string | undefined): string {\n  if (!text) return '';\n  const div = document.createElement('div');\n  div.textContent = text;\n  return div.innerHTML;\n}\n\n/**\n * Format timestamp to locale time string\n */\nexport function formatTime(timestamp: string): string {\n  const date = new Date(timestamp);\n  return date.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });\n}\n\n/**\n * Format timestamp to human-readable date\n */\nexport function formatDate(timestamp: string): string {\n  const date = new Date(timestamp);\n  const today = new Date();\n  const yesterday = new Date(today);\n  yesterday.setDate(yesterday.getDate() - 1);\n\n  if (date.toDateString() === today.toDateString()) {\n    return 'Today';\n  } else if (date.toDateString() === yesterday.toDateString()) {\n    return 'Yesterday';\n  } else {\n    return date.toLocaleDateString([], {\n      weekday: 'long',\n      month: 'long',\n      day: 'numeric',\n    });\n  }\n}\n\n/**\n * Generate a consistent color for an agent based on their name\n */\nexport function getAvatarColor(name: string): string {\n  const colors = [\n    '#e01e5a',\n    '#2bac76',\n    '#e8a427',\n    '#1264a3',\n    '#7c3aed',\n    '#0d9488',\n    '#dc2626',\n    '#9333ea',\n    '#ea580c',\n    '#0891b2',\n  ];\n  let hash = 0;\n  for (let i = 0; i < name.length; i++) {\n    hash = name.charCodeAt(i) + ((hash << 5) - hash);\n  }\n  return colors[Math.abs(hash) % colors.length];\n}\n\n/**\n * Get initials from a name (first 2 characters, uppercase)\n */\nexport function getInitials(name: string): string {\n  return name.substring(0, 2).toUpperCase();\n}\n\n/**\n * Format message body with basic markdown-like formatting\n */\nexport function formatMessageBody(content: string | undefined): string {\n  if (!content) return '';\n\n  let escaped = escapeHtml(content);\n\n  // Simple code block detection\n  escaped = escaped.replace(/```([\\s\\S]*?)```/g, '<pre>$1</pre>');\n  escaped = escaped.replace(/`([^`]+)`/g, '<code>$1</code>');\n\n  // Convert newlines to <br> for proper multi-line display\n  escaped = escaped.replace(/\\n/g, '<br>');\n\n  return escaped;\n}\n", "/**\n * Dashboard UI Components\n */\n\nimport type { Agent, Message, DOMElements, ChannelType, SpawnedAgent } from './types.js';\nimport { state, getFilteredMessages, setCurrentChannel, setCurrentThread, getThreadMessages, getThreadReplyCount } from './state.js';\nimport {\n  escapeHtml,\n  formatTime,\n  formatDate,\n  getAvatarColor,\n  getInitials,\n  formatMessageBody,\n  isAgentOnline,\n} from './utils.js';\n\n// Track spawned agents\nlet spawnedAgents: SpawnedAgent[] = [];\n\nlet elements: DOMElements;\nlet paletteSelectedIndex = -1;\n\n/**\n * Initialize DOM element references\n */\nexport function initElements(): DOMElements {\n  elements = {\n    connectionDot: document.getElementById('connection-dot')!,\n    channelsList: document.getElementById('channels-list')!,\n    agentsList: document.getElementById('agents-list')!,\n    messagesList: document.getElementById('messages-list')!,\n    currentChannelName: document.getElementById('current-channel-name')!,\n    channelTopic: document.getElementById('channel-topic')!,\n    onlineCount: document.getElementById('online-count')!,\n    messageInput: document.getElementById('message-input') as HTMLTextAreaElement,\n    sendBtn: document.getElementById('send-btn') as HTMLButtonElement,\n    boldBtn: document.getElementById('bold-btn') as HTMLButtonElement,\n    emojiBtn: document.getElementById('emoji-btn') as HTMLButtonElement,\n    searchTrigger: document.getElementById('search-trigger')!,\n    commandPaletteOverlay: document.getElementById('command-palette-overlay')!,\n    paletteSearch: document.getElementById('palette-search') as HTMLInputElement,\n    paletteResults: document.getElementById('palette-results')!,\n    paletteChannelsSection: document.getElementById('palette-channels-section')!,\n    paletteAgentsSection: document.getElementById('palette-agents-section')!,\n    paletteMessagesSection: document.getElementById('palette-messages-section')!,\n    typingIndicator: document.getElementById('typing-indicator')!,\n    threadPanelOverlay: document.getElementById('thread-panel-overlay')!,\n    threadPanelId: document.getElementById('thread-panel-id')!,\n    threadPanelClose: document.getElementById('thread-panel-close') as HTMLButtonElement,\n    threadMessages: document.getElementById('thread-messages')!,\n    threadMessageInput: document.getElementById('thread-message-input') as HTMLTextAreaElement,\n    threadSendBtn: document.getElementById('thread-send-btn') as HTMLButtonElement,\n    mentionAutocomplete: document.getElementById('mention-autocomplete')!,\n    mentionAutocompleteList: document.getElementById('mention-autocomplete-list')!,\n    // Spawn modal elements\n    spawnBtn: document.getElementById('spawn-btn') as HTMLButtonElement,\n    spawnModalOverlay: document.getElementById('spawn-modal-overlay')!,\n    spawnModalClose: document.getElementById('spawn-modal-close') as HTMLButtonElement,\n    spawnNameInput: document.getElementById('spawn-name-input') as HTMLInputElement,\n    spawnCliInput: document.getElementById('spawn-cli-input') as HTMLInputElement,\n    spawnTaskInput: document.getElementById('spawn-task-input') as HTMLTextAreaElement,\n    spawnSubmitBtn: document.getElementById('spawn-submit-btn') as HTMLButtonElement,\n    spawnStatus: document.getElementById('spawn-status')!,\n  };\n  return elements;\n}\n\n/**\n * Get DOM elements\n */\nexport function getElements(): DOMElements {\n  return elements;\n}\n\n/**\n * Update connection status indicator\n */\nexport function updateConnectionStatus(): void {\n  if (state.isConnected) {\n    elements.connectionDot.classList.remove('offline');\n  } else {\n    elements.connectionDot.classList.add('offline');\n  }\n}\n\n/**\n * Render agents list in sidebar\n */\nexport function renderAgents(): void {\n  console.log('[UI] renderAgents called, agents:', state.agents.length, state.agents.map(a => a.name));\n\n  // Create a set of spawned agent names for quick lookup\n  const spawnedNames = new Set(spawnedAgents.map(a => a.name));\n\n  const html = state.agents\n    .map((agent) => {\n      const online = isAgentOnline(agent.lastSeen || agent.lastActive);\n      const presenceClass = online ? 'online' : '';\n      const isActive = state.currentChannel === agent.name;\n      const needsAttentionClass = agent.needsAttention ? 'needs-attention' : '';\n      const isSpawned = spawnedNames.has(agent.name);\n\n      // Spawned icon SVG (play/launch icon)\n      const spawnedIcon = isSpawned ? `\n        <svg class=\"spawned-icon\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" title=\"Spawned from dashboard\">\n          <polygon points=\"5 3 19 12 5 21 5 3\"/>\n        </svg>\n      ` : '';\n\n      // Release button for spawned agents\n      const releaseBtn = isSpawned ? `\n        <button class=\"release-btn\" title=\"Release agent\" data-release=\"${escapeHtml(agent.name)}\">\n          <svg width=\"10\" height=\"10\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"3\">\n            <line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\"/>\n            <line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\"/>\n          </svg>\n        </button>\n      ` : '';\n\n      return `\n      <li class=\"channel-item ${isActive ? 'active' : ''} ${needsAttentionClass}\" data-agent=\"${escapeHtml(agent.name)}\" ${isSpawned ? 'title=\"Spawned from dashboard\"' : ''}>\n        <div class=\"agent-avatar\" style=\"background: ${isSpawned ? 'var(--accent-green)' : getAvatarColor(agent.name)}\">\n          ${getInitials(agent.name)}\n          <span class=\"presence-indicator ${presenceClass}\"></span>\n        </div>\n        <span class=\"channel-name\">${escapeHtml(agent.name)}</span>\n        ${spawnedIcon}\n        ${agent.needsAttention ? '<span class=\"attention-badge\">Needs Input</span>' : ''}\n        ${releaseBtn}\n      </li>\n    `;\n    })\n    .join('');\n\n  elements.agentsList.innerHTML =\n    html ||\n    '<li class=\"channel-item\" style=\"color: var(--text-muted); cursor: default;\">No agents connected</li>';\n\n  // Add click handlers for agent selection\n  elements.agentsList.querySelectorAll<HTMLElement>('.channel-item[data-agent]').forEach((item) => {\n    item.addEventListener('click', (e) => {\n      // Don't select channel if clicking release button\n      if ((e.target as HTMLElement).closest('.release-btn')) {\n        return;\n      }\n      const agentName = item.dataset.agent;\n      if (agentName) {\n        selectChannel(agentName);\n      }\n    });\n  });\n\n  // Add release button click handlers\n  elements.agentsList.querySelectorAll<HTMLButtonElement>('.release-btn[data-release]').forEach((btn) => {\n    btn.addEventListener('click', async (e) => {\n      e.stopPropagation();\n      const agentName = btn.dataset.release;\n      if (agentName && confirm(`Release agent \"${agentName}\"? This will terminate the agent.`)) {\n        await releaseAgent(agentName);\n      }\n    });\n  });\n\n  // Update command palette agents\n  updatePaletteAgents();\n}\n\n/**\n * Render messages list\n */\nexport function renderMessages(): void {\n  const filtered = getFilteredMessages();\n\n  if (filtered.length === 0) {\n    elements.messagesList.innerHTML = `\n      <div class=\"empty-state\">\n        <svg class=\"empty-state-icon\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\">\n          <path d=\"M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z\"/>\n        </svg>\n        <div class=\"empty-state-title\">No messages yet</div>\n        <div class=\"empty-state-text\">\n          ${\n            state.currentChannel === 'general'\n              ? 'Messages between agents will appear here'\n              : `Messages with ${state.currentChannel} will appear here`\n          }\n        </div>\n      </div>\n    `;\n    return;\n  }\n\n  let html = '';\n  let lastDate: string | null = null;\n\n  filtered.forEach((msg) => {\n    const msgDate = new Date(msg.timestamp).toDateString();\n\n    // Add date divider if needed\n    if (msgDate !== lastDate) {\n      html += `\n        <div class=\"date-divider\">\n          <span class=\"date-divider-text\">${formatDate(msg.timestamp)}</span>\n        </div>\n      `;\n      lastDate = msgDate;\n    }\n\n    const isBroadcast = msg.to === '*';\n    const avatarColor = getAvatarColor(msg.from);\n    const replyCount = getThreadReplyCount(msg.id);\n\n    // Format: @From \u2192 @To: message (like Slack)\n    // For cross-project messages, show project badge before agent name\n    const recipientDisplay = isBroadcast\n      ? '@everyone'\n      : msg.project\n        ? `<span class=\"project-badge\">${escapeHtml(msg.project)}</span>@${escapeHtml(msg.to)}`\n        : `@${escapeHtml(msg.to)}`;\n\n    html += `\n      <div class=\"message ${isBroadcast ? 'broadcast' : ''}\" data-id=\"${escapeHtml(msg.id)}\">\n        <div class=\"message-avatar\" style=\"background: ${avatarColor}\">\n          ${getInitials(msg.from)}\n        </div>\n        <div class=\"message-content\">\n          <div class=\"message-header\">\n            <span class=\"message-sender\">@${escapeHtml(msg.from)}</span>\n            <span class=\"message-recipient\">\n              \u2192 <span class=\"target\">${recipientDisplay}</span>\n            </span>\n            <span class=\"message-timestamp\">${formatTime(msg.timestamp)}</span>\n          </div>\n          <div class=\"message-body\">${formatMessageBody(msg.content)}</div>\n          ${\n            msg.thread\n              ? `\n            <div class=\"thread-indicator\" data-thread=\"${escapeHtml(msg.thread)}\">\n              <svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\">\n                <path d=\"M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z\"/>\n              </svg>\n              Thread: ${escapeHtml(msg.thread)}\n            </div>\n          `\n              : ''\n          }\n          ${\n            replyCount > 0\n              ? `\n            <div class=\"reply-count-badge\" data-thread=\"${escapeHtml(msg.id)}\">\n              <svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\">\n                <path d=\"M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z\"/>\n              </svg>\n              ${replyCount} ${replyCount === 1 ? 'reply' : 'replies'}\n            </div>\n          `\n              : ''\n          }\n        </div>\n        <div class=\"message-actions\">\n          <button class=\"message-action-btn\" data-action=\"reply\" title=\"Reply in thread\">\n            <svg width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\">\n              <path d=\"M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z\"/>\n            </svg>\n          </button>\n          <button class=\"message-action-btn\" title=\"Add reaction\">\n            <svg width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\">\n              <circle cx=\"12\" cy=\"12\" r=\"10\"/>\n              <path d=\"M8 14s1.5 2 4 2 4-2 4-2\"/>\n              <line x1=\"9\" y1=\"9\" x2=\"9.01\" y2=\"9\"/>\n              <line x1=\"15\" y1=\"9\" x2=\"15.01\" y2=\"9\"/>\n            </svg>\n          </button>\n        </div>\n      </div>\n    `;\n  });\n\n  elements.messagesList.innerHTML = html;\n\n  // Note: Auto-scroll removed - interferes with manual scrolling through history\n\n  // Attach thread click handlers\n  attachThreadHandlers();\n}\n\n/**\n * Select a channel and update UI\n */\nexport function selectChannel(channel: ChannelType): void {\n  setCurrentChannel(channel);\n\n  // Update sidebar active states\n  elements.channelsList.querySelectorAll<HTMLElement>('.channel-item').forEach((item) => {\n    item.classList.toggle('active', item.dataset.channel === channel);\n  });\n  elements.agentsList.querySelectorAll<HTMLElement>('.channel-item').forEach((item) => {\n    item.classList.toggle('active', item.dataset.agent === channel);\n  });\n\n  // Update header\n  const prefixEl = document.querySelector('.channel-header-name .prefix');\n  if (channel === 'general') {\n    elements.currentChannelName.innerHTML = 'general';\n    elements.channelTopic.textContent = 'All agent communications';\n    if (prefixEl) prefixEl.textContent = '#';\n  } else {\n    elements.currentChannelName.innerHTML = escapeHtml(channel);\n    const agent = state.agents.find((a) => a.name === channel);\n    elements.channelTopic.textContent = agent?.status || 'Direct messages';\n    if (prefixEl) prefixEl.textContent = '@';\n  }\n\n  // Update composer placeholder - DM mode doesn't require @mention\n  elements.messageInput.placeholder =\n    channel === 'general'\n      ? '@AgentName message... (or @* to broadcast)'\n      : `Message ${channel}... (@ not required)`;\n\n  // Re-render messages\n  renderMessages();\n}\n\n/**\n * Update online count display\n */\nexport function updateOnlineCount(): void {\n  const online = state.agents.filter((a) => isAgentOnline(a.lastSeen || a.lastActive)).length;\n  elements.onlineCount.textContent = `${online} online`;\n}\n\n/**\n * Update agents in command palette\n */\nexport function updatePaletteAgents(): void {\n  const html = state.agents\n    .map((agent) => {\n      const online = isAgentOnline(agent.lastSeen || agent.lastActive);\n      return `\n      <div class=\"palette-item\" data-jump-agent=\"${escapeHtml(agent.name)}\">\n        <div class=\"palette-item-icon\">\n          <div class=\"agent-avatar\" style=\"background: ${getAvatarColor(agent.name)}; width: 20px; height: 20px; font-size: 9px;\">\n            ${getInitials(agent.name)}\n            <span class=\"presence-indicator ${online ? 'online' : ''}\"></span>\n          </div>\n        </div>\n        <div class=\"palette-item-content\">\n          <div class=\"palette-item-title\">${escapeHtml(agent.name)}</div>\n          <div class=\"palette-item-subtitle\">${online ? 'Online' : 'Offline'}</div>\n        </div>\n      </div>\n    `;\n    })\n    .join('');\n\n  const section = elements.paletteAgentsSection;\n  const items = section.querySelectorAll('.palette-item');\n  items.forEach((item) => item.remove());\n  section.insertAdjacentHTML('beforeend', html);\n\n  // Add click handlers\n  section.querySelectorAll<HTMLElement>('.palette-item[data-jump-agent]').forEach((item) => {\n    item.addEventListener('click', () => {\n      const agentName = item.dataset.jumpAgent;\n      if (agentName) {\n        selectChannel(agentName);\n        closeCommandPalette();\n      }\n    });\n  });\n}\n\n/**\n * Initialize channel click handlers in command palette\n */\nexport function initPaletteChannels(): void {\n  elements.paletteChannelsSection\n    .querySelectorAll<HTMLElement>('.palette-item[data-jump-channel]')\n    .forEach((item) => {\n      item.addEventListener('click', () => {\n        const channelName = item.dataset.jumpChannel;\n        if (channelName) {\n          selectChannel(channelName);\n          closeCommandPalette();\n        }\n      });\n    });\n}\n\n/**\n * Open command palette\n */\nexport function openCommandPalette(): void {\n  elements.commandPaletteOverlay.classList.add('visible');\n  elements.paletteSearch.value = '';\n  elements.paletteSearch.focus();\n  paletteSelectedIndex = -1;\n  filterPaletteResults('');\n}\n\n/**\n * Get all visible palette items\n */\nexport function getVisiblePaletteItems(): HTMLElement[] {\n  const allItems = Array.from(\n    elements.paletteResults.querySelectorAll<HTMLElement>('.palette-item')\n  );\n  return allItems.filter((item) => item.style.display !== 'none');\n}\n\n/**\n * Update the selected palette item visually\n */\nexport function updatePaletteSelection(): void {\n  const items = getVisiblePaletteItems();\n\n  // Remove selection from all items\n  items.forEach((item) => item.classList.remove('selected'));\n\n  // Add selection to current item\n  if (paletteSelectedIndex >= 0 && paletteSelectedIndex < items.length) {\n    const selectedItem = items[paletteSelectedIndex];\n    selectedItem.classList.add('selected');\n\n    // Scroll into view if needed\n    selectedItem.scrollIntoView({ block: 'nearest', behavior: 'smooth' });\n  }\n}\n\n/**\n * Handle keyboard navigation in command palette\n */\nexport function handlePaletteKeydown(e: KeyboardEvent): void {\n  const items = getVisiblePaletteItems();\n\n  if (items.length === 0) return;\n\n  switch (e.key) {\n    case 'ArrowDown':\n      e.preventDefault();\n      paletteSelectedIndex = paletteSelectedIndex < items.length - 1\n        ? paletteSelectedIndex + 1\n        : 0;\n      updatePaletteSelection();\n      break;\n\n    case 'ArrowUp':\n      e.preventDefault();\n      paletteSelectedIndex = paletteSelectedIndex > 0\n        ? paletteSelectedIndex - 1\n        : items.length - 1;\n      updatePaletteSelection();\n      break;\n\n    case 'Enter':\n      e.preventDefault();\n      if (paletteSelectedIndex >= 0 && paletteSelectedIndex < items.length) {\n        executePaletteItem(items[paletteSelectedIndex]);\n      }\n      break;\n  }\n}\n\n/**\n * Execute the action for a palette item\n */\nexport function executePaletteItem(item: HTMLElement): void {\n  // Check for command\n  const command = item.dataset.command;\n  if (command) {\n    if (command === 'broadcast') {\n      // Pre-fill message input with @* for broadcast\n      elements.messageInput.value = '@* ';\n      elements.messageInput.focus();\n    } else if (command === 'clear') {\n      elements.messagesList.innerHTML = '';\n    }\n    closeCommandPalette();\n    return;\n  }\n\n  // Check for channel jump\n  const channel = item.dataset.jumpChannel;\n  if (channel) {\n    selectChannel(channel);\n    closeCommandPalette();\n    return;\n  }\n\n  // Check for agent jump\n  const agent = item.dataset.jumpAgent;\n  if (agent) {\n    selectChannel(agent);\n    closeCommandPalette();\n    return;\n  }\n\n  // Check for message jump\n  const messageId = item.dataset.jumpMessage;\n  if (messageId) {\n    // Find and scroll to the message\n    const messageEl = elements.messagesList.querySelector(`[data-id=\"${messageId}\"]`);\n    if (messageEl) {\n      messageEl.scrollIntoView({ behavior: 'smooth', block: 'center' });\n      messageEl.classList.add('highlighted');\n      setTimeout(() => messageEl.classList.remove('highlighted'), 2000);\n    }\n    closeCommandPalette();\n    return;\n  }\n}\n\n/**\n * Close command palette\n */\nexport function closeCommandPalette(): void {\n  elements.commandPaletteOverlay.classList.remove('visible');\n}\n\n/**\n * Filter command palette results based on query\n */\nexport function filterPaletteResults(query: string): void {\n  const q = query.toLowerCase();\n\n  // Reset selection when filtering\n  paletteSelectedIndex = -1;\n\n  // Filter command items\n  document.querySelectorAll<HTMLElement>('.palette-item[data-command]').forEach((item) => {\n    const titleEl = item.querySelector('.palette-item-title');\n    const title = titleEl?.textContent?.toLowerCase() || '';\n    item.style.display = title.includes(q) ? 'flex' : 'none';\n  });\n\n  // Filter channel items\n  document.querySelectorAll<HTMLElement>('.palette-item[data-jump-channel]').forEach((item) => {\n    const titleEl = item.querySelector('.palette-item-title');\n    const title = titleEl?.textContent?.toLowerCase() || '';\n    item.style.display = title.includes(q) ? 'flex' : 'none';\n  });\n\n  // Filter agent items\n  document.querySelectorAll<HTMLElement>('.palette-item[data-jump-agent]').forEach((item) => {\n    const name = item.dataset.jumpAgent?.toLowerCase() || '';\n    item.style.display = name.includes(q) ? 'flex' : 'none';\n  });\n\n  // Show message search if query is long enough\n  if (q.length >= 2) {\n    const matches = state.messages.filter((m) => m.content.toLowerCase().includes(q)).slice(0, 5);\n\n    if (matches.length > 0) {\n      elements.paletteMessagesSection.style.display = 'block';\n      const items = matches\n        .map(\n          (m) => `\n        <div class=\"palette-item\" data-jump-message=\"${escapeHtml(m.id)}\">\n          <div class=\"palette-item-icon\">\n            <svg width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\">\n              <path d=\"M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z\"/>\n            </svg>\n          </div>\n          <div class=\"palette-item-content\">\n            <div class=\"palette-item-title\">${escapeHtml(m.from)}</div>\n            <div class=\"palette-item-subtitle\">${escapeHtml(m.content.substring(0, 60))}${m.content.length > 60 ? '...' : ''}</div>\n          </div>\n        </div>\n      `\n        )\n        .join('');\n\n      const existingItems = elements.paletteMessagesSection.querySelectorAll('.palette-item');\n      existingItems.forEach((item) => item.remove());\n      elements.paletteMessagesSection.insertAdjacentHTML('beforeend', items);\n    } else {\n      elements.paletteMessagesSection.style.display = 'none';\n    }\n  } else {\n    elements.paletteMessagesSection.style.display = 'none';\n  }\n}\n\n/**\n * Open thread panel for a specific thread\n */\nexport function openThreadPanel(threadId: string): void {\n  setCurrentThread(threadId);\n  elements.threadPanelId.textContent = threadId;\n  elements.threadPanelOverlay.classList.add('visible');\n  elements.threadMessageInput.value = '';\n  renderThreadMessages(threadId);\n  elements.threadMessageInput.focus();\n}\n\n/**\n * Close thread panel\n */\nexport function closeThreadPanel(): void {\n  setCurrentThread(null);\n  elements.threadPanelOverlay.classList.remove('visible');\n}\n\n/**\n * Render messages in thread panel\n */\nexport function renderThreadMessages(threadId: string): void {\n  const messages = getThreadMessages(threadId);\n\n  if (messages.length === 0) {\n    elements.threadMessages.innerHTML = `\n      <div class=\"thread-empty\">\n        <p>No messages in this thread yet.</p>\n        <p style=\"font-size: 12px; margin-top: 8px;\">Start the conversation below!</p>\n      </div>\n    `;\n    return;\n  }\n\n  const html = messages\n    .map((msg) => `\n      <div class=\"thread-message\">\n        <div class=\"thread-message-header\">\n          <div class=\"thread-message-avatar\" style=\"background: ${getAvatarColor(msg.from)}\">\n            ${getInitials(msg.from)}\n          </div>\n          <span class=\"thread-message-sender\">${escapeHtml(msg.from)}</span>\n          <span class=\"thread-message-time\">${formatTime(msg.timestamp)}</span>\n        </div>\n        <div class=\"thread-message-body\">${formatMessageBody(msg.content)}</div>\n      </div>\n    `)\n    .join('');\n\n  elements.threadMessages.innerHTML = html;\n\n  // Scroll to bottom\n  elements.threadMessages.scrollTop = elements.threadMessages.scrollHeight;\n}\n\n/**\n * Attach thread click handlers to messages (call after renderMessages)\n */\nexport function attachThreadHandlers(): void {\n  // Thread indicator clicks\n  elements.messagesList.querySelectorAll<HTMLElement>('.thread-indicator').forEach((el) => {\n    el.style.cursor = 'pointer';\n    el.addEventListener('click', (e) => {\n      e.stopPropagation();\n      const threadId = el.dataset.thread;\n      if (threadId) {\n        openThreadPanel(threadId);\n      }\n    });\n  });\n\n  // Reply count badge clicks\n  elements.messagesList.querySelectorAll<HTMLElement>('.reply-count-badge').forEach((el) => {\n    el.addEventListener('click', (e) => {\n      e.stopPropagation();\n      const threadId = el.dataset.thread;\n      if (threadId) {\n        openThreadPanel(threadId);\n      }\n    });\n  });\n\n  // Reply in thread button clicks\n  elements.messagesList.querySelectorAll<HTMLElement>('.message-action-btn[data-action=\"reply\"]').forEach((el) => {\n    el.addEventListener('click', (e) => {\n      e.stopPropagation();\n      const messageId = el.closest('.message')?.getAttribute('data-id');\n      if (messageId) {\n        // Use message ID as thread ID for new threads\n        openThreadPanel(messageId);\n      }\n    });\n  });\n}\n\n/**\n * @-Mention Autocomplete State\n */\nlet mentionSelectedIndex = 0;\nlet mentionFilteredAgents: typeof state.agents = [];\n\n/**\n * Show mention autocomplete dropdown with filtered agents\n */\nexport function showMentionAutocomplete(filter: string): void {\n  const filterLower = filter.toLowerCase();\n\n  // Filter agents by name, include broadcast option\n  mentionFilteredAgents = state.agents.filter(agent =>\n    agent.name.toLowerCase().includes(filterLower)\n  );\n\n  // Reset selection\n  mentionSelectedIndex = 0;\n\n  // Build HTML for agent list\n  let html = '';\n\n  // Add broadcast option if filter matches\n  if ('*'.includes(filterLower) || 'everyone'.includes(filterLower) || 'all'.includes(filterLower) || 'broadcast'.includes(filterLower)) {\n    html += `\n      <div class=\"mention-autocomplete-item ${mentionSelectedIndex === 0 && mentionFilteredAgents.length === 0 ? 'selected' : ''}\" data-mention=\"*\">\n        <div class=\"agent-avatar\" style=\"background: var(--accent-yellow);\">*</div>\n        <span class=\"mention-autocomplete-name\">@everyone</span>\n        <span class=\"mention-autocomplete-role\">Broadcast to all</span>\n      </div>\n    `;\n  }\n\n  // Add agents\n  mentionFilteredAgents.forEach((agent, index) => {\n    const isSelected = index === mentionSelectedIndex;\n    html += `\n      <div class=\"mention-autocomplete-item ${isSelected ? 'selected' : ''}\" data-mention=\"${escapeHtml(agent.name)}\">\n        <div class=\"agent-avatar\" style=\"background: ${getAvatarColor(agent.name)}\">\n          ${getInitials(agent.name)}\n        </div>\n        <span class=\"mention-autocomplete-name\">@${escapeHtml(agent.name)}</span>\n        <span class=\"mention-autocomplete-role\">${escapeHtml(agent.role || 'Agent')}</span>\n      </div>\n    `;\n  });\n\n  if (html === '') {\n    html = '<div class=\"mention-autocomplete-item\" style=\"color: var(--text-muted); cursor: default;\">No matching agents</div>';\n  }\n\n  elements.mentionAutocompleteList.innerHTML = html;\n  elements.mentionAutocomplete.classList.add('visible');\n\n  // Add click handlers to items\n  elements.mentionAutocompleteList.querySelectorAll<HTMLElement>('.mention-autocomplete-item[data-mention]').forEach((item) => {\n    item.addEventListener('click', () => {\n      const mention = item.dataset.mention;\n      if (mention) {\n        completeMention(mention);\n      }\n    });\n  });\n}\n\n/**\n * Hide mention autocomplete dropdown\n */\nexport function hideMentionAutocomplete(): void {\n  elements.mentionAutocomplete.classList.remove('visible');\n  mentionFilteredAgents = [];\n  mentionSelectedIndex = 0;\n}\n\n/**\n * Check if mention autocomplete is visible\n */\nexport function isMentionAutocompleteVisible(): boolean {\n  return elements.mentionAutocomplete.classList.contains('visible');\n}\n\n/**\n * Navigate mention autocomplete selection\n */\nexport function navigateMentionAutocomplete(direction: 'up' | 'down'): void {\n  const items = elements.mentionAutocompleteList.querySelectorAll<HTMLElement>('.mention-autocomplete-item[data-mention]');\n  if (items.length === 0) return;\n\n  // Remove current selection\n  items[mentionSelectedIndex]?.classList.remove('selected');\n\n  // Update index\n  if (direction === 'down') {\n    mentionSelectedIndex = (mentionSelectedIndex + 1) % items.length;\n  } else {\n    mentionSelectedIndex = (mentionSelectedIndex - 1 + items.length) % items.length;\n  }\n\n  // Add new selection\n  items[mentionSelectedIndex]?.classList.add('selected');\n  items[mentionSelectedIndex]?.scrollIntoView({ block: 'nearest' });\n}\n\n/**\n * Complete the current mention selection\n */\nexport function completeMention(mention?: string): void {\n  const items = elements.mentionAutocompleteList.querySelectorAll<HTMLElement>('.mention-autocomplete-item[data-mention]');\n\n  // Use provided mention or get from selected item\n  let selectedMention = mention;\n  if (!selectedMention && items.length > 0) {\n    selectedMention = items[mentionSelectedIndex]?.dataset.mention;\n  }\n\n  if (!selectedMention) {\n    hideMentionAutocomplete();\n    return;\n  }\n\n  // Replace the @... text with the completed mention\n  const input = elements.messageInput;\n  const value = input.value;\n\n  // Find the @ position (should be at start or after whitespace)\n  const atMatch = value.match(/^@\\S*/);\n  if (atMatch) {\n    // Replace the @partial with @CompletedName\n    const completedText = `@${selectedMention} `;\n    input.value = completedText + value.substring(atMatch[0].length);\n    input.selectionStart = input.selectionEnd = completedText.length;\n  }\n\n  hideMentionAutocomplete();\n  input.focus();\n}\n\n/**\n * Get the current @mention being typed (if any)\n */\nexport function getCurrentMentionQuery(): string | null {\n  const input = elements.messageInput;\n  const value = input.value;\n  const cursorPos = input.selectionStart;\n\n  // Check if cursor is within an @mention at the start\n  const atMatch = value.match(/^@(\\S*)/);\n  if (atMatch && cursorPos <= atMatch[0].length) {\n    return atMatch[1]; // Return the text after @\n  }\n\n  return null;\n}\n\n// ========================================\n// Spawn Modal Functions\n// ========================================\n\n/**\n * Open the spawn agent modal\n */\nexport function openSpawnModal(): void {\n  elements.spawnModalOverlay.classList.add('visible');\n  elements.spawnNameInput.value = '';\n  elements.spawnCliInput.value = 'claude';\n  elements.spawnTaskInput.value = '';\n  elements.spawnStatus.textContent = '';\n  elements.spawnStatus.className = 'spawn-status';\n  elements.spawnNameInput.focus();\n}\n\n/**\n * Close the spawn agent modal\n */\nexport function closeSpawnModal(): void {\n  elements.spawnModalOverlay.classList.remove('visible');\n}\n\n/**\n * Spawn a new agent via the API\n */\nexport async function spawnAgent(): Promise<{ success: boolean; error?: string }> {\n  const name = elements.spawnNameInput.value.trim();\n  const cli = elements.spawnCliInput.value.trim() || 'claude';\n  const task = elements.spawnTaskInput.value.trim();\n\n  if (!name) {\n    elements.spawnStatus.textContent = 'Agent name is required';\n    elements.spawnStatus.className = 'spawn-status error';\n    return { success: false, error: 'Agent name is required' };\n  }\n\n  elements.spawnSubmitBtn.disabled = true;\n  elements.spawnStatus.textContent = 'Spawning agent...';\n  elements.spawnStatus.className = 'spawn-status loading';\n\n  try {\n    const response = await fetch('/api/spawn', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ name, cli, task }),\n    });\n\n    const result = await response.json();\n\n    if (response.ok && result.success) {\n      elements.spawnStatus.textContent = `Agent \"${name}\" spawned successfully!`;\n      elements.spawnStatus.className = 'spawn-status success';\n\n      // Refresh spawned agents list\n      await fetchSpawnedAgents();\n\n      // Close modal after brief delay\n      setTimeout(() => {\n        closeSpawnModal();\n      }, 1000);\n\n      return { success: true };\n    } else {\n      throw new Error(result.error || 'Failed to spawn agent');\n    }\n  } catch (err: any) {\n    elements.spawnStatus.textContent = err.message || 'Failed to spawn agent';\n    elements.spawnStatus.className = 'spawn-status error';\n    return { success: false, error: err.message };\n  } finally {\n    elements.spawnSubmitBtn.disabled = false;\n  }\n}\n\n/**\n * Fetch list of spawned agents from API\n */\nexport async function fetchSpawnedAgents(): Promise<void> {\n  try {\n    const response = await fetch('/api/spawned');\n    const result = await response.json();\n\n    if (result.success && Array.isArray(result.agents)) {\n      spawnedAgents = result.agents;\n      // Re-render agents to show spawned status\n      renderAgents();\n    }\n  } catch (err) {\n    console.error('[UI] Failed to fetch spawned agents:', err);\n  }\n}\n\n/**\n * Release a spawned agent\n */\nexport async function releaseAgent(name: string): Promise<void> {\n  try {\n    const response = await fetch(`/api/spawned/${encodeURIComponent(name)}`, {\n      method: 'DELETE',\n    });\n\n    const result = await response.json();\n\n    if (result.success) {\n      // Refresh the list\n      await fetchSpawnedAgents();\n    } else {\n      console.error('[UI] Failed to release agent:', result.error);\n    }\n  } catch (err) {\n    console.error('[UI] Failed to release agent:', err);\n  }\n}\n\n/**\n * Get spawned agents list\n */\nexport function getSpawnedAgents(): SpawnedAgent[] {\n  return spawnedAgents;\n}\n", "/**\n * Dashboard Application Entry Point\n */\n\nimport { subscribe, state } from './state.js';\nimport { connect, sendMessage } from './websocket.js';\nimport {\n  initElements,\n  getElements,\n  updateConnectionStatus,\n  renderAgents,\n  renderMessages,\n  selectChannel,\n  updateOnlineCount,\n  openCommandPalette,\n  closeCommandPalette,\n  filterPaletteResults,\n  handlePaletteKeydown,\n  initPaletteChannels,\n  closeThreadPanel,\n  renderThreadMessages,\n  showMentionAutocomplete,\n  hideMentionAutocomplete,\n  isMentionAutocompleteVisible,\n  navigateMentionAutocomplete,\n  completeMention,\n  getCurrentMentionQuery,\n  openSpawnModal,\n  closeSpawnModal,\n  spawnAgent,\n  fetchSpawnedAgents,\n} from './components.js';\nimport { state } from './state.js';\n\n/**\n * Initialize the dashboard application\n */\nexport function initApp(): void {\n  const elements = initElements();\n\n  // Subscribe to state changes\n  subscribe(() => {\n    updateConnectionStatus();\n    renderAgents();\n    renderMessages();\n    updateOnlineCount();\n  });\n\n  // Set up event listeners\n  setupEventListeners(elements);\n\n  // Connect to WebSocket\n  connect();\n\n  // Fetch initial spawned agents list\n  fetchSpawnedAgents();\n}\n\n/**\n * Set up all event listeners\n */\nfunction setupEventListeners(elements: ReturnType<typeof getElements>): void {\n  // Channel clicks\n  elements.channelsList.querySelectorAll<HTMLElement>('.channel-item').forEach((item) => {\n    item.addEventListener('click', () => {\n      const channel = item.dataset.channel;\n      if (channel) {\n        selectChannel(channel);\n      }\n    });\n  });\n\n  // Send button\n  elements.sendBtn.addEventListener('click', handleSend);\n\n  // Keyboard shortcuts for composer\n  elements.messageInput.addEventListener('keydown', (e: KeyboardEvent) => {\n    // Handle mention autocomplete keys first\n    if (isMentionAutocompleteVisible()) {\n      if (e.key === 'Tab' || e.key === 'Enter') {\n        e.preventDefault();\n        completeMention();\n        return;\n      }\n      if (e.key === 'ArrowUp') {\n        e.preventDefault();\n        navigateMentionAutocomplete('up');\n        return;\n      }\n      if (e.key === 'ArrowDown') {\n        e.preventDefault();\n        navigateMentionAutocomplete('down');\n        return;\n      }\n      if (e.key === 'Escape') {\n        e.preventDefault();\n        hideMentionAutocomplete();\n        return;\n      }\n    }\n\n    // Enter to send (Slack-style), Shift+Enter for newline\n    if (e.key === 'Enter' && !e.shiftKey) {\n      e.preventDefault();\n      handleSend();\n    }\n    // Shift+Enter allows default behavior (inserts newline)\n  });\n\n  // Auto-resize textarea and handle @-mention autocomplete\n  elements.messageInput.addEventListener('input', () => {\n    elements.messageInput.style.height = 'auto';\n    elements.messageInput.style.height =\n      Math.min(elements.messageInput.scrollHeight, 200) + 'px';\n\n    // Check for @-mention at start of input\n    const query = getCurrentMentionQuery();\n    if (query !== null) {\n      showMentionAutocomplete(query);\n    } else {\n      hideMentionAutocomplete();\n    }\n  });\n\n  // Hide mention autocomplete when input loses focus (with delay to allow clicks)\n  elements.messageInput.addEventListener('blur', () => {\n    setTimeout(() => {\n      hideMentionAutocomplete();\n    }, 150);\n  });\n\n  // Bold button - wrap selected text with ** or insert **bold**\n  elements.boldBtn.addEventListener('click', () => {\n    const input = elements.messageInput;\n    const start = input.selectionStart;\n    const end = input.selectionEnd;\n    const text = input.value;\n\n    if (start === end) {\n      // No selection - insert **bold** placeholder\n      const before = text.substring(0, start);\n      const after = text.substring(end);\n      input.value = before + '**bold**' + after;\n      input.selectionStart = start + 2;\n      input.selectionEnd = start + 6;\n    } else {\n      // Wrap selection with **\n      const before = text.substring(0, start);\n      const selected = text.substring(start, end);\n      const after = text.substring(end);\n      input.value = before + '**' + selected + '**' + after;\n      input.selectionStart = start;\n      input.selectionEnd = end + 4;\n    }\n    input.focus();\n  });\n\n  // Emoji button - insert common emojis via simple picker\n  elements.emojiBtn.addEventListener('click', () => {\n    const emojis = ['\uD83D\uDC4D', '\uD83D\uDC4E', '\u2705', '\u274C', '\uD83C\uDF89', '\uD83D\uDD25', '\uD83D\uDCA1', '\u26A0\uFE0F', '\uD83D\uDCDD', '\uD83D\uDE80'];\n    const emoji = emojis[Math.floor(Math.random() * emojis.length)];\n    const input = elements.messageInput;\n    const start = input.selectionStart;\n    const text = input.value;\n    input.value = text.substring(0, start) + emoji + text.substring(start);\n    input.selectionStart = input.selectionEnd = start + emoji.length;\n    input.focus();\n  });\n\n  // Command palette\n  elements.searchTrigger.addEventListener('click', openCommandPalette);\n\n  document.addEventListener('keydown', (e: KeyboardEvent) => {\n    if ((e.ctrlKey || e.metaKey) && e.key === 'k') {\n      e.preventDefault();\n      if (elements.commandPaletteOverlay.classList.contains('visible')) {\n        closeCommandPalette();\n      } else {\n        openCommandPalette();\n      }\n    }\n\n    if (e.key === 'Escape') {\n      closeCommandPalette();\n    }\n  });\n\n  elements.commandPaletteOverlay.addEventListener('click', (e: MouseEvent) => {\n    if (e.target === elements.commandPaletteOverlay) {\n      closeCommandPalette();\n    }\n  });\n\n  elements.paletteSearch.addEventListener('input', (e: Event) => {\n    const target = e.target as HTMLInputElement;\n    filterPaletteResults(target.value);\n  });\n\n  elements.paletteSearch.addEventListener('keydown', handlePaletteKeydown);\n\n  // Command execution\n  document.querySelectorAll<HTMLElement>('.palette-item[data-command]').forEach((item) => {\n    item.addEventListener('click', () => {\n      const command = item.dataset.command;\n\n      if (command === 'broadcast') {\n        // Pre-fill message input with @* for broadcast\n        elements.messageInput.value = '@* ';\n        elements.messageInput.focus();\n      } else if (command === 'clear') {\n        elements.messagesList.innerHTML = '';\n      }\n\n      closeCommandPalette();\n    });\n  });\n\n  // Initialize palette channel click handlers\n  initPaletteChannels();\n\n  // Thread panel close button\n  elements.threadPanelClose.addEventListener('click', closeThreadPanel);\n\n  // Thread panel send button\n  elements.threadSendBtn.addEventListener('click', handleThreadSend);\n\n  // Thread message input keyboard shortcuts (Slack-style)\n  elements.threadMessageInput.addEventListener('keydown', (e: KeyboardEvent) => {\n    if (e.key === 'Enter' && !e.shiftKey) {\n      e.preventDefault();\n      handleThreadSend();\n    }\n    // Shift+Enter allows default behavior (inserts newline)\n  });\n\n  // Close thread panel on Escape\n  document.addEventListener('keydown', (e: KeyboardEvent) => {\n    if (e.key === 'Escape' && elements.threadPanelOverlay.classList.contains('visible')) {\n      closeThreadPanel();\n    }\n  });\n\n  // Spawn modal event listeners\n  elements.spawnBtn.addEventListener('click', openSpawnModal);\n\n  elements.spawnModalClose.addEventListener('click', closeSpawnModal);\n\n  // Cancel button in spawn modal\n  document.getElementById('spawn-cancel-btn')?.addEventListener('click', closeSpawnModal);\n\n  // Close spawn modal on overlay click\n  elements.spawnModalOverlay.addEventListener('click', (e: MouseEvent) => {\n    if (e.target === elements.spawnModalOverlay) {\n      closeSpawnModal();\n    }\n  });\n\n  // Close spawn modal on Escape\n  document.addEventListener('keydown', (e: KeyboardEvent) => {\n    if (e.key === 'Escape' && elements.spawnModalOverlay.classList.contains('visible')) {\n      closeSpawnModal();\n    }\n  });\n\n  // Submit spawn form\n  elements.spawnSubmitBtn.addEventListener('click', spawnAgent);\n\n  // Enter key in spawn name input triggers submit\n  elements.spawnNameInput.addEventListener('keydown', (e: KeyboardEvent) => {\n    if (e.key === 'Enter' && !e.shiftKey) {\n      e.preventDefault();\n      spawnAgent();\n    }\n  });\n}\n\n/**\n * Parse @mention from message text\n * Formats: \"@AgentName message\" or \"@* message\" for broadcast\n * Returns { to, message } or null if no valid mention found\n */\nfunction parseMention(text: string): { to: string; message: string } | null {\n  const trimmed = text.trim();\n\n  // Match @mention at the start of the message\n  // @* for broadcast, @AgentName for direct message\n  const match = trimmed.match(/^@(\\*|[^\\s]+)\\s+(.+)$/s);\n\n  if (!match) {\n    return null;\n  }\n\n  return {\n    to: match[1],\n    message: match[2].trim(),\n  };\n}\n\n/**\n * Handle send button click\n */\nasync function handleSend(): Promise<void> {\n  const elements = getElements();\n  const rawMessage = elements.messageInput.value.trim();\n\n  if (!rawMessage) {\n    return;\n  }\n\n  let to: string;\n  let message: string;\n\n  // Check if we're in a DM (not general channel)\n  const isInDM = state.currentChannel !== 'general';\n\n  // Parse @mention from the message\n  const parsed = parseMention(rawMessage);\n\n  if (parsed) {\n    // Message has explicit @mention - use it\n    to = parsed.to;\n    message = parsed.message;\n  } else if (isInDM) {\n    // In DM context - send to current channel without requiring @\n    to = state.currentChannel;\n    message = rawMessage;\n  } else {\n    // In general channel without @mention - require it\n    alert('Message must start with @recipient (e.g., \"@Lead hello\" or \"@* broadcast\")');\n    return;\n  }\n\n  elements.sendBtn.disabled = true;\n\n  const result = await sendMessage(to, message);\n\n  if (result.success) {\n    elements.messageInput.value = '';\n    elements.messageInput.style.height = 'auto';\n  } else {\n    alert(result.error);\n  }\n\n  elements.sendBtn.disabled = false;\n}\n\n/**\n * Handle thread panel send button click\n */\nasync function handleThreadSend(): Promise<void> {\n  const elements = getElements();\n  const message = elements.threadMessageInput.value.trim();\n  const threadId = state.currentThread;\n\n  if (!message || !threadId) {\n    return;\n  }\n\n  // For thread replies, send to broadcast or use original recipient\n  // For now, send as broadcast with thread ID\n  elements.threadSendBtn.disabled = true;\n\n  const result = await sendMessage('*', message, threadId);\n\n  if (result.success) {\n    elements.threadMessageInput.value = '';\n    // Re-render thread messages to show the new message\n    renderThreadMessages(threadId);\n  } else {\n    alert(result.error);\n  }\n\n  elements.threadSendBtn.disabled = false;\n}\n\n// Auto-initialize when DOM is ready\nif (typeof document !== 'undefined') {\n  if (document.readyState === 'loading') {\n    document.addEventListener('DOMContentLoaded', initApp);\n  } else {\n    initApp();\n  }\n}\n"],
+  "mappings": "AASO,IAAMA,EAAkB,CAC7B,OAAQ,CAAC,EACT,SAAU,CAAC,EACX,eAAgB,UAChB,cAAe,KACf,YAAa,GACb,GAAI,KACJ,kBAAmB,CACrB,EAMMC,EAA6B,CAAC,EAK7B,SAASC,EAAUC,EAAqC,CAC7D,OAAAF,EAAU,KAAKE,CAAQ,EAChB,IAAM,CACX,IAAMC,EAAQH,EAAU,QAAQE,CAAQ,EACpCC,EAAQ,IACVH,EAAU,OAAOG,EAAO,CAAC,CAE7B,CACF,CAKA,SAASC,GAAwB,CAC/BJ,EAAU,QAASE,GAAaA,EAAS,CAAC,CAC5C,CAKO,SAASG,EAAUC,EAAuB,CAC/CP,EAAM,OAASO,EACfF,EAAgB,CAClB,CAKO,SAASG,EAAYC,EAA2B,CACrDT,EAAM,SAAWS,EACjBJ,EAAgB,CAClB,CAKO,SAASK,EAAkBC,EAA4B,CAC5DX,EAAM,eAAiBW,EACvBN,EAAgB,CAClB,CAKO,SAASO,EAAoBC,EAA0B,CAC5Db,EAAM,YAAca,EAChBA,IACFb,EAAM,kBAAoB,GAE5BK,EAAgB,CAClB,CAKO,SAASS,GAAmC,CACjDd,EAAM,mBACR,CAKO,SAASe,EAAaC,EAA4B,CACvDhB,EAAM,GAAKgB,CACb,CAKO,SAASC,GAAiC,CAC/C,GAAM,CAAE,SAAAR,EAAU,eAAAS,CAAe,EAAIlB,EAErC,OAAIkB,IAAmB,UACdT,EAIFA,EAAS,OACbU,GAAMA,EAAE,OAASD,GAAkBC,EAAE,KAAOD,CAC/C,CACF,CAKO,SAASE,EAAiBC,EAA6B,CAC5DrB,EAAM,cAAgBqB,CACxB,CAKO,SAASC,EAAkBC,EAA6B,CAC7D,OAAOvB,EAAM,SAAS,OAAQmB,GAAMA,EAAE,SAAWI,CAAQ,CAC3D,CAKO,SAASC,EAAoBD,EAA0B,CAC5D,OAAOvB,EAAM,SAAS,OAAQmB,GAAMA,EAAE,SAAWI,CAAQ,EAAE,MAC7D,CCjHA,IAAIE,EAAkC,KAY/B,SAASC,GAAgB,CAC9B,IAAMC,EAAW,OAAO,SAAS,WAAa,SAAW,OAAS,MAC5DC,EAAK,IAAI,UAAU,GAAGD,CAAQ,KAAK,OAAO,SAAS,IAAI,KAAK,EAElEC,EAAG,OAAS,IAAY,CACtBC,EAAoB,EAAI,CAC1B,EAEAD,EAAG,QAAU,IAAY,CACvBC,EAAoB,EAAK,EAEzB,IAAMC,EAAQ,KAAK,IAAI,IAAO,KAAK,IAAI,EAAGC,EAAM,iBAAiB,EAAG,GAAK,EACzEC,EAA2B,EAC3B,WAAWN,EAASI,CAAK,CAC3B,EAEAF,EAAG,QAAWK,GAAgB,CAC5B,QAAQ,MAAM,mBAAoBA,CAAK,CACzC,EAEAL,EAAG,UAAaM,GAA8B,CAC5C,GAAI,CACF,IAAMC,EAAsB,KAAK,MAAMD,EAAM,IAAc,EAC3DE,GAAWD,CAAI,CACjB,OAASE,EAAG,CACV,QAAQ,MAAM,2BAA4BA,CAAC,CAC7C,CACF,EAEAC,EAAaV,CAAE,CACjB,CAKA,SAASQ,GAAWD,EAA2B,CAC7C,QAAQ,IAAI,sBAAuB,CAAE,WAAYA,EAAK,QAAQ,OAAQ,aAAcA,EAAK,UAAU,MAAO,CAAC,EAEvGA,EAAK,SACP,QAAQ,IAAI,uBAAwBA,EAAK,OAAO,IAAII,GAAKA,EAAE,IAAI,CAAC,EAChEC,EAAUL,EAAK,MAAM,GAGnBA,EAAK,UACPM,EAAYN,EAAK,QAAQ,EAGvBO,GACFA,EAAYP,CAAI,CAEpB,CAKA,eAAsBQ,EACpBC,EACAC,EACAC,EAC+C,CAC/C,GAAI,CACF,IAAMC,EAAyD,CAAE,GAAAH,EAAI,QAAAC,CAAQ,EACzEC,IACFC,EAAK,OAASD,GAGhB,IAAME,EAAW,MAAM,MAAM,YAAa,CACxC,OAAQ,OACR,QAAS,CAAE,eAAgB,kBAAmB,EAC9C,KAAM,KAAK,UAAUD,CAAI,CAC3B,CAAC,EAEKE,EAAS,MAAMD,EAAS,KAAK,EAEnC,OAAIA,EAAS,IAAMC,EAAO,QACjB,CAAE,QAAS,EAAK,EAEhB,CAAE,QAAS,GAAO,MAAOA,EAAO,OAAS,wBAAyB,CAE7E,MAAc,CACZ,MAAO,CAAE,QAAS,GAAO,MAAO,wCAAyC,CAC3E,CACF,CCpGO,SAASC,EAAcC,EAAuC,CACnE,GAAI,CAACA,EAAU,MAAO,GACtB,IAAMC,EAAK,KAAK,MAAMD,CAAQ,EAC9B,OAAI,OAAO,MAAMC,CAAE,EAAU,GACtB,KAAK,IAAI,EAAIA,EAAK,GAC3B,CAKO,SAASC,EAAWC,EAAkC,CAC3D,GAAI,CAACA,EAAM,MAAO,GAClB,IAAMC,EAAM,SAAS,cAAc,KAAK,EACxC,OAAAA,EAAI,YAAcD,EACXC,EAAI,SACb,CAKO,SAASC,EAAWC,EAA2B,CAEpD,OADa,IAAI,KAAKA,CAAS,EACnB,mBAAmB,CAAC,EAAG,CAAE,KAAM,UAAW,OAAQ,SAAU,CAAC,CAC3E,CAKO,SAASC,EAAWD,EAA2B,CACpD,IAAME,EAAO,IAAI,KAAKF,CAAS,EACzBG,EAAQ,IAAI,KACZC,EAAY,IAAI,KAAKD,CAAK,EAGhC,OAFAC,EAAU,QAAQA,EAAU,QAAQ,EAAI,CAAC,EAErCF,EAAK,aAAa,IAAMC,EAAM,aAAa,EACtC,QACED,EAAK,aAAa,IAAME,EAAU,aAAa,EACjD,YAEAF,EAAK,mBAAmB,CAAC,EAAG,CACjC,QAAS,OACT,MAAO,OACP,IAAK,SACP,CAAC,CAEL,CAKO,SAASG,EAAeC,EAAsB,CACnD,IAAMC,EAAS,CACb,UACA,UACA,UACA,UACA,UACA,UACA,UACA,UACA,UACA,SACF,EACIC,EAAO,EACX,QAASC,EAAI,EAAGA,EAAIH,EAAK,OAAQG,IAC/BD,EAAOF,EAAK,WAAWG,CAAC,IAAMD,GAAQ,GAAKA,GAE7C,OAAOD,EAAO,KAAK,IAAIC,CAAI,EAAID,EAAO,MAAM,CAC9C,CAKO,SAASG,EAAYJ,EAAsB,CAChD,OAAOA,EAAK,UAAU,EAAG,CAAC,EAAE,YAAY,CAC1C,CAKO,SAASK,EAAkBC,EAAqC,CACrE,GAAI,CAACA,EAAS,MAAO,GAErB,IAAIC,EAAUjB,EAAWgB,CAAO,EAGhC,OAAAC,EAAUA,EAAQ,QAAQ,oBAAqB,eAAe,EAC9DA,EAAUA,EAAQ,QAAQ,aAAc,iBAAiB,EAGzDA,EAAUA,EAAQ,QAAQ,MAAO,MAAM,EAEhCA,CACT,CCtFA,IAAIC,GAAgC,CAAC,EAEjCC,EACAC,EAAuB,GAKpB,SAASC,IAA4B,CAC1C,OAAAF,EAAW,CACT,cAAe,SAAS,eAAe,gBAAgB,EACvD,aAAc,SAAS,eAAe,eAAe,EACrD,WAAY,SAAS,eAAe,aAAa,EACjD,aAAc,SAAS,eAAe,eAAe,EACrD,mBAAoB,SAAS,eAAe,sBAAsB,EAClE,aAAc,SAAS,eAAe,eAAe,EACrD,YAAa,SAAS,eAAe,cAAc,EACnD,aAAc,SAAS,eAAe,eAAe,EACrD,QAAS,SAAS,eAAe,UAAU,EAC3C,QAAS,SAAS,eAAe,UAAU,EAC3C,SAAU,SAAS,eAAe,WAAW,EAC7C,cAAe,SAAS,eAAe,gBAAgB,EACvD,sBAAuB,SAAS,eAAe,yBAAyB,EACxE,cAAe,SAAS,eAAe,gBAAgB,EACvD,eAAgB,SAAS,eAAe,iBAAiB,EACzD,uBAAwB,SAAS,eAAe,0BAA0B,EAC1E,qBAAsB,SAAS,eAAe,wBAAwB,EACtE,uBAAwB,SAAS,eAAe,0BAA0B,EAC1E,gBAAiB,SAAS,eAAe,kBAAkB,EAC3D,mBAAoB,SAAS,eAAe,sBAAsB,EAClE,cAAe,SAAS,eAAe,iBAAiB,EACxD,iBAAkB,SAAS,eAAe,oBAAoB,EAC9D,eAAgB,SAAS,eAAe,iBAAiB,EACzD,mBAAoB,SAAS,eAAe,sBAAsB,EAClE,cAAe,SAAS,eAAe,iBAAiB,EACxD,oBAAqB,SAAS,eAAe,sBAAsB,EACnE,wBAAyB,SAAS,eAAe,2BAA2B,EAE5E,SAAU,SAAS,eAAe,WAAW,EAC7C,kBAAmB,SAAS,eAAe,qBAAqB,EAChE,gBAAiB,SAAS,eAAe,mBAAmB,EAC5D,eAAgB,SAAS,eAAe,kBAAkB,EAC1D,cAAe,SAAS,eAAe,iBAAiB,EACxD,eAAgB,SAAS,eAAe,kBAAkB,EAC1D,eAAgB,SAAS,eAAe,kBAAkB,EAC1D,YAAa,SAAS,eAAe,cAAc,CACrD,EACOA,CACT,CAKO,SAASG,GAA2B,CACzC,OAAOH,CACT,CAKO,SAASI,IAA+B,CACzCC,EAAM,YACRL,EAAS,cAAc,UAAU,OAAO,SAAS,EAEjDA,EAAS,cAAc,UAAU,IAAI,SAAS,CAElD,CAKO,SAASM,GAAqB,CACnC,QAAQ,IAAI,oCAAqCD,EAAM,OAAO,OAAQA,EAAM,OAAO,IAAIE,GAAKA,EAAE,IAAI,CAAC,EAGnG,IAAMC,EAAe,IAAI,IAAIT,GAAc,IAAIQ,GAAKA,EAAE,IAAI,CAAC,EAErDE,EAAOJ,EAAM,OAChB,IAAKK,GAAU,CAEd,IAAMC,EADSC,EAAcF,EAAM,UAAYA,EAAM,UAAU,EAChC,SAAW,GACpCG,EAAWR,EAAM,iBAAmBK,EAAM,KAC1CI,EAAsBJ,EAAM,eAAiB,kBAAoB,GACjEK,EAAYP,EAAa,IAAIE,EAAM,IAAI,EAGvCM,EAAcD,EAAY;AAAA;AAAA;AAAA;AAAA,QAI5B,GAGEE,GAAaF,EAAY;AAAA,0EACqCG,EAAWR,EAAM,IAAI,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAMtF,GAEJ,MAAO;AAAA,gCACmBG,EAAW,SAAW,EAAE,IAAIC,CAAmB,iBAAiBI,EAAWR,EAAM,IAAI,CAAC,KAAKK,EAAY,iCAAmC,EAAE;AAAA,uDACrHA,EAAY,sBAAwBI,EAAeT,EAAM,IAAI,CAAC;AAAA,YACzGU,EAAYV,EAAM,IAAI,CAAC;AAAA,4CACSC,CAAa;AAAA;AAAA,qCAEpBO,EAAWR,EAAM,IAAI,CAAC;AAAA,UACjDM,CAAW;AAAA,UACXN,EAAM,eAAiB,mDAAqD,EAAE;AAAA,UAC9EO,EAAU;AAAA;AAAA,KAGhB,CAAC,EACA,KAAK,EAAE,EAEVjB,EAAS,WAAW,UAClBS,GACA,uGAGFT,EAAS,WAAW,iBAA8B,2BAA2B,EAAE,QAASqB,GAAS,CAC/FA,EAAK,iBAAiB,QAAUC,GAAM,CAEpC,GAAKA,EAAE,OAAuB,QAAQ,cAAc,EAClD,OAEF,IAAMC,EAAYF,EAAK,QAAQ,MAC3BE,GACFC,EAAcD,CAAS,CAE3B,CAAC,CACH,CAAC,EAGDvB,EAAS,WAAW,iBAAoC,4BAA4B,EAAE,QAASyB,GAAQ,CACrGA,EAAI,iBAAiB,QAAS,MAAOH,GAAM,CACzCA,EAAE,gBAAgB,EAClB,IAAMC,EAAYE,EAAI,QAAQ,QAC1BF,GAAa,QAAQ,kBAAkBA,CAAS,mCAAmC,GACrF,MAAMG,GAAaH,CAAS,CAEhC,CAAC,CACH,CAAC,EAGDI,GAAoB,CACtB,CAKO,SAASC,GAAuB,CACrC,IAAMC,EAAWC,EAAoB,EAErC,GAAID,EAAS,SAAW,EAAG,CACzB7B,EAAS,aAAa,UAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,YAQ1BK,EAAM,iBAAmB,UACrB,2CACA,iBAAiBA,EAAM,cAAc,mBAC3C;AAAA;AAAA;AAAA,MAIN,MACF,CAEA,IAAII,EAAO,GACPsB,EAA0B,KAE9BF,EAAS,QAASG,GAAQ,CACxB,IAAMC,EAAU,IAAI,KAAKD,EAAI,SAAS,EAAE,aAAa,EAGjDC,IAAYF,IACdtB,GAAQ;AAAA;AAAA,4CAE8ByB,EAAWF,EAAI,SAAS,CAAC;AAAA;AAAA,QAG/DD,EAAWE,GAGb,IAAME,EAAcH,EAAI,KAAO,IACzBI,EAAcjB,EAAea,EAAI,IAAI,EACrCK,EAAaC,EAAoBN,EAAI,EAAE,EAIvCO,EAAmBJ,EACrB,YACAH,EAAI,QACF,+BAA+Bd,EAAWc,EAAI,OAAO,CAAC,WAAWd,EAAWc,EAAI,EAAE,CAAC,GACnF,IAAId,EAAWc,EAAI,EAAE,CAAC,GAE5BvB,GAAQ;AAAA,4BACgB0B,EAAc,YAAc,EAAE,cAAcjB,EAAWc,EAAI,EAAE,CAAC;AAAA,yDACjCI,CAAW;AAAA,YACxDhB,EAAYY,EAAI,IAAI,CAAC;AAAA;AAAA;AAAA;AAAA,4CAIWd,EAAWc,EAAI,IAAI,CAAC;AAAA;AAAA,4CAEzBO,CAAgB;AAAA;AAAA,8CAETC,EAAWR,EAAI,SAAS,CAAC;AAAA;AAAA,sCAEjCS,EAAkBT,EAAI,OAAO,CAAC;AAAA,YAExDA,EAAI,OACA;AAAA,yDACyCd,EAAWc,EAAI,MAAM,CAAC;AAAA;AAAA;AAAA;AAAA,wBAIvDd,EAAWc,EAAI,MAAM,CAAC;AAAA;AAAA,YAG9B,EACN;AAAA,YAEEK,EAAa,EACT;AAAA,0DAC0CnB,EAAWc,EAAI,EAAE,CAAC;AAAA;AAAA;AAAA;AAAA,gBAI5DK,CAAU,IAAIA,IAAe,EAAI,QAAU,SAAS;AAAA;AAAA,YAGpD,EACN;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,KAmBR,CAAC,EAEDrC,EAAS,aAAa,UAAYS,EAKlCiC,GAAqB,CACvB,CAKO,SAASlB,EAAcmB,EAA4B,CACxDC,EAAkBD,CAAO,EAGzB3C,EAAS,aAAa,iBAA8B,eAAe,EAAE,QAASqB,GAAS,CACrFA,EAAK,UAAU,OAAO,SAAUA,EAAK,QAAQ,UAAYsB,CAAO,CAClE,CAAC,EACD3C,EAAS,WAAW,iBAA8B,eAAe,EAAE,QAASqB,GAAS,CACnFA,EAAK,UAAU,OAAO,SAAUA,EAAK,QAAQ,QAAUsB,CAAO,CAChE,CAAC,EAGD,IAAME,EAAW,SAAS,cAAc,8BAA8B,EACtE,GAAIF,IAAY,UACd3C,EAAS,mBAAmB,UAAY,UACxCA,EAAS,aAAa,YAAc,2BAChC6C,IAAUA,EAAS,YAAc,SAChC,CACL7C,EAAS,mBAAmB,UAAYkB,EAAWyB,CAAO,EAC1D,IAAMjC,EAAQL,EAAM,OAAO,KAAME,GAAMA,EAAE,OAASoC,CAAO,EACzD3C,EAAS,aAAa,YAAcU,GAAO,QAAU,kBACjDmC,IAAUA,EAAS,YAAc,IACvC,CAGA7C,EAAS,aAAa,YACpB2C,IAAY,UACR,6CACA,WAAWA,CAAO,uBAGxBf,EAAe,CACjB,CAKO,SAASkB,IAA0B,CACxC,IAAMC,EAAS1C,EAAM,OAAO,OAAQE,GAAMK,EAAcL,EAAE,UAAYA,EAAE,UAAU,CAAC,EAAE,OACrFP,EAAS,YAAY,YAAc,GAAG+C,CAAM,SAC9C,CAKO,SAASpB,IAA4B,CAC1C,IAAMlB,EAAOJ,EAAM,OAChB,IAAKK,GAAU,CACd,IAAMqC,EAASnC,EAAcF,EAAM,UAAYA,EAAM,UAAU,EAC/D,MAAO;AAAA,mDACsCQ,EAAWR,EAAM,IAAI,CAAC;AAAA;AAAA,yDAEhBS,EAAeT,EAAM,IAAI,CAAC;AAAA,cACrEU,EAAYV,EAAM,IAAI,CAAC;AAAA,8CACSqC,EAAS,SAAW,EAAE;AAAA;AAAA;AAAA;AAAA,4CAIxB7B,EAAWR,EAAM,IAAI,CAAC;AAAA,+CACnBqC,EAAS,SAAW,SAAS;AAAA;AAAA;AAAA,KAIxE,CAAC,EACA,KAAK,EAAE,EAEJC,EAAUhD,EAAS,qBACXgD,EAAQ,iBAAiB,eAAe,EAChD,QAAS3B,GAASA,EAAK,OAAO,CAAC,EACrC2B,EAAQ,mBAAmB,YAAavC,CAAI,EAG5CuC,EAAQ,iBAA8B,gCAAgC,EAAE,QAAS3B,GAAS,CACxFA,EAAK,iBAAiB,QAAS,IAAM,CACnC,IAAME,EAAYF,EAAK,QAAQ,UAC3BE,IACFC,EAAcD,CAAS,EACvB0B,EAAoB,EAExB,CAAC,CACH,CAAC,CACH,CAKO,SAASC,IAA4B,CAC1ClD,EAAS,uBACN,iBAA8B,kCAAkC,EAChE,QAASqB,GAAS,CACjBA,EAAK,iBAAiB,QAAS,IAAM,CACnC,IAAM8B,EAAc9B,EAAK,QAAQ,YAC7B8B,IACF3B,EAAc2B,CAAW,EACzBF,EAAoB,EAExB,CAAC,CACH,CAAC,CACL,CAKO,SAASG,GAA2B,CACzCpD,EAAS,sBAAsB,UAAU,IAAI,SAAS,EACtDA,EAAS,cAAc,MAAQ,GAC/BA,EAAS,cAAc,MAAM,EAC7BC,EAAuB,GACvBoD,EAAqB,EAAE,CACzB,CAKO,SAASC,IAAwC,CAItD,OAHiB,MAAM,KACrBtD,EAAS,eAAe,iBAA8B,eAAe,CACvE,EACgB,OAAQqB,GAASA,EAAK,MAAM,UAAY,MAAM,CAChE,CAKO,SAASkC,GAA+B,CAC7C,IAAMC,EAAQF,GAAuB,EAMrC,GAHAE,EAAM,QAASnC,GAASA,EAAK,UAAU,OAAO,UAAU,CAAC,EAGrDpB,GAAwB,GAAKA,EAAuBuD,EAAM,OAAQ,CACpE,IAAMC,EAAeD,EAAMvD,CAAoB,EAC/CwD,EAAa,UAAU,IAAI,UAAU,EAGrCA,EAAa,eAAe,CAAE,MAAO,UAAW,SAAU,QAAS,CAAC,CACtE,CACF,CAKO,SAASC,GAAqBpC,EAAwB,CAC3D,IAAMkC,EAAQF,GAAuB,EAErC,GAAIE,EAAM,SAAW,EAErB,OAAQlC,EAAE,IAAK,CACb,IAAK,YACHA,EAAE,eAAe,EACjBrB,EAAuBA,EAAuBuD,EAAM,OAAS,EACzDvD,EAAuB,EACvB,EACJsD,EAAuB,EACvB,MAEF,IAAK,UACHjC,EAAE,eAAe,EACjBrB,EAAuBA,EAAuB,EAC1CA,EAAuB,EACvBuD,EAAM,OAAS,EACnBD,EAAuB,EACvB,MAEF,IAAK,QACHjC,EAAE,eAAe,EACbrB,GAAwB,GAAKA,EAAuBuD,EAAM,QAC5DG,GAAmBH,EAAMvD,CAAoB,CAAC,EAEhD,KACJ,CACF,CAKO,SAAS0D,GAAmBtC,EAAyB,CAE1D,IAAMuC,EAAUvC,EAAK,QAAQ,QAC7B,GAAIuC,EAAS,CACPA,IAAY,aAEd5D,EAAS,aAAa,MAAQ,MAC9BA,EAAS,aAAa,MAAM,GACnB4D,IAAY,UACrB5D,EAAS,aAAa,UAAY,IAEpCiD,EAAoB,EACpB,MACF,CAGA,IAAMN,EAAUtB,EAAK,QAAQ,YAC7B,GAAIsB,EAAS,CACXnB,EAAcmB,CAAO,EACrBM,EAAoB,EACpB,MACF,CAGA,IAAMvC,EAAQW,EAAK,QAAQ,UAC3B,GAAIX,EAAO,CACTc,EAAcd,CAAK,EACnBuC,EAAoB,EACpB,MACF,CAGA,IAAMY,EAAYxC,EAAK,QAAQ,YAC/B,GAAIwC,EAAW,CAEb,IAAMC,EAAY9D,EAAS,aAAa,cAAc,aAAa6D,CAAS,IAAI,EAC5EC,IACFA,EAAU,eAAe,CAAE,SAAU,SAAU,MAAO,QAAS,CAAC,EAChEA,EAAU,UAAU,IAAI,aAAa,EACrC,WAAW,IAAMA,EAAU,UAAU,OAAO,aAAa,EAAG,GAAI,GAElEb,EAAoB,EACpB,MACF,CACF,CAKO,SAASA,GAA4B,CAC1CjD,EAAS,sBAAsB,UAAU,OAAO,SAAS,CAC3D,CAKO,SAASqD,EAAqBU,EAAqB,CACxD,IAAMC,EAAID,EAAM,YAAY,EA0B5B,GAvBA9D,EAAuB,GAGvB,SAAS,iBAA8B,6BAA6B,EAAE,QAASoB,GAAS,CAEtF,IAAM4C,EADU5C,EAAK,cAAc,qBAAqB,GACjC,aAAa,YAAY,GAAK,GACrDA,EAAK,MAAM,QAAU4C,EAAM,SAASD,CAAC,EAAI,OAAS,MACpD,CAAC,EAGD,SAAS,iBAA8B,kCAAkC,EAAE,QAAS3C,GAAS,CAE3F,IAAM4C,EADU5C,EAAK,cAAc,qBAAqB,GACjC,aAAa,YAAY,GAAK,GACrDA,EAAK,MAAM,QAAU4C,EAAM,SAASD,CAAC,EAAI,OAAS,MACpD,CAAC,EAGD,SAAS,iBAA8B,gCAAgC,EAAE,QAAS3C,GAAS,CACzF,IAAM6C,EAAO7C,EAAK,QAAQ,WAAW,YAAY,GAAK,GACtDA,EAAK,MAAM,QAAU6C,EAAK,SAASF,CAAC,EAAI,OAAS,MACnD,CAAC,EAGGA,EAAE,QAAU,EAAG,CACjB,IAAMG,EAAU9D,EAAM,SAAS,OAAQ+D,GAAMA,EAAE,QAAQ,YAAY,EAAE,SAASJ,CAAC,CAAC,EAAE,MAAM,EAAG,CAAC,EAE5F,GAAIG,EAAQ,OAAS,EAAG,CACtBnE,EAAS,uBAAuB,MAAM,QAAU,QAChD,IAAMwD,EAAQW,EACX,IACEC,GAAM;AAAA,uDACsClD,EAAWkD,EAAE,EAAE,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,8CAOzBlD,EAAWkD,EAAE,IAAI,CAAC;AAAA,iDACflD,EAAWkD,EAAE,QAAQ,UAAU,EAAG,EAAE,CAAC,CAAC,GAAGA,EAAE,QAAQ,OAAS,GAAK,MAAQ,EAAE;AAAA;AAAA;AAAA,OAIpH,EACC,KAAK,EAAE,EAEYpE,EAAS,uBAAuB,iBAAiB,eAAe,EACxE,QAASqB,GAASA,EAAK,OAAO,CAAC,EAC7CrB,EAAS,uBAAuB,mBAAmB,YAAawD,CAAK,CACvE,MACExD,EAAS,uBAAuB,MAAM,QAAU,MAEpD,MACEA,EAAS,uBAAuB,MAAM,QAAU,MAEpD,CAKO,SAASqE,EAAgBC,EAAwB,CACtDC,EAAiBD,CAAQ,EACzBtE,EAAS,cAAc,YAAcsE,EACrCtE,EAAS,mBAAmB,UAAU,IAAI,SAAS,EACnDA,EAAS,mBAAmB,MAAQ,GACpCwE,EAAqBF,CAAQ,EAC7BtE,EAAS,mBAAmB,MAAM,CACpC,CAKO,SAASyE,GAAyB,CACvCF,EAAiB,IAAI,EACrBvE,EAAS,mBAAmB,UAAU,OAAO,SAAS,CACxD,CAKO,SAASwE,EAAqBF,EAAwB,CAC3D,IAAMI,EAAWC,EAAkBL,CAAQ,EAE3C,GAAII,EAAS,SAAW,EAAG,CACzB1E,EAAS,eAAe,UAAY;AAAA;AAAA;AAAA;AAAA;AAAA,MAMpC,MACF,CAEA,IAAMS,EAAOiE,EACV,IAAK1C,GAAQ;AAAA;AAAA;AAAA,kEAGgDb,EAAea,EAAI,IAAI,CAAC;AAAA,cAC5EZ,EAAYY,EAAI,IAAI,CAAC;AAAA;AAAA,gDAEad,EAAWc,EAAI,IAAI,CAAC;AAAA,8CACtBQ,EAAWR,EAAI,SAAS,CAAC;AAAA;AAAA,2CAE5BS,EAAkBT,EAAI,OAAO,CAAC;AAAA;AAAA,KAEpE,EACA,KAAK,EAAE,EAEVhC,EAAS,eAAe,UAAYS,EAGpCT,EAAS,eAAe,UAAYA,EAAS,eAAe,YAC9D,CAKO,SAAS0C,IAA6B,CAE3C1C,EAAS,aAAa,iBAA8B,mBAAmB,EAAE,QAAS4E,GAAO,CACvFA,EAAG,MAAM,OAAS,UAClBA,EAAG,iBAAiB,QAAU,GAAM,CAClC,EAAE,gBAAgB,EAClB,IAAMN,EAAWM,EAAG,QAAQ,OACxBN,GACFD,EAAgBC,CAAQ,CAE5B,CAAC,CACH,CAAC,EAGDtE,EAAS,aAAa,iBAA8B,oBAAoB,EAAE,QAAS4E,GAAO,CACxFA,EAAG,iBAAiB,QAAU,GAAM,CAClC,EAAE,gBAAgB,EAClB,IAAMN,EAAWM,EAAG,QAAQ,OACxBN,GACFD,EAAgBC,CAAQ,CAE5B,CAAC,CACH,CAAC,EAGDtE,EAAS,aAAa,iBAA8B,0CAA0C,EAAE,QAAS4E,GAAO,CAC9GA,EAAG,iBAAiB,QAAU,GAAM,CAClC,EAAE,gBAAgB,EAClB,IAAMf,EAAYe,EAAG,QAAQ,UAAU,GAAG,aAAa,SAAS,EAC5Df,GAEFQ,EAAgBR,CAAS,CAE7B,CAAC,CACH,CAAC,CACH,CAKA,IAAIgB,EAAuB,EACvBC,EAA6C,CAAC,EAK3C,SAASC,GAAwBC,EAAsB,CAC5D,IAAMC,EAAcD,EAAO,YAAY,EAGvCF,EAAwBzE,EAAM,OAAO,OAAOK,GAC1CA,EAAM,KAAK,YAAY,EAAE,SAASuE,CAAW,CAC/C,EAGAJ,EAAuB,EAGvB,IAAIpE,EAAO,IAGP,IAAI,SAASwE,CAAW,GAAK,WAAW,SAASA,CAAW,GAAK,MAAM,SAASA,CAAW,GAAK,YAAY,SAASA,CAAW,KAClIxE,GAAQ;AAAA,8CACkCoE,IAAyB,GAAKC,EAAsB,SAAW,EAAI,WAAa,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA,OAS9HA,EAAsB,QAAQ,CAACpE,EAAOwE,IAAU,CAE9CzE,GAAQ;AAAA,8CADWyE,IAAUL,EAE0B,WAAa,EAAE,mBAAmB3D,EAAWR,EAAM,IAAI,CAAC;AAAA,uDAC5DS,EAAeT,EAAM,IAAI,CAAC;AAAA,YACrEU,EAAYV,EAAM,IAAI,CAAC;AAAA;AAAA,mDAEgBQ,EAAWR,EAAM,IAAI,CAAC;AAAA,kDACvBQ,EAAWR,EAAM,MAAQ,OAAO,CAAC;AAAA;AAAA,KAGjF,CAAC,EAEGD,IAAS,KACXA,EAAO,sHAGTT,EAAS,wBAAwB,UAAYS,EAC7CT,EAAS,oBAAoB,UAAU,IAAI,SAAS,EAGpDA,EAAS,wBAAwB,iBAA8B,0CAA0C,EAAE,QAASqB,GAAS,CAC3HA,EAAK,iBAAiB,QAAS,IAAM,CACnC,IAAM8D,EAAU9D,EAAK,QAAQ,QACzB8D,GACFC,EAAgBD,CAAO,CAE3B,CAAC,CACH,CAAC,CACH,CAKO,SAASE,GAAgC,CAC9CrF,EAAS,oBAAoB,UAAU,OAAO,SAAS,EACvD8E,EAAwB,CAAC,EACzBD,EAAuB,CACzB,CAKO,SAASS,IAAwC,CACtD,OAAOtF,EAAS,oBAAoB,UAAU,SAAS,SAAS,CAClE,CAKO,SAASuF,EAA4BC,EAAgC,CAC1E,IAAMhC,EAAQxD,EAAS,wBAAwB,iBAA8B,0CAA0C,EACnHwD,EAAM,SAAW,IAGrBA,EAAMqB,CAAoB,GAAG,UAAU,OAAO,UAAU,EAGpDW,IAAc,OAChBX,GAAwBA,EAAuB,GAAKrB,EAAM,OAE1DqB,GAAwBA,EAAuB,EAAIrB,EAAM,QAAUA,EAAM,OAI3EA,EAAMqB,CAAoB,GAAG,UAAU,IAAI,UAAU,EACrDrB,EAAMqB,CAAoB,GAAG,eAAe,CAAE,MAAO,SAAU,CAAC,EAClE,CAKO,SAASO,EAAgBD,EAAwB,CACtD,IAAM3B,EAAQxD,EAAS,wBAAwB,iBAA8B,0CAA0C,EAGnHyF,EAAkBN,EAKtB,GAJI,CAACM,GAAmBjC,EAAM,OAAS,IACrCiC,EAAkBjC,EAAMqB,CAAoB,GAAG,QAAQ,SAGrD,CAACY,EAAiB,CACpBJ,EAAwB,EACxB,MACF,CAGA,IAAMK,EAAQ1F,EAAS,aACjB2F,EAAQD,EAAM,MAGdE,EAAUD,EAAM,MAAM,OAAO,EACnC,GAAIC,EAAS,CAEX,IAAMC,EAAgB,IAAIJ,CAAe,IACzCC,EAAM,MAAQG,EAAgBF,EAAM,UAAUC,EAAQ,CAAC,EAAE,MAAM,EAC/DF,EAAM,eAAiBA,EAAM,aAAeG,EAAc,MAC5D,CAEAR,EAAwB,EACxBK,EAAM,MAAM,CACd,CAKO,SAASI,IAAwC,CACtD,IAAMJ,EAAQ1F,EAAS,aACjB2F,EAAQD,EAAM,MACdK,EAAYL,EAAM,eAGlBE,EAAUD,EAAM,MAAM,SAAS,EACrC,OAAIC,GAAWG,GAAaH,EAAQ,CAAC,EAAE,OAC9BA,EAAQ,CAAC,EAGX,IACT,CASO,SAASI,IAAuB,CACrChG,EAAS,kBAAkB,UAAU,IAAI,SAAS,EAClDA,EAAS,eAAe,MAAQ,GAChCA,EAAS,cAAc,MAAQ,SAC/BA,EAAS,eAAe,MAAQ,GAChCA,EAAS,YAAY,YAAc,GACnCA,EAAS,YAAY,UAAY,eACjCA,EAAS,eAAe,MAAM,CAChC,CAKO,SAASiG,GAAwB,CACtCjG,EAAS,kBAAkB,UAAU,OAAO,SAAS,CACvD,CAKA,eAAsBkG,GAA4D,CAChF,IAAMhC,EAAOlE,EAAS,eAAe,MAAM,KAAK,EAC1CmG,EAAMnG,EAAS,cAAc,MAAM,KAAK,GAAK,SAC7CoG,EAAOpG,EAAS,eAAe,MAAM,KAAK,EAEhD,GAAI,CAACkE,EACH,OAAAlE,EAAS,YAAY,YAAc,yBACnCA,EAAS,YAAY,UAAY,qBAC1B,CAAE,QAAS,GAAO,MAAO,wBAAyB,EAG3DA,EAAS,eAAe,SAAW,GACnCA,EAAS,YAAY,YAAc,oBACnCA,EAAS,YAAY,UAAY,uBAEjC,GAAI,CACF,IAAMqG,EAAW,MAAM,MAAM,aAAc,CACzC,OAAQ,OACR,QAAS,CAAE,eAAgB,kBAAmB,EAC9C,KAAM,KAAK,UAAU,CAAE,KAAAnC,EAAM,IAAAiC,EAAK,KAAAC,CAAK,CAAC,CAC1C,CAAC,EAEKE,EAAS,MAAMD,EAAS,KAAK,EAEnC,GAAIA,EAAS,IAAMC,EAAO,QACxB,OAAAtG,EAAS,YAAY,YAAc,UAAUkE,CAAI,0BACjDlE,EAAS,YAAY,UAAY,uBAGjC,MAAMuG,EAAmB,EAGzB,WAAW,IAAM,CACfN,EAAgB,CAClB,EAAG,GAAI,EAEA,CAAE,QAAS,EAAK,EAEvB,MAAM,IAAI,MAAMK,EAAO,OAAS,uBAAuB,CAE3D,OAASE,EAAU,CACjB,OAAAxG,EAAS,YAAY,YAAcwG,EAAI,SAAW,wBAClDxG,EAAS,YAAY,UAAY,qBAC1B,CAAE,QAAS,GAAO,MAAOwG,EAAI,OAAQ,CAC9C,QAAE,CACAxG,EAAS,eAAe,SAAW,EACrC,CACF,CAKA,eAAsBuG,GAAoC,CACxD,GAAI,CAEF,IAAMD,EAAS,MADE,MAAM,MAAM,cAAc,GACb,KAAK,EAE/BA,EAAO,SAAW,MAAM,QAAQA,EAAO,MAAM,IAC/CvG,GAAgBuG,EAAO,OAEvBhG,EAAa,EAEjB,OAASkG,EAAK,CACZ,QAAQ,MAAM,uCAAwCA,CAAG,CAC3D,CACF,CAKA,eAAsB9E,GAAawC,EAA6B,CAC9D,GAAI,CAKF,IAAMoC,EAAS,MAJE,MAAM,MAAM,gBAAgB,mBAAmBpC,CAAI,CAAC,GAAI,CACvE,OAAQ,QACV,CAAC,GAE6B,KAAK,EAE/BoC,EAAO,QAET,MAAMC,EAAmB,EAEzB,QAAQ,MAAM,gCAAiCD,EAAO,KAAK,CAE/D,OAASE,EAAK,CACZ,QAAQ,MAAM,gCAAiCA,CAAG,CACpD,CACF,CCh5BO,SAASC,IAAgB,CAC9B,IAAMC,EAAWC,GAAa,EAG9BC,EAAU,IAAM,CACdC,GAAuB,EACvBC,EAAa,EACbC,EAAe,EACfC,GAAkB,CACpB,CAAC,EAGDC,GAAoBP,CAAQ,EAG5BQ,EAAQ,EAGRC,EAAmB,CACrB,CAKA,SAASF,GAAoBP,EAAgD,CAE3EA,EAAS,aAAa,iBAA8B,eAAe,EAAE,QAASU,GAAS,CACrFA,EAAK,iBAAiB,QAAS,IAAM,CACnC,IAAMC,EAAUD,EAAK,QAAQ,QACzBC,GACFC,EAAcD,CAAO,CAEzB,CAAC,CACH,CAAC,EAGDX,EAAS,QAAQ,iBAAiB,QAASa,EAAU,EAGrDb,EAAS,aAAa,iBAAiB,UAAY,GAAqB,CAEtE,GAAIc,GAA6B,EAAG,CAClC,GAAI,EAAE,MAAQ,OAAS,EAAE,MAAQ,QAAS,CACxC,EAAE,eAAe,EACjBC,EAAgB,EAChB,MACF,CACA,GAAI,EAAE,MAAQ,UAAW,CACvB,EAAE,eAAe,EACjBC,EAA4B,IAAI,EAChC,MACF,CACA,GAAI,EAAE,MAAQ,YAAa,CACzB,EAAE,eAAe,EACjBA,EAA4B,MAAM,EAClC,MACF,CACA,GAAI,EAAE,MAAQ,SAAU,CACtB,EAAE,eAAe,EACjBC,EAAwB,EACxB,MACF,CACF,CAGI,EAAE,MAAQ,SAAW,CAAC,EAAE,WAC1B,EAAE,eAAe,EACjBJ,GAAW,EAGf,CAAC,EAGDb,EAAS,aAAa,iBAAiB,QAAS,IAAM,CACpDA,EAAS,aAAa,MAAM,OAAS,OACrCA,EAAS,aAAa,MAAM,OAC1B,KAAK,IAAIA,EAAS,aAAa,aAAc,GAAG,EAAI,KAGtD,IAAMkB,EAAQC,GAAuB,EACjCD,IAAU,KACZE,GAAwBF,CAAK,EAE7BD,EAAwB,CAE5B,CAAC,EAGDjB,EAAS,aAAa,iBAAiB,OAAQ,IAAM,CACnD,WAAW,IAAM,CACfiB,EAAwB,CAC1B,EAAG,GAAG,CACR,CAAC,EAGDjB,EAAS,QAAQ,iBAAiB,QAAS,IAAM,CAC/C,IAAMqB,EAAQrB,EAAS,aACjBsB,EAAQD,EAAM,eACdE,EAAMF,EAAM,aACZG,EAAOH,EAAM,MAEnB,GAAIC,IAAUC,EAAK,CAEjB,IAAME,EAASD,EAAK,UAAU,EAAGF,CAAK,EAChCI,EAAQF,EAAK,UAAUD,CAAG,EAChCF,EAAM,MAAQI,EAAS,WAAaC,EACpCL,EAAM,eAAiBC,EAAQ,EAC/BD,EAAM,aAAeC,EAAQ,CAC/B,KAAO,CAEL,IAAMG,EAASD,EAAK,UAAU,EAAGF,CAAK,EAChCK,EAAWH,EAAK,UAAUF,EAAOC,CAAG,EACpCG,EAAQF,EAAK,UAAUD,CAAG,EAChCF,EAAM,MAAQI,EAAS,KAAOE,EAAW,KAAOD,EAChDL,EAAM,eAAiBC,EACvBD,EAAM,aAAeE,EAAM,CAC7B,CACAF,EAAM,MAAM,CACd,CAAC,EAGDrB,EAAS,SAAS,iBAAiB,QAAS,IAAM,CAChD,IAAM4B,EAAS,CAAC,YAAM,YAAM,SAAK,SAAK,YAAM,YAAM,YAAM,eAAM,YAAM,WAAI,EAClEC,EAAQD,EAAO,KAAK,MAAM,KAAK,OAAO,EAAIA,EAAO,MAAM,CAAC,EACxDP,EAAQrB,EAAS,aACjBsB,EAAQD,EAAM,eACdG,EAAOH,EAAM,MACnBA,EAAM,MAAQG,EAAK,UAAU,EAAGF,CAAK,EAAIO,EAAQL,EAAK,UAAUF,CAAK,EACrED,EAAM,eAAiBA,EAAM,aAAeC,EAAQO,EAAM,OAC1DR,EAAM,MAAM,CACd,CAAC,EAGDrB,EAAS,cAAc,iBAAiB,QAAS8B,CAAkB,EAEnE,SAAS,iBAAiB,UAAY,GAAqB,EACpD,EAAE,SAAW,EAAE,UAAY,EAAE,MAAQ,MACxC,EAAE,eAAe,EACb9B,EAAS,sBAAsB,UAAU,SAAS,SAAS,EAC7D+B,EAAoB,EAEpBD,EAAmB,GAInB,EAAE,MAAQ,UACZC,EAAoB,CAExB,CAAC,EAED/B,EAAS,sBAAsB,iBAAiB,QAAU,GAAkB,CACtE,EAAE,SAAWA,EAAS,uBACxB+B,EAAoB,CAExB,CAAC,EAED/B,EAAS,cAAc,iBAAiB,QAAU,GAAa,CAC7D,IAAMgC,EAAS,EAAE,OACjBC,EAAqBD,EAAO,KAAK,CACnC,CAAC,EAEDhC,EAAS,cAAc,iBAAiB,UAAWkC,EAAoB,EAGvE,SAAS,iBAA8B,6BAA6B,EAAE,QAASxB,GAAS,CACtFA,EAAK,iBAAiB,QAAS,IAAM,CACnC,IAAMyB,EAAUzB,EAAK,QAAQ,QAEzByB,IAAY,aAEdnC,EAAS,aAAa,MAAQ,MAC9BA,EAAS,aAAa,MAAM,GACnBmC,IAAY,UACrBnC,EAAS,aAAa,UAAY,IAGpC+B,EAAoB,CACtB,CAAC,CACH,CAAC,EAGDK,GAAoB,EAGpBpC,EAAS,iBAAiB,iBAAiB,QAASqC,CAAgB,EAGpErC,EAAS,cAAc,iBAAiB,QAASsC,EAAgB,EAGjEtC,EAAS,mBAAmB,iBAAiB,UAAY,GAAqB,CACxE,EAAE,MAAQ,SAAW,CAAC,EAAE,WAC1B,EAAE,eAAe,EACjBsC,GAAiB,EAGrB,CAAC,EAGD,SAAS,iBAAiB,UAAY,GAAqB,CACrD,EAAE,MAAQ,UAAYtC,EAAS,mBAAmB,UAAU,SAAS,SAAS,GAChFqC,EAAiB,CAErB,CAAC,EAGDrC,EAAS,SAAS,iBAAiB,QAASuC,EAAc,EAE1DvC,EAAS,gBAAgB,iBAAiB,QAASwC,CAAe,EAGlE,SAAS,eAAe,kBAAkB,GAAG,iBAAiB,QAASA,CAAe,EAGtFxC,EAAS,kBAAkB,iBAAiB,QAAU,GAAkB,CAClE,EAAE,SAAWA,EAAS,mBACxBwC,EAAgB,CAEpB,CAAC,EAGD,SAAS,iBAAiB,UAAY,GAAqB,CACrD,EAAE,MAAQ,UAAYxC,EAAS,kBAAkB,UAAU,SAAS,SAAS,GAC/EwC,EAAgB,CAEpB,CAAC,EAGDxC,EAAS,eAAe,iBAAiB,QAASyC,CAAU,EAG5DzC,EAAS,eAAe,iBAAiB,UAAY,GAAqB,CACpE,EAAE,MAAQ,SAAW,CAAC,EAAE,WAC1B,EAAE,eAAe,EACjByC,EAAW,EAEf,CAAC,CACH,CAOA,SAASC,GAAalB,EAAsD,CAK1E,IAAMmB,EAJUnB,EAAK,KAAK,EAIJ,MAAM,wBAAwB,EAEpD,OAAKmB,EAIE,CACL,GAAIA,EAAM,CAAC,EACX,QAASA,EAAM,CAAC,EAAE,KAAK,CACzB,EANS,IAOX,CAKA,eAAe9B,IAA4B,CACzC,IAAMb,EAAW4C,EAAY,EACvBC,EAAa7C,EAAS,aAAa,MAAM,KAAK,EAEpD,GAAI,CAAC6C,EACH,OAGF,IAAIC,EACAC,EAGEC,EAASC,EAAM,iBAAmB,UAGlCC,EAASR,GAAaG,CAAU,EAEtC,GAAIK,EAEFJ,EAAKI,EAAO,GACZH,EAAUG,EAAO,gBACRF,EAETF,EAAKG,EAAM,eACXF,EAAUF,MACL,CAEL,MAAM,4EAA4E,EAClF,MACF,CAEA7C,EAAS,QAAQ,SAAW,GAE5B,IAAMmD,EAAS,MAAMC,EAAYN,EAAIC,CAAO,EAExCI,EAAO,SACTnD,EAAS,aAAa,MAAQ,GAC9BA,EAAS,aAAa,MAAM,OAAS,QAErC,MAAMmD,EAAO,KAAK,EAGpBnD,EAAS,QAAQ,SAAW,EAC9B,CAKA,eAAesC,IAAkC,CAC/C,IAAMtC,EAAW4C,EAAY,EACvBG,EAAU/C,EAAS,mBAAmB,MAAM,KAAK,EACjDqD,EAAWJ,EAAM,cAEvB,GAAI,CAACF,GAAW,CAACM,EACf,OAKFrD,EAAS,cAAc,SAAW,GAElC,IAAMmD,EAAS,MAAMC,EAAY,IAAKL,EAASM,CAAQ,EAEnDF,EAAO,SACTnD,EAAS,mBAAmB,MAAQ,GAEpCsD,EAAqBD,CAAQ,GAE7B,MAAMF,EAAO,KAAK,EAGpBnD,EAAS,cAAc,SAAW,EACpC,CAGI,OAAO,SAAa,MAClB,SAAS,aAAe,UAC1B,SAAS,iBAAiB,mBAAoBD,EAAO,EAErDA,GAAQ",
+  "names": ["state", "listeners", "subscribe", "listener", "index", "notifyListeners", "setAgents", "agents", "setMessages", "messages", "setCurrentChannel", "channel", "setConnectionStatus", "connected", "incrementReconnectAttempts", "setWebSocket", "ws", "getFilteredMessages", "currentChannel", "m", "setCurrentThread", "thread", "getThreadMessages", "threadId", "getThreadReplyCount", "dataHandler", "connect", "protocol", "ws", "setConnectionStatus", "delay", "state", "incrementReconnectAttempts", "error", "event", "data", "handleData", "e", "setWebSocket", "a", "setAgents", "setMessages", "dataHandler", "sendMessage", "to", "message", "thread", "body", "response", "result", "isAgentOnline", "lastSeen", "ts", "escapeHtml", "text", "div", "formatTime", "timestamp", "formatDate", "date", "today", "yesterday", "getAvatarColor", "name", "colors", "hash", "i", "getInitials", "formatMessageBody", "content", "escaped", "spawnedAgents", "elements", "paletteSelectedIndex", "initElements", "getElements", "updateConnectionStatus", "state", "renderAgents", "a", "spawnedNames", "html", "agent", "presenceClass", "isAgentOnline", "isActive", "needsAttentionClass", "isSpawned", "spawnedIcon", "releaseBtn", "escapeHtml", "getAvatarColor", "getInitials", "item", "e", "agentName", "selectChannel", "btn", "releaseAgent", "updatePaletteAgents", "renderMessages", "filtered", "getFilteredMessages", "lastDate", "msg", "msgDate", "formatDate", "isBroadcast", "avatarColor", "replyCount", "getThreadReplyCount", "recipientDisplay", "formatTime", "formatMessageBody", "attachThreadHandlers", "channel", "setCurrentChannel", "prefixEl", "updateOnlineCount", "online", "section", "closeCommandPalette", "initPaletteChannels", "channelName", "openCommandPalette", "filterPaletteResults", "getVisiblePaletteItems", "updatePaletteSelection", "items", "selectedItem", "handlePaletteKeydown", "executePaletteItem", "command", "messageId", "messageEl", "query", "q", "title", "name", "matches", "m", "openThreadPanel", "threadId", "setCurrentThread", "renderThreadMessages", "closeThreadPanel", "messages", "getThreadMessages", "el", "mentionSelectedIndex", "mentionFilteredAgents", "showMentionAutocomplete", "filter", "filterLower", "index", "mention", "completeMention", "hideMentionAutocomplete", "isMentionAutocompleteVisible", "navigateMentionAutocomplete", "direction", "selectedMention", "input", "value", "atMatch", "completedText", "getCurrentMentionQuery", "cursorPos", "openSpawnModal", "closeSpawnModal", "spawnAgent", "cli", "task", "response", "result", "fetchSpawnedAgents", "err", "initApp", "elements", "initElements", "subscribe", "updateConnectionStatus", "renderAgents", "renderMessages", "updateOnlineCount", "setupEventListeners", "connect", "fetchSpawnedAgents", "item", "channel", "selectChannel", "handleSend", "isMentionAutocompleteVisible", "completeMention", "navigateMentionAutocomplete", "hideMentionAutocomplete", "query", "getCurrentMentionQuery", "showMentionAutocomplete", "input", "start", "end", "text", "before", "after", "selected", "emojis", "emoji", "openCommandPalette", "closeCommandPalette", "target", "filterPaletteResults", "handlePaletteKeydown", "command", "initPaletteChannels", "closeThreadPanel", "handleThreadSend", "openSpawnModal", "closeSpawnModal", "spawnAgent", "parseMention", "match", "getElements", "rawMessage", "to", "message", "isInDM", "state", "parsed", "result", "sendMessage", "threadId", "renderThreadMessages"]
+}
diff --git a/src/dashboard/public/metrics.html b/src/dashboard/public/metrics.html
new file mode 100644
index 000000000..3572bb596
--- /dev/null
+++ b/src/dashboard/public/metrics.html
@@ -0,0 +1,999 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Metrics | Agent Relay</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600;700&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <style>
+    :root {
+      --bg-deep: #0a0c0f;
+      --bg-panel: #0f1318;
+      --bg-card: #141a21;
+      --bg-elevated: #1a2129;
+
+      --border-dim: rgba(255, 255, 255, 0.06);
+      --border-subtle: rgba(255, 255, 255, 0.1);
+      --border-glow: rgba(0, 255, 200, 0.3);
+
+      --text-primary: #e8eaed;
+      --text-secondary: #9aa0a6;
+      --text-muted: #5f6368;
+
+      --accent-cyan: #00ffc8;
+      --accent-blue: #4a9eff;
+      --accent-purple: #b388ff;
+      --accent-orange: #ff9e40;
+      --accent-red: #ff5c5c;
+      --accent-green: #00e676;
+
+      --glow-cyan: 0 0 20px rgba(0, 255, 200, 0.3);
+      --glow-green: 0 0 15px rgba(0, 230, 118, 0.4);
+      --glow-red: 0 0 15px rgba(255, 92, 92, 0.4);
+
+      --font-display: 'Space Grotesk', sans-serif;
+      --font-mono: 'IBM Plex Mono', monospace;
+    }
+
+    *, *::before, *::after {
+      box-sizing: border-box;
+      margin: 0;
+      padding: 0;
+    }
+
+    html, body {
+      height: 100%;
+      overflow-x: hidden;
+    }
+
+    body {
+      font-family: var(--font-display);
+      background: var(--bg-deep);
+      color: var(--text-primary);
+      line-height: 1.5;
+      -webkit-font-smoothing: antialiased;
+    }
+
+    /* Subtle grid background */
+    body::before {
+      content: '';
+      position: fixed;
+      inset: 0;
+      background-image:
+        linear-gradient(rgba(0, 255, 200, 0.02) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(0, 255, 200, 0.02) 1px, transparent 1px);
+      background-size: 40px 40px;
+      pointer-events: none;
+      z-index: 0;
+    }
+
+    /* Header */
+    .header {
+      position: sticky;
+      top: 0;
+      z-index: 100;
+      background: linear-gradient(to bottom, var(--bg-deep) 0%, transparent 100%);
+      padding: 24px 32px 48px;
+    }
+
+    .header-content {
+      max-width: 1400px;
+      margin: 0 auto;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+    }
+
+    .header-left {
+      display: flex;
+      align-items: center;
+      gap: 16px;
+    }
+
+    .back-link {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      color: var(--text-secondary);
+      text-decoration: none;
+      font-size: 14px;
+      font-weight: 500;
+      padding: 8px 12px;
+      border-radius: 6px;
+      transition: all 0.2s;
+    }
+
+    .back-link:hover {
+      color: var(--accent-cyan);
+      background: rgba(0, 255, 200, 0.1);
+    }
+
+    .logo {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+    }
+
+    .logo-icon {
+      width: 32px;
+      height: 32px;
+      background: linear-gradient(135deg, var(--accent-cyan), var(--accent-blue));
+      border-radius: 8px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+
+    .logo-text {
+      font-size: 20px;
+      font-weight: 700;
+      letter-spacing: -0.5px;
+    }
+
+    .logo-text span {
+      color: var(--accent-cyan);
+    }
+
+    .live-indicator {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 6px 12px;
+      background: rgba(0, 230, 118, 0.1);
+      border: 1px solid rgba(0, 230, 118, 0.3);
+      border-radius: 20px;
+      font-family: var(--font-mono);
+      font-size: 12px;
+      font-weight: 500;
+      color: var(--accent-green);
+    }
+
+    .live-dot {
+      width: 8px;
+      height: 8px;
+      background: var(--accent-green);
+      border-radius: 50%;
+      animation: pulse 2s ease-in-out infinite;
+      box-shadow: var(--glow-green);
+    }
+
+    @keyframes pulse {
+      0%, 100% { opacity: 1; transform: scale(1); }
+      50% { opacity: 0.5; transform: scale(0.9); }
+    }
+
+    /* Main content */
+    .main {
+      position: relative;
+      z-index: 1;
+      max-width: 1400px;
+      margin: 0 auto;
+      padding: 0 32px 48px;
+    }
+
+    /* Stats overview */
+    .stats-grid {
+      display: grid;
+      grid-template-columns: repeat(4, 1fr);
+      gap: 20px;
+      margin-bottom: 32px;
+    }
+
+    .stat-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border-dim);
+      border-radius: 12px;
+      padding: 24px;
+      position: relative;
+      overflow: hidden;
+      transition: all 0.3s ease;
+    }
+
+    .stat-card::before {
+      content: '';
+      position: absolute;
+      top: 0;
+      left: 0;
+      right: 0;
+      height: 2px;
+      background: linear-gradient(90deg, transparent, var(--accent-cyan), transparent);
+      opacity: 0;
+      transition: opacity 0.3s;
+    }
+
+    .stat-card:hover {
+      border-color: var(--border-glow);
+      transform: translateY(-2px);
+    }
+
+    .stat-card:hover::before {
+      opacity: 1;
+    }
+
+    .stat-label {
+      font-size: 12px;
+      font-weight: 500;
+      text-transform: uppercase;
+      letter-spacing: 1px;
+      color: var(--text-muted);
+      margin-bottom: 8px;
+    }
+
+    .stat-value {
+      font-family: var(--font-mono);
+      font-size: 36px;
+      font-weight: 700;
+      color: var(--text-primary);
+      line-height: 1;
+    }
+
+    .stat-value.accent-cyan { color: var(--accent-cyan); }
+    .stat-value.accent-green { color: var(--accent-green); }
+    .stat-value.accent-orange { color: var(--accent-orange); }
+    .stat-value.accent-blue { color: var(--accent-blue); }
+
+    .stat-subtext {
+      font-size: 13px;
+      color: var(--text-secondary);
+      margin-top: 8px;
+      font-family: var(--font-mono);
+    }
+
+    /* Sections */
+    .section {
+      margin-bottom: 32px;
+    }
+
+    .section-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      margin-bottom: 16px;
+    }
+
+    .section-title {
+      font-size: 14px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 1.5px;
+      color: var(--text-secondary);
+      display: flex;
+      align-items: center;
+      gap: 10px;
+    }
+
+    .section-title::before {
+      content: '';
+      width: 3px;
+      height: 16px;
+      background: var(--accent-cyan);
+      border-radius: 2px;
+    }
+
+    /* Throughput panel */
+    .throughput-panel {
+      background: var(--bg-card);
+      border: 1px solid var(--border-dim);
+      border-radius: 12px;
+      padding: 28px;
+    }
+
+    .throughput-grid {
+      display: grid;
+      grid-template-columns: repeat(4, 1fr);
+      gap: 32px;
+    }
+
+    .throughput-item {
+      text-align: center;
+    }
+
+    .throughput-value {
+      font-family: var(--font-mono);
+      font-size: 48px;
+      font-weight: 700;
+      color: var(--accent-cyan);
+      line-height: 1;
+      text-shadow: var(--glow-cyan);
+    }
+
+    .throughput-label {
+      font-size: 13px;
+      color: var(--text-secondary);
+      margin-top: 8px;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+    }
+
+    .throughput-bar {
+      height: 4px;
+      background: var(--bg-elevated);
+      border-radius: 2px;
+      margin-top: 12px;
+      overflow: hidden;
+    }
+
+    .throughput-bar-fill {
+      height: 100%;
+      background: linear-gradient(90deg, var(--accent-cyan), var(--accent-blue));
+      border-radius: 2px;
+      transition: width 0.5s ease;
+    }
+
+    /* Agent table */
+    .agents-table-container {
+      background: var(--bg-card);
+      border: 1px solid var(--border-dim);
+      border-radius: 12px;
+      overflow: hidden;
+    }
+
+    .agents-table {
+      width: 100%;
+      border-collapse: collapse;
+    }
+
+    .agents-table th,
+    .agents-table td {
+      padding: 16px 20px;
+      text-align: left;
+    }
+
+    .agents-table th {
+      background: var(--bg-elevated);
+      font-size: 11px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 1px;
+      color: var(--text-muted);
+      border-bottom: 1px solid var(--border-dim);
+    }
+
+    .agents-table tr {
+      border-bottom: 1px solid var(--border-dim);
+      transition: background 0.2s;
+    }
+
+    .agents-table tr:last-child {
+      border-bottom: none;
+    }
+
+    .agents-table tr:hover {
+      background: rgba(0, 255, 200, 0.02);
+    }
+
+    .agent-name {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+    }
+
+    .agent-avatar {
+      width: 32px;
+      height: 32px;
+      border-radius: 6px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-weight: 600;
+      font-size: 12px;
+      color: white;
+    }
+
+    .agent-name-text {
+      font-weight: 600;
+      font-family: var(--font-mono);
+    }
+
+    .status-badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 10px;
+      border-radius: 12px;
+      font-size: 12px;
+      font-weight: 500;
+    }
+
+    .status-badge.online {
+      background: rgba(0, 230, 118, 0.15);
+      color: var(--accent-green);
+    }
+
+    .status-badge.offline {
+      background: rgba(255, 92, 92, 0.15);
+      color: var(--accent-red);
+    }
+
+    .status-badge::before {
+      content: '';
+      width: 6px;
+      height: 6px;
+      border-radius: 50%;
+      background: currentColor;
+    }
+
+    .metric-cell {
+      font-family: var(--font-mono);
+      font-size: 14px;
+    }
+
+    .metric-cell.sent {
+      color: var(--accent-blue);
+    }
+
+    .metric-cell.received {
+      color: var(--accent-purple);
+    }
+
+    .uptime-cell {
+      font-family: var(--font-mono);
+      font-size: 13px;
+      color: var(--text-secondary);
+    }
+
+    /* Session lifecycle panel */
+    .lifecycle-panel {
+      background: var(--bg-card);
+      border: 1px solid var(--border-dim);
+      border-radius: 12px;
+      padding: 28px;
+    }
+
+    .lifecycle-grid {
+      display: grid;
+      grid-template-columns: repeat(5, 1fr);
+      gap: 24px;
+    }
+
+    .lifecycle-item {
+      text-align: center;
+    }
+
+    .lifecycle-value {
+      font-family: var(--font-mono);
+      font-size: 36px;
+      font-weight: 700;
+      line-height: 1;
+    }
+
+    .lifecycle-value.accent-green { color: var(--accent-green); }
+    .lifecycle-value.accent-blue { color: var(--accent-blue); }
+    .lifecycle-value.accent-orange { color: var(--accent-orange); }
+    .lifecycle-value.accent-red { color: var(--accent-red); }
+    .lifecycle-value.accent-purple { color: var(--accent-purple); }
+
+    .lifecycle-label {
+      font-size: 12px;
+      color: var(--text-secondary);
+      margin-top: 8px;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+    }
+
+    .error-rate-indicator {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 10px;
+      border-radius: 12px;
+      font-size: 12px;
+      font-weight: 600;
+      font-family: var(--font-mono);
+    }
+
+    .error-rate-indicator.healthy {
+      background: rgba(0, 230, 118, 0.15);
+      color: var(--accent-green);
+    }
+
+    .error-rate-indicator.warning {
+      background: rgba(255, 158, 64, 0.15);
+      color: var(--accent-orange);
+    }
+
+    .error-rate-indicator.critical {
+      background: rgba(255, 92, 92, 0.15);
+      color: var(--accent-red);
+    }
+
+    .sessions-table {
+      width: 100%;
+      border-collapse: collapse;
+      margin-top: 20px;
+    }
+
+    .sessions-table th,
+    .sessions-table td {
+      padding: 12px 16px;
+      text-align: left;
+    }
+
+    .sessions-table th {
+      background: var(--bg-elevated);
+      font-size: 11px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 1px;
+      color: var(--text-muted);
+      border-bottom: 1px solid var(--border-dim);
+    }
+
+    .sessions-table tr {
+      border-bottom: 1px solid var(--border-dim);
+    }
+
+    .sessions-table tr:last-child {
+      border-bottom: none;
+    }
+
+    .closed-badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      padding: 2px 8px;
+      border-radius: 10px;
+      font-size: 11px;
+      font-weight: 500;
+    }
+
+    .closed-badge.agent {
+      background: rgba(0, 230, 118, 0.15);
+      color: var(--accent-green);
+    }
+
+    .closed-badge.disconnect {
+      background: rgba(255, 158, 64, 0.15);
+      color: var(--accent-orange);
+    }
+
+    .closed-badge.error {
+      background: rgba(255, 92, 92, 0.15);
+      color: var(--accent-red);
+    }
+
+    .closed-badge.active {
+      background: rgba(74, 158, 255, 0.15);
+      color: var(--accent-blue);
+    }
+
+    @media (max-width: 1200px) {
+      .lifecycle-grid {
+        grid-template-columns: repeat(3, 1fr);
+      }
+    }
+
+    @media (max-width: 768px) {
+      .lifecycle-grid {
+        grid-template-columns: repeat(2, 1fr);
+      }
+    }
+
+    /* Empty state */
+    .empty-state {
+      padding: 64px 32px;
+      text-align: center;
+    }
+
+    .empty-state-icon {
+      width: 64px;
+      height: 64px;
+      margin: 0 auto 16px;
+      color: var(--text-muted);
+      opacity: 0.5;
+    }
+
+    .empty-state-text {
+      color: var(--text-muted);
+      font-size: 14px;
+    }
+
+    /* Last updated */
+    .last-updated {
+      text-align: center;
+      padding: 24px;
+      font-size: 12px;
+      color: var(--text-muted);
+      font-family: var(--font-mono);
+    }
+
+    /* Loading state */
+    .loading {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 64px;
+    }
+
+    .spinner {
+      width: 32px;
+      height: 32px;
+      border: 2px solid var(--border-subtle);
+      border-top-color: var(--accent-cyan);
+      border-radius: 50%;
+      animation: spin 1s linear infinite;
+    }
+
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    /* Responsive */
+    @media (max-width: 1200px) {
+      .stats-grid {
+        grid-template-columns: repeat(2, 1fr);
+      }
+      .throughput-grid {
+        grid-template-columns: repeat(2, 1fr);
+        gap: 24px;
+      }
+    }
+
+    @media (max-width: 768px) {
+      .header {
+        padding: 16px 20px 32px;
+      }
+      .main {
+        padding: 0 20px 32px;
+      }
+      .stats-grid {
+        grid-template-columns: 1fr;
+      }
+      .throughput-grid {
+        grid-template-columns: 1fr;
+      }
+      .agents-table th,
+      .agents-table td {
+        padding: 12px;
+      }
+    }
+
+    /* Animation on load */
+    .stat-card, .throughput-panel, .lifecycle-panel, .agents-table-container {
+      animation: fadeIn 0.5s ease forwards;
+      opacity: 0;
+    }
+
+    .stat-card:nth-child(1) { animation-delay: 0.1s; }
+    .stat-card:nth-child(2) { animation-delay: 0.15s; }
+    .stat-card:nth-child(3) { animation-delay: 0.2s; }
+    .stat-card:nth-child(4) { animation-delay: 0.25s; }
+    .throughput-panel { animation-delay: 0.3s; }
+    .lifecycle-panel { animation-delay: 0.35s; }
+    .agents-table-container { animation-delay: 0.45s; }
+
+    @keyframes fadeIn {
+      from {
+        opacity: 0;
+        transform: translateY(10px);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0);
+      }
+    }
+  </style>
+</head>
+<body>
+  <header class="header">
+    <div class="header-content">
+      <div class="header-left">
+        <a href="/" class="back-link">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M19 12H5M12 19l-7-7 7-7"/>
+          </svg>
+          Dashboard
+        </a>
+        <div class="logo">
+          <div class="logo-icon">
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="white" stroke-width="2">
+              <path d="M3 3v18h18"/>
+              <path d="M18 17V9"/>
+              <path d="M13 17V5"/>
+              <path d="M8 17v-3"/>
+            </svg>
+          </div>
+          <div class="logo-text">Agent <span>Metrics</span></div>
+        </div>
+      </div>
+      <div class="live-indicator">
+        <span class="live-dot"></span>
+        LIVE
+      </div>
+    </div>
+  </header>
+
+  <main class="main">
+    <div id="content">
+      <div class="loading">
+        <div class="spinner"></div>
+      </div>
+    </div>
+  </main>
+
+  <script>
+    const REFRESH_INTERVAL = 5000;
+    const COLORS = ['#4a9eff', '#b388ff', '#ff9e40', '#00e676', '#ff5c5c', '#00ffc8'];
+
+    function getAvatarColor(name) {
+      let hash = 0;
+      for (let i = 0; i < name.length; i++) {
+        hash = name.charCodeAt(i) + ((hash << 5) - hash);
+      }
+      return COLORS[Math.abs(hash) % COLORS.length];
+    }
+
+    function getInitials(name) {
+      return name.slice(0, 2).toUpperCase();
+    }
+
+    function formatDuration(seconds) {
+      if (seconds < 60) return `${seconds}s`;
+      if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+      if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
+      return `${Math.floor(seconds / 86400)}d ${Math.floor((seconds % 86400) / 3600)}h`;
+    }
+
+    function formatTime(isoString) {
+      return new Date(isoString).toLocaleTimeString('en-US', {
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false
+      });
+    }
+
+    function getErrorRateClass(rate) {
+      if (rate <= 1) return 'healthy';
+      if (rate <= 5) return 'warning';
+      return 'critical';
+    }
+
+    function getClosedByLabel(closedBy) {
+      if (!closedBy) return 'Active';
+      switch (closedBy) {
+        case 'agent': return 'Clean';
+        case 'disconnect': return 'Disconnect';
+        case 'error': return 'Error';
+        default: return closedBy;
+      }
+    }
+
+    function render(metrics) {
+      const content = document.getElementById('content');
+
+      // Calculate max throughput for bar scaling
+      const maxThroughput = Math.max(
+        metrics.throughput.messagesLastMinute * 60,
+        metrics.throughput.messagesLastHour,
+        metrics.throughput.messagesLast24Hours / 24,
+        1
+      );
+
+      content.innerHTML = `
+        <!-- Stats Overview -->
+        <div class="stats-grid">
+          <div class="stat-card">
+            <div class="stat-label">Total Agents</div>
+            <div class="stat-value accent-cyan">${metrics.totalAgents}</div>
+            <div class="stat-subtext">${metrics.onlineAgents} online / ${metrics.offlineAgents} offline</div>
+          </div>
+          <div class="stat-card">
+            <div class="stat-label">Online Now</div>
+            <div class="stat-value accent-green">${metrics.onlineAgents}</div>
+            <div class="stat-subtext">${metrics.totalAgents > 0 ? Math.round((metrics.onlineAgents / metrics.totalAgents) * 100) : 0}% availability</div>
+          </div>
+          <div class="stat-card">
+            <div class="stat-label">Total Messages</div>
+            <div class="stat-value accent-blue">${metrics.totalMessages.toLocaleString()}</div>
+            <div class="stat-subtext">all time</div>
+          </div>
+          <div class="stat-card">
+            <div class="stat-label">Avg. Throughput</div>
+            <div class="stat-value accent-orange">${metrics.throughput.avgMessagesPerMinute}</div>
+            <div class="stat-subtext">messages / minute</div>
+          </div>
+        </div>
+
+        <!-- Throughput Section -->
+        <section class="section">
+          <div class="section-header">
+            <h2 class="section-title">Message Throughput</h2>
+          </div>
+          <div class="throughput-panel">
+            <div class="throughput-grid">
+              <div class="throughput-item">
+                <div class="throughput-value">${metrics.throughput.messagesLastMinute}</div>
+                <div class="throughput-label">Last Minute</div>
+                <div class="throughput-bar">
+                  <div class="throughput-bar-fill" style="width: ${Math.min((metrics.throughput.messagesLastMinute / 10) * 100, 100)}%"></div>
+                </div>
+              </div>
+              <div class="throughput-item">
+                <div class="throughput-value">${metrics.throughput.messagesLastHour}</div>
+                <div class="throughput-label">Last Hour</div>
+                <div class="throughput-bar">
+                  <div class="throughput-bar-fill" style="width: ${Math.min((metrics.throughput.messagesLastHour / 100) * 100, 100)}%"></div>
+                </div>
+              </div>
+              <div class="throughput-item">
+                <div class="throughput-value">${metrics.throughput.messagesLast24Hours}</div>
+                <div class="throughput-label">Last 24 Hours</div>
+                <div class="throughput-bar">
+                  <div class="throughput-bar-fill" style="width: ${Math.min((metrics.throughput.messagesLast24Hours / 1000) * 100, 100)}%"></div>
+                </div>
+              </div>
+              <div class="throughput-item">
+                <div class="throughput-value">${metrics.throughput.avgMessagesPerMinute}</div>
+                <div class="throughput-label">Avg / Min</div>
+                <div class="throughput-bar">
+                  <div class="throughput-bar-fill" style="width: ${Math.min((metrics.throughput.avgMessagesPerMinute / 5) * 100, 100)}%"></div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </section>
+
+        <!-- Session Lifecycle Section -->
+        <section class="section">
+          <div class="section-header">
+            <h2 class="section-title">Session Lifecycle</h2>
+            <span class="error-rate-indicator ${getErrorRateClass(metrics.sessions?.errorRate || 0)}">
+              ${(metrics.sessions?.errorRate || 0).toFixed(1)}% error rate
+            </span>
+          </div>
+          <div class="lifecycle-panel">
+            <div class="lifecycle-grid">
+              <div class="lifecycle-item">
+                <div class="lifecycle-value accent-purple">${metrics.sessions?.totalSessions || 0}</div>
+                <div class="lifecycle-label">Total Sessions</div>
+              </div>
+              <div class="lifecycle-item">
+                <div class="lifecycle-value accent-blue">${metrics.sessions?.activeSessions || 0}</div>
+                <div class="lifecycle-label">Active</div>
+              </div>
+              <div class="lifecycle-item">
+                <div class="lifecycle-value accent-green">${metrics.sessions?.closedByAgent || 0}</div>
+                <div class="lifecycle-label">Clean Close</div>
+              </div>
+              <div class="lifecycle-item">
+                <div class="lifecycle-value accent-orange">${metrics.sessions?.closedByDisconnect || 0}</div>
+                <div class="lifecycle-label">Disconnect</div>
+              </div>
+              <div class="lifecycle-item">
+                <div class="lifecycle-value accent-red">${metrics.sessions?.closedByError || 0}</div>
+                <div class="lifecycle-label">Error</div>
+              </div>
+            </div>
+            ${metrics.sessions?.recentSessions?.length > 0 ? `
+              <table class="sessions-table">
+                <thead>
+                  <tr>
+                    <th>Agent</th>
+                    <th>Status</th>
+                    <th>Messages</th>
+                    <th>Started</th>
+                    <th>Duration</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  ${metrics.sessions.recentSessions.slice(0, 5).map(session => {
+                    const started = new Date(session.startedAt);
+                    const ended = session.endedAt ? new Date(session.endedAt) : new Date();
+                    const durationSec = Math.floor((ended - started) / 1000);
+                    const closedClass = session.closedBy || 'active';
+                    return `
+                      <tr>
+                        <td>
+                          <div class="agent-name">
+                            <div class="agent-avatar" style="background: ${getAvatarColor(session.agentName)}">
+                              ${getInitials(session.agentName)}
+                            </div>
+                            <span class="agent-name-text">${session.agentName}</span>
+                          </div>
+                        </td>
+                        <td>
+                          <span class="closed-badge ${closedClass}">
+                            ${getClosedByLabel(session.closedBy)}
+                          </span>
+                        </td>
+                        <td class="metric-cell">${session.messageCount}</td>
+                        <td class="uptime-cell">${formatTime(session.startedAt)}</td>
+                        <td class="uptime-cell">${formatDuration(durationSec)}</td>
+                      </tr>
+                    `;
+                  }).join('')}
+                </tbody>
+              </table>
+            ` : ''}
+          </div>
+        </section>
+
+        <!-- Agents Section -->
+        <section class="section">
+          <div class="section-header">
+            <h2 class="section-title">Agent Health</h2>
+          </div>
+          <div class="agents-table-container">
+            ${metrics.agents.length === 0 ? `
+              <div class="empty-state">
+                <svg class="empty-state-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+                  <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2"/>
+                  <circle cx="12" cy="7" r="4"/>
+                </svg>
+                <p class="empty-state-text">No agents registered yet</p>
+              </div>
+            ` : `
+              <table class="agents-table">
+                <thead>
+                  <tr>
+                    <th>Agent</th>
+                    <th>Status</th>
+                    <th>Messages Sent</th>
+                    <th>Messages Received</th>
+                    <th>Uptime</th>
+                    <th>Last Seen</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  ${metrics.agents.map(agent => `
+                    <tr>
+                      <td>
+                        <div class="agent-name">
+                          <div class="agent-avatar" style="background: ${getAvatarColor(agent.name)}">
+                            ${getInitials(agent.name)}
+                          </div>
+                          <span class="agent-name-text">${agent.name}</span>
+                        </div>
+                      </td>
+                      <td>
+                        <span class="status-badge ${agent.isOnline ? 'online' : 'offline'}">
+                          ${agent.isOnline ? 'Online' : 'Offline'}
+                        </span>
+                      </td>
+                      <td class="metric-cell sent">${agent.messagesSent.toLocaleString()}</td>
+                      <td class="metric-cell received">${agent.messagesReceived.toLocaleString()}</td>
+                      <td class="uptime-cell">${formatDuration(agent.uptimeSeconds)}</td>
+                      <td class="uptime-cell">${formatTime(agent.lastSeen)}</td>
+                    </tr>
+                  `).join('')}
+                </tbody>
+              </table>
+            `}
+          </div>
+        </section>
+
+        <div class="last-updated">
+          Last updated: ${formatTime(metrics.timestamp)}
+        </div>
+      `;
+    }
+
+    async function fetchMetrics() {
+      try {
+        const response = await fetch('/api/metrics');
+        if (!response.ok) throw new Error('Failed to fetch metrics');
+        const metrics = await response.json();
+        render(metrics);
+      } catch (err) {
+        console.error('Error fetching metrics:', err);
+        document.getElementById('content').innerHTML = `
+          <div class="empty-state">
+            <svg class="empty-state-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+              <circle cx="12" cy="12" r="10"/>
+              <path d="M12 8v4M12 16h.01"/>
+            </svg>
+            <p class="empty-state-text">Failed to load metrics. Retrying...</p>
+          </div>
+        `;
+      }
+    }
+
+    // Initial fetch and set up refresh
+    fetchMetrics();
+    setInterval(fetchMetrics, REFRESH_INTERVAL);
+  </script>
+</body>
+</html>
diff --git a/src/dashboard/server.ts b/src/dashboard/server.ts
index 192f167df..f2dfa1304 100644
--- a/src/dashboard/server.ts
+++ b/src/dashboard/server.ts
@@ -3,9 +3,16 @@ import { WebSocketServer, WebSocket } from 'ws';
 import http from 'http';
 import path from 'path';
 import fs from 'fs';
+import crypto from 'crypto';
 import { fileURLToPath } from 'url';
 import { SqliteStorageAdapter } from '../storage/sqlite-adapter.js';
 import type { StorageAdapter, StoredMessage } from '../storage/adapter.js';
+import { RelayClient } from '../wrapper/client.js';
+import { computeNeedsAttention } from './needs-attention.js';
+import { computeSystemMetrics, formatPrometheusMetrics } from './metrics.js';
+import { MultiProjectClient } from '../bridge/multi-project-client.js';
+import { AgentSpawner } from '../bridge/spawner.js';
+import type { ProjectConfig, SpawnRequest, WorkerInfo } from '../bridge/types.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -17,6 +24,8 @@ interface AgentStatus {
   messageCount: number;
   status?: string;
   lastActive?: string;
+  lastSeen?: string;
+  needsAttention?: boolean;
 }
 
 interface Message {
@@ -25,9 +34,64 @@ interface Message {
   content: string;
   timestamp: string;
   id: string; // unique-ish id
+  thread?: string;
 }
 
-export async function startDashboard(port: number, dataDir: string, dbPath?: string): Promise<number> {
+interface SessionInfo {
+  id: string;
+  agentName: string;
+  cli?: string;
+  startedAt: string;
+  endedAt?: string;
+  duration?: string;
+  messageCount: number;
+  summary?: string;
+  /**
+   * true if session is still active (endedAt is not set).
+   * Note: This is determined solely by endedAt, regardless of how the session
+   * was closed (agent explicit close, disconnect, or error via closedBy field).
+   */
+  isActive: boolean;
+  /** How the session was closed: 'agent' (explicit), 'disconnect', 'error', or undefined */
+  closedBy?: 'agent' | 'disconnect' | 'error';
+}
+
+interface AgentSummary {
+  agentName: string;
+  lastUpdated: string;
+  currentTask?: string;
+  completedTasks?: string[];
+  context?: string;
+}
+
+export interface DashboardOptions {
+  port: number;
+  dataDir: string;
+  teamDir: string;
+  dbPath?: string;
+  /** Enable agent spawning API */
+  enableSpawner?: boolean;
+  /** Project root for spawner (defaults to dataDir) */
+  projectRoot?: string;
+  /** Tmux session name for workers */
+  tmuxSession?: string;
+}
+
+export async function startDashboard(port: number, dataDir: string, teamDir: string, dbPath?: string): Promise<number>;
+export async function startDashboard(options: DashboardOptions): Promise<number>;
+export async function startDashboard(
+  portOrOptions: number | DashboardOptions,
+  dataDirArg?: string,
+  teamDirArg?: string,
+  dbPathArg?: string
+): Promise<number> {
+  // Handle overloaded signatures
+  const options: DashboardOptions = typeof portOrOptions === 'number'
+    ? { port: portOrOptions, dataDir: dataDirArg!, teamDir: teamDirArg!, dbPath: dbPathArg }
+    : portOrOptions;
+
+  const { port, dataDir, teamDir, dbPath, enableSpawner, projectRoot, tmuxSession } = options;
+
   console.log('Starting dashboard...');
   console.log('__dirname:', __dirname);
   const publicDir = path.join(__dirname, 'public');
@@ -36,6 +100,11 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
     ? new SqliteStorageAdapter({ dbPath })
     : undefined;
 
+  // Initialize spawner if enabled
+  const spawner: AgentSpawner | undefined = enableSpawner
+    ? new AgentSpawner(projectRoot || dataDir, tmuxSession)
+    : undefined;
+
   process.on('uncaughtException', (err) => {
     console.error('Uncaught Exception:', err);
   });
@@ -46,7 +115,50 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
 
   const app = express();
   const server = http.createServer(app);
-  const wss = new WebSocketServer({ server, path: '/ws' });
+
+  // Use noServer mode to manually route upgrade requests
+  // This prevents the bug where multiple WebSocketServers attached to the same
+  // HTTP server cause conflicts - each one's upgrade handler fires and the ones
+  // that don't match the path call abortHandshake(400), writing raw HTTP to the socket
+  const wss = new WebSocketServer({
+    noServer: true,
+    perMessageDeflate: false,
+    skipUTF8Validation: true,
+    maxPayload: 100 * 1024 * 1024 // 100MB
+  });
+  const wssBridge = new WebSocketServer({
+    noServer: true,
+    perMessageDeflate: false,
+    skipUTF8Validation: true,
+    maxPayload: 100 * 1024 * 1024
+  });
+
+  // Manually handle upgrade requests and route to correct WebSocketServer
+  server.on('upgrade', (request, socket, head) => {
+    const pathname = new URL(request.url || '', `http://${request.headers.host}`).pathname;
+
+    if (pathname === '/ws') {
+      wss.handleUpgrade(request, socket, head, (ws) => {
+        wss.emit('connection', ws, request);
+      });
+    } else if (pathname === '/ws/bridge') {
+      wssBridge.handleUpgrade(request, socket, head, (ws) => {
+        wssBridge.emit('connection', ws, request);
+      });
+    } else {
+      // Unknown path - destroy socket
+      socket.destroy();
+    }
+  });
+
+  // Server-level error handlers
+  wss.on('error', (err) => {
+    console.error('[dashboard] WebSocket server error:', err);
+  });
+
+  wssBridge.on('error', (err) => {
+    console.error('[dashboard] Bridge WebSocket server error:', err);
+  });
   if (storage) {
     await storage.init();
   }
@@ -55,9 +167,176 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
   app.use(express.static(publicDir));
   app.use(express.json());
 
+  // Relay client for sending messages from dashboard
+  const socketPath = path.join(dataDir, 'relay.sock');
+  let relayClient: RelayClient | undefined;
+
+  const connectRelayClient = async (): Promise<void> => {
+    // Only attempt connection if socket exists (daemon is running)
+    if (!fs.existsSync(socketPath)) {
+      console.log('[dashboard] Relay socket not found, messaging disabled');
+      return;
+    }
+
+    relayClient = new RelayClient({
+      socketPath,
+      agentName: 'Dashboard',
+      cli: 'dashboard',
+      reconnect: true,
+      maxReconnectAttempts: 5,
+    });
+
+    relayClient.onError = (err) => {
+      console.error('[dashboard] Relay client error:', err.message);
+    };
+
+    relayClient.onStateChange = (state) => {
+      console.log(`[dashboard] Relay client state: ${state}`);
+    };
+
+    try {
+      await relayClient.connect();
+      console.log('[dashboard] Connected to relay daemon');
+    } catch (err) {
+      console.error('[dashboard] Failed to connect to relay daemon:', err);
+      relayClient = undefined;
+    }
+  };
+
+  // Start relay client connection (non-blocking)
+  connectRelayClient().catch(() => {});
+
+  // Bridge client for cross-project messaging
+  let bridgeClient: MultiProjectClient | undefined;
+  let bridgeClientConnecting = false;
+
+  const connectBridgeClient = async (): Promise<void> => {
+    if (bridgeClient || bridgeClientConnecting) return;
+
+    // Check if bridge-state.json exists and has projects
+    const bridgeStatePath = path.join(dataDir, 'bridge-state.json');
+    if (!fs.existsSync(bridgeStatePath)) {
+      return;
+    }
+
+    try {
+      const bridgeState = JSON.parse(fs.readFileSync(bridgeStatePath, 'utf-8'));
+      if (!bridgeState.connected || !bridgeState.projects?.length) {
+        return;
+      }
+
+      bridgeClientConnecting = true;
+
+      // Build project configs from bridge state
+      const projectConfigs: ProjectConfig[] = bridgeState.projects.map((p: {
+        id: string;
+        path: string;
+        lead?: { name: string };
+      }) => {
+        // Compute socket path for each project
+        const projectHash = crypto.createHash('sha256').update(p.path).digest('hex').slice(0, 12);
+        const projectDataDir = path.join(path.dirname(dataDir), projectHash);
+        const socketPath = path.join(projectDataDir, 'relay.sock');
+
+        return {
+          id: p.id,
+          path: p.path,
+          socketPath,
+          leadName: p.lead?.name || 'Lead',
+          cli: 'dashboard-bridge',
+        };
+      });
+
+      // Filter to projects with existing sockets
+      const validConfigs = projectConfigs.filter((p: ProjectConfig) => fs.existsSync(p.socketPath));
+      if (validConfigs.length === 0) {
+        bridgeClientConnecting = false;
+        return;
+      }
+
+      bridgeClient = new MultiProjectClient(validConfigs, {
+        agentName: '__DashboardBridge__',  // Unique name to avoid conflict with CLI bridge
+        reconnect: true,
+      });
+
+      bridgeClient.onProjectStateChange = (projectId, connected) => {
+        console.log(`[dashboard-bridge] Project ${projectId} ${connected ? 'connected' : 'disconnected'}`);
+      };
+
+      await bridgeClient.connect();
+      console.log('[dashboard] Bridge client connected to', validConfigs.length, 'project(s)');
+      bridgeClientConnecting = false;
+    } catch (err) {
+      console.error('[dashboard] Failed to connect bridge client:', err);
+      bridgeClient = undefined;
+      bridgeClientConnecting = false;
+    }
+  };
+
+  // Start bridge client connection (non-blocking)
+  connectBridgeClient().catch(() => {});
+
+  // API endpoint to send messages
+  app.post('/api/send', async (req, res) => {
+    const { to, message, thread } = req.body;
+
+    if (!to || !message) {
+      return res.status(400).json({ error: 'Missing "to" or "message" field' });
+    }
+
+    if (!relayClient || relayClient.state !== 'READY') {
+      // Try to reconnect
+      await connectRelayClient();
+      if (!relayClient || relayClient.state !== 'READY') {
+        return res.status(503).json({ error: 'Relay daemon not connected' });
+      }
+    }
+
+    try {
+      const sent = relayClient.sendMessage(to, message, 'message', undefined, thread);
+      if (sent) {
+        res.json({ success: true });
+      } else {
+        res.status(500).json({ error: 'Failed to send message' });
+      }
+    } catch (err) {
+      console.error('[dashboard] Failed to send message:', err);
+      res.status(500).json({ error: 'Failed to send message' });
+    }
+  });
+
+  // API endpoint to send messages via bridge (cross-project)
+  app.post('/api/bridge/send', async (req, res) => {
+    const { projectId, to, message } = req.body;
+
+    if (!projectId || !to || !message) {
+      return res.status(400).json({ error: 'Missing "projectId", "to", or "message" field' });
+    }
+
+    // Try to connect bridge client if not connected
+    if (!bridgeClient) {
+      await connectBridgeClient();
+      if (!bridgeClient) {
+        return res.status(503).json({ error: 'Bridge not connected. Is the bridge command running?' });
+      }
+    }
+
+    try {
+      const sent = bridgeClient.sendToProject(projectId, to, message);
+      if (sent) {
+        res.json({ success: true });
+      } else {
+        res.status(500).json({ error: `Failed to send message to ${projectId}:${to}` });
+      }
+    } catch (err) {
+      console.error('[dashboard] Failed to send bridge message:', err);
+      res.status(500).json({ error: 'Failed to send bridge message' });
+    }
+  });
+
   const getTeamData = () => {
     // Try team.json first (file-based team mode)
-    const teamPath = path.join(dataDir, 'team.json');
+    const teamPath = path.join(teamDir, 'team.json');
     if (fs.existsSync(teamPath)) {
       try {
         return JSON.parse(fs.readFileSync(teamPath, 'utf-8'));
@@ -67,16 +346,18 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
     }
 
     // Fall back to agents.json (daemon mode - live connected agents)
-    const agentsPath = path.join(dataDir, 'agents.json');
+    const agentsPath = path.join(teamDir, 'agents.json');
     if (fs.existsSync(agentsPath)) {
       try {
         const data = JSON.parse(fs.readFileSync(agentsPath, 'utf-8'));
         // Convert agents.json format to team.json format
         return {
-          agents: data.agents.map((a: { name: string; connectedAt?: string; cli?: string }) => ({
+          agents: data.agents.map((a: { name: string; connectedAt?: string; cli?: string; lastSeen?: string }) => ({
             name: a.name,
             role: 'Agent',
             cli: a.cli ?? 'Unknown',
+            lastSeen: a.lastSeen ?? a.connectedAt,
+            lastActive: a.lastSeen ?? a.connectedAt,
           })),
         };
       } catch (e) {
@@ -139,11 +420,12 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
       content: row.body,
       timestamp: new Date(row.ts).toISOString(),
       id: row.id,
+      thread: row.thread,
     }));
 
   const getMessages = async (agents: any[]): Promise<Message[]> => {
     if (storage) {
-      const rows = await storage.getMessages({ limit: 500, order: 'desc' });
+      const rows = await storage.getMessages({ limit: 100, order: 'desc' });
       // Dashboard expects oldest first
       return mapStoredMessages(rows).reverse();
     }
@@ -157,9 +439,53 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
     return allMessages;
   };
 
+  const formatDuration = (startMs: number, endMs?: number): string => {
+    const end = endMs ?? Date.now();
+    const durationMs = end - startMs;
+    const minutes = Math.floor(durationMs / 60000);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0) {
+      return `${hours}h ${minutes % 60}m`;
+    }
+    return `${minutes}m`;
+  };
+
+  const getRecentSessions = async (): Promise<SessionInfo[]> => {
+    if (storage && storage instanceof SqliteStorageAdapter) {
+      const sessions = await storage.getRecentSessions(20);
+      return sessions.map(s => ({
+        id: s.id,
+        agentName: s.agentName,
+        cli: s.cli,
+        startedAt: new Date(s.startedAt).toISOString(),
+        endedAt: s.endedAt ? new Date(s.endedAt).toISOString() : undefined,
+        duration: formatDuration(s.startedAt, s.endedAt),
+        messageCount: s.messageCount,
+        summary: s.summary,
+        isActive: !s.endedAt, // Active if no end time
+        closedBy: s.closedBy,
+      }));
+    }
+    return [];
+  };
+
+  const getAgentSummaries = async (): Promise<AgentSummary[]> => {
+    if (storage && storage instanceof SqliteStorageAdapter) {
+      const summaries = await storage.getAllAgentSummaries();
+      return summaries.map(s => ({
+        agentName: s.agentName,
+        lastUpdated: new Date(s.lastUpdated).toISOString(),
+        currentTask: s.currentTask,
+        completedTasks: s.completedTasks,
+        context: s.context,
+      }));
+    }
+    return [];
+  };
+
   const getAllData = async () => {
     const team = getTeamData();
-    if (!team) return { agents: [], messages: [], activity: [] };
+    if (!team) return { agents: [], messages: [], activity: [], sessions: [], summaries: [] };
 
     const agentsMap = new Map<string, AgentStatus>();
     const allMessages: Message[] = await getMessages(team.agents);
@@ -171,7 +497,10 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
         role: a.role,
         cli: a.cli ?? 'Unknown',
         messageCount: 0,
-        status: 'Idle'
+        status: 'Idle',
+        lastSeen: a.lastSeen,
+        lastActive: a.lastActive,
+        needsAttention: false,
       });
     });
 
@@ -192,33 +521,251 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
 
     // Derive status from messages sent BY agents
     // We scan all messages; if M is from A, we check if it is a STATUS message
+    // Note: lastActive is updated from messages, but lastSeen comes from the registry
+    // (heartbeat-based) and should NOT be overwritten by message timestamps
     allMessages.forEach(m => {
       const agent = agentsMap.get(m.from);
       if (agent) {
         agent.lastActive = m.timestamp;
+        // Don't overwrite lastSeen - it comes from registry (heartbeat/connection tracking)
         if (m.content.startsWith('STATUS:')) {
           agent.status = m.content.substring(7).trim(); // remove "STATUS:"
         }
       }
     });
 
+    // Detect agents with unanswered inbound messages (needs attention)
+    const needsAttentionAgents = computeNeedsAttention(allMessages.map((m) => ({
+      from: m.from,
+      to: m.to,
+      timestamp: m.timestamp,
+      thread: m.thread,
+    })));
+
+    needsAttentionAgents.forEach((agentName) => {
+      const agent = agentsMap.get(agentName);
+      if (agent) {
+        agent.needsAttention = true;
+      }
+    });
+
+    // Fetch sessions and summaries in parallel
+    const [sessions, summaries] = await Promise.all([
+      getRecentSessions(),
+      getAgentSummaries(),
+    ]);
+
+    // Filter agents:
+    // 1. Exclude "Dashboard" (internal agent, not a real team member)
+    // 2. Exclude offline agents (no lastSeen or lastSeen > 5 minutes ago)
+    const now = Date.now();
+    const OFFLINE_THRESHOLD_MS = 5 * 60 * 1000; // 5 minutes
+    const filteredAgents = Array.from(agentsMap.values()).filter(agent => {
+      // Exclude Dashboard
+      if (agent.name === 'Dashboard') return false;
+
+      // Exclude agents starting with __ (internal/system agents)
+      if (agent.name.startsWith('__')) return false;
+
+      // Exclude offline agents (no lastSeen or too old)
+      if (!agent.lastSeen) return false;
+      const lastSeenTime = new Date(agent.lastSeen).getTime();
+      if (now - lastSeenTime > OFFLINE_THRESHOLD_MS) return false;
+
+      return true;
+    });
+
     return {
-      agents: Array.from(agentsMap.values()),
+      agents: filteredAgents,
       messages: allMessages,
-      activity: allMessages // For now, activity log is just the message log
+      activity: allMessages, // For now, activity log is just the message log
+      sessions,
+      summaries,
     };
   };
 
+  // Track clients that are still initializing (haven't received first data yet)
+  // This prevents race conditions where broadcastData sends before initial data is sent
+  const initializingClients = new WeakSet<WebSocket>();
+
   const broadcastData = async () => {
-    const data = await getAllData();
-    const payload = JSON.stringify(data);
-    wss.clients.forEach(client => {
-      if (client.readyState === WebSocket.OPEN) {
-        client.send(payload);
+    try {
+      const data = await getAllData();
+      const payload = JSON.stringify(data);
+
+      // Guard against empty/invalid payloads
+      if (!payload || payload.length === 0) {
+        console.warn('[dashboard] Skipping broadcast - empty payload');
+        return;
       }
-    });
+
+      wss.clients.forEach(client => {
+        // Skip clients that are still being initialized by the connection handler
+        if (initializingClients.has(client)) {
+          return;
+        }
+        if (client.readyState === WebSocket.OPEN) {
+          try {
+            client.send(payload);
+          } catch (err) {
+            console.error('[dashboard] Failed to send to client:', err);
+          }
+        }
+      });
+    } catch (err) {
+      console.error('[dashboard] Failed to broadcast data:', err);
+    }
   };
 
+  // Bridge data functions - defined before connection handlers
+  const getBridgeData = async () => {
+    const bridgeStatePath = path.join(dataDir, 'bridge-state.json');
+    if (fs.existsSync(bridgeStatePath)) {
+      try {
+        const bridgeState = JSON.parse(fs.readFileSync(bridgeStatePath, 'utf-8'));
+
+        // Enrich each project with actual agent data from their team directories
+        if (bridgeState.projects && Array.isArray(bridgeState.projects)) {
+          for (const project of bridgeState.projects) {
+            if (project.path) {
+              // Get project's data directory
+              const crypto = await import('crypto');
+              const projectHash = crypto.createHash('sha256').update(project.path).digest('hex').slice(0, 12);
+              const projectDataDir = path.join(path.dirname(dataDir), projectHash);
+              const projectTeamDir = path.join(projectDataDir, 'team');
+              const agentsPath = path.join(projectTeamDir, 'agents.json');
+
+              // Read actual connected agents
+              if (fs.existsSync(agentsPath)) {
+                try {
+                  const agentsData = JSON.parse(fs.readFileSync(agentsPath, 'utf-8'));
+                  if (agentsData.agents && Array.isArray(agentsData.agents)) {
+                    // Filter to only show online agents (seen in last 5 minutes)
+                    const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;
+                    project.agents = agentsData.agents
+                      .filter((a: { lastSeen?: string }) => {
+                        if (!a.lastSeen) return false;
+                        return new Date(a.lastSeen).getTime() > fiveMinutesAgo;
+                      })
+                      .map((a: { name: string; cli?: string; lastSeen?: string }) => ({
+                        name: a.name,
+                        status: 'active',
+                        cli: a.cli,
+                        lastSeen: a.lastSeen,
+                      }));
+
+                    // Update lead status based on actual agents
+                    if (project.lead) {
+                      const leadAgent = project.agents.find((a: { name: string }) =>
+                        a.name.toLowerCase() === project.lead.name.toLowerCase()
+                      );
+                      project.lead.connected = !!leadAgent;
+                    }
+                  }
+                } catch (e) {
+                  console.error(`Failed to read agents for ${project.path}:`, e);
+                }
+              }
+            }
+          }
+        }
+
+        return bridgeState;
+      } catch {
+        return { projects: [], messages: [], connected: false };
+      }
+    }
+    return { projects: [], messages: [], connected: false };
+  };
+
+  const broadcastBridgeData = async () => {
+    try {
+      const data = await getBridgeData();
+      const payload = JSON.stringify(data);
+
+      // Guard against empty/invalid payloads
+      if (!payload || payload.length === 0) {
+        console.warn('[dashboard] Skipping bridge broadcast - empty payload');
+        return;
+      }
+
+      wssBridge.clients.forEach(client => {
+        if (client.readyState === WebSocket.OPEN) {
+          try {
+            client.send(payload);
+          } catch (err) {
+            console.error('[dashboard] Failed to send to bridge client:', err);
+          }
+        }
+      });
+    } catch (err) {
+      console.error('[dashboard] Failed to broadcast bridge data:', err);
+    }
+  };
+
+  // Handle new WebSocket connections - send initial data immediately
+  wss.on('connection', async (ws, req) => {
+    console.log('[dashboard] WebSocket client connected from:', req.socket.remoteAddress);
+
+    // Mark as initializing to prevent broadcastData from sending before we do
+    initializingClients.add(ws);
+
+    try {
+      const data = await getAllData();
+      const payload = JSON.stringify(data);
+
+      // Guard against empty/invalid payloads
+      if (!payload || payload.length === 0) {
+        console.warn('[dashboard] Skipping initial send - empty payload');
+        return;
+      }
+
+      if (ws.readyState === WebSocket.OPEN) {
+        console.log('[dashboard] Sending initial data, size:', payload.length, 'first 200 chars:', payload.substring(0, 200));
+        ws.send(payload);
+        console.log('[dashboard] Initial data sent successfully');
+      } else {
+        console.warn('[dashboard] WebSocket not open, state:', ws.readyState);
+      }
+    } catch (err) {
+      console.error('[dashboard] Failed to send initial data:', err);
+    } finally {
+      // Now allow broadcastData to send to this client
+      initializingClients.delete(ws);
+    }
+
+    ws.on('error', (err) => {
+      console.error('[dashboard] WebSocket client error:', err);
+    });
+
+    ws.on('close', (code, reason) => {
+      console.log('[dashboard] WebSocket client disconnected, code:', code, 'reason:', reason?.toString() || 'none');
+    });
+  });
+
+  // Handle bridge WebSocket connections
+  wssBridge.on('connection', async (ws) => {
+    console.log('[dashboard] Bridge WebSocket client connected');
+
+    try {
+      const data = await getBridgeData();
+      const payload = JSON.stringify(data);
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(payload);
+      }
+    } catch (err) {
+      console.error('[dashboard] Failed to send initial bridge data:', err);
+    }
+
+    ws.on('error', (err) => {
+      console.error('[dashboard] Bridge WebSocket client error:', err);
+    });
+
+    ws.on('close', (code, reason) => {
+      console.log('[dashboard] Bridge WebSocket client disconnected, code:', code, 'reason:', reason?.toString() || 'none');
+    });
+  });
+
   app.get('/api/data', (req, res) => {
     getAllData().then((data) => res.json(data)).catch((err) => {
       console.error('Failed to fetch dashboard data', err);
@@ -226,13 +773,242 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
     });
   });
 
+  // ===== Metrics API =====
+
+  /**
+   * GET /api/metrics - JSON format metrics for dashboard
+   */
+  app.get('/api/metrics', async (req, res) => {
+    try {
+      // Read agent registry for message counts
+      const agentsPath = path.join(teamDir, 'agents.json');
+      let agentRecords: Array<{
+        name: string;
+        messagesSent: number;
+        messagesReceived: number;
+        firstSeen: string;
+        lastSeen: string;
+      }> = [];
+
+      if (fs.existsSync(agentsPath)) {
+        const data = JSON.parse(fs.readFileSync(agentsPath, 'utf-8'));
+        agentRecords = (data.agents || []).map((a: any) => ({
+          name: a.name,
+          messagesSent: a.messagesSent ?? 0,
+          messagesReceived: a.messagesReceived ?? 0,
+          firstSeen: a.firstSeen ?? new Date().toISOString(),
+          lastSeen: a.lastSeen ?? new Date().toISOString(),
+        }));
+      }
+
+      // Get messages for throughput calculation
+      const team = getTeamData();
+      const messages = team ? await getMessages(team.agents) : [];
+
+      // Get session data for lifecycle metrics
+      const sessions = storage?.getSessions
+        ? await storage.getSessions({ limit: 100 })
+        : [];
+
+      const metrics = computeSystemMetrics(agentRecords, messages, sessions);
+      res.json(metrics);
+    } catch (err) {
+      console.error('Failed to compute metrics', err);
+      res.status(500).json({ error: 'Failed to compute metrics' });
+    }
+  });
+
+  /**
+   * GET /api/metrics/prometheus - Prometheus exposition format
+   */
+  app.get('/api/metrics/prometheus', async (req, res) => {
+    try {
+      // Read agent registry for message counts
+      const agentsPath = path.join(teamDir, 'agents.json');
+      let agentRecords: Array<{
+        name: string;
+        messagesSent: number;
+        messagesReceived: number;
+        firstSeen: string;
+        lastSeen: string;
+      }> = [];
+
+      if (fs.existsSync(agentsPath)) {
+        const data = JSON.parse(fs.readFileSync(agentsPath, 'utf-8'));
+        agentRecords = (data.agents || []).map((a: any) => ({
+          name: a.name,
+          messagesSent: a.messagesSent ?? 0,
+          messagesReceived: a.messagesReceived ?? 0,
+          firstSeen: a.firstSeen ?? new Date().toISOString(),
+          lastSeen: a.lastSeen ?? new Date().toISOString(),
+        }));
+      }
+
+      // Get messages for throughput calculation
+      const team = getTeamData();
+      const messages = team ? await getMessages(team.agents) : [];
+
+      // Get session data for lifecycle metrics
+      const sessions = storage?.getSessions
+        ? await storage.getSessions({ limit: 100 })
+        : [];
+
+      const metrics = computeSystemMetrics(agentRecords, messages, sessions);
+      const prometheusOutput = formatPrometheusMetrics(metrics);
+
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.send(prometheusOutput);
+    } catch (err) {
+      console.error('Failed to compute Prometheus metrics', err);
+      res.status(500).send('# Error computing metrics\n');
+    }
+  });
+
+  // Metrics view route - serves metrics.html
+  app.get('/metrics', (req, res) => {
+    res.sendFile(path.join(publicDir, 'metrics.html'));
+  });
+
+  // Bridge view route - serves bridge.html
+  app.get('/bridge', (req, res) => {
+    res.sendFile(path.join(publicDir, 'bridge.html'));
+  });
+
+  // Bridge API endpoint - returns multi-project data
+  // This is a placeholder that returns empty data when not in bridge mode
+  // The actual bridge data comes from MultiProjectClient when running `agent-relay bridge`
+  app.get('/api/bridge', async (req, res) => {
+    try {
+      // Check if bridge state file exists (written by bridge command)
+      const bridgeStatePath = path.join(dataDir, 'bridge-state.json');
+      if (fs.existsSync(bridgeStatePath)) {
+        const bridgeData = JSON.parse(fs.readFileSync(bridgeStatePath, 'utf-8'));
+        res.json(bridgeData);
+      } else {
+        // No bridge running - return empty state
+        res.json({
+          projects: [],
+          messages: [],
+          connected: false,
+        });
+      }
+    } catch (err) {
+      console.error('Failed to fetch bridge data', err);
+      res.status(500).json({ error: 'Failed to load bridge data' });
+    }
+  });
+
+  // ===== Agent Spawn API =====
+
+  /**
+   * POST /api/spawn - Spawn a new agent
+   * Body: { name: string, cli?: string, task?: string }
+   */
+  app.post('/api/spawn', async (req, res) => {
+    if (!spawner) {
+      return res.status(503).json({
+        success: false,
+        error: 'Spawner not enabled. Start dashboard with enableSpawner: true',
+      });
+    }
+
+    const { name, cli = 'claude', task = '' } = req.body;
+
+    if (!name || typeof name !== 'string') {
+      return res.status(400).json({
+        success: false,
+        error: 'Missing required field: name',
+      });
+    }
+
+    try {
+      const request: SpawnRequest = {
+        name,
+        cli,
+        task,
+        requestedBy: 'api',
+      };
+      const result = await spawner.spawn(request);
+
+      if (result.success) {
+        // Broadcast update to WebSocket clients
+        broadcastData().catch(() => {});
+      }
+
+      res.json(result);
+    } catch (err: any) {
+      console.error('[api] Spawn error:', err);
+      res.status(500).json({
+        success: false,
+        name,
+        error: err.message,
+      });
+    }
+  });
+
+  /**
+   * GET /api/spawned - List active spawned agents
+   */
+  app.get('/api/spawned', (req, res) => {
+    if (!spawner) {
+      return res.status(503).json({
+        success: false,
+        error: 'Spawner not enabled',
+        agents: [],
+      });
+    }
+
+    const agents = spawner.getActiveWorkers();
+    res.json({
+      success: true,
+      agents,
+    });
+  });
+
+  /**
+   * DELETE /api/spawned/:name - Release a spawned agent
+   */
+  app.delete('/api/spawned/:name', async (req, res) => {
+    if (!spawner) {
+      return res.status(503).json({
+        success: false,
+        error: 'Spawner not enabled',
+      });
+    }
+
+    const { name } = req.params;
+
+    try {
+      const released = await spawner.release(name);
+
+      if (released) {
+        broadcastData().catch(() => {});
+      }
+
+      res.json({
+        success: released,
+        name,
+        error: released ? undefined : `Agent ${name} not found`,
+      });
+    } catch (err: any) {
+      console.error('[api] Release error:', err);
+      res.status(500).json({
+        success: false,
+        name,
+        error: err.message,
+      });
+    }
+  });
+
   // Watch for changes
   if (storage) {
     setInterval(() => {
       broadcastData().catch((err) => console.error('Broadcast failed', err));
+      broadcastBridgeData().catch((err) => console.error('Bridge broadcast failed', err));
     }, 1000);
   } else {
     let fsWait: NodeJS.Timeout | null = null;
+    let bridgeFsWait: NodeJS.Timeout | null = null;
     try {
       if (fs.existsSync(dataDir)) {
           console.log(`Watching ${dataDir} for changes...`);
@@ -245,6 +1021,14 @@ export async function startDashboard(port: number, dataDir: string, dbPath?: str
                       broadcastData();
                   }, 100);
               }
+              // Watch for bridge state changes
+              if (filename && filename.endsWith('bridge-state.json')) {
+                  if (bridgeFsWait) return;
+                  bridgeFsWait = setTimeout(() => {
+                      bridgeFsWait = null;
+                      broadcastBridgeData();
+                  }, 100);
+              }
           });
       } else {
           console.warn(`Data directory ${dataDir} does not exist yet.`);
diff --git a/src/dashboard/start.ts b/src/dashboard/start.ts
index 36d55373e..6cf26a6a1 100644
--- a/src/dashboard/start.ts
+++ b/src/dashboard/start.ts
@@ -13,4 +13,4 @@ console.log(`Starting dashboard for project: ${paths.projectRoot}`);
 console.log(`Data dir: ${paths.dataDir}`);
 console.log(`Database: ${paths.dbPath}`);
 
-startDashboard(port, paths.dataDir, paths.dbPath).catch(console.error);
+startDashboard(port, paths.dataDir, paths.teamDir, paths.dbPath).catch(console.error);
diff --git a/src/index.ts b/src/index.ts
index 50e0f3b30..0bafd6241 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -7,3 +7,11 @@ export * from './protocol/index.js';
 export * from './daemon/index.js';
 export * from './wrapper/index.js';
 export * from './utils/index.js';
+
+// Storage types for external consumers (e.g., agent-trajectories)
+export {
+  type StoredMessage,
+  type MessageQuery,
+  type StorageAdapter,
+  type StorageConfig,
+} from './storage/adapter.js';
diff --git a/src/protocol/types.ts b/src/protocol/types.ts
index 02cd71eac..d2e62e493 100644
--- a/src/protocol/types.ts
+++ b/src/protocol/types.ts
@@ -49,6 +49,14 @@ export interface HelloPayload {
   };
   /** Optional hint about which CLI the agent is using (claude, codex, gemini, etc.) */
   cli?: string;
+  /** Optional program identifier (e.g., 'claude', 'gpt-4o') */
+  program?: string;
+  /** Optional model identifier (e.g., 'claude-3-opus-2024') */
+  model?: string;
+  /** Optional task/role description for dashboard/registry */
+  task?: string;
+  /** Optional working directory hint for registry/dashboard */
+  workingDirectory?: string;
   session?: {
     resume_token?: string;
   };
@@ -56,7 +64,8 @@ export interface HelloPayload {
 
 export interface WelcomePayload {
   session_id: string;
-  resume_token: string;
+  /** Optional - only provided when session resume is implemented */
+  resume_token?: string;
   server: {
     max_frame_bytes: number;
     heartbeat_ms: number;
@@ -75,6 +84,8 @@ export interface SendPayload {
 export interface SendMeta {
   requires_ack?: boolean;
   ttl_ms?: number;
+  importance?: number; // 0-100, 100 is highest
+  replyTo?: string;    // Correlation ID for replies
 }
 
 export interface DeliveryInfo {
@@ -138,7 +149,7 @@ export interface SyncPayload {
 export type HelloEnvelope = Envelope<HelloPayload>;
 export type WelcomeEnvelope = Envelope<WelcomePayload>;
 export type SendEnvelope = Envelope<SendPayload> & { payload_meta?: SendMeta };
-export type DeliverEnvelope = Envelope<SendPayload> & { delivery: DeliveryInfo };
+export type DeliverEnvelope = Envelope<SendPayload> & { delivery: DeliveryInfo; payload_meta?: SendMeta };
 export type AckEnvelope = Envelope<AckPayload>;
 export type NackEnvelope = Envelope<NackPayload>;
 export type PingEnvelope = Envelope<PingPayload>;
diff --git a/src/storage/adapter.ts b/src/storage/adapter.ts
index 31255e317..573d2fe0c 100644
--- a/src/storage/adapter.ts
+++ b/src/storage/adapter.ts
@@ -1,5 +1,7 @@
 import type { PayloadKind } from '../protocol/types.js';
 
+export type MessageStatus = 'unread' | 'read' | 'acked';
+
 export interface StoredMessage {
   id: string;
   ts: number;
@@ -14,6 +16,10 @@ export interface StoredMessage {
   deliverySeq?: number;
   deliverySessionId?: string;
   sessionId?: string;
+  /** Per-recipient message status */
+  status: MessageStatus;
+  /** Whether the message is marked as urgent */
+  is_urgent: boolean;
 }
 
 export interface MessageQuery {
@@ -25,6 +31,42 @@ export interface MessageQuery {
   /** Filter by thread ID */
   thread?: string;
   order?: 'asc' | 'desc';
+  /** Only include unread messages */
+  unreadOnly?: boolean;
+  /** Only include urgent messages */
+  urgentOnly?: boolean;
+}
+
+export interface StoredSession {
+  id: string;
+  agentName: string;
+  cli?: string;
+  projectId?: string;
+  projectRoot?: string;
+  startedAt: number;
+  endedAt?: number;
+  messageCount: number;
+  summary?: string;
+  /** How the session was closed: 'agent' (explicit), 'disconnect', 'error', or undefined (still active) */
+  closedBy?: 'agent' | 'disconnect' | 'error';
+}
+
+export interface SessionQuery {
+  agentName?: string;
+  projectId?: string;
+  since?: number;
+  limit?: number;
+}
+
+export interface AgentSummary {
+  agentName: string;
+  projectId?: string;
+  lastUpdated: number;
+  currentTask?: string;
+  completedTasks?: string[];
+  decisions?: string[];
+  context?: string;
+  files?: string[];
 }
 
 export interface StorageAdapter {
@@ -33,6 +75,18 @@ export interface StorageAdapter {
   getMessages(query?: MessageQuery): Promise<StoredMessage[]>;
   getMessageById?(id: string): Promise<StoredMessage | null>;
   close?(): Promise<void>;
+
+  // Session management (optional - for adapters that support it)
+  startSession?(session: Omit<StoredSession, 'messageCount'>): Promise<void>;
+  endSession?(sessionId: string, options?: { summary?: string; closedBy?: 'agent' | 'disconnect' | 'error' }): Promise<void>;
+  getSessions?(query?: SessionQuery): Promise<StoredSession[]>;
+  getRecentSessions?(limit?: number): Promise<StoredSession[]>;
+  incrementSessionMessageCount?(sessionId: string): Promise<void>;
+
+  // Agent summaries (optional - for adapters that support it)
+  saveAgentSummary?(summary: Omit<AgentSummary, 'lastUpdated'>): Promise<void>;
+  getAgentSummary?(agentName: string): Promise<AgentSummary | null>;
+  getAllAgentSummaries?(): Promise<AgentSummary[]>;
 }
 
 /**
diff --git a/src/storage/sqlite-adapter.test.ts b/src/storage/sqlite-adapter.test.ts
index 40b7e378f..00f3d12de 100644
--- a/src/storage/sqlite-adapter.test.ts
+++ b/src/storage/sqlite-adapter.test.ts
@@ -18,6 +18,8 @@ const makeMessage = (overrides: Partial<StoredMessage> = {}): StoredMessage => (
   deliverySeq: overrides.deliverySeq,
   deliverySessionId: overrides.deliverySessionId,
   sessionId: overrides.sessionId,
+  status: overrides.status ?? 'unread',
+  is_urgent: overrides.is_urgent ?? false,
 });
 
 describe('SqliteStorageAdapter', () => {
@@ -28,7 +30,7 @@ describe('SqliteStorageAdapter', () => {
   beforeEach(async () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'relay-sqlite-'));
     dbPath = path.join(tmpDir, 'messages.sqlite');
-    adapter = new SqliteStorageAdapter({ dbPath });
+    adapter = new SqliteStorageAdapter({ dbPath, cleanupIntervalMs: 0 }); // Disable auto cleanup for tests
     await adapter.init();
   });
 
@@ -77,6 +79,23 @@ describe('SqliteStorageAdapter', () => {
     expect(limited).toHaveLength(1);
   });
 
+  it('supports unread and urgent filters', async () => {
+    const now = Date.now();
+    await adapter.saveMessage(makeMessage({ id: 'u1', ts: now - 3000, status: 'unread', is_urgent: false }));
+    await adapter.saveMessage(makeMessage({ id: 'u2', ts: now - 2000, status: 'unread', is_urgent: true }));
+    await adapter.saveMessage(makeMessage({ id: 'u3', ts: now - 1000, status: 'read', is_urgent: true }));
+    await adapter.saveMessage(makeMessage({ id: 'u4', ts: now, status: 'read', is_urgent: false }));
+
+    const unread = await adapter.getMessages({ unreadOnly: true, order: 'asc' });
+    expect(unread.map(r => r.id)).toEqual(['u1', 'u2']);
+
+    const urgent = await adapter.getMessages({ urgentOnly: true, order: 'asc' });
+    expect(urgent.map(r => r.id)).toEqual(['u2', 'u3']);
+
+    const unreadUrgent = await adapter.getMessages({ unreadOnly: true, urgentOnly: true, order: 'asc' });
+    expect(unreadUrgent.map(r => r.id)).toEqual(['u2']);
+  });
+
   it('supports thread filtering', async () => {
     await adapter.saveMessage(makeMessage({ id: 't1', thread: 'th-1', body: 'a' }));
     await adapter.saveMessage(makeMessage({ id: 't2', thread: 'th-2', body: 'b' }));
@@ -107,4 +126,252 @@ describe('SqliteStorageAdapter', () => {
     const rows = await adapter.getMessages();
     expect(rows.map(r => r.id)).toEqual(['fallback-1']);
   });
+
+  describe('Session Management', () => {
+    it('starts and retrieves a session', async () => {
+      const sessionId = 'session-1';
+      await adapter.startSession({
+        id: sessionId,
+        agentName: 'TestAgent',
+        cli: 'claude',
+        projectId: 'proj-123',
+        projectRoot: '/home/test/project',
+        startedAt: Date.now(),
+      });
+
+      const sessions = await adapter.getSessions();
+      expect(sessions).toHaveLength(1);
+      expect(sessions[0]).toMatchObject({
+        id: sessionId,
+        agentName: 'TestAgent',
+        cli: 'claude',
+        projectId: 'proj-123',
+        messageCount: 0,
+      });
+      expect(sessions[0].endedAt).toBeUndefined();
+    });
+
+    it('ends a session with closedBy reason', async () => {
+      const sessionId = 'session-2';
+      await adapter.startSession({
+        id: sessionId,
+        agentName: 'Agent2',
+        startedAt: Date.now() - 5000,
+      });
+
+      await adapter.endSession(sessionId, {
+        summary: 'Completed auth module',
+        closedBy: 'agent',
+      });
+
+      const sessions = await adapter.getSessions();
+      expect(sessions[0]).toMatchObject({
+        id: sessionId,
+        summary: 'Completed auth module',
+        closedBy: 'agent',
+      });
+      expect(sessions[0].endedAt).toBeDefined();
+    });
+
+    it('increments session message count', async () => {
+      const sessionId = 'session-3';
+      await adapter.startSession({
+        id: sessionId,
+        agentName: 'Agent3',
+        startedAt: Date.now(),
+      });
+
+      await adapter.incrementSessionMessageCount(sessionId);
+      await adapter.incrementSessionMessageCount(sessionId);
+      await adapter.incrementSessionMessageCount(sessionId);
+
+      const sessions = await adapter.getSessions();
+      expect(sessions[0].messageCount).toBe(3);
+    });
+
+    it('filters sessions by agentName and projectId', async () => {
+      const now = Date.now();
+      await adapter.startSession({ id: 's1', agentName: 'Alice', projectId: 'p1', startedAt: now - 2000 });
+      await adapter.startSession({ id: 's2', agentName: 'Bob', projectId: 'p1', startedAt: now - 1000 });
+      await adapter.startSession({ id: 's3', agentName: 'Alice', projectId: 'p2', startedAt: now });
+
+      const aliceSessions = await adapter.getSessions({ agentName: 'Alice' });
+      expect(aliceSessions.map(s => s.id)).toEqual(['s3', 's1']);
+
+      const p1Sessions = await adapter.getSessions({ projectId: 'p1' });
+      expect(p1Sessions.map(s => s.id)).toEqual(['s2', 's1']);
+    });
+
+    it('getRecentSessions returns limited results', async () => {
+      for (let i = 0; i < 5; i++) {
+        await adapter.startSession({
+          id: `recent-${i}`,
+          agentName: 'Agent',
+          startedAt: Date.now() + i * 100,
+        });
+      }
+
+      const recent = await adapter.getRecentSessions(3);
+      expect(recent).toHaveLength(3);
+      expect(recent[0].id).toBe('recent-4'); // Most recent first
+    });
+  });
+
+  describe('Agent Summaries', () => {
+    it('saves and retrieves an agent summary', async () => {
+      await adapter.saveAgentSummary({
+        agentName: 'SummaryAgent',
+        projectId: 'proj-1',
+        currentTask: 'Implementing auth',
+        completedTasks: ['setup', 'database'],
+        decisions: ['Use JWT'],
+        context: 'Working on login flow',
+        files: ['src/auth.ts', 'src/login.ts'],
+      });
+
+      const summary = await adapter.getAgentSummary('SummaryAgent');
+      expect(summary).not.toBeNull();
+      expect(summary).toMatchObject({
+        agentName: 'SummaryAgent',
+        projectId: 'proj-1',
+        currentTask: 'Implementing auth',
+        completedTasks: ['setup', 'database'],
+        decisions: ['Use JWT'],
+        context: 'Working on login flow',
+        files: ['src/auth.ts', 'src/login.ts'],
+      });
+      expect(summary!.lastUpdated).toBeDefined();
+    });
+
+    it('returns null for non-existent agent summary', async () => {
+      const summary = await adapter.getAgentSummary('NonExistent');
+      expect(summary).toBeNull();
+    });
+
+    it('updates existing summary on save', async () => {
+      await adapter.saveAgentSummary({
+        agentName: 'UpdateAgent',
+        currentTask: 'Task 1',
+      });
+
+      await adapter.saveAgentSummary({
+        agentName: 'UpdateAgent',
+        currentTask: 'Task 2',
+        completedTasks: ['Task 1'],
+      });
+
+      const summary = await adapter.getAgentSummary('UpdateAgent');
+      expect(summary?.currentTask).toBe('Task 2');
+      expect(summary?.completedTasks).toEqual(['Task 1']);
+    });
+
+    it('getAllAgentSummaries returns all summaries ordered by lastUpdated', async () => {
+      await adapter.saveAgentSummary({ agentName: 'Agent1', currentTask: 'T1' });
+      await new Promise(r => setTimeout(r, 10)); // Small delay for different timestamps
+      await adapter.saveAgentSummary({ agentName: 'Agent2', currentTask: 'T2' });
+      await new Promise(r => setTimeout(r, 10));
+      await adapter.saveAgentSummary({ agentName: 'Agent3', currentTask: 'T3' });
+
+      const summaries = await adapter.getAllAgentSummaries();
+      expect(summaries).toHaveLength(3);
+      expect(summaries[0].agentName).toBe('Agent3'); // Most recent first
+      expect(summaries[2].agentName).toBe('Agent1'); // Oldest last
+    });
+  });
+
+  describe('getMessageById', () => {
+    it('retrieves message by exact ID', async () => {
+      await adapter.saveMessage(makeMessage({ id: 'exact-id-123', body: 'hello' }));
+
+      const msg = await adapter.getMessageById('exact-id-123');
+      expect(msg).not.toBeNull();
+      expect(msg?.body).toBe('hello');
+    });
+
+    it('retrieves message by ID prefix', async () => {
+      await adapter.saveMessage(makeMessage({ id: 'prefix-abc-xyz-123', body: 'world' }));
+
+      const msg = await adapter.getMessageById('prefix-abc');
+      expect(msg).not.toBeNull();
+      expect(msg?.id).toBe('prefix-abc-xyz-123');
+    });
+
+    it('returns null for non-existent message', async () => {
+      const msg = await adapter.getMessageById('does-not-exist');
+      expect(msg).toBeNull();
+    });
+  });
+
+  describe('message cleanup', () => {
+    it('cleanupExpiredMessages removes old messages', async () => {
+      const now = Date.now();
+      const oldTs = now - 8 * 24 * 60 * 60 * 1000; // 8 days ago
+      const newTs = now - 1 * 24 * 60 * 60 * 1000; // 1 day ago
+
+      // Save old and new messages
+      await adapter.saveMessage(makeMessage({ id: 'old-msg', ts: oldTs }));
+      await adapter.saveMessage(makeMessage({ id: 'new-msg', ts: newTs }));
+
+      // Verify both exist
+      let messages = await adapter.getMessages({});
+      expect(messages).toHaveLength(2);
+
+      // Run cleanup (default 7 day retention)
+      const deleted = await adapter.cleanupExpiredMessages();
+      expect(deleted).toBe(1);
+
+      // Verify only new message remains
+      messages = await adapter.getMessages({});
+      expect(messages).toHaveLength(1);
+      expect(messages[0].id).toBe('new-msg');
+    });
+
+    it('cleanupExpiredMessages returns 0 when no expired messages', async () => {
+      await adapter.saveMessage(makeMessage({ id: 'recent-msg', ts: Date.now() }));
+
+      const deleted = await adapter.cleanupExpiredMessages();
+      expect(deleted).toBe(0);
+
+      const messages = await adapter.getMessages({});
+      expect(messages).toHaveLength(1);
+    });
+
+    it('respects custom retention period', async () => {
+      // Close current adapter and create one with shorter retention
+      await adapter.close();
+
+      const shortRetentionAdapter = new SqliteStorageAdapter({
+        dbPath,
+        messageRetentionMs: 1000, // 1 second
+        cleanupIntervalMs: 0, // Disable auto cleanup
+      });
+      await shortRetentionAdapter.init();
+
+      const oldTs = Date.now() - 2000; // 2 seconds ago
+      await shortRetentionAdapter.saveMessage(makeMessage({ id: 'msg', ts: oldTs }));
+
+      const deleted = await shortRetentionAdapter.cleanupExpiredMessages();
+      expect(deleted).toBe(1);
+
+      await shortRetentionAdapter.close();
+    });
+  });
+
+  describe('getStats', () => {
+    it('returns correct counts', async () => {
+      await adapter.saveMessage(makeMessage({ id: 'msg-1' }));
+      await adapter.saveMessage(makeMessage({ id: 'msg-2' }));
+
+      const stats = await adapter.getStats();
+      expect(stats.messageCount).toBe(2);
+      expect(stats.sessionCount).toBe(0);
+      expect(stats.oldestMessageTs).toBeDefined();
+    });
+
+    it('returns undefined oldestMessageTs when no messages', async () => {
+      const stats = await adapter.getStats();
+      expect(stats.messageCount).toBe(0);
+      expect(stats.oldestMessageTs).toBeUndefined();
+    });
+  });
 });
diff --git a/src/storage/sqlite-adapter.ts b/src/storage/sqlite-adapter.ts
index e0239080d..118629667 100644
--- a/src/storage/sqlite-adapter.ts
+++ b/src/storage/sqlite-adapter.ts
@@ -1,12 +1,32 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
-import { type MessageQuery, type StorageAdapter, type StoredMessage } from './adapter.js';
+import {
+  type AgentSummary,
+  type MessageQuery,
+  type MessageStatus,
+  type SessionQuery,
+  type StorageAdapter,
+  type StoredMessage,
+  type StoredSession,
+} from './adapter.js';
 
 export interface SqliteAdapterOptions {
   dbPath: string;
+  /** Message retention period in milliseconds (default: 7 days) */
+  messageRetentionMs?: number;
+  /** Auto-cleanup interval in milliseconds (default: 1 hour, 0 to disable) */
+  cleanupIntervalMs?: number;
 }
 
+/** Default retention: 7 days */
+const DEFAULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** Default cleanup interval: 1 hour */
+const DEFAULT_CLEANUP_INTERVAL_MS = 60 * 60 * 1000;
+
+// Re-export types for backwards compatibility
+export type { StoredSession, SessionQuery } from './adapter.js';
+
 type SqliteDriverName = 'better-sqlite3' | 'node';
 
 interface SqliteStatement {
@@ -26,10 +46,16 @@ export class SqliteStorageAdapter implements StorageAdapter {
   private dbPath: string;
   private db?: SqliteDatabase;
   private insertStmt?: SqliteStatement;
+  private insertSessionStmt?: SqliteStatement;
   private driver?: SqliteDriverName;
+  private retentionMs: number;
+  private cleanupIntervalMs: number;
+  private cleanupTimer?: ReturnType<typeof setInterval>;
 
   constructor(options: SqliteAdapterOptions) {
     this.dbPath = options.dbPath;
+    this.retentionMs = options.messageRetentionMs ?? DEFAULT_RETENTION_MS;
+    this.cleanupIntervalMs = options.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS;
   }
 
   private resolvePreferredDriver(): SqliteDriverName | undefined {
@@ -90,41 +116,183 @@ export class SqliteStorageAdapter implements StorageAdapter {
       );
     }
 
+    // Check if messages table exists for migration decisions
+    const messagesTableExists = this.db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='messages'"
+    ).get() as { name: string } | undefined;
+
+    if (!messagesTableExists) {
+      // Fresh install: create messages table with all columns
+      this.db.exec(`
+        CREATE TABLE messages (
+          id TEXT PRIMARY KEY,
+          ts INTEGER NOT NULL,
+          sender TEXT NOT NULL,
+          recipient TEXT NOT NULL,
+          topic TEXT,
+          kind TEXT NOT NULL,
+          body TEXT NOT NULL,
+          data TEXT,
+          thread TEXT,
+          delivery_seq INTEGER,
+          delivery_session_id TEXT,
+          session_id TEXT,
+          status TEXT NOT NULL DEFAULT 'unread',
+          is_urgent INTEGER NOT NULL DEFAULT 0
+        );
+        CREATE INDEX idx_messages_ts ON messages (ts);
+        CREATE INDEX idx_messages_sender ON messages (sender);
+        CREATE INDEX idx_messages_recipient ON messages (recipient);
+        CREATE INDEX idx_messages_topic ON messages (topic);
+        CREATE INDEX idx_messages_thread ON messages (thread);
+        CREATE INDEX idx_messages_status ON messages (status);
+        CREATE INDEX idx_messages_is_urgent ON messages (is_urgent);
+      `);
+    } else {
+      // Existing database: run migrations for missing columns
+      const columns = this.db.prepare("PRAGMA table_info(messages)").all() as { name: string }[];
+      const columnNames = new Set(columns.map(c => c.name));
+
+      if (!columnNames.has('thread')) {
+        this.db.exec('ALTER TABLE messages ADD COLUMN thread TEXT');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_messages_thread ON messages (thread)');
+      }
+      if (!columnNames.has('status')) {
+        this.db.exec("ALTER TABLE messages ADD COLUMN status TEXT NOT NULL DEFAULT 'unread'");
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_messages_status ON messages (status)');
+      }
+      if (!columnNames.has('is_urgent')) {
+        this.db.exec("ALTER TABLE messages ADD COLUMN is_urgent INTEGER NOT NULL DEFAULT 0");
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_messages_is_urgent ON messages (is_urgent)');
+      }
+    }
+
+    // Create sessions table (IF NOT EXISTS is safe here - no new columns to migrate)
     this.db.exec(`
-      CREATE TABLE IF NOT EXISTS messages (
+      CREATE TABLE IF NOT EXISTS sessions (
         id TEXT PRIMARY KEY,
-        ts INTEGER NOT NULL,
-        sender TEXT NOT NULL,
-        recipient TEXT NOT NULL,
-        topic TEXT,
-        kind TEXT NOT NULL,
-        body TEXT NOT NULL,
-        data TEXT,
-        thread TEXT,
-        delivery_seq INTEGER,
-        delivery_session_id TEXT,
-        session_id TEXT
+        agent_name TEXT NOT NULL,
+        cli TEXT,
+        project_id TEXT,
+        project_root TEXT,
+        started_at INTEGER NOT NULL,
+        ended_at INTEGER,
+        message_count INTEGER DEFAULT 0,
+        summary TEXT,
+        closed_by TEXT
       );
-      CREATE INDEX IF NOT EXISTS idx_messages_ts ON messages (ts);
-      CREATE INDEX IF NOT EXISTS idx_messages_sender ON messages (sender);
-      CREATE INDEX IF NOT EXISTS idx_messages_recipient ON messages (recipient);
-      CREATE INDEX IF NOT EXISTS idx_messages_topic ON messages (topic);
-      CREATE INDEX IF NOT EXISTS idx_messages_thread ON messages (thread);
+      CREATE INDEX IF NOT EXISTS idx_sessions_agent ON sessions (agent_name);
+      CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions (started_at);
+      CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions (project_id);
     `);
 
-    // Migration: add thread column if missing (for existing databases)
-    const columns = this.db.prepare("PRAGMA table_info(messages)").all() as { name: string }[];
-    const hasThread = columns.some(c => c.name === 'thread');
-    if (!hasThread) {
-      this.db.exec('ALTER TABLE messages ADD COLUMN thread TEXT');
-      this.db.exec('CREATE INDEX IF NOT EXISTS idx_messages_thread ON messages (thread)');
-    }
+    // Create agent_summaries table (IF NOT EXISTS is safe here - no new columns to migrate)
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS agent_summaries (
+        agent_name TEXT PRIMARY KEY,
+        project_id TEXT,
+        last_updated INTEGER NOT NULL,
+        current_task TEXT,
+        completed_tasks TEXT,
+        decisions TEXT,
+        context TEXT,
+        files TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_summaries_updated ON agent_summaries (last_updated);
+    `);
+
+    // Create presence table for real-time status tracking
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS presence (
+        agent_name TEXT PRIMARY KEY,
+        status TEXT NOT NULL DEFAULT 'offline',
+        status_text TEXT,
+        last_activity INTEGER NOT NULL,
+        typing_in TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_presence_status ON presence (status);
+      CREATE INDEX IF NOT EXISTS idx_presence_activity ON presence (last_activity);
+    `);
+
+    // Create read_state table for tracking last read message per channel/conversation
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS read_state (
+        agent_name TEXT NOT NULL,
+        channel TEXT NOT NULL,
+        last_read_ts INTEGER NOT NULL,
+        last_read_id TEXT,
+        PRIMARY KEY (agent_name, channel)
+      );
+    `);
 
     this.insertStmt = this.db.prepare(`
       INSERT OR REPLACE INTO messages
-      (id, ts, sender, recipient, topic, kind, body, data, thread, delivery_seq, delivery_session_id, session_id)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      (id, ts, sender, recipient, topic, kind, body, data, thread, delivery_seq, delivery_session_id, session_id, status, is_urgent)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
+
+    // Start automatic cleanup if enabled
+    if (this.cleanupIntervalMs > 0) {
+      this.startCleanupTimer();
+    }
+  }
+
+  /**
+   * Start the automatic cleanup timer
+   */
+  private startCleanupTimer(): void {
+    // Run cleanup once at startup (async, don't block)
+    this.cleanupExpiredMessages().catch(() => {});
+
+    // Schedule periodic cleanup
+    this.cleanupTimer = setInterval(() => {
+      this.cleanupExpiredMessages().catch(() => {});
+    }, this.cleanupIntervalMs);
+
+    // Prevent timer from keeping process alive
+    if (this.cleanupTimer.unref) {
+      this.cleanupTimer.unref();
+    }
+  }
+
+  /**
+   * Clean up messages older than the retention period
+   * @returns Number of messages deleted
+   */
+  async cleanupExpiredMessages(): Promise<number> {
+    if (!this.db) {
+      return 0;
+    }
+
+    const cutoffTs = Date.now() - this.retentionMs;
+    const stmt = this.db.prepare('DELETE FROM messages WHERE ts < ?');
+    const result = stmt.run(cutoffTs) as { changes?: number };
+    const deleted = result.changes ?? 0;
+
+    if (deleted > 0) {
+      console.log(`[storage] Cleaned up ${deleted} expired messages (older than ${Math.round(this.retentionMs / 86400000)}d)`);
+    }
+
+    return deleted;
+  }
+
+  /**
+   * Get storage statistics
+   */
+  async getStats(): Promise<{ messageCount: number; sessionCount: number; oldestMessageTs?: number }> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const msgCount = this.db.prepare('SELECT COUNT(*) as count FROM messages').get() as { count: number };
+    const sessionCount = this.db.prepare('SELECT COUNT(*) as count FROM sessions').get() as { count: number };
+    const oldest = this.db.prepare('SELECT MIN(ts) as ts FROM messages').get() as { ts: number | null };
+
+    return {
+      messageCount: msgCount.count,
+      sessionCount: sessionCount.count,
+      oldestMessageTs: oldest.ts ?? undefined,
+    };
   }
 
   async saveMessage(message: StoredMessage): Promise<void> {
@@ -144,7 +312,9 @@ export class SqliteStorageAdapter implements StorageAdapter {
       message.thread ?? null,
       message.deliverySeq ?? null,
       message.deliverySessionId ?? null,
-      message.sessionId ?? null
+      message.sessionId ?? null,
+      message.status,
+      message.is_urgent ? 1 : 0
     );
   }
 
@@ -176,13 +346,21 @@ export class SqliteStorageAdapter implements StorageAdapter {
       clauses.push('thread = ?');
       params.push(query.thread);
     }
+    if (query.unreadOnly) {
+      clauses.push('status = ?');
+      params.push('unread');
+    }
+    if (query.urgentOnly) {
+      clauses.push('is_urgent = ?');
+      params.push(1);
+    }
 
     const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
     const order = query.order === 'asc' ? 'ASC' : 'DESC';
     const limit = query.limit ?? 200;
 
     const stmt = this.db.prepare(`
-      SELECT id, ts, sender, recipient, topic, kind, body, data, thread, delivery_seq, delivery_session_id, session_id
+      SELECT id, ts, sender, recipient, topic, kind, body, data, thread, delivery_seq, delivery_session_id, session_id, status, is_urgent
       FROM messages
       ${where}
       ORDER BY ts ${order}
@@ -203,9 +381,19 @@ export class SqliteStorageAdapter implements StorageAdapter {
       deliverySeq: row.delivery_seq ?? undefined,
       deliverySessionId: row.delivery_session_id ?? undefined,
       sessionId: row.session_id ?? undefined,
+      status: row.status,
+      is_urgent: row.is_urgent === 1,
     }));
   }
 
+  async updateMessageStatus(id: string, status: MessageStatus): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+    const stmt = this.db.prepare('UPDATE messages SET status = ? WHERE id = ?');
+    stmt.run(status, id);
+  }
+
   async getMessageById(id: string): Promise<StoredMessage | null> {
     if (!this.db) {
       throw new Error('SqliteStorageAdapter not initialized');
@@ -213,7 +401,7 @@ export class SqliteStorageAdapter implements StorageAdapter {
 
     // Support both exact match and prefix match (for short IDs like "06eb33da")
     const stmt = this.db.prepare(`
-      SELECT id, ts, sender, recipient, topic, kind, body, data, delivery_seq, delivery_session_id, session_id
+      SELECT id, ts, sender, recipient, topic, kind, body, data, thread, delivery_seq, delivery_session_id, session_id, status, is_urgent
       FROM messages
       WHERE id = ? OR id LIKE ?
       ORDER BY ts DESC
@@ -232,16 +420,390 @@ export class SqliteStorageAdapter implements StorageAdapter {
       kind: row.kind,
       body: row.body,
       data: row.data ? JSON.parse(row.data) : undefined,
+      thread: row.thread ?? undefined,
       deliverySeq: row.delivery_seq ?? undefined,
       deliverySessionId: row.delivery_session_id ?? undefined,
       sessionId: row.session_id ?? undefined,
+      status: row.status ?? 'unread',
+      is_urgent: row.is_urgent === 1,
     };
   }
 
   async close(): Promise<void> {
+    // Stop cleanup timer
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+
     if (this.db) {
       this.db.close();
       this.db = undefined;
     }
   }
+
+  // ============ Session Management ============
+
+  async startSession(session: Omit<StoredSession, 'messageCount'>): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO sessions
+      (id, agent_name, cli, project_id, project_root, started_at, ended_at, message_count, summary)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    stmt.run(
+      session.id,
+      session.agentName,
+      session.cli ?? null,
+      session.projectId ?? null,
+      session.projectRoot ?? null,
+      session.startedAt,
+      session.endedAt ?? null,
+      0,
+      session.summary ?? null
+    );
+  }
+
+  /**
+   * End a session and optionally set a summary.
+   *
+   * Note: The summary uses COALESCE(?, summary) - if a summary was previously
+   * set (e.g., during startSession or a prior endSession call), passing null/undefined
+   * for summary will preserve the existing value rather than clearing it.
+   * To explicitly clear a summary, pass an empty string.
+   */
+  async endSession(
+    sessionId: string,
+    options?: { summary?: string; closedBy?: 'agent' | 'disconnect' | 'error' }
+  ): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      UPDATE sessions
+      SET ended_at = ?, summary = COALESCE(?, summary), closed_by = ?
+      WHERE id = ?
+    `);
+
+    stmt.run(
+      Date.now(),
+      options?.summary ?? null,
+      options?.closedBy ?? null,
+      sessionId
+    );
+  }
+
+  async incrementSessionMessageCount(sessionId: string): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      UPDATE sessions SET message_count = message_count + 1 WHERE id = ?
+    `);
+
+    stmt.run(sessionId);
+  }
+
+  async getSessions(query: SessionQuery = {}): Promise<StoredSession[]> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const clauses: string[] = [];
+    const params: unknown[] = [];
+
+    if (query.agentName) {
+      clauses.push('agent_name = ?');
+      params.push(query.agentName);
+    }
+    if (query.projectId) {
+      clauses.push('project_id = ?');
+      params.push(query.projectId);
+    }
+    if (query.since) {
+      clauses.push('started_at >= ?');
+      params.push(query.since);
+    }
+
+    const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+    const limit = query.limit ?? 50;
+
+    const stmt = this.db.prepare(`
+      SELECT id, agent_name, cli, project_id, project_root, started_at, ended_at, message_count, summary, closed_by
+      FROM sessions
+      ${where}
+      ORDER BY started_at DESC
+      LIMIT ?
+    `);
+
+    const rows = stmt.all(...params, limit);
+    return rows.map((row: any) => ({
+      id: row.id,
+      agentName: row.agent_name,
+      cli: row.cli ?? undefined,
+      projectId: row.project_id ?? undefined,
+      projectRoot: row.project_root ?? undefined,
+      startedAt: row.started_at,
+      endedAt: row.ended_at ?? undefined,
+      messageCount: row.message_count,
+      summary: row.summary ?? undefined,
+      closedBy: row.closed_by ?? undefined,
+    }));
+  }
+
+  async getRecentSessions(limit: number = 10): Promise<StoredSession[]> {
+    return this.getSessions({ limit });
+  }
+
+  // ============ Agent Summaries ============
+
+  async saveAgentSummary(summary: {
+    agentName: string;
+    projectId?: string;
+    currentTask?: string;
+    completedTasks?: string[];
+    decisions?: string[];
+    context?: string;
+    files?: string[];
+  }): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO agent_summaries
+      (agent_name, project_id, last_updated, current_task, completed_tasks, decisions, context, files)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    stmt.run(
+      summary.agentName,
+      summary.projectId ?? null,
+      Date.now(),
+      summary.currentTask ?? null,
+      summary.completedTasks ? JSON.stringify(summary.completedTasks) : null,
+      summary.decisions ? JSON.stringify(summary.decisions) : null,
+      summary.context ?? null,
+      summary.files ? JSON.stringify(summary.files) : null
+    );
+  }
+
+  async getAgentSummary(agentName: string): Promise<AgentSummary | null> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT agent_name, project_id, last_updated, current_task, completed_tasks, decisions, context, files
+      FROM agent_summaries
+      WHERE agent_name = ?
+    `);
+
+    const row: any = stmt.get(agentName);
+    if (!row) return null;
+
+    return {
+      agentName: row.agent_name,
+      projectId: row.project_id ?? undefined,
+      lastUpdated: row.last_updated,
+      currentTask: row.current_task ?? undefined,
+      completedTasks: row.completed_tasks ? JSON.parse(row.completed_tasks) : undefined,
+      decisions: row.decisions ? JSON.parse(row.decisions) : undefined,
+      context: row.context ?? undefined,
+      files: row.files ? JSON.parse(row.files) : undefined,
+    };
+  }
+
+  async getAllAgentSummaries(): Promise<AgentSummary[]> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT agent_name, project_id, last_updated, current_task, completed_tasks, decisions, context, files
+      FROM agent_summaries
+      ORDER BY last_updated DESC
+    `);
+
+    const rows = stmt.all();
+    return rows.map((row: any) => ({
+      agentName: row.agent_name,
+      projectId: row.project_id ?? undefined,
+      lastUpdated: row.last_updated,
+      currentTask: row.current_task ?? undefined,
+      completedTasks: row.completed_tasks ? JSON.parse(row.completed_tasks) : undefined,
+      decisions: row.decisions ? JSON.parse(row.decisions) : undefined,
+      context: row.context ?? undefined,
+      files: row.files ? JSON.parse(row.files) : undefined,
+    }));
+  }
+
+  // ============ Presence Management ============
+
+  async updatePresence(presence: {
+    agentName: string;
+    status: 'online' | 'away' | 'busy' | 'offline';
+    statusText?: string;
+    typingIn?: string;
+  }): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO presence
+      (agent_name, status, status_text, last_activity, typing_in)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+
+    stmt.run(
+      presence.agentName,
+      presence.status,
+      presence.statusText ?? null,
+      Date.now(),
+      presence.typingIn ?? null
+    );
+  }
+
+  async getPresence(agentName: string): Promise<{
+    agentName: string;
+    status: 'online' | 'away' | 'busy' | 'offline';
+    statusText?: string;
+    lastActivity: number;
+    typingIn?: string;
+  } | null> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT agent_name, status, status_text, last_activity, typing_in
+      FROM presence
+      WHERE agent_name = ?
+    `);
+
+    const row: any = stmt.get(agentName);
+    if (!row) return null;
+
+    return {
+      agentName: row.agent_name,
+      status: row.status,
+      statusText: row.status_text ?? undefined,
+      lastActivity: row.last_activity,
+      typingIn: row.typing_in ?? undefined,
+    };
+  }
+
+  async getAllPresence(): Promise<Array<{
+    agentName: string;
+    status: 'online' | 'away' | 'busy' | 'offline';
+    statusText?: string;
+    lastActivity: number;
+    typingIn?: string;
+  }>> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT agent_name, status, status_text, last_activity, typing_in
+      FROM presence
+      ORDER BY last_activity DESC
+    `);
+
+    const rows = stmt.all();
+    return rows.map((row: any) => ({
+      agentName: row.agent_name,
+      status: row.status,
+      statusText: row.status_text ?? undefined,
+      lastActivity: row.last_activity,
+      typingIn: row.typing_in ?? undefined,
+    }));
+  }
+
+  async setTypingIndicator(agentName: string, channel: string | null): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      UPDATE presence
+      SET typing_in = ?, last_activity = ?
+      WHERE agent_name = ?
+    `);
+
+    stmt.run(channel, Date.now(), agentName);
+  }
+
+  // ============ Read State Management ============
+
+  async updateReadState(agentName: string, channel: string, lastReadTs: number, lastReadId?: string): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO read_state
+      (agent_name, channel, last_read_ts, last_read_id)
+      VALUES (?, ?, ?, ?)
+    `);
+
+    stmt.run(agentName, channel, lastReadTs, lastReadId ?? null);
+  }
+
+  async getReadState(agentName: string, channel: string): Promise<{
+    lastReadTs: number;
+    lastReadId?: string;
+  } | null> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT last_read_ts, last_read_id
+      FROM read_state
+      WHERE agent_name = ? AND channel = ?
+    `);
+
+    const row: any = stmt.get(agentName, channel);
+    if (!row) return null;
+
+    return {
+      lastReadTs: row.last_read_ts,
+      lastReadId: row.last_read_id ?? undefined,
+    };
+  }
+
+  async getUnreadCounts(agentName: string): Promise<Record<string, number>> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    // Get all read states for this agent
+    const readStates = this.db.prepare(`
+      SELECT channel, last_read_ts FROM read_state WHERE agent_name = ?
+    `).all(agentName) as Array<{ channel: string; last_read_ts: number }>;
+
+    const counts: Record<string, number> = {};
+
+    // Count unread messages for each channel (conversation with agent)
+    for (const { channel, last_read_ts } of readStates) {
+      const count = this.db.prepare(`
+        SELECT COUNT(*) as count FROM messages
+        WHERE recipient = ? AND ts > ?
+      `).get(channel, last_read_ts) as { count: number };
+
+      if (count.count > 0) {
+        counts[channel] = count.count;
+      }
+    }
+
+    return counts;
+  }
 }
diff --git a/src/utils/agent-config.test.ts b/src/utils/agent-config.test.ts
new file mode 100644
index 000000000..ac2d882be
--- /dev/null
+++ b/src/utils/agent-config.test.ts
@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { findAgentConfig, isClaudeCli, buildClaudeArgs } from './agent-config.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+describe('agent-config', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-config-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('findAgentConfig', () => {
+    it('returns null when no config exists', () => {
+      const result = findAgentConfig('Lead', tempDir);
+      expect(result).toBeNull();
+    });
+
+    it('finds config in .claude/agents/', () => {
+      const agentsDir = path.join(tempDir, '.claude', 'agents');
+      fs.mkdirSync(agentsDir, { recursive: true });
+      fs.writeFileSync(path.join(agentsDir, 'lead.md'), `---
+name: lead
+model: haiku
+description: Test agent
+---
+
+# Lead Agent
+`);
+
+      const result = findAgentConfig('Lead', tempDir);
+      expect(result).not.toBeNull();
+      expect(result?.name).toBe('lead');
+      expect(result?.model).toBe('haiku');
+      expect(result?.description).toBe('Test agent');
+    });
+
+    it('finds config case-insensitively', () => {
+      const agentsDir = path.join(tempDir, '.claude', 'agents');
+      fs.mkdirSync(agentsDir, { recursive: true });
+      fs.writeFileSync(path.join(agentsDir, 'MyAgent.md'), `---
+name: MyAgent
+model: opus
+---
+`);
+
+      const result = findAgentConfig('myagent', tempDir);
+      expect(result).not.toBeNull();
+      expect(result?.name).toBe('MyAgent');
+      expect(result?.model).toBe('opus');
+    });
+
+    it('finds config in .openagents/', () => {
+      const agentsDir = path.join(tempDir, '.openagents');
+      fs.mkdirSync(agentsDir, { recursive: true });
+      fs.writeFileSync(path.join(agentsDir, 'worker.md'), `---
+name: worker
+model: sonnet
+---
+`);
+
+      const result = findAgentConfig('Worker', tempDir);
+      expect(result).not.toBeNull();
+      expect(result?.model).toBe('sonnet');
+    });
+
+    it('prefers .claude/agents/ over .openagents/', () => {
+      // Create both directories
+      const claudeDir = path.join(tempDir, '.claude', 'agents');
+      const openDir = path.join(tempDir, '.openagents');
+      fs.mkdirSync(claudeDir, { recursive: true });
+      fs.mkdirSync(openDir, { recursive: true });
+
+      fs.writeFileSync(path.join(claudeDir, 'agent.md'), `---
+model: haiku
+---
+`);
+      fs.writeFileSync(path.join(openDir, 'agent.md'), `---
+model: opus
+---
+`);
+
+      const result = findAgentConfig('agent', tempDir);
+      expect(result?.model).toBe('haiku'); // Claude takes precedence
+    });
+
+    it('parses allowed-tools from frontmatter', () => {
+      const agentsDir = path.join(tempDir, '.claude', 'agents');
+      fs.mkdirSync(agentsDir, { recursive: true });
+      fs.writeFileSync(path.join(agentsDir, 'test.md'), `---
+name: test
+allowed-tools: Read, Grep, Glob
+---
+`);
+
+      const result = findAgentConfig('test', tempDir);
+      expect(result?.allowedTools).toEqual(['Read', 'Grep', 'Glob']);
+    });
+  });
+
+  describe('isClaudeCli', () => {
+    it('returns true for "claude"', () => {
+      expect(isClaudeCli('claude')).toBe(true);
+    });
+
+    it('returns true for paths containing claude', () => {
+      expect(isClaudeCli('/usr/local/bin/claude')).toBe(true);
+    });
+
+    it('returns false for other commands', () => {
+      expect(isClaudeCli('codex')).toBe(false);
+      expect(isClaudeCli('gemini')).toBe(false);
+      expect(isClaudeCli('node')).toBe(false);
+    });
+  });
+
+  describe('buildClaudeArgs', () => {
+    it('returns existing args when no config found', () => {
+      const args = buildClaudeArgs('Unknown', ['--debug'], tempDir);
+      expect(args).toEqual(['--debug']);
+    });
+
+    it('adds --model and --agent when config found', () => {
+      const agentsDir = path.join(tempDir, '.claude', 'agents');
+      fs.mkdirSync(agentsDir, { recursive: true });
+      fs.writeFileSync(path.join(agentsDir, 'lead.md'), `---
+name: lead
+model: haiku
+---
+`);
+
+      const args = buildClaudeArgs('Lead', [], tempDir);
+      expect(args).toContain('--model');
+      expect(args).toContain('haiku');
+      expect(args).toContain('--agent');
+      expect(args).toContain('lead');
+    });
+
+    it('does not duplicate --model if already present', () => {
+      const agentsDir = path.join(tempDir, '.claude', 'agents');
+      fs.mkdirSync(agentsDir, { recursive: true });
+      fs.writeFileSync(path.join(agentsDir, 'lead.md'), `---
+model: haiku
+---
+`);
+
+      const args = buildClaudeArgs('Lead', ['--model', 'opus'], tempDir);
+      const modelCount = args.filter(a => a === '--model').length;
+      expect(modelCount).toBe(1);
+      expect(args).toContain('opus'); // Original preserved
+    });
+  });
+});
diff --git a/src/utils/agent-config.ts b/src/utils/agent-config.ts
new file mode 100644
index 000000000..bbe419e7f
--- /dev/null
+++ b/src/utils/agent-config.ts
@@ -0,0 +1,157 @@
+/**
+ * Agent Config Detection
+ *
+ * Detects agent configuration from .claude/agents/ or .openagents/ directories.
+ * Parses frontmatter to extract model, description, and other settings.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface AgentConfig {
+  /** Agent name (from filename or frontmatter) */
+  name: string;
+  /** Path to the config file */
+  configPath: string;
+  /** Model to use (e.g., 'haiku', 'sonnet', 'opus') */
+  model?: string;
+  /** Agent description */
+  description?: string;
+  /** Allowed tools */
+  allowedTools?: string[];
+  /** Agent type */
+  agentType?: string;
+}
+
+/**
+ * Parse YAML-style frontmatter from markdown content.
+ * Handles basic key: value pairs.
+ */
+function parseFrontmatter(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  // Check for frontmatter delimiters
+  if (!content.startsWith('---')) {
+    return result;
+  }
+
+  const endIndex = content.indexOf('---', 3);
+  if (endIndex === -1) {
+    return result;
+  }
+
+  const frontmatter = content.slice(3, endIndex).trim();
+  const lines = frontmatter.split('\n');
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+
+    if (key && value) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Find and parse agent config for a given agent name.
+ * Searches in order:
+ *   1. .claude/agents/<name>.md (case-insensitive)
+ *   2. .openagents/<name>.md (case-insensitive)
+ *
+ * @param agentName The agent name to look up
+ * @param projectRoot The project root directory (defaults to cwd)
+ * @returns AgentConfig if found, null otherwise
+ */
+export function findAgentConfig(agentName: string, projectRoot?: string): AgentConfig | null {
+  const root = projectRoot ?? process.cwd();
+  const lowerName = agentName.toLowerCase();
+
+  // Directories to search
+  const searchDirs = [
+    path.join(root, '.claude', 'agents'),
+    path.join(root, '.openagents'),
+  ];
+
+  for (const dir of searchDirs) {
+    if (!fs.existsSync(dir)) {
+      continue;
+    }
+
+    try {
+      const files = fs.readdirSync(dir);
+
+      // Find matching file (case-insensitive)
+      for (const file of files) {
+        if (!file.endsWith('.md')) continue;
+
+        const baseName = file.slice(0, -3); // Remove .md
+        if (baseName.toLowerCase() === lowerName) {
+          const configPath = path.join(dir, file);
+          const content = fs.readFileSync(configPath, 'utf-8');
+          const frontmatter = parseFrontmatter(content);
+
+          return {
+            name: frontmatter.name || baseName,
+            configPath,
+            model: frontmatter.model,
+            description: frontmatter.description,
+            allowedTools: frontmatter['allowed-tools']?.split(',').map(t => t.trim()),
+            agentType: frontmatter.agentType,
+          };
+        }
+      }
+    } catch {
+      // Directory read failed, continue to next
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if a command is a Claude CLI command.
+ */
+export function isClaudeCli(command: string): boolean {
+  const cmd = command.toLowerCase();
+  return cmd === 'claude' || cmd.startsWith('claude ') || cmd.includes('/claude');
+}
+
+/**
+ * Build Claude CLI arguments with auto-detected agent config.
+ *
+ * @param agentName Agent name
+ * @param existingArgs Existing command arguments
+ * @param projectRoot Project root directory
+ * @returns Modified args array with --model and --agent if applicable
+ */
+export function buildClaudeArgs(
+  agentName: string,
+  existingArgs: string[] = [],
+  projectRoot?: string
+): string[] {
+  const config = findAgentConfig(agentName, projectRoot);
+
+  if (!config) {
+    return existingArgs;
+  }
+
+  const newArgs = [...existingArgs];
+
+  // Add --model if specified in config and not already in args
+  if (config.model && !existingArgs.includes('--model')) {
+    newArgs.push('--model', config.model);
+  }
+
+  // Add --agent to load the agent's system prompt (if not already specified)
+  if (!existingArgs.includes('--agent')) {
+    newArgs.push('--agent', config.name);
+  }
+
+  return newArgs;
+}
diff --git a/src/utils/project-namespace.test.ts b/src/utils/project-namespace.test.ts
new file mode 100644
index 000000000..254c638cf
--- /dev/null
+++ b/src/utils/project-namespace.test.ts
@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import {
+  findProjectRoot,
+  getProjectPaths,
+  getGlobalPaths,
+  ensureProjectDir,
+  listProjects,
+} from './project-namespace.js';
+
+describe('project-namespace', () => {
+  describe('findProjectRoot', () => {
+    it('should find project root from current directory', () => {
+      // agent-relay has .git, so should find it
+      const root = findProjectRoot();
+      expect(root).toBeTruthy();
+      expect(fs.existsSync(path.join(root, '.git')) || fs.existsSync(path.join(root, 'package.json'))).toBe(true);
+    });
+
+    it('should find project root from subdirectory', () => {
+      const subDir = path.join(process.cwd(), 'src');
+      if (fs.existsSync(subDir)) {
+        const root = findProjectRoot(subDir);
+        expect(root).toBe(path.resolve(process.cwd()));
+      }
+    });
+
+    it('should return start directory if no markers found', () => {
+      // Use temp dir with no project markers
+      const tempDir = os.tmpdir();
+      const root = findProjectRoot(tempDir);
+      // Should return the temp dir or find a marker up the chain
+      expect(root).toBeTruthy();
+    });
+  });
+
+  describe('getProjectPaths', () => {
+    it('should return all required paths', () => {
+      const paths = getProjectPaths();
+
+      expect(paths.dataDir).toBeTruthy();
+      expect(paths.teamDir).toBeTruthy();
+      expect(paths.dbPath).toBeTruthy();
+      expect(paths.socketPath).toBeTruthy();
+      expect(paths.projectRoot).toBeTruthy();
+      expect(paths.projectId).toBeTruthy();
+    });
+
+    it('should generate consistent paths for same project', () => {
+      const paths1 = getProjectPaths();
+      const paths2 = getProjectPaths();
+
+      expect(paths1.projectId).toBe(paths2.projectId);
+      expect(paths1.dataDir).toBe(paths2.dataDir);
+    });
+
+    it('should generate different paths for different projects', () => {
+      const paths1 = getProjectPaths('/tmp/project-a');
+      const paths2 = getProjectPaths('/tmp/project-b');
+
+      expect(paths1.projectId).not.toBe(paths2.projectId);
+      expect(paths1.dataDir).not.toBe(paths2.dataDir);
+    });
+
+    it('should have consistent structure', () => {
+      const paths = getProjectPaths();
+
+      expect(paths.teamDir).toBe(path.join(paths.dataDir, 'team'));
+      expect(paths.dbPath).toBe(path.join(paths.dataDir, 'messages.sqlite'));
+      expect(paths.socketPath).toBe(path.join(paths.dataDir, 'relay.sock'));
+    });
+
+    it('should use 12-char hash for projectId', () => {
+      const paths = getProjectPaths();
+      expect(paths.projectId).toMatch(/^[a-f0-9]{12}$/);
+    });
+  });
+
+  describe('getGlobalPaths', () => {
+    it('should return global paths', () => {
+      const paths = getGlobalPaths();
+
+      expect(paths.projectId).toBe('global');
+      expect(paths.dataDir).toContain('.agent-relay');
+      expect(paths.dataDir).not.toMatch(/[a-f0-9]{12}$/);
+    });
+  });
+
+  describe('ensureProjectDir', () => {
+    let testDir: string;
+
+    beforeEach(() => {
+      testDir = path.join(os.tmpdir(), `agent-relay-test-${Date.now()}`);
+    });
+
+    afterEach(() => {
+      // Clean up test directory
+      if (fs.existsSync(testDir)) {
+        fs.rmSync(testDir, { recursive: true, force: true });
+      }
+    });
+
+    it('should create data directory if not exists', () => {
+      // Create a test project dir
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, 'package.json'), '{}');
+
+      const paths = ensureProjectDir(testDir);
+
+      expect(fs.existsSync(paths.dataDir)).toBe(true);
+      expect(fs.existsSync(paths.teamDir)).toBe(true);
+    });
+
+    it('should write .project marker file', () => {
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, 'package.json'), '{}');
+
+      const paths = ensureProjectDir(testDir);
+      const markerPath = path.join(paths.dataDir, '.project');
+
+      expect(fs.existsSync(markerPath)).toBe(true);
+
+      const marker = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
+      expect(marker.projectRoot).toBe(testDir);
+      expect(marker.projectId).toBe(paths.projectId);
+      expect(marker.createdAt).toBeTruthy();
+    });
+  });
+
+  describe('listProjects', () => {
+    it('should return array of projects', () => {
+      const projects = listProjects();
+
+      expect(Array.isArray(projects)).toBe(true);
+      // Each project should have required fields
+      for (const project of projects) {
+        expect(project.projectId).toBeTruthy();
+        expect(project.projectRoot).toBeTruthy();
+        expect(project.dataDir).toBeTruthy();
+      }
+    });
+
+    it('should include current project if initialized', () => {
+      // Get current project paths
+      const currentPaths = getProjectPaths();
+      const markerPath = path.join(currentPaths.dataDir, '.project');
+
+      // Only test if project marker exists (project has been properly initialized)
+      if (fs.existsSync(markerPath)) {
+        const projects = listProjects();
+        const found = projects.find(p => p.projectId === currentPaths.projectId);
+        expect(found).toBeTruthy();
+      }
+    });
+  });
+});
diff --git a/src/utils/project-namespace.ts b/src/utils/project-namespace.ts
index c0ad207c8..dcc9e5c44 100644
--- a/src/utils/project-namespace.ts
+++ b/src/utils/project-namespace.ts
@@ -9,8 +9,32 @@
 import crypto from 'node:crypto';
 import path from 'node:path';
 import fs from 'node:fs';
+import os from 'node:os';
 
-const BASE_DIR = '/tmp/agent-relay';
+/**
+ * Get the base directory for agent-relay data.
+ * Priority:
+ * 1. AGENT_RELAY_DATA_DIR environment variable
+ * 2. XDG_DATA_HOME/agent-relay (Linux/macOS standard)
+ * 3. ~/.agent-relay (fallback)
+ */
+function getBaseDir(): string {
+  // Explicit override
+  if (process.env.AGENT_RELAY_DATA_DIR) {
+    return process.env.AGENT_RELAY_DATA_DIR;
+  }
+
+  // XDG Base Directory Specification
+  const xdgDataHome = process.env.XDG_DATA_HOME;
+  if (xdgDataHome) {
+    return path.join(xdgDataHome, 'agent-relay');
+  }
+
+  // Default: ~/.agent-relay
+  return path.join(os.homedir(), '.agent-relay');
+}
+
+const BASE_DIR = getBaseDir();
 
 /**
  * Generate a short hash of a path for namespacing
diff --git a/src/wrapper/client.test.ts b/src/wrapper/client.test.ts
new file mode 100644
index 000000000..d0ed5b5fb
--- /dev/null
+++ b/src/wrapper/client.test.ts
@@ -0,0 +1,173 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Envelope, ErrorPayload, WelcomePayload, SendPayload, DeliverEnvelope } from '../protocol/types.js';
+import { RelayClient, type RelayClientConfig } from './client.js';
+
+describe('RelayClient', () => {
+  describe('configuration', () => {
+    it('should use default config values', () => {
+      const client = new RelayClient({});
+      expect(client.state).toBe('DISCONNECTED');
+    });
+
+    it('should accept custom config', () => {
+      const client = new RelayClient({
+        agentName: 'TestAgent',
+        socketPath: '/custom/socket.sock',
+        reconnect: false,
+        maxReconnectAttempts: 5,
+      });
+      expect(client.state).toBe('DISCONNECTED');
+    });
+
+    it('should use agentName from config', () => {
+      const client = new RelayClient({ agentName: 'CustomAgent' });
+      // agentName is stored internally
+      expect((client as any).config.agentName).toBe('CustomAgent');
+    });
+  });
+
+  describe('state management', () => {
+    it('should start in DISCONNECTED state', () => {
+      const client = new RelayClient({});
+      expect(client.state).toBe('DISCONNECTED');
+    });
+
+    it('should notify on state change', () => {
+      const client = new RelayClient({ reconnect: false });
+      const states: string[] = [];
+      client.onStateChange = (state) => states.push(state);
+
+      // Trigger internal state changes using setState
+      (client as any).setState('CONNECTING');
+      (client as any).setState('READY');
+
+      expect(states).toContain('CONNECTING');
+      expect(states).toContain('READY');
+    });
+  });
+
+  describe('message handling', () => {
+    it('should call onMessage when DELIVER received', () => {
+      const client = new RelayClient({ reconnect: false });
+      const messages: any[] = [];
+      client.onMessage = (from, payload, id) => messages.push({ from, payload, id });
+
+      // DELIVER envelope has delivery info and from at envelope level
+      const deliverEnvelope: DeliverEnvelope = {
+        v: 1,
+        type: 'DELIVER',
+        id: 'msg-1',
+        ts: Date.now(),
+        from: 'Alice',
+        payload: {
+          from: 'Alice',
+          to: 'Bob',
+          body: 'Hello!',
+        },
+        delivery: {
+          topic: 'dm',
+          seq: 1,
+        },
+      };
+
+      (client as any).processFrame(deliverEnvelope);
+
+      expect(messages).toHaveLength(1);
+      expect(messages[0].from).toBe('Alice');
+      expect(messages[0].payload.body).toBe('Hello!');
+    });
+
+    it('should handle WELCOME and transition to READY', () => {
+      const client = new RelayClient({ reconnect: false });
+      (client as any)._state = 'CONNECTING';
+
+      const welcomeEnvelope: Envelope<WelcomePayload> = {
+        v: 1,
+        type: 'WELCOME',
+        id: 'welcome-1',
+        ts: Date.now(),
+        payload: {
+          session_id: 'session-123',
+          server: {
+            max_frame_bytes: 1024 * 1024,
+            heartbeat_ms: 5000,
+          },
+        },
+      };
+
+      (client as any).processFrame(welcomeEnvelope);
+
+      expect(client.state).toBe('READY');
+    });
+  });
+
+  describe('error handling', () => {
+    it('clears resume token after RESUME_TOO_OLD error', () => {
+      const client = new RelayClient({ reconnect: false });
+
+      // Simulate a stored resume token that the server rejects
+      (client as any).resumeToken = 'stale-token';
+
+      const errorEnvelope: Envelope<ErrorPayload> = {
+        v: 1,
+        type: 'ERROR',
+        id: 'err-1',
+        ts: Date.now(),
+        payload: {
+          code: 'RESUME_TOO_OLD',
+          message: 'Session resume not yet supported; starting new session',
+          fatal: false,
+        },
+      };
+
+      (client as any).processFrame(errorEnvelope);
+
+      expect((client as any).resumeToken).toBeUndefined();
+    });
+
+    it('should handle ERROR frames without crashing', () => {
+      const client = new RelayClient({ reconnect: false });
+
+      const errorEnvelope: Envelope<ErrorPayload> = {
+        v: 1,
+        type: 'ERROR',
+        id: 'err-1',
+        ts: Date.now(),
+        payload: {
+          code: 'INTERNAL_ERROR',
+          message: 'Something went wrong',
+          fatal: true,
+        },
+      };
+
+      // Should not throw
+      expect(() => (client as any).processFrame(errorEnvelope)).not.toThrow();
+    });
+  });
+
+  describe('sendMessage', () => {
+    it('should return false when not connected', () => {
+      const client = new RelayClient({ reconnect: false });
+      const result = client.sendMessage('Alice', 'Hello');
+      expect(result).toBe(false);
+    });
+
+    it('should return false when in wrong state', () => {
+      const client = new RelayClient({ reconnect: false });
+      (client as any)._state = 'CONNECTING';
+      const result = client.sendMessage('Alice', 'Hello');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('disconnect', () => {
+    it('should transition to DISCONNECTED state', () => {
+      const client = new RelayClient({ reconnect: false });
+      (client as any)._state = 'READY';
+
+      client.disconnect();
+
+      expect(client.state).toBe('DISCONNECTED');
+    });
+  });
+});
diff --git a/src/wrapper/client.ts b/src/wrapper/client.ts
index 8fe0443ec..cc8a7358d 100644
--- a/src/wrapper/client.ts
+++ b/src/wrapper/client.ts
@@ -10,7 +10,10 @@ import {
   type HelloPayload,
   type WelcomePayload,
   type SendPayload,
+  type SendMeta,
+  type SendEnvelope,
   type DeliverEnvelope,
+  type ErrorPayload,
   type PayloadKind,
   PROTOCOL_VERSION,
 } from '../protocol/types.js';
@@ -24,6 +27,16 @@ export interface ClientConfig {
   agentName: string;
   /** Optional CLI identifier to surface to the dashboard */
   cli?: string;
+  /** Optional program identifier (e.g., 'claude', 'gpt-4o') */
+  program?: string;
+  /** Optional model identifier (e.g., 'claude-3-opus-2024-xx') */
+  model?: string;
+  /** Optional task description for registry/dashboard */
+  task?: string;
+  /** Optional working directory to surface in registry/dashboard */
+  workingDirectory?: string;
+  /** Suppress client-side console logging */
+  quiet?: boolean;
   reconnect: boolean;
   maxReconnectAttempts: number;
   reconnectDelayMs: number;
@@ -34,6 +47,7 @@ const DEFAULT_CLIENT_CONFIG: ClientConfig = {
   socketPath: DEFAULT_SOCKET_PATH,
   agentName: 'agent',
   cli: undefined,
+  quiet: false,
   reconnect: true,
   maxReconnectAttempts: 10,
   reconnectDelayMs: 100,
@@ -54,7 +68,7 @@ export class RelayClient {
   private _destroyed = false;
 
   // Event handlers
-  onMessage?: (from: string, payload: SendPayload, messageId: string) => void;
+  onMessage?: (from: string, payload: SendPayload, messageId: string, meta?: SendMeta) => void;
   onStateChange?: (state: ClientState) => void;
   onError?: (error: Error) => void;
 
@@ -72,6 +86,11 @@ export class RelayClient {
     return this.config.agentName;
   }
 
+  /** Get the session ID assigned by the server */
+  get currentSessionId(): string | undefined {
+    return this.sessionId;
+  }
+
   /**
    * Connect to the relay daemon.
    */
@@ -172,13 +191,14 @@ export class RelayClient {
    * @param kind - Message type (default: 'message')
    * @param data - Optional structured data
    * @param thread - Optional thread ID for grouping related messages
+   * @param meta - Optional message metadata (importance, replyTo, etc.)
    */
-  sendMessage(to: string, body: string, kind: PayloadKind = 'message', data?: Record<string, unknown>, thread?: string): boolean {
+  sendMessage(to: string, body: string, kind: PayloadKind = 'message', data?: Record<string, unknown>, thread?: string, meta?: SendMeta): boolean {
     if (this._state !== 'READY') {
       return false;
     }
 
-    const envelope: Envelope<SendPayload> = {
+    const envelope: SendEnvelope = {
       v: PROTOCOL_VERSION,
       type: 'SEND',
       id: uuid(),
@@ -190,6 +210,7 @@ export class RelayClient {
         data,
         thread,
       },
+      payload_meta: meta,
     };
 
     return this.send(envelope);
@@ -250,6 +271,10 @@ export class RelayClient {
       payload: {
         agent: this.config.agentName,
         cli: this.config.cli,
+        program: this.config.program,
+        model: this.config.model,
+        task: this.config.task,
+        workingDirectory: this.config.workingDirectory,
         capabilities: {
           ack: true,
           resume: true,
@@ -302,7 +327,7 @@ export class RelayClient {
         break;
 
       case 'ERROR':
-        console.error('[client] Server error:', envelope.payload);
+        this.handleErrorFrame(envelope as Envelope<ErrorPayload>);
         break;
 
       case 'BUSY':
@@ -317,7 +342,9 @@ export class RelayClient {
     this.reconnectAttempts = 0;
     this.reconnectDelay = this.config.reconnectDelayMs;
     this.setState('READY');
-    console.log(`[client] Connected as ${this.config.agentName} (session: ${this.sessionId})`);
+    if (!this.config.quiet) {
+      console.log(`[client] Connected as ${this.config.agentName} (session: ${this.sessionId})`);
+    }
   }
 
   private handleDeliver(envelope: DeliverEnvelope): void {
@@ -335,7 +362,7 @@ export class RelayClient {
 
     // Notify handler
     if (this.onMessage && envelope.from) {
-      this.onMessage(envelope.from, envelope.payload, envelope.id);
+      this.onMessage(envelope.from, envelope.payload, envelope.id, envelope.payload_meta);
     }
   }
 
@@ -349,6 +376,19 @@ export class RelayClient {
     });
   }
 
+  private handleErrorFrame(envelope: Envelope<ErrorPayload>): void {
+    console.error('[client] Server error:', envelope.payload);
+
+    if (envelope.payload.code === 'RESUME_TOO_OLD') {
+      if (this.resumeToken) {
+        console.warn('[client] Resume token rejected, clearing and requesting new session');
+      }
+      // Clear resume token so next HELLO starts a fresh session instead of looping on an invalid token
+      this.resumeToken = undefined;
+      this.sessionId = undefined;
+    }
+  }
+
   private handleDisconnect(): void {
     this.parser.reset();
     this.socket = undefined;
@@ -387,7 +427,9 @@ export class RelayClient {
     const delay = Math.min(this.reconnectDelay * jitter, this.config.reconnectMaxDelayMs);
     this.reconnectDelay *= 2;
 
-    console.log(`[client] Reconnecting in ${Math.round(delay)}ms (attempt ${this.reconnectAttempts})`);
+    if (!this.config.quiet) {
+      console.log(`[client] Reconnecting in ${Math.round(delay)}ms (attempt ${this.reconnectAttempts})`);
+    }
 
     this.reconnectTimer = setTimeout(() => {
       this.connect().catch(() => {
diff --git a/src/wrapper/parser.test.ts b/src/wrapper/parser.test.ts
index 7656a52f9..70a8f19fa 100644
--- a/src/wrapper/parser.test.ts
+++ b/src/wrapper/parser.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, beforeEach } from 'vitest';
-import { OutputParser, formatIncomingMessage } from './parser.js';
+import { OutputParser, formatIncomingMessage, parseSummaryFromOutput, parseSessionEndFromOutput, parseRelayMetadataFromOutput } from './parser.js';
 
 describe('OutputParser', () => {
   let parser: OutputParser;
@@ -12,22 +12,22 @@ describe('OutputParser', () => {
     parser = new OutputParser();
   });
 
-  describe('Inline format - @relay:target message', () => {
+  describe('Inline format - ->relay:target message', () => {
     it('parses basic inline relay command', () => {
-      const result = parser.parse('@relay:agent2 Hello there\n');
+      const result = parser.parse('->relay:agent2 Hello there\n');
 
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0]).toMatchObject({
         to: 'agent2',
         kind: 'message',
         body: 'Hello there',
-        raw: '@relay:agent2 Hello there',
+        raw: '->relay:agent2 Hello there',
       });
       expect(result.output).toBe('');
     });
 
     it('extracts target and body correctly', () => {
-      const result = parser.parse('@relay:supervisor This is a longer message with multiple words\n');
+      const result = parser.parse('->relay:supervisor This is a longer message with multiple words\n');
 
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].to).toBe('supervisor');
@@ -35,22 +35,30 @@ describe('OutputParser', () => {
     });
 
     it('only matches at start of line (after whitespace)', () => {
-      const result = parser.parse('  @relay:agent2 Indented message\n');
+      const result = parser.parse('  ->relay:agent2 Indented message\n');
 
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].to).toBe('agent2');
       expect(result.commands[0].body).toBe('Indented message');
     });
 
-    it('does not match @relay: in middle of line', () => {
-      const result = parser.parse('This is text @relay:agent2 should not match\n');
+    it('handles Gemini sparkle prefix (✦)', () => {
+      const result = parser.parse('✦ ->relay:Lead STATUS: Gem is ready\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0].to).toBe('Lead');
+      expect(result.commands[0].body).toBe('STATUS: Gem is ready');
+    });
+
+    it('does not match ->relay: in middle of line', () => {
+      const result = parser.parse('This is text ->relay:agent2 should not match\n');
 
       expect(result.commands).toHaveLength(0);
-      expect(result.output).toBe('This is text @relay:agent2 should not match\n');
+      expect(result.output).toBe('This is text ->relay:agent2 should not match\n');
     });
 
-    it('handles @thinking: variant', () => {
-      const result = parser.parse('@thinking:agent2 Considering the options\n');
+    it('handles ->thinking: variant', () => {
+      const result = parser.parse('->thinking:agent2 Considering the options\n');
 
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0]).toMatchObject({
@@ -61,7 +69,7 @@ describe('OutputParser', () => {
     });
 
     it('parses multiple inline commands', () => {
-      const result = parser.parse('@relay:agent1 First message\n@relay:agent2 Second message\n');
+      const result = parser.parse('->relay:agent1 First message\n->relay:agent2 Second message\n');
 
       expect(result.commands).toHaveLength(2);
       expect(result.commands[0].to).toBe('agent1');
@@ -72,7 +80,7 @@ describe('OutputParser', () => {
 
     it('parses multi-line inline command with indented continuation', () => {
       // TUI wrapping indents continuation lines
-      const result = parser.parse('@relay:agent2 First line\n   Second line\n');
+      const result = parser.parse('->relay:agent2 First line\n   Second line\n');
 
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].body).toBe('First line\n   Second line');
@@ -80,7 +88,7 @@ describe('OutputParser', () => {
     });
 
     it('does not swallow subsequent inline command after indented continuation', () => {
-      const result = parser.parse('@relay:agent1 First line\n   Second line\n@relay:agent2 Next\n');
+      const result = parser.parse('->relay:agent1 First line\n   Second line\n->relay:agent2 Next\n');
 
       expect(result.commands).toHaveLength(2);
       expect(result.commands[0].body).toBe('First line\n   Second line');
@@ -88,17 +96,35 @@ describe('OutputParser', () => {
       expect(result.output).toBe('');
     });
 
-    it('does not treat non-indented lines as continuation', () => {
-      // Non-indented lines after @relay should be regular output
-      const result = parser.parse('@relay:agent2 Message\nRegular output\n');
+    it('captures bullet list continuation lines', () => {
+      const input = '->relay:agent2 Updates for mcl/2z1:\n- Task A\n- Task B\n\nAfter\n';
+      const result = parser.parse(input);
 
       expect(result.commands).toHaveLength(1);
-      expect(result.commands[0].body).toBe('Message');
-      expect(result.output).toBe('Regular output\n');
+      expect(result.commands[0].body).toBe('Updates for mcl/2z1:\n- Task A\n- Task B');
+      expect(result.output).toBe('\nAfter\n');
+    });
+
+    it('captures non-indented paragraph continuation until blank line', () => {
+      const input = '->relay:lead Signing off. Progress report:\nSummary line one.\nSummary line two.\n\nNext output\n';
+      const result = parser.parse(input);
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0].body).toBe('Signing off. Progress report:\nSummary line one.\nSummary line two.');
+      expect(result.output).toBe('\nNext output\n');
+    });
+
+    it('stops continuation at prompt-ish line', () => {
+      const input = '->relay:agent2 Message body\n> \nFollow-up\n';
+      const result = parser.parse(input);
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0].body).toBe('Message body');
+      expect(result.output).toBe('> \nFollow-up\n');
     });
 
     it('does not require spaces in target name', () => {
-      const result = parser.parse('@relay:agent-with-dashes Message here\n');
+      const result = parser.parse('->relay:agent-with-dashes Message here\n');
 
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].to).toBe('agent-with-dashes');
@@ -194,25 +220,25 @@ describe('OutputParser', () => {
   });
 
   describe('Code fence handling', () => {
-    it('ignores @relay: inside code fences', () => {
-      const input = '```\n@relay:agent2 This should be ignored\n```\n';
+    it('ignores ->relay: inside code fences', () => {
+      const input = '```\n->relay:agent2 This should be ignored\n```\n';
       const result = parser.parse(input);
 
       expect(result.commands).toHaveLength(0);
-      expect(result.output).toBe('```\n@relay:agent2 This should be ignored\n```\n');
+      expect(result.output).toBe('```\n->relay:agent2 This should be ignored\n```\n');
     });
 
     it('tracks code fence state correctly', () => {
-      const input = 'Before fence\n```\n@relay:agent2 Inside fence\n```\nAfter fence\n@relay:agent3 Outside fence\n';
+      const input = 'Before fence\n```\n->relay:agent2 Inside fence\n```\nAfter fence\n->relay:agent3 Outside fence\n';
       const result = parser.parse(input);
 
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].to).toBe('agent3');
-      expect(result.output).toContain('@relay:agent2 Inside fence');
+      expect(result.output).toContain('->relay:agent2 Inside fence');
     });
 
     it('handles multiple code fences', () => {
-      const input = '```\n@relay:a1 First fence\n```\nBetween\n```\n@relay:a2 Second fence\n```\n@relay:a3 Outside\n';
+      const input = '```\n->relay:a1 First fence\n```\nBetween\n```\n->relay:a2 Second fence\n```\n->relay:a3 Outside\n';
       const result = parser.parse(input);
 
       expect(result.commands).toHaveLength(1);
@@ -220,11 +246,11 @@ describe('OutputParser', () => {
     });
 
     it('handles code fence with language specifier', () => {
-      const input = '```javascript\n@relay:agent2 Code example\n```\n';
+      const input = '```javascript\n->relay:agent2 Code example\n```\n';
       const result = parser.parse(input);
 
       expect(result.commands).toHaveLength(0);
-      expect(result.output).toContain('@relay:agent2 Code example');
+      expect(result.output).toContain('->relay:agent2 Code example');
     });
 
     it('does not interfere with block format in code fence', () => {
@@ -237,32 +263,32 @@ describe('OutputParser', () => {
   });
 
   describe('Escaping', () => {
-    it('\\@relay: outputs as @relay: without triggering command', () => {
-      const result = parser.parse('\\@relay:agent2 This is escaped\n');
+    it('\\->relay: outputs as ->relay: without triggering command', () => {
+      const result = parser.parse('\\->relay:agent2 This is escaped\n');
 
       expect(result.commands).toHaveLength(0);
-      expect(result.output).toBe('@relay:agent2 This is escaped\n');
+      expect(result.output).toBe('->relay:agent2 This is escaped\n');
     });
 
-    it('\\@thinking: outputs as @thinking: without triggering command', () => {
-      const result = parser.parse('\\@thinking:agent2 This is escaped\n');
+    it('\\->thinking: outputs as ->thinking: without triggering command', () => {
+      const result = parser.parse('\\->thinking:agent2 This is escaped\n');
 
       expect(result.commands).toHaveLength(0);
-      expect(result.output).toBe('@thinking:agent2 This is escaped\n');
+      expect(result.output).toBe('->thinking:agent2 This is escaped\n');
     });
 
     it('escapes work with indentation', () => {
-      const result = parser.parse('  \\@relay:agent2 Indented escape\n');
+      const result = parser.parse('  \\->relay:agent2 Indented escape\n');
 
       expect(result.commands).toHaveLength(0);
-      expect(result.output).toBe('  @relay:agent2 Indented escape\n');
+      expect(result.output).toBe('  ->relay:agent2 Indented escape\n');
     });
 
     it('only escapes at line start', () => {
-      const result = parser.parse('Text \\@relay:agent2 Not escaped\n');
+      const result = parser.parse('Text \\->relay:agent2 Not escaped\n');
 
       expect(result.commands).toHaveLength(0);
-      expect(result.output).toBe('Text \\@relay:agent2 Not escaped\n');
+      expect(result.output).toBe('Text \\->relay:agent2 Not escaped\n');
     });
   });
 
@@ -270,9 +296,9 @@ describe('OutputParser', () => {
     it('inline commands must be complete in single chunk (no cross-chunk buffering)', () => {
       // Inline relay commands split across chunks are NOT detected
       // This is intentional for minimal terminal interference
-      const result1 = parser.parse('@relay:agent2 Partial');
+      const result1 = parser.parse('->relay:agent2 Partial');
       expect(result1.commands).toHaveLength(0);
-      expect(result1.output).toBe('@relay:agent2 Partial'); // Passed through
+      expect(result1.output).toBe('->relay:agent2 Partial'); // Passed through
 
       const result2 = parser.parse(' line\n');
       expect(result2.commands).toHaveLength(0); // Not detected
@@ -290,18 +316,18 @@ describe('OutputParser', () => {
 
     it('flush() does not detect incomplete inline commands (no buffering)', () => {
       // Incomplete inline commands without newline are passed through, not buffered
-      const result1 = parser.parse('@relay:agent2 No newline');
-      expect(result1.output).toBe('@relay:agent2 No newline'); // Passed through
+      const result1 = parser.parse('->relay:agent2 No newline');
+      expect(result1.output).toBe('->relay:agent2 No newline'); // Passed through
 
       const result = parser.flush();
       expect(result.commands).toHaveLength(0); // Not detected
     });
 
     it('flush() clears all state', () => {
-      parser.parse('```\n@relay:agent2 In fence');
+      parser.parse('```\n->relay:agent2 In fence');
       parser.flush();
 
-      const result = parser.parse('@relay:agent3 After flush\n');
+      const result = parser.parse('->relay:agent3 After flush\n');
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].to).toBe('agent3');
     });
@@ -316,10 +342,10 @@ describe('OutputParser', () => {
     });
 
     it('reset() clears code fence state', () => {
-      parser.parse('```\n@relay:agent2 test');
+      parser.parse('```\n->relay:agent2 test');
       parser.reset();
 
-      const result = parser.parse('@relay:agent3 After reset\n');
+      const result = parser.parse('->relay:agent3 After reset\n');
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].to).toBe('agent3');
     });
@@ -355,7 +381,7 @@ describe('OutputParser', () => {
     });
 
     it('mixes relay commands with regular output', () => {
-      const input = 'Output 1\n@relay:agent2 Message\nOutput 2\n';
+      const input = 'Output 1\n->relay:agent2 Message\nOutput 2\n';
       const result = parser.parse(input);
 
       expect(result.commands).toHaveLength(1);
@@ -370,7 +396,7 @@ describe('OutputParser', () => {
     });
 
     it('handles target with special characters', () => {
-      const result = parser.parse('@relay:agent_2-test.v1 Message\n');
+      const result = parser.parse('->relay:agent_2-test.v1 Message\n');
 
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].to).toBe('agent_2-test.v1');
@@ -379,7 +405,7 @@ describe('OutputParser', () => {
     it('handles empty body in inline format', () => {
       // Note: The regex requires at least one character for the body (.+)
       // so this actually won't match as a command
-      const result = parser.parse('@relay:agent2 Test\n');
+      const result = parser.parse('->relay:agent2 Test\n');
 
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].body).toBe('Test');
@@ -396,10 +422,10 @@ describe('OutputParser', () => {
   describe('Parser options', () => {
     it('disables inline format when enableInline is false', () => {
       const customParser = new OutputParser({ enableInline: false });
-      const result = customParser.parse('@relay:agent2 Message\n');
+      const result = customParser.parse('->relay:agent2 Message\n');
 
       expect(result.commands).toHaveLength(0);
-      expect(result.output).toBe('@relay:agent2 Message\n');
+      expect(result.output).toBe('->relay:agent2 Message\n');
     });
 
     it('disables block format when enableBlock is false', () => {
@@ -424,9 +450,9 @@ describe('OutputParser', () => {
 
   describe('Complex scenarios', () => {
     it('handles multiple commands in one parse call', () => {
-      const input = `@relay:agent1 First
+      const input = `->relay:agent1 First
 Regular output
-@relay:agent2 Second
+->relay:agent2 Second
 [[RELAY]]{"to":"agent3","type":"message","body":"Third"}[[/RELAY]]
 More output
 `;
@@ -442,9 +468,9 @@ More output
 
     it('handles incremental parsing with multiple parse calls', () => {
       parser.parse('Line 1\n');
-      parser.parse('@relay:agent1 Message 1\n');
+      parser.parse('->relay:agent1 Message 1\n');
       parser.parse('Line 2\n');
-      const result = parser.parse('@relay:agent2 Message 2\n');
+      const result = parser.parse('->relay:agent2 Message 2\n');
 
       // Only the last parse call returns commands from that call
       expect(result.commands).toHaveLength(1);
@@ -468,9 +494,9 @@ More output
 
     it('preserves order of commands and output', () => {
       const input = `Out1
-@relay:agent1 Msg1
+->relay:agent1 Msg1
 Out2
-@relay:agent2 Msg2
+->relay:agent2 Msg2
 Out3
 `;
       const result = parser.parse(input);
@@ -482,12 +508,115 @@ Out3
     });
   });
 
+  describe('Cross-project messaging syntax', () => {
+    it('parses project:agent syntax for cross-project messaging', () => {
+      const result = parser.parse('->relay:myproject:agent2 Hello from another project\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0]).toMatchObject({
+        to: 'agent2',
+        project: 'myproject',
+        kind: 'message',
+        body: 'Hello from another project',
+      });
+    });
+
+    it('parses local agent without project', () => {
+      const result = parser.parse('->relay:agent2 Local message\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0].to).toBe('agent2');
+      expect(result.commands[0].project).toBeUndefined();
+    });
+
+    it('handles project names with dashes and underscores', () => {
+      const result = parser.parse('->relay:my-project_v2:some-agent Hello\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0].to).toBe('some-agent');
+      expect(result.commands[0].project).toBe('my-project_v2');
+    });
+
+    it('only splits on first colon to allow colons in agent names', () => {
+      const result = parser.parse('->relay:proj:agent:with:colons Message\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0].to).toBe('agent:with:colons');
+      expect(result.commands[0].project).toBe('proj');
+    });
+
+    it('handles cross-project with ->thinking: variant', () => {
+      const result = parser.parse('->thinking:otherproj:agent2 Thinking about something\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0]).toMatchObject({
+        to: 'agent2',
+        project: 'otherproj',
+        kind: 'thinking',
+        body: 'Thinking about something',
+      });
+    });
+
+    it('handles cross-project broadcast', () => {
+      const result = parser.parse('->relay:prod-project:* Broadcast to all in prod\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0].to).toBe('*');
+      expect(result.commands[0].project).toBe('prod-project');
+    });
+
+    it('handles cross-project with thread syntax', () => {
+      const result = parser.parse('->relay:proj:agent [thread:abc123] Threaded cross-project message\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0]).toMatchObject({
+        to: 'agent',
+        project: 'proj',
+        thread: 'abc123',
+        body: 'Threaded cross-project message',
+      });
+    });
+
+    it('parses cross-project in block format with explicit project field', () => {
+      const result = parser.parse('[[RELAY]]{"to":"agent2","project":"otherproj","type":"message","body":"Hello"}[[/RELAY]]\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0]).toMatchObject({
+        to: 'agent2',
+        project: 'otherproj',
+        kind: 'message',
+        body: 'Hello',
+      });
+    });
+
+    it('parses cross-project in block format with colon syntax in to field', () => {
+      const result = parser.parse('[[RELAY]]{"to":"myproj:agent2","type":"message","body":"Hi"}[[/RELAY]]\n');
+
+      expect(result.commands).toHaveLength(1);
+      expect(result.commands[0]).toMatchObject({
+        to: 'agent2',
+        project: 'myproj',
+        kind: 'message',
+        body: 'Hi',
+      });
+    });
+
+    it('explicit project field takes precedence over colon syntax in block format', () => {
+      const result = parser.parse('[[RELAY]]{"to":"ignored:agent2","project":"explicit","type":"message","body":"Test"}[[/RELAY]]\n');
+
+      expect(result.commands).toHaveLength(1);
+      // When explicit project is set, the to field is used as-is
+      expect(result.commands[0].to).toBe('ignored:agent2');
+      expect(result.commands[0].project).toBe('explicit');
+    });
+  });
+
   describe('Configurable prefix', () => {
-    it('uses default @relay: prefix', () => {
+    it('uses default ->relay: prefix', () => {
       const defaultParser = new OutputParser();
-      expect(defaultParser.prefix).toBe('@relay:');
+      expect(defaultParser.prefix).toBe('->relay:');
 
-      const result = defaultParser.parse('@relay:agent2 Hello\n');
+      const result = defaultParser.parse('->relay:agent2 Hello\n');
       expect(result.commands).toHaveLength(1);
       expect(result.commands[0].to).toBe('agent2');
     });
@@ -502,12 +631,12 @@ Out3
       expect(result.commands[0].body).toBe('Hello from Gemini');
     });
 
-    it('ignores @relay: when using >> prefix', () => {
-      const customParser = new OutputParser({ prefix: '>>' });
+    it('ignores ->relay: when using @msg: prefix', () => {
+      const customParser = new OutputParser({ prefix: '@msg:' });
 
-      const result = customParser.parse('@relay:agent2 Should not match\n');
+      const result = customParser.parse('->relay:agent2 Should not match\n');
       expect(result.commands).toHaveLength(0);
-      expect(result.output).toBe('@relay:agent2 Should not match\n');
+      expect(result.output).toBe('->relay:agent2 Should not match\n');
     });
 
     it('uses custom prefix /relay', () => {
@@ -594,3 +723,183 @@ describe('formatIncomingMessage', () => {
     expect(result).toBe('\n[MSG] from agent1: Line 1\nLine 2\nLine 3\n');
   });
 });
+
+describe('parseSummaryFromOutput', () => {
+  it('parses valid JSON summary block', () => {
+    const output = `Some output
+[[SUMMARY]]
+{
+  "currentTask": "Implementing auth",
+  "context": "Working on login flow",
+  "files": ["src/auth.ts"]
+}
+[[/SUMMARY]]
+More output`;
+
+    const summary = parseSummaryFromOutput(output);
+    expect(summary).not.toBeNull();
+    expect(summary).toEqual({
+      currentTask: 'Implementing auth',
+      context: 'Working on login flow',
+      files: ['src/auth.ts'],
+    });
+  });
+
+  it('parses summary with all fields', () => {
+    const output = `[[SUMMARY]]{"currentTask":"Task 1","completedTasks":["T0"],"decisions":["Use JWT"],"context":"Auth work","files":["a.ts","b.ts"]}[[/SUMMARY]]`;
+
+    const summary = parseSummaryFromOutput(output);
+    expect(summary).toEqual({
+      currentTask: 'Task 1',
+      completedTasks: ['T0'],
+      decisions: ['Use JWT'],
+      context: 'Auth work',
+      files: ['a.ts', 'b.ts'],
+    });
+  });
+
+  it('returns null when no summary block exists', () => {
+    const output = 'Just regular output without any summary block';
+
+    const summary = parseSummaryFromOutput(output);
+    expect(summary).toBeNull();
+  });
+
+  it('returns null for invalid JSON', () => {
+    const output = '[[SUMMARY]]not valid json[[/SUMMARY]]';
+
+    const summary = parseSummaryFromOutput(output);
+    expect(summary).toBeNull();
+  });
+
+  it('handles empty summary block', () => {
+    const output = '[[SUMMARY]]{}[[/SUMMARY]]';
+
+    const summary = parseSummaryFromOutput(output);
+    expect(summary).toEqual({});
+  });
+});
+
+describe('parseSessionEndFromOutput', () => {
+  it('parses valid JSON session end block', () => {
+    const output = `Some output
+[[SESSION_END]]
+{
+  "summary": "Completed auth module",
+  "completedTasks": ["login", "logout"]
+}
+[[/SESSION_END]]
+More output`;
+
+    const result = parseSessionEndFromOutput(output);
+    expect(result).not.toBeNull();
+    expect(result).toEqual({
+      summary: 'Completed auth module',
+      completedTasks: ['login', 'logout'],
+    });
+  });
+
+  it('parses empty session end block', () => {
+    const output = '[[SESSION_END]][[/SESSION_END]]';
+
+    const result = parseSessionEndFromOutput(output);
+    expect(result).toEqual({});
+  });
+
+  it('parses session end with only summary', () => {
+    const output = '[[SESSION_END]]{"summary":"All done!"}[[/SESSION_END]]';
+
+    const result = parseSessionEndFromOutput(output);
+    expect(result).toEqual({ summary: 'All done!' });
+  });
+
+  it('treats non-JSON content as plain summary', () => {
+    const output = '[[SESSION_END]]Work completed successfully[[/SESSION_END]]';
+
+    const result = parseSessionEndFromOutput(output);
+    expect(result).toEqual({ summary: 'Work completed successfully' });
+  });
+
+  it('returns null when no session end block exists', () => {
+    const output = 'Regular output without session end';
+
+    const result = parseSessionEndFromOutput(output);
+    expect(result).toBeNull();
+  });
+
+  it('handles multiline plain text summary', () => {
+    const output = `[[SESSION_END]]
+Completed the following:
+- Feature A
+- Feature B
+[[/SESSION_END]]`;
+
+    const result = parseSessionEndFromOutput(output);
+    expect(result?.summary).toContain('Completed the following:');
+    expect(result?.summary).toContain('Feature A');
+  });
+});
+
+describe('parseRelayMetadataFromOutput', () => {
+  it('parses valid metadata block', () => {
+    const output = `Some output
+[[RELAY_METADATA]]
+{
+  "subject": "Task update",
+  "importance": 80,
+  "replyTo": "msg-abc123",
+  "ackRequired": true
+}
+[[/RELAY_METADATA]]
+More output`;
+
+    const result = parseRelayMetadataFromOutput(output);
+    expect(result.found).toBe(true);
+    expect(result.valid).toBe(true);
+    expect(result.metadata).toEqual({
+      subject: 'Task update',
+      importance: 80,
+      replyTo: 'msg-abc123',
+      ackRequired: true,
+    });
+    expect(result.rawContent).toContain('"subject"');
+  });
+
+  it('returns not found when no metadata block exists', () => {
+    const output = 'Regular output without any metadata block';
+
+    const result = parseRelayMetadataFromOutput(output);
+    expect(result.found).toBe(false);
+    expect(result.valid).toBe(false);
+    expect(result.metadata).toBeNull();
+    expect(result.rawContent).toBeNull();
+  });
+
+  it('returns invalid for malformed JSON', () => {
+    const output = '[[RELAY_METADATA]]not valid json[[/RELAY_METADATA]]';
+
+    const result = parseRelayMetadataFromOutput(output);
+    expect(result.found).toBe(true);
+    expect(result.valid).toBe(false);
+    expect(result.metadata).toBeNull();
+    expect(result.rawContent).toBe('not valid json');
+  });
+
+  it('handles empty metadata block', () => {
+    const output = '[[RELAY_METADATA]]{}[[/RELAY_METADATA]]';
+
+    const result = parseRelayMetadataFromOutput(output);
+    expect(result.found).toBe(true);
+    expect(result.valid).toBe(true);
+    expect(result.metadata).toEqual({});
+  });
+
+  it('parses metadata with partial fields', () => {
+    const output = '[[RELAY_METADATA]]{"subject":"Quick note"}[[/RELAY_METADATA]]';
+
+    const result = parseRelayMetadataFromOutput(output);
+    expect(result.found).toBe(true);
+    expect(result.valid).toBe(true);
+    expect(result.metadata).toEqual({ subject: 'Quick note' });
+  });
+});
diff --git a/src/wrapper/parser.ts b/src/wrapper/parser.ts
index 2b9e2e625..a38c93a9e 100644
--- a/src/wrapper/parser.ts
+++ b/src/wrapper/parser.ts
@@ -3,13 +3,13 @@
  * Extracts relay commands from agent terminal output.
  *
  * Supports two formats:
- * 1. Inline: @relay:<target> <message> (single line, start of line only)
+ * 1. Inline: ->relay:<target> <message> (single line, start of line only)
  * 2. Block: [[RELAY]]{ json }[[/RELAY]] (multi-line, structured)
  *
  * Rules:
  * - Inline only matches at start of line (after whitespace)
  * - Ignores content inside code fences
- * - Escape with \@relay: to output literal
+ * - Escape with \->relay: to output literal
  * - Block format is preferred for structured data
  */
 
@@ -22,16 +22,19 @@ export interface ParsedCommand {
   data?: Record<string, unknown>;
   /** Optional thread ID for grouping related messages */
   thread?: string;
+  /** Optional project for cross-project messaging (e.g., ->relay:project:agent) */
+  project?: string;
   raw: string;
+  meta?: ParsedMessageMetadata;
 }
 
 export interface ParserOptions {
   maxBlockBytes?: number;
   enableInline?: boolean;
   enableBlock?: boolean;
-  /** Relay prefix pattern (default: '@relay:') */
+  /** Relay prefix pattern (default: '->relay:') */
   prefix?: string;
-  /** Thinking prefix pattern (default: '@thinking:') */
+  /** Thinking prefix pattern (default: '->thinking:') */
   thinkingPrefix?: string;
 }
 
@@ -39,13 +42,19 @@ const DEFAULT_OPTIONS: Required<ParserOptions> = {
   maxBlockBytes: 1024 * 1024, // 1 MiB
   enableInline: true,
   enableBlock: true,
-  prefix: '@relay:',
-  thinkingPrefix: '@thinking:',
+  prefix: '->relay:',
+  thinkingPrefix: '->thinking:',
 };
 
 // Static patterns (not prefix-dependent)
 const BLOCK_END = /\[\[\/RELAY\]\]/;
-const CODE_FENCE = /^```/;
+const BLOCK_METADATA_START = '[[RELAY_METADATA]]';
+const BLOCK_METADATA_END = /\[\[\/RELAY_METADATA\]\]/;
+const CODE_FENCE = /^```/;// Continuation helpers
+const BULLET_OR_NUMBERED_LIST = /^[ \t]*([\-*•◦‣⏺◆◇○□■]|[0-9]+[.)])\s+/;
+const PROMPTISH_LINE = /^[\s]*[>$%#➜›»][\s]*$/;
+const RELAY_INJECTION_PREFIX = /^\s*Relay message from /;
+const MAX_INLINE_CONTINUATION_LINES = 30;
 
 /**
  * Escape special regex characters in a string
@@ -56,19 +65,20 @@ function escapeRegex(str: string): string {
 
 /**
  * Build inline pattern for a given prefix
- * Allow common input prefixes: >, $, %, #, →, ➜, bullets (●•◦‣⁃-*⏺◆◇○□■), and their variations
+ * Allow common input prefixes: >, $, %, #, →, ➜, bullets (●•◦‣⁃-*⏺◆◇○□■), box chars (│┃┆┇┊┋╎╏), and their variations
  *
- * Supports optional thread syntax: @relay:Target [thread:id] message
+ * Supports optional thread syntax: ->relay:Target [thread:id] message
  * Thread IDs can contain alphanumeric chars, hyphens, underscores
  */
 function buildInlinePattern(prefix: string): RegExp {
   const escaped = escapeRegex(prefix);
   // Group 1: target, Group 2: optional thread ID (without brackets), Group 3: message body
-  return new RegExp(`^(?:\\s*(?:[>$%#→➜›»●•◦‣⁃\\-*⏺◆◇○□■]\\s*)*)?${escaped}(\\S+)(?:\\s+\\[thread:([\\w-]+)\\])?\\s+(.+)$`);
+  // Includes box drawing characters (│┃┆┇┊┋╎╏) and sparkle (✦) for Gemini CLI output
+  return new RegExp(`^(?:\\s*(?:[>$%#→➜›»●•◦‣⁃\\-*⏺◆◇○□■│┃┆┇┊┋╎╏✦]\\s*)*)?${escaped}(\\S+)(?:\\s+\\[thread:([\\w-]+)\\])?\\s+(.+)$`);
 }
 
 /**
- * Build escape pattern for a given prefix (e.g., \@relay: or \>>)
+ * Build escape pattern for a given prefix (e.g., \->relay: or \->)
  */
 function buildEscapePattern(prefix: string, thinkingPrefix: string): RegExp {
   // Extract the first character(s) that would be escaped
@@ -81,6 +91,29 @@ function buildEscapePattern(prefix: string, thinkingPrefix: string): RegExp {
 // eslint-disable-next-line no-control-regex
 const ANSI_PATTERN = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b\].*?(?:\x07|\x1b\\)|\r/g;
 
+/**
+ * Parse a target string that may contain cross-project syntax.
+ * Supports: "agent" (local) or "project:agent" (cross-project)
+ *
+ * @param target The raw target string from the relay command
+ * @returns Object with `to` (agent name) and optional `project`
+ */
+function parseTarget(target: string): { to: string; project?: string } {
+  // Check for cross-project syntax: project:agent
+  // Only split on FIRST colon to allow agent names with colons
+  const colonIndex = target.indexOf(':');
+
+  if (colonIndex > 0 && colonIndex < target.length - 1) {
+    // Has a colon with content on both sides
+    const project = target.substring(0, colonIndex);
+    const agent = target.substring(colonIndex + 1);
+    return { to: agent, project };
+  }
+
+  // Local target (no colon or malformed)
+  return { to: target };
+}
+
 /**
  * Strip ANSI escape codes from a string for pattern matching.
  */
@@ -93,6 +126,8 @@ export class OutputParser {
   private inCodeFence = false;
   private inBlock = false;
   private blockBuffer = '';
+  private blockType: 'RELAY' | 'RELAY_METADATA' | null = null;
+  private lastParsedMetadata: ParsedMessageMetadata | null = null;
 
   // Dynamic patterns based on prefix configuration
   private inlineRelayPattern: RegExp;
@@ -127,17 +162,17 @@ export class OutputParser {
     let output = '';
 
     // If we're inside a block, accumulate until we see the end
-    if (this.inBlock) {
-      return this.parseInBlockMode(data, commands);
+    if (this.inBlock && this.blockType) {
+      return this.parseInBlockMode(data, commands, this.blockType);
     }
 
-    // Find [[RELAY]] that's at the start of a line (or start of input)
-    // and NOT inside a code fence
-    const blockStartIdx = this.findBlockStart(data);
+    // Find [[RELAY_METADATA]] or [[RELAY]] that's at the start of a line
+    const blockStart = this.findBlockStart(data);
 
-    if (this.options.enableBlock && blockStartIdx !== -1) {
-      const before = data.substring(0, blockStartIdx);
-      const after = data.substring(blockStartIdx + '[[RELAY]]'.length);
+    if (this.options.enableBlock && blockStart.index !== -1 && blockStart.identifier) {
+      const blockStartIdentifier = blockStart.identifier;
+      const before = data.substring(0, blockStart.index);
+      const after = data.substring(blockStart.index + blockStartIdentifier.length);
 
       // Output everything before the block start
       if (before) {
@@ -147,6 +182,7 @@ export class OutputParser {
 
       // Enter block mode
       this.inBlock = true;
+      this.blockType = blockStartIdentifier === BLOCK_METADATA_START ? 'RELAY_METADATA' : 'RELAY';
       this.blockBuffer = after;
 
       // Check size limit before processing
@@ -154,12 +190,14 @@ export class OutputParser {
         console.error('[parser] Block too large, discarding');
         this.inBlock = false;
         this.blockBuffer = '';
+        this.blockType = null;
         return { commands, output };
       }
 
       // Check if block ends in same chunk
-      if (BLOCK_END.test(this.blockBuffer)) {
-        const blockResult = this.finishBlock();
+      const blockEndPattern = this.blockType === 'RELAY_METADATA' ? BLOCK_METADATA_END : BLOCK_END;
+      if (blockEndPattern.test(this.blockBuffer)) {
+        const blockResult = this.finishBlock(this.blockType);
         if (blockResult.command) {
           commands.push(blockResult.command);
         }
@@ -180,66 +218,76 @@ export class OutputParser {
   }
 
   /**
-   * Find [[RELAY]] that's at the start of a line and not inside a code fence.
-   * Returns the index, or -1 if not found.
+   * Find [[RELAY_METADATA]] or [[RELAY]] that's at the start of a line and not inside a code fence.
+   * Returns the index and identifier, or -1 and null if not found.
    */
-  private findBlockStart(data: string): number {
+  private findBlockStart(data: string): { index: number; identifier: string | null } {
     // Track code fence state through the data
     let inFence = this.inCodeFence;
     let searchStart = 0;
 
+    // Prioritize RELAY_METADATA over RELAY
+    const blockIdentifiers = [BLOCK_METADATA_START, '[[RELAY]]'];
+
     while (searchStart < data.length) {
-      // Look for next [[RELAY]] or code fence
-      const relayIdx = data.indexOf('[[RELAY]]', searchStart);
-      const fenceIdx = data.indexOf('```', searchStart);
+      let earliestBlockIdx = -1;
+      let earliestBlockIdentifier: string | null = null;
+
+      for (const identifier of blockIdentifiers) {
+        const currentBlockIdx = data.indexOf(identifier, searchStart);
+        if (currentBlockIdx !== -1 && (earliestBlockIdx === -1 || currentBlockIdx < earliestBlockIdx)) {
+          earliestBlockIdx = currentBlockIdx;
+          earliestBlockIdentifier = identifier;
+        }
+      }
 
-      // No more [[RELAY]] found
-      if (relayIdx === -1) {
+      // No more blocks found
+      if (earliestBlockIdx === -1) {
         // Still update code fence state for remaining data
+        let fenceIdx = data.indexOf('```', searchStart);
         while (fenceIdx !== -1) {
-          const nextFence = data.indexOf('```', searchStart);
-          if (nextFence === -1) break;
           inFence = !inFence;
-          searchStart = nextFence + 3;
+          searchStart = fenceIdx + 3;
+          fenceIdx = data.indexOf('```', searchStart);
         }
-        return -1;
+        return { index: -1, identifier: null };
       }
 
-      // Process any code fences before this [[RELAY]]
+      // Process any code fences before this block
       let tempIdx = searchStart;
       while (true) {
         const nextFence = data.indexOf('```', tempIdx);
-        if (nextFence === -1 || nextFence >= relayIdx) break;
+        if (nextFence === -1 || nextFence >= earliestBlockIdx) break;
         inFence = !inFence;
         tempIdx = nextFence + 3;
       }
 
-      // If we're inside a code fence, skip this [[RELAY]]
+      // If we're inside a code fence, skip this block
       if (inFence) {
-        searchStart = relayIdx + 9; // Skip past [[RELAY]]
+        searchStart = earliestBlockIdx + (earliestBlockIdentifier?.length ?? 0); // Skip past the block
         continue;
       }
 
-      // Check if [[RELAY]] is at start of a line
-      if (relayIdx === 0) {
-        return 0; // At very start
+      // Check if block is at start of a line
+      if (earliestBlockIdx === 0) {
+        return { index: 0, identifier: earliestBlockIdentifier }; // At very start
       }
 
       // Look backwards for the start of line
-      const beforeRelay = data.substring(0, relayIdx);
-      const lastNewline = beforeRelay.lastIndexOf('\n');
-      const lineStart = beforeRelay.substring(lastNewline + 1);
+      const beforeBlock = data.substring(0, earliestBlockIdx);
+      const lastNewline = beforeBlock.lastIndexOf('\n');
+      const lineStart = beforeBlock.substring(lastNewline + 1);
 
-      // Must be only whitespace before [[RELAY]] on this line
+      // Must be only whitespace before block on this line
       if (/^\s*$/.test(lineStart)) {
-        return relayIdx;
+        return { index: earliestBlockIdx, identifier: earliestBlockIdentifier };
       }
 
       // Not at start of line, keep searching
-      searchStart = relayIdx + 9;
+      searchStart = earliestBlockIdx + (earliestBlockIdentifier?.length ?? 0);
     }
 
-    return -1;
+    return { index: -1, identifier: null };
   }
 
   /**
@@ -257,6 +305,61 @@ export class OutputParser {
     const lines = data.split('\n');
     const hasTrailingNewline = data.endsWith('\n');
 
+    const isInlineStart = (line: string): boolean => {
+      return this.inlineRelayPattern.test(line) || this.inlineThinkingPattern.test(line);
+    };
+
+    const isBlockMarker = (line: string): boolean => {
+      return CODE_FENCE.test(line) || line.includes('[[RELAY]]') || BLOCK_END.test(line);
+    };
+
+    const shouldStopContinuation = (line: string, continuationCount: number, lines: string[], currentIndex: number): boolean => {
+      const trimmed = line.trim();
+      if (isInlineStart(line)) return true;
+      if (isBlockMarker(line)) return true;
+      if (PROMPTISH_LINE.test(trimmed)) return true;
+      if (RELAY_INJECTION_PREFIX.test(line)) return true; // Avoid swallowing injected inbound messages
+
+      // Allow blank lines only in structured content like tables or between numbered sections
+      if (trimmed === '') {
+        // If we haven't started continuation yet, stop on blank
+        if (continuationCount === 0) return true;
+
+        // Look ahead to see if there's more content that looks like structured markdown
+        for (let j = currentIndex + 1; j < lines.length; j++) {
+          const nextLine = lines[j].trim();
+          if (nextLine === '') {
+            // Double blank line always stops
+            return true;
+          }
+          // Only continue for table rows or numbered list items after blank
+          if (/^\|/.test(nextLine)) return false; // Table row
+          if (/^\d+[.)]\s/.test(nextLine)) return false; // Numbered list like "1." or "2)"
+          // Stop for anything else after a blank line
+          return true;
+        }
+        return true; // No more content, stop
+      }
+      return false;
+    };
+
+    const isContinuationLine = (
+      original: string,
+      stripped: string,
+      prevStripped: string,
+      continuationCount: number
+    ): boolean => {
+      // Note: shouldStopContinuation is already checked in the main loop before calling this
+      if (/^[ \t]/.test(original)) return true; // Indented lines from TUI wrapping
+      if (BULLET_OR_NUMBERED_LIST.test(stripped)) return true; // Bullet/numbered lists after ->relay:
+      const prevTrimmed = prevStripped.trimEnd();
+      const prevSuggestsContinuation = prevTrimmed !== '' && /[:;,\-–—…]$/.test(prevTrimmed);
+      if (prevSuggestsContinuation) return true;
+      // If we've already continued once, allow subsequent lines until a stop condition
+      if (continuationCount > 0) return true;
+      return false;
+    };
+
     const outputLines: string[] = [];
     let strippedCount = 0;
 
@@ -284,6 +387,7 @@ export class OutputParser {
           let body = result.command.body;
           const rawLines = [result.command.raw];
           let consumed = 0;
+          let continuationLines = 0;
 
           while (i + 1 < lines.length) {
             const nextIsLast = i + 1 === lines.length - 1;
@@ -295,32 +399,25 @@ export class OutputParser {
             }
 
             const nextStripped = stripAnsi(nextLine);
+            const prevStripped = stripAnsi(rawLines[rawLines.length - 1] ?? '');
 
-            // Stop at empty lines - they end the continuation
-            if (nextStripped.trim() === '') {
+            // Stop if this line clearly marks a new block, prompt, or inline command
+            if (shouldStopContinuation(nextStripped, continuationLines, lines, i + 1)) {
               break;
             }
 
-            // Stop if the next line starts another inline command, code fence, or block marker
-            if (
-              this.inlineRelayPattern.test(nextStripped) ||
-              this.inlineThinkingPattern.test(nextStripped) ||
-              CODE_FENCE.test(nextStripped) ||
-              nextStripped.includes('[[RELAY]]') ||
-              BLOCK_END.test(nextStripped)
-            ) {
+            if (continuationLines >= MAX_INLINE_CONTINUATION_LINES) {
               break;
             }
 
-            // Only consume as continuation if the line is INDENTED (starts with whitespace)
-            // This handles TUI wrapping where continuation lines are indented
-            // Non-indented lines are regular output, not continuation
-            if (!/^[ \t]/.test(nextLine)) {
+            // Consume as continuation if it looks like it belongs to the ->relay message
+            if (!isContinuationLine(nextLine, nextStripped, prevStripped, continuationLines)) {
               break;
             }
 
             consumed++;
             i++; // Skip the consumed continuation line
+            continuationLines++;
             body += '\n' + nextLine;
             rawLines.push(nextLine);
           }
@@ -360,7 +457,7 @@ export class OutputParser {
   /**
    * Parse while inside a [[RELAY]] block - buffer until we see [[/RELAY]].
    */
-  private parseInBlockMode(data: string, commands: ParsedCommand[]): { commands: ParsedCommand[]; output: string } {
+  private parseInBlockMode(data: string, commands: ParsedCommand[], blockType: 'RELAY' | 'RELAY_METADATA'): { commands: ParsedCommand[]; output: string } {
     this.blockBuffer += data;
 
     // Check size limit
@@ -368,12 +465,14 @@ export class OutputParser {
       console.error('[parser] Block too large, discarding');
       this.inBlock = false;
       this.blockBuffer = '';
+      this.blockType = null;
       return { commands, output: '' };
     }
 
     // Check for block end
-    if (BLOCK_END.test(this.blockBuffer)) {
-      const result = this.finishBlock();
+    const blockEndPattern = blockType === 'RELAY_METADATA' ? BLOCK_METADATA_END : BLOCK_END;
+    if (blockEndPattern.test(this.blockBuffer)) {
+      const result = this.finishBlock(blockType);
       if (result.command) {
         commands.push(result.command);
       }
@@ -428,12 +527,14 @@ export class OutputParser {
       const relayMatch = stripped.match(this.inlineRelayPattern);
       if (relayMatch) {
         const [raw, target, threadId, body] = relayMatch;
+        const { to, project } = parseTarget(target);
         return {
           command: {
-            to: target,
+            to,
             kind: 'message',
             body,
             thread: threadId || undefined, // undefined if no thread specified
+            project, // undefined if local, set if cross-project
             raw,
           },
           output: null, // Don't output relay commands
@@ -443,12 +544,14 @@ export class OutputParser {
       const thinkingMatch = stripped.match(this.inlineThinkingPattern);
       if (thinkingMatch) {
         const [raw, target, threadId, body] = thinkingMatch;
+        const { to, project } = parseTarget(target);
         return {
           command: {
-            to: target,
+            to,
             kind: 'thinking',
             body,
             thread: threadId || undefined,
+            project,
             raw,
           },
           output: null,
@@ -464,37 +567,72 @@ export class OutputParser {
    * Finish processing a block and extract command.
    * Returns the command (if valid) and any remaining content after [[/RELAY]].
    */
-  private finishBlock(): { command: ParsedCommand | null; remaining: string | null } {
-    const endIdx = this.blockBuffer.indexOf('[[/RELAY]]');
+  private finishBlock(blockType: 'RELAY' | 'RELAY_METADATA'): { command: ParsedCommand | null; remaining: string | null; metadata: ParsedMessageMetadata | null } {
+    const blockEndIdentifier = blockType === 'RELAY_METADATA' ? BLOCK_METADATA_END.source : BLOCK_END.source;
+    const endIdx = this.blockBuffer.indexOf(blockEndIdentifier.replace(/\\/g, '')); // Remove regex escapes for indexOf
     const jsonStr = this.blockBuffer.substring(0, endIdx).trim();
-    const remaining = this.blockBuffer.substring(endIdx + '[[/RELAY]]'.length) || null;
+    const remaining = this.blockBuffer.substring(endIdx + blockEndIdentifier.replace(/\\/g, '').length) || null;
 
     this.inBlock = false;
     this.blockBuffer = '';
+    this.blockType = null;
+
+    if (blockType === 'RELAY_METADATA') {
+      try {
+        const metadata = JSON.parse(jsonStr) as ParsedMessageMetadata;
+        this.lastParsedMetadata = metadata;
+        return { command: null, remaining, metadata };
+      } catch (err) {
+        console.error('[parser] Invalid JSON in RELAY_METADATA block:', err);
+        this.lastParsedMetadata = null;
+        return { command: null, remaining, metadata: null };
+      }
+    } else { // blockType === 'RELAY'
+      try {
+        const parsed = JSON.parse(jsonStr);
+
+        // Validate required fields
+        if (!parsed.to || !parsed.type) {
+          console.error('[parser] Block missing required fields (to, type)');
+          this.lastParsedMetadata = null; // Clear metadata even if RELAY block is invalid
+          return { command: null, remaining, metadata: null };
+        }
 
-    try {
-      const parsed = JSON.parse(jsonStr);
+        // Handle cross-project syntax in block format
+        // Supports both explicit "project" field and "project:agent" in "to" field
+        let to = parsed.to;
+        let project = parsed.project;
 
-      // Validate required fields
-      if (!parsed.to || !parsed.type) {
-        console.error('[parser] Block missing required fields (to, type)');
-        return { command: null, remaining };
-      }
+        if (!project && typeof to === 'string') {
+          // Check if "to" field uses project:agent syntax
+          const targetParsed = parseTarget(to);
+          to = targetParsed.to;
+          project = targetParsed.project;
+        }
 
-      return {
-        command: {
-          to: parsed.to,
+        const command: ParsedCommand = {
+          to,
           kind: parsed.type as PayloadKind,
           body: parsed.body ?? parsed.text ?? '',
           data: parsed.data,
           thread: parsed.thread || undefined,
+          project: project || undefined,
           raw: jsonStr,
-        },
-        remaining,
-      };
-    } catch (err) {
-      console.error('[parser] Invalid JSON in block:', err);
-      return { command: null, remaining };
+          meta: this.lastParsedMetadata || undefined, // Attach last parsed metadata
+        };
+
+        this.lastParsedMetadata = null; // Clear after use
+
+        return {
+          command,
+          remaining,
+          metadata: null,
+        };
+      } catch (err) {
+        console.error('[parser] Invalid JSON in RELAY block:', err);
+        this.lastParsedMetadata = null;
+        return { command: null, remaining, metadata: null };
+      }
     }
   }
 
@@ -505,6 +643,8 @@ export class OutputParser {
     const result = this.parse('\n');
     this.inBlock = false;
     this.blockBuffer = '';
+    this.blockType = null;
+    this.lastParsedMetadata = null;
     this.inCodeFence = false;
     return result;
   }
@@ -515,6 +655,8 @@ export class OutputParser {
   reset(): void {
     this.inBlock = false;
     this.blockBuffer = '';
+    this.blockType = null;
+    this.lastParsedMetadata = null;
     this.inCodeFence = false;
   }
 }
@@ -526,3 +668,153 @@ export function formatIncomingMessage(from: string, body: string, kind: PayloadK
   const prefix = kind === 'thinking' ? '[THINKING]' : '[MSG]';
   return `\n${prefix} from ${from}: ${body}\n`;
 }
+
+/**
+ * Parsed message metadata block from agent output.
+ */
+export interface ParsedMessageMetadata {
+  subject?: string;
+  importance?: number;
+  replyTo?: string;
+  ackRequired?: boolean;
+}
+
+/**
+ * Result of attempting to parse a RELAY_METADATA block.
+ */
+export interface MetadataParseResult {
+  found: boolean;
+  valid: boolean;
+  metadata: ParsedMessageMetadata | null;
+  rawContent: string | null;  // Raw block content for deduplication
+}
+
+/**
+ * Parse [[RELAY_METADATA]]...[[/RELAY_METADATA]] blocks from agent output.
+ * Agents can output metadata to enhance messages.
+ *
+ * Format:
+ * [[RELAY_METADATA]]
+ * {
+ *   "subject": "Task update",
+ *   "importance": 80,
+ *   "replyTo": "msg-abc123",
+ *   "ackRequired": true
+ * }
+ * [[/RELAY_METADATA]]
+ */
+export function parseRelayMetadataFromOutput(output: string): MetadataParseResult {
+  const match = output.match(/\[\[RELAY_METADATA\]\]([\s\S]*?)\[\[\/RELAY_METADATA\]\]/);
+
+  if (!match) {
+    return { found: false, valid: false, metadata: null, rawContent: null };
+  }
+
+  const rawContent = match[1].trim();
+
+  try {
+    const metadata = JSON.parse(rawContent) as ParsedMessageMetadata;
+    return { found: true, valid: true, metadata, rawContent };
+  } catch {
+    return { found: true, valid: false, metadata: null, rawContent };
+  }
+}
+
+/**
+ * Parsed summary block from agent output.
+ */
+export interface ParsedSummary {
+  currentTask?: string;
+  completedTasks?: string[];
+  decisions?: string[];
+  context?: string;
+  files?: string[];
+}
+
+/**
+ * Result of attempting to parse a SUMMARY block.
+ */
+export interface SummaryParseResult {
+  found: boolean;
+  valid: boolean;
+  summary: ParsedSummary | null;
+  rawContent: string | null;  // Raw block content for deduplication
+}
+
+/**
+ * Parse [[SUMMARY]]...[[/SUMMARY]] blocks from agent output.
+ * Agents can output summaries to keep a running context of their work.
+ *
+ * Format:
+ * [[SUMMARY]]
+ * {
+ *   "currentTask": "Working on auth module",
+ *   "context": "Completed login flow, now implementing logout",
+ *   "files": ["src/auth.ts", "src/session.ts"]
+ * }
+ * [[/SUMMARY]]
+ */
+export function parseSummaryFromOutput(output: string): ParsedSummary | null {
+  const result = parseSummaryWithDetails(output);
+  return result.summary;
+}
+
+/**
+ * Parse SUMMARY block with full details for deduplication.
+ * Returns raw content to allow caller to dedupe before logging errors.
+ */
+export function parseSummaryWithDetails(output: string): SummaryParseResult {
+  const match = output.match(/\[\[SUMMARY\]\]([\s\S]*?)\[\[\/SUMMARY\]\]/);
+
+  if (!match) {
+    return { found: false, valid: false, summary: null, rawContent: null };
+  }
+
+  const rawContent = match[1].trim();
+
+  try {
+    const summary = JSON.parse(rawContent) as ParsedSummary;
+    return { found: true, valid: true, summary, rawContent };
+  } catch {
+    return { found: true, valid: false, summary: null, rawContent };
+  }
+}
+
+/**
+ * Session end marker from agent output.
+ */
+export interface SessionEndMarker {
+  summary?: string;
+  completedTasks?: string[];
+}
+
+/**
+ * Parse [[SESSION_END]]...[[/SESSION_END]] blocks from agent output.
+ * Agents output this to explicitly mark their session as complete.
+ *
+ * Format:
+ * [[SESSION_END]]
+ * {"summary": "Completed auth module implementation", "completedTasks": ["login", "logout"]}
+ * [[/SESSION_END]]
+ *
+ * Or simply: [[SESSION_END]][[/SESSION_END]] for a clean close without summary.
+ */
+export function parseSessionEndFromOutput(output: string): SessionEndMarker | null {
+  const match = output.match(/\[\[SESSION_END\]\]([\s\S]*?)\[\[\/SESSION_END\]\]/);
+
+  if (!match) {
+    return null;
+  }
+
+  const content = match[1].trim();
+  if (!content) {
+    return {}; // Empty marker = session ended without summary
+  }
+
+  try {
+    return JSON.parse(content) as SessionEndMarker;
+  } catch {
+    // If not valid JSON, treat the content as a plain summary string
+    return { summary: content };
+  }
+}
diff --git a/src/wrapper/tmux-wrapper.test.ts b/src/wrapper/tmux-wrapper.test.ts
new file mode 100644
index 000000000..133e24855
--- /dev/null
+++ b/src/wrapper/tmux-wrapper.test.ts
@@ -0,0 +1,170 @@
+/**
+ * Unit tests for TmuxWrapper constants and utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getDefaultPrefix } from './tmux-wrapper.js';
+
+describe('TmuxWrapper constants', () => {
+  // Unified prefix across all CLI types
+  describe('getDefaultPrefix', () => {
+    it('returns ->relay: for gemini CLI type', () => {
+      expect(getDefaultPrefix('gemini')).toBe('->relay:');
+    });
+
+    it('returns ->relay: for claude CLI type', () => {
+      expect(getDefaultPrefix('claude')).toBe('->relay:');
+    });
+
+    it('returns ->relay: for codex CLI type', () => {
+      expect(getDefaultPrefix('codex')).toBe('->relay:');
+    });
+
+    it('returns ->relay: for other CLI type', () => {
+      expect(getDefaultPrefix('other')).toBe('->relay:');
+    });
+  });
+});
+
+describe('String truncation safety', () => {
+  // Test the truncation pattern used throughout tmux-wrapper
+  // Pattern: str.substring(0, Math.min(LIMIT, str.length))
+
+  const safeSubstring = (str: string, maxLen: number): string => {
+    return str.substring(0, Math.min(maxLen, str.length));
+  };
+
+  describe('safeSubstring helper pattern', () => {
+    it('truncates long strings', () => {
+      const longString = 'a'.repeat(100);
+      expect(safeSubstring(longString, 40)).toBe('a'.repeat(40));
+      expect(safeSubstring(longString, 40)).toHaveLength(40);
+    });
+
+    it('preserves short strings', () => {
+      const shortString = 'hello';
+      expect(safeSubstring(shortString, 40)).toBe('hello');
+      expect(safeSubstring(shortString, 40)).toHaveLength(5);
+    });
+
+    it('handles exact length strings', () => {
+      const exactString = 'a'.repeat(40);
+      expect(safeSubstring(exactString, 40)).toBe(exactString);
+      expect(safeSubstring(exactString, 40)).toHaveLength(40);
+    });
+
+    it('handles empty strings', () => {
+      expect(safeSubstring('', 40)).toBe('');
+      expect(safeSubstring('', 40)).toHaveLength(0);
+    });
+
+    it('handles strings shorter than limit', () => {
+      expect(safeSubstring('ab', 40)).toBe('ab');
+    });
+
+    it('handles limit of 0', () => {
+      expect(safeSubstring('hello', 0)).toBe('');
+    });
+
+    it('handles unicode characters', () => {
+      const unicodeStr = ''.repeat(100);
+      expect(safeSubstring(unicodeStr, 10)).toBe(''.repeat(10));
+    });
+  });
+
+  describe('DEBUG_LOG_TRUNCATE_LENGTH constant (40)', () => {
+    const DEBUG_LOG_TRUNCATE_LENGTH = 40;
+
+    it('truncates debug log content appropriately', () => {
+      const longMessage = 'This is a very long debug message that exceeds the limit';
+      const truncated = safeSubstring(longMessage, DEBUG_LOG_TRUNCATE_LENGTH);
+      expect(truncated).toBe('This is a very long debug message that e');
+      expect(truncated).toHaveLength(40);
+    });
+  });
+
+  describe('RELAY_LOG_TRUNCATE_LENGTH constant (50)', () => {
+    const RELAY_LOG_TRUNCATE_LENGTH = 50;
+
+    it('truncates relay command log content appropriately', () => {
+      const longMessage = 'This is a very long relay message that definitely exceeds the fifty character limit';
+      const truncated = safeSubstring(longMessage, RELAY_LOG_TRUNCATE_LENGTH);
+      expect(truncated).toBe('This is a very long relay message that definitely ');
+      expect(truncated).toHaveLength(50);
+    });
+  });
+});
+
+describe('Cursor stability constants', () => {
+  // These test the logic that uses STABLE_CURSOR_THRESHOLD and MAX_PROMPT_CURSOR_POSITION
+
+  const STABLE_CURSOR_THRESHOLD = 3;
+  const MAX_PROMPT_CURSOR_POSITION = 4;
+
+  describe('STABLE_CURSOR_THRESHOLD', () => {
+    it('requires 3 or more stable polls to consider input clear', () => {
+      // Simulate cursor stability counting
+      let stableCursorCount = 0;
+      const cursorX = 2;
+
+      // First poll - not stable yet
+      stableCursorCount++;
+      expect(stableCursorCount >= STABLE_CURSOR_THRESHOLD).toBe(false);
+
+      // Second poll - still not stable
+      stableCursorCount++;
+      expect(stableCursorCount >= STABLE_CURSOR_THRESHOLD).toBe(false);
+
+      // Third poll - now stable
+      stableCursorCount++;
+      expect(stableCursorCount >= STABLE_CURSOR_THRESHOLD).toBe(true);
+      expect(cursorX <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+    });
+
+    it('resets count when cursor moves', () => {
+      let stableCursorCount = 2;
+      let lastCursorX = 2;
+      const newCursorX = 5; // Cursor moved
+
+      if (newCursorX !== lastCursorX) {
+        stableCursorCount = 0;
+        lastCursorX = newCursorX;
+      }
+
+      expect(stableCursorCount).toBe(0);
+    });
+  });
+
+  describe('MAX_PROMPT_CURSOR_POSITION', () => {
+    it('considers positions 0-4 as typical prompt positions', () => {
+      expect(0 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+      expect(1 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+      expect(2 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+      expect(3 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+      expect(4 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+    });
+
+    it('considers positions > 4 as likely having user input', () => {
+      expect(5 <= MAX_PROMPT_CURSOR_POSITION).toBe(false);
+      expect(10 <= MAX_PROMPT_CURSOR_POSITION).toBe(false);
+    });
+
+    it('works with combined stability check', () => {
+      const stableCursorCount = 3;
+      const cursorAtPrompt = 2;
+      const cursorWithInput = 10;
+
+      // At prompt position - should be considered clear
+      const isClearAtPrompt =
+        stableCursorCount >= STABLE_CURSOR_THRESHOLD &&
+        cursorAtPrompt <= MAX_PROMPT_CURSOR_POSITION;
+      expect(isClearAtPrompt).toBe(true);
+
+      // With input - should not be considered clear
+      const isClearWithInput =
+        stableCursorCount >= STABLE_CURSOR_THRESHOLD &&
+        cursorWithInput <= MAX_PROMPT_CURSOR_POSITION;
+      expect(isClearWithInput).toBe(false);
+    });
+  });
+});
diff --git a/src/wrapper/tmux-wrapper.ts b/src/wrapper/tmux-wrapper.ts
index f1006eb11..0853c725d 100644
--- a/src/wrapper/tmux-wrapper.ts
+++ b/src/wrapper/tmux-wrapper.ts
@@ -5,7 +5,7 @@
  * 1. Start agent in detached tmux session
  * 2. Attach user to tmux (they see real terminal)
  * 3. Background: poll capture-pane silently (no stdout writes)
- * 4. Background: parse @relay commands, send to daemon
+ * 4. Background: parse ->relay commands, send to daemon
  * 5. Background: inject messages via send-keys
  *
  * The key insight: user sees the REAL tmux session, not a proxy.
@@ -13,15 +13,28 @@
  */
 
 import { exec, execSync, spawn, ChildProcess } from 'node:child_process';
+import crypto from 'node:crypto';
 import { promisify } from 'node:util';
 import { RelayClient } from './client.js';
-import { OutputParser, type ParsedCommand } from './parser.js';
+import { OutputParser, type ParsedCommand, parseSummaryWithDetails, parseSessionEndFromOutput, ParsedMessageMetadata } from './parser.js';
 import { InboxManager } from './inbox.js';
-import type { SendPayload } from '../protocol/types.js';
+import type { SendPayload, SendMeta } from '../protocol/types.js';
+import { SqliteStorageAdapter } from '../storage/sqlite-adapter.js';
+import { getProjectPaths } from '../utils/project-namespace.js';
 
 const execAsync = promisify(exec);
 const escapeRegex = (str: string): string => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+// Constants for cursor stability detection in waitForClearInput
+/** Number of consecutive polls with stable cursor before assuming input is clear */
+const STABLE_CURSOR_THRESHOLD = 3;
+/** Maximum cursor X position that indicates a prompt (typical prompts are 1-4 chars) */
+const MAX_PROMPT_CURSOR_POSITION = 4;
+/** Maximum characters to show in debug log truncation */
+const DEBUG_LOG_TRUNCATE_LENGTH = 40;
+/** Maximum characters to show in relay command log truncation */
+const RELAY_LOG_TRUNCATE_LENGTH = 50;
+
 export interface TmuxWrapperConfig {
   name: string;
   command: string;
@@ -31,6 +44,12 @@ export interface TmuxWrapperConfig {
   rows?: number;
   cwd?: string;
   env?: Record<string, string>;
+  /** Optional program identifier (e.g., 'claude', 'gpt-4o') */
+  program?: string;
+  /** Optional model identifier (e.g., 'claude-3-opus') */
+  model?: string;
+  /** Optional task/role description for dashboard/registry */
+  task?: string;
   /** Use file-based inbox in addition to injection */
   useInbox?: boolean;
   /** Custom inbox directory */
@@ -47,27 +66,35 @@ export interface TmuxWrapperConfig {
   injectRetryMs?: number;
   /** How long with no output before marking session idle (ms) */
   activityIdleThresholdMs?: number;
+  /** Max time to wait for clear input before injecting (ms) */
+  inputWaitTimeoutMs?: number;
+  /** Polling interval when waiting for clear input (ms) */
+  inputWaitPollMs?: number;
   /** CLI type for special handling (auto-detected from command if not set) */
   cliType?: 'claude' | 'codex' | 'gemini' | 'other';
   /** Enable tmux mouse mode for scroll passthrough (default: true) */
   mouseMode?: boolean;
-  /** Relay prefix pattern (default: '@relay:' or '>>' for Gemini) */
+  /** Relay prefix pattern (default: '->relay:') */
   relayPrefix?: string;
+  /** Run in detached mode (don't attach to tmux, run as background daemon) */
+  detached?: boolean;
+  /** Callback for spawn commands (@relay:spawn WorkerName cli "task") */
+  onSpawn?: (name: string, cli: string, task: string) => Promise<void>;
+  /** Callback for release commands (@relay:release WorkerName) */
+  onRelease?: (name: string) => Promise<void>;
+  /** Max time to wait for stable pane output before injection (ms) */
+  outputStabilityTimeoutMs?: number;
+  /** Poll interval when checking pane stability before injection (ms) */
+  outputStabilityPollMs?: number;
 }
 
 /**
  * Get the default relay prefix for a given CLI type.
- * Gemini uses '>>' to avoid conflict with @ file references.
+ * All agents now use '->relay:' as the unified prefix.
  */
 export function getDefaultPrefix(cliType: 'claude' | 'codex' | 'gemini' | 'other'): string {
-  switch (cliType) {
-    case 'gemini':
-      return '>>'; // Avoid @ conflict with Gemini file references
-    case 'claude':
-    case 'codex':
-    default:
-      return '@relay:'; // Original, works fine
-  }
+  // Unified prefix for all agent types
+  return '->relay:';
 }
 
 export class TmuxWrapper {
@@ -76,6 +103,8 @@ export class TmuxWrapper {
   private client: RelayClient;
   private parser: OutputParser;
   private inbox?: InboxManager;
+  private storage?: SqliteStorageAdapter;
+  private storageReady: Promise<boolean>; // Resolves true if storage initialized, false if failed
   private running = false;
   private pollTimer?: NodeJS.Timeout;
   private attachProcess?: ChildProcess;
@@ -85,13 +114,21 @@ export class TmuxWrapper {
   private activityState: 'active' | 'idle' | 'disconnected' = 'disconnected';
   private recentlySentMessages: Map<string, number> = new Map();
   private sentMessageHashes: Set<string> = new Set(); // Permanent dedup
-  private messageQueue: Array<{ from: string; body: string; messageId: string }> = [];
+  private messageQueue: Array<{ from: string; body: string; messageId: string; thread?: string; importance?: number }> = [];
   private isInjecting = false;
   // Track processed output to avoid re-parsing
   private processedOutputLength = 0;
   private lastDebugLog = 0;
   private cliType: 'claude' | 'codex' | 'gemini' | 'other';
   private relayPrefix: string;
+  private lastSummaryHash = ''; // Dedup summary saves
+  private lastSummaryRawContent = ''; // Dedup invalid JSON error logging
+  private sessionEndProcessed = false; // Track if we've already processed session end
+  private pendingRelayCommands: ParsedCommand[] = [];
+  private queuedMessageHashes: Set<string> = new Set(); // For offline queue dedup
+  private readonly MAX_PENDING_RELAY_COMMANDS = 50;
+  private processedSpawnCommands: Set<string> = new Set(); // Dedup spawn commands
+  private processedReleaseCommands: Set<string> = new Set(); // Dedup release commands
 
   constructor(config: TmuxWrapperConfig) {
     this.config = {
@@ -100,10 +137,12 @@ export class TmuxWrapper {
       pollInterval: 200, // Slightly slower polling since we're not displaying
       idleBeforeInjectMs: 1500,
       injectRetryMs: 500,
-      debug: true,
+      debug: false,
       debugLogIntervalMs: 0,
       mouseMode: true, // Enable mouse scroll passthrough by default
       activityIdleThresholdMs: 30_000, // Consider idle after 30s with no output
+      outputStabilityTimeoutMs: 2000,
+      outputStabilityPollMs: 200,
       ...config,
     };
 
@@ -124,13 +163,18 @@ export class TmuxWrapper {
     // Determine relay prefix: explicit config > auto-detect from CLI type
     this.relayPrefix = config.relayPrefix ?? getDefaultPrefix(this.cliType);
 
-    // Generate unique session name
-    this.sessionName = `relay-${config.name}-${process.pid}`;
+    // Session name (one agent per name - starting a duplicate kills the existing one)
+    this.sessionName = `relay-${config.name}`;
 
     this.client = new RelayClient({
       agentName: config.name,
       socketPath: config.socketPath,
       cli: this.cliType,
+      program: this.config.program,
+      model: this.config.model,
+      task: this.config.task,
+      workingDirectory: this.config.cwd ?? process.cwd(),
+      quiet: true, // Keep stdout clean; we log to stderr via wrapper
     });
 
     this.parser = new OutputParser({ prefix: this.relayPrefix });
@@ -143,15 +187,32 @@ export class TmuxWrapper {
       });
     }
 
+    // Initialize storage for session/summary persistence
+    const projectPaths = getProjectPaths();
+    this.storage = new SqliteStorageAdapter({ dbPath: projectPaths.dbPath });
+    // Initialize asynchronously (don't block constructor) - methods await storageReady
+    this.storageReady = this.storage.init().then(() => true).catch(err => {
+      this.logStderr(`Failed to initialize storage: ${err.message}`, true);
+      this.storage = undefined;
+      return false;
+    });
+
     // Handle incoming messages from relay
-    this.client.onMessage = (from: string, payload: SendPayload, messageId: string) => {
-      this.handleIncomingMessage(from, payload, messageId);
+    this.client.onMessage = (from: string, payload: SendPayload, messageId: string, meta?: SendMeta) => {
+      this.handleIncomingMessage(from, payload, messageId, meta);
     };
 
     this.client.onStateChange = (state) => {
       // Only log to stderr, never stdout (user is in tmux)
       if (state === 'READY') {
-        this.logStderr(`Connected to relay daemon`);
+        this.logStderr('Connected to relay daemon');
+        this.flushQueuedRelayCommands();
+      } else if (state === 'BACKOFF') {
+        this.logStderr('Relay unavailable, will retry (backoff)');
+      } else if (state === 'DISCONNECTED') {
+        this.logStderr('Relay disconnected (offline mode)');
+      } else if (state === 'CONNECTING') {
+        this.logStderr('Connecting to relay daemon...');
       }
     };
   }
@@ -160,7 +221,7 @@ export class TmuxWrapper {
    * Log to stderr (safe - doesn't interfere with tmux display)
    */
   private logStderr(msg: string, force = false): void {
-    if (!force && this.config.debug === false) return;
+    if (!force && !this.config.debug) return;
 
     const now = Date.now();
     if (!force && this.config.debugLogIntervalMs && this.config.debugLogIntervalMs > 0) {
@@ -219,8 +280,9 @@ export class TmuxWrapper {
     }
 
     // Connect to relay daemon (in background, don't block)
-    this.client.connect().catch(() => {
-      // Silent - relay connection is optional
+    this.client.connect().catch((err: Error) => {
+      // Connection failures will retry via client backoff; surface once to stderr.
+      this.logStderr(`Relay connect failed: ${err.message}. Will retry if enabled.`, true);
     });
 
     // Kill any existing session with this name
@@ -250,6 +312,8 @@ export class TmuxWrapper {
         'setw -g alternate-screen on',        // Ensure alternate screen works
         // Pass through mouse scroll to application in alternate screen mode
         'set -ga terminal-overrides ",xterm*:Tc"',
+        'set -g status-left-length 100',      // Provide ample space for agent name in status bar
+        'set -g mode-keys vi',                // Predictable key table (avoid copy-mode surprises)
       ];
 
       // Add mouse mode if enabled (allows scroll passthrough to CLI apps)
@@ -266,6 +330,25 @@ export class TmuxWrapper {
         }
       }
 
+      // Mouse scroll should work for both TUIs (alternate screen) and plain shells.
+      // If the pane is in alternate screen, pass scroll to the app; otherwise enter copy-mode and scroll tmux history.
+      const tmuxMouseBindings = [
+        'unbind -T root WheelUpPane',
+        'unbind -T root WheelDownPane',
+        'unbind -T root MouseDrag1Pane',
+        'bind -T root WheelUpPane if-shell -F "#{alternate_on}" "send-keys -M" "copy-mode -e; send-keys -X scroll-up"',
+        'bind -T root WheelDownPane if-shell -F "#{alternate_on}" "send-keys -M" "send-keys -X scroll-down"',
+        'bind -T root MouseDrag1Pane if-shell -F "#{alternate_on}" "send-keys -M" "copy-mode -e"',
+      ];
+
+      for (const setting of tmuxMouseBindings) {
+        try {
+          execSync(`tmux ${setting}`, { stdio: 'pipe' });
+        } catch {
+          // Ignore on older tmux versions lacking these key tables
+        }
+      }
+
       // Set environment variables
       for (const [key, value] of Object.entries({
         ...this.config.env,
@@ -301,6 +384,15 @@ export class TmuxWrapper {
     // Start background polling (silent - no stdout writes)
     this.startSilentPolling();
 
+    // In detached mode, don't attach - just keep polling in background
+    if (this.config.detached) {
+      this.logStderr('Running in detached mode (daemon)', true);
+      this.logStderr(`Attach with: tmux attach -t ${this.sessionName}`, true);
+      // Keep the process alive
+      await new Promise(() => {}); // Never resolves - keeps daemon running
+      return;
+    }
+
     // Attach user to tmux session
     // This takes over stdin/stdout - user sees the real terminal
     this.attachToSession();
@@ -315,8 +407,9 @@ export class TmuxWrapper {
     const instructions = [
       `[Agent Relay] You are "${this.config.name}" - connected for real-time messaging.`,
       `SEND: ${this.relayPrefix}AgentName message (or ${this.relayPrefix}* to broadcast)`,
-      `RECEIVE: "Relay message from X [id]: content"`,
-      `TRUNCATED: Run "agent-relay read <id>" if message seems cut off`,
+      `RECEIVE: Messages appear as "Relay message from X [id]: content"`,
+      `SUMMARY: Periodically output [[SUMMARY]]{"currentTask":"...","context":"..."}[[/SUMMARY]] to track progress`,
+      `END: Output [[SESSION_END]]{"summary":"..."}[[/SESSION_END]] when your task is complete`,
     ].join(' | ');
 
     try {
@@ -413,7 +506,7 @@ export class TmuxWrapper {
   }
 
   /**
-   * Start silent polling for @relay commands
+   * Start silent polling for ->relay commands
    * Does NOT write to stdout - just parses and sends to daemon
    */
   private startSilentPolling(): void {
@@ -425,7 +518,7 @@ export class TmuxWrapper {
   }
 
   /**
-   * Poll for @relay commands in output (silent)
+   * Poll for ->relay commands in output (silent)
    */
   private async pollForRelayCommands(): Promise<void> {
     if (!this.running) return;
@@ -433,11 +526,11 @@ export class TmuxWrapper {
     try {
       // Capture scrollback
       const { stdout } = await execAsync(
-        // -J joins wrapped lines to avoid truncating @relay commands mid-line
+        // -J joins wrapped lines to avoid truncating ->relay commands mid-line
         `tmux capture-pane -t ${this.sessionName} -p -J -S - 2>/dev/null`
       );
 
-      // Always parse the FULL capture for @relay commands
+      // Always parse the FULL capture for ->relay commands
       // This handles terminal UIs that rewrite content in place
       const cleanContent = this.stripAnsi(stdout);
       // Join continuation lines that TUIs split across multiple lines
@@ -456,6 +549,15 @@ export class TmuxWrapper {
         this.sendRelayCommand(cmd);
       }
 
+      // Check for [[SUMMARY]] blocks and save to storage
+      this.parseSummaryAndSave(cleanContent);
+
+      // Check for [[SESSION_END]] blocks to explicitly close session
+      this.parseSessionEndAndClose(cleanContent);
+
+      // Check for @relay:spawn and @relay:release commands (lead mode)
+      this.parseSpawnReleaseCommands(cleanContent);
+
       this.updateActivityState();
 
       // Also check for injection opportunity
@@ -477,10 +579,10 @@ export class TmuxWrapper {
   }
 
   /**
-   * Join continuation lines after @relay commands.
+   * Join continuation lines after ->relay commands.
    * Claude Code and other TUIs insert real newlines in output, causing
-   * @relay messages to span multiple lines. This joins indented
-   * continuation lines back to the @relay line.
+   * ->relay messages to span multiple lines. This joins indented
+   * continuation lines back to the ->relay line.
    */
   private joinContinuationLines(content: string): string {
     const lines = content.split('\n');
@@ -500,7 +602,7 @@ export class TmuxWrapper {
     while (i < lines.length) {
       const line = lines[i];
 
-      // Check if this is a @relay line
+      // Check if this is a ->relay line
       if (relayPattern.test(line)) {
         let joined = line;
         let j = i + 1;
@@ -567,19 +669,6 @@ export class TmuxWrapper {
     }
   }
 
-  /**
-   * Escape string for ANSI-C quoting ($'...')
-   * This handles special characters more reliably than mixing quote styles
-   */
-  private escapeForAnsiC(str: string): string {
-    return str
-      .replace(/\\/g, '\\\\')     // Backslash
-      .replace(/'/g, "\\'")       // Single quote
-      .replace(/\n/g, '\\n')      // Newline
-      .replace(/\r/g, '\\r')      // Carriage return
-      .replace(/\t/g, '\\t');     // Tab
-  }
-
   /**
    * Send relay command to daemon
    */
@@ -591,24 +680,217 @@ export class TmuxWrapper {
       return;
     }
 
-    const success = this.client.sendMessage(cmd.to, cmd.body, cmd.kind, cmd.data);
+    // If client not ready, queue for later and return
+    if (this.client.state !== 'READY') {
+      if (this.queuedMessageHashes.has(msgHash)) {
+        return; // Already queued
+      }
+      if (this.pendingRelayCommands.length >= this.MAX_PENDING_RELAY_COMMANDS) {
+        this.logStderr('Relay offline queue full, dropping oldest');
+        const dropped = this.pendingRelayCommands.shift();
+        if (dropped) {
+          this.queuedMessageHashes.delete(`${dropped.to}:${dropped.body}`);
+        }
+      }
+      this.pendingRelayCommands.push(cmd);
+      this.queuedMessageHashes.add(msgHash);
+      this.logStderr(`Relay offline; queued message to ${cmd.to}`);
+      return;
+    }
+
+    // Convert ParsedMessageMetadata to SendMeta if present
+    let sendMeta: SendMeta | undefined;
+    if (cmd.meta) {
+      sendMeta = {
+        importance: cmd.meta.importance,
+        replyTo: cmd.meta.replyTo,
+        requires_ack: cmd.meta.ackRequired,
+      };
+    }
+
+    const success = this.client.sendMessage(cmd.to, cmd.body, cmd.kind, cmd.data, cmd.thread, sendMeta);
     if (success) {
       this.sentMessageHashes.add(msgHash);
-      this.logStderr(`→ ${cmd.to}: ${cmd.body.substring(0, 50)}...`);
+      this.queuedMessageHashes.delete(msgHash);
+      const truncatedBody = cmd.body.substring(0, Math.min(RELAY_LOG_TRUNCATE_LENGTH, cmd.body.length));
+      this.logStderr(`→ ${cmd.to}: ${truncatedBody}...`);
     } else if (this.client.state !== 'READY') {
       // Only log failure once per state change
       this.logStderr(`Send failed (client ${this.client.state})`);
     }
   }
 
+  /**
+   * Flush any queued relay commands when the client reconnects.
+   */
+  private flushQueuedRelayCommands(): void {
+    if (this.pendingRelayCommands.length === 0) return;
+
+    const queued = [...this.pendingRelayCommands];
+    this.pendingRelayCommands = [];
+    this.queuedMessageHashes.clear();
+
+    for (const cmd of queued) {
+      this.sendRelayCommand(cmd);
+    }
+  }
+
+  /**
+   * Parse [[SUMMARY]] blocks from output and save to storage.
+   * Agents can output summaries to maintain running context:
+   *
+   * [[SUMMARY]]
+   * {"currentTask": "Implementing auth", "context": "Completed login flow"}
+   * [[/SUMMARY]]
+   */
+  private parseSummaryAndSave(content: string): void {
+    const result = parseSummaryWithDetails(content);
+
+    // No SUMMARY block found
+    if (!result.found) return;
+
+    // Dedup based on raw content - prevents repeated error logging for same invalid JSON
+    if (result.rawContent === this.lastSummaryRawContent) return;
+    this.lastSummaryRawContent = result.rawContent || '';
+
+    // Invalid JSON - log error once (deduped above)
+    if (!result.valid) {
+      this.logStderr('[parser] Invalid JSON in SUMMARY block');
+      return;
+    }
+
+    const summary = result.summary!;
+
+    // Dedup valid summaries - don't save same summary twice
+    const summaryHash = JSON.stringify(summary);
+    if (summaryHash === this.lastSummaryHash) return;
+    this.lastSummaryHash = summaryHash;
+
+    // Wait for storage to be ready before saving
+    this.storageReady.then(ready => {
+      if (!ready || !this.storage) {
+        this.logStderr('Cannot save summary: storage not initialized');
+        return;
+      }
+
+      const projectPaths = getProjectPaths();
+      this.storage.saveAgentSummary({
+        agentName: this.config.name,
+        projectId: projectPaths.projectId,
+        currentTask: summary.currentTask,
+        completedTasks: summary.completedTasks,
+        decisions: summary.decisions,
+        context: summary.context,
+        files: summary.files,
+      }).then(() => {
+        this.logStderr(`Saved agent summary: ${summary.currentTask || 'updated context'}`);
+      }).catch(err => {
+        this.logStderr(`Failed to save summary: ${err.message}`, true);
+      });
+    });
+  }
+
+  /**
+   * Parse [[SESSION_END]] blocks from output and close session explicitly.
+   * Agents output this to mark their work session as complete:
+   *
+   * [[SESSION_END]]
+   * {"summary": "Completed auth module", "completedTasks": ["login", "logout"]}
+   * [[/SESSION_END]]
+   */
+  private parseSessionEndAndClose(content: string): void {
+    if (this.sessionEndProcessed) return; // Only process once per session
+
+    const sessionEnd = parseSessionEndFromOutput(content);
+    if (!sessionEnd) return;
+
+    // Get session ID from client connection - if not available yet, don't set flag
+    // so we can retry when sessionId becomes available
+    const sessionId = this.client.currentSessionId;
+    if (!sessionId) {
+      this.logStderr('Cannot close session: no session ID yet, will retry');
+      return;
+    }
+
+    this.sessionEndProcessed = true;
+
+    // Wait for storage to be ready before attempting to close session
+    this.storageReady.then(ready => {
+      if (!ready || !this.storage) {
+        this.logStderr('Cannot close session: storage not initialized');
+        return;
+      }
+
+      this.storage.endSession(sessionId, {
+        summary: sessionEnd.summary,
+        closedBy: 'agent',
+      }).then(() => {
+        this.logStderr(`Session closed by agent: ${sessionEnd.summary || 'complete'}`);
+      }).catch(err => {
+        this.logStderr(`Failed to close session: ${err.message}`, true);
+      });
+    });
+  }
+
+  /**
+   * Parse ->relay:spawn and ->relay:release commands from output.
+   * Format:
+   *   ->relay:spawn WorkerName cli "task description"
+   *   ->relay:release WorkerName
+   */
+  private parseSpawnReleaseCommands(content: string): void {
+    // Only process if callbacks are configured (lead mode)
+    if (!this.config.onSpawn && !this.config.onRelease) return;
+
+    const lines = content.split('\n');
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+
+      // Match ->relay:spawn WorkerName cli "task"
+      // Pattern: ->relay:spawn <name> <cli> "<task>" or ->relay:spawn <name> <cli> '<task>'
+      const spawnMatch = trimmed.match(/^->relay:spawn\s+(\S+)\s+(\S+)\s+["'](.+)["']$/);
+      if (spawnMatch && this.config.onSpawn) {
+        const [, name, cli, task] = spawnMatch;
+        const spawnKey = `${name}:${cli}:${task}`;
+
+        // Dedup - only process each spawn once
+        if (!this.processedSpawnCommands.has(spawnKey)) {
+          this.processedSpawnCommands.add(spawnKey);
+          this.logStderr(`Spawn command: ${name} (${cli}) - "${task.substring(0, 50)}..."`);
+          this.config.onSpawn(name, cli, task).catch(err => {
+            this.logStderr(`Spawn failed: ${err.message}`, true);
+          });
+        }
+        continue;
+      }
+
+      // Match ->relay:release WorkerName
+      const releaseMatch = trimmed.match(/^->relay:release\s+(\S+)$/);
+      if (releaseMatch && this.config.onRelease) {
+        const [, name] = releaseMatch;
+
+        // Dedup - only process each release once
+        if (!this.processedReleaseCommands.has(name)) {
+          this.processedReleaseCommands.add(name);
+          this.logStderr(`Release command: ${name}`);
+          this.config.onRelease(name).catch(err => {
+            this.logStderr(`Release failed: ${err.message}`, true);
+          });
+        }
+      }
+    }
+  }
+
   /**
    * Handle incoming message from relay
    */
-  private handleIncomingMessage(from: string, payload: SendPayload, messageId: string): void {
-    this.logStderr(`← ${from}: ${payload.body.substring(0, 40)}...`);
+  private handleIncomingMessage(from: string, payload: SendPayload, messageId: string, meta?: SendMeta): void {
+    const truncatedBody = payload.body.substring(0, Math.min(DEBUG_LOG_TRUNCATE_LENGTH, payload.body.length));
+    this.logStderr(`← ${from}: ${truncatedBody}...`);
 
     // Queue for injection
-    this.messageQueue.push({ from, body: payload.body, messageId });
+    this.messageQueue.push({ from, body: payload.body, messageId, thread: payload.thread, importance: meta?.importance });
 
     // Write to inbox if enabled
     if (this.inbox) {
@@ -650,16 +932,18 @@ export class TmuxWrapper {
 
     try {
       let sanitizedBody = msg.body.replace(/[\r\n]+/g, ' ').trim();
+
+      // Gemini interprets certain keywords (While, For, If, etc.) as shell commands
+      // Wrap in backticks to prevent shell keyword interpretation
+      if (this.cliType === 'gemini') {
+        sanitizedBody = `\`${sanitizedBody.replace(/`/g, "'")}\``;
+      }
+
       // Short message ID for display (first 8 chars)
       const shortId = msg.messageId.substring(0, 8);
 
-      // Truncate very long messages to avoid display issues
-      const maxLen = 2000;
-      let wasTruncated = false;
-      if (sanitizedBody.length > maxLen) {
-        sanitizedBody = sanitizedBody.substring(0, maxLen) + '...';
-        wasTruncated = true;
-      }
+      // Remove message truncation to allow full messages to pass through
+      const wasTruncated = false;
 
       // Always include message ID; add lookup hint if truncated
       const idTag = `[${shortId}]`;
@@ -667,47 +951,63 @@ export class TmuxWrapper {
         ? ` [TRUNCATED - run "agent-relay read ${msg.messageId}"]`
         : '';
 
-      // Gemini CLI interprets input as shell commands, so we need special handling
-      if (this.cliType === 'gemini') {
-        // For Gemini: Use printf with %s to safely handle any characters
-        // printf '%s\n' 'message' - the %s treats the argument as literal string
-        // We use $'...' ANSI-C quoting which handles escapes more predictably
-        const safeBody = this.escapeForAnsiC(sanitizedBody);
-        const safeFrom = this.escapeForAnsiC(msg.from);
-        const safeHint = this.escapeForAnsiC(truncationHint);
-        const printfMsg = `printf '%s\\n' $'Relay message from ${safeFrom} ${idTag}: ${safeBody}${safeHint}'`;
-
-        // Clear any partial input
+      // Wait for input to be clear before injecting
+      const waitTimeoutMs = this.config.inputWaitTimeoutMs ?? 5000;
+      const waitPollMs = this.config.inputWaitPollMs ?? 200;
+      const inputClear = await this.waitForClearInput(waitTimeoutMs, waitPollMs);
+      if (!inputClear) {
+        // Input still has text after timeout - clear it forcefully
+        this.logStderr('Input not clear after waiting, clearing forcefully');
         await this.sendKeys('Escape');
         await this.sleep(30);
         await this.sendKeys('C-u');
         await this.sleep(30);
+      }
 
-        // Send printf command to display the message
-        await this.sendKeysLiteral(printfMsg);
-        await this.sleep(50);
-        await this.sendKeys('Enter');
+      // Ensure pane output is stable to avoid interleaving with active generation
+      const stablePane = await this.waitForStablePane(
+        this.config.outputStabilityTimeoutMs ?? 2000,
+        this.config.outputStabilityPollMs ?? 200
+      );
+      if (!stablePane) {
+        this.logStderr('Output still active, re-queuing injection');
+        this.messageQueue.unshift(msg);
+        this.isInjecting = false;
+        setTimeout(() => this.checkForInjectionOpportunity(), this.config.injectRetryMs ?? 500);
+        return;
+      }
 
-        this.logStderr(`Injection complete (gemini printf mode)`);
-      } else {
-        // Standard injection for Claude, Codex, etc.
-        // Format: Relay message from Sender [abc12345]: content
-        const injection = `Relay message from ${msg.from} ${idTag}: ${sanitizedBody}${truncationHint}`;
+      // For Gemini: check if we're at a shell prompt ($) vs chat prompt (>)
+      // If at shell prompt, skip injection to avoid shell command execution
+      if (this.cliType === 'gemini') {
+        const lastLine = await this.getLastLine();
+        const cleanLine = this.stripAnsi(lastLine).trim();
+        if (/^\$\s*$/.test(cleanLine) || /^\s*\$\s*$/.test(cleanLine)) {
+          this.logStderr('Gemini at shell prompt, skipping injection to avoid shell execution');
+          // Re-queue the message for later
+          this.messageQueue.unshift(msg);
+          this.isInjecting = false;
+          setTimeout(() => this.checkForInjectionOpportunity(), 2000);
+          return;
+        }
+      }
 
-        // Clear any partial input
-        await this.sendKeys('Escape');
-        await this.sleep(30);
-        await this.sendKeys('C-u');
-        await this.sleep(30);
+      // Standard injection for all CLIs including Gemini
+      // Format: Relay message from Sender [abc12345] [thread:xxx] [!]: content
+      // Thread/importance hints are compact and optional to not break TUIs
+      const threadHint = msg.thread ? ` [thread:${msg.thread}]` : '';
+      // Importance indicator: [!!] for high (>75), [!] for medium (>50), none for low/default
+      const importanceHint = msg.importance !== undefined && msg.importance > 75 ? ' [!!]' :
+                             msg.importance !== undefined && msg.importance > 50 ? ' [!]' : '';
+      const injection = `Relay message from ${msg.from} ${idTag}${threadHint}${importanceHint}: ${sanitizedBody}${truncationHint}`;
 
-        // Type the message
-        await this.sendKeysLiteral(injection);
-        await this.sleep(50);
+      // Paste message as a bracketed paste to avoid interleaving with active output
+      await this.pasteLiteral(injection);
+      await this.sleep(30);
 
-        // Submit
-        await this.sendKeys('Enter');
-        this.logStderr(`Injection complete`);
-      }
+      // Submit
+      await this.sendKeys('Enter');
+      this.logStderr(`Injection complete`);
 
     } catch (err: any) {
       this.logStderr(`Injection failed: ${err.message}`, true);
@@ -743,10 +1043,205 @@ export class TmuxWrapper {
     await execAsync(`tmux send-keys -t ${this.sessionName} -l "${escaped}"`);
   }
 
+  /**
+   * Paste text using tmux buffer with bracketed paste (-p) to avoid interleaving with ongoing output.
+   */
+  private async pasteLiteral(text: string): Promise<void> {
+    // Sanitize newlines to keep injection single-line inside paste buffer
+    const sanitized = text.replace(/[\r\n]+/g, ' ');
+    const escaped = sanitized
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\$/g, '\\$')
+      .replace(/`/g, '\\`')
+      .replace(/!/g, '\\!');
+
+    // Set tmux buffer then paste with -p (bracketed paste)
+    await execAsync(`tmux set-buffer -- "${escaped}"`);
+    await execAsync(`tmux paste-buffer -t ${this.sessionName} -p`);
+  }
+
   private sleep(ms: number): Promise<void> {
     return new Promise(r => setTimeout(r, ms));
   }
 
+  /**
+   * Reset session-specific state for wrapper reuse.
+   * Call this when starting a new session with the same wrapper instance.
+   */
+  resetSessionState(): void {
+    this.sessionEndProcessed = false;
+    this.lastSummaryHash = '';
+    this.lastSummaryRawContent = '';
+  }
+
+  /**
+   * Get the prompt pattern for the current CLI type.
+   */
+  private getPromptPattern(): RegExp {
+    const promptPatterns: Record<string, RegExp> = {
+      claude: /^[>›»]\s*$/,           // Claude: "> " or similar
+      gemini: /^[>›»]\s*$/,           // Gemini: "> "
+      codex: /^[>›»]\s*$/,            // Codex: "> "
+      other: /^[>$%#➜›»]\s*$/,        // Shell or other: "$ ", "> ", etc.
+    };
+
+    return promptPatterns[this.cliType] || promptPatterns.other;
+  }
+
+  /**
+   * Capture the last non-empty line from the tmux pane.
+   */
+  private async getLastLine(): Promise<string> {
+    try {
+      const { stdout } = await execAsync(
+        `tmux capture-pane -t ${this.sessionName} -p -J 2>/dev/null`
+      );
+      const lines = stdout.split('\n').filter(l => l.length > 0);
+      return lines[lines.length - 1] || '';
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * Detect if the provided line contains visible user input (beyond the prompt).
+   */
+  private hasVisibleInput(line: string): boolean {
+    const cleanLine = this.stripAnsi(line).trimEnd();
+    if (cleanLine === '') return false;
+
+    return !this.getPromptPattern().test(cleanLine);
+  }
+
+  /**
+   * Check if the input line is clear (no user-typed text after the prompt).
+   * Returns true if the last visible line appears to be just a prompt.
+   */
+  private async isInputClear(lastLine?: string): Promise<boolean> {
+    try {
+      const lineToCheck = lastLine ?? await this.getLastLine();
+      const cleanLine = this.stripAnsi(lineToCheck).trimEnd();
+      const isClear = this.getPromptPattern().test(cleanLine);
+
+      if (this.config.debug) {
+        const truncatedLine = cleanLine.substring(0, Math.min(DEBUG_LOG_TRUNCATE_LENGTH, cleanLine.length));
+        this.logStderr(`isInputClear: lastLine="${truncatedLine}", clear=${isClear}`);
+      }
+
+      return isClear;
+    } catch {
+      // If we can't capture, assume not clear (safer)
+      return false;
+    }
+  }
+
+  /**
+   * Get cursor X position to detect input length.
+   * Returns the cursor column (0-indexed).
+   */
+  private async getCursorX(): Promise<number> {
+    try {
+      const { stdout } = await execAsync(
+        `tmux display-message -t ${this.sessionName} -p "#{cursor_x}" 2>/dev/null`
+      );
+      return parseInt(stdout.trim(), 10) || 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * Wait for the input line to be clear before injecting.
+   * Polls until the input appears empty or timeout is reached.
+   *
+   * @param maxWaitMs Maximum time to wait (default 5000ms)
+   * @param pollIntervalMs How often to check (default 200ms)
+   * @returns true if input became clear, false if timed out
+   */
+  private async waitForClearInput(maxWaitMs = 5000, pollIntervalMs = 200): Promise<boolean> {
+    const startTime = Date.now();
+    let lastCursorX = -1;
+    let stableCursorCount = 0;
+
+    while (Date.now() - startTime < maxWaitMs) {
+      const lastLine = await this.getLastLine();
+
+      // Check if input line is just a prompt
+      if (await this.isInputClear(lastLine)) {
+        return true;
+      }
+
+      const hasInput = this.hasVisibleInput(lastLine);
+
+      // Also check cursor stability - if cursor is moving, agent is typing
+      const cursorX = await this.getCursorX();
+      if (!hasInput && cursorX === lastCursorX) {
+        stableCursorCount++;
+        // If cursor has been stable for enough polls and at typical prompt position,
+        // the agent might be done but we just can't match the prompt pattern
+        if (stableCursorCount >= STABLE_CURSOR_THRESHOLD && cursorX <= MAX_PROMPT_CURSOR_POSITION) {
+          this.logStderr(`waitForClearInput: cursor stable at x=${cursorX}, assuming clear`);
+          return true;
+        }
+      } else {
+        stableCursorCount = 0;
+        lastCursorX = cursorX;
+      }
+
+      await this.sleep(pollIntervalMs);
+    }
+
+    this.logStderr(`waitForClearInput: timed out after ${maxWaitMs}ms`);
+    return false;
+  }
+
+  /**
+   * Capture a signature of the current pane content for stability checks.
+   * Uses hash+length to cheaply detect changes without storing full content.
+   */
+  private async capturePaneSignature(): Promise<string | null> {
+    try {
+      const { stdout } = await execAsync(
+        `tmux capture-pane -t ${this.sessionName} -p -J -S - 2>/dev/null`
+      );
+      const hash = crypto.createHash('sha1').update(stdout).digest('hex');
+      return `${stdout.length}:${hash}`;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Wait for pane output to stabilize before injecting to avoid interleaving with ongoing output.
+   */
+  private async waitForStablePane(maxWaitMs = 2000, pollIntervalMs = 200, requiredStablePolls = 2): Promise<boolean> {
+    const start = Date.now();
+    let lastSig = await this.capturePaneSignature();
+    if (!lastSig) return false;
+
+    let stableCount = 0;
+
+    while (Date.now() - start < maxWaitMs) {
+      await this.sleep(pollIntervalMs);
+      const sig = await this.capturePaneSignature();
+      if (!sig) continue;
+
+      if (sig === lastSig) {
+        stableCount++;
+        if (stableCount >= requiredStablePolls) {
+          return true;
+        }
+      } else {
+        stableCount = 0;
+        lastSig = sig;
+      }
+    }
+
+    this.logStderr(`waitForStablePane: timed out after ${maxWaitMs}ms`);
+    return false;
+  }
+
   /**
    * Stop and cleanup
    */
@@ -755,6 +1250,9 @@ export class TmuxWrapper {
     this.running = false;
     this.activityState = 'disconnected';
 
+    // Reset session state for potential reuse
+    this.resetSessionState();
+
     // Stop polling
     if (this.pollTimer) {
       clearInterval(this.pollTimer);
diff --git a/tsconfig.json b/tsconfig.json
index e6cca9a93..76d98918a 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -16,5 +16,5 @@
     "sourceMap": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts", "src/dashboard/frontend/**/*"]
 }
diff --git a/vitest.config.ts b/vitest.config.ts
index db3ec5700..8a209d57b 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -5,6 +5,10 @@ export default defineConfig({
     globals: true,
     environment: 'node',
     include: ['src/**/*.test.ts'],
+    // Use jsdom environment for frontend tests
+    environmentMatchGlobs: [
+      ['src/dashboard/frontend/**/*.test.ts', 'jsdom'],
+    ],
     coverage: {
       provider: 'v8',
       reporter: ['text', 'lcov', 'html'],