refactor(web): migrate to TanStack Query + add WS event accounting (Phase 1)

.github/workflows/e2e-tests.yml

@@ -69,6 +69,12 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Build backend and web
+        # NEXT_PUBLIC_KANDEV_E2E_MOCK=true bakes the WS event-accounting hook
+        # into the FE bundle (see lib/ws/client.ts). Next.js inlines NEXT_PUBLIC_*
+        # at build time, so without this flag the hook dead-eliminates and the
+        # fixture's WS-drop check has nothing to read.
+        env:
+          NEXT_PUBLIC_KANDEV_E2E_MOCK: "true"
         run: make build-backend build-web
 
       # Linux/amd64 helper binaries (agentctl + mock-agent) bind-mounted into
@@ -133,6 +139,13 @@ jobs:
     # previously ran on.
     env:
       NODE_OPTIONS: --dns-result-order=ipv4first
+      # Enforce WS event accounting: any event the backend sent that the FE
+      # never processed (per-connection or per-session seq gap), and any
+      # session-routed event a bridge handler failed to apply to the TQ cache,
+      # fails the test that observed it. Requires the FE bundle built with
+      # NEXT_PUBLIC_KANDEV_E2E_MOCK=true (see the build job) so the accounting
+      # hooks are present. See docs/specs/ws-event-accounting/plan.md.
+      KANDEV_E2E_WS_ASSERT: "1"
     strategy:
       fail-fast: false
       matrix:

AGENTS.md

@@ -7,7 +7,7 @@
 ```
 apps/
 ├── backend/          # Go backend (orchestrator, lifecycle, agentctl, WS gateway)
-├── web/              # Next.js frontend (SSR + WS + Zustand)
+├── web/              # Next.js frontend (SSR + WS + TanStack Query + Zustand)
 ├── cli/              # CLI tool (TypeScript)
 ├── landing/          # Landing page
 └── packages/         # Shared packages/types
@@ -37,7 +37,7 @@ Architecture notes and per-area conventions live alongside the code they describ
 - `apps/backend/internal/agentctl/AGENTS.md` — agentctl HTTP server: route groups, adapter model, ACP protocol.
 - `apps/backend/internal/agentctl/server/api/AGENTS.md` — reverse-proxy body rewriting (`Accept-Encoding`), iframe-blocking header stripping.
 - `apps/backend/internal/integrations/AGENTS.md` — adding a new third-party integration (Jira/Linear pattern, both backend and frontend halves). The `/add-integration` skill mirrors this for scaffolding new integrations.
-- `apps/web/AGENTS.md` — Next.js frontend: shadcn imports, SSR-hydrate-store data flow, store slice structure (incl. `office`), WS format, component conventions, TS lint limits.
+- `apps/web/AGENTS.md` — Next.js frontend: shadcn imports, TanStack Query data flow (queries + WS→cache bridges + ring-buffered streams), client-only Zustand slices (transitional mirrors), WS format, component conventions, TS lint limits.
 
 ---
 

apps/backend/cmd/kandev/e2e_reset.go

@@ -4,24 +4,36 @@ import (
 	"context"
 	"net/http"
 	"os"
+	"strconv"
 	"strings"
 
 	"github.com/gin-gonic/gin"
 	"go.uber.org/zap"
 
 	"github.com/kandev/kandev/internal/automation"
 	"github.com/kandev/kandev/internal/common/logger"
+	gateways "github.com/kandev/kandev/internal/gateway/websocket"
 	sqliterepo "github.com/kandev/kandev/internal/task/repository/sqlite"
 	taskservice "github.com/kandev/kandev/internal/task/service"
 )
 
+// errorField is the JSON key for error responses across every E2E endpoint.
+// Extracted to satisfy goconst; the value is part of the public contract with
+// the FE test harness so don't rename without updating the consumers.
+const errorField = "error"
+
+// errUnknownConnection is the 404 message body for connection-id lookups
+// against the WS gateway's ring buffer. Extracted to satisfy goconst.
+const errUnknownConnection = "unknown connection_id"
+
 // registerE2EResetRoutes registers the E2E test-only endpoints.
 // The endpoints are available when KANDEV_MOCK_AGENT is "true" or "only" (dev/E2E modes).
 func registerE2EResetRoutes(
 	router *gin.Engine,
 	repo *sqliterepo.Repository,
 	taskSvc *taskservice.Service,
 	automationSvc *automation.Service,
+	hub *gateways.Hub,
 	log *logger.Logger,
 ) {
 	mockMode := os.Getenv("KANDEV_MOCK_AGENT")
@@ -35,10 +47,79 @@ func registerE2EResetRoutes(
 	// workflow path (e.g. improve-kandev) without depending on the real
 	// bootstrap endpoint, which clones from GitHub and shells out to gh.
 	api.POST("/hidden-workflow", handleE2ECreateHiddenWorkflow(taskSvc, log))
+	// WS send-log inspector: lets E2E tests diff what the BE sent vs what
+	// the FE received per WS connection. Gaps in the FE-side seq sequence
+	// against this server-of-record indicate a real WS regression rather
+	// than a noisy UI test.
+	api.GET("/ws-sent", handleE2EWsSent(hub))
 
 	log.Info("registered E2E endpoints (test-only)")
 }
 
+// e2eWsSentResponse matches the contract the FE-side accountant consumes.
+// Keep field names stable — changes here require a matching FE update.
+type e2eWsSentResponse struct {
+	ConnectionID string                 `json:"connection_id"`
+	Events       []gateways.WsSentEvent `json:"events"`
+	MaxSeq       int64                  `json:"max_seq"`
+}
+
+func handleE2EWsSent(hub *gateways.Hub) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		connectionID := c.Query("connection_id")
+		if connectionID == "" {
+			c.JSON(http.StatusBadRequest, gin.H{errorField: "connection_id is required"})
+			return
+		}
+		var sinceSeq int64
+		if raw := c.Query("since_seq"); raw != "" {
+			parsed, err := strconv.ParseInt(raw, 10, 64)
+			if err != nil {
+				c.JSON(http.StatusBadRequest, gin.H{errorField: "since_seq must be an integer"})
+				return
+			}
+			sinceSeq = parsed
+		}
+
+		// Optional per-session filter (Workstream 1): when set, returns only
+		// entries whose stamped SessionID matches, sorted by SessionSeq
+		// ascending. MaxSeq in the response then carries the max SessionSeq
+		// for the filter (the per-session counter, not per-connection). The
+		// FE per-session diff uses this to catch cross-session misrouting
+		// that per-connection seq alone cannot detect.
+		if sessionID := c.Query("session_id"); sessionID != "" {
+			events, maxSessionSeq, ok := hub.GetSentEventsForSession(connectionID, sessionID)
+			if !ok {
+				c.JSON(http.StatusNotFound, gin.H{errorField: errUnknownConnection})
+				return
+			}
+			if events == nil {
+				events = []gateways.WsSentEvent{}
+			}
+			c.JSON(http.StatusOK, e2eWsSentResponse{
+				ConnectionID: connectionID,
+				Events:       events,
+				MaxSeq:       maxSessionSeq,
+			})
+			return
+		}
+
+		events, maxSeq, ok := hub.GetSentEventsFor(connectionID, sinceSeq)
+		if !ok {
+			c.JSON(http.StatusNotFound, gin.H{errorField: errUnknownConnection})
+			return
+		}
+		if events == nil {
+			events = []gateways.WsSentEvent{}
+		}
+		c.JSON(http.StatusOK, e2eWsSentResponse{
+			ConnectionID: connectionID,
+			Events:       events,
+			MaxSeq:       maxSeq,
+		})
+	}
+}
+
 func handleE2EReset(
 	repo *sqliterepo.Repository,
 	taskSvc *taskservice.Service,
@@ -96,7 +177,7 @@ func handleE2EReset(
 		tasks, total, err := repo.ListTasksByWorkspace(ctx, workspaceID, "", "", "", 1, resetPageSize, true, true, false, false)
 		if err != nil {
 			log.Error("e2e reset: failed to list tasks", zap.Error(err))
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			c.JSON(http.StatusInternalServerError, gin.H{errorField: err.Error()})
 			return
 		}
 		if total > resetPageSize {
@@ -116,7 +197,7 @@ func handleE2EReset(
 				// would create orphan rows visible to subsequent tests.
 				log.Error("e2e reset: failed to delete task",
 					zap.String("task_id", t.ID), zap.Error(err))
-				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				c.JSON(http.StatusInternalServerError, gin.H{errorField: err.Error()})
 				return
 			}
 			deletedTasks++
@@ -125,14 +206,14 @@ func handleE2EReset(
 		deletedWorkflows, err := repo.DeleteWorkflowsByWorkspace(ctx, workspaceID, keepWorkflowIDs)
 		if err != nil {
 			log.Error("e2e reset: failed to delete workflows", zap.Error(err))
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			c.JSON(http.StatusInternalServerError, gin.H{errorField: err.Error()})
 			return
 		}
 
 		deletedAutomations, autoErr := deleteAutomationsForReset(ctx, automationSvc, workspaceID)
 		if autoErr != nil {
 			log.Error("e2e reset: failed to delete automations", zap.Error(autoErr))
-			c.JSON(http.StatusInternalServerError, gin.H{"error": autoErr.Error()})
+			c.JSON(http.StatusInternalServerError, gin.H{errorField: autoErr.Error()})
 			return
 		}
 
@@ -164,7 +245,7 @@ func handleE2ECreateHiddenWorkflow(taskSvc *taskservice.Service, log *logger.Log
 	return func(c *gin.Context) {
 		var body e2eHiddenWorkflowRequest
 		if err := c.ShouldBindJSON(&body); err != nil || body.WorkspaceID == "" || body.Name == "" {
-			c.JSON(http.StatusBadRequest, gin.H{"error": "workspace_id and name are required"})
+			c.JSON(http.StatusBadRequest, gin.H{errorField: "workspace_id and name are required"})
 			return
 		}
 		workflow, err := taskSvc.CreateWorkflow(c.Request.Context(), &taskservice.CreateWorkflowRequest{
@@ -174,7 +255,7 @@ func handleE2ECreateHiddenWorkflow(taskSvc *taskservice.Service, log *logger.Log
 		})
 		if err != nil {
 			log.Error("e2e: failed to create hidden workflow", zap.Error(err))
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			c.JSON(http.StatusInternalServerError, gin.H{errorField: err.Error()})
 			return
 		}
 		c.JSON(http.StatusCreated, gin.H{