feat: implement ephemeral polecat model

This implements the ephemeral polecat model where polecats are spawned fresh for each task and deleted upon completion. Key changes: **Spawn (internal/cmd/spawn.go):** - Always create fresh worktree from main branch - Run bd init in new worktree to initialize beads - Remove --create flag (now implicit) - Replace stale polecats with fresh worktrees **Handoff (internal/cmd/handoff.go):** - Add rig/polecat detection from environment and tmux session - Send shutdown requests to correct witness (rig/witness) - Include polecat name in lifecycle request body **Witness (internal/witness/manager.go):** - Add mail checking in monitoring loop - Process LIFECYCLE shutdown requests - Implement full cleanup sequence: - Kill tmux session - Remove git worktree - Delete polecat branch **Polecat state machine (internal/polecat/types.go):** - Primary states: working, done, stuck - Deprecate idle/active (kept for backward compatibility) - New polecats start in working state - ClearIssue transitions to done (not idle) **Polecat commands (internal/cmd/polecat.go):** - Update list to show "Active Polecats" - Normalize legacy states for display - Add deprecation warnings to wake/sleep commands Closes gt-7ik 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-19 01:48:59 -08:00
parent 717bc89132
commit 231d6e92e0
7 changed files with 393 additions and 133 deletions
--- a/internal/cmd/handoff.go
+++ b/internal/cmd/handoff.go
@@ -226,9 +226,12 @@ func getManager(role Role) string {
 	case RoleMayor, RoleWitness:
 		return "daemon/"
 	case RolePolecat, RoleRefinery:
-		// Would need rig context to determine witness address
-		// For now, use a placeholder pattern
-		return "<rig>/witness"
+		// Detect rig from environment or working directory
+		rigName := detectRigName()
+		if rigName != "" {
+			return rigName + "/witness"
+		}
+		return "witness/" // fallback
 	case RoleCrew:
 		return "human" // Crew is human-managed
 	default:
@@ -236,6 +239,41 @@ func getManager(role Role) string {
 	}
 }

+// detectRigName detects the rig name from environment or directory context.
+func detectRigName() string {
+	// Check environment variable first
+	if rig := os.Getenv("GT_RIG"); rig != "" {
+		return rig
+	}
+
+	// Try to detect from tmux session name (format: gt-<rig>-<polecat>)
+	out, err := exec.Command("tmux", "display-message", "-p", "#{session_name}").Output()
+	if err == nil {
+		sessionName := strings.TrimSpace(string(out))
+		if strings.HasPrefix(sessionName, "gt-") {
+			parts := strings.SplitN(sessionName, "-", 3)
+			if len(parts) >= 2 {
+				return parts[1]
+			}
+		}
+	}
+
+	// Try to detect from working directory
+	cwd, err := os.Getwd()
+	if err != nil {
+		return ""
+	}
+
+	// Look for "polecats" in path: .../rig/polecats/polecat/...
+	if idx := strings.Index(cwd, "/polecats/"); idx != -1 {
+		// Extract rig name from path before /polecats/
+		rigPath := cwd[:idx]
+		return filepath.Base(rigPath)
+	}
+
+	return ""
+}
+
 // sendHandoffMail sends a handoff message to ourselves for the successor to read.
 func sendHandoffMail(role Role, townRoot string) error {
 	// Determine our address
@@ -286,19 +324,26 @@ func sendLifecycleRequest(manager string, role Role, action HandoffAction, townR
 		return nil
 	}

+	// Get polecat name for identification
+	polecatName := detectPolecatName()
+	rigName := detectRigName()
+
 	subject := fmt.Sprintf("LIFECYCLE: %s requesting %s", role, action)
 	body := fmt.Sprintf(`Lifecycle request from %s.

 Action: %s
+Rig: %s
+Polecat: %s
 Time: %s

 Please verify state and execute lifecycle action.
-`, role, action, time.Now().Format(time.RFC3339))
+`, role, action, rigName, polecatName, time.Now().Format(time.RFC3339))

 	// Send via bd mail (syntax: bd mail send <recipient> -s <subject> -m <body>)
 	cmd := exec.Command("bd", "mail", "send", manager,
 		"-s", subject,
 		"-m", body,
+		"--type", "task", // Mark as task requiring action
 	)
 	cmd.Dir = townRoot

@@ -309,6 +354,45 @@ Please verify state and execute lifecycle action.
 	return nil
 }

+// detectPolecatName detects the polecat name from environment or directory context.
+func detectPolecatName() string {
+	// Check environment variable first
+	if polecat := os.Getenv("GT_POLECAT"); polecat != "" {
+		return polecat
+	}
+
+	// Try to detect from tmux session name (format: gt-<rig>-<polecat>)
+	out, err := exec.Command("tmux", "display-message", "-p", "#{session_name}").Output()
+	if err == nil {
+		sessionName := strings.TrimSpace(string(out))
+		if strings.HasPrefix(sessionName, "gt-") {
+			parts := strings.SplitN(sessionName, "-", 3)
+			if len(parts) >= 3 {
+				return parts[2]
+			}
+		}
+	}
+
+	// Try to detect from working directory
+	cwd, err := os.Getwd()
+	if err != nil {
+		return ""
+	}
+
+	// Look for "polecats" in path: .../rig/polecats/polecat/...
+	if idx := strings.Index(cwd, "/polecats/"); idx != -1 {
+		// Extract polecat name from path after /polecats/
+		remainder := cwd[idx+len("/polecats/"):]
+		// Take first component
+		if slashIdx := strings.Index(remainder, "/"); slashIdx != -1 {
+			return remainder[:slashIdx]
+		}
+		return remainder
+	}
+
+	return ""
+}
+
 // setRequestingState updates state.json to indicate we're requesting lifecycle action.
 func setRequestingState(role Role, action HandoffAction, townRoot string) error {
 	// Determine state file location based on role
--- a/internal/cmd/polecat.go
+++ b/internal/cmd/polecat.go
@@ -40,11 +40,11 @@ var polecatListCmd = &cobra.Command{
 	Short: "List polecats in a rig",
 	Long: `List polecats in a rig or all rigs.

-Output:
-  - Name
-  - State (idle/active/working/done/stuck)
-  - Current issue (if any)
-  - Session status (running/stopped)
+In the ephemeral model, polecats exist only while working. The list shows
+all currently active polecats with their states:
+  - working: Actively working on an issue
+  - done: Completed work, waiting for cleanup
+  - stuck: Needs assistance

 Examples:
  gt polecat list gastown
@@ -85,10 +85,13 @@ Example:

 var polecatWakeCmd = &cobra.Command{
 	Use:   "wake <rig>/<polecat>",
-	Short: "Mark polecat as active (ready for work)",
-	Long: `Mark polecat as active (ready for work).
+	Short: "(Deprecated) Resume a polecat to working state",
+	Long: `Resume a polecat to working state.

-Transitions: idle → active
+DEPRECATED: In the ephemeral model, polecats are created fresh for each task
+via 'gt spawn'. This command is kept for backward compatibility.
+
+Transitions: done → working

 Example:
  gt polecat wake gastown/Toast`,
@@ -98,11 +101,14 @@ Example:

 var polecatSleepCmd = &cobra.Command{
 	Use:   "sleep <rig>/<polecat>",
-	Short: "Mark polecat as idle (not available)",
-	Long: `Mark polecat as idle (not available).
+	Short: "(Deprecated) Mark polecat as done",
+	Long: `Mark polecat as done.

-Transitions: active → idle
-Fails if session is running (stop first).
+DEPRECATED: In the ephemeral model, polecats use 'gt handoff' when complete,
+which triggers automatic cleanup by the Witness. This command is kept for
+backward compatibility.
+
+Transitions: working → done

 Example:
  gt polecat sleep gastown/Toast`,
@@ -224,11 +230,11 @@ func runPolecatList(cmd *cobra.Command, args []string) error {
 	}

 	if len(allPolecats) == 0 {
-		fmt.Println("No polecats found.")
+		fmt.Println("No active polecats found.")
 		return nil
 	}

-	fmt.Printf("%s\n\n", style.Bold.Render("Polecats"))
+	fmt.Printf("%s\n\n", style.Bold.Render("Active Polecats"))
 	for _, p := range allPolecats {
 		// Session indicator
 		sessionStatus := style.Dim.Render("○")
@@ -236,9 +242,15 @@ func runPolecatList(cmd *cobra.Command, args []string) error {
 			sessionStatus = style.Success.Render("●")
 		}

+		// Normalize state for display (legacy idle/active → working)
+		displayState := p.State
+		if p.State == polecat.StateIdle || p.State == polecat.StateActive {
+			displayState = polecat.StateWorking
+		}
+
 		// State color
-		stateStr := string(p.State)
-		switch p.State {
+		stateStr := string(displayState)
+		switch displayState {
 		case polecat.StateWorking:
 			stateStr = style.Info.Render(stateStr)
 		case polecat.StateStuck:
@@ -316,6 +328,9 @@ func runPolecatRemove(cmd *cobra.Command, args []string) error {
 }

 func runPolecatWake(cmd *cobra.Command, args []string) error {
+	fmt.Println(style.Warning.Render("DEPRECATED: Use 'gt spawn' to create fresh polecats instead"))
+	fmt.Println()
+
 	rigName, polecatName, err := parseAddress(args[0])
 	if err != nil {
 		return err
@@ -330,11 +345,14 @@ func runPolecatWake(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("waking polecat: %w", err)
 	}

-	fmt.Printf("%s Polecat %s is now active.\n", style.SuccessPrefix, polecatName)
+	fmt.Printf("%s Polecat %s is now working.\n", style.SuccessPrefix, polecatName)
 	return nil
 }

 func runPolecatSleep(cmd *cobra.Command, args []string) error {
+	fmt.Println(style.Warning.Render("DEPRECATED: Use 'gt handoff' from within a polecat session instead"))
+	fmt.Println()
+
 	rigName, polecatName, err := parseAddress(args[0])
 	if err != nil {
 		return err
@@ -350,13 +368,13 @@ func runPolecatSleep(cmd *cobra.Command, args []string) error {
 	sessMgr := session.NewManager(t, r)
 	running, _ := sessMgr.IsRunning(polecatName)
 	if running {
-		return fmt.Errorf("session is running. Stop it first with: gt session stop %s/%s", rigName, polecatName)
+		return fmt.Errorf("session is running. Use 'gt handoff' from the polecat session, or stop it with: gt session stop %s/%s", rigName, polecatName)
 	}

 	if err := mgr.Sleep(polecatName); err != nil {
-		return fmt.Errorf("sleeping polecat: %w", err)
+		return fmt.Errorf("marking polecat as done: %w", err)
 	}

-	fmt.Printf("%s Polecat %s is now idle.\n", style.SuccessPrefix, polecatName)
+	fmt.Printf("%s Polecat %s is now done.\n", style.SuccessPrefix, polecatName)
 	return nil
 }
--- a/internal/cmd/spawn.go
+++ b/internal/cmd/spawn.go
@@ -32,7 +32,6 @@ var polecatNames = []string{
 var (
 	spawnIssue   string
 	spawnMessage string
-	spawnCreate  bool
 	spawnNoStart bool
 )

@@ -42,14 +41,17 @@ var spawnCmd = &cobra.Command{
 	Short:   "Spawn a polecat with work assignment",
 	Long: `Spawn a polecat with a work assignment.

-Assigns an issue or task to a polecat and starts a session. If no polecat
-is specified, auto-selects an idle polecat in the rig.
+Creates a fresh polecat worktree, assigns an issue or task, and starts
+a session. Polecats are ephemeral - they exist only while working.
+
+If no polecat name is specified, generates a random name. If the specified
+name already exists as a non-working polecat, it will be replaced with
+a fresh worktree.

 Examples:
-  gt spawn gastown/Toast --issue gt-abc
-  gt spawn gastown --issue gt-def          # auto-select polecat
-  gt spawn gastown/Nux -m "Fix the tests"  # free-form task
-  gt spawn gastown/Capable --issue gt-xyz --create  # create if missing`,
+  gt spawn gastown --issue gt-abc          # auto-generate polecat name
+  gt spawn gastown/Toast --issue gt-def    # use specific name
+  gt spawn gastown/Nux -m "Fix the tests"  # free-form task`,
 	Args: cobra.ExactArgs(1),
 	RunE: runSpawn,
 }
@@ -57,7 +59,6 @@ Examples:
 func init() {
 	spawnCmd.Flags().StringVar(&spawnIssue, "issue", "", "Beads issue ID to assign")
 	spawnCmd.Flags().StringVarP(&spawnMessage, "message", "m", "", "Free-form task description")
-	spawnCmd.Flags().BoolVar(&spawnCreate, "create", false, "Create polecat if it doesn't exist")
 	spawnCmd.Flags().BoolVar(&spawnNoStart, "no-start", false, "Assign work but don't start session")

 	rootCmd.AddCommand(spawnCmd)
@@ -107,42 +108,41 @@ func runSpawn(cmd *cobra.Command, args []string) error {
 	polecatGit := git.NewGit(r.Path)
 	polecatMgr := polecat.NewManager(r, polecatGit)

-	// Auto-select polecat if not specified
+	// Ephemeral model: always create fresh polecat
+	// If no name specified, generate one
 	if polecatName == "" {
-		polecatName, err = selectIdlePolecat(polecatMgr, r)
-		if err != nil {
-			// If --create is set, generate a new polecat name instead of failing
-			if spawnCreate {
-				polecatName = generatePolecatName(polecatMgr)
-				fmt.Printf("Generated polecat name: %s\n", polecatName)
-			} else {
-				return fmt.Errorf("auto-select polecat: %w", err)
-			}
-		} else {
-			fmt.Printf("Auto-selected polecat: %s\n", polecatName)
-		}
+		polecatName = generatePolecatName(polecatMgr)
+		fmt.Printf("Generated polecat name: %s\n", polecatName)
 	}

-	// Check/create polecat
+	// Check if polecat already exists
 	pc, err := polecatMgr.Get(polecatName)
-	if err != nil {
-		if err == polecat.ErrPolecatNotFound {
-			if !spawnCreate {
-				return fmt.Errorf("polecat '%s' not found (use --create to create)", polecatName)
-			}
-			fmt.Printf("Creating polecat %s...\n", polecatName)
-			pc, err = polecatMgr.Add(polecatName)
-			if err != nil {
-				return fmt.Errorf("creating polecat: %w", err)
-			}
-		} else {
-			return fmt.Errorf("getting polecat: %w", err)
+	if err == nil {
+		// Polecat exists - check if working
+		if pc.State == polecat.StateWorking {
+			return fmt.Errorf("polecat '%s' is already working on %s", polecatName, pc.Issue)
 		}
+		// Existing polecat not working - remove and recreate fresh
+		fmt.Printf("Removing stale polecat %s for fresh worktree...\n", polecatName)
+		if err := polecatMgr.Remove(polecatName, true); err != nil {
+			return fmt.Errorf("removing stale polecat: %w", err)
+		}
+	} else if err != polecat.ErrPolecatNotFound {
+		return fmt.Errorf("checking polecat: %w", err)
 	}

-	// Check polecat state
-	if pc.State == polecat.StateWorking {
-		return fmt.Errorf("polecat '%s' is already working on %s", polecatName, pc.Issue)
+	// Create fresh polecat with new worktree from main
+	fmt.Printf("Creating fresh polecat %s...\n", polecatName)
+	pc, err = polecatMgr.Add(polecatName)
+	if err != nil {
+		return fmt.Errorf("creating polecat: %w", err)
+	}
+
+	// Initialize beads in the new worktree
+	fmt.Printf("Initializing beads in worktree...\n")
+	if err := initBeadsInWorktree(pc.ClonePath); err != nil {
+		// Non-fatal - beads might already be initialized
+		fmt.Printf("  %s\n", style.Dim.Render(fmt.Sprintf("(beads init: %v)", err)))
 	}

 	// Get issue details if specified
@@ -251,42 +251,23 @@ func generatePolecatName(mgr *polecat.Manager) string {
 	}
 }

-// selectIdlePolecat finds an idle polecat in the rig.
-func selectIdlePolecat(mgr *polecat.Manager, r *rig.Rig) (string, error) {
-	polecats, err := mgr.List()
-	if err != nil {
-		return "", err
+// initBeadsInWorktree initializes beads in a new polecat worktree.
+func initBeadsInWorktree(worktreePath string) error {
+	cmd := exec.Command("bd", "init")
+	cmd.Dir = worktreePath
+
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+
+	if err := cmd.Run(); err != nil {
+		errMsg := strings.TrimSpace(stderr.String())
+		if errMsg != "" {
+			return fmt.Errorf("%s", errMsg)
+		}
+		return err
 	}

-	// Prefer idle polecats
-	for _, pc := range polecats {
-		if pc.State == polecat.StateIdle {
-			return pc.Name, nil
-		}
-	}
-
-	// Accept active polecats without current work
-	for _, pc := range polecats {
-		if pc.State == polecat.StateActive && pc.Issue == "" {
-			return pc.Name, nil
-		}
-	}
-
-	// Check rig's polecat list for any we haven't loaded yet
-	for _, name := range r.Polecats {
-		found := false
-		for _, pc := range polecats {
-			if pc.Name == name {
-				found = true
-				break
-			}
-		}
-		if !found {
-			return name, nil
-		}
-	}
-
-	return "", fmt.Errorf("no available polecats in rig '%s'", r.Name)
+	return nil
 }

 // fetchBeadsIssue gets issue details from beads CLI.