feat(connection): Add extended address parser (gt-f9x.10)

Implement address parsing for cross-machine operations:

Format: [machine:]rig[/polecat]

Examples:
- gastown/rictus -> local, gastown rig, rictus polecat
- vm:gastown/rictus -> vm machine, gastown rig, rictus
- gastown/ -> broadcast to gastown rig

Address struct with:
- ParseAddress() parser with validation
- String() canonical form
- IsLocal(), IsBroadcast() predicates
- Equal() comparison (normalizes local machine)
- Validate() against MachineRegistry
- RigPath() for rig/polecat without machine prefix

Includes comprehensive test coverage.

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

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

internal/connection/address.go

@@ -0,0 +1,138 @@
+package connection
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Address represents a parsed agent or rig address.
+// Format: [machine:]rig[/polecat]
+//
+// Examples:
+//   - "gastown/rictus"        -> local machine, gastown rig, rictus polecat
+//   - "vm:gastown/rictus"     -> vm machine, gastown rig, rictus polecat
+//   - "gastown/"              -> local machine, gastown rig, broadcast
+//   - "vm:gastown/"           -> vm machine, gastown rig, broadcast
+type Address struct {
+	Machine string // Machine name (empty = local)
+	Rig     string // Rig name (required)
+	Polecat string // Polecat name (empty = broadcast to rig)
+}
+
+// ParseAddress parses an address string into its components.
+// Valid formats:
+//   - rig/polecat
+//   - rig/
+//   - machine:rig/polecat
+//   - machine:rig/
+func ParseAddress(s string) (*Address, error) {
+	if s == "" {
+		return nil, fmt.Errorf("empty address")
+	}
+
+	addr := &Address{}
+
+	// Check for machine prefix (machine:)
+	if idx := strings.Index(s, ":"); idx >= 0 {
+		addr.Machine = s[:idx]
+		s = s[idx+1:]
+		if addr.Machine == "" {
+			return nil, fmt.Errorf("empty machine name before ':'")
+		}
+	}
+
+	// Parse rig/polecat
+	parts := strings.SplitN(s, "/", 2)
+	if len(parts) < 1 || parts[0] == "" {
+		return nil, fmt.Errorf("missing rig name in address")
+	}
+
+	addr.Rig = parts[0]
+
+	if len(parts) == 2 {
+		addr.Polecat = parts[1] // May be empty for broadcast
+	}
+
+	return addr, nil
+}
+
+// String returns the address in canonical form.
+func (a *Address) String() string {
+	var sb strings.Builder
+
+	if a.Machine != "" {
+		sb.WriteString(a.Machine)
+		sb.WriteString(":")
+	}
+
+	sb.WriteString(a.Rig)
+	sb.WriteString("/")
+
+	if a.Polecat != "" {
+		sb.WriteString(a.Polecat)
+	}
+
+	return sb.String()
+}
+
+// IsLocal returns true if the address targets the local machine.
+func (a *Address) IsLocal() bool {
+	return a.Machine == "" || a.Machine == "local"
+}
+
+// IsBroadcast returns true if the address targets a rig (no specific polecat).
+func (a *Address) IsBroadcast() bool {
+	return a.Polecat == ""
+}
+
+// RigPath returns the rig/polecat portion without machine prefix.
+func (a *Address) RigPath() string {
+	if a.Polecat != "" {
+		return a.Rig + "/" + a.Polecat
+	}
+	return a.Rig + "/"
+}
+
+// Validate checks if the address is valid against the registry.
+// Returns nil if valid, otherwise an error describing the issue.
+func (a *Address) Validate(registry *MachineRegistry) error {
+	// Check machine exists (if specified)
+	if a.Machine != "" && a.Machine != "local" {
+		if _, err := registry.Get(a.Machine); err != nil {
+			return fmt.Errorf("unknown machine: %s", a.Machine)
+		}
+	}
+
+	// Rig validation would require connection to target machine
+	// to check if rig exists - defer to caller for now
+
+	return nil
+}
+
+// Equal returns true if two addresses are equivalent.
+func (a *Address) Equal(other *Address) bool {
+	if other == nil {
+		return false
+	}
+
+	// Normalize local machine comparisons
+	m1, m2 := a.Machine, other.Machine
+	if m1 == "" || m1 == "local" {
+		m1 = "local"
+	}
+	if m2 == "" || m2 == "local" {
+		m2 = "local"
+	}
+
+	return m1 == m2 && a.Rig == other.Rig && a.Polecat == other.Polecat
+}
+
+// MustParseAddress parses an address and panics on error.
+// Only use for known-good addresses (e.g., constants).
+func MustParseAddress(s string) *Address {
+	addr, err := ParseAddress(s)
+	if err != nil {
+		panic(fmt.Sprintf("invalid address %q: %v", s, err))
+	}
+	return addr
+}

internal/connection/address_test.go

@@ -0,0 +1,192 @@
+package connection
+
+import (
+	"testing"
+)
+
+func TestParseAddress(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    *Address
+		wantErr bool
+	}{
+		{
+			name:  "rig/polecat",
+			input: "gastown/rictus",
+			want:  &Address{Rig: "gastown", Polecat: "rictus"},
+		},
+		{
+			name:  "rig/ broadcast",
+			input: "gastown/",
+			want:  &Address{Rig: "gastown"},
+		},
+		{
+			name:  "machine:rig/polecat",
+			input: "vm:gastown/rictus",
+			want:  &Address{Machine: "vm", Rig: "gastown", Polecat: "rictus"},
+		},
+		{
+			name:  "machine:rig/ broadcast",
+			input: "vm:gastown/",
+			want:  &Address{Machine: "vm", Rig: "gastown"},
+		},
+		{
+			name:  "rig only (no slash)",
+			input: "gastown",
+			want:  &Address{Rig: "gastown"},
+		},
+		{
+			name:    "empty string",
+			input:   "",
+			wantErr: true,
+		},
+		{
+			name:    "empty machine",
+			input:   ":gastown/rictus",
+			wantErr: true,
+		},
+		{
+			name:    "empty rig",
+			input:   "vm:/rictus",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ParseAddress(tt.input)
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("ParseAddress(%q) expected error, got nil", tt.input)
+				}
+				return
+			}
+			if err != nil {
+				t.Errorf("ParseAddress(%q) unexpected error: %v", tt.input, err)
+				return
+			}
+			if got.Machine != tt.want.Machine {
+				t.Errorf("Machine = %q, want %q", got.Machine, tt.want.Machine)
+			}
+			if got.Rig != tt.want.Rig {
+				t.Errorf("Rig = %q, want %q", got.Rig, tt.want.Rig)
+			}
+			if got.Polecat != tt.want.Polecat {
+				t.Errorf("Polecat = %q, want %q", got.Polecat, tt.want.Polecat)
+			}
+		})
+	}
+}
+
+func TestAddressString(t *testing.T) {
+	tests := []struct {
+		addr *Address
+		want string
+	}{
+		{
+			addr: &Address{Rig: "gastown", Polecat: "rictus"},
+			want: "gastown/rictus",
+		},
+		{
+			addr: &Address{Rig: "gastown"},
+			want: "gastown/",
+		},
+		{
+			addr: &Address{Machine: "vm", Rig: "gastown", Polecat: "rictus"},
+			want: "vm:gastown/rictus",
+		},
+		{
+			addr: &Address{Machine: "vm", Rig: "gastown"},
+			want: "vm:gastown/",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.want, func(t *testing.T) {
+			got := tt.addr.String()
+			if got != tt.want {
+				t.Errorf("String() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestAddressIsLocal(t *testing.T) {
+	tests := []struct {
+		addr *Address
+		want bool
+	}{
+		{&Address{Rig: "gastown"}, true},
+		{&Address{Machine: "", Rig: "gastown"}, true},
+		{&Address{Machine: "local", Rig: "gastown"}, true},
+		{&Address{Machine: "vm", Rig: "gastown"}, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.addr.String(), func(t *testing.T) {
+			if got := tt.addr.IsLocal(); got != tt.want {
+				t.Errorf("IsLocal() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestAddressIsBroadcast(t *testing.T) {
+	tests := []struct {
+		addr *Address
+		want bool
+	}{
+		{&Address{Rig: "gastown"}, true},
+		{&Address{Rig: "gastown", Polecat: ""}, true},
+		{&Address{Rig: "gastown", Polecat: "rictus"}, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.addr.String(), func(t *testing.T) {
+			if got := tt.addr.IsBroadcast(); got != tt.want {
+				t.Errorf("IsBroadcast() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestAddressEqual(t *testing.T) {
+	tests := []struct {
+		a, b *Address
+		want bool
+	}{
+		{
+			&Address{Rig: "gastown", Polecat: "rictus"},
+			&Address{Rig: "gastown", Polecat: "rictus"},
+			true,
+		},
+		{
+			&Address{Machine: "", Rig: "gastown"},
+			&Address{Machine: "local", Rig: "gastown"},
+			true,
+		},
+		{
+			&Address{Rig: "gastown", Polecat: "rictus"},
+			&Address{Rig: "gastown", Polecat: "nux"},
+			false,
+		},
+		{
+			&Address{Rig: "gastown"},
+			nil,
+			false,
+		},
+	}
+
+	for _, tt := range tests {
+		name := "equal"
+		if !tt.want {
+			name = "not equal"
+		}
+		t.Run(name, func(t *testing.T) {
+			if got := tt.a.Equal(tt.b); got != tt.want {
+				t.Errorf("Equal() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}