From 5618c5879faf826d9d3a4c767ae0075e3265ff2a Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Thu, 19 Feb 2026 21:36:25 +0000
Subject: [PATCH] docs: add TODO.md and FINDINGS.md for fleet delegation

Co-Authored-By: Virgil <virgil@lethean.io>
---
 FINDINGS.md | 26 ++++++++++++++++++++++++++
 TODO.md     | 27 +++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 FINDINGS.md
 create mode 100644 TODO.md

diff --git a/FINDINGS.md b/FINDINGS.md
new file mode 100644
index 0000000..ccc8acc
--- /dev/null
+++ b/FINDINGS.md
@@ -0,0 +1,26 @@
+# FINDINGS.md -- go-ws
+
+## 2026-02-19: Split from core/go (Virgil)
+
+### Origin
+
+Extracted from `forge.lthn.ai/core/go` `pkg/ws/` on 19 Feb 2026.
+
+### Architecture
+
+- Hub pattern: central `Hub` manages client registration, unregistration, and message routing
+- Channel-based subscriptions: clients subscribe to named channels for targeted messaging
+- Broadcast support: send to all connected clients or to a specific channel
+- Message types: `process_output`, `process_status`, `event`, `error`, `ping/pong`, `subscribe/unsubscribe`
+- `writePump` batches outbound messages for efficiency (reduces syscall overhead)
+- `readPump` handles inbound messages and automatic ping/pong keepalive
+
+### Dependencies
+
+- `github.com/gorilla/websocket` -- WebSocket server implementation
+
+### Notes
+
+- Hub must be started with `go hub.Run(ctx)` before accepting connections
+- HTTP handler exposed via `hub.Handler()` for mounting on any router
+- `hub.SendProcessOutput(processID, line)` is the primary API for streaming subprocess output
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..05a1f3c
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,27 @@
+# TODO.md -- go-ws
+
+## Phase 1: Connection Resilience
+
+- [ ] Add client-side reconnection support (exponential backoff)
+- [ ] Tune heartbeat interval and pong timeout for flaky networks
+- [ ] Add connection state callbacks (onConnect, onDisconnect, onReconnect)
+
+## Phase 2: Auth
+
+- [ ] Add token-based authentication on WebSocket upgrade handshake
+- [ ] Validate JWT or API key before promoting HTTP connection to WebSocket
+- [ ] Reject unauthenticated connections with appropriate HTTP status
+
+## Phase 3: Scaling
+
+- [ ] Support Redis pub/sub as backend for multi-instance hub coordination
+- [ ] Broadcast messages across hub instances via Redis channels
+- [ ] Add sticky sessions or connection-affinity documentation for load balancers
+
+---
+
+## Workflow
+
+1. Virgil in core/go writes tasks here after research
+2. This repo's dedicated session picks up tasks in phase order
+3. Mark `[x]` when done, note commit hash