Changeset 0.26.0 (#165)

2026-03-10 13:38:01 +00:00
parent dbc1a97343
commit 400f7dd176
48 changed files with 4923 additions and 208 deletions
--- a/server/handlers/completion.go
+++ b/server/handlers/completion.go
@@ -161,7 +161,7 @@ func (h *CompletionHandler) evaluateRouting(
 		Model:        model,
 		ConfigID:     configID,
 		HealthStatus: healthStatus,
-		Pricing:      map[string]*models.ModelPricing{}, // TODO: populate from pricing store
+		Pricing:      map[string]*models.ModelPricing{}, // populated when cost_limit routing is enabled (deferred)
 	}

 	ranked, dec := h.router.Evaluate(routingCtx, policies, candidates)
@@ -457,6 +457,18 @@ func (h *CompletionHandler) Complete(c *gin.Context) {
 		return
 	}

+	// ── Workflow form template injection (v0.26.4) ──
+	// When the channel is a workflow instance, inject the current stage's
+	// form_template as a system message so the persona knows what to collect.
+	if channelType == "workflow" {
+		if hint := h.buildWorkflowFormHint(c.Request.Context(), channelID); hint != "" {
+			messages = append(messages[:1], append([]providers.Message{{
+				Role:    "system",
+				Content: hint,
+			}}, messages[1:]...)...)
+		}
+	}
+
 	// Resolve capabilities early — needed for vision gating below
 	caps := h.getModelCapabilities(c, model, configID)

@@ -709,9 +721,9 @@ func (h *CompletionHandler) Complete(c *gin.Context) {
 	}

 	if stream {
-		h.streamCompletion(c, provider, providerCfg, provReq, channelID, userID, model, providerID, configID, providerScope, personaID, workspaceID)
+		h.streamCompletion(c, provider, providerCfg, provReq, channelID, userID, model, providerID, configID, providerScope, personaID, workspaceID, teamID)
 	} else {
-		h.syncCompletion(c, provider, providerCfg, provReq, channelID, userID, model, providerID, configID, providerScope, personaID, workspaceID)
+		h.syncCompletion(c, provider, providerCfg, provReq, channelID, userID, model, providerID, configID, providerScope, personaID, workspaceID, teamID)
 	}
 }

@@ -724,7 +736,7 @@ func (h *CompletionHandler) multiModelStream(
 	c *gin.Context,
 	targets []models.ChannelModel,
 	messages []providers.Message,
-	channelID, userID, personaID, personaSystemPrompt, workspaceID string,
+	channelID, userID, personaID, personaSystemPrompt, workspaceID, teamID string,
 	req completionRequest,
 ) {
 	// Set SSE headers once for the entire multi-model stream
@@ -821,7 +833,7 @@ func (h *CompletionHandler) multiModelStream(
 		}

 		// Stream this model's response using the shared streaming core
-		result := streamModelResponse(c, provider, providerCfg, &provReq, model, providerID, target.DisplayName, userID, channelID, personaID, workspaceID, configID, h.hub, h.health)
+		result := streamModelResponse(c, provider, providerCfg, &provReq, model, providerID, target.DisplayName, userID, channelID, personaID, workspaceID, configID, teamID, h.hub, h.health)

 		// Persist assistant message with model attribution
 		if result.Content != "" {
@@ -1012,14 +1024,14 @@ func (h *CompletionHandler) streamCompletion(
 	provider providers.Provider,
 	cfg providers.ProviderConfig,
 	req providers.CompletionRequest,
-	channelID, userID, model, providerID, configID, providerScope, personaID, workspaceID string,
+	channelID, userID, model, providerID, configID, providerScope, personaID, workspaceID, teamID string,
 ) {
 	// Apply provider-specific request hooks (v0.22.1)
 	if hooks := providers.GetHooks(providerID); hooks != nil {
 		hooks.PreRequest(cfg, &req)
 	}

-	result := streamWithToolLoop(c, provider, cfg, &req, model, providerID, userID, channelID, personaID, workspaceID, configID, h.hub, h.health)
+	result := streamWithToolLoop(c, provider, cfg, &req, model, providerID, userID, channelID, personaID, workspaceID, configID, teamID, h.hub, h.health)

 	// Persist assistant response
 	if result.Content != "" {
@@ -1052,7 +1064,7 @@ func (h *CompletionHandler) syncCompletion(
 	provider providers.Provider,
 	cfg providers.ProviderConfig,
 	req providers.CompletionRequest,
-	channelID, userID, model, providerID, configID, providerScope, personaID, workspaceID string,
+	channelID, userID, model, providerID, configID, providerScope, personaID, workspaceID, teamID string,
 ) {
 	// Apply provider-specific request hooks (v0.22.1)
 	if hooks := providers.GetHooks(providerID); hooks != nil {
@@ -1137,6 +1149,7 @@ func (h *CompletionHandler) syncCompletion(
 			ChannelID:   channelID,
 			PersonaID:   personaID,
 			WorkspaceID: workspaceID,
+			TeamID:      teamID,
 		}
 		for _, tc := range resp.ToolCalls {
 			call := tools.ToolCall{
@@ -1335,6 +1348,71 @@ func (h *CompletionHandler) conversationHasPersonaMessages(ctx context.Context,
 	return err == nil && id != ""
 }

+// buildWorkflowFormHint loads the current workflow stage's form_template
+// and returns a system message instructing the persona what to collect.
+// Returns empty string if not a workflow or no template defined.
+func (h *CompletionHandler) buildWorkflowFormHint(ctx context.Context, channelID string) string {
+	var workflowID *string
+	var currentStage int
+	_ = database.DB.QueryRowContext(ctx, database.Q(`
+		SELECT workflow_id, COALESCE(current_stage, 0)
+		FROM channels WHERE id = $1 AND type = 'workflow'
+	`), channelID).Scan(&workflowID, &currentStage)
+
+	if workflowID == nil || *workflowID == "" {
+		return ""
+	}
+
+	if h.stores.Workflows == nil {
+		return ""
+	}
+
+	stages, err := h.stores.Workflows.ListStages(ctx, *workflowID)
+	if err != nil || currentStage >= len(stages) {
+		return ""
+	}
+
+	stage := stages[currentStage]
+	if len(stage.FormTemplate) == 0 || string(stage.FormTemplate) == "{}" {
+		return ""
+	}
+
+	// Parse form template to extract field descriptions
+	var fields map[string]interface{}
+	if err := json.Unmarshal(stage.FormTemplate, &fields); err != nil {
+		return ""
+	}
+	if len(fields) == 0 {
+		return ""
+	}
+
+	hint := "You are in workflow stage: " + stage.Name + ".\n\n"
+	hint += "Collect the following information from the user through natural conversation:\n\n"
+	for name, spec := range fields {
+		switch v := spec.(type) {
+		case map[string]interface{}:
+			desc, _ := v["description"].(string)
+			required, _ := v["required"].(bool)
+			if desc != "" {
+				hint += "- " + name + ": " + desc
+			} else {
+				hint += "- " + name
+			}
+			if required {
+				hint += " (required)"
+			}
+			hint += "\n"
+		default:
+			hint += "- " + name + "\n"
+		}
+	}
+
+	hint += "\nWhen you have gathered all required information, call the workflow_advance tool " +
+		"with the collected data as a JSON object. Do not advance until all required fields are filled."
+
+	return hint
+}
+
 // buildParticipantHint builds a system message listing available @mentionable
 // personas so the LLM knows who it can direct responses to.
 // Only includes personas accessible to this user. Excludes the current persona.
--- a/server/handlers/messages.go
+++ b/server/handlers/messages.go
@@ -545,18 +545,21 @@ func (h *MessageHandler) Regenerate(c *gin.Context) {

 	// Attach tool definitions (same as normal completion)
 	workspaceID, _ := h.stores.Channels.ResolveWorkspaceID(c.Request.Context(), channelID)
+
+	// Query channel metadata for tool context and execution context
+	var chType string
+	var chTeamID *string
+	_ = database.DB.QueryRowContext(c.Request.Context(), database.Q(`
+		SELECT COALESCE(type, 'direct'), team_id FROM channels WHERE id = $1
+	`), channelID).Scan(&chType, &chTeamID)
+	msgTeamID := ""
+	if chTeamID != nil {
+		msgTeamID = *chTeamID
+	}
+
 	hasBrowserTools := h.hub != nil && h.hub.IsConnected(userID)
 	if caps.ToolCalling && (tools.HasTools() || hasBrowserTools) {
 		// v0.25.0: Build ToolContext with channel metadata
-		var chType string
-		var chTeamID *string
-		_ = database.DB.QueryRowContext(c.Request.Context(), database.Q(`
-			SELECT COALESCE(type, 'direct'), team_id FROM channels WHERE id = $1
-		`), channelID).Scan(&chType, &chTeamID)
-		msgTeamID := ""
-		if chTeamID != nil {
-			msgTeamID = *chTeamID
-		}
 		tctx := tools.ToolContext{
 			ChannelType: chType,
 			WorkspaceID: workspaceID,
@@ -574,7 +577,7 @@ func (h *MessageHandler) Regenerate(c *gin.Context) {
 		hooks.PreRequest(providerCfg, &provReq)
 	}

-	result := streamWithToolLoop(c, provider, providerCfg, &provReq, model, providerID, userID, channelID, personaID, workspaceID, configID, h.hub, comp.health)
+	result := streamWithToolLoop(c, provider, providerCfg, &provReq, model, providerID, userID, channelID, personaID, workspaceID, configID, msgTeamID, h.hub, comp.health)

 	// Persist as sibling (regen) with tool activity
 	if result.Content != "" {
--- a/server/handlers/route_test.go
+++ b/server/handlers/route_test.go
@@ -0,0 +1,177 @@
+package handlers
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"git.gobha.me/xcaliber/chat-switchboard/config"
+	authpkg "git.gobha.me/xcaliber/chat-switchboard/auth"
+	"git.gobha.me/xcaliber/chat-switchboard/database"
+	"git.gobha.me/xcaliber/chat-switchboard/middleware"
+	"git.gobha.me/xcaliber/chat-switchboard/pages"
+	"git.gobha.me/xcaliber/chat-switchboard/store"
+	postgres "git.gobha.me/xcaliber/chat-switchboard/store/postgres"
+	sqlite "git.gobha.me/xcaliber/chat-switchboard/store/sqlite"
+)
+
+// TestRouteRegistration verifies that ALL production routes can be
+// registered on a single Gin engine without panicking. This catches
+// wildcard parameter name conflicts (e.g. /w/:id vs /w/:scope/:slug)
+// which cause runtime panics during startup.
+//
+// The test mirrors the route structure in main.go and pages.go.
+// Any new route group should be added here.
+func TestRouteRegistration(t *testing.T) {
+	database.RequireTestDB(t)
+
+	cfg := &config.Config{
+		JWTSecret: testJWTSecret,
+		BasePath:  "/test",
+		Port:      "0",
+	}
+
+	var stores store.Stores
+	if database.IsSQLite() {
+		stores = sqlite.NewStores(database.TestDB)
+	} else {
+		stores = postgres.NewStores(database.TestDB)
+	}
+
+	// This must not panic. If it does, there's a wildcard conflict.
+	r := gin.New()
+	base := r.Group(cfg.BasePath)
+
+	// ── API routes (mirrors main.go) ────────
+
+	api := base.Group("/api/v1")
+
+	// Auth (public)
+	auth := NewAuthHandler(cfg, stores, nil, authpkg.NewBuiltinProvider())
+	api.POST("/auth/login", auth.Login)
+	api.POST("/auth/register", auth.Register)
+
+	// Protected API routes
+	protected := api.Group("")
+	protected.Use(middleware.Auth(cfg))
+
+	// Channels (the route group that conflicts with workflow)
+	channels := NewChannelHandler()
+	protected.GET("/channels", channels.ListChannels)
+	protected.POST("/channels", channels.CreateChannel)
+	protected.GET("/channels/:id", channels.GetChannel)
+	protected.DELETE("/channels/:id", channels.DeleteChannel)
+
+	// Messages
+	msgs := NewMessageHandler(nil, stores, nil, nil)
+	protected.GET("/channels/:id/messages", msgs.ListMessages)
+	protected.POST("/channels/:id/messages", msgs.CreateMessage)
+
+	// Workflow CRUD
+	wfH := NewWorkflowHandler(stores)
+	protected.GET("/workflows", wfH.List)
+	protected.POST("/workflows", wfH.Create)
+	protected.GET("/workflows/:id", wfH.Get)
+	protected.PATCH("/workflows/:id", wfH.Update)
+	protected.DELETE("/workflows/:id", wfH.Delete)
+	protected.GET("/workflows/:id/stages", wfH.ListStages)
+	protected.POST("/workflows/:id/stages", wfH.CreateStage)
+	protected.PUT("/workflows/:id/stages/:sid", wfH.UpdateStage)
+	protected.DELETE("/workflows/:id/stages/:sid", wfH.DeleteStage)
+	protected.PATCH("/workflows/:id/stages/reorder", wfH.ReorderStages)
+	protected.POST("/workflows/:id/publish", wfH.Publish)
+	protected.GET("/workflows/:id/versions/:version", wfH.GetVersion)
+
+	// Workflow instances
+	wfInstH := NewWorkflowInstanceHandler(stores)
+	protected.POST("/workflows/:id/start", wfInstH.Start)
+	protected.GET("/channels/:id/workflow/status", wfInstH.GetStatus)
+	protected.POST("/channels/:id/workflow/advance", wfInstH.Advance)
+	protected.POST("/channels/:id/workflow/reject", wfInstH.Reject)
+
+	// Workflow assignments (v0.26.4)
+	wfAssignH := NewWorkflowAssignmentHandler()
+	protected.GET("/workflow-assignments/mine", wfAssignH.ListMine)
+	protected.POST("/workflow-assignments/:id/claim", wfAssignH.Claim)
+	protected.POST("/workflow-assignments/:id/complete", wfAssignH.Complete)
+
+	// Session API (the /w/:id group)
+	wfAPI := base.Group("/api/v1/w")
+	wfAPI.Use(middleware.AuthOrSession(cfg, stores))
+	wfAPI.POST("/:id/messages", msgs.CreateMessage)
+	wfAPI.GET("/:id/messages", msgs.ListMessages)
+
+	// Visitor entry (separate namespace to avoid /w/:id collision)
+	wfEntry := NewWorkflowEntryHandler(stores)
+	base.POST("/api/v1/workflow-entry/:scope/:slug", wfEntry.StartVisitor)
+
+	// ── Page routes (mirrors pages.go surface registration) ────
+
+	pageEngine := pages.New(cfg, stores)
+	pageEngine.RegisterPageRoutes(base, pages.PageRouteMiddleware{
+		Authenticated: middleware.AuthOrRedirect(cfg),
+		Admin:         []gin.HandlerFunc{middleware.AuthOrRedirect(cfg), middleware.RequireAdminPage()},
+		Session:       middleware.AuthOrSession(cfg, stores),
+	})
+
+	// ── Verify routes actually resolve ────
+
+	// Health-check style: send a request and confirm we get a response
+	// (not a panic). We don't care about the status code — just that
+	// the router doesn't blow up.
+	paths := []struct {
+		method string
+		path   string
+	}{
+		{"GET", "/test/api/v1/workflows"},
+		{"GET", "/test/api/v1/channels"},
+		{"GET", "/test/w/some-channel-id"},         // workflow chat surface
+		{"GET", "/test/w/some-scope/some-slug"},     // workflow landing surface
+		{"POST", "/test/api/v1/workflow-entry/global/test-slug"},
+	}
+
+	for _, p := range paths {
+		req := httptest.NewRequest(p.method, p.path, nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		// We just want to confirm the router didn't panic and returned
+		// something (even 401/404 is fine — means routing worked).
+		if w.Code == 0 {
+			t.Errorf("%s %s: got status 0 (router failed to match)", p.method, p.path)
+		}
+	}
+}
+
+// TestWorkflowPageRoutesNoConflict specifically tests the /w/ namespace
+// to ensure different-depth routes with the same param name work.
+func TestWorkflowPageRoutesNoConflict(t *testing.T) {
+	r := gin.New()
+
+	// These two routes MUST use the same wildcard name at position 1.
+	// /w/:id (2 segments) = workflow chat
+	// /w/:id/:slug (3 segments) = workflow landing
+	// Using different names (e.g. :scope) at the same position panics.
+	r.GET("/w/:id", func(c *gin.Context) {
+		c.String(http.StatusOK, "chat:"+c.Param("id"))
+	})
+	r.GET("/w/:id/:slug", func(c *gin.Context) {
+		c.String(http.StatusOK, "landing:"+c.Param("id")+"/"+c.Param("slug"))
+	})
+
+	// 2-segment path → chat
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, httptest.NewRequest("GET", "/w/channel-123", nil))
+	if w.Code != 200 || w.Body.String() != "chat:channel-123" {
+		t.Errorf("2-segment: got %d %q", w.Code, w.Body.String())
+	}
+
+	// 3-segment path → landing
+	w = httptest.NewRecorder()
+	r.ServeHTTP(w, httptest.NewRequest("GET", "/w/my-team/intake-form", nil))
+	if w.Code != 200 || w.Body.String() != "landing:my-team/intake-form" {
+		t.Errorf("3-segment: got %d %q", w.Code, w.Body.String())
+	}
+}
--- a/server/handlers/stream_loop.go
+++ b/server/handlers/stream_loop.go
@@ -62,7 +62,7 @@ func streamWithToolLoop(
 	provider providers.Provider,
 	cfg providers.ProviderConfig,
 	req *providers.CompletionRequest,
-	model, providerType, userID, channelID, personaID, workspaceID, configID string,
+	model, providerType, userID, channelID, personaID, workspaceID, configID, teamID string,
 	hub *events.Hub,
 	health HealthRecorder,
 ) streamResult {
@@ -199,6 +199,7 @@ func streamWithToolLoop(
 			ChannelID:   channelID,
 			PersonaID:   personaID,
 			WorkspaceID: workspaceID,
+			TeamID:      teamID,
 		}
 		for _, tc := range toolCalls {
 			call := tools.ToolCall{
@@ -307,7 +308,7 @@ func streamModelResponse(
 	provider providers.Provider,
 	cfg providers.ProviderConfig,
 	req *providers.CompletionRequest,
-	model, providerType, displayName, userID, channelID, personaID, workspaceID, configID string,
+	model, providerType, displayName, userID, channelID, personaID, workspaceID, configID, teamID string,
 	hub *events.Hub,
 	health HealthRecorder,
 ) streamResult {
@@ -424,6 +425,7 @@ func streamModelResponse(
 			ChannelID:   channelID,
 			PersonaID:   personaID,
 			WorkspaceID: workspaceID,
+			TeamID:      teamID,
 		}
 		for _, tc := range toolCalls {
 			call := tools.ToolCall{
--- a/server/handlers/surfaces.go
+++ b/server/handlers/surfaces.go
@@ -105,8 +105,13 @@ func (h *SurfaceHandler) DeleteSurface(c *gin.Context) {
 		return
 	}

-	// TODO: Delete static assets from SURFACE_ASSET_DIR/{id}/
-	// TODO: Delete templates from SURFACE_TEMPLATE_DIR/{id}/
+	// Clean up extracted static assets for this surface
+	if h.surfacesDir != "" {
+		assetDir := filepath.Join(h.surfacesDir, id)
+		if err := os.RemoveAll(assetDir); err != nil {
+			log.Printf("⚠️ Failed to clean up surface assets at %s: %v", assetDir, err)
+		}
+	}

 	c.JSON(http.StatusOK, gin.H{"id": id, "deleted": true})
 }
--- a/server/handlers/workflow_assignments.go
+++ b/server/handlers/workflow_assignments.go
@@ -0,0 +1,144 @@
+package handlers
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"git.gobha.me/xcaliber/chat-switchboard/database"
+)
+
+// ── Workflow Assignment Handler ─────────────
+// Manages the assignment queue for human review stages.
+
+type WorkflowAssignmentHandler struct{}
+
+func NewWorkflowAssignmentHandler() *WorkflowAssignmentHandler {
+	return &WorkflowAssignmentHandler{}
+}
+
+type assignmentRow struct {
+	ID          string     `json:"id"`
+	ChannelID   string     `json:"channel_id"`
+	Stage       int        `json:"stage"`
+	TeamID      string     `json:"team_id"`
+	AssignedTo  *string    `json:"assigned_to"`
+	Status      string     `json:"status"`
+	CreatedAt   time.Time  `json:"created_at"`
+	ClaimedAt   *time.Time `json:"claimed_at"`
+	CompletedAt *time.Time `json:"completed_at"`
+}
+
+// ListForTeam returns unassigned + claimed assignments for a team.
+// GET /api/v1/teams/:teamId/assignments
+func (h *WorkflowAssignmentHandler) ListForTeam(c *gin.Context) {
+	teamID := c.Param("teamId")
+	status := c.DefaultQuery("status", "unassigned")
+
+	rows, err := database.DB.QueryContext(c.Request.Context(), database.Q(`
+		SELECT id, channel_id, stage, team_id, assigned_to, status,
+		       created_at, claimed_at, completed_at
+		FROM workflow_assignments
+		WHERE team_id = $1 AND status = $2
+		ORDER BY created_at ASC
+	`), teamID, status)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list assignments"})
+		return
+	}
+	defer rows.Close()
+
+	var result []assignmentRow
+	for rows.Next() {
+		var a assignmentRow
+		if err := rows.Scan(&a.ID, &a.ChannelID, &a.Stage, &a.TeamID,
+			&a.AssignedTo, &a.Status, &a.CreatedAt, &a.ClaimedAt, &a.CompletedAt); err != nil {
+			continue
+		}
+		result = append(result, a)
+	}
+	if result == nil {
+		result = []assignmentRow{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": result})
+}
+
+// ListForUser returns assignments claimed by the current user.
+// GET /api/v1/workflow-assignments/mine
+func (h *WorkflowAssignmentHandler) ListMine(c *gin.Context) {
+	userID := c.GetString("user_id")
+	rows, err := database.DB.QueryContext(c.Request.Context(), database.Q(`
+		SELECT id, channel_id, stage, team_id, assigned_to, status,
+		       created_at, claimed_at, completed_at
+		FROM workflow_assignments
+		WHERE assigned_to = $1 AND status = 'claimed'
+		ORDER BY claimed_at DESC
+	`), userID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list assignments"})
+		return
+	}
+	defer rows.Close()
+
+	var result []assignmentRow
+	for rows.Next() {
+		var a assignmentRow
+		if err := rows.Scan(&a.ID, &a.ChannelID, &a.Stage, &a.TeamID,
+			&a.AssignedTo, &a.Status, &a.CreatedAt, &a.ClaimedAt, &a.CompletedAt); err != nil {
+			continue
+		}
+		result = append(result, a)
+	}
+	if result == nil {
+		result = []assignmentRow{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": result})
+}
+
+// Claim assigns a workflow to the current user via optimistic lock.
+// POST /api/v1/workflow-assignments/:id/claim
+func (h *WorkflowAssignmentHandler) Claim(c *gin.Context) {
+	assignmentID := c.Param("id")
+	userID := c.GetString("user_id")
+	now := time.Now().UTC()
+
+	res, err := database.DB.ExecContext(c.Request.Context(), database.Q(`
+		UPDATE workflow_assignments
+		SET assigned_to = $1, status = 'claimed', claimed_at = $2
+		WHERE id = $3 AND status = 'unassigned'
+	`), userID, now, assignmentID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to claim assignment"})
+		return
+	}
+	n, _ := res.RowsAffected()
+	if n == 0 {
+		c.JSON(http.StatusConflict, gin.H{"error": "assignment already claimed or not found"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"claimed": true, "assignment_id": assignmentID})
+}
+
+// Complete marks an assignment as completed.
+// POST /api/v1/workflow-assignments/:id/complete
+func (h *WorkflowAssignmentHandler) Complete(c *gin.Context) {
+	assignmentID := c.Param("id")
+	now := time.Now().UTC()
+
+	res, err := database.DB.ExecContext(c.Request.Context(), database.Q(`
+		UPDATE workflow_assignments
+		SET status = 'completed', completed_at = $1
+		WHERE id = $2 AND status = 'claimed'
+	`), now, assignmentID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to complete assignment"})
+		return
+	}
+	n, _ := res.RowsAffected()
+	if n == 0 {
+		c.JSON(http.StatusConflict, gin.H{"error": "assignment not in claimed state"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"completed": true, "assignment_id": assignmentID})
+}
--- a/server/handlers/workflow_entry.go
+++ b/server/handlers/workflow_entry.go
@@ -0,0 +1,135 @@
+package handlers
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"git.gobha.me/xcaliber/chat-switchboard/database"
+	"git.gobha.me/xcaliber/chat-switchboard/models"
+	"git.gobha.me/xcaliber/chat-switchboard/store"
+)
+
+// ── Workflow Entry Handler ──────────────────
+// Handles the visitor-facing workflow start flow.
+// Landing page rendering is in pages/pages.go (RenderWorkflowLanding).
+
+type WorkflowEntryHandler struct {
+	stores store.Stores
+}
+
+func NewWorkflowEntryHandler(stores store.Stores) *WorkflowEntryHandler {
+	return &WorkflowEntryHandler{stores: stores}
+}
+
+// StartVisitor creates an anonymous session + workflow instance for a visitor.
+// POST /api/v1/workflow-entry/:scope/:slug
+func (h *WorkflowEntryHandler) StartVisitor(c *gin.Context) {
+	ctx := c.Request.Context()
+	scope := c.Param("scope")
+	slug := c.Param("slug")
+
+	var teamID *string
+	if scope != "global" {
+		teamID = &scope
+	}
+
+	wf, err := h.stores.Workflows.GetBySlug(ctx, teamID, slug)
+	if err != nil || wf == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "workflow not found"})
+		return
+	}
+	if !wf.IsActive {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "workflow not active"})
+		return
+	}
+	if wf.EntryMode != "public_link" {
+		c.JSON(http.StatusForbidden, gin.H{"error": "workflow requires authentication"})
+		return
+	}
+
+	ver, err := h.stores.Workflows.GetLatestVersion(ctx, wf.ID)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "workflow has no published version"})
+		return
+	}
+
+	stages, err := h.stores.Workflows.ListStages(ctx, wf.ID)
+	if err != nil || len(stages) == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "workflow has no stages"})
+		return
+	}
+
+	// Create the workflow channel (owned by workflow creator)
+	ch := &models.Channel{
+		UserID:      wf.CreatedBy,
+		Title:       wf.Name,
+		Description: wf.Description,
+		Type:        "workflow",
+		TeamID:      wf.TeamID,
+	}
+	if err := h.stores.Channels.Create(ctx, ch); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create channel"})
+		return
+	}
+
+	// Set workflow columns
+	_, err = database.DB.ExecContext(ctx, database.Q(`
+		UPDATE channels
+		SET workflow_id = $1, workflow_version = $2, current_stage = 0,
+		    stage_data = '{}', workflow_status = 'active',
+		    last_activity_at = $3, allow_anonymous = true, ai_mode = 'auto'
+		WHERE id = $4
+	`), wf.ID, ver.VersionNumber, time.Now().UTC(), ch.ID)
+	if err != nil {
+		log.Printf("Failed to set workflow columns: %v", err)
+	}
+
+	// Create anonymous session
+	sessionToken := store.NewID()
+	visitorCount, _ := h.stores.Sessions.CountForChannel(ctx, ch.ID)
+	displayName := "Visitor"
+	if visitorCount > 0 {
+		displayName = fmt.Sprintf("Visitor %d", visitorCount+1)
+	}
+	sess := &models.SessionParticipant{
+		SessionToken: sessionToken,
+		ChannelID:    ch.ID,
+		DisplayName:  displayName,
+	}
+	if err := h.stores.Sessions.Create(ctx, sess); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create session"})
+		return
+	}
+
+	// Add session as channel participant
+	_ = h.stores.Channels.AddParticipant(ctx, &models.ChannelParticipant{
+		ChannelID:       ch.ID,
+		ParticipantType: "session",
+		ParticipantID:   sess.ID,
+		Role:            "visitor",
+	})
+
+	// Bind stage 0 persona
+	if stages[0].PersonaID != nil {
+		_ = h.stores.Channels.AddParticipant(ctx, &models.ChannelParticipant{
+			ChannelID:       ch.ID,
+			ParticipantType: "persona",
+			ParticipantID:   *stages[0].PersonaID,
+			Role:            "member",
+		})
+	}
+
+	// Set session cookie (30 day expiry, matching v0.24.3)
+	c.SetCookie("sb_session", sessionToken, 30*24*60*60, "/", "", false, true)
+
+	// Redirect to chat — visitor lands on existing /w/:channelId
+	c.JSON(http.StatusCreated, gin.H{
+		"channel_id":  ch.ID,
+		"session_id":  sess.ID,
+		"redirect_to": "/w/" + ch.ID,
+	})
+}
--- a/server/handlers/workflow_instances.go
+++ b/server/handlers/workflow_instances.go
@@ -0,0 +1,319 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"git.gobha.me/xcaliber/chat-switchboard/database"
+	"git.gobha.me/xcaliber/chat-switchboard/models"
+	"git.gobha.me/xcaliber/chat-switchboard/store"
+	"git.gobha.me/xcaliber/chat-switchboard/tools"
+)
+
+// ── Workflow Instance Handler ───────────────
+// Manages the runtime lifecycle of workflow channels: starting instances,
+// advancing/rejecting stages, and querying status.
+
+type WorkflowInstanceHandler struct {
+	stores store.Stores
+}
+
+func NewWorkflowInstanceHandler(stores store.Stores) *WorkflowInstanceHandler {
+	return &WorkflowInstanceHandler{stores: stores}
+}
+
+// ── Start ───────────────────────────────────
+
+// Start creates a new workflow channel from a published workflow version.
+// POST /api/v1/workflows/:id/start
+func (h *WorkflowInstanceHandler) Start(c *gin.Context) {
+	ctx := c.Request.Context()
+	wfID := c.Param("id")
+	userID := c.GetString("user_id")
+
+	wf, err := h.stores.Workflows.GetByID(ctx, wfID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "workflow not found"})
+		return
+	}
+	if !wf.IsActive {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "workflow is not active"})
+		return
+	}
+
+	ver, err := h.stores.Workflows.GetLatestVersion(ctx, wfID)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "workflow has no published version — publish first"})
+		return
+	}
+
+	stages, err := h.stores.Workflows.ListStages(ctx, wfID)
+	if err != nil || len(stages) == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "workflow has no stages"})
+		return
+	}
+
+	// Create the workflow channel
+	ch := &models.Channel{
+		UserID:      userID,
+		Title:       wf.Name,
+		Description: wf.Description,
+		Type:        "workflow",
+		TeamID:      wf.TeamID,
+	}
+	if err := h.stores.Channels.Create(ctx, ch); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create channel: " + err.Error()})
+		return
+	}
+
+	// Set workflow-specific columns (not part of base Channel.Create)
+	allowAnon := wf.EntryMode == "public_link"
+	var allowAnonVal interface{} = allowAnon
+	if database.CurrentDialect == database.DialectSQLite {
+		if allowAnon {
+			allowAnonVal = 1
+		} else {
+			allowAnonVal = 0
+		}
+	}
+	_, err = database.DB.ExecContext(ctx, database.Q(`
+		UPDATE channels
+		SET workflow_id = $1, workflow_version = $2, current_stage = 0,
+		    stage_data = '{}', workflow_status = 'active',
+		    last_activity_at = $3, allow_anonymous = $4, ai_mode = 'auto'
+		WHERE id = $5
+	`), wfID, ver.VersionNumber, time.Now().UTC(), allowAnonVal, ch.ID)
+	if err != nil {
+		log.Printf("Failed to set workflow columns on channel %s: %v", ch.ID, err)
+	}
+
+	// Add caller as channel owner
+	_ = h.stores.Channels.AddParticipant(ctx, &models.ChannelParticipant{
+		ChannelID:       ch.ID,
+		ParticipantType: "user",
+		ParticipantID:   userID,
+		Role:            "owner",
+	})
+
+	// Bind stage 0 persona as participant
+	firstStage := stages[0]
+	if firstStage.PersonaID != nil {
+		_ = h.stores.Channels.AddParticipant(ctx, &models.ChannelParticipant{
+			ChannelID:       ch.ID,
+			ParticipantType: "persona",
+			ParticipantID:   *firstStage.PersonaID,
+			Role:            "member",
+		})
+	}
+
+	c.JSON(http.StatusCreated, gin.H{
+		"channel_id":       ch.ID,
+		"workflow_id":      wfID,
+		"workflow_version": ver.VersionNumber,
+		"current_stage":    0,
+		"stage":            firstStage,
+	})
+}
+
+// ── Status ──────────────────────────────────
+
+// WorkflowChannelStatus holds the runtime state of a workflow instance.
+type WorkflowChannelStatus struct {
+	WorkflowID      *string         `json:"workflow_id"`
+	WorkflowVersion *int            `json:"workflow_version"`
+	CurrentStage    int             `json:"current_stage"`
+	StageData       json.RawMessage `json:"stage_data"`
+	Status          string          `json:"status"`
+	LastActivityAt  *time.Time      `json:"last_activity_at"`
+}
+
+// GetStatus returns the workflow state for a channel.
+// GET /api/v1/channels/:id/workflow/status
+func (h *WorkflowInstanceHandler) GetStatus(c *gin.Context) {
+	channelID := c.Param("id")
+	var ws WorkflowChannelStatus
+	var stageData []byte
+	err := database.DB.QueryRowContext(c.Request.Context(), database.Q(`
+		SELECT workflow_id, workflow_version, current_stage,
+		       COALESCE(stage_data, '{}'), COALESCE(workflow_status, 'active'),
+		       last_activity_at
+		FROM channels WHERE id = $1 AND type = 'workflow'
+	`), channelID).Scan(&ws.WorkflowID, &ws.WorkflowVersion,
+		&ws.CurrentStage, &stageData, &ws.Status, &ws.LastActivityAt)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "workflow channel not found"})
+		return
+	}
+	ws.StageData = stageData
+	c.JSON(http.StatusOK, ws)
+}
+
+// ── Advance ─────────────────────────────────
+
+// Advance moves the workflow to the next stage.
+// POST /api/v1/channels/:id/workflow/advance
+func (h *WorkflowInstanceHandler) Advance(c *gin.Context) {
+	ctx := c.Request.Context()
+	channelID := c.Param("id")
+
+	workflowID, currentStage, status, err := h.readWorkflowState(ctx, channelID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "workflow channel not found"})
+		return
+	}
+	if status != "active" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "workflow is " + status + ", cannot advance"})
+		return
+	}
+
+	stages, err := h.stores.Workflows.ListStages(ctx, workflowID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to load stages"})
+		return
+	}
+
+	var body struct {
+		Data json.RawMessage `json:"data,omitempty"`
+	}
+	_ = c.ShouldBindJSON(&body)
+
+	mergedData := tools.MergeWorkflowStageData(ctx, channelID, body.Data)
+	nextStage := currentStage + 1
+
+	if nextStage >= len(stages) {
+		// Workflow complete
+		_, err = database.DB.ExecContext(ctx, database.Q(`
+			UPDATE channels
+			SET current_stage = $1, workflow_status = 'completed',
+			    stage_data = $2, last_activity_at = $3, ai_mode = 'off'
+			WHERE id = $4
+		`), nextStage, mergedData, time.Now().UTC(), channelID)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to complete workflow"})
+			return
+		}
+		tools.CreateWorkflowStageNote(ctx, h.stores, channelID, currentStage, body.Data, "")
+		c.JSON(http.StatusOK, gin.H{"status": "completed", "current_stage": nextStage})
+		return
+	}
+
+	// Advance to next stage
+	_, err = database.DB.ExecContext(ctx, database.Q(`
+		UPDATE channels
+		SET current_stage = $1, stage_data = $2, last_activity_at = $3
+		WHERE id = $4
+	`), nextStage, mergedData, time.Now().UTC(), channelID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to advance stage"})
+		return
+	}
+
+	tools.CreateWorkflowStageNote(ctx, h.stores, channelID, currentStage, body.Data, "")
+
+	nextStageDef := stages[nextStage]
+
+	// Bind next persona
+	if nextStageDef.PersonaID != nil {
+		alreadyIn, _ := h.stores.Channels.IsParticipant(ctx, channelID, "persona", *nextStageDef.PersonaID)
+		if !alreadyIn {
+			_ = h.stores.Channels.AddParticipant(ctx, &models.ChannelParticipant{
+				ChannelID:       channelID,
+				ParticipantType: "persona",
+				ParticipantID:   *nextStageDef.PersonaID,
+				Role:            "member",
+			})
+		}
+	}
+
+	// Notify assignment team (stub — fully wired in v0.26.4)
+	if nextStageDef.AssignmentTeamID != nil {
+		tools.CreateWorkflowAssignment(ctx, channelID, nextStage, *nextStageDef.AssignmentTeamID)
+		log.Printf("Workflow stage '%s' assigned to team %s (channel %s)",
+			nextStageDef.Name, *nextStageDef.AssignmentTeamID, channelID)
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"status":        "active",
+		"current_stage": nextStage,
+		"stage":         nextStageDef,
+	})
+}
+
+// ── Reject ──────────────────────────────────
+
+// Reject returns the workflow to the previous stage with a reason.
+// POST /api/v1/channels/:id/workflow/reject
+func (h *WorkflowInstanceHandler) Reject(c *gin.Context) {
+	ctx := c.Request.Context()
+	channelID := c.Param("id")
+
+	var body struct {
+		Reason string `json:"reason"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.Reason == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "reason is required"})
+		return
+	}
+
+	_, currentStage, status, err := h.readWorkflowState(ctx, channelID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "workflow channel not found"})
+		return
+	}
+	if status != "active" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "workflow is " + status + ", cannot reject"})
+		return
+	}
+	if currentStage <= 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "cannot reject from the first stage"})
+		return
+	}
+
+	prevStage := currentStage - 1
+	_, err = database.DB.ExecContext(ctx, database.Q(`
+		UPDATE channels SET current_stage = $1, last_activity_at = $2 WHERE id = $3
+	`), prevStage, time.Now().UTC(), channelID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to reject stage"})
+		return
+	}
+
+	// Persist rejection as system message
+	if h.stores.Messages != nil {
+		_ = h.stores.Messages.Create(ctx, &models.Message{
+			ChannelID:       channelID,
+			Role:            "system",
+			Content:         "Stage rejected: " + body.Reason,
+			ParticipantType: "user",
+			ParticipantID:   c.GetString("user_id"),
+		})
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"status":        "active",
+		"current_stage": prevStage,
+		"reason":        body.Reason,
+	})
+}
+
+// ── Helpers ─────────────────────────────────
+
+func (h *WorkflowInstanceHandler) readWorkflowState(ctx context.Context, channelID string) (workflowID string, currentStage int, status string, err error) {
+	var wfID *string
+	err = database.DB.QueryRowContext(ctx, database.Q(`
+		SELECT workflow_id, COALESCE(current_stage, 0), COALESCE(workflow_status, 'active')
+		FROM channels WHERE id = $1 AND type = 'workflow'
+	`), channelID).Scan(&wfID, &currentStage, &status)
+	if wfID != nil {
+		workflowID = *wfID
+	}
+	return
+}
+
+// createStageNote and mergeStageData are now in tools/workflow.go
+// (shared between handler and workflow_advance tool).
--- a/server/handlers/workflow_test.go
+++ b/server/handlers/workflow_test.go
@@ -0,0 +1,339 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"git.gobha.me/xcaliber/chat-switchboard/config"
+	authpkg "git.gobha.me/xcaliber/chat-switchboard/auth"
+	"git.gobha.me/xcaliber/chat-switchboard/database"
+	"git.gobha.me/xcaliber/chat-switchboard/middleware"
+	"git.gobha.me/xcaliber/chat-switchboard/store"
+	postgres "git.gobha.me/xcaliber/chat-switchboard/store/postgres"
+	sqlite "git.gobha.me/xcaliber/chat-switchboard/store/sqlite"
+)
+
+// TestWorkflowCRUD exercises the full workflow lifecycle:
+// create → add stages → publish → start instance → advance → complete.
+func TestWorkflowCRUD(t *testing.T) {
+	h := setupWorkflowHarness(t)
+
+	// ── Create workflow ─────────────────────
+
+	resp := h.request("POST", "/api/v1/workflows", h.adminToken, map[string]interface{}{
+		"name":        "Customer Intake",
+		"slug":        "customer-intake",
+		"description": "Collect customer info and route to support",
+		"entry_mode":  "public_link",
+	})
+	if resp.Code != http.StatusCreated {
+		t.Fatalf("Create workflow: got %d, body: %s", resp.Code, resp.Body.String())
+	}
+
+	var wf struct {
+		ID      string `json:"id"`
+		Slug    string `json:"slug"`
+		Version int    `json:"version"`
+	}
+	json.Unmarshal(resp.Body.Bytes(), &wf)
+	if wf.ID == "" {
+		t.Fatal("workflow ID is empty")
+	}
+	if wf.Slug != "customer-intake" {
+		t.Errorf("slug: got %q, want %q", wf.Slug, "customer-intake")
+	}
+	if wf.Version != 1 {
+		t.Errorf("version: got %d, want 1", wf.Version)
+	}
+
+	// ── Get workflow ────────────────────────
+
+	resp = h.request("GET", "/api/v1/workflows/"+wf.ID, h.adminToken, nil)
+	if resp.Code != http.StatusOK {
+		t.Fatalf("Get workflow: got %d", resp.Code)
+	}
+
+	// ── List workflows ──────────────────────
+
+	resp = h.request("GET", "/api/v1/workflows", h.adminToken, nil)
+	if resp.Code != http.StatusOK {
+		t.Fatalf("List workflows: got %d", resp.Code)
+	}
+	var listResp struct {
+		Data []struct{ ID string } `json:"data"`
+	}
+	json.Unmarshal(resp.Body.Bytes(), &listResp)
+	if len(listResp.Data) == 0 {
+		t.Error("List workflows returned empty")
+	}
+
+	// ── Add stages ──────────────────────────
+
+	resp = h.request("POST", "/api/v1/workflows/"+wf.ID+"/stages", h.adminToken, map[string]interface{}{
+		"name":         "Collect Info",
+		"history_mode": "full",
+		"ordinal":      0,
+	})
+	if resp.Code != http.StatusCreated {
+		t.Fatalf("Create stage 0: got %d, body: %s", resp.Code, resp.Body.String())
+	}
+	var stage0 struct{ ID string `json:"id"` }
+	json.Unmarshal(resp.Body.Bytes(), &stage0)
+
+	resp = h.request("POST", "/api/v1/workflows/"+wf.ID+"/stages", h.adminToken, map[string]interface{}{
+		"name":         "Review",
+		"history_mode": "fresh",
+		"ordinal":      1,
+	})
+	if resp.Code != http.StatusCreated {
+		t.Fatalf("Create stage 1: got %d, body: %s", resp.Code, resp.Body.String())
+	}
+	var stage1 struct{ ID string `json:"id"` }
+	json.Unmarshal(resp.Body.Bytes(), &stage1)
+
+	// ── List stages ─────────────────────────
+
+	resp = h.request("GET", "/api/v1/workflows/"+wf.ID+"/stages", h.adminToken, nil)
+	if resp.Code != http.StatusOK {
+		t.Fatalf("List stages: got %d", resp.Code)
+	}
+	var stagesResp struct {
+		Data []struct {
+			ID      string `json:"id"`
+			Ordinal int    `json:"ordinal"`
+		} `json:"data"`
+	}
+	json.Unmarshal(resp.Body.Bytes(), &stagesResp)
+	if len(stagesResp.Data) != 2 {
+		t.Fatalf("List stages: got %d, want 2", len(stagesResp.Data))
+	}
+
+	// ── Reorder stages ──────────────────────
+
+	resp = h.request("PATCH", "/api/v1/workflows/"+wf.ID+"/stages/reorder", h.adminToken, map[string]interface{}{
+		"ordered_ids": []string{stage1.ID, stage0.ID},
+	})
+	if resp.Code != http.StatusOK {
+		t.Fatalf("Reorder stages: got %d, body: %s", resp.Code, resp.Body.String())
+	}
+
+	// ── Update workflow ─────────────────────
+
+	resp = h.request("PATCH", "/api/v1/workflows/"+wf.ID, h.adminToken, map[string]interface{}{
+		"is_active": true,
+	})
+	if resp.Code != http.StatusOK {
+		t.Fatalf("Update workflow: got %d, body: %s", resp.Code, resp.Body.String())
+	}
+
+	// Re-read to get incremented version
+	resp = h.request("GET", "/api/v1/workflows/"+wf.ID, h.adminToken, nil)
+	json.Unmarshal(resp.Body.Bytes(), &wf)
+	if wf.Version != 2 {
+		t.Errorf("version after update: got %d, want 2", wf.Version)
+	}
+
+	// ── Publish ─────────────────────────────
+
+	resp = h.request("POST", "/api/v1/workflows/"+wf.ID+"/publish", h.adminToken, nil)
+	if resp.Code != http.StatusCreated {
+		t.Fatalf("Publish: got %d, body: %s", resp.Code, resp.Body.String())
+	}
+	var ver struct {
+		VersionNumber int             `json:"version_number"`
+		Snapshot      json.RawMessage `json:"snapshot"`
+	}
+	json.Unmarshal(resp.Body.Bytes(), &ver)
+	if ver.VersionNumber != 2 {
+		t.Errorf("published version: got %d, want 2", ver.VersionNumber)
+	}
+	if len(ver.Snapshot) == 0 {
+		t.Error("snapshot is empty")
+	}
+
+	// ── Duplicate publish should conflict ───
+
+	resp = h.request("POST", "/api/v1/workflows/"+wf.ID+"/publish", h.adminToken, nil)
+	if resp.Code != http.StatusConflict {
+		t.Errorf("Duplicate publish: got %d, want 409", resp.Code)
+	}
+
+	// ── Get version ─────────────────────────
+
+	resp = h.request("GET", "/api/v1/workflows/"+wf.ID+"/versions/2", h.adminToken, nil)
+	if resp.Code != http.StatusOK {
+		t.Fatalf("Get version: got %d", resp.Code)
+	}
+
+	// ── Duplicate slug should conflict ──────
+
+	resp = h.request("POST", "/api/v1/workflows", h.adminToken, map[string]interface{}{
+		"name": "Another Intake",
+		"slug": "customer-intake",
+	})
+	if resp.Code != http.StatusConflict {
+		t.Errorf("Duplicate slug: got %d, want 409", resp.Code)
+	}
+
+	// ── Auto-slug from name ─────────────────
+
+	resp = h.request("POST", "/api/v1/workflows", h.adminToken, map[string]interface{}{
+		"name": "Bug Report Triage",
+	})
+	if resp.Code != http.StatusCreated {
+		t.Fatalf("Auto-slug: got %d, body: %s", resp.Code, resp.Body.String())
+	}
+	var wf2 struct{ Slug string `json:"slug"` }
+	json.Unmarshal(resp.Body.Bytes(), &wf2)
+	if wf2.Slug != "bug-report-triage" {
+		t.Errorf("auto-slug: got %q, want %q", wf2.Slug, "bug-report-triage")
+	}
+
+	// ── Delete stage ────────────────────────
+
+	resp = h.request("DELETE", "/api/v1/workflows/"+wf.ID+"/stages/"+stage1.ID, h.adminToken, nil)
+	if resp.Code != http.StatusOK {
+		t.Fatalf("Delete stage: got %d", resp.Code)
+	}
+
+	// ── Delete workflow (cascades) ──────────
+
+	resp = h.request("DELETE", "/api/v1/workflows/"+wf.ID, h.adminToken, nil)
+	if resp.Code != http.StatusOK {
+		t.Fatalf("Delete workflow: got %d", resp.Code)
+	}
+
+	// Confirm gone
+	resp = h.request("GET", "/api/v1/workflows/"+wf.ID, h.adminToken, nil)
+	if resp.Code != http.StatusNotFound {
+		t.Errorf("After delete: got %d, want 404", resp.Code)
+	}
+}
+
+// TestWorkflowValidation tests input validation on workflow endpoints.
+func TestWorkflowValidation(t *testing.T) {
+	h := setupWorkflowHarness(t)
+
+	// Missing name
+	resp := h.request("POST", "/api/v1/workflows", h.adminToken, map[string]interface{}{
+		"slug": "test",
+	})
+	if resp.Code != http.StatusBadRequest {
+		t.Errorf("Missing name: got %d, want 400", resp.Code)
+	}
+
+	// Invalid slug
+	resp = h.request("POST", "/api/v1/workflows", h.adminToken, map[string]interface{}{
+		"name": "Test",
+		"slug": "A",
+	})
+	if resp.Code != http.StatusBadRequest {
+		t.Errorf("Short slug: got %d, want 400", resp.Code)
+	}
+
+	// Invalid entry_mode
+	resp = h.request("POST", "/api/v1/workflows", h.adminToken, map[string]interface{}{
+		"name":       "Test",
+		"entry_mode": "invalid",
+	})
+	if resp.Code != http.StatusBadRequest {
+		t.Errorf("Bad entry_mode: got %d, want 400", resp.Code)
+	}
+
+	// Invalid history_mode on stage
+	resp = h.request("POST", "/api/v1/workflows", h.adminToken, map[string]interface{}{
+		"name": "For Stage Test",
+	})
+	var stageWf struct{ ID string `json:"id"` }
+	json.Unmarshal(resp.Body.Bytes(), &stageWf)
+
+	resp = h.request("POST", "/api/v1/workflows/"+stageWf.ID+"/stages", h.adminToken, map[string]interface{}{
+		"name":         "Bad Mode",
+		"history_mode": "invalid",
+	})
+	if resp.Code != http.StatusBadRequest {
+		t.Errorf("Bad history_mode: got %d, want 400", resp.Code)
+	}
+}
+
+// ── Workflow Test Harness ───────────────────
+
+type workflowHarness struct {
+	*testHarness
+	adminToken string
+	adminID    string
+}
+
+func setupWorkflowHarness(t *testing.T) *workflowHarness {
+	t.Helper()
+	database.RequireTestDB(t)
+	database.TruncateAll(t)
+
+	cfg := &config.Config{
+		JWTSecret: testJWTSecret,
+		BasePath:  "",
+	}
+
+	var stores store.Stores
+	if database.IsSQLite() {
+		stores = sqlite.NewStores(database.TestDB)
+	} else {
+		stores = postgres.NewStores(database.TestDB)
+	}
+
+	r := gin.New()
+	api := r.Group("/api/v1")
+
+	// Auth (for token generation)
+	auth := NewAuthHandler(cfg, stores, nil, authpkg.NewBuiltinProvider())
+	api.POST("/auth/login", auth.Login)
+	api.POST("/auth/register", auth.Register)
+
+	protected := api.Group("")
+	protected.Use(middleware.Auth(cfg))
+
+	// Workflow CRUD
+	wfH := NewWorkflowHandler(stores)
+	protected.GET("/workflows", wfH.List)
+	protected.POST("/workflows", wfH.Create)
+	protected.GET("/workflows/:id", wfH.Get)
+	protected.PATCH("/workflows/:id", wfH.Update)
+	protected.DELETE("/workflows/:id", wfH.Delete)
+	protected.GET("/workflows/:id/stages", wfH.ListStages)
+	protected.POST("/workflows/:id/stages", wfH.CreateStage)
+	protected.PUT("/workflows/:id/stages/:sid", wfH.UpdateStage)
+	protected.DELETE("/workflows/:id/stages/:sid", wfH.DeleteStage)
+	protected.PATCH("/workflows/:id/stages/reorder", wfH.ReorderStages)
+	protected.POST("/workflows/:id/publish", wfH.Publish)
+	protected.GET("/workflows/:id/versions/:version", wfH.GetVersion)
+
+	// Workflow instances
+	wfInstH := NewWorkflowInstanceHandler(stores)
+	protected.POST("/workflows/:id/start", wfInstH.Start)
+	protected.GET("/channels/:id/workflow/status", wfInstH.GetStatus)
+	protected.POST("/channels/:id/workflow/advance", wfInstH.Advance)
+	protected.POST("/channels/:id/workflow/reject", wfInstH.Reject)
+
+	// Channels (needed for workflow instance creation)
+	channels := NewChannelHandler()
+	protected.GET("/channels", channels.ListChannels)
+	protected.POST("/channels", channels.CreateChannel)
+	protected.GET("/channels/:id", channels.GetChannel)
+
+	// Seed an admin user (handle + auth_source required since v0.24.0)
+	adminID := seedInsertReturningID(t,
+		`INSERT INTO users (username, email, password_hash, role, handle, auth_source) VALUES ($1, $2, $3, $4, $5, $6) RETURNING id`,
+		"wf-admin", "wf-admin@test.com", "$2a$10$test", "admin", "wf-admin", "builtin",
+	)
+
+	token := makeToken(adminID, "wf-admin@test.com", "admin")
+
+	return &workflowHarness{
+		testHarness: &testHarness{router: r, t: t},
+		adminToken:  token,
+		adminID:     adminID,
+	}
+}
--- a/server/handlers/workflows.go
+++ b/server/handlers/workflows.go
@@ -0,0 +1,341 @@
+package handlers
+
+import (
+	"database/sql"
+	"encoding/json"
+	"net/http"
+	"regexp"
+	"strconv"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"git.gobha.me/xcaliber/chat-switchboard/models"
+	"git.gobha.me/xcaliber/chat-switchboard/store"
+)
+
+// ── Workflow Handler ────────────────────────
+
+type WorkflowHandler struct {
+	stores store.Stores
+}
+
+func NewWorkflowHandler(stores store.Stores) *WorkflowHandler {
+	return &WorkflowHandler{stores: stores}
+}
+
+var slugRe = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*[a-z0-9]$`)
+
+func validSlug(s string) bool {
+	if len(s) < 2 || len(s) > 64 {
+		return false
+	}
+	return slugRe.MatchString(s)
+}
+
+// ── Workflow CRUD ───────────────────────────
+
+// List returns workflows visible to the caller.
+// GET /api/v1/workflows?team_id=...
+func (h *WorkflowHandler) List(c *gin.Context) {
+	teamID := c.Query("team_id")
+	var result []models.Workflow
+	var err error
+	if teamID != "" {
+		result, err = h.stores.Workflows.ListForTeam(c.Request.Context(), teamID)
+	} else {
+		result, err = h.stores.Workflows.ListGlobal(c.Request.Context())
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list workflows"})
+		return
+	}
+	if result == nil {
+		result = []models.Workflow{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": result})
+}
+
+// Get returns a single workflow with its stages.
+// GET /api/v1/workflows/:id
+func (h *WorkflowHandler) Get(c *gin.Context) {
+	w, err := h.stores.Workflows.GetByID(c.Request.Context(), c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "workflow not found"})
+		return
+	}
+	stages, _ := h.stores.Workflows.ListStages(c.Request.Context(), w.ID)
+	if stages == nil {
+		stages = []models.WorkflowStage{}
+	}
+	w.Stages = stages
+	c.JSON(http.StatusOK, w)
+}
+
+// Create creates a new workflow definition.
+// POST /api/v1/workflows
+func (h *WorkflowHandler) Create(c *gin.Context) {
+	var w models.Workflow
+	if err := c.ShouldBindJSON(&w); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if w.Name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+	if w.Slug == "" {
+		w.Slug = slugify(w.Name)
+	}
+	if !validSlug(w.Slug) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "slug must be 2-64 chars, lowercase alphanumeric and hyphens"})
+		return
+	}
+	if w.EntryMode == "" {
+		w.EntryMode = "public_link"
+	}
+	if w.EntryMode != "public_link" && w.EntryMode != "team_only" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "entry_mode must be public_link or team_only"})
+		return
+	}
+
+	w.CreatedBy = c.GetString("user_id")
+
+	if err := h.stores.Workflows.Create(c.Request.Context(), &w); err != nil {
+		if strings.Contains(err.Error(), "unique") || strings.Contains(err.Error(), "UNIQUE") {
+			c.JSON(http.StatusConflict, gin.H{"error": "slug already exists in this scope"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create workflow: " + err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, w)
+}
+
+// Update patches a workflow definition.
+// PATCH /api/v1/workflows/:id
+func (h *WorkflowHandler) Update(c *gin.Context) {
+	id := c.Param("id")
+	var patch models.WorkflowPatch
+	if err := c.ShouldBindJSON(&patch); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if patch.EntryMode != nil && *patch.EntryMode != "public_link" && *patch.EntryMode != "team_only" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "entry_mode must be public_link or team_only"})
+		return
+	}
+	if err := h.stores.Workflows.Update(c.Request.Context(), id, patch); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to update workflow"})
+		return
+	}
+	w, _ := h.stores.Workflows.GetByID(c.Request.Context(), id)
+	if w == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "workflow not found"})
+		return
+	}
+	c.JSON(http.StatusOK, w)
+}
+
+// Delete deletes a workflow and all its stages/versions (CASCADE).
+// DELETE /api/v1/workflows/:id
+func (h *WorkflowHandler) Delete(c *gin.Context) {
+	if err := h.stores.Workflows.Delete(c.Request.Context(), c.Param("id")); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to delete workflow"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"deleted": true})
+}
+
+// ── Stage CRUD ──────────────────────────────
+
+// ListStages returns stages for a workflow, ordered by ordinal.
+// GET /api/v1/workflows/:id/stages
+func (h *WorkflowHandler) ListStages(c *gin.Context) {
+	stages, err := h.stores.Workflows.ListStages(c.Request.Context(), c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list stages"})
+		return
+	}
+	if stages == nil {
+		stages = []models.WorkflowStage{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": stages})
+}
+
+// CreateStage adds a stage to a workflow.
+// POST /api/v1/workflows/:id/stages
+func (h *WorkflowHandler) CreateStage(c *gin.Context) {
+	var st models.WorkflowStage
+	if err := c.ShouldBindJSON(&st); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	st.WorkflowID = c.Param("id")
+	if st.Name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
+		return
+	}
+	if st.HistoryMode == "" {
+		st.HistoryMode = "full"
+	}
+	if st.HistoryMode != "full" && st.HistoryMode != "summary" && st.HistoryMode != "fresh" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "history_mode must be full, summary, or fresh"})
+		return
+	}
+	if st.Ordinal == 0 {
+		existing, _ := h.stores.Workflows.ListStages(c.Request.Context(), st.WorkflowID)
+		st.Ordinal = len(existing)
+	}
+	if err := h.stores.Workflows.CreateStage(c.Request.Context(), &st); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create stage: " + err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, st)
+}
+
+// UpdateStage updates a stage.
+// PUT /api/v1/workflows/:id/stages/:sid
+func (h *WorkflowHandler) UpdateStage(c *gin.Context) {
+	var st models.WorkflowStage
+	if err := c.ShouldBindJSON(&st); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	st.ID = c.Param("sid")
+	st.WorkflowID = c.Param("id")
+	if st.HistoryMode != "" && st.HistoryMode != "full" && st.HistoryMode != "summary" && st.HistoryMode != "fresh" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "history_mode must be full, summary, or fresh"})
+		return
+	}
+	if err := h.stores.Workflows.UpdateStage(c.Request.Context(), &st); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to update stage"})
+		return
+	}
+	c.JSON(http.StatusOK, st)
+}
+
+// DeleteStage removes a stage.
+// DELETE /api/v1/workflows/:id/stages/:sid
+func (h *WorkflowHandler) DeleteStage(c *gin.Context) {
+	if err := h.stores.Workflows.DeleteStage(c.Request.Context(), c.Param("sid")); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to delete stage"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"deleted": true})
+}
+
+// ReorderStages sets the ordinal for all stages.
+// PATCH /api/v1/workflows/:id/stages/reorder
+func (h *WorkflowHandler) ReorderStages(c *gin.Context) {
+	var body struct {
+		OrderedIDs []string `json:"ordered_ids"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || len(body.OrderedIDs) == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "ordered_ids required"})
+		return
+	}
+	if err := h.stores.Workflows.ReorderStages(c.Request.Context(), c.Param("id"), body.OrderedIDs); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to reorder stages"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"reordered": true})
+}
+
+// ── Publish ─────────────────────────────────
+
+// Publish creates an immutable version snapshot of the current workflow state.
+// POST /api/v1/workflows/:id/publish
+func (h *WorkflowHandler) Publish(c *gin.Context) {
+	wfID := c.Param("id")
+	w, err := h.stores.Workflows.GetByID(c.Request.Context(), wfID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "workflow not found"})
+		return
+	}
+
+	stages, _ := h.stores.Workflows.ListStages(c.Request.Context(), wfID)
+	if stages == nil {
+		stages = []models.WorkflowStage{}
+	}
+
+	// Snapshot includes persona tool grants at publish time (frozen for running instances)
+	type stageSnapshot struct {
+		models.WorkflowStage
+		ToolGrants []string `json:"tool_grants,omitempty"`
+	}
+	snapshotStages := make([]stageSnapshot, len(stages))
+	for i, st := range stages {
+		snapshotStages[i] = stageSnapshot{WorkflowStage: st}
+		if st.PersonaID != nil && h.stores.Personas != nil {
+			grants, _ := h.stores.Personas.GetToolGrants(c.Request.Context(), *st.PersonaID)
+			snapshotStages[i].ToolGrants = grants
+		}
+	}
+
+	snapshot := map[string]interface{}{
+		"workflow": w,
+		"stages":   snapshotStages,
+	}
+	snapshotJSON, err := json.Marshal(snapshot)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to serialize snapshot"})
+		return
+	}
+
+	v := &models.WorkflowVersion{
+		WorkflowID:    wfID,
+		VersionNumber: w.Version,
+		Snapshot:      snapshotJSON,
+	}
+
+	existing, _ := h.stores.Workflows.GetVersion(c.Request.Context(), wfID, w.Version)
+	if existing != nil {
+		c.JSON(http.StatusConflict, gin.H{"error": "version already published — edit the workflow to increment"})
+		return
+	}
+
+	if err := h.stores.Workflows.Publish(c.Request.Context(), v); err != nil {
+		if strings.Contains(err.Error(), "unique") || strings.Contains(err.Error(), "UNIQUE") {
+			c.JSON(http.StatusConflict, gin.H{"error": "version already published"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to publish: " + err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, v)
+}
+
+// GetVersion returns a specific version snapshot.
+// GET /api/v1/workflows/:id/versions/:version
+func (h *WorkflowHandler) GetVersion(c *gin.Context) {
+	wfID := c.Param("id")
+	vNum, err := strconv.Atoi(c.Param("version"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid version number"})
+		return
+	}
+	v, err := h.stores.Workflows.GetVersion(c.Request.Context(), wfID, vNum)
+	if err != nil {
+		if err == sql.ErrNoRows {
+			c.JSON(http.StatusNotFound, gin.H{"error": "version not found"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to get version"})
+		return
+	}
+	c.JSON(http.StatusOK, v)
+}
+
+// ── Helpers ─────────────────────────────────
+
+func slugify(name string) string {
+	s := strings.ToLower(strings.TrimSpace(name))
+	s = regexp.MustCompile(`[^a-z0-9]+`).ReplaceAllString(s, "-")
+	s = strings.Trim(s, "-")
+	if len(s) > 64 {
+		s = s[:64]
+	}
+	return s
+}