feat: Generate working branch names upfront in backend API

Implements Option 3 solution for improved git repository context UX.
The backend now generates working branch names during session creation,
providing clear visibility in the UI and simplifying runner logic.

Backend Changes:
- Added branch name generation helpers in handlers/helpers.go:
  - isProtectedBranch(): Detects commonly protected branches
  - sanitizeBranchName(): Converts display names to valid git branch names
  - generateWorkingBranch(): Core logic for branch name generation
    - Uses user-requested branch if specified
    - Creates work/{branch}/{sessionID} for protected branches
    - Falls back to sanitized session name or session-{ID}
- Updated CreateSession and AddRepo handlers to process repos and generate
  branch names upfront
- Extended SimpleRepo type with WorkingBranch and AllowProtectedWork input fields

Runner Changes:
- Simplified wrapper.py repository cloning logic
- Removed _is_protected_branch() and _handle_protected_branch() methods
- Now simply reads 'branch' from spec and checks out/creates it
- No more runtime auto-generation logic

Frontend Changes:
- Updated addRepoMutation to send workingBranch and allowProtectedWork
- Simplified Repository type (removed baseBranch/featureBranch)
- Changed display from "Base: main" to "Branch: {workingBranch}"
- Now shows the actual working branch generated by backend

User Experience:
- Users can now see the exact branch that will be used before session starts
- Protected branch handling is transparent (shows work/{branch}/{sessionID})
- Session-named branches are visible upfront (e.g., "Fix-login-bug")

Fixes part of #376

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: sallyom

components/backend/handlers/helpers.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"log"
 	"math"
+	"strings"
 	"time"
 
 	authv1 "k8s.io/api/authorization/v1"
@@ -74,3 +75,74 @@ func ValidateSecretAccess(ctx context.Context, k8sClient kubernetes.Interface, n
 
 	return nil
 }
+
+// isProtectedBranch checks if a branch name is commonly protected
+func isProtectedBranch(branch string) bool {
+	if branch == "" {
+		return false
+	}
+	protectedNames := []string{
+		"main", "master", "develop", "dev", "development",
+		"production", "prod", "staging", "stage", "qa", "test", "stable",
+	}
+	branchLower := strings.ToLower(strings.TrimSpace(branch))
+	for _, protected := range protectedNames {
+		if branchLower == protected {
+			return true
+		}
+	}
+	return false
+}
+
+// sanitizeBranchName converts a display name to a valid git branch name
+func sanitizeBranchName(name string) string {
+	// Replace spaces with hyphens
+	name = strings.ReplaceAll(name, " ", "-")
+	// Remove or replace invalid characters for git branch names
+	// Valid: alphanumeric, dash, underscore, slash, dot (but not at start/end)
+	var result strings.Builder
+	for _, r := range name {
+		if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') ||
+			(r >= '0' && r <= '9') || r == '-' || r == '_' || r == '/' {
+			result.WriteRune(r)
+		}
+	}
+	sanitized := result.String()
+	// Trim leading/trailing dashes or slashes
+	sanitized = strings.Trim(sanitized, "-/")
+	return sanitized
+}
+
+// generateWorkingBranch generates a working branch name based on the session and repo context
+// Returns the branch name to use for the session
+func generateWorkingBranch(sessionDisplayName, sessionID, requestedBranch string, allowProtectedWork bool) string {
+	// If user explicitly requested a branch
+	if requestedBranch != "" {
+		// Check if it's protected and user hasn't allowed working on it
+		if isProtectedBranch(requestedBranch) && !allowProtectedWork {
+			// Create a temporary working branch to protect the base branch
+			sessionIDShort := sessionID
+			if len(sessionID) > 8 {
+				sessionIDShort = sessionID[:8]
+			}
+			return fmt.Sprintf("work/%s/%s", requestedBranch, sessionIDShort)
+		}
+		// User requested non-protected branch or explicitly allowed protected work
+		return requestedBranch
+	}
+
+	// No branch requested - generate from session name
+	if sessionDisplayName != "" {
+		sanitized := sanitizeBranchName(sessionDisplayName)
+		if sanitized != "" {
+			return sanitized
+		}
+	}
+
+	// Fallback: use session ID
+	sessionIDShort := sessionID
+	if len(sessionID) > 8 {
+		sessionIDShort = sessionID[:8]
+	}
+	return fmt.Sprintf("session-%s", sessionIDShort)
+}

components/backend/handlers/sessions.go

@@ -621,14 +621,36 @@ func CreateSession(c *gin.Context) {
 	}
 
 	// Set multi-repo configuration on spec (simplified format)
+	// Generate working branch names upfront based on session context
 	{
 		spec := session["spec"].(map[string]interface{})
 		if len(req.Repos) > 0 {
 			arr := make([]map[string]interface{}, 0, len(req.Repos))
 			for _, r := range req.Repos {
-				m := map[string]interface{}{"url": r.URL}
-				if r.Branch != nil {
-					m["branch"] = *r.Branch
+				// Determine the working branch to use
+				var requestedBranch string
+				if r.WorkingBranch != nil {
+					requestedBranch = strings.TrimSpace(*r.WorkingBranch)
+				} else if r.Branch != nil {
+					requestedBranch = strings.TrimSpace(*r.Branch)
+				}
+
+				allowProtected := false
+				if r.AllowProtectedWork != nil {
+					allowProtected = *r.AllowProtectedWork
+				}
+
+				// Generate the actual branch name that will be used
+				workingBranch := generateWorkingBranch(
+					req.DisplayName,
+					name, // session name (unique ID)
+					requestedBranch,
+					allowProtected,
+				)
+
+				m := map[string]interface{}{
+					"url":    r.URL,
+					"branch": workingBranch,
 				}
 				arr = append(arr, m)
 			}
@@ -1406,19 +1428,17 @@ func AddRepo(c *gin.Context) {
 	}
 
 	var req struct {
-		URL    string `json:"url" binding:"required"`
-		Branch string `json:"branch"`
+		URL                string `json:"url" binding:"required"`
+		Branch             string `json:"branch"`
+		WorkingBranch      string `json:"workingBranch"`
+		AllowProtectedWork bool   `json:"allowProtectedWork"`
 	}
 
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 
-	if req.Branch == "" {
-		req.Branch = "main"
-	}
-
 	gvr := GetAgenticSessionV1Alpha1Resource()
 	item, err := k8sDyn.Resource(gvr).Namespace(project).Get(context.TODO(), sessionName, v1.GetOptions{})
 	if err != nil {
@@ -1447,9 +1467,29 @@ func AddRepo(c *gin.Context) {
 		repos = []interface{}{}
 	}
 
+	// Determine the requested branch
+	requestedBranch := req.WorkingBranch
+	if requestedBranch == "" {
+		requestedBranch = req.Branch
+	}
+
+	// Get session display name for branch generation
+	displayName := ""
+	if dn, ok := spec["displayName"].(string); ok {
+		displayName = dn
+	}
+
+	// Generate the actual working branch name
+	workingBranch := generateWorkingBranch(
+		displayName,
+		sessionName,
+		requestedBranch,
+		req.AllowProtectedWork,
+	)
+
 	newRepo := map[string]interface{}{
 		"url":    req.URL,
-		"branch": req.Branch,
+		"branch": workingBranch,
 	}
 	repos = append(repos, newRepo)
 	spec["repos"] = repos

components/backend/types/session.go

@@ -28,8 +28,10 @@ type AgenticSessionSpec struct {
 
 // SimpleRepo represents a simplified repository configuration
 type SimpleRepo struct {
-	URL    string  `json:"url"`
-	Branch *string `json:"branch,omitempty"`
+	URL                string  `json:"url"`
+	Branch             *string `json:"branch,omitempty"`
+	WorkingBranch      *string `json:"workingBranch,omitempty"`      // User-requested working branch (input only)
+	AllowProtectedWork *bool   `json:"allowProtectedWork,omitempty"` // Allow work directly on protected branches (input only)
 }
 
 type AgenticSessionStatus struct {

components/frontend/src/app/projects/[name]/sessions/[sessionName]/components/accordions/repositories-accordion.tsx

@@ -8,9 +8,7 @@ import { Button } from "@/components/ui/button";
 
 type Repository = {
   url: string;
-  branch?: string;
-  baseBranch?: string;
-  featureBranch?: string;
+  branch?: string; // The actual working branch (generated by backend)
   allowProtectedWork?: boolean;
   sync?: {
     url: string;
@@ -105,9 +103,8 @@ export function RepositoriesAccordion({
                 const repoName = repo.url.split('/').pop()?.replace('.git', '') || `repo-${idx}`;
                 const isRemoving = removingRepo === repoName;
 
-                // Determine which branch info to show
-                const baseBranch = repo.baseBranch || repo.branch || 'main';
-                const featureBranch = repo.featureBranch;
+                // Get the actual working branch from spec (generated by backend)
+                const workingBranch = repo.branch || 'main';
                 const hasSync = !!repo.sync?.url;
                 const allowProtected = repo.allowProtectedWork;
 
@@ -135,16 +132,10 @@ export function RepositoriesAccordion({
 
                         {/* Branch information */}
                         <div className="flex flex-wrap gap-1 text-xs">
-                          <div className="inline-flex items-center gap-1 bg-background px-2 py-0.5 rounded border">
-                            <span className="text-muted-foreground">Base:</span>
-                            <span className="font-mono">{baseBranch}</span>
+                          <div className="inline-flex items-center gap-1 bg-blue-50 dark:bg-blue-950 px-2 py-0.5 rounded border border-blue-200 dark:border-blue-800">
+                            <span className="text-blue-700 dark:text-blue-300">Branch:</span>
+                            <span className="font-mono text-blue-900 dark:text-blue-100">{workingBranch}</span>
                           </div>
-                          {featureBranch && (
-                            <div className="inline-flex items-center gap-1 bg-blue-50 dark:bg-blue-950 px-2 py-0.5 rounded border border-blue-200 dark:border-blue-800">
-                              <span className="text-blue-700 dark:text-blue-300">Feature:</span>
-                              <span className="font-mono text-blue-900 dark:text-blue-100">{featureBranch}</span>
-                            </div>
-                          )}
                           {hasSync && (
                             <div className="inline-flex items-center gap-1 bg-green-50 dark:bg-green-950 px-2 py-0.5 rounded border border-green-200 dark:border-green-800">
                               <GitMerge className="h-3 w-3 text-green-600 dark:text-green-400" />

components/frontend/src/app/projects/[name]/sessions/[sessionName]/page.tsx

@@ -214,7 +214,7 @@ export default function ProjectSessionDetailPage({
 
   // Repo management mutations
   const addRepoMutation = useMutation({
-    mutationFn: async (repo: { url: string; branch: string }) => {
+    mutationFn: async (repo: { url: string; workingBranch?: string; allowProtectedWork?: boolean }) => {
       setRepoChanging(true);
       const response = await fetch(
         `/api/projects/${projectName}/agentic-sessions/${sessionName}/repos`,
@@ -1460,10 +1460,12 @@ export default function ProjectSessionDetailPage({
         open={contextModalOpen}
         onOpenChange={setContextModalOpen}
         onAddRepository={async (config) => {
-          // For now, use workingBranch as branch (backend compatibility)
+          // Send workingBranch and allowProtectedWork to backend
+          // Backend will generate the actual branch name to use
           await addRepoMutation.mutateAsync({
             url: config.url,
-            branch: config.workingBranch || 'main'
+            workingBranch: config.workingBranch,
+            allowProtectedWork: config.allowProtectedWork
           });
           setContextModalOpen(false);
         }}