Document intentional error suppressions with comments (gt-zn9m)

All 156 instances of _ = error suppression in non-test code now have
explanatory comments documenting why the error is intentionally ignored.

Categories of intentional suppressions:
- non-fatal: session works without these - tmux environment setup
- non-fatal: theming failure does not affect operation - visual styling
- best-effort cleanup - defer cleanup on failure paths
- best-effort notification - mail/notifications that should not block
- best-effort interrupt - graceful shutdown attempts
- crypto/rand.Read only fails on broken system - random ID generation
- output errors non-actionable - fmt.Fprint to io.Writer

This addresses the silent failure and debugging concerns raised in the
issue by making the intentionality explicit in the code.

Generated with Claude Code https://claude.com/claude-code

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

internal/daemon/daemon.go

@@ -61,7 +61,7 @@ func (d *Daemon) Run() error {
 	if err := os.WriteFile(d.config.PidFile, []byte(strconv.Itoa(os.Getpid())), 0644); err != nil {
 		return fmt.Errorf("writing PID file: %w", err)
 	}
-	defer func() { _ = os.Remove(d.config.PidFile) }()
+	defer func() { _ = os.Remove(d.config.PidFile) }() // best-effort cleanup
 
 	// Update state
 	state := &State{
@@ -219,7 +219,7 @@ func (d *Daemon) ensureDeaconRunning() {
 		return
 	}
 
-	// Set environment
+	// Set environment (non-fatal: session works without these)
 	_ = d.tmux.SetEnvironment(DeaconSessionName, "GT_ROLE", "deacon")
 	_ = d.tmux.SetEnvironment(DeaconSessionName, "BD_ACTOR", "deacon")
 
@@ -361,7 +361,7 @@ func IsRunning(townRoot string) (bool, int, error) {
 	// On Unix, FindProcess always succeeds. Send signal 0 to check if alive.
 	err = process.Signal(syscall.Signal(0))
 	if err != nil {
-		// Process not running, clean up stale PID file
+		// Process not running, clean up stale PID file (best-effort cleanup)
 		_ = os.Remove(pidFile)
 		return false, 0, nil
 	}
@@ -394,11 +394,11 @@ func StopDaemon(townRoot string) error {
 
 	// Check if still running
 	if err := process.Signal(syscall.Signal(0)); err == nil {
-		// Still running, force kill
+		// Still running, force kill (best-effort)
 		_ = process.Signal(syscall.SIGKILL)
 	}
 
-	// Clean up PID file
+	// Clean up PID file (best-effort cleanup)
 	pidFile := filepath.Join(townRoot, "daemon", "daemon.pid")
 	_ = os.Remove(pidFile)
 

internal/daemon/lifecycle.go

@@ -260,13 +260,13 @@ func (d *Daemon) restartSession(sessionName, identity string) error {
 		return fmt.Errorf("creating session: %w", err)
 	}
 
-	// Set environment
+	// Set environment (non-fatal: session works without these)
 	_ = d.tmux.SetEnvironment(sessionName, "GT_ROLE", identity)
 	// BD_ACTOR uses slashes instead of dashes for path-like identity
 	bdActor := identityToBDActor(identity)
 	_ = d.tmux.SetEnvironment(sessionName, "BD_ACTOR", bdActor)
 
-	// Apply theme
+	// Apply theme (non-fatal: theming failure doesn't affect operation)
 	if identity == "mayor" {
 		theme := tmux.MayorTheme()
 		_ = d.tmux.ConfigureGasTownSession(sessionName, theme, "", "Mayor", "coordinator")

internal/daemon/notification.go

@@ -165,7 +165,7 @@ func (m *NotificationManager) MarkSessionActive(session string) error {
 			ns.Consumed = true
 			ns.ConsumedAt = time.Now()
 			if data, err := json.Marshal(&ns); err == nil {
-				_ = os.WriteFile(path, data, 0644)
+				_ = os.WriteFile(path, data, 0644) // non-fatal: state file update
 			}
 		}
 	}
@@ -198,7 +198,7 @@ func (m *NotificationManager) ClearStaleSlots() error {
 		}
 
 		if time.Since(info.ModTime()) > m.maxAge {
-			_ = os.Remove(path)
+			_ = os.Remove(path) // best-effort cleanup
 		}
 	}