Detect and clean stale POLECAT_DONE messages (#913)

* fix(witness): detect and ignore stale POLECAT_DONE messages

Add timestamp validation to prevent witness from nuking newly spawned
polecat sessions when processing stale POLECAT_DONE messages from
previous sessions.

- Add isStalePolecatDone() to compare message timestamp vs session created time
- If message timestamp < session created time, message is stale and ignored
- Add unit tests for timestamp parsing and stale detection logic

Fixes #909

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

* feat(mail): add --stale flag to gt mail archive

Add ability to archive stale messages (sent before current session started).
This prevents old messages from cycling forever in patrol inbox.

Changes:
- Add --stale and --dry-run flags to gt mail archive
- Move stale detection helpers to internal/session/stale.go for reuse
- Add ParseAddress to parse mail addresses into AgentIdentity
- Add SessionCreatedAt to get tmux session start time

Usage:
  gt mail archive --stale           # Archive all stale messages
  gt mail archive --stale --dry-run # Preview what would be archived

Co-Authored-By: GPT-5.2 Codex <noreply@openai.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: GPT-5.2 Codex <noreply@openai.com>

internal/session/identity.go

@@ -25,6 +25,59 @@ type AgentIdentity struct {
 	Name string // crew/polecat name (empty for mayor/deacon/witness/refinery)
 }
 
+// ParseAddress parses a mail-style address into an AgentIdentity.
+func ParseAddress(address string) (*AgentIdentity, error) {
+	address = strings.TrimSpace(address)
+	if address == "" {
+		return nil, fmt.Errorf("empty address")
+	}
+
+	if address == "mayor" || address == "mayor/" {
+		return &AgentIdentity{Role: RoleMayor}, nil
+	}
+	if address == "deacon" || address == "deacon/" {
+		return &AgentIdentity{Role: RoleDeacon}, nil
+	}
+	if address == "overseer" {
+		return nil, fmt.Errorf("overseer has no session")
+	}
+
+	address = strings.TrimSuffix(address, "/")
+	parts := strings.Split(address, "/")
+	if len(parts) < 2 {
+		return nil, fmt.Errorf("invalid address %q", address)
+	}
+
+	rig := parts[0]
+	switch len(parts) {
+	case 2:
+		name := parts[1]
+		switch name {
+		case "witness":
+			return &AgentIdentity{Role: RoleWitness, Rig: rig}, nil
+		case "refinery":
+			return &AgentIdentity{Role: RoleRefinery, Rig: rig}, nil
+		case "crew", "polecats":
+			return nil, fmt.Errorf("invalid address %q", address)
+		default:
+			return &AgentIdentity{Role: RolePolecat, Rig: rig, Name: name}, nil
+		}
+	case 3:
+		role := parts[1]
+		name := parts[2]
+		switch role {
+		case "crew":
+			return &AgentIdentity{Role: RoleCrew, Rig: rig, Name: name}, nil
+		case "polecats":
+			return &AgentIdentity{Role: RolePolecat, Rig: rig, Name: name}, nil
+		default:
+			return nil, fmt.Errorf("invalid address %q", address)
+		}
+	default:
+		return nil, fmt.Errorf("invalid address %q", address)
+	}
+}
+
 // ParseSessionName parses a tmux session name into an AgentIdentity.
 //
 // Session name formats:

internal/session/identity_test.go

@@ -250,3 +250,71 @@ func TestParseSessionName_RoundTrip(t *testing.T) {
 		})
 	}
 }
+
+func TestParseAddress(t *testing.T) {
+	tests := []struct {
+		name    string
+		address string
+		want    AgentIdentity
+		wantErr bool
+	}{
+		{
+			name:    "mayor",
+			address: "mayor/",
+			want:    AgentIdentity{Role: RoleMayor},
+		},
+		{
+			name:    "deacon",
+			address: "deacon",
+			want:    AgentIdentity{Role: RoleDeacon},
+		},
+		{
+			name:    "witness",
+			address: "gastown/witness",
+			want:    AgentIdentity{Role: RoleWitness, Rig: "gastown"},
+		},
+		{
+			name:    "refinery",
+			address: "rig-a/refinery",
+			want:    AgentIdentity{Role: RoleRefinery, Rig: "rig-a"},
+		},
+		{
+			name:    "crew",
+			address: "gastown/crew/max",
+			want:    AgentIdentity{Role: RoleCrew, Rig: "gastown", Name: "max"},
+		},
+		{
+			name:    "polecat explicit",
+			address: "gastown/polecats/nux",
+			want:    AgentIdentity{Role: RolePolecat, Rig: "gastown", Name: "nux"},
+		},
+		{
+			name:    "polecat canonical",
+			address: "gastown/nux",
+			want:    AgentIdentity{Role: RolePolecat, Rig: "gastown", Name: "nux"},
+		},
+		{
+			name:    "invalid",
+			address: "gastown/crew",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ParseAddress(tt.address)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatalf("expected error")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("ParseAddress(%q) error = %v", tt.address, err)
+			}
+			if *got != tt.want {
+				t.Fatalf("ParseAddress(%q) = %#v, want %#v", tt.address, *got, tt.want)
+			}
+		})
+	}
+}

internal/session/stale.go

@@ -0,0 +1,46 @@
+package session
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/steveyegge/gastown/internal/tmux"
+)
+
+// SessionCreatedAt returns the time a tmux session was created.
+func SessionCreatedAt(sessionName string) (time.Time, error) {
+	t := tmux.NewTmux()
+	info, err := t.GetSessionInfo(sessionName)
+	if err != nil {
+		return time.Time{}, err
+	}
+
+	return ParseTmuxSessionCreated(info.Created)
+}
+
+// ParseTmuxSessionCreated parses the tmux session created timestamp.
+func ParseTmuxSessionCreated(created string) (time.Time, error) {
+	created = strings.TrimSpace(created)
+	if created == "" {
+		return time.Time{}, fmt.Errorf("empty session created time")
+	}
+	return time.ParseInLocation("2006-01-02 15:04:05", created, time.Local)
+}
+
+// StaleReasonForTimes compares message time to session creation and returns staleness info.
+func StaleReasonForTimes(messageTime, sessionCreated time.Time) (bool, string) {
+	if messageTime.IsZero() || sessionCreated.IsZero() {
+		return false, ""
+	}
+
+	if messageTime.Before(sessionCreated) {
+		reason := fmt.Sprintf("message=%s session_started=%s",
+			messageTime.Format(time.RFC3339),
+			sessionCreated.Format(time.RFC3339),
+		)
+		return true, reason
+	}
+
+	return false, ""
+}

internal/session/stale_test.go

@@ -0,0 +1,60 @@
+package session
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestParseTmuxSessionCreated(t *testing.T) {
+	input := "2026-01-24 01:02:03"
+	expected, err := time.ParseInLocation("2006-01-02 15:04:05", input, time.Local)
+	if err != nil {
+		t.Fatalf("parse expected: %v", err)
+	}
+
+	parsed, err := ParseTmuxSessionCreated(input)
+	if err != nil {
+		t.Fatalf("ParseTmuxSessionCreated: %v", err)
+	}
+	if !parsed.Equal(expected) {
+		t.Fatalf("parsed time mismatch: got %v want %v", parsed, expected)
+	}
+}
+
+func TestStaleReasonForTimes(t *testing.T) {
+	now := time.Date(2026, 1, 24, 2, 0, 0, 0, time.UTC)
+	newer := now.Add(2 * time.Minute)
+	older := now.Add(-2 * time.Minute)
+
+	t.Run("message before session", func(t *testing.T) {
+		stale, reason := StaleReasonForTimes(older, newer)
+		if !stale {
+			t.Fatalf("expected stale")
+		}
+		if !strings.Contains(reason, "message=") || !strings.Contains(reason, "session_started=") {
+			t.Fatalf("expected reason details, got %q", reason)
+		}
+	})
+
+	t.Run("message after session", func(t *testing.T) {
+		stale, reason := StaleReasonForTimes(newer, older)
+		if stale || reason != "" {
+			t.Fatalf("expected not stale, got %v %q", stale, reason)
+		}
+	})
+
+	t.Run("zero message time", func(t *testing.T) {
+		stale, reason := StaleReasonForTimes(time.Time{}, now)
+		if stale || reason != "" {
+			t.Fatalf("expected not stale for zero message time, got %v %q", stale, reason)
+		}
+	})
+
+	t.Run("zero session time", func(t *testing.T) {
+		stale, reason := StaleReasonForTimes(now, time.Time{})
+		if stale || reason != "" {
+			t.Fatalf("expected not stale for zero session time, got %v %q", stale, reason)
+		}
+	})
+}