feat(prime): add --state, --dry-run, --explain flags with mutual exclusivity validation

Add three new flags to gt prime command:
- --state: Output role state as JSON and exit early (for scripting)
- --dry-run: Skip side effects (persistence, locks, events)
- --explain: Show verbose role detection reasoning

The --state flag is mutually exclusive with all other flags and errors
if combined. The other flags (--dry-run, --explain, --hook) can be
combined freely.

Also fixes missing filepath import in beads.go.

Closes: bd-t8ven

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

internal/cmd/prime.go

@@ -61,6 +61,21 @@ Role detection:
 
 This command is typically used in shell prompts or agent initialization.
 
+FLAGS:
+
+STATE MODE (--state):
+  Output detected role information as JSON and exit early.
+  Useful for scripting and programmatic role detection.
+  This flag is standalone - cannot be combined with other flags.
+
+DRY-RUN MODE (--dry-run):
+  Show what context would be output without side effects.
+  Skips session ID persistence, lock acquisition, and event emission.
+
+EXPLAIN MODE (--explain):
+  Provide verbose explanations for role detection decisions.
+  Shows why certain context is being included.
+
 HOOK MODE (--hook):
   When called as an LLM runtime hook, use --hook to enable session ID handling.
   This reads session metadata from stdin and persists it for the session.
@@ -71,7 +86,11 @@ HOOK MODE (--hook):
   Claude Code sends JSON on stdin:
     {"session_id": "uuid", "transcript_path": "/path", "source": "startup|resume"}
 
-  Other agents can set GT_SESSION_ID environment variable instead.`,
+  Other agents can set GT_SESSION_ID environment variable instead.
+
+FLAG COMBINATIONS:
+  --state is mutually exclusive with all other flags.
+  --dry-run, --explain, and --hook can be combined.`,
 	RunE: runPrime,
 }
 
@@ -102,6 +121,11 @@ func runPrime(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("finding workspace: %w", err)
 	}
 
+	// Validate mutually exclusive flags
+	if primeState && (primeHookMode || primeDryRun || primeExplain) {
+		return fmt.Errorf("--state cannot be combined with other flags (--hook, --dry-run, --explain)")
+	}
+
 	// "Discover, Don't Track" principle:
 	// - If we're in a workspace, proceed - the workspace's existence IS the enable signal
 	// - If we're NOT in a workspace, check the global enabled state
@@ -123,10 +147,12 @@ func runPrime(cmd *cobra.Command, args []string) error {
 			if cwd != townRoot {
 				persistSessionID(cwd, sessionID)
 			}
+			// Set environment for this process (affects event emission below)
+			_ = os.Setenv("GT_SESSION_ID", sessionID)
+			_ = os.Setenv("CLAUDE_SESSION_ID", sessionID) // Legacy compatibility
+		} else if primeExplain {
+			fmt.Println("[dry-run] Would persist session ID:", sessionID)
 		}
-		// Set environment for this process (affects event emission below)
-		_ = os.Setenv("GT_SESSION_ID", sessionID)
-		_ = os.Setenv("CLAUDE_SESSION_ID", sessionID) // Legacy compatibility
 		// Output session beacon
 		explain(true, "Session beacon: hook mode enabled, session ID from stdin")
 		fmt.Printf("[session:%s]\n", sessionID)
@@ -149,6 +175,24 @@ func runPrime(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("detecting role: %w", err)
 	}
 
+	// --state mode: output JSON and exit early
+	if primeState {
+		return outputStateJSON(roleInfo, cwd, townRoot)
+	}
+
+	// --explain mode: show role detection reasoning
+	if primeExplain {
+		fmt.Printf("[explain] Role detection source: %s\n", roleInfo.Source)
+		fmt.Printf("[explain] Detected role: %s\n", roleInfo.Role)
+		if roleInfo.Rig != "" {
+			fmt.Printf("[explain] Rig: %s\n", roleInfo.Rig)
+		}
+		if roleInfo.Polecat != "" {
+			fmt.Printf("[explain] Polecat/Crew: %s\n", roleInfo.Polecat)
+		}
+		fmt.Println()
+	}
+
 	// Warn prominently if there's a role/cwd mismatch
 	if roleInfo.Mismatch {
 		fmt.Printf("\n%s\n", style.Bold.Render("⚠️  ROLE/LOCATION MISMATCH"))
@@ -184,12 +228,18 @@ func runPrime(cmd *cobra.Command, args []string) error {
 		if err := acquireIdentityLock(ctx); err != nil {
 			return err
 		}
+	} else if primeExplain {
+		fmt.Println("[dry-run] Would acquire identity lock for:", getAgentIdentity(ctx))
 	}
 
 	// Ensure beads redirect exists for worktree-based roles
 	// Skip if there's a role/location mismatch to avoid creating bad redirects
-	if !roleInfo.Mismatch && !primeDryRun {
-		ensureBeadsRedirect(ctx)
+	if !roleInfo.Mismatch {
+		if !primeDryRun {
+			ensureBeadsRedirect(ctx)
+		} else if primeExplain {
+			fmt.Println("[dry-run] Would ensure beads redirect")
+		}
 	}
 
 	// NOTE: reportAgentState("running") removed (gt-zecmc)
@@ -199,6 +249,8 @@ func runPrime(cmd *cobra.Command, args []string) error {
 	// Emit session_start event for seance discovery
 	if !primeDryRun {
 		emitSessionEvent(ctx)
+	} else if primeExplain {
+		fmt.Println("[dry-run] Would emit session_start event")
 	}
 
 	// Output session metadata for seance discovery
@@ -335,6 +387,47 @@ func detectRole(cwd, townRoot string) RoleInfo {
 	return ctx
 }
 
+// PrimeState represents the JSON output for --state mode.
+type PrimeState struct {
+	Role     Role   `json:"role"`
+	Source   string `json:"source"`
+	Rig      string `json:"rig,omitempty"`
+	Polecat  string `json:"polecat,omitempty"`
+	TownRoot string `json:"town_root"`
+	WorkDir  string `json:"work_dir"`
+	Mismatch bool   `json:"mismatch,omitempty"`
+	CwdRole  Role   `json:"cwd_role,omitempty"`
+	Identity string `json:"identity,omitempty"`
+}
+
+// outputStateJSON outputs role state as JSON and returns (for --state flag).
+func outputStateJSON(roleInfo RoleInfo, cwd, townRoot string) error {
+	state := PrimeState{
+		Role:     roleInfo.Role,
+		Source:   roleInfo.Source,
+		Rig:      roleInfo.Rig,
+		Polecat:  roleInfo.Polecat,
+		TownRoot: townRoot,
+		WorkDir:  cwd,
+		Mismatch: roleInfo.Mismatch,
+		CwdRole:  roleInfo.CwdRole,
+	}
+
+	// Compute identity string
+	ctx := RoleContext{
+		Role:     roleInfo.Role,
+		Rig:      roleInfo.Rig,
+		Polecat:  roleInfo.Polecat,
+		TownRoot: townRoot,
+		WorkDir:  cwd,
+	}
+	state.Identity = getAgentIdentity(ctx)
+
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	return enc.Encode(state)
+}
+
 func outputPrimeContext(ctx RoleContext) error {
 	// Try to use templates first
 	tmpl, err := templates.New()