session: sanitize imported runtime names

Author: julianknutsen

cmd/gc/pool.go

@@ -399,8 +399,7 @@ func discoverPoolInstances(agentName, agentDir string, sp0 scaleParams, a *confi
 			if templatePrefix != "" && strings.HasPrefix(qnSanitized, templatePrefix) {
 				qnSanitized = qnSanitized[len(templatePrefix):]
 			}
-			// Unsanitize: "--" → "/"
-			qn := strings.ReplaceAll(qnSanitized, "--", "/")
+			qn := agent.UnsanitizeQualifiedNameFromSession(qnSanitized)
 			names = append(names, qn)
 		}
 	}

cmd/gc/pool_session_name.go

@@ -4,6 +4,7 @@ import (
 	"path"
 	"strings"
 
+	"github.com/gastownhall/gascity/internal/agent"
 	"github.com/gastownhall/gascity/internal/beads"
 	"github.com/gastownhall/gascity/internal/config"
 )
@@ -13,9 +14,7 @@ import (
 // Named sessions with an alias use the alias instead.
 func PoolSessionName(template, beadID string) string {
 	base := path.Base(template)
-	// Sanitize: replace "/" with "--" for tmux compatibility.
-	base = strings.ReplaceAll(base, "/", "--")
-	return base + "-" + beadID
+	return agent.SanitizeQualifiedNameForSession(base) + "-" + beadID
 }
 
 // GCSweepSessionBeads closes open session beads that have no remaining

cmd/gc/pool_session_name_test.go

@@ -17,6 +17,8 @@ func TestPoolSessionName(t *testing.T) {
 		{"claude", "mc-abc", "claude-mc-abc"},
 		{"myrig/codex", "mc-123", "codex-mc-123"},
 		{"control-dispatcher", "mc-wfc", "control-dispatcher-mc-wfc"},
+		{"gs.polecat", "mc-dot", "gs__polecat-mc-dot"},
+		{"myrig/gs.polecat", "mc-rigdot", "gs__polecat-mc-rigdot"},
 	}
 	for _, tt := range tests {
 		got := PoolSessionName(tt.template, tt.beadID)

internal/agent/session_name.go

@@ -8,28 +8,50 @@ import (
 	"text/template"
 )
 
+var sessionNameQualifiedReplacer = strings.NewReplacer(
+	"/", "--",
+	".", "__",
+)
+
+var sessionNameQualifiedReverseReplacer = strings.NewReplacer(
+	"--", "/",
+	"__", ".",
+)
+
 // sessionData holds template variables for custom session naming.
 type sessionData struct {
 	City  string // workspace name
-	Agent string // tmux-safe qualified name (/ → --)
+	Agent string // tmux-safe qualified name (/ -> --, . -> __)
 	Dir   string // rig/dir component (empty for singletons)
 	Name  string // bare agent name
 }
 
+// SanitizeQualifiedNameForSession converts a qualified identity into the
+// deterministic tmux-safe form used by runtime session_name values.
+func SanitizeQualifiedNameForSession(agentName string) string {
+	return sessionNameQualifiedReplacer.Replace(agentName)
+}
+
+// UnsanitizeQualifiedNameFromSession best-effort decodes a tmux-safe runtime
+// session name fragment back to the corresponding qualified identity.
+func UnsanitizeQualifiedNameFromSession(name string) string {
+	return sessionNameQualifiedReverseReplacer.Replace(name)
+}
+
 // SessionNameFor returns the session name for a city agent.
 // This is the single source of truth for the naming convention.
 // sessionTemplate is a Go text/template string; empty means use the
 // default pattern "{agent}" (the sanitized agent name). With per-city
 // tmux socket isolation as the default, the city prefix is unnecessary.
 //
-// For rig-scoped agents (name contains "/"), the dir and name
-// components are joined with "--" to avoid tmux naming issues:
+// For qualified identities, structural separators are encoded to avoid tmux
+// naming issues while preserving slash-vs-dot distinction:
 //
 //	"mayor"               → "mayor"
 //	"hello-world/polecat" → "hello-world--polecat"
+//	"gastown.mayor"       → "gastown__mayor"
 func SessionNameFor(cityName, agentName, sessionTemplate string) string {
-	// Pre-sanitize: replace "/" with "--" for tmux safety.
-	sanitized := strings.ReplaceAll(agentName, "/", "--")
+	sanitized := SanitizeQualifiedNameForSession(agentName)
 
 	if sessionTemplate == "" {
 		// Default: just the sanitized agent name. Per-city tmux socket

internal/agent/session_name_test.go

@@ -0,0 +1,45 @@
+package agent
+
+import "testing"
+
+func TestSanitizeQualifiedNameForSession(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{name: "plain", input: "mayor", want: "mayor"},
+		{name: "rig scoped", input: "repo/polecat", want: "repo--polecat"},
+		{name: "imported city scoped", input: "wendy.wendy", want: "wendy__wendy"},
+		{name: "imported rig scoped", input: "repo/wendy.wendy", want: "repo--wendy__wendy"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := SanitizeQualifiedNameForSession(tt.input); got != tt.want {
+				t.Fatalf("SanitizeQualifiedNameForSession(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+			if got := SessionNameFor("city", tt.input, ""); got != tt.want {
+				t.Fatalf("SessionNameFor(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestUnsanitizeQualifiedNameFromSession(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{input: "mayor", want: "mayor"},
+		{input: "repo--polecat", want: "repo/polecat"},
+		{input: "wendy__wendy", want: "wendy.wendy"},
+		{input: "repo--wendy__wendy", want: "repo/wendy.wendy"},
+	}
+
+	for _, tt := range tests {
+		if got := UnsanitizeQualifiedNameFromSession(tt.input); got != tt.want {
+			t.Fatalf("UnsanitizeQualifiedNameFromSession(%q) = %q, want %q", tt.input, got, tt.want)
+		}
+	}
+}

internal/api/handler_agents.go

@@ -415,7 +415,7 @@ func discoverUnlimitedPool(a config.Agent, poolName, cityName, sessTmpl string,
 		if templatePrefix != "" && strings.HasPrefix(qnSanitized, templatePrefix) {
 			qnSanitized = qnSanitized[len(templatePrefix):]
 		}
-		qn := strings.ReplaceAll(qnSanitized, "--", "/")
+		qn := agent.UnsanitizeQualifiedNameFromSession(qnSanitized)
 		result = append(result, expandedAgent{
 			qualifiedName: qn,
 			rig:           a.Dir,

internal/api/handler_agents_test.go

@@ -125,6 +125,53 @@ func TestAgentListUnlimitedPoolDiscovery(t *testing.T) {
 	}
 }
 
+func TestAgentListUnlimitedImportedPoolDiscovery(t *testing.T) {
+	state := newFakeState(t)
+	state.cfg.Agents = []config.Agent{
+		{
+			Name:              "polecat",
+			Dir:               "myrig",
+			BindingName:       "gs",
+			MinActiveSessions: intPtr(0), MaxActiveSessions: intPtr(-1),
+		},
+	}
+	state.sp.Start(context.Background(), "myrig--gs__polecat-1", runtime.Config{}) //nolint:errcheck
+	state.sp.Start(context.Background(), "myrig--gs__polecat-2", runtime.Config{}) //nolint:errcheck
+	srv := New(state)
+
+	req := httptest.NewRequest("GET", "/v0/agents", nil)
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var resp struct {
+		Items []agentResponse `json:"items"`
+		Total int             `json:"total"`
+	}
+	if err := json.NewDecoder(rec.Body).Decode(&resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+
+	if resp.Total != 2 {
+		t.Fatalf("Total = %d, want 2", resp.Total)
+	}
+
+	for i, item := range resp.Items {
+		if item.Name != "myrig/gs.polecat-1" && item.Name != "myrig/gs.polecat-2" {
+			t.Errorf("Items[%d].Name = %q, want imported pool member name", i, item.Name)
+		}
+		if item.Pool != "myrig/gs.polecat" {
+			t.Errorf("Items[%d].Pool = %q, want %q", i, item.Pool, "myrig/gs.polecat")
+		}
+		if !item.Running {
+			t.Errorf("Items[%d].Running = false, want true", i)
+		}
+	}
+}
+
 func TestFindAgentUnlimitedPoolMember(t *testing.T) {
 	cfg := &config.City{
 		Agents: []config.Agent{

test/acceptance/import_named_sessions_regression_test.go

@@ -0,0 +1,113 @@
+//go:build acceptance_a
+
+package acceptance_test
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	helpers "github.com/gastownhall/gascity/test/acceptance/helpers"
+)
+
+type namedSessionListEntry struct {
+	Template    string `json:"Template"`
+	SessionName string `json:"SessionName"`
+}
+
+func TestImportedNamedSessionsUseSafeRuntimeNames(t *testing.T) {
+	c := helpers.NewCity(t, testEnv)
+	c.Init("claude")
+
+	rigDir := filepath.Join(c.Dir, "repo")
+	mustWriteTestFile(t, filepath.Join(c.Dir, "pack.toml"), `
+[pack]
+name = "import-regression"
+schema = 2
+
+[imports.gs]
+source = "./assets/sidecar"
+`)
+	mustWriteTestFile(t, filepath.Join(c.Dir, "city.toml"), `
+[workspace]
+name = "import-regression"
+start_command = "sleep 300"
+
+[[rigs]]
+name = "repo"
+path = "./repo"
+
+[rigs.imports.gs]
+source = "./assets/sidecar"
+`)
+	mustWriteTestFile(t, filepath.Join(c.Dir, "assets", "sidecar", "pack.toml"), `
+[pack]
+name = "sidecar"
+schema = 2
+
+[[named_session]]
+template = "captain"
+scope = "city"
+mode = "always"
+
+[[named_session]]
+template = "watcher"
+scope = "rig"
+mode = "always"
+`)
+	mustWriteTestFile(t, filepath.Join(c.Dir, "assets", "sidecar", "agents", "captain", "agent.toml"), "scope = \"city\"\n")
+	mustWriteTestFile(t, filepath.Join(c.Dir, "assets", "sidecar", "agents", "captain", "prompt.md"), "You are the imported captain.\n")
+	mustWriteTestFile(t, filepath.Join(c.Dir, "assets", "sidecar", "agents", "watcher", "agent.toml"), "scope = \"rig\"\n")
+	mustWriteTestFile(t, filepath.Join(c.Dir, "assets", "sidecar", "agents", "watcher", "prompt.md"), "You are the imported watcher.\n")
+	if err := os.MkdirAll(rigDir, 0o755); err != nil {
+		t.Fatalf("creating rig dir: %v", err)
+	}
+
+	if out, err := c.GC("unregister", c.Dir); err != nil {
+		t.Fatalf("gc unregister: %v\n%s", err, out)
+	}
+
+	c.StartForeground()
+
+	var sessions []namedSessionListEntry
+	deadline := time.Now().Add(20 * time.Second)
+	for time.Now().Before(deadline) {
+		out, err := c.GC("session", "list", "--json")
+		if err == nil {
+			if unmarshalErr := json.Unmarshal([]byte(out), &sessions); unmarshalErr == nil {
+				if hasNamedSession(sessions, "gs.captain", "gs__captain") &&
+					hasNamedSession(sessions, "repo/gs.watcher", "repo--gs__watcher") {
+					return
+				}
+			}
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+
+	out, err := c.GC("session", "list", "--json")
+	if err != nil {
+		t.Fatalf("gc session list --json: %v\n%s", err, out)
+	}
+	t.Fatalf("imported named sessions never reached safe runtime names:\n%s", out)
+}
+
+func hasNamedSession(sessions []namedSessionListEntry, template, sessionName string) bool {
+	for _, s := range sessions {
+		if s.Template == template && s.SessionName == sessionName {
+			return true
+		}
+	}
+	return false
+}
+
+func mustWriteTestFile(t *testing.T, path, contents string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("creating %s: %v", filepath.Dir(path), err)
+	}
+	if err := os.WriteFile(path, []byte(contents), 0o644); err != nil {
+		t.Fatalf("writing %s: %v", path, err)
+	}
+}