Add files using upload-large-folder tool

internal/config/agent_id_test.go

@@ -0,0 +1,29 @@
+package config
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestConfig_AgentIDs(t *testing.T) {
+	cfg := &Config{
+		Options: &Options{
+			DisabledTools: []string{},
+		},
+	}
+	cfg.SetupAgents()
+
+	t.Run("Coder agent should have correct ID", func(t *testing.T) {
+		coderAgent, ok := cfg.Agents[AgentCoder]
+		require.True(t, ok)
+		assert.Equal(t, AgentCoder, coderAgent.ID, "Coder agent ID should be '%s'", AgentCoder)
+	})
+
+	t.Run("Task agent should have correct ID", func(t *testing.T) {
+		taskAgent, ok := cfg.Agents[AgentTask]
+		require.True(t, ok)
+		assert.Equal(t, AgentTask, taskAgent.ID, "Task agent ID should be '%s'", AgentTask)
+	})
+}

internal/config/atomicwrite.go

@@ -0,0 +1,63 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// atomicWriteFile writes data to a file atomically by writing to a unique
+// temporary file in the same directory and renaming it into place. This
+// prevents concurrent readers from observing a partially-written file.
+func atomicWriteFile(path string, data []byte, perm os.FileMode) error {
+	path = filepath.Clean(path)
+	dir := filepath.Dir(path)
+	f, err := os.CreateTemp(dir, filepath.Base(path)+".*.tmp")
+	if err != nil {
+		return err
+	}
+	tmp := f.Name()
+	if _, err := f.Write(data); err != nil {
+		f.Close()
+		os.Remove(tmp)
+		return err
+	}
+	if err := f.Chmod(perm); err != nil {
+		f.Close()
+		os.Remove(tmp)
+		return err
+	}
+	if err := f.Close(); err != nil {
+		os.Remove(tmp)
+		return err
+	}
+	if err := renameFile(tmp, path); err != nil {
+		os.Remove(tmp)
+		return err
+	}
+	return nil
+}
+
+// renameRetryBudget bounds how long renameFile keeps retrying transient
+// failures before giving up and returning the error.
+const renameRetryBudget = 2 * time.Second
+
+// renameFile renames tmp over path. On Windows the rename fails with
+// ERROR_ACCESS_DENIED or ERROR_SHARING_VIOLATION while another process
+// (antivirus, search indexer) or a concurrent reader briefly holds a
+// handle on the destination, so transient failures are retried with
+// backoff. On other platforms isTransientRenameError is always false
+// and this is a plain os.Rename.
+func renameFile(tmp, path string) error {
+	var slept time.Duration
+	delay := time.Millisecond
+	for {
+		err := os.Rename(tmp, path)
+		if err == nil || !isTransientRenameError(err) || slept >= renameRetryBudget {
+			return err
+		}
+		time.Sleep(delay)
+		slept += delay
+		delay = min(delay*2, 50*time.Millisecond)
+	}
+}

internal/config/atomicwrite_test.go

@@ -0,0 +1,43 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestAtomicWriteFile(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "test.json")
+
+	require.NoError(t, atomicWriteFile(path, []byte(`{"key":"value"}`), 0o600))
+
+	data, err := os.ReadFile(path)
+	require.NoError(t, err)
+	require.Equal(t, `{"key":"value"}`, string(data))
+
+	// No temp files should linger.
+	entries, err := os.ReadDir(dir)
+	require.NoError(t, err)
+	require.Len(t, entries, 1)
+	require.Equal(t, "test.json", entries[0].Name())
+}
+
+func TestAtomicWriteFile_PermissionsApplied(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("Windows does not support Unix file permissions")
+	}
+	t.Parallel()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "test.json")
+
+	require.NoError(t, atomicWriteFile(path, []byte(`{}`), 0o600))
+
+	info, err := os.Stat(path)
+	require.NoError(t, err)
+	require.Equal(t, os.FileMode(0o600), info.Mode().Perm())
+}

internal/config/atomicwrite_unix.go

@@ -0,0 +1,7 @@
+//go:build !windows
+
+package config
+
+// isTransientRenameError reports whether err is a rename failure that
+// can resolve on its own. Only Windows has such failures.
+func isTransientRenameError(error) bool { return false }

internal/config/atomicwrite_windows_test.go

@@ -0,0 +1,45 @@
+//go:build windows
+
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/windows"
+)
+
+// Regression test for the windows-latest CI flake where
+// TestConfigStore_SetConfigFields_concurrentInProcess failed with
+// "rename ...crush.json.<rand>.tmp ...crush.json: Access is denied":
+// renaming over a destination while another handle is open on it
+// without sharing must be retried until the handle closes, not
+// surfaced as an error.
+func TestAtomicWriteFile_RetriesWhileDestinationHandleOpen(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "test.json")
+	require.NoError(t, atomicWriteFile(path, []byte(`{"v":1}`), 0o600))
+
+	// Hold the destination open with no sharing flags so the rename
+	// fails with ERROR_ACCESS_DENIED/ERROR_SHARING_VIOLATION until the
+	// handle closes, mimicking an antivirus scan or exclusive reader.
+	p, err := windows.UTF16PtrFromString(path)
+	require.NoError(t, err)
+	h, err := windows.CreateFile(p, windows.GENERIC_READ, 0, nil,
+		windows.OPEN_EXISTING, windows.FILE_ATTRIBUTE_NORMAL, 0)
+	require.NoError(t, err)
+	go func() {
+		time.Sleep(200 * time.Millisecond)
+		windows.CloseHandle(h)
+	}()
+
+	require.NoError(t, atomicWriteFile(path, []byte(`{"v":2}`), 0o600))
+
+	data, err := os.ReadFile(path)
+	require.NoError(t, err)
+	require.JSONEq(t, `{"v":2}`, string(data))
+}

internal/config/attribution_migration_test.go

@@ -0,0 +1,93 @@
+package config
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestAttributionMigration(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name             string
+		configJSON       string
+		expectedTrailer  TrailerStyle
+		expectedGenerate bool
+	}{
+		{
+			name: "old setting co_authored_by=true migrates to co-authored-by",
+			configJSON: `{
+				"options": {
+					"attribution": {
+						"co_authored_by": true,
+						"generated_with": false
+					}
+				}
+			}`,
+			expectedTrailer:  TrailerStyleCoAuthoredBy,
+			expectedGenerate: false,
+		},
+		{
+			name: "old setting co_authored_by=false migrates to none",
+			configJSON: `{
+				"options": {
+					"attribution": {
+						"co_authored_by": false,
+						"generated_with": true
+					}
+				}
+			}`,
+			expectedTrailer:  TrailerStyleNone,
+			expectedGenerate: true,
+		},
+		{
+			name: "new setting takes precedence over old setting",
+			configJSON: `{
+				"options": {
+					"attribution": {
+						"trailer_style": "assisted-by",
+						"co_authored_by": true,
+						"generated_with": false
+					}
+				}
+			}`,
+			expectedTrailer:  TrailerStyleAssistedBy,
+			expectedGenerate: false,
+		},
+		{
+			name: "default when neither setting present",
+			configJSON: `{
+				"options": {
+					"attribution": {
+						"generated_with": true
+					}
+				}
+			}`,
+			expectedTrailer:  TrailerStyleAssistedBy,
+			expectedGenerate: true,
+		},
+		{
+			name: "default when attribution is null",
+			configJSON: `{
+				"options": {}
+			}`,
+			expectedTrailer:  TrailerStyleAssistedBy,
+			expectedGenerate: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			cfg, err := loadFromBytes([][]byte{[]byte(tt.configJSON)})
+			require.NoError(t, err)
+
+			cfg.setDefaults(t.TempDir(), "")
+
+			require.Equal(t, tt.expectedTrailer, cfg.Options.Attribution.TrailerStyle)
+			require.Equal(t, tt.expectedGenerate, cfg.Options.Attribution.GeneratedWith)
+		})
+	}
+}

internal/config/config_unix.go

@@ -0,0 +1,7 @@
+//go:build !windows
+
+package config
+
+// systemConfigPath is the system-wide configuration file path. It is
+// loaded at the lowest priority so user and project configs override it.
+const systemConfigPath = "/etc/crush/crush.json"

internal/config/copilot.go

@@ -0,0 +1 @@
+package config

internal/config/docker_mcp.go

@@ -0,0 +1,141 @@
+package config
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"sync"
+	"time"
+)
+
+var dockerMCPVersionRunner = func(ctx context.Context) error {
+	cmd := exec.CommandContext(ctx, "docker", "mcp", "version")
+	return cmd.Run()
+}
+
+const dockerMCPAvailabilityTTL = 10 * time.Second
+
+var dockerMCPAvailabilityCache struct {
+	mu        sync.Mutex
+	available bool
+	checkedAt time.Time
+	known     bool
+}
+
+// DockerMCPName is the name of the Docker MCP configuration.
+const DockerMCPName = "docker"
+
+// IsDockerMCPAvailable checks if Docker MCP is available by running
+// 'docker mcp version'.
+func IsDockerMCPAvailable() bool {
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	err := dockerMCPVersionRunner(ctx)
+	return err == nil
+}
+
+// DockerMCPAvailabilityCached returns the cached Docker MCP availability and
+// whether the cached value is still fresh.
+func DockerMCPAvailabilityCached() (available bool, known bool) {
+	dockerMCPAvailabilityCache.mu.Lock()
+	defer dockerMCPAvailabilityCache.mu.Unlock()
+
+	if !dockerMCPAvailabilityCache.known {
+		return false, false
+	}
+	if time.Since(dockerMCPAvailabilityCache.checkedAt) > dockerMCPAvailabilityTTL {
+		return dockerMCPAvailabilityCache.available, false
+	}
+	return dockerMCPAvailabilityCache.available, true
+}
+
+// RefreshDockerMCPAvailability refreshes and caches Docker MCP availability.
+func RefreshDockerMCPAvailability() bool {
+	available := IsDockerMCPAvailable()
+	dockerMCPAvailabilityCache.mu.Lock()
+	dockerMCPAvailabilityCache.available = available
+	dockerMCPAvailabilityCache.checkedAt = time.Now()
+	dockerMCPAvailabilityCache.known = true
+	dockerMCPAvailabilityCache.mu.Unlock()
+	return available
+}
+
+// IsDockerMCPEnabled checks if Docker MCP is already configured.
+func (c *Config) IsDockerMCPEnabled() bool {
+	if c.MCP == nil {
+		return false
+	}
+	_, exists := c.MCP[DockerMCPName]
+	return exists
+}
+
+// DockerMCPConfig returns the default Docker MCP stdio configuration.
+func DockerMCPConfig() MCPConfig {
+	return MCPConfig{
+		Type:     MCPStdio,
+		Command:  "docker",
+		Args:     []string{"mcp", "gateway", "run"},
+		Disabled: false,
+	}
+}
+
+// PrepareDockerMCPConfig validates Docker MCP availability and stages the
+// Docker MCP configuration in memory.
+func (s *ConfigStore) PrepareDockerMCPConfig() (MCPConfig, error) {
+	if !IsDockerMCPAvailable() {
+		return MCPConfig{}, fmt.Errorf("docker mcp is not available, please ensure docker is installed and 'docker mcp version' succeeds")
+	}
+
+	mcpConfig := DockerMCPConfig()
+	// In-memory only; persistence happens in PersistDockerMCPConfig.
+	s.mutateInMemory(func(c *Config) {
+		if c.MCP == nil {
+			c.MCP = make(map[string]MCPConfig)
+		}
+		c.MCP[DockerMCPName] = mcpConfig
+	})
+	return mcpConfig, nil
+}
+
+// PersistDockerMCPConfig persists a previously prepared Docker MCP
+// configuration to the global config file.
+func (s *ConfigStore) PersistDockerMCPConfig(mcpConfig MCPConfig) error {
+	if err := s.SetConfigField(ScopeGlobal, "mcp."+DockerMCPName, mcpConfig); err != nil {
+		return fmt.Errorf("failed to persist docker mcp configuration: %w", err)
+	}
+	return nil
+}
+
+// EnableDockerMCP adds Docker MCP configuration and persists it.
+func (s *ConfigStore) EnableDockerMCP() error {
+	mcpConfig, err := s.PrepareDockerMCPConfig()
+	if err != nil {
+		return err
+	}
+	if err := s.PersistDockerMCPConfig(mcpConfig); err != nil {
+		return err
+	}
+	return nil
+}
+
+// DisableDockerMCP removes Docker MCP configuration and persists the change.
+func (s *ConfigStore) DisableDockerMCP() error {
+	return s.update(ScopeGlobal, func(c *Config) map[string]any {
+		if c.MCP == nil {
+			return nil
+		}
+		delete(c.MCP, DockerMCPName)
+		return map[string]any{"mcp": c.MCP}
+	})
+}
+
+// RemoveDockerMCPInMemory removes the Docker MCP entry from the in-memory
+// config via copy-on-write, without persisting to disk. It rolls back a
+// staged PrepareDockerMCPConfig when starting or persisting the server
+// fails, so callers must not mutate Config().MCP directly.
+func (s *ConfigStore) RemoveDockerMCPInMemory() {
+	s.mutateInMemory(func(c *Config) {
+		delete(c.MCP, DockerMCPName)
+	})
+}

internal/config/docker_mcp_test.go

@@ -0,0 +1,195 @@
+package config
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/charmbracelet/crush/internal/env"
+	"github.com/stretchr/testify/require"
+)
+
+var errDockerUnavailable = errors.New("docker unavailable")
+
+func setDockerMCPVersionRunner(t *testing.T, runner func(context.Context) error) {
+	t.Helper()
+	orig := dockerMCPVersionRunner
+	dockerMCPVersionRunner = runner
+	t.Cleanup(func() {
+		dockerMCPVersionRunner = orig
+	})
+}
+
+func TestIsDockerMCPEnabled(t *testing.T) {
+	t.Parallel()
+
+	t.Run("returns false when MCP is nil", func(t *testing.T) {
+		t.Parallel()
+		cfg := &Config{
+			MCP: nil,
+		}
+		require.False(t, cfg.IsDockerMCPEnabled())
+	})
+
+	t.Run("returns false when docker mcp not configured", func(t *testing.T) {
+		t.Parallel()
+		cfg := &Config{
+			MCP: make(map[string]MCPConfig),
+		}
+		require.False(t, cfg.IsDockerMCPEnabled())
+	})
+
+	t.Run("returns true when docker mcp is configured", func(t *testing.T) {
+		t.Parallel()
+		cfg := &Config{
+			MCP: map[string]MCPConfig{
+				DockerMCPName: {
+					Type:    MCPStdio,
+					Command: "docker",
+				},
+			},
+		}
+		require.True(t, cfg.IsDockerMCPEnabled())
+	})
+}
+
+func TestEnableDockerMCP(t *testing.T) {
+	t.Run("adds docker mcp to config", func(t *testing.T) {
+		setDockerMCPVersionRunner(t, func(context.Context) error { return nil })
+
+		// Create a temporary directory for config.
+		tmpDir := t.TempDir()
+		configPath := filepath.Join(tmpDir, "crush.json")
+
+		cfg := &Config{
+			MCP: make(map[string]MCPConfig),
+		}
+		store := &ConfigStore{
+			config:         cfg,
+			globalDataPath: configPath,
+			resolver:       NewShellVariableResolver(env.New()),
+		}
+
+		err := store.EnableDockerMCP()
+		require.NoError(t, err)
+
+		// Check in-memory config via the store (copy-on-write publishes
+		// a new Config; the captured cfg pointer stays unchanged).
+		require.True(t, store.Config().IsDockerMCPEnabled())
+		mcpConfig, exists := store.Config().MCP[DockerMCPName]
+		require.True(t, exists)
+		require.Equal(t, MCPStdio, mcpConfig.Type)
+		require.Equal(t, "docker", mcpConfig.Command)
+		require.Equal(t, []string{"mcp", "gateway", "run"}, mcpConfig.Args)
+		require.False(t, mcpConfig.Disabled)
+
+		// Check persisted config.
+		data, err := os.ReadFile(configPath)
+		require.NoError(t, err)
+		require.Contains(t, string(data), "docker")
+		require.Contains(t, string(data), "gateway")
+	})
+
+	t.Run("fails when docker mcp not available", func(t *testing.T) {
+		setDockerMCPVersionRunner(t, func(context.Context) error { return errDockerUnavailable })
+
+		// Create a temporary directory for config.
+		tmpDir := t.TempDir()
+		configPath := filepath.Join(tmpDir, "crush.json")
+
+		cfg := &Config{
+			MCP: make(map[string]MCPConfig),
+		}
+		store := &ConfigStore{
+			config:         cfg,
+			globalDataPath: configPath,
+			resolver:       NewShellVariableResolver(env.New()),
+		}
+
+		err := store.EnableDockerMCP()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "docker mcp is not available")
+	})
+}
+
+func TestDisableDockerMCP(t *testing.T) {
+	t.Parallel()
+
+	t.Run("removes docker mcp from config", func(t *testing.T) {
+		t.Parallel()
+
+		// Create a temporary directory for config.
+		tmpDir := t.TempDir()
+		configPath := filepath.Join(tmpDir, "crush.json")
+
+		cfg := &Config{
+			MCP: map[string]MCPConfig{
+				DockerMCPName: {
+					Type:     MCPStdio,
+					Command:  "docker",
+					Args:     []string{"mcp", "gateway", "run"},
+					Disabled: false,
+				},
+			},
+		}
+		store := &ConfigStore{
+			config:         cfg,
+			globalDataPath: configPath,
+			resolver:       NewShellVariableResolver(env.New()),
+		}
+
+		// Verify it's enabled first.
+		require.True(t, cfg.IsDockerMCPEnabled())
+
+		err := store.DisableDockerMCP()
+		require.NoError(t, err)
+
+		// Check in-memory config via the store (copy-on-write publishes a
+		// new Config; the original cfg pointer is intentionally unchanged).
+		require.False(t, store.Config().IsDockerMCPEnabled())
+		_, exists := store.Config().MCP[DockerMCPName]
+		require.False(t, exists)
+	})
+
+	t.Run("does nothing when MCP is nil", func(t *testing.T) {
+		t.Parallel()
+
+		cfg := &Config{
+			MCP: nil,
+		}
+		store := &ConfigStore{
+			config:         cfg,
+			globalDataPath: filepath.Join(t.TempDir(), "crush.json"),
+			resolver:       NewShellVariableResolver(env.New()),
+		}
+
+		err := store.DisableDockerMCP()
+		require.NoError(t, err)
+	})
+}
+
+func TestEnableDockerMCPWithRealDockerWhenAvailable(t *testing.T) {
+	t.Parallel()
+
+	if !IsDockerMCPAvailable() {
+		t.Skip("docker mcp not available on this machine")
+	}
+
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "crush.json")
+
+	cfg := &Config{
+		MCP: make(map[string]MCPConfig),
+	}
+	store := &ConfigStore{
+		config:         cfg,
+		globalDataPath: configPath,
+		resolver:       NewShellVariableResolver(env.New()),
+	}
+
+	err := store.EnableDockerMCP()
+	require.NoError(t, err)
+	require.True(t, store.Config().IsDockerMCPEnabled())
+}

internal/config/init.go

@@ -0,0 +1,127 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+
+	"github.com/charmbracelet/crush/internal/fsext"
+)
+
+const (
+	InitFlagFilename = "init"
+)
+
+type ProjectInitFlag struct {
+	Initialized bool `json:"initialized"`
+}
+
+func Init(workingDir, dataDir string, debug bool) (*ConfigStore, error) {
+	store, err := Load(workingDir, dataDir, debug)
+	if err != nil {
+		return nil, err
+	}
+	return store, nil
+}
+
+func ProjectNeedsInitialization(store *ConfigStore) (bool, error) {
+	if store == nil {
+		return false, fmt.Errorf("config not loaded")
+	}
+
+	cfg := store.Config()
+	flagFilePath := filepath.Join(cfg.Options.DataDirectory, InitFlagFilename)
+
+	_, err := os.Stat(flagFilePath)
+	if err == nil {
+		return false, nil
+	}
+
+	if !os.IsNotExist(err) {
+		return false, fmt.Errorf("failed to check init flag file: %w", err)
+	}
+
+	someContextFileExists, err := contextPathsExist(store.WorkingDir())
+	if err != nil {
+		return false, fmt.Errorf("failed to check for context files: %w", err)
+	}
+	if someContextFileExists {
+		return false, nil
+	}
+
+	// If the working directory has no non-ignored files, skip initialization step
+	empty, err := dirHasNoVisibleFiles(store.WorkingDir())
+	if err != nil {
+		return false, fmt.Errorf("failed to check if directory is empty: %w", err)
+	}
+	if empty {
+		return false, nil
+	}
+
+	return true, nil
+}
+
+func contextPathsExist(dir string) (bool, error) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return false, err
+	}
+
+	// Create a slice of lowercase filenames for lookup with slices.Contains
+	var files []string
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			files = append(files, strings.ToLower(entry.Name()))
+		}
+	}
+
+	// Check if any of the default context paths exist in the directory
+	for _, path := range defaultContextPaths {
+		// Extract just the filename from the path
+		_, filename := filepath.Split(path)
+		filename = strings.ToLower(filename)
+
+		if slices.Contains(files, filename) {
+			return true, nil
+		}
+	}
+
+	return false, nil
+}
+
+// dirHasNoVisibleFiles returns true if the directory has no files/dirs after applying ignore rules.
+func dirHasNoVisibleFiles(dir string) (bool, error) {
+	files, _, err := fsext.ListDirectory(dir, nil, 1, 1)
+	if err != nil {
+		return false, err
+	}
+	return len(files) == 0, nil
+}
+
+func MarkProjectInitialized(store *ConfigStore) error {
+	if store == nil {
+		return fmt.Errorf("config not loaded")
+	}
+	flagFilePath := filepath.Join(store.Config().Options.DataDirectory, InitFlagFilename)
+
+	file, err := os.Create(flagFilePath)
+	if err != nil {
+		return fmt.Errorf("failed to create init flag file: %w", err)
+	}
+	defer file.Close()
+
+	return nil
+}
+
+func HasInitialDataConfig(store *ConfigStore) bool {
+	if store == nil {
+		return false
+	}
+	cfgPath := GlobalConfigData()
+	if _, err := os.Stat(cfgPath); err != nil {
+		return false
+	}
+	return store.Config().IsConfigured()
+}

internal/config/load.go

@@ -0,0 +1,1454 @@
+package config
+
+import (
+	"cmp"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"maps"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"slices"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"github.com/charmbracelet/crush/internal/agent/hyper"
+	"github.com/charmbracelet/crush/internal/csync"
+	"github.com/charmbracelet/crush/internal/discover"
+	"github.com/charmbracelet/crush/internal/env"
+	"github.com/charmbracelet/crush/internal/filepathext"
+	"github.com/charmbracelet/crush/internal/fsext"
+	"github.com/charmbracelet/crush/internal/home"
+	"github.com/charmbracelet/crush/internal/shellconfig"
+	powernapConfig "github.com/charmbracelet/x/powernap/pkg/config"
+	"github.com/qjebbs/go-jsons"
+	"github.com/tidwall/gjson"
+	"github.com/tidwall/sjson"
+)
+
+const defaultCatwalkURL = "https://catwalk.charm.land"
+
+// Load loads the configuration from the default paths and returns a
+// ConfigStore that owns both the pure-data Config and all runtime state.
+func Load(workingDir, dataDir string, debug bool) (*ConfigStore, error) {
+	// Migrate deprecated disable_notifications before loading config.
+	migrateDisableNotifications()
+
+	configPaths := lookupConfigs(workingDir)
+
+	cfg, loadedPaths, err := loadFromConfigPaths(context.Background(), configPaths)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config from paths %v: %w", configPaths, err)
+	}
+
+	cfg.setDefaults(workingDir, dataDir)
+
+	store := &ConfigStore{
+		config:         cfg,
+		workingDir:     workingDir,
+		globalDataPath: GlobalConfigData(),
+		workspacePath:  filepath.Join(cfg.Options.DataDirectory, fmt.Sprintf("%s.json", appName)),
+		loadedPaths:    loadedPaths,
+	}
+
+	if debug {
+		cfg.Options.Debug = true
+	}
+
+	// Load workspace config last so it has highest priority.
+	if wsData, err := os.ReadFile(store.workspacePath); err == nil && len(wsData) > 0 {
+		if !json.Valid(wsData) {
+			return nil, fmt.Errorf("invalid JSON in config file %s", store.workspacePath)
+		}
+		merged, mergeErr := loadFromBytes(append([][]byte{mustMarshalConfig(cfg)}, wsData))
+		if mergeErr == nil {
+			// Preserve defaults that setDefaults already applied.
+			dataDir := cfg.Options.DataDirectory
+			*cfg = *merged
+			cfg.setDefaults(workingDir, dataDir)
+			store.config = cfg
+			store.loadedPaths = append(store.loadedPaths, store.workspacePath)
+		}
+	}
+
+	// Validate hooks after all config merging is complete so workspace
+	// hooks also get their matcher regexes compiled.
+	if err := cfg.ValidateHooks(); err != nil {
+		return nil, fmt.Errorf("invalid hook configuration: %w", err)
+	}
+
+	if !isInsideWorktree() {
+		const depth = 2
+		const items = 100
+		slog.Warn("No git repository detected in working directory, will limit file walk operations", "depth", depth, "items", items)
+		assignIfNil(&cfg.Tools.Ls.MaxDepth, depth)
+		assignIfNil(&cfg.Tools.Ls.MaxItems, items)
+		assignIfNil(&cfg.Options.TUI.Completions.MaxDepth, depth)
+		assignIfNil(&cfg.Options.TUI.Completions.MaxItems, items)
+	}
+
+	if isAppleTerminal() {
+		slog.Warn("Detected Apple Terminal, enabling transparent mode")
+		assignIfNil(&cfg.Options.TUI.Transparent, true)
+	}
+
+	// Load known providers, this loads the config from catwalk. A failed
+	// refresh still yields the cached or embedded catalog, so only an empty
+	// list is fatal: starting up without providers is worse than starting
+	// up with slightly stale ones. Pass a Hyper token refresher so the
+	// catalog fetch can retry on 401.
+	providers, err := Providers(cfg, func(ctx context.Context) error {
+		return store.RefreshOAuthToken(ctx, ScopeGlobal, "hyper")
+	})
+	if err != nil {
+		if len(providers) == 0 {
+			return nil, err
+		}
+		slog.Warn("Continuing with the previously known providers", "error", err)
+	}
+	store.knownProviders = providers
+
+	env := env.New()
+	// Configure providers
+	valueResolver := NewShellVariableResolver(env)
+	store.resolver = valueResolver
+
+	// Hold writeMu during initial load to prevent configureProviders
+	// from triggering auto-reload via RemoveConfigField.
+	store.writeMu.Lock()
+	defer store.writeMu.Unlock()
+
+	// Apply top-level env vars before configuring providers so variables
+	// like AWS_PROFILE are visible to the AWS SDK credential chain.
+	cfg.applyEnv(valueResolver)
+
+	if err := cfg.configureProviders(context.Background(), store, env, valueResolver, store.knownProviders); err != nil {
+		return nil, fmt.Errorf("failed to configure providers: %w", err)
+	}
+
+	if !cfg.IsConfigured() {
+		slog.Warn("No providers configured")
+		return store, nil
+	}
+
+	resolved, err := resolveSelectedModels(cfg, store.knownProviders)
+	if err != nil {
+		return nil, fmt.Errorf("failed to configure selected models: %w", err)
+	}
+	cfg.Models[SelectedModelTypeLarge] = resolved.Large
+	cfg.Models[SelectedModelTypeSmall] = resolved.Small
+
+	// Persist any fallback corrections while we still hold writeMu.
+	if resolved.LargeFallback {
+		if err := store.updateLocked(ScopeGlobal, func(c *Config) map[string]any {
+			return store.updatePreferredModelFields(c, SelectedModelTypeLarge, resolved.Large)
+		}); err != nil {
+			return nil, fmt.Errorf("failed to update preferred large model: %w", err)
+		}
+	}
+	if resolved.SmallFallback {
+		if err := store.updateLocked(ScopeGlobal, func(c *Config) map[string]any {
+			return store.updatePreferredModelFields(c, SelectedModelTypeSmall, resolved.Small)
+		}); err != nil {
+			return nil, fmt.Errorf("failed to update preferred small model: %w", err)
+		}
+	}
+	store.SetupAgents()
+
+	// Capture initial staleness snapshot
+	// Capture initial staleness snapshot. Track every discovered config path,
+	// not just the ones that loaded, so a config file created after startup
+	// (e.g. a crushrc added mid-session) is detected as a change.
+	store.captureStalenessSnapshot(append(slices.Clone(configPaths), loadedPaths...))
+
+	return store, nil
+}
+
+// mustMarshalConfig marshals the config to JSON bytes, returning empty JSON on
+// error.
+func mustMarshalConfig(cfg *Config) []byte {
+	data, err := json.Marshal(cfg)
+	if err != nil {
+		return []byte("{}")
+	}
+	return data
+}
+
+func PushPopCrushEnv() func() {
+	var found []string
+	for _, ev := range os.Environ() {
+		if strings.HasPrefix(ev, "CRUSH_") {
+			pair := strings.SplitN(ev, "=", 2)
+			if len(pair) != 2 {
+				continue
+			}
+			found = append(found, strings.TrimPrefix(pair[0], "CRUSH_"))
+		}
+	}
+	backups := make(map[string]string)
+	for _, ev := range found {
+		backups[ev] = os.Getenv(ev)
+	}
+
+	for _, ev := range found {
+		os.Setenv(ev, os.Getenv("CRUSH_"+ev))
+	}
+
+	restore := func() {
+		for k, v := range backups {
+			os.Setenv(k, v)
+		}
+	}
+	return restore
+}
+
+func (c *Config) configureProviders(ctx context.Context, store *ConfigStore, env env.Env, resolver VariableResolver, knownProviders []catwalk.Provider) error {
+	knownProviderNames := make(map[string]bool)
+	restore := PushPopCrushEnv()
+	defer restore()
+
+	// When disable_default_providers is enabled, skip all default/embedded
+	// providers entirely. Users must fully specify any providers they want.
+	// We skip to the custom provider validation loop which handles all
+	// user-configured providers uniformly.
+	if c.Options.DisableDefaultProviders {
+		knownProviders = nil
+	}
+
+	for _, p := range knownProviders {
+		knownProviderNames[string(p.ID)] = true
+		config, configExists := c.Providers.Get(string(p.ID))
+		// if the user configured a known provider we need to allow it to override a couple of parameters
+		if configExists {
+			if config.BaseURL != "" {
+				p.APIEndpoint = config.BaseURL
+			}
+			if config.APIKey != "" {
+				p.APIKey = config.APIKey
+			}
+			if len(config.Models) > 0 {
+				models := []catwalk.Model{}
+				seen := make(map[string]bool)
+
+				for _, model := range config.Models {
+					if seen[model.ID] {
+						continue
+					}
+					seen[model.ID] = true
+					if model.Name == "" {
+						model.Name = model.ID
+					}
+					models = append(models, model)
+				}
+				for _, model := range p.Models {
+					if seen[model.ID] {
+						continue
+					}
+					seen[model.ID] = true
+					if model.Name == "" {
+						model.Name = model.ID
+					}
+					models = append(models, model)
+				}
+
+				p.Models = models
+			}
+		}
+
+		headers := map[string]string{}
+		if len(p.DefaultHeaders) > 0 {
+			maps.Copy(headers, p.DefaultHeaders)
+		}
+		if len(config.ExtraHeaders) > 0 {
+			maps.Copy(headers, config.ExtraHeaders)
+		}
+		// Provider headers use the same error contract as MCP headers:
+		// a failing $(...) aborts the provider load with a clear
+		// message, and a header that resolves to the empty string
+		// (unset bare $VAR under lenient nounset, $(echo), or literal
+		// "") is dropped from the outgoing request.
+		for k, v := range headers {
+			resolved, err := resolver.ResolveValue(v)
+			if err != nil {
+				return fmt.Errorf("resolving provider %s header %q: %w", p.ID, k, err)
+			}
+			if resolved == "" {
+				delete(headers, k)
+				continue
+			}
+			headers[k] = resolved
+		}
+		// Start from user config so all user fields survive without
+		// explicit copying. Overlay catwalk identity/endpoint fields
+		// (already merged with user overrides above).
+		prepared := config
+		prepared.ID = string(p.ID)
+		prepared.Name = p.Name
+		prepared.BaseURL = p.APIEndpoint
+		prepared.APIKey = p.APIKey
+		prepared.APIKeyTemplate = p.APIKey // Store original template for re-resolution
+		prepared.Type = p.Type
+		prepared.Models = p.Models
+		prepared.ExtraHeaders = headers
+		if prepared.ExtraParams == nil {
+			prepared.ExtraParams = make(map[string]string)
+		}
+
+		switch {
+		case p.ID == catwalk.InferenceProviderAnthropic && config.OAuthToken != nil:
+			// Claude Code subscription is not supported anymore. Remove to show onboarding.
+			// RemoveConfigField persists the deletion to disk. The in-memory
+			// state is kept consistent by the Providers.Del call below; any
+			// concurrent reload that races with this write will also see the
+			// removal because it re-reads from disk.
+			store.RemoveConfigField(ScopeGlobal, "providers.anthropic")
+			c.Providers.Del(string(p.ID))
+			continue
+		case p.ID == catwalk.InferenceProviderCopilot && config.OAuthToken != nil:
+			prepared.SetupGitHubCopilot()
+		}
+
+		switch p.ID {
+		// Handle specific providers that require additional configuration
+		case catwalk.InferenceProviderVertexAI:
+			var (
+				project  = env.Get("VERTEXAI_PROJECT")
+				location = env.Get("VERTEXAI_LOCATION")
+			)
+			if project == "" || location == "" {
+				if configExists {
+					slog.Warn("Skipping Vertex AI provider due to missing credentials")
+					c.Providers.Del(string(p.ID))
+				}
+				continue
+			}
+			prepared.ExtraParams["project"] = project
+			prepared.ExtraParams["location"] = location
+		case catwalk.InferenceProviderAzure:
+			endpoint, err := resolver.ResolveValue(p.APIEndpoint)
+			if err != nil || endpoint == "" {
+				if configExists {
+					slog.Warn("Skipping Azure provider due to missing API endpoint", "provider", p.ID, "error", err)
+					c.Providers.Del(string(p.ID))
+				}
+				continue
+			}
+			prepared.BaseURL = endpoint
+			prepared.ExtraParams["apiVersion"] = env.Get("AZURE_OPENAI_API_VERSION")
+		case catwalk.InferenceProviderBedrock, catwalk.InferenceProviderBedrockEurope:
+			if p.APIKey == "" && !hasAWSCredentials(env) {
+				if configExists {
+					slog.Warn("Skipping Bedrock provider due to missing AWS credentials")
+					c.Providers.Del(string(p.ID))
+				}
+				continue
+			}
+		case catwalk.InferenceProvider("hyper"):
+			if apiKey := env.Get("HYPER_API_KEY"); apiKey != "" {
+				prepared.APIKey = apiKey
+				prepared.APIKeyTemplate = apiKey
+			} else {
+				v, err := resolver.ResolveValue(p.APIKey)
+				if v == "" || err != nil {
+					if configExists {
+						slog.Warn("Skipping Hyper provider due to missing API key", "provider", p.ID)
+						c.Providers.Del(string(p.ID))
+					}
+					continue
+				}
+			}
+		default:
+			// An OAuth login is a credential too: providers signed in
+			// through OAuth (e.g. OpenAI with a ChatGPT account) are
+			// configured even when no API key is present.
+			if config.OAuthToken != nil {
+				break
+			}
+			// if the provider api or endpoint are missing we skip them
+			v, err := resolver.ResolveValue(p.APIKey)
+			if v == "" || err != nil {
+				if configExists {
+					slog.Warn("Skipping provider due to missing API key", "provider", p.ID)
+					c.Providers.Del(string(p.ID))
+				}
+				continue
+			}
+		}
+		c.Providers.Set(string(p.ID), prepared)
+	}
+
+	// Discover models concurrently for custom providers that need it.
+	// A provider needs discovery when discover_models is explicitly true,
+	// or when the models list is empty (auto-trigger, unless opted out).
+	type discoveryResult struct {
+		models []catwalk.Model
+		err    error
+	}
+
+	discoveryResults := make(map[string]discoveryResult)
+	var mu sync.Mutex
+	var wg sync.WaitGroup
+
+	discoverCtx, discoverCancel := context.WithTimeout(ctx, 3*time.Second)
+	for id, pc := range c.Providers.Seq2() {
+		if knownProviderNames[id] {
+			continue
+		}
+		if pc.Disable || pc.BaseURL == "" {
+			continue
+		}
+		wantsDiscovery := pc.AutoDiscoverModels != nil && *pc.AutoDiscoverModels
+		autoTrigger := len(pc.Models) == 0 && (pc.AutoDiscoverModels == nil || *pc.AutoDiscoverModels)
+		if !wantsDiscovery && !autoTrigger {
+			continue
+		}
+		providerID := cmp.Or(pc.ID, id)
+		cfg := discover.Config{
+			ID:             providerID,
+			BaseURL:        pc.BaseURL,
+			APIKey:         pc.APIKey,
+			ExtraHeaders:   pc.ExtraHeaders,
+			ExistingModels: pc.Models,
+		}
+		providerType := cmp.Or(pc.Type, catwalk.TypeOpenAICompat)
+		wg.Go(func() {
+			models, err := discover.DiscoverModels(discoverCtx, cfg, resolver)
+			if err == nil && len(models) > 0 {
+				if enricher := discover.GetEnricher(string(providerType)); enricher != nil {
+					models, _ = enricher.EnrichModels(discoverCtx, cfg, resolver, models)
+				}
+			}
+			mu.Lock()
+			discoveryResults[id] = discoveryResult{models: models, err: err}
+			mu.Unlock()
+		})
+	}
+	wg.Wait()
+	discoverCancel()
+
+	// Validate the custom providers.
+	for id, providerConfig := range c.Providers.Seq2() {
+		if knownProviderNames[id] {
+			continue
+		}
+
+		// Make sure the provider ID is set.
+		providerConfig.ID = id
+		providerConfig.Name = cmp.Or(providerConfig.Name, id) // Use ID as name if not set
+		// Default to OpenAI if not set.
+		providerConfig.Type = cmp.Or(providerConfig.Type, catwalk.TypeOpenAICompat)
+		if !slices.Contains(catwalk.KnownProviderTypes(), providerConfig.Type) &&
+			providerConfig.Type != hyper.Name &&
+			!discover.IsKnownCustomProvider(string(providerConfig.Type)) {
+			slog.Warn("Skipping custom provider due to unsupported provider type", "provider", id)
+			c.Providers.Del(id)
+			continue
+		}
+
+		if providerConfig.Disable {
+			slog.Debug("Skipping custom provider due to disable flag", "provider", id)
+			c.Providers.Del(id)
+			continue
+		}
+		apiKey, err := resolver.ResolveValue(providerConfig.APIKey)
+		if apiKey == "" || err != nil {
+			slog.Warn("Provider is missing API key, this might be OK for local providers", "provider", id)
+		}
+		baseURL, err := resolver.ResolveValue(providerConfig.BaseURL)
+		if baseURL == "" || err != nil {
+			slog.Warn("Skipping custom provider due to missing API endpoint", "provider", id, "error", err)
+			c.Providers.Del(id)
+			continue
+		}
+
+		// Apply discovery results if available.
+		if result, ok := discoveryResults[id]; ok {
+			if result.err != nil {
+				slog.Warn("Model discovery failed", "provider", id, "error", result.err)
+				if len(providerConfig.Models) == 0 {
+					slog.Warn("Skipping provider with no models after failed discovery", "provider", id)
+					c.Providers.Del(id)
+					continue
+				}
+			} else if len(result.models) > 0 {
+				providerConfig.Models = result.models
+				slog.Info("Discovered models for provider", "provider", id, "count", len(result.models))
+			}
+		}
+
+		if len(providerConfig.Models) == 0 {
+			slog.Warn("Skipping custom provider because the provider has no models", "provider", id)
+			c.Providers.Del(id)
+			continue
+		}
+
+		// Custom-provider headers share the MCP error contract; see
+		// the known-provider loop above.
+		for k, v := range providerConfig.ExtraHeaders {
+			resolved, err := resolver.ResolveValue(v)
+			if err != nil {
+				return fmt.Errorf("resolving provider %s header %q: %w", id, k, err)
+			}
+			if resolved == "" {
+				delete(providerConfig.ExtraHeaders, k)
+				continue
+			}
+			providerConfig.ExtraHeaders[k] = resolved
+		}
+
+		c.Providers.Set(id, providerConfig)
+	}
+
+	if c.Providers.Len() == 0 && c.Options.DisableDefaultProviders {
+		return fmt.Errorf("default providers are disabled and there are no custom providers are configured")
+	}
+
+	return nil
+}
+
+// applyEnv sets top-level env vars from the config. Keys are sorted for
+// deterministic ordering so that vars referencing other vars via the
+// value resolver produce consistent results.
+func (c *Config) applyEnv(resolver VariableResolver) {
+	keys := make([]string, 0, len(c.Env))
+	for k := range c.Env {
+		keys = append(keys, k)
+	}
+	slices.Sort(keys)
+	for _, k := range keys {
+		resolved, err := resolver.ResolveValue(c.Env[k])
+		if err != nil {
+			slog.Warn("Skipping env var due to resolution failure.", "key", k, "value", c.Env[k], "error", err)
+			continue
+		}
+		os.Setenv(k, resolved)
+	}
+}
+
+// NormalizeOptions allocates Options and Options.TUI and fills in the option
+// defaults the UI relies on, so readers can dereference them without guarding.
+// Configs loaded from disk get this via setDefaults; configs arriving over the
+// wire from a Crush server need the same treatment before the UI reads them.
+//
+// DiffMode is deliberately left alone: the permissions dialog reads its zero
+// value as "choose split or unified from the terminal width".
+func (c *Config) NormalizeOptions() {
+	if c.Options == nil {
+		c.Options = &Options{}
+	}
+	if c.Options.TUI == nil {
+		c.Options.TUI = &TUIOptions{}
+	}
+	if c.Options.TUI.Scrollbar == "" {
+		c.Options.TUI.Scrollbar = ScrollbarDefault
+	}
+	if c.Options.TUI.ExitBanner == "" {
+		c.Options.TUI.ExitBanner = ExitBannerDefault
+	}
+}
+
+func (c *Config) setDefaults(workingDir, dataDir string) {
+	c.NormalizeOptions()
+	if len(c.Options.GlobalContextPaths) == 0 {
+		crushConfigDir := filepath.Dir(GlobalConfig())
+		c.Options.GlobalContextPaths = []string{
+			filepath.Join(crushConfigDir, "CRUSH.md"),
+			filepath.Join(filepath.Dir(crushConfigDir), "AGENTS.md"),
+		}
+	}
+	slices.Sort(c.Options.GlobalContextPaths)
+	c.Options.GlobalContextPaths = slices.Compact(c.Options.GlobalContextPaths)
+
+	if dataDir != "" {
+		c.Options.DataDirectory = dataDir
+	} else if c.Options.DataDirectory == "" {
+		if path, ok := fsext.LookupClosestBounded(workingDir, projectBoundary(workingDir), defaultDataDirectory); ok {
+			c.Options.DataDirectory = path
+		} else {
+			c.Options.DataDirectory = filepath.Join(workingDir, defaultDataDirectory)
+		}
+	}
+	c.Options.DataDirectory = filepath.Clean(filepathext.SmartJoin(workingDir, c.Options.DataDirectory))
+	if c.Providers == nil {
+		c.Providers = csync.NewMap[string, ProviderConfig]()
+	}
+	if c.Models == nil {
+		c.Models = make(map[SelectedModelType]SelectedModel)
+	}
+	if c.RecentModels == nil {
+		c.RecentModels = make(map[SelectedModelType][]SelectedModel)
+	}
+	if c.MCP == nil {
+		c.MCP = make(map[string]MCPConfig)
+	}
+	// Drop orphaned OAuth token entries left behind when a user removes
+	// an MCP from crush.json. See MCPConfig.isOrphanedToken.
+	for name, m := range c.MCP {
+		if m.isOrphanedToken() {
+			delete(c.MCP, name)
+		}
+	}
+	if c.LSP == nil {
+		c.LSP = make(map[string]LSPConfig)
+	}
+
+	// Apply defaults to LSP configurations
+	c.applyLSPDefaults()
+
+	// Add the default context paths if they are not already present
+	c.Options.ContextPaths = append(slices.Clone(defaultContextPaths), c.Options.ContextPaths...)
+
+	slices.Sort(c.Options.ContextPaths)
+	c.Options.ContextPaths = slices.Compact(c.Options.ContextPaths)
+
+	// Add the default skills directories if not already present.
+	for _, dir := range GlobalSkillsDirs() {
+		if !slices.Contains(c.Options.SkillsPaths, dir) {
+			c.Options.SkillsPaths = append(c.Options.SkillsPaths, dir)
+		}
+	}
+
+	// Project specific skills dirs.
+	c.Options.SkillsPaths = append(c.Options.SkillsPaths, ProjectSkillsDir(workingDir)...)
+
+	if str, ok := os.LookupEnv("CRUSH_DISABLE_PROVIDER_AUTO_UPDATE"); ok {
+		c.Options.DisableProviderAutoUpdate, _ = strconv.ParseBool(str)
+	}
+
+	if str, ok := os.LookupEnv("CRUSH_DISABLE_DEFAULT_PROVIDERS"); ok {
+		c.Options.DisableDefaultProviders, _ = strconv.ParseBool(str)
+	}
+
+	if c.Options.Attribution == nil {
+		c.Options.Attribution = &Attribution{
+			TrailerStyle:  TrailerStyleAssistedBy,
+			GeneratedWith: true,
+		}
+	} else if c.Options.Attribution.TrailerStyle == "" {
+		// Migrate deprecated co_authored_by or apply default
+		if c.Options.Attribution.CoAuthoredBy != nil {
+			if *c.Options.Attribution.CoAuthoredBy {
+				c.Options.Attribution.TrailerStyle = TrailerStyleCoAuthoredBy
+			} else {
+				c.Options.Attribution.TrailerStyle = TrailerStyleNone
+			}
+		} else {
+			c.Options.Attribution.TrailerStyle = TrailerStyleAssistedBy
+		}
+	}
+
+	c.Options.InitializeAs = cmp.Or(c.Options.InitializeAs, defaultInitializeAs)
+}
+
+// powernapDefaults caches the powernap default LSP server catalog. The
+// catalog is static and immutable for the life of the process, but
+// building it (NewManager + LoadDefaults) is expensive and was previously
+// repeated on every config reload. We load it once and only ever read from
+// it via GetServer, so a shared instance is safe.
+var (
+	powernapDefaultsOnce sync.Once
+	powernapDefaults     *powernapConfig.Manager
+)
+
+func lspDefaultsManager() *powernapConfig.Manager {
+	powernapDefaultsOnce.Do(func() {
+		m := powernapConfig.NewManager()
+		// LoadDefaults only fails on malformed embedded defaults, which
+		// would be a build-time bug; treat the manager as usable either
+		// way so a transient error never wedges config loading.
+		_ = m.LoadDefaults()
+		powernapDefaults = m
+	})
+	return powernapDefaults
+}
+
+// applyLSPDefaults applies default values from powernap to LSP configurations
+func (c *Config) applyLSPDefaults() {
+	// Reuse the process-wide default catalog; building it per reload was a
+	// significant chunk of reload latency.
+	configManager := lspDefaultsManager()
+
+	// Apply defaults to each LSP configuration
+	for name, cfg := range c.LSP {
+		// Try to get defaults from powernap based on name or command name.
+		base, ok := configManager.GetServer(name)
+		if !ok {
+			base, ok = configManager.GetServer(cfg.Command)
+			if !ok {
+				continue
+			}
+		}
+		if cfg.Options == nil {
+			cfg.Options = base.Settings
+		}
+		if cfg.InitOptions == nil {
+			cfg.InitOptions = base.InitOptions
+		}
+		if len(cfg.FileTypes) == 0 {
+			cfg.FileTypes = base.FileTypes
+		}
+		if len(cfg.RootMarkers) == 0 {
+			cfg.RootMarkers = base.RootMarkers
+		}
+		cfg.Command = cmp.Or(cfg.Command, base.Command)
+		if len(cfg.Args) == 0 {
+			cfg.Args = base.Args
+		}
+		if len(cfg.Env) == 0 {
+			cfg.Env = base.Environment
+		}
+		// Update the config in the map
+		c.LSP[name] = cfg
+	}
+}
+
+func (c *Config) defaultModelSelection(knownProviders []catwalk.Provider) (largeModel SelectedModel, smallModel SelectedModel, err error) {
+	if len(knownProviders) == 0 && c.Providers.Len() == 0 {
+		err = fmt.Errorf("no providers configured, please configure at least one provider")
+		return largeModel, smallModel, err
+	}
+
+	// Use the first provider enabled based on the known providers order
+	// if no provider found that is known use the first provider configured
+	for _, p := range knownProviders {
+		providerConfig, ok := c.Providers.Get(string(p.ID))
+		if !ok || providerConfig.Disable {
+			continue
+		}
+		defaultLargeModel := c.GetModel(string(p.ID), p.DefaultLargeModelID)
+		if defaultLargeModel == nil {
+			slog.Warn("Default large model %s not found for provider %s", p.DefaultLargeModelID, p.ID)
+			if len(providerConfig.Models) == 0 {
+				return largeModel, smallModel, fmt.Errorf("default large model %s not found for provider %s", p.DefaultLargeModelID, p.ID)
+			}
+			defaultLargeModel = &providerConfig.Models[0]
+		}
+		largeModel = SelectedModel{
+			Provider:        string(p.ID),
+			Model:           defaultLargeModel.ID,
+			MaxTokens:       defaultLargeModel.DefaultMaxTokens,
+			ReasoningEffort: defaultLargeModel.DefaultReasoningEffort,
+		}
+
+		defaultSmallModel := c.GetModel(string(p.ID), p.DefaultSmallModelID)
+		if defaultSmallModel == nil {
+			slog.Warn("Default small model %s not found for provider %s", p.DefaultSmallModelID, p.ID)
+			if len(providerConfig.Models) == 0 {
+				return largeModel, smallModel, fmt.Errorf("default small model %s not found for provider %s", p.DefaultSmallModelID, p.ID)
+			}
+			defaultSmallModel = &providerConfig.Models[0]
+		}
+		smallModel = SelectedModel{
+			Provider:        string(p.ID),
+			Model:           defaultSmallModel.ID,
+			MaxTokens:       defaultSmallModel.DefaultMaxTokens,
+			ReasoningEffort: defaultSmallModel.DefaultReasoningEffort,
+		}
+		return largeModel, smallModel, err
+	}
+
+	enabledProviders := c.EnabledProviders()
+	slices.SortFunc(enabledProviders, func(a, b ProviderConfig) int {
+		return strings.Compare(a.ID, b.ID)
+	})
+
+	if len(enabledProviders) == 0 {
+		err = fmt.Errorf("no providers configured, please configure at least one provider")
+		return largeModel, smallModel, err
+	}
+
+	providerConfig := enabledProviders[0]
+	if len(providerConfig.Models) == 0 {
+		err = fmt.Errorf("provider %s has no models configured", providerConfig.ID)
+		return largeModel, smallModel, err
+	}
+	defaultLargeModel := c.GetModel(providerConfig.ID, providerConfig.Models[0].ID)
+	largeModel = SelectedModel{
+		Provider:  providerConfig.ID,
+		Model:     defaultLargeModel.ID,
+		MaxTokens: defaultLargeModel.DefaultMaxTokens,
+	}
+	defaultSmallModel := c.GetModel(providerConfig.ID, providerConfig.Models[0].ID)
+	smallModel = SelectedModel{
+		Provider:  providerConfig.ID,
+		Model:     defaultSmallModel.ID,
+		MaxTokens: defaultSmallModel.DefaultMaxTokens,
+	}
+	return largeModel, smallModel, err
+}
+
+// resolvedModels holds the result of resolving user-configured model
+// selections against the provider catalog.
+type resolvedModels struct {
+	Large         SelectedModel
+	Small         SelectedModel
+	LargeFallback bool // true if Large was corrected to a default
+	SmallFallback bool // true if Small was corrected to a default
+}
+
+// resolveSelectedModels validates the user's configured model selections
+// against the provider catalog, falling back to defaults when a model ID is
+// invalid. It is pure resolution logic: it does not mutate the store or
+// touch disk. The caller assigns the results to c.Models and persists any
+// fallback corrections as appropriate.
+func resolveSelectedModels(cfg *Config, knownProviders []catwalk.Provider) (resolvedModels, error) {
+	var result resolvedModels
+	defaultLarge, defaultSmall, err := cfg.defaultModelSelection(knownProviders)
+	if err != nil {
+		return result, fmt.Errorf("failed to select default models: %w", err)
+	}
+	large, small := defaultLarge, defaultSmall
+
+	largeModelSelected, largeModelConfigured := cfg.Models[SelectedModelTypeLarge]
+	if largeModelConfigured {
+		if largeModelSelected.Model != "" {
+			large.Model = largeModelSelected.Model
+		}
+		if largeModelSelected.Provider != "" {
+			large.Provider = largeModelSelected.Provider
+		}
+		model := cfg.GetModel(large.Provider, large.Model)
+		if model == nil {
+			large = defaultLarge
+			result.LargeFallback = true
+		} else {
+			if largeModelSelected.MaxTokens > 0 {
+				large.MaxTokens = largeModelSelected.MaxTokens
+			} else {
+				large.MaxTokens = model.DefaultMaxTokens
+			}
+			if largeModelSelected.ReasoningEffort != "" {
+				large.ReasoningEffort = largeModelSelected.ReasoningEffort
+			} else {
+				large.ReasoningEffort = model.DefaultReasoningEffort
+			}
+			large.Think = largeModelSelected.Think
+			if largeModelSelected.Temperature != nil {
+				large.Temperature = largeModelSelected.Temperature
+			}
+			if largeModelSelected.TopP != nil {
+				large.TopP = largeModelSelected.TopP
+			}
+			if largeModelSelected.TopK != nil {
+				large.TopK = largeModelSelected.TopK
+			}
+			if largeModelSelected.FrequencyPenalty != nil {
+				large.FrequencyPenalty = largeModelSelected.FrequencyPenalty
+			}
+			if largeModelSelected.PresencePenalty != nil {
+				large.PresencePenalty = largeModelSelected.PresencePenalty
+			}
+			if largeModelSelected.ProviderOptions != nil {
+				large.ProviderOptions = maps.Clone(largeModelSelected.ProviderOptions)
+			}
+		}
+	}
+	smallModelSelected, smallModelConfigured := cfg.Models[SelectedModelTypeSmall]
+	if smallModelConfigured {
+		if smallModelSelected.Model != "" {
+			small.Model = smallModelSelected.Model
+		}
+		if smallModelSelected.Provider != "" {
+			small.Provider = smallModelSelected.Provider
+		}
+
+		model := cfg.GetModel(small.Provider, small.Model)
+		if model == nil {
+			small = defaultSmall
+			result.SmallFallback = true
+		} else {
+			if smallModelSelected.MaxTokens > 0 {
+				small.MaxTokens = smallModelSelected.MaxTokens
+			} else {
+				small.MaxTokens = model.DefaultMaxTokens
+			}
+			if smallModelSelected.ReasoningEffort != "" {
+				small.ReasoningEffort = smallModelSelected.ReasoningEffort
+			} else {
+				small.ReasoningEffort = model.DefaultReasoningEffort
+			}
+			if smallModelSelected.Temperature != nil {
+				small.Temperature = smallModelSelected.Temperature
+			}
+			if smallModelSelected.TopP != nil {
+				small.TopP = smallModelSelected.TopP
+			}
+			if smallModelSelected.TopK != nil {
+				small.TopK = smallModelSelected.TopK
+			}
+			if smallModelSelected.FrequencyPenalty != nil {
+				small.FrequencyPenalty = smallModelSelected.FrequencyPenalty
+			}
+			if smallModelSelected.PresencePenalty != nil {
+				small.PresencePenalty = smallModelSelected.PresencePenalty
+			}
+			if smallModelSelected.ProviderOptions != nil {
+				small.ProviderOptions = maps.Clone(smallModelSelected.ProviderOptions)
+			}
+			small.Think = smallModelSelected.Think
+		}
+	}
+
+	// When small isn't explicitly configured and the provider isn't a
+	// known built-in, use the large model as the small model. This
+	// prevents two different models from being requested concurrently
+	// for local/openai-compat providers.
+	if !smallModelConfigured {
+		isKnownProvider := false
+		for _, kp := range knownProviders {
+			if string(kp.ID) == small.Provider {
+				isKnownProvider = true
+				break
+			}
+		}
+		if !isKnownProvider {
+			slog.Warn("Using large model as small model for unknown provider", "provider", large.Provider, "model", large.Model)
+			small = large
+		}
+	}
+
+	result.Large = large
+	result.Small = small
+	return result, nil
+}
+
+// lookupConfigs searches config files starting at cwd and walking up
+// through the current project. The upward walk stops at the git
+// working tree root when one can be detected, otherwise at cwd itself,
+// so an unrelated crush.json placed above the project is never picked
+// up. Global user-level config locations are always included
+// regardless of the boundary.
+func lookupConfigs(cwd string) []string {
+	// Prepend global user config and machine-owned data JSON. Only the user
+	// config directory contributes a crushrc; the data directory is writable
+	// machine state and must never be executed as Bash. Missing files are
+	// skipped when loaded.
+	configPaths := []string{
+		systemConfigPath,
+		GlobalConfig(),
+		shellConfigSibling(GlobalConfig()),
+		GlobalConfigData(),
+	}
+
+	// Ordered high-to-low priority within a directory. LookupBounded returns
+	// matches in this order, and the later reverse + merge make the earliest
+	// listed name win on conflict. So: .crushrc beats crushrc, both beat the
+	// JSON configs, and .crush.json beats crush.json.
+	configNames := []string{
+		"." + appName + "rc",
+		appName + "rc",
+		"." + appName + ".json",
+		appName + ".json",
+	}
+
+	foundConfigs, err := fsext.LookupBounded(cwd, projectBoundary(cwd), configNames...)
+	if err != nil {
+		// returns at least default configs
+		return configPaths
+	}
+
+	// reverse order so last config has more priority
+	slices.Reverse(foundConfigs)
+
+	return append(configPaths, foundConfigs...)
+}
+
+func loadFromConfigPaths(ctx context.Context, configPaths []string) (*Config, []string, error) {
+	var configs [][]byte
+	var loaded []string
+
+	// Track directories that have both crush.json and crushrc to warn
+	// about potential confusion, along with the top-level keys each
+	// defines so we can report conflicts.
+	jsonDirKeys := make(map[string]map[string]bool)
+	shDirKeys := make(map[string]map[string]bool)
+
+	for _, path := range configPaths {
+		if path == "" {
+			continue
+		}
+		data, err := os.ReadFile(path)
+		if err != nil {
+			if os.IsNotExist(err) {
+				continue
+			}
+			return nil, nil, fmt.Errorf("failed to open config file %s: %w", path, err)
+		}
+		if len(data) == 0 {
+			continue
+		}
+
+		dir := filepath.Dir(path)
+		if isShellConfig(path) {
+			jsonBytes, err := shellconfig.LoadShellConfig(ctx, path, data)
+			if err != nil {
+				return nil, nil, fmt.Errorf("failed to load shell config %s: %w", path, err)
+			}
+			if len(jsonBytes) > 0 {
+				if !json.Valid(jsonBytes) {
+					return nil, nil, fmt.Errorf("shell config %s produced invalid JSON", path)
+				}
+				addTopLevelKeys(shDirKeys, dir, jsonBytes)
+				configs = append(configs, jsonBytes)
+				loaded = append(loaded, path)
+			}
+		} else {
+			if !json.Valid(data) {
+				return nil, nil, fmt.Errorf("invalid JSON in config file %s", path)
+			}
+			addTopLevelKeys(jsonDirKeys, dir, data)
+			configs = append(configs, data)
+			loaded = append(loaded, path)
+		}
+	}
+
+	// Warn if both a JSON config and a crushrc exist in the same directory
+	// and define overlapping top-level keys. Disjoint coexistence is
+	// intentional and not worth warning about.
+	for dir, jKeys := range jsonDirKeys {
+		sKeys, ok := shDirKeys[dir]
+		if !ok {
+			continue
+		}
+		var conflicts []string
+		for k := range jKeys {
+			if sKeys[k] {
+				conflicts = append(conflicts, k)
+			}
+		}
+		if len(conflicts) > 0 {
+			slices.Sort(conflicts)
+			slog.Warn("Found both a JSON config and a crushrc in the same directory; merging with crushrc taking precedence",
+				"dir", dir, "conflicting_keys", strings.Join(conflicts, ", "))
+		}
+	}
+
+	cfg, err := loadFromBytes(configs)
+	if err != nil {
+		return nil, nil, err
+	}
+	return cfg, loaded, nil
+}
+
+// addTopLevelKeys records the top-level JSON keys present in data into the
+// set for dir.
+func addTopLevelKeys(m map[string]map[string]bool, dir string, data []byte) {
+	keys := m[dir]
+	if keys == nil {
+		keys = make(map[string]bool)
+		m[dir] = keys
+	}
+	gjson.ParseBytes(data).ForEach(func(key, _ gjson.Result) bool {
+		keys[key.String()] = true
+		return true
+	})
+}
+
+func loadFromBytes(configs [][]byte) (*Config, error) {
+	if len(configs) == 0 {
+		return &Config{}, nil
+	}
+
+	data, err := jsons.Merge(configs)
+	if err != nil {
+		return nil, err
+	}
+	var config Config
+	if err := json.Unmarshal(data, &config); err != nil {
+		return nil, err
+	}
+	return &config, nil
+}
+
+func hasAWSCredentials(env env.Env) bool {
+	if env.Get("AWS_BEARER_TOKEN_BEDROCK") != "" {
+		return true
+	}
+
+	if env.Get("AWS_ACCESS_KEY_ID") != "" && env.Get("AWS_SECRET_ACCESS_KEY") != "" {
+		return true
+	}
+
+	if env.Get("AWS_PROFILE") != "" || env.Get("AWS_DEFAULT_PROFILE") != "" {
+		return true
+	}
+
+	if env.Get("AWS_REGION") != "" || env.Get("AWS_DEFAULT_REGION") != "" {
+		return true
+	}
+
+	if env.Get("AWS_CONTAINER_CREDENTIALS_RELATIVE_URI") != "" ||
+		env.Get("AWS_CONTAINER_CREDENTIALS_FULL_URI") != "" {
+		return true
+	}
+
+	// File-based credential discovery requires filesystem stats, so do it
+	// last and skip it under test. Checking testing.Testing() before the
+	// os.Stat call (rather than after, in the && tail) ensures the syscall
+	// is never issued during tests, where it otherwise ran unconditionally
+	// and only had its result discarded.
+	if testing.Testing() {
+		return false
+	}
+	if _, err := os.Stat(filepath.Join(home.Dir(), ".aws/credentials")); err == nil {
+		return true
+	}
+	if _, err := os.Stat(filepath.Join(home.Dir(), ".aws/login")); err == nil {
+		return true
+	}
+
+	return false
+}
+
+// migrateDisableNotifications migrates the deprecated disable_notifications
+// and notification_style fields to the unified notifications field. It checks
+// both the user config (~/.config) and data config (~/.local) files. If
+// disable_notifications is true, it sets notifications to "disabled" in the
+// data file. If notification_style is set, it moves the value to notifications.
+// Regardless of value, it removes the deprecated fields from any file that
+// contains them.
+func migrateDisableNotifications() {
+	globalConfig := GlobalConfig()
+	dataConfig := GlobalConfigData()
+
+	var wasDisabled bool
+	var styleValue string
+	filesToClean := []string{}
+
+	for _, path := range []string{globalConfig, dataConfig} {
+		data, err := os.ReadFile(path)
+		if err != nil {
+			continue
+		}
+		needsClean := false
+		if gjson.Get(string(data), "options.disable_notifications").Exists() {
+			needsClean = true
+			if gjson.Get(string(data), "options.disable_notifications").Bool() {
+				wasDisabled = true
+			}
+		}
+		if v := gjson.Get(string(data), "options.notification_style"); v.Exists() {
+			needsClean = true
+			if styleValue == "" {
+				styleValue = v.String()
+			}
+		}
+		if needsClean {
+			filesToClean = append(filesToClean, path)
+		}
+	}
+
+	if len(filesToClean) == 0 {
+		return
+	}
+
+	// Determine the value to persist: notification_style takes precedence,
+	// then disable_notifications: true maps to "disabled".
+	migratedValue := styleValue
+	if migratedValue == "" && wasDisabled {
+		migratedValue = "disabled"
+	}
+
+	if migratedValue != "" {
+		data, err := os.ReadFile(dataConfig)
+		if err == nil {
+			if !gjson.Get(string(data), "options.notifications").Exists() {
+				updated, err := sjson.Set(string(data), "options.notifications", migratedValue)
+				if err == nil {
+					if err := atomicWriteFile(dataConfig, []byte(updated), 0o600); err != nil {
+						slog.Warn("Failed to migrate to notifications field", "error", err)
+					} else {
+						slog.Info("Migrated notification settings to notifications field", "value", migratedValue)
+					}
+				}
+			}
+		}
+	}
+
+	// Remove deprecated fields from all files that contain them.
+	for _, path := range filesToClean {
+		data, err := os.ReadFile(path)
+		if err != nil {
+			continue
+		}
+		updated := string(data)
+		updated, _ = sjson.Delete(updated, "options.disable_notifications")
+		updated, _ = sjson.Delete(updated, "options.notification_style")
+		if updated == string(data) {
+			continue
+		}
+		if err := atomicWriteFile(path, []byte(updated), 0o600); err != nil {
+			slog.Warn("Failed to write migrated config", "path", path, "error", err)
+		}
+	}
+}
+
+// GlobalConfig returns the global configuration file path for the application.
+func GlobalConfig() string {
+	if crushGlobal := os.Getenv("CRUSH_GLOBAL_CONFIG"); crushGlobal != "" {
+		return filepath.Join(crushGlobal, fmt.Sprintf("%s.json", appName))
+	}
+	return filepath.Join(home.Config(), appName, fmt.Sprintf("%s.json", appName))
+}
+
+// shellConfigSibling returns the crushrc path that sits alongside a given
+// crush.json path (same directory). Used so global config locations pick up a
+// shell config, not just JSON.
+func shellConfigSibling(jsonPath string) string {
+	return filepath.Join(filepath.Dir(jsonPath), appName+"rc")
+}
+
+// isShellConfig reports whether a config path is a shell config (crushrc or
+// the hidden .crushrc), as opposed to a JSON config.
+func isShellConfig(path string) bool {
+	base := filepath.Base(path)
+	return base == appName+"rc" || base == "."+appName+"rc"
+}
+
+// GlobalCacheDir returns the path to the global cache directory for the
+// application.
+func GlobalCacheDir() string {
+	if crushCache := os.Getenv("CRUSH_CACHE_DIR"); crushCache != "" {
+		return crushCache
+	}
+	if xdgCacheHome := os.Getenv("XDG_CACHE_HOME"); xdgCacheHome != "" {
+		return filepath.Join(xdgCacheHome, appName)
+	}
+	if runtime.GOOS == "windows" {
+		localAppData := cmp.Or(
+			os.Getenv("LOCALAPPDATA"),
+			filepath.Join(os.Getenv("USERPROFILE"), "AppData", "Local"),
+		)
+		return filepath.Join(localAppData, appName, "cache")
+	}
+	return filepath.Join(home.Dir(), ".cache", appName)
+}
+
+// ProjectConfigs returns list of current project configs paths.
+func ProjectConfigs(cwd string) []string {
+	return lookupConfigs(cwd)
+}
+
+// GlobalConfigData returns the path to the main data directory for the application.
+// this config is used when the app overrides configurations instead of updating the global config.
+func GlobalConfigData() string {
+	if crushData := os.Getenv("CRUSH_GLOBAL_DATA"); crushData != "" {
+		return filepath.Join(crushData, fmt.Sprintf("%s.json", appName))
+	}
+	if xdgDataHome := os.Getenv("XDG_DATA_HOME"); xdgDataHome != "" {
+		return filepath.Join(xdgDataHome, appName, fmt.Sprintf("%s.json", appName))
+	}
+
+	// return the path to the main data directory
+	// for windows, it should be in `%LOCALAPPDATA%/crush/`
+	// for linux and macOS, it should be in `$HOME/.local/share/crush/`
+	if runtime.GOOS == "windows" {
+		localAppData := cmp.Or(
+			os.Getenv("LOCALAPPDATA"),
+			filepath.Join(os.Getenv("USERPROFILE"), "AppData", "Local"),
+		)
+		return filepath.Join(localAppData, appName, fmt.Sprintf("%s.json", appName))
+	}
+
+	return filepath.Join(home.Dir(), ".local", "share", appName, fmt.Sprintf("%s.json", appName))
+}
+
+// GlobalWorkspaceDir returns the path to the global server workspace
+// directory. This directory acts as a meta-workspace for the server
+// process, giving it a real workingDir so that config loading, scoped
+// writes, and provider resolution behave identically to project
+// workspaces.
+func GlobalWorkspaceDir() string {
+	return filepath.Dir(GlobalConfigData())
+}
+
+func assignIfNil[T any](ptr **T, val T) {
+	if *ptr == nil {
+		*ptr = &val
+	}
+}
+
+func isInsideWorktree() bool {
+	bts, err := exec.CommandContext(
+		context.Background(),
+		"git", "rev-parse",
+		"--is-inside-work-tree",
+	).CombinedOutput()
+	return err == nil && strings.TrimSpace(string(bts)) == "true"
+}
+
+// worktreeRoot returns the absolute path of the git working tree root for
+// dir, or the empty string if dir is not inside a working tree (bare
+// repositories, missing git binary, plain directories, or any other
+// failure mode). Linked worktrees and submodules each report their own
+// top-level, which is what callers want when bounding lookups.
+// worktreeRootCache memoizes the git worktree root per directory. The root
+// is stable for the life of the process, so we avoid re-shelling out to
+// "git rev-parse" on every config reload. Keyed by the requested dir; the
+// value is the resolved root ("" when dir is not in a git worktree).
+var worktreeRootCache sync.Map // map[string]string
+
+func worktreeRoot(dir string) string {
+	if cached, ok := worktreeRootCache.Load(dir); ok {
+		return cached.(string)
+	}
+	root := computeWorktreeRoot(dir)
+	worktreeRootCache.Store(dir, root)
+	return root
+}
+
+func computeWorktreeRoot(dir string) string {
+	cmd := exec.CommandContext(
+		context.Background(),
+		"git", "rev-parse", "--show-toplevel",
+	)
+	cmd.Dir = dir
+	out, err := cmd.Output()
+	if err != nil {
+		return ""
+	}
+	root := strings.TrimSpace(string(out))
+	if root == "" {
+		return ""
+	}
+	abs, err := filepath.Abs(root)
+	if err != nil {
+		return ""
+	}
+	return abs
+}
+
+// projectBoundary returns the directory at which an upward configuration
+// search rooted at dir should stop. It is the git working tree root when
+// one can be detected, otherwise dir itself. Returning dir as a
+// fallback keeps Crush from silently adopting state files placed above
+// the current project.
+func projectBoundary(dir string) string {
+	if root := worktreeRoot(dir); root != "" {
+		return root
+	}
+	abs, err := filepath.Abs(dir)
+	if err != nil {
+		return dir
+	}
+	return abs
+}
+
+// GlobalSkillsDirs returns the default directories for Agent Skills.
+// Skills in these directories are auto-discovered and their files can be read
+// without permission prompts.
+func GlobalSkillsDirs() []string {
+	if crushSkills := os.Getenv("CRUSH_SKILLS_DIR"); crushSkills != "" {
+		return []string{crushSkills}
+	}
+
+	paths := []string{
+		filepath.Join(home.Config(), appName, "skills"),
+		filepath.Join(home.Config(), "agents", "skills"),
+		// Per the Agent Skills spec, scan ~/.agents/skills
+		filepath.Join(home.Dir(), ".agents", "skills"),
+		filepath.Join(home.Dir(), ".claude", "skills"),
+	}
+
+	// On Windows, also load from app data on top of `$HOME/.config/crush`.
+	// This is here mostly for backwards compatibility.
+	if runtime.GOOS == "windows" {
+		appData := cmp.Or(
+			os.Getenv("LOCALAPPDATA"),
+			filepath.Join(os.Getenv("USERPROFILE"), "AppData", "Local"),
+		)
+		paths = append(
+			paths,
+			filepath.Join(appData, appName, "skills"),
+			filepath.Join(appData, "agents", "skills"),
+		)
+	}
+
+	return paths
+}
+
+// projectSkillSubdirs lists the conventional subdirectories where
+// project-level skills are discovered. Shared across working-dir and
+// git-root lookups to prevent drift when a new convention is added.
+var projectSkillSubdirs = []string{
+	".agents/skills",
+	".crush/skills",
+	".claude/skills",
+	".cursor/skills",
+}
+
+// ProjectSkillsDir returns the default project directories for which Crush
+// will look for skills. In addition to the working directory, it also
+// checks the git working tree root so that monorepo-level skills are
+// discovered when the user is inside a subdirectory.
+// Working-directory paths come first so local skills take precedence
+// over monorepo-level ones.
+func ProjectSkillsDir(workingDir string) []string {
+	dirs := make([]string, 0, len(projectSkillSubdirs)*2)
+	for _, sub := range projectSkillSubdirs {
+		dirs = append(dirs, filepath.Join(workingDir, sub))
+	}
+
+	// When the working directory is inside a git repository, also look at
+	// the repository root so monorepo-level .agents/skills are found.
+	if root := worktreeRoot(workingDir); root != "" && root != workingDir {
+		for _, sub := range projectSkillSubdirs {
+			dirs = append(dirs, filepath.Join(root, sub))
+		}
+	}
+
+	return dirs
+}
+
+func isAppleTerminal() bool { return os.Getenv("TERM_PROGRAM") == "Apple_Terminal" }
+
+// normalizeHookEvent maps user-provided event names to their canonical
+// form. Matching is case-insensitive and accepts snake_case variants
+// (e.g. "pre_tool_use" → "PreToolUse").
+func normalizeHookEvent(name string) string {
+	switch strings.ToLower(strings.ReplaceAll(name, "_", "")) {
+	case "pretooluse":
+		return "PreToolUse"
+	default:
+		return name
+	}
+}
+
+// ValidateHooks normalizes event names and checks that every configured
+// hook has a command and a syntactically valid matcher regex. Matcher
+// compilation used for matching is owned by hooks.Runner; this function
+// only validates up front so the user sees config errors at load time
+// rather than on the first tool call.
+func (c *Config) ValidateHooks() error {
+	// Normalize event name keys.
+	for event, eventHooks := range c.Hooks {
+		canonical := normalizeHookEvent(event)
+		if canonical != event {
+			c.Hooks[canonical] = append(c.Hooks[canonical], eventHooks...)
+			delete(c.Hooks, event)
+		}
+	}
+
+	for event, eventHooks := range c.Hooks {
+		for i, h := range eventHooks {
+			if h.Command == "" {
+				return fmt.Errorf("hook %s[%d]: command is required", event, i)
+			}
+			if h.Matcher == "" {
+				continue
+			}
+			if _, err := regexp.Compile(h.Matcher); err != nil {
+				return fmt.Errorf("hook %s[%d]: invalid matcher regex %q: %w", event, i, h.Matcher, err)
+			}
+		}
+	}
+	return nil
+}

internal/config/load_test.go

@@ -0,0 +1,2536 @@
+package config
+
+import (
+	"context"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"github.com/charmbracelet/crush/internal/csync"
+	"github.com/charmbracelet/crush/internal/env"
+	"github.com/charmbracelet/crush/internal/oauth"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestMain(m *testing.M) {
+	slog.SetDefault(slog.New(slog.NewTextHandler(io.Discard, nil)))
+
+	exitVal := m.Run()
+	os.Exit(exitVal)
+}
+
+func TestConfig_LoadFromBytes(t *testing.T) {
+	data1 := []byte(`{"providers": {"openai": {"api_key": "key1", "base_url": "https://api.openai.com/v1"}}}`)
+	data2 := []byte(`{"providers": {"openai": {"api_key": "key2", "base_url": "https://api.openai.com/v2"}}}`)
+	data3 := []byte(`{"providers": {"openai": {}}}`)
+
+	loadedConfig, err := loadFromBytes([][]byte{data1, data2, data3})
+
+	require.NoError(t, err)
+	require.NotNil(t, loadedConfig)
+	require.Equal(t, 1, loadedConfig.Providers.Len())
+	pc, _ := loadedConfig.Providers.Get("openai")
+	require.Equal(t, "key2", pc.APIKey)
+	require.Equal(t, "https://api.openai.com/v2", pc.BaseURL)
+}
+
+func TestLookupConfigs_BoundedByProject(t *testing.T) {
+	// Force GlobalConfig and GlobalConfigData to point at locations we
+	// control so they can be present in the result without polluting
+	// the developer's real config.
+	globalDir := t.TempDir()
+	dataDir := t.TempDir()
+	t.Setenv("CRUSH_GLOBAL_CONFIG", globalDir)
+	t.Setenv("CRUSH_GLOBAL_DATA", dataDir)
+
+	t.Run("does not pick up crush.json above non-git project", func(t *testing.T) {
+		parent := t.TempDir()
+
+		// crush.json above the project must not be adopted.
+		require.NoError(t, os.WriteFile(
+			filepath.Join(parent, "crush.json"),
+			[]byte(`{}`),
+			0o644,
+		))
+
+		project := filepath.Join(parent, "project")
+		require.NoError(t, os.Mkdir(project, 0o755))
+
+		got := lookupConfigs(project)
+		for _, p := range got {
+			require.NotEqual(t, filepath.Join(parent, "crush.json"), p)
+		}
+	})
+
+	t.Run("does not climb out of git worktree to find crush.json", func(t *testing.T) {
+		if _, err := exec.LookPath("git"); err != nil {
+			t.Skip("git not available")
+		}
+
+		parent := t.TempDir()
+
+		require.NoError(t, os.WriteFile(
+			filepath.Join(parent, "crush.json"),
+			[]byte(`{}`),
+			0o644,
+		))
+
+		worktree := filepath.Join(parent, "worktree")
+		require.NoError(t, os.Mkdir(worktree, 0o755))
+		gitInit := exec.CommandContext(t.Context(), "git", "init", "-q")
+		gitInit.Dir = worktree
+		require.NoError(t, gitInit.Run())
+
+		got := lookupConfigs(worktree)
+		strayEval, err := filepath.EvalSymlinks(filepath.Join(parent, "crush.json"))
+		require.NoError(t, err)
+		for _, p := range got {
+			pEval, err := filepath.EvalSymlinks(p)
+			if err != nil {
+				continue
+			}
+			require.NotEqual(t, strayEval, pEval, "must not adopt parent crush.json")
+		}
+	})
+
+	t.Run("picks up crush.json inside the project", func(t *testing.T) {
+		project := t.TempDir()
+		local := filepath.Join(project, "crush.json")
+		require.NoError(t, os.WriteFile(local, []byte(`{}`), 0o644))
+
+		got := lookupConfigs(project)
+
+		localEval, err := filepath.EvalSymlinks(local)
+		require.NoError(t, err)
+		var foundLocal bool
+		for _, p := range got {
+			pEval, err := filepath.EvalSymlinks(p)
+			if err != nil {
+				continue
+			}
+			if pEval == localEval {
+				foundLocal = true
+				break
+			}
+		}
+		require.True(t, foundLocal, "expected project crush.json to be in lookup result: %v", got)
+	})
+
+	t.Run("global config is always included regardless of boundary", func(t *testing.T) {
+		project := t.TempDir()
+
+		got := lookupConfigs(project)
+		// Global config and global data path are always prepended,
+		// even when no project file exists.
+		require.Contains(t, got, GlobalConfig())
+		require.Contains(t, got, GlobalConfigData())
+	})
+
+	t.Run("global shell config (crushrc) is included", func(t *testing.T) {
+		project := t.TempDir()
+
+		got := lookupConfigs(project)
+		// A global crushrc is discovered only beside the user config. The data
+		// directory is machine-owned state and must never execute a crushrc.
+		require.Contains(t, got, shellConfigSibling(GlobalConfig()))
+		require.NotContains(t, got, shellConfigSibling(GlobalConfigData()))
+	})
+
+	t.Run("project crushrc and .crushrc are discovered", func(t *testing.T) {
+		project := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(project, "crushrc"), []byte(""), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(project, ".crushrc"), []byte(""), 0o644))
+
+		got := lookupConfigs(project)
+		require.Contains(t, got, filepath.Join(project, "crushrc"))
+		require.Contains(t, got, filepath.Join(project, ".crushrc"))
+	})
+
+	t.Run("system config is loaded first", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("system config not supported on Windows")
+		}
+
+		got := lookupConfigs(t.TempDir())
+		require.NotEmpty(t, got)
+		// The system-wide config must be first so it has the lowest
+		// priority when configs are merged.
+		require.Equal(t, "/etc/crush/crush.json", got[0])
+	})
+}
+
+func TestLoadFromConfigPaths_InvalidJSON(t *testing.T) {
+	t.Parallel()
+
+	t.Run("identifies the offending file", func(t *testing.T) {
+		t.Parallel()
+		tmpDir := t.TempDir()
+		good := filepath.Join(tmpDir, "good.json")
+		bad := filepath.Join(tmpDir, "bad.json")
+		require.NoError(t, os.WriteFile(good, []byte(`{"providers":{}}`), 0o644))
+		require.NoError(t, os.WriteFile(bad, []byte(`{not valid json}`), 0o644))
+
+		_, _, err := loadFromConfigPaths(context.Background(), []string{good, bad})
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "invalid JSON in config file")
+		require.Contains(t, err.Error(), "bad.json")
+	})
+
+	t.Run("skips missing and empty files", func(t *testing.T) {
+		t.Parallel()
+		tmpDir := t.TempDir()
+		empty := filepath.Join(tmpDir, "empty.json")
+		require.NoError(t, os.WriteFile(empty, []byte(""), 0o644))
+
+		cfg, _, err := loadFromConfigPaths(context.Background(), []string{
+			filepath.Join(tmpDir, "nonexistent.json"),
+			empty,
+		})
+		require.NoError(t, err)
+		require.NotNil(t, cfg)
+	})
+}
+
+// TestLoadFromConfigPaths_ConflictWarningNamesKeys verifies that when a JSON
+// config and a crushrc coexist in the same directory, the merge warning names
+// the overlapping top-level keys so incremental migrations can spot stale
+// duplicates.
+func TestLoadFromConfigPaths_ConflictWarningNamesKeys(t *testing.T) {
+	capture := func(t *testing.T) *strings.Builder {
+		t.Helper()
+		var buf strings.Builder
+		prev := slog.Default()
+		slog.SetDefault(slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{Level: slog.LevelWarn})))
+		t.Cleanup(func() { slog.SetDefault(prev) })
+		return &buf
+	}
+
+	t.Run("names overlapping keys", func(t *testing.T) {
+		buf := capture(t)
+		tmpDir := t.TempDir()
+		jsonPath := filepath.Join(tmpDir, "crush.json")
+		rcPath := filepath.Join(tmpDir, "crushrc")
+		require.NoError(t, os.WriteFile(jsonPath, []byte(`{"options":{"debug":true},"providers":{}}`), 0o644))
+		require.NoError(t, os.WriteFile(rcPath, []byte("option debug true\n"), 0o644))
+
+		_, _, err := loadFromConfigPaths(context.Background(), []string{jsonPath, rcPath})
+		require.NoError(t, err)
+		require.Contains(t, buf.String(), "crushrc taking precedence")
+		require.Contains(t, buf.String(), `"conflicting_keys":"options"`)
+	})
+
+	t.Run("no warning when nothing overlaps", func(t *testing.T) {
+		buf := capture(t)
+		tmpDir := t.TempDir()
+		jsonPath := filepath.Join(tmpDir, "crush.json")
+		rcPath := filepath.Join(tmpDir, "crushrc")
+		require.NoError(t, os.WriteFile(jsonPath, []byte(`{"providers":{}}`), 0o644))
+		require.NoError(t, os.WriteFile(rcPath, []byte("option debug true\n"), 0o644))
+
+		_, _, err := loadFromConfigPaths(context.Background(), []string{jsonPath, rcPath})
+		require.NoError(t, err)
+		require.NotContains(t, buf.String(), "crushrc taking precedence",
+			"disjoint coexistence should not warn")
+	})
+}
+
+// testStore wraps a Config in a minimal ConfigStore for testing.
+func testStore(cfg *Config) *ConfigStore {
+	return &ConfigStore{config: cfg}
+}
+
+func TestConfig_setDefaults(t *testing.T) {
+	t.Run("sets default data directory", func(t *testing.T) {
+		cfg := &Config{}
+		workingDir := t.TempDir()
+
+		cfg.setDefaults(workingDir, "")
+
+		require.NotNil(t, cfg.Options)
+		require.NotNil(t, cfg.Options.TUI)
+		require.NotNil(t, cfg.Options.ContextPaths)
+		require.NotNil(t, cfg.Providers)
+		require.NotNil(t, cfg.Models)
+		require.NotNil(t, cfg.LSP)
+		require.NotNil(t, cfg.MCP)
+		require.Equal(t, filepath.Join(workingDir, ".crush"), cfg.Options.DataDirectory)
+		require.Equal(t, "AGENTS.md", cfg.Options.InitializeAs)
+		// DiffMode is deliberately left empty: the permissions dialog treats
+		// the zero value as "pick split or unified based on terminal width".
+		require.Empty(t, cfg.Options.TUI.DiffMode)
+		require.Equal(t, ScrollbarDefault, cfg.Options.TUI.Scrollbar)
+		require.Equal(t, ExitBannerDefault, cfg.Options.TUI.ExitBanner)
+		for _, path := range defaultContextPaths {
+			require.Contains(t, cfg.Options.ContextPaths, path)
+		}
+	})
+
+	t.Run("sets TUI defaults only when unset", func(t *testing.T) {
+		cfg := &Config{}
+		workingDir := t.TempDir()
+
+		cfg.setDefaults(workingDir, "")
+
+		require.Empty(t, cfg.Options.TUI.DiffMode)
+		require.Equal(t, ScrollbarDefault, cfg.Options.TUI.Scrollbar)
+		require.Equal(t, ExitBannerDefault, cfg.Options.TUI.ExitBanner)
+
+		cfg.Options.TUI.DiffMode = DiffModeSplit
+		cfg.Options.TUI.Scrollbar = ScrollbarNever
+		cfg.Options.TUI.ExitBanner = ExitBannerCompact
+		cfg.setDefaults(workingDir, "")
+
+		require.Equal(t, DiffModeSplit, cfg.Options.TUI.DiffMode)
+		require.Equal(t, ScrollbarNever, cfg.Options.TUI.Scrollbar)
+		require.Equal(t, ExitBannerCompact, cfg.Options.TUI.ExitBanner)
+	})
+
+	t.Run("prunes orphaned OAuth token MCP entries but keeps real ones", func(t *testing.T) {
+		cfg := &Config{
+			MCP: map[string]MCPConfig{
+				"orphan":     {OAuthToken: &oauth.Token{AccessToken: "stale"}},
+				"real-http":  {Type: MCPHttp, URL: "https://example.com/mcp", OAuthToken: &oauth.Token{AccessToken: "live"}},
+				"real-stdio": {Type: MCPStdio, Command: "npx"},
+				"malformed":  {Command: "npx"}, // missing type but has a command: surface the error, don't prune
+			},
+		}
+
+		cfg.setDefaults(t.TempDir(), "")
+
+		require.NotContains(t, cfg.MCP, "orphan", "orphaned token entry should be pruned")
+		require.Contains(t, cfg.MCP, "real-http")
+		require.Contains(t, cfg.MCP, "real-stdio")
+		require.Contains(t, cfg.MCP, "malformed", "malformed entry should survive so its error surfaces")
+	})
+
+	t.Run("resolves relative configured data directory from working directory", func(t *testing.T) {
+		cfg := &Config{Options: &Options{DataDirectory: "."}}
+		workingDir := filepath.Join(t.TempDir(), "worktree")
+
+		cfg.setDefaults(workingDir, "")
+
+		require.Equal(t, workingDir, cfg.Options.DataDirectory)
+	})
+
+	t.Run("resolves relative flag data directory from working directory", func(t *testing.T) {
+		cfg := &Config{}
+		workingDir := filepath.Join(t.TempDir(), "worktree")
+
+		cfg.setDefaults(workingDir, "./state")
+
+		require.Equal(t, filepath.Join(workingDir, "state"), cfg.Options.DataDirectory)
+	})
+
+	t.Run("preserves absolute configured data directory", func(t *testing.T) {
+		// Use a platform-appropriate absolute path so the test runs
+		// the same way on POSIX and Windows.
+		absDir := filepath.Join(t.TempDir(), "data")
+		cfg := &Config{Options: &Options{DataDirectory: absDir}}
+
+		cfg.setDefaults(filepath.Join(t.TempDir(), "worktree"), "")
+
+		require.Equal(t, absDir, cfg.Options.DataDirectory)
+	})
+
+	t.Run("workspace merge re-entry keeps an absolute data directory", func(t *testing.T) {
+		// Simulate the load and reload paths: defaults are applied
+		// twice with the data directory potentially carried through
+		// from an earlier merge as a relative string.
+		workingDir := filepath.Join(t.TempDir(), "worktree")
+		cfg := &Config{}
+		cfg.setDefaults(workingDir, "")
+
+		// Workspace JSON sets data_directory to a relative value; the
+		// merge replaces the struct, then setDefaults runs again.
+		cfg.Options.DataDirectory = "./state"
+		cfg.setDefaults(workingDir, "")
+
+		require.True(t, filepath.IsAbs(cfg.Options.DataDirectory),
+			"data directory must remain absolute after re-merge, got %q",
+			cfg.Options.DataDirectory)
+		require.Equal(t, filepath.Join(workingDir, "state"), cfg.Options.DataDirectory)
+	})
+
+	t.Run("does not adopt .crush from a parent project", func(t *testing.T) {
+		parent := t.TempDir()
+
+		// .crush in the parent: it should not be reused by the child
+		// because there is no git context joining them.
+		require.NoError(t, os.Mkdir(filepath.Join(parent, defaultDataDirectory), 0o755))
+
+		child := filepath.Join(parent, "child")
+		require.NoError(t, os.Mkdir(child, 0o755))
+
+		cfg := &Config{}
+		cfg.setDefaults(child, "")
+
+		require.Equal(
+			t,
+			filepath.Clean(filepath.Join(child, defaultDataDirectory)),
+			filepath.Clean(cfg.Options.DataDirectory),
+		)
+	})
+
+	t.Run("does not climb out of git worktree to find .crush", func(t *testing.T) {
+		if _, err := exec.LookPath("git"); err != nil {
+			t.Skip("git not available")
+		}
+
+		parent := t.TempDir()
+
+		// Stray .crush above the worktree root.
+		require.NoError(t, os.Mkdir(filepath.Join(parent, defaultDataDirectory), 0o755))
+
+		worktree := filepath.Join(parent, "worktree")
+		require.NoError(t, os.Mkdir(worktree, 0o755))
+
+		sub := filepath.Join(worktree, "pkg")
+		require.NoError(t, os.Mkdir(sub, 0o755))
+
+		// Make worktree a real git repo so the boundary detection
+		// resolves to it, mirroring what happens with linked worktrees
+		// in real usage.
+		gitInit := exec.CommandContext(t.Context(), "git", "init", "-q")
+		gitInit.Dir = worktree
+		require.NoError(t, gitInit.Run())
+
+		cfg := &Config{}
+		cfg.setDefaults(sub, "")
+
+		// Resolve symlinks because TempDir on macOS sits under /var
+		// which is a symlink to /private/var. The data directory has
+		// not been created yet, so resolve its parent and join.
+		gotDir, gotName := filepath.Split(cfg.Options.DataDirectory)
+		gotEvalDir, err := filepath.EvalSymlinks(filepath.Clean(gotDir))
+		require.NoError(t, err)
+		gotEval := filepath.Join(gotEvalDir, gotName)
+
+		strayEval, err := filepath.EvalSymlinks(filepath.Join(parent, defaultDataDirectory))
+		require.NoError(t, err)
+		require.NotEqual(t, strayEval, gotEval, "must not adopt parent .crush")
+
+		subEval, err := filepath.EvalSymlinks(sub)
+		require.NoError(t, err)
+		require.Equal(t, filepath.Join(subEval, defaultDataDirectory), gotEval)
+	})
+}
+
+func TestConfig_configureProviders(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$OPENAI_API_KEY",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models: []catwalk.Model{{
+				ID: "test-model",
+			}},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+	env := env.NewFromMap(map[string]string{
+		"OPENAI_API_KEY": "test-key",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	require.Equal(t, 1, cfg.Providers.Len())
+
+	// We want to make sure that we keep the configured API key as a placeholder
+	pc, _ := cfg.Providers.Get("openai")
+	require.Equal(t, "$OPENAI_API_KEY", pc.APIKey)
+}
+
+func TestConfig_configureProvidersWithOverride(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$OPENAI_API_KEY",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models: []catwalk.Model{{
+				ID: "test-model",
+			}},
+		},
+	}
+
+	cfg := &Config{
+		Providers: csync.NewMap[string, ProviderConfig](),
+	}
+	cfg.Providers.Set("openai", ProviderConfig{
+		APIKey:  "xyz",
+		BaseURL: "https://api.openai.com/v2",
+		Models: []catwalk.Model{
+			{
+				ID:   "test-model",
+				Name: "Updated",
+			},
+			{
+				ID: "another-model",
+			},
+		},
+	})
+	cfg.setDefaults("/tmp", "")
+
+	env := env.NewFromMap(map[string]string{
+		"OPENAI_API_KEY": "test-key",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	require.Equal(t, 1, cfg.Providers.Len())
+
+	// We want to make sure that we keep the configured API key as a placeholder
+	pc, _ := cfg.Providers.Get("openai")
+	require.Equal(t, "xyz", pc.APIKey)
+	require.Equal(t, "https://api.openai.com/v2", pc.BaseURL)
+	require.Len(t, pc.Models, 2)
+	require.Equal(t, "Updated", pc.Models[0].Name)
+}
+
+func TestConfig_configureProvidersWithNewProvider(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$OPENAI_API_KEY",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models: []catwalk.Model{{
+				ID: "test-model",
+			}},
+		},
+	}
+
+	cfg := &Config{
+		Providers: csync.NewMapFrom(map[string]ProviderConfig{
+			"custom": {
+				APIKey:  "xyz",
+				BaseURL: "https://api.someendpoint.com/v2",
+				Models: []catwalk.Model{
+					{
+						ID: "test-model",
+					},
+				},
+			},
+		}),
+	}
+	cfg.setDefaults("/tmp", "")
+	env := env.NewFromMap(map[string]string{
+		"OPENAI_API_KEY": "test-key",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	// Should be to because of the env variable
+	require.Equal(t, cfg.Providers.Len(), 2)
+
+	// We want to make sure that we keep the configured API key as a placeholder
+	pc, _ := cfg.Providers.Get("custom")
+	require.Equal(t, "xyz", pc.APIKey)
+	// Make sure we set the ID correctly
+	require.Equal(t, "custom", pc.ID)
+	require.Equal(t, "https://api.someendpoint.com/v2", pc.BaseURL)
+	require.Len(t, pc.Models, 1)
+
+	_, ok := cfg.Providers.Get("openai")
+	require.True(t, ok, "OpenAI provider should still be present")
+}
+
+func TestConfig_configureProvidersBedrockWithCredentials(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          catwalk.InferenceProviderBedrock,
+			APIKey:      "",
+			APIEndpoint: "",
+			Models: []catwalk.Model{{
+				ID: "anthropic.claude-sonnet-4-20250514-v1:0",
+			}},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+	env := env.NewFromMap(map[string]string{
+		"AWS_ACCESS_KEY_ID":     "test-key-id",
+		"AWS_SECRET_ACCESS_KEY": "test-secret-key",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	require.Equal(t, cfg.Providers.Len(), 1)
+
+	bedrockProvider, ok := cfg.Providers.Get("bedrock")
+	require.True(t, ok, "Bedrock provider should be present")
+	require.Len(t, bedrockProvider.Models, 1)
+	require.Equal(t, "anthropic.claude-sonnet-4-20250514-v1:0", bedrockProvider.Models[0].ID)
+}
+
+func TestConfig_configureProvidersBedrockWithoutCredentials(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          catwalk.InferenceProviderBedrock,
+			APIKey:      "",
+			APIEndpoint: "",
+			Models: []catwalk.Model{{
+				ID: "anthropic.claude-sonnet-4-20250514-v1:0",
+			}},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+	env := env.NewFromMap(map[string]string{})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	// Provider should not be configured without credentials
+	require.Equal(t, cfg.Providers.Len(), 0)
+}
+
+func TestConfig_configureProvidersVertexAIWithCredentials(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          catwalk.InferenceProviderVertexAI,
+			APIKey:      "",
+			APIEndpoint: "",
+			Models: []catwalk.Model{{
+				ID: "gemini-pro",
+			}},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+	env := env.NewFromMap(map[string]string{
+		"VERTEXAI_PROJECT":  "test-project",
+		"VERTEXAI_LOCATION": "us-central1",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	require.Equal(t, cfg.Providers.Len(), 1)
+
+	vertexProvider, ok := cfg.Providers.Get("vertexai")
+	require.True(t, ok, "VertexAI provider should be present")
+	require.Len(t, vertexProvider.Models, 1)
+	require.Equal(t, "gemini-pro", vertexProvider.Models[0].ID)
+	require.Equal(t, "test-project", vertexProvider.ExtraParams["project"])
+	require.Equal(t, "us-central1", vertexProvider.ExtraParams["location"])
+}
+
+func TestConfig_configureProvidersVertexAIWithoutCredentials(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          catwalk.InferenceProviderVertexAI,
+			APIKey:      "",
+			APIEndpoint: "",
+			Models: []catwalk.Model{{
+				ID: "gemini-pro",
+			}},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+	env := env.NewFromMap(map[string]string{
+		"GOOGLE_GENAI_USE_VERTEXAI": "false",
+		"GOOGLE_CLOUD_PROJECT":      "test-project",
+		"GOOGLE_CLOUD_LOCATION":     "us-central1",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	// Provider should not be configured without proper credentials
+	require.Equal(t, cfg.Providers.Len(), 0)
+}
+
+func TestConfig_configureProvidersVertexAIMissingProject(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          catwalk.InferenceProviderVertexAI,
+			APIKey:      "",
+			APIEndpoint: "",
+			Models: []catwalk.Model{{
+				ID: "gemini-pro",
+			}},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+	env := env.NewFromMap(map[string]string{
+		"GOOGLE_GENAI_USE_VERTEXAI": "true",
+		"GOOGLE_CLOUD_LOCATION":     "us-central1",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	// Provider should not be configured without project
+	require.Equal(t, cfg.Providers.Len(), 0)
+}
+
+func TestConfig_configureProvidersSetProviderID(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$OPENAI_API_KEY",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models: []catwalk.Model{{
+				ID: "test-model",
+			}},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+	env := env.NewFromMap(map[string]string{
+		"OPENAI_API_KEY": "test-key",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	require.Equal(t, cfg.Providers.Len(), 1)
+
+	// Provider ID should be set
+	pc, _ := cfg.Providers.Get("openai")
+	require.Equal(t, "openai", pc.ID)
+}
+
+func TestConfig_EnabledProviders(t *testing.T) {
+	t.Run("all providers enabled", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"openai": {
+					ID:      "openai",
+					APIKey:  "key1",
+					Disable: false,
+				},
+				"anthropic": {
+					ID:      "anthropic",
+					APIKey:  "key2",
+					Disable: false,
+				},
+			}),
+		}
+
+		enabled := cfg.EnabledProviders()
+		require.Len(t, enabled, 2)
+	})
+
+	t.Run("some providers disabled", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"openai": {
+					ID:      "openai",
+					APIKey:  "key1",
+					Disable: false,
+				},
+				"anthropic": {
+					ID:      "anthropic",
+					APIKey:  "key2",
+					Disable: true,
+				},
+			}),
+		}
+
+		enabled := cfg.EnabledProviders()
+		require.Len(t, enabled, 1)
+		require.Equal(t, "openai", enabled[0].ID)
+	})
+
+	t.Run("empty providers map", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMap[string, ProviderConfig](),
+		}
+
+		enabled := cfg.EnabledProviders()
+		require.Len(t, enabled, 0)
+	})
+}
+
+func TestConfig_IsConfigured(t *testing.T) {
+	t.Run("returns true when at least one provider is enabled", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"openai": {
+					ID:      "openai",
+					APIKey:  "key1",
+					Disable: false,
+				},
+			}),
+		}
+
+		require.True(t, cfg.IsConfigured())
+	})
+
+	t.Run("returns false when no providers are configured", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMap[string, ProviderConfig](),
+		}
+
+		require.False(t, cfg.IsConfigured())
+	})
+
+	t.Run("returns false when all providers are disabled", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"openai": {
+					ID:      "openai",
+					APIKey:  "key1",
+					Disable: true,
+				},
+				"anthropic": {
+					ID:      "anthropic",
+					APIKey:  "key2",
+					Disable: true,
+				},
+			}),
+		}
+
+		require.False(t, cfg.IsConfigured())
+	})
+}
+
+func TestConfig_setupAgentsWithNoDisabledTools(t *testing.T) {
+	cfg := &Config{
+		Options: &Options{
+			DisabledTools: []string{},
+		},
+	}
+
+	cfg.SetupAgents()
+	coderAgent, ok := cfg.Agents[AgentCoder]
+	require.True(t, ok)
+	assert.Equal(t, allToolNames(), coderAgent.AllowedTools)
+
+	taskAgent, ok := cfg.Agents[AgentTask]
+	require.True(t, ok)
+	assert.Equal(t, []string{"lsp_symbols", "lsp_definition", "lsp_call_hierarchy", "glob", "grep", "ls", "sourcegraph", "view"}, taskAgent.AllowedTools)
+}
+
+func TestConfig_setupAgentsWithDisabledTools(t *testing.T) {
+	cfg := &Config{
+		Options: &Options{
+			DisabledTools: []string{
+				"edit",
+				"download",
+				"grep",
+			},
+		},
+	}
+
+	cfg.SetupAgents()
+	coderAgent, ok := cfg.Agents[AgentCoder]
+	require.True(t, ok)
+
+	assert.Equal(t, []string{"agent", "bash", "crush_info", "crush_logs", "job_output", "job_kill", "multiedit", "lsp_diagnostics", "lsp_references", "lsp_restart", "lsp_symbols", "lsp_definition", "lsp_call_hierarchy", "lsp_rename", "lsp_replace_symbol", "fetch", "agentic_fetch", "glob", "ls", "question", "sourcegraph", "todos", "view", "write", "list_mcp_resources", "read_mcp_resource"}, coderAgent.AllowedTools)
+
+	taskAgent, ok := cfg.Agents[AgentTask]
+	require.True(t, ok)
+	assert.Equal(t, []string{"lsp_symbols", "lsp_definition", "lsp_call_hierarchy", "glob", "ls", "sourcegraph", "view"}, taskAgent.AllowedTools)
+}
+
+func TestConfig_setupAgentsWithEveryReadOnlyToolDisabled(t *testing.T) {
+	cfg := &Config{
+		Options: &Options{
+			DisabledTools: []string{
+				"glob",
+				"grep",
+				"ls",
+				"lsp_call_hierarchy",
+				"lsp_definition",
+				"lsp_symbols",
+				"sourcegraph",
+				"view",
+			},
+		},
+	}
+
+	cfg.SetupAgents()
+	coderAgent, ok := cfg.Agents[AgentCoder]
+	require.True(t, ok)
+	assert.Equal(t, []string{"agent", "bash", "crush_info", "crush_logs", "job_output", "job_kill", "download", "edit", "multiedit", "lsp_diagnostics", "lsp_references", "lsp_restart", "lsp_rename", "lsp_replace_symbol", "fetch", "agentic_fetch", "question", "todos", "write", "list_mcp_resources", "read_mcp_resource"}, coderAgent.AllowedTools)
+
+	taskAgent, ok := cfg.Agents[AgentTask]
+	require.True(t, ok)
+	assert.Len(t, taskAgent.AllowedTools, 0)
+}
+
+func TestConfig_configureProvidersWithDisabledProvider(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$OPENAI_API_KEY",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models: []catwalk.Model{{
+				ID: "test-model",
+			}},
+		},
+	}
+
+	cfg := &Config{
+		Providers: csync.NewMapFrom(map[string]ProviderConfig{
+			"openai": {
+				Disable: true,
+			},
+		}),
+	}
+	cfg.setDefaults("/tmp", "")
+
+	env := env.NewFromMap(map[string]string{
+		"OPENAI_API_KEY": "test-key",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+
+	require.Equal(t, cfg.Providers.Len(), 1)
+	prov, exists := cfg.Providers.Get("openai")
+	require.True(t, exists)
+	require.True(t, prov.Disable)
+}
+
+func TestConfig_configureProvidersCustomProviderValidation(t *testing.T) {
+	t.Run("custom provider with missing API key is allowed, but not known providers", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					BaseURL: "https://api.custom.com/v1",
+					Models: []catwalk.Model{{
+						ID: "test-model",
+					}},
+				},
+				"openai": {
+					APIKey: "$MISSING",
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 1)
+		_, exists := cfg.Providers.Get("custom")
+		require.True(t, exists)
+	})
+
+	t.Run("custom provider with missing BaseURL is removed", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey: "test-key",
+					Models: []catwalk.Model{{
+						ID: "test-model",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 0)
+		_, exists := cfg.Providers.Get("custom")
+		require.False(t, exists)
+	})
+
+	t.Run("custom provider with shell-expanded BaseURL is kept", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "$(echo https://api.custom.com/v1)",
+					Models: []catwalk.Model{{
+						ID: "test-model",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, 1, cfg.Providers.Len())
+		_, exists := cfg.Providers.Get("custom")
+		require.True(t, exists, "a BaseURL supplied via shell expansion must pass endpoint validation")
+	})
+
+	t.Run("custom provider with env var BaseURL is kept", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "$CUSTOM_API_URL",
+					Models: []catwalk.Model{{
+						ID: "test-model",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{
+			"CUSTOM_API_URL": "https://api.custom.com/v1",
+		})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, 1, cfg.Providers.Len())
+		_, exists := cfg.Providers.Get("custom")
+		require.True(t, exists, "a BaseURL supplied via an env variable must pass endpoint validation")
+	})
+
+	t.Run("custom provider whose BaseURL resolves to empty is removed", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "$MISSING_API_URL",
+					Models: []catwalk.Model{{
+						ID: "test-model",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, 0, cfg.Providers.Len())
+		_, exists := cfg.Providers.Get("custom")
+		require.False(t, exists, "a raw-non-empty BaseURL that resolves to empty must be rejected")
+	})
+
+	t.Run("BaseURL resolving to empty with disable_default_providers returns an error", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "$MISSING_API_URL",
+					Models: []catwalk.Model{{
+						ID: "test-model",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+		cfg.Options.DisableDefaultProviders = true
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.Error(t, err, "the sole custom provider is invalid after resolution, so configuration must fail")
+	})
+
+	t.Run("custom provider with no models attempts discovery and is removed on failure", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "https://api.custom.com/v1",
+					Models:  []catwalk.Model{},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		// Discovery fails (unreachable URL) so provider is removed.
+		require.Equal(t, 0, cfg.Providers.Len())
+		_, exists := cfg.Providers.Get("custom")
+		require.False(t, exists)
+	})
+
+	t.Run("custom provider with no models and discover_models:false is removed", func(t *testing.T) {
+		discoverFalse := false
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:             "test-key",
+					BaseURL:            "https://api.custom.com/v1",
+					Models:             []catwalk.Model{},
+					AutoDiscoverModels: &discoverFalse,
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, 0, cfg.Providers.Len())
+		_, exists := cfg.Providers.Get("custom")
+		require.False(t, exists)
+	})
+
+	t.Run("custom provider with models and discover_models:true merges discovered models", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"data": [
+				{"id": "existing-model", "object": "model"},
+				{"id": "discovered-model", "object": "model"}
+			]}`))
+		}))
+		defer server.Close()
+
+		discoverTrue := true
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: server.URL + "/v1",
+					Models: []catwalk.Model{
+						{ID: "existing-model", Name: "My Custom Name", ContextWindow: 200000},
+					},
+					AutoDiscoverModels: &discoverTrue,
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, 1, cfg.Providers.Len())
+		p, exists := cfg.Providers.Get("custom")
+		require.True(t, exists)
+		require.Len(t, p.Models, 2)
+
+		// User-specified model keeps its custom fields.
+		require.Equal(t, "existing-model", p.Models[0].ID)
+		require.Equal(t, "My Custom Name", p.Models[0].Name)
+		require.Equal(t, int64(200000), p.Models[0].ContextWindow)
+
+		// Discovered model is appended.
+		require.Equal(t, "discovered-model", p.Models[1].ID)
+	})
+
+	t.Run("custom provider with models and no discover_models uses only listed models", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "https://api.custom.com/v1",
+					Models: []catwalk.Model{
+						{ID: "my-model", Name: "My Model"},
+					},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, 1, cfg.Providers.Len())
+		p, exists := cfg.Providers.Get("custom")
+		require.True(t, exists)
+		require.Len(t, p.Models, 1)
+		require.Equal(t, "my-model", p.Models[0].ID)
+	})
+
+	t.Run("custom provider with no models auto-discovers successfully", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"data": [
+				{"id": "auto-model-a", "object": "model"},
+				{"id": "auto-model-b", "object": "model"}
+			]}`))
+		}))
+		defer server.Close()
+
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: server.URL + "/v1",
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, 1, cfg.Providers.Len())
+		p, exists := cfg.Providers.Get("custom")
+		require.True(t, exists)
+		require.Len(t, p.Models, 2)
+		require.Equal(t, "auto-model-a", p.Models[0].ID)
+		require.Equal(t, "auto-model-b", p.Models[1].ID)
+	})
+
+	t.Run("custom provider with unsupported type is removed", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "https://api.custom.com/v1",
+					Type:    "unsupported",
+					Models: []catwalk.Model{{
+						ID: "test-model",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 0)
+		_, exists := cfg.Providers.Get("custom")
+		require.False(t, exists)
+	})
+
+	t.Run("valid custom provider is kept and ID is set", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "https://api.custom.com/v1",
+					Type:    catwalk.TypeOpenAI,
+					Models: []catwalk.Model{{
+						ID: "test-model",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 1)
+		customProvider, exists := cfg.Providers.Get("custom")
+		require.True(t, exists)
+		require.Equal(t, "custom", customProvider.ID)
+		require.Equal(t, "test-key", customProvider.APIKey)
+		require.Equal(t, "https://api.custom.com/v1", customProvider.BaseURL)
+	})
+
+	t.Run("custom anthropic provider is supported", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom-anthropic": {
+					APIKey:  "test-key",
+					BaseURL: "https://api.anthropic.com/v1",
+					Type:    catwalk.TypeAnthropic,
+					Models: []catwalk.Model{{
+						ID: "claude-3-sonnet",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 1)
+		customProvider, exists := cfg.Providers.Get("custom-anthropic")
+		require.True(t, exists)
+		require.Equal(t, "custom-anthropic", customProvider.ID)
+		require.Equal(t, "test-key", customProvider.APIKey)
+		require.Equal(t, "https://api.anthropic.com/v1", customProvider.BaseURL)
+		require.Equal(t, catwalk.TypeAnthropic, customProvider.Type)
+	})
+
+	t.Run("disabled custom provider is removed", func(t *testing.T) {
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "https://api.custom.com/v1",
+					Type:    catwalk.TypeOpenAI,
+					Disable: true,
+					Models: []catwalk.Model{{
+						ID: "test-model",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 0)
+		_, exists := cfg.Providers.Get("custom")
+		require.False(t, exists)
+	})
+}
+
+func TestConfig_configureProvidersEnhancedCredentialValidation(t *testing.T) {
+	t.Run("VertexAI provider removed when credentials missing with existing config", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:          catwalk.InferenceProviderVertexAI,
+				APIKey:      "",
+				APIEndpoint: "",
+				Models: []catwalk.Model{{
+					ID: "gemini-pro",
+				}},
+			},
+		}
+
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"vertexai": {
+					BaseURL: "custom-url",
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{
+			"GOOGLE_GENAI_USE_VERTEXAI": "false",
+		})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 0)
+		_, exists := cfg.Providers.Get("vertexai")
+		require.False(t, exists)
+	})
+
+	t.Run("Bedrock provider removed when AWS credentials missing with existing config", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:          catwalk.InferenceProviderBedrock,
+				APIKey:      "",
+				APIEndpoint: "",
+				Models: []catwalk.Model{{
+					ID: "anthropic.claude-sonnet-4-20250514-v1:0",
+				}},
+			},
+		}
+
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"bedrock": {
+					BaseURL: "custom-url",
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 0)
+		_, exists := cfg.Providers.Get("bedrock")
+		require.False(t, exists)
+	})
+
+	t.Run("provider removed when API key missing with existing config", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:          "openai",
+				APIKey:      "$MISSING_API_KEY",
+				APIEndpoint: "https://api.openai.com/v1",
+				Models: []catwalk.Model{{
+					ID: "test-model",
+				}},
+			},
+		}
+
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"openai": {
+					BaseURL: "custom-url",
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 0)
+		_, exists := cfg.Providers.Get("openai")
+		require.False(t, exists)
+	})
+
+	t.Run("known provider should still be added if the endpoint is missing the client will use default endpoints", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:          "openai",
+				APIKey:      "$OPENAI_API_KEY",
+				APIEndpoint: "$MISSING_ENDPOINT",
+				Models: []catwalk.Model{{
+					ID: "test-model",
+				}},
+			},
+		}
+
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"openai": {
+					APIKey: "test-key",
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{
+			"OPENAI_API_KEY": "test-key",
+		})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		require.Equal(t, cfg.Providers.Len(), 1)
+		_, exists := cfg.Providers.Get("openai")
+		require.True(t, exists)
+	})
+}
+
+func TestConfig_defaultModelSelection(t *testing.T) {
+	t.Run("default behavior uses the default models for given provider", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "abc",
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "small-model",
+						DefaultMaxTokens: 500,
+					},
+				},
+			},
+		}
+
+		cfg := &Config{}
+		cfg.setDefaults("/tmp", "")
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		large, small, err := cfg.defaultModelSelection(knownProviders)
+		require.NoError(t, err)
+		require.Equal(t, "large-model", large.Model)
+		require.Equal(t, "openai", large.Provider)
+		require.Equal(t, int64(1000), large.MaxTokens)
+		require.Equal(t, "small-model", small.Model)
+		require.Equal(t, "openai", small.Provider)
+		require.Equal(t, int64(500), small.MaxTokens)
+	})
+	t.Run("should error if no providers configured", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "$MISSING_KEY",
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "small-model",
+						DefaultMaxTokens: 500,
+					},
+				},
+			},
+		}
+
+		cfg := &Config{}
+		cfg.setDefaults("/tmp", "")
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		_, _, err = cfg.defaultModelSelection(knownProviders)
+		require.Error(t, err)
+	})
+	t.Run("should not error if model is missing", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "abc",
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "not-large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "small-model",
+						DefaultMaxTokens: 500,
+					},
+				},
+			},
+		}
+
+		cfg := &Config{}
+		cfg.setDefaults("/tmp", "")
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+		_, _, err = cfg.defaultModelSelection(knownProviders)
+		require.NoError(t, err)
+	})
+
+	t.Run("should configure the default models with a custom provider", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "$MISSING", // will not be included in the config
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "not-large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "small-model",
+						DefaultMaxTokens: 500,
+					},
+				},
+			},
+		}
+
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "https://api.custom.com/v1",
+					Models: []catwalk.Model{
+						{
+							ID:               "model",
+							DefaultMaxTokens: 600,
+						},
+					},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+		large, small, err := cfg.defaultModelSelection(knownProviders)
+		require.NoError(t, err)
+		require.Equal(t, "model", large.Model)
+		require.Equal(t, "custom", large.Provider)
+		require.Equal(t, int64(600), large.MaxTokens)
+		require.Equal(t, "model", small.Model)
+		require.Equal(t, "custom", small.Provider)
+		require.Equal(t, int64(600), small.MaxTokens)
+	})
+
+	t.Run("should fail if no model configured", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "$MISSING", // will not be included in the config
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "not-large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "small-model",
+						DefaultMaxTokens: 500,
+					},
+				},
+			},
+		}
+
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "https://api.custom.com/v1",
+					Models:  []catwalk.Model{},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+		_, _, err = cfg.defaultModelSelection(knownProviders)
+		require.Error(t, err)
+	})
+	t.Run("should use the default provider first", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "set",
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "small-model",
+						DefaultMaxTokens: 500,
+					},
+				},
+			},
+		}
+
+		cfg := &Config{
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"custom": {
+					APIKey:  "test-key",
+					BaseURL: "https://api.custom.com/v1",
+					Models: []catwalk.Model{
+						{
+							ID:               "large-model",
+							DefaultMaxTokens: 1000,
+						},
+					},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+		large, small, err := cfg.defaultModelSelection(knownProviders)
+		require.NoError(t, err)
+		require.Equal(t, "large-model", large.Model)
+		require.Equal(t, "openai", large.Provider)
+		require.Equal(t, int64(1000), large.MaxTokens)
+		require.Equal(t, "small-model", small.Model)
+		require.Equal(t, "openai", small.Provider)
+		require.Equal(t, int64(500), small.MaxTokens)
+	})
+}
+
+func TestConfig_configureProvidersDisableDefaultProviders(t *testing.T) {
+	t.Run("when enabled, ignores all default providers and requires full specification", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:          "openai",
+				APIKey:      "$OPENAI_API_KEY",
+				APIEndpoint: "https://api.openai.com/v1",
+				Models: []catwalk.Model{{
+					ID: "gpt-4",
+				}},
+			},
+		}
+
+		// User references openai but doesn't fully specify it (no base_url, no
+		// models). This should be rejected because disable_default_providers
+		// treats all providers as custom.
+		cfg := &Config{
+			Options: &Options{
+				DisableDefaultProviders: true,
+			},
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"openai": {
+					APIKey: "$OPENAI_API_KEY",
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{
+			"OPENAI_API_KEY": "test-key",
+		})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.ErrorContains(t, err, "no custom providers")
+
+		// openai should NOT be present because it lacks base_url and models.
+		require.Equal(t, 0, cfg.Providers.Len())
+		_, exists := cfg.Providers.Get("openai")
+		require.False(t, exists, "openai should not be present without full specification")
+	})
+
+	t.Run("when enabled, fully specified providers work", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:          "openai",
+				APIKey:      "$OPENAI_API_KEY",
+				APIEndpoint: "https://api.openai.com/v1",
+				Models: []catwalk.Model{{
+					ID: "gpt-4",
+				}},
+			},
+		}
+
+		// User fully specifies their provider.
+		cfg := &Config{
+			Options: &Options{
+				DisableDefaultProviders: true,
+			},
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"my-llm": {
+					APIKey:  "$MY_API_KEY",
+					BaseURL: "https://my-llm.example.com/v1",
+					Models: []catwalk.Model{{
+						ID: "my-model",
+					}},
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{
+			"MY_API_KEY":     "test-key",
+			"OPENAI_API_KEY": "test-key",
+		})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		// Only fully specified provider should be present.
+		require.Equal(t, 1, cfg.Providers.Len())
+		provider, exists := cfg.Providers.Get("my-llm")
+		require.True(t, exists, "my-llm should be present")
+		require.Equal(t, "https://my-llm.example.com/v1", provider.BaseURL)
+		require.Len(t, provider.Models, 1)
+
+		// Default openai should NOT be present.
+		_, exists = cfg.Providers.Get("openai")
+		require.False(t, exists, "openai should not be present")
+	})
+
+	t.Run("when disabled, includes all known providers with valid credentials", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:          "openai",
+				APIKey:      "$OPENAI_API_KEY",
+				APIEndpoint: "https://api.openai.com/v1",
+				Models: []catwalk.Model{{
+					ID: "gpt-4",
+				}},
+			},
+			{
+				ID:          "anthropic",
+				APIKey:      "$ANTHROPIC_API_KEY",
+				APIEndpoint: "https://api.anthropic.com/v1",
+				Models: []catwalk.Model{{
+					ID: "claude-3",
+				}},
+			},
+		}
+
+		// User only configures openai, both API keys are available, but option
+		// is disabled.
+		cfg := &Config{
+			Options: &Options{
+				DisableDefaultProviders: false,
+			},
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"openai": {
+					APIKey: "$OPENAI_API_KEY",
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{
+			"OPENAI_API_KEY":    "test-key",
+			"ANTHROPIC_API_KEY": "test-key",
+		})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		// Both providers should be present.
+		require.Equal(t, 2, cfg.Providers.Len())
+		_, exists := cfg.Providers.Get("openai")
+		require.True(t, exists, "openai should be present")
+		_, exists = cfg.Providers.Get("anthropic")
+		require.True(t, exists, "anthropic should be present")
+	})
+
+	t.Run("when enabled, provider missing models attempts discovery but still triggers no-custom-providers error", func(t *testing.T) {
+		cfg := &Config{
+			Options: &Options{
+				DisableDefaultProviders: true,
+			},
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"my-llm": {
+					APIKey:  "test-key",
+					BaseURL: "https://my-llm.example.com/v1",
+					Models:  []catwalk.Model{}, // No models.
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.ErrorContains(t, err, "no custom providers")
+
+		// Discovery fails (unreachable URL) so provider is removed.
+		require.Equal(t, 0, cfg.Providers.Len())
+	})
+
+	t.Run("when enabled, provider missing base_url is rejected", func(t *testing.T) {
+		cfg := &Config{
+			Options: &Options{
+				DisableDefaultProviders: true,
+			},
+			Providers: csync.NewMapFrom(map[string]ProviderConfig{
+				"my-llm": {
+					APIKey: "test-key",
+					Models: []catwalk.Model{{ID: "model"}},
+					// No BaseURL.
+				},
+			}),
+		}
+		cfg.setDefaults("/tmp", "")
+
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, []catwalk.Provider{})
+		require.ErrorContains(t, err, "no custom providers")
+
+		// Provider should be rejected for missing base_url.
+		require.Equal(t, 0, cfg.Providers.Len())
+	})
+}
+
+func TestConfig_setDefaultsDisableDefaultProvidersEnvVar(t *testing.T) {
+	t.Run("sets option from environment variable", func(t *testing.T) {
+		t.Setenv("CRUSH_DISABLE_DEFAULT_PROVIDERS", "true")
+
+		cfg := &Config{}
+		cfg.setDefaults("/tmp", "")
+
+		require.True(t, cfg.Options.DisableDefaultProviders)
+	})
+
+	t.Run("does not override when env var is not set", func(t *testing.T) {
+		cfg := &Config{
+			Options: &Options{
+				DisableDefaultProviders: true,
+			},
+		}
+		cfg.setDefaults("/tmp", "")
+
+		require.True(t, cfg.Options.DisableDefaultProviders)
+	})
+}
+
+func TestConfig_configureSelectedModels(t *testing.T) {
+	t.Run("reload mode should not persist fallback defaults", func(t *testing.T) {
+		dir := t.TempDir()
+		globalPath := filepath.Join(dir, "crush.json")
+		require.NoError(t, os.WriteFile(globalPath, []byte(`{"models":{"large":{"provider":"ghost","model":"missing"}}}`), 0o600))
+
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "abc",
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{ID: "large-model", DefaultMaxTokens: 1000},
+					{ID: "small-model", DefaultMaxTokens: 500},
+				},
+			},
+		}
+
+		cfg := &Config{
+			Models: map[SelectedModelType]SelectedModel{
+				SelectedModelTypeLarge: {Provider: "ghost", Model: "missing"},
+			},
+		}
+		cfg.setDefaults(dir, "")
+		store := &ConfigStore{config: cfg, globalDataPath: globalPath}
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), store, env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		resolved, resolveErr := resolveSelectedModels(cfg, knownProviders)
+		require.NoError(t, resolveErr)
+		cfg.Models[SelectedModelTypeLarge] = resolved.Large
+		cfg.Models[SelectedModelTypeSmall] = resolved.Small
+
+		// In-memory falls back to default.
+		require.True(t, resolved.LargeFallback)
+		require.Equal(t, "openai", cfg.Models[SelectedModelTypeLarge].Provider)
+		require.Equal(t, "large-model", cfg.Models[SelectedModelTypeLarge].Model)
+
+		// Disk remains unchanged (resolveSelectedModels never persists).
+		data, readErr := os.ReadFile(globalPath)
+		require.NoError(t, readErr)
+		require.Contains(t, string(data), `"provider":"ghost"`)
+		require.Contains(t, string(data), `"model":"missing"`)
+	})
+	t.Run("should override defaults", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "abc",
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "larger-model",
+						DefaultMaxTokens: 2000,
+					},
+					{
+						ID:               "large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "small-model",
+						DefaultMaxTokens: 500,
+					},
+				},
+			},
+		}
+
+		cfg := &Config{
+			Models: map[SelectedModelType]SelectedModel{
+				"large": {
+					Model: "larger-model",
+				},
+			},
+		}
+		cfg.setDefaults("/tmp", "")
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		resolved, resolveErr := resolveSelectedModels(cfg, knownProviders)
+		require.NoError(t, resolveErr)
+		cfg.Models[SelectedModelTypeLarge] = resolved.Large
+		cfg.Models[SelectedModelTypeSmall] = resolved.Small
+		large := cfg.Models[SelectedModelTypeLarge]
+		small := cfg.Models[SelectedModelTypeSmall]
+		require.Equal(t, "larger-model", large.Model)
+		require.Equal(t, "openai", large.Provider)
+		require.Equal(t, int64(2000), large.MaxTokens)
+		require.Equal(t, "small-model", small.Model)
+		require.Equal(t, "openai", small.Provider)
+		require.Equal(t, int64(500), small.MaxTokens)
+	})
+	t.Run("should be possible to use multiple providers", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "abc",
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "small-model",
+						DefaultMaxTokens: 500,
+					},
+				},
+			},
+			{
+				ID:                  "anthropic",
+				APIKey:              "abc",
+				DefaultLargeModelID: "a-large-model",
+				DefaultSmallModelID: "a-small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "a-large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "a-small-model",
+						DefaultMaxTokens: 200,
+					},
+				},
+			},
+		}
+
+		cfg := &Config{
+			Models: map[SelectedModelType]SelectedModel{
+				"small": {
+					Model:     "a-small-model",
+					Provider:  "anthropic",
+					MaxTokens: 300,
+				},
+			},
+		}
+		cfg.setDefaults("/tmp", "")
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		resolved, resolveErr := resolveSelectedModels(cfg, knownProviders)
+		require.NoError(t, resolveErr)
+		cfg.Models[SelectedModelTypeLarge] = resolved.Large
+		cfg.Models[SelectedModelTypeSmall] = resolved.Small
+		large := cfg.Models[SelectedModelTypeLarge]
+		small := cfg.Models[SelectedModelTypeSmall]
+		require.Equal(t, "large-model", large.Model)
+		require.Equal(t, "openai", large.Provider)
+		require.Equal(t, int64(1000), large.MaxTokens)
+		require.Equal(t, "a-small-model", small.Model)
+		require.Equal(t, "anthropic", small.Provider)
+		require.Equal(t, int64(300), small.MaxTokens)
+	})
+
+	t.Run("should override the max tokens only", func(t *testing.T) {
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "abc",
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{
+						ID:               "large-model",
+						DefaultMaxTokens: 1000,
+					},
+					{
+						ID:               "small-model",
+						DefaultMaxTokens: 500,
+					},
+				},
+			},
+		}
+
+		cfg := &Config{
+			Models: map[SelectedModelType]SelectedModel{
+				"large": {
+					MaxTokens: 100,
+				},
+			},
+		}
+		cfg.setDefaults("/tmp", "")
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		resolved, resolveErr := resolveSelectedModels(cfg, knownProviders)
+		require.NoError(t, resolveErr)
+		cfg.Models[SelectedModelTypeLarge] = resolved.Large
+		cfg.Models[SelectedModelTypeSmall] = resolved.Small
+		large := cfg.Models[SelectedModelTypeLarge]
+		require.Equal(t, "large-model", large.Model)
+		require.Equal(t, "openai", large.Provider)
+		require.Equal(t, int64(100), large.MaxTokens)
+	})
+	t.Run("resolve and persist fallback under writeMu does not deadlock", func(t *testing.T) {
+		dir := t.TempDir()
+		globalPath := filepath.Join(dir, "crush.json")
+		require.NoError(t, os.WriteFile(globalPath, []byte(`{}`), 0o600))
+
+		knownProviders := []catwalk.Provider{
+			{
+				ID:                  "openai",
+				APIKey:              "abc",
+				DefaultLargeModelID: "large-model",
+				DefaultSmallModelID: "small-model",
+				Models: []catwalk.Model{
+					{ID: "large-model", DefaultMaxTokens: 1000},
+					{ID: "small-model", DefaultMaxTokens: 500},
+				},
+			},
+		}
+
+		cfg := &Config{
+			Models: map[SelectedModelType]SelectedModel{
+				SelectedModelTypeLarge: {Provider: "openai", Model: "this-model-does-not-exist"},
+				SelectedModelTypeSmall: {Provider: "openai", Model: "also-does-not-exist"},
+			},
+		}
+		cfg.setDefaults(dir, "")
+		store := &ConfigStore{config: cfg, globalDataPath: globalPath}
+		env := env.NewFromMap(map[string]string{})
+		resolver := NewShellVariableResolver(env)
+		err := cfg.configureProviders(context.Background(), store, env, resolver, knownProviders)
+		require.NoError(t, err)
+
+		// Simulate the Load path: resolve (pure), then persist fallbacks
+		// under writeMu using updateLocked. Before the refactor, the
+		// combined configureSelectedModels(persist=true) self-deadlocked
+		// because UpdatePreferredModel re-acquired writeMu.
+		done := make(chan error, 1)
+		go func() {
+			resolved, resolveErr := resolveSelectedModels(cfg, knownProviders)
+			if resolveErr != nil {
+				done <- resolveErr
+				return
+			}
+			cfg.Models[SelectedModelTypeLarge] = resolved.Large
+			cfg.Models[SelectedModelTypeSmall] = resolved.Small
+
+			store.writeMu.Lock()
+			defer store.writeMu.Unlock()
+			if resolved.LargeFallback {
+				if err := store.updateLocked(ScopeGlobal, func(c *Config) map[string]any {
+					return store.updatePreferredModelFields(c, SelectedModelTypeLarge, resolved.Large)
+				}); err != nil {
+					done <- err
+					return
+				}
+			}
+			if resolved.SmallFallback {
+				if err := store.updateLocked(ScopeGlobal, func(c *Config) map[string]any {
+					return store.updatePreferredModelFields(c, SelectedModelTypeSmall, resolved.Small)
+				}); err != nil {
+					done <- err
+					return
+				}
+			}
+			done <- nil
+		}()
+
+		select {
+		case err := <-done:
+			require.NoError(t, err)
+			// Should have fallen back to defaults.
+			require.Equal(t, "large-model", cfg.Models[SelectedModelTypeLarge].Model)
+			require.Equal(t, "small-model", cfg.Models[SelectedModelTypeSmall].Model)
+		case <-time.After(5 * time.Second):
+			t.Fatal("resolve + persist deadlocked under writeMu")
+		}
+	})
+}
+
+func TestConfig_configureProviders_HyperAPIKeyFromEnv(t *testing.T) {
+	// Test that HYPER_API_KEY environment variable works without config
+	knownProviders := []catwalk.Provider{
+		{
+			ID:                  "hyper",
+			APIKey:              "", // No API key in provider definition
+			DefaultLargeModelID: "large-model",
+			DefaultSmallModelID: "small-model",
+			Models: []catwalk.Model{
+				{
+					ID:               "large-model",
+					DefaultMaxTokens: 1000,
+				},
+				{
+					ID:               "small-model",
+					DefaultMaxTokens: 500,
+				},
+			},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+	env := env.NewFromMap(map[string]string{
+		"HYPER_API_KEY": "env-api-key",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	require.Equal(t, 1, cfg.Providers.Len())
+
+	// Verify Hyper provider is configured with the env var API key
+	pc, ok := cfg.Providers.Get("hyper")
+	require.True(t, ok, "Hyper provider should be configured")
+	require.Equal(t, "env-api-key", pc.APIKey)
+	require.Equal(t, "env-api-key", pc.APIKeyTemplate)
+}
+
+func TestConfig_configureProviders_HyperAPIKeyFromConfigOverrides(t *testing.T) {
+	// Test that config API key takes precedence when HYPER_API_KEY is also set
+	knownProviders := []catwalk.Provider{
+		{
+			ID:                  "hyper",
+			APIKey:              "provider-api-key",
+			DefaultLargeModelID: "large-model",
+			DefaultSmallModelID: "small-model",
+			Models: []catwalk.Model{
+				{
+					ID:               "large-model",
+					DefaultMaxTokens: 1000,
+				},
+				{
+					ID:               "small-model",
+					DefaultMaxTokens: 500,
+				},
+			},
+		},
+	}
+
+	// User has Hyper configured with an API key
+	cfg := &Config{
+		Providers: csync.NewMapFrom(map[string]ProviderConfig{
+			"hyper": {
+				APIKey: "config-api-key",
+			},
+		}),
+	}
+	cfg.setDefaults("/tmp", "")
+
+	// But they also have HYPER_API_KEY set - env var should take precedence
+	env := env.NewFromMap(map[string]string{
+		"HYPER_API_KEY": "env-api-key",
+	})
+	resolver := NewShellVariableResolver(env)
+	err := cfg.configureProviders(context.Background(), testStore(cfg), env, resolver, knownProviders)
+	require.NoError(t, err)
+	require.Equal(t, 1, cfg.Providers.Len())
+
+	// Verify env var takes precedence (as per requirements)
+	pc, ok := cfg.Providers.Get("hyper")
+	require.True(t, ok, "Hyper provider should be configured")
+	require.Equal(t, "env-api-key", pc.APIKey)
+}
+
+// TestConfig_configureProviders_ProviderHeaderResolveError verifies
+// that a failing $(cmd) in a provider header fails the provider load
+// with a clear message that names the offending header. Provider
+// headers share the MCP error contract.
+func TestConfig_configureProviders_ProviderHeaderResolveError(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$OPENAI_API_KEY",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models:      []catwalk.Model{{ID: "test-model"}},
+		},
+	}
+
+	cfg := &Config{
+		Providers: csync.NewMapFrom(map[string]ProviderConfig{
+			"openai": {
+				ExtraHeaders: map[string]string{
+					// Failing $(...) — inner command exits 1. Must
+					// propagate as an error, not a silent truncation.
+					"X-Broken": "$(false)",
+				},
+			},
+		}),
+	}
+	cfg.setDefaults("/tmp", "")
+
+	testEnv := env.NewFromMap(map[string]string{
+		"OPENAI_API_KEY": "test-key",
+		"PATH":           os.Getenv("PATH"),
+	})
+	resolver := NewShellVariableResolver(testEnv)
+
+	err := cfg.configureProviders(context.Background(), testStore(cfg), testEnv, resolver, knownProviders)
+	require.Error(t, err, "failing $(cmd) in a header must fail the provider load")
+	require.Contains(t, err.Error(), "X-Broken", "error must name the offending header")
+}
+
+// TestConfig_configureProviders_CatwalkDefaultWithUnsetVarLoads
+// verifies that a Catwalk-style default header like
+// "OpenAI-Organization": "$OPENAI_ORG_ID" loads cleanly under lenient
+// nounset (unset → "" → header dropped), and does not fail the load
+// or leave the literal template on the wire.
+func TestConfig_configureProviders_CatwalkDefaultWithUnsetVarLoads(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$OPENAI_API_KEY",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models:      []catwalk.Model{{ID: "test-model"}},
+			DefaultHeaders: map[string]string{
+				"OpenAI-Organization": "$OPENAI_ORG_ID",
+			},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+
+	testEnv := env.NewFromMap(map[string]string{
+		"OPENAI_API_KEY": "test-key",
+		"PATH":           os.Getenv("PATH"),
+	})
+	resolver := NewShellVariableResolver(testEnv)
+
+	err := cfg.configureProviders(context.Background(), testStore(cfg), testEnv, resolver, knownProviders)
+	require.NoError(t, err, "optional env-gated header must not fail the load")
+
+	pc, ok := cfg.Providers.Get("openai")
+	require.True(t, ok, "openai provider must still be configured")
+	_, present := pc.ExtraHeaders["OpenAI-Organization"]
+	require.False(t, present, "header whose value resolves to empty must be absent")
+}
+
+// TestConfig_configureProviders_LiteralEmptyHeaderDropped pins design
+// decision #18 for the literal case: a user-authored
+// "X-Custom": "" in extra_headers is absent from the resolved map.
+// Applies to both known- and custom-provider paths; this test
+// exercises the custom-provider loop.
+func TestConfig_configureProviders_LiteralEmptyHeaderDropped(t *testing.T) {
+	cfg := &Config{
+		Providers: csync.NewMapFrom(map[string]ProviderConfig{
+			"my-llm": {
+				APIKey:  "test-key",
+				BaseURL: "https://my-llm.example.com/v1",
+				Type:    catwalk.TypeOpenAI,
+				Models:  []catwalk.Model{{ID: "m"}},
+				ExtraHeaders: map[string]string{
+					"X-Custom": "",
+					"X-Kept":   "present",
+				},
+			},
+		}),
+	}
+	cfg.setDefaults("/tmp", "")
+
+	testEnv := env.NewFromMap(map[string]string{
+		"PATH": os.Getenv("PATH"),
+	})
+	resolver := NewShellVariableResolver(testEnv)
+
+	err := cfg.configureProviders(context.Background(), testStore(cfg), testEnv, resolver, []catwalk.Provider{})
+	require.NoError(t, err)
+
+	pc, ok := cfg.Providers.Get("my-llm")
+	require.True(t, ok)
+	_, present := pc.ExtraHeaders["X-Custom"]
+	require.False(t, present, "literal empty-string header must be dropped")
+	require.Equal(t, "present", pc.ExtraHeaders["X-Kept"])
+}
+
+// TestConfig_configureProviders_EchoEmptyHeaderDropped pins design
+// decision #18 for the non-failing empty case: $(echo) exits 0 with
+// empty output, resolves cleanly to "", and must be dropped the same
+// way an unset bare $VAR is. Exercises the known-provider loop.
+func TestConfig_configureProviders_EchoEmptyHeaderDropped(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$OPENAI_API_KEY",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models:      []catwalk.Model{{ID: "test-model"}},
+			DefaultHeaders: map[string]string{
+				"X-Empty": "$(echo)",
+				"X-Kept":  "present",
+			},
+		},
+	}
+
+	cfg := &Config{}
+	cfg.setDefaults("/tmp", "")
+
+	testEnv := env.NewFromMap(map[string]string{
+		"OPENAI_API_KEY": "test-key",
+		"PATH":           os.Getenv("PATH"),
+	})
+	resolver := NewShellVariableResolver(testEnv)
+
+	err := cfg.configureProviders(context.Background(), testStore(cfg), testEnv, resolver, knownProviders)
+	require.NoError(t, err)
+
+	pc, ok := cfg.Providers.Get("openai")
+	require.True(t, ok)
+	_, present := pc.ExtraHeaders["X-Empty"]
+	require.False(t, present, "$(echo) → empty → header must be dropped")
+	require.Equal(t, "present", pc.ExtraHeaders["X-Kept"])
+}
+
+// TestConfig_configureProviders_UnsetAPIKeySkipsProvider verifies that
+// under the lenient-nounset shell resolver, $UNSET_API_KEY expands to
+// ("", nil) rather than ("", err), and the existing
+// `v == "" || err != nil` skip path at load.go:331 still drops the
+// provider. The slog.Warn line is emitted on the same
+// path but is not asserted here — internal/config/load_test.go's
+// TestMain replaces the default slog handler with an io.Discard
+// writer, so capturing that log line would require mid-test handler
+// swapping and a sync.Mutex dance that adds more flake surface than
+// signal. The observable outcome (provider absent from the map) is
+// what downstream code — model picker, agent wiring — actually reads,
+// so that's what we pin.
+func TestConfig_configureProviders_UnsetAPIKeySkipsProvider(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$SOMETHING_UNSET",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models:      []catwalk.Model{{ID: "test-model"}},
+		},
+	}
+
+	// Existing user config for this known provider so the load.go:332
+	// `if configExists` branch fires and actually calls Providers.Del.
+	// Without it the provider was never in the map to begin with and
+	// the test would pass trivially.
+	cfg := &Config{
+		Providers: csync.NewMapFrom(map[string]ProviderConfig{
+			"openai": {BaseURL: "custom-url"},
+		}),
+	}
+	cfg.setDefaults("/tmp", "")
+
+	testEnv := env.NewFromMap(map[string]string{
+		"PATH": os.Getenv("PATH"),
+	})
+	resolver := NewShellVariableResolver(testEnv)
+
+	err := cfg.configureProviders(context.Background(), testStore(cfg), testEnv, resolver, knownProviders)
+	require.NoError(t, err, "skip path must not surface as a load error")
+
+	require.Equal(t, 0, cfg.Providers.Len(), "provider with unset API key must be skipped")
+	_, exists := cfg.Providers.Get("openai")
+	require.False(t, exists)
+}
+
+// TestConfig_configureProviders_FailingAPIKeyCmdSkipsProvider pins
+// that the two failure modes for APIKey — ("", nil) from an unset var
+// under lenient nounset and ("", err) from a failing $(cmd) — are
+// equivalent for the skip outcome at load.go:331. The `v == "" ||
+// err != nil` check fires on either branch; this test locks in that
+// equivalence so a future refactor that splits the check into two
+// paths doesn't accidentally start propagating $(false) as a load
+// error while keeping unset-var as a silent skip (or vice versa).
+func TestConfig_configureProviders_FailingAPIKeyCmdSkipsProvider(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          "openai",
+			APIKey:      "$(false)",
+			APIEndpoint: "https://api.openai.com/v1",
+			Models:      []catwalk.Model{{ID: "test-model"}},
+		},
+	}
+
+	cfg := &Config{
+		Providers: csync.NewMapFrom(map[string]ProviderConfig{
+			"openai": {BaseURL: "custom-url"},
+		}),
+	}
+	cfg.setDefaults("/tmp", "")
+
+	testEnv := env.NewFromMap(map[string]string{
+		"PATH": os.Getenv("PATH"),
+	})
+	resolver := NewShellVariableResolver(testEnv)
+
+	err := cfg.configureProviders(context.Background(), testStore(cfg), testEnv, resolver, knownProviders)
+	require.NoError(t, err, "failing $(cmd) in API key must skip provider, not fail load")
+
+	require.Equal(t, 0, cfg.Providers.Len(), "provider with failing $(cmd) API key must be skipped")
+	_, exists := cfg.Providers.Get("openai")
+	require.False(t, exists)
+}
+
+// TestConfig_configureProviders_UnsetAzureEndpointSkipsProvider pins
+// the same contract on the Azure path at load.go:287 — APIEndpoint is
+// the field that gates Azure and goes through the same
+// `v == "" || err != nil` skip check. Covered here so both branches
+// of the shared skip pattern (APIKey default path and APIEndpoint
+// Azure path) are tested; a future refactor that unifies them can
+// rely on these two tests to catch drift.
+func TestConfig_configureProviders_UnsetAzureEndpointSkipsProvider(t *testing.T) {
+	knownProviders := []catwalk.Provider{
+		{
+			ID:          catwalk.InferenceProviderAzure,
+			APIKey:      "test-key",
+			APIEndpoint: "$UNSET_AZURE_ENDPOINT",
+			Models:      []catwalk.Model{{ID: "test-model"}},
+		},
+	}
+
+	cfg := &Config{
+		Providers: csync.NewMapFrom(map[string]ProviderConfig{
+			"azure": {BaseURL: ""},
+		}),
+	}
+	cfg.setDefaults("/tmp", "")
+
+	testEnv := env.NewFromMap(map[string]string{
+		"PATH": os.Getenv("PATH"),
+	})
+	resolver := NewShellVariableResolver(testEnv)
+
+	err := cfg.configureProviders(context.Background(), testStore(cfg), testEnv, resolver, knownProviders)
+	require.NoError(t, err)
+
+	require.Equal(t, 0, cfg.Providers.Len(), "azure provider with unset endpoint must be skipped")
+	_, exists := cfg.Providers.Get("azure")
+	require.False(t, exists)
+}
+
+func TestConfig_LoadFromBytes_Env(t *testing.T) {
+	data := []byte(`{"env": {"AWS_PROFILE": "my-profile", "AWS_REGION": "us-west-2"}}`)
+
+	loadedConfig, err := loadFromBytes([][]byte{data})
+
+	require.NoError(t, err)
+	require.NotNil(t, loadedConfig.Env)
+	require.Equal(t, "my-profile", loadedConfig.Env["AWS_PROFILE"])
+	require.Equal(t, "us-west-2", loadedConfig.Env["AWS_REGION"])
+}
+
+func TestConfig_LoadFromBytes_EnvMerge(t *testing.T) {
+	data1 := []byte(`{"env": {"AWS_PROFILE": "first", "AWS_REGION": "us-east-1"}}`)
+	data2 := []byte(`{"env": {"AWS_PROFILE": "second"}}`)
+
+	loadedConfig, err := loadFromBytes([][]byte{data1, data2})
+
+	require.NoError(t, err)
+	require.NotNil(t, loadedConfig.Env)
+	require.Equal(t, "second", loadedConfig.Env["AWS_PROFILE"])
+	require.Equal(t, "us-east-1", loadedConfig.Env["AWS_REGION"])
+}

internal/config/lsp_defaults_test.go

@@ -0,0 +1,35 @@
+package config
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestApplyLSPDefaults(t *testing.T) {
+	t.Parallel()
+
+	// Create a config with an LSP that should get defaults
+	config := &Config{
+		LSP: map[string]LSPConfig{
+			"gopls": {
+				Command: "gopls", // This should get defaults from powernap
+			},
+			"custom": {
+				Command:     "custom-lsp",
+				RootMarkers: []string{"custom.toml"}, // This should keep its explicit config
+			},
+		},
+	}
+
+	// Apply defaults
+	config.applyLSPDefaults()
+
+	// Check that gopls got defaults (it should have some root markers now)
+	goplsConfig := config.LSP["gopls"]
+	require.NotEmpty(t, goplsConfig.RootMarkers, "gopls should have received default root markers")
+
+	// Check that custom LSP kept its explicit config
+	customConfig := config.LSP["custom"]
+	require.Equal(t, []string{"custom.toml"}, customConfig.RootMarkers, "custom LSP should keep its explicit root markers")
+}

internal/config/openai_test.go

@@ -0,0 +1,220 @@
+package config
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"github.com/charmbracelet/crush/internal/csync"
+	"github.com/charmbracelet/crush/internal/oauth"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGetModelIncludesChatGPTModels(t *testing.T) {
+	t.Parallel()
+
+	providers := csync.NewMap[string, ProviderConfig]()
+	providers.Set("openai", ProviderConfig{
+		Models:        []catwalk.Model{{ID: "gpt-5.1"}},
+		ChatGPTModels: []catwalk.Model{{ID: "gpt-5.1-codex", Name: "GPT-5.1 Codex"}},
+	})
+	cfg := &Config{Providers: providers}
+
+	model := cfg.GetModel("openai", "gpt-5.1-codex")
+	require.NotNil(t, model)
+	require.Equal(t, "GPT-5.1 Codex", model.Name)
+
+	require.NotNil(t, cfg.GetModel("openai", "gpt-5.1"))
+	require.Nil(t, cfg.GetModel("openai", "missing"))
+}
+
+func TestTokenFields(t *testing.T) {
+	t.Parallel()
+
+	t.Run("openai keeps the api key", func(t *testing.T) {
+		t.Parallel()
+
+		fields := tokenFields("openai", &oauth.Token{AccessToken: "at"})
+		require.Contains(t, fields, "providers.openai.oauth")
+		require.NotContains(t, fields, "providers.openai.api_key")
+	})
+
+	t.Run("other providers mirror the access token", func(t *testing.T) {
+		t.Parallel()
+
+		fields := tokenFields("hyper", &oauth.Token{AccessToken: "at"})
+		require.Contains(t, fields, "providers.hyper.oauth")
+		require.Equal(t, "at", fields["providers.hyper.api_key"])
+	})
+}
+
+func TestTokenAccountIDRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	// The account ID is persisted with the token in crush.json; verify
+	// it survives the JSON round trip loadTokenFromDisk performs.
+	token := &oauth.Token{
+		AccessToken:  "at",
+		RefreshToken: "rt",
+		IDToken:      "idt",
+		AccountID:    "acct-42",
+		ExpiresIn:    3600,
+		ExpiresAt:    4102444800,
+	}
+
+	data, err := json.Marshal(token)
+	require.NoError(t, err)
+
+	var restored oauth.Token
+	require.NoError(t, json.Unmarshal(data, &restored))
+	require.Equal(t, "acct-42", restored.AccountID)
+	require.Equal(t, "idt", restored.IDToken)
+	require.Equal(t, "rt", restored.RefreshToken)
+}
+
+// testResolver mimics the shell resolver for templates: variables
+// resolve to empty when unset, literals pass through.
+type testResolver struct{}
+
+func (testResolver) ResolveValue(v string) (string, error) {
+	if strings.HasPrefix(v, "$") {
+		return "", nil
+	}
+	return v, nil
+}
+
+func TestHasAPIKey(t *testing.T) {
+	t.Parallel()
+
+	t.Run("empty", func(t *testing.T) {
+		t.Parallel()
+
+		require.False(t, (&ProviderConfig{}).HasAPIKey(testResolver{}))
+	})
+
+	t.Run("literal key", func(t *testing.T) {
+		t.Parallel()
+
+		require.True(t, (&ProviderConfig{APIKey: "sk-key"}).HasAPIKey(testResolver{}))
+	})
+
+	t.Run("unresolved template", func(t *testing.T) {
+		t.Parallel()
+
+		require.False(t, (&ProviderConfig{APIKey: "$OPENAI_API_KEY"}).HasAPIKey(testResolver{}))
+	})
+}
+
+// TestSetProviderAPIKeyOpenAIIsEitherOr proves the OpenAI provider holds
+// exactly one credential: a ChatGPT login retires a previously entered
+// API key, and entering an API key retires a previous ChatGPT login.
+// Copilot keeps mirroring the access token into api_key as before.
+func TestSetProviderAPIKeyOpenAIIsEitherOr(t *testing.T) {
+	// Not parallel: t.Setenv below.
+
+	// Point config discovery at the test sandbox: the write below
+	// triggers an auto-reload, which must not pick up the developer's
+	// real crush.json.
+	t.Setenv("CRUSH_GLOBAL_CONFIG", t.TempDir())
+	t.Setenv("CRUSH_GLOBAL_DATA", t.TempDir())
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+
+	token := &oauth.Token{
+		AccessToken:  "chatgpt-at",
+		RefreshToken: "chatgpt-rt",
+		ExpiresIn:    3600,
+		ExpiresAt:    time.Now().Add(time.Hour).Unix(),
+	}
+
+	newStore := func(t *testing.T, providerID string, initialConfig string) *ConfigStore {
+		t.Helper()
+		dir := t.TempDir()
+		configPath := filepath.Join(dir, "crush.json")
+		require.NoError(t, os.WriteFile(configPath, []byte(initialConfig), 0o600))
+
+		// The in-memory config mirrors what a real load would produce.
+		// SetConfigFields auto-reloads from configPath, so any state the
+		// assertions expect to survive must be on disk.
+		providers := csync.NewMap[string, ProviderConfig]()
+		require.NoError(t, json.Unmarshal([]byte(initialConfig), &struct {
+			Providers *csync.Map[string, ProviderConfig] `json:"providers"`
+		}{Providers: providers}))
+
+		return &ConfigStore{
+			config:         &Config{Providers: providers},
+			globalDataPath: configPath,
+			workingDir:     dir,
+			fetchOpenAIModels: func(context.Context, *oauth.Token) ([]catwalk.Model, error) {
+				return []catwalk.Model{{ID: "gpt-5.1-codex"}}, nil
+			},
+		}
+	}
+
+	t.Run("chatgpt login retires the api key", func(t *testing.T) {
+		store := newStore(t, "openai", `{
+			"providers": {
+				"openai": {
+					"id": "openai",
+					"api_key": "sk-keep",
+					"models": [{"id": "gpt-5.1", "name": "GPT-5.1"}]
+				}
+			}
+		}`)
+
+		require.NoError(t, store.SetProviderAPIKey(ScopeGlobal, "openai", token))
+
+		pc, ok := store.Config().Providers.Get("openai")
+		require.True(t, ok)
+		require.Empty(t, pc.APIKey, "the ChatGPT login replaces the API key")
+		require.Equal(t, token, pc.OAuthToken)
+		require.Equal(t, "gpt-5.1-codex", pc.ChatGPTModels[0].ID, "the subscription catalog lands in its own field")
+		require.Equal(t, "gpt-5.1", pc.Models[0].ID, "the API catalog is untouched")
+
+		disk, err := os.ReadFile(store.globalDataPath)
+		require.NoError(t, err)
+		require.NotContains(t, string(disk), "sk-keep", "the retired key is gone from the config file")
+		require.Contains(t, string(disk), "chatgpt-rt", "the login is persisted")
+	})
+
+	t.Run("api key retires the chatgpt login", func(t *testing.T) {
+		store := newStore(t, "openai", `{
+			"providers": {
+				"openai": {
+					"id": "openai",
+					"api_key": "",
+					"oauth": {"access_token": "old-at", "refresh_token": "old-rt"},
+					"chatgpt_models": [{"id": "gpt-5.6-luna"}]
+				}
+			}
+		}`)
+
+		require.NoError(t, store.SetProviderAPIKey(ScopeGlobal, "openai", "sk-new"))
+
+		pc, ok := store.Config().Providers.Get("openai")
+		require.True(t, ok)
+		require.Equal(t, "sk-new", pc.APIKey)
+		require.Nil(t, pc.OAuthToken, "the API key replaces the ChatGPT login")
+		require.Empty(t, pc.ChatGPTModels, "the subscription catalog goes with it")
+
+		disk, err := os.ReadFile(store.globalDataPath)
+		require.NoError(t, err)
+		require.NotContains(t, string(disk), "old-rt", "the retired login is gone from the config file")
+		require.NotContains(t, string(disk), "gpt-5.6-luna")
+	})
+
+	t.Run("copilot", func(t *testing.T) {
+		store := newStore(t, "copilot", `{"providers":{"copilot":{"id":"copilot"}}}`)
+
+		require.NoError(t, store.SetProviderAPIKey(ScopeGlobal, "copilot", token))
+
+		pc, ok := store.Config().Providers.Get("copilot")
+		require.True(t, ok)
+		require.Equal(t, "chatgpt-at", pc.APIKey, "copilot still mirrors the access token into api_key")
+		require.Equal(t, token, pc.OAuthToken)
+	})
+}

internal/config/options_request_timeout_test.go

@@ -0,0 +1,63 @@
+package config
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func ptr[T any](v T) *T { return &v }
+
+func TestOptionsGetRequestTimeout(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		options  *Options
+		expected time.Duration
+	}{
+		{
+			name:     "nil options",
+			options:  nil,
+			expected: DefaultRequestTimeout,
+		},
+		{
+			name:     "unset field",
+			options:  &Options{},
+			expected: DefaultRequestTimeout,
+		},
+		{
+			name:     "disabled",
+			options:  &Options{RequestTimeout: ptr(0)},
+			expected: 0,
+		},
+		{
+			name:     "negative disables too",
+			options:  &Options{RequestTimeout: ptr(-1)},
+			expected: 0,
+		},
+		{
+			name:     "seconds to duration",
+			options:  &Options{RequestTimeout: ptr(300)},
+			expected: 5 * time.Minute,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			require.Equal(t, tt.expected, tt.options.GetRequestTimeout())
+		})
+	}
+}
+
+func TestOptionsRequestTimeoutFromJSON(t *testing.T) {
+	t.Parallel()
+
+	var cfg Config
+	require.NoError(t, json.Unmarshal([]byte(`{"options":{"request_timeout":300}}`), &cfg))
+	require.Equal(t, 300, *cfg.Options.RequestTimeout)
+	require.Equal(t, 5*time.Minute, cfg.Options.GetRequestTimeout())
+}

internal/config/provider_empty_test.go

@@ -0,0 +1,39 @@
+package config
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"github.com/stretchr/testify/require"
+)
+
+type emptyProviderClient struct{}
+
+func (m *emptyProviderClient) GetProviders(context.Context, string) ([]catwalk.Provider, error) {
+	return []catwalk.Provider{}, nil
+}
+
+// TestCatwalkSync_GetEmptyResultFromClient tests that when the client returns
+// an empty list, we fall back to cached providers and return an error.
+func TestCatwalkSync_GetEmptyResultFromClient(t *testing.T) {
+	t.Parallel()
+
+	tmpDir := t.TempDir()
+	path := tmpDir + "/providers.json"
+
+	syncer := &catwalkSync{}
+	client := &emptyProviderClient{}
+
+	syncer.Init(client, path, true)
+
+	providers, err := syncer.Get(t.Context())
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "empty providers list from catwalk")
+	require.NotEmpty(t, providers) // Should have embedded providers as fallback.
+
+	// Check that no cache file was created for empty results.
+	_, statErr := os.Stat(path)
+	require.True(t, os.IsNotExist(statErr), "Cache file should not exist for empty results")
+}

internal/config/recent_models_test.go

@@ -0,0 +1,158 @@
+package config
+
+import (
+	"encoding/json"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// readConfigJSON reads and unmarshals the JSON config file at path.
+func readConfigJSON(t *testing.T, path string) map[string]any {
+	t.Helper()
+	baseDir := filepath.Dir(path)
+	fileName := filepath.Base(path)
+	b, err := fs.ReadFile(os.DirFS(baseDir), fileName)
+	require.NoError(t, err)
+	var out map[string]any
+	require.NoError(t, json.Unmarshal(b, &out))
+	return out
+}
+
+// readRecentModels reads the recent_models section from the config file.
+func readRecentModels(t *testing.T, path string) map[string]any {
+	t.Helper()
+	out := readConfigJSON(t, path)
+	rm, ok := out["recent_models"].(map[string]any)
+	require.True(t, ok)
+	return rm
+}
+
+// testStoreWithPath creates a ConfigStore backed by a Config for recent model tests.
+func testStoreWithPath(cfg *Config, dir string) *ConfigStore {
+	return &ConfigStore{
+		config:         cfg,
+		globalDataPath: filepath.Join(dir, "config.json"),
+	}
+}
+
+// configWithRecents builds a Config seeded with the given recent models for
+// the large type, for exercising the pure nextRecentModels helper.
+func configWithRecents(recents ...SelectedModel) *Config {
+	return &Config{
+		RecentModels: map[SelectedModelType][]SelectedModel{
+			SelectedModelTypeLarge: recents,
+		},
+	}
+}
+
+func TestNextRecentModels_AddsToFront(t *testing.T) {
+	t.Parallel()
+
+	cfg := configWithRecents()
+	updated, changed := nextRecentModels(cfg, SelectedModelTypeLarge, SelectedModel{Provider: "openai", Model: "gpt-4o"})
+	require.True(t, changed)
+	require.Equal(t, []SelectedModel{{Provider: "openai", Model: "gpt-4o"}}, updated)
+}
+
+func TestNextRecentModels_DedupeAndMoveToFront(t *testing.T) {
+	t.Parallel()
+
+	cfg := configWithRecents(
+		SelectedModel{Provider: "anthropic", Model: "claude"},
+		SelectedModel{Provider: "openai", Model: "gpt-4o"},
+	)
+	updated, changed := nextRecentModels(cfg, SelectedModelTypeLarge, SelectedModel{Provider: "openai", Model: "gpt-4o"})
+	require.True(t, changed)
+	require.Equal(t, []SelectedModel{
+		{Provider: "openai", Model: "gpt-4o"},
+		{Provider: "anthropic", Model: "claude"},
+	}, updated)
+}
+
+func TestNextRecentModels_TrimsToMax(t *testing.T) {
+	t.Parallel()
+
+	var seed []SelectedModel
+	for _, id := range []string{"m5", "m4", "m3", "m2", "m1"} {
+		seed = append(seed, SelectedModel{Provider: "p", Model: id})
+	}
+	cfg := configWithRecents(seed...)
+
+	updated, changed := nextRecentModels(cfg, SelectedModelTypeLarge, SelectedModel{Provider: "p", Model: "m6"})
+	require.True(t, changed)
+	require.Len(t, updated, maxRecentModelsPerType)
+	require.Equal(t, SelectedModel{Provider: "p", Model: "m6"}, updated[0])
+	require.Equal(t, SelectedModel{Provider: "p", Model: "m2"}, updated[maxRecentModelsPerType-1])
+}
+
+func TestNextRecentModels_SkipsEmptyValues(t *testing.T) {
+	t.Parallel()
+
+	cfg := configWithRecents()
+	_, changed := nextRecentModels(cfg, SelectedModelTypeLarge, SelectedModel{Provider: "", Model: "m"})
+	require.False(t, changed)
+	_, changed = nextRecentModels(cfg, SelectedModelTypeLarge, SelectedModel{Provider: "p", Model: ""})
+	require.False(t, changed)
+}
+
+func TestNextRecentModels_NoChangeWhenAlreadyFront(t *testing.T) {
+	t.Parallel()
+
+	entry := SelectedModel{Provider: "openai", Model: "gpt-4o"}
+	cfg := configWithRecents(entry)
+	_, changed := nextRecentModels(cfg, SelectedModelTypeLarge, entry)
+	require.False(t, changed)
+}
+
+func TestUpdatePreferredModel_PersistsModelAndRecents(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	cfg := &Config{}
+	cfg.setDefaults(dir, "")
+	store := testStoreWithPath(cfg, dir)
+
+	sel := SelectedModel{Provider: "openai", Model: "gpt-4o"}
+	require.NoError(t, store.UpdatePreferredModel(ScopeGlobal, SelectedModelTypeLarge, sel))
+
+	// in-memory state (read through the store; copy-on-write publishes a
+	// new Config, so the seed cfg pointer is intentionally unchanged).
+	require.Equal(t, sel, store.Config().Models[SelectedModelTypeLarge])
+	require.Len(t, store.Config().RecentModels[SelectedModelTypeLarge], 1)
+
+	// persisted state
+	rm := readRecentModels(t, store.globalDataPath)
+	large, ok := rm[string(SelectedModelTypeLarge)].([]any)
+	require.True(t, ok)
+	require.Len(t, large, 1)
+	item := large[0].(map[string]any)
+	require.Equal(t, "openai", item["provider"])
+	require.Equal(t, "gpt-4o", item["model"])
+}
+
+func TestUpdatePreferredModel_TypeIsolation(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	cfg := &Config{}
+	cfg.setDefaults(dir, "")
+	store := testStoreWithPath(cfg, dir)
+
+	largeModel := SelectedModel{Provider: "openai", Model: "gpt-4o"}
+	smallModel := SelectedModel{Provider: "anthropic", Model: "claude"}
+	require.NoError(t, store.UpdatePreferredModel(ScopeGlobal, SelectedModelTypeLarge, largeModel))
+	require.NoError(t, store.UpdatePreferredModel(ScopeGlobal, SelectedModelTypeSmall, smallModel))
+
+	// Adding to large leaves small untouched.
+	anotherLarge := SelectedModel{Provider: "google", Model: "gemini"}
+	require.NoError(t, store.UpdatePreferredModel(ScopeGlobal, SelectedModelTypeLarge, anotherLarge))
+
+	require.Len(t, store.Config().RecentModels[SelectedModelTypeLarge], 2)
+	require.Equal(t, anotherLarge, store.Config().RecentModels[SelectedModelTypeLarge][0])
+	require.Len(t, store.Config().RecentModels[SelectedModelTypeSmall], 1)
+	require.Equal(t, smallModel, store.Config().RecentModels[SelectedModelTypeSmall][0])
+}

internal/config/reload_crushrc_test.go

@@ -0,0 +1,137 @@
+package config_test
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/stretchr/testify/require"
+)
+
+// isolateReloadEnv points HOME/XDG/CRUSH_* at a throwaway directory so a
+// reload only sees the config files the test writes. No t.Parallel(): these
+// tests Setenv.
+func isolateReloadEnv(t *testing.T) (workDir, dataDir string) {
+	t.Helper()
+	isolated := t.TempDir()
+	t.Setenv("HOME", isolated)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(isolated, ".config"))
+	t.Setenv("XDG_DATA_HOME", filepath.Join(isolated, ".local", "share"))
+	t.Setenv("CRUSH_GLOBAL_CONFIG", filepath.Join(isolated, ".config", "crush"))
+	t.Setenv("CRUSH_GLOBAL_DATA", filepath.Join(isolated, ".local", "share", "crush"))
+	return t.TempDir(), t.TempDir()
+}
+
+// TestReloadFromDisk_PicksUpEditedCrushrc verifies that a crushrc edit on
+// disk is reflected in memory after a reload, matching how JSON config
+// already behaves.
+func TestReloadFromDisk_PicksUpEditedCrushrc(t *testing.T) {
+	workDir, dataDir := isolateReloadEnv(t)
+	rcPath := filepath.Join(workDir, "crushrc")
+	require.NoError(t, os.WriteFile(rcPath, []byte("option notifications bell\n"), 0o644))
+
+	store, err := config.Load(workDir, dataDir, false)
+	require.NoError(t, err)
+	require.Equal(t, "bell", store.Config().Options.Notifications)
+
+	require.NoError(t, os.WriteFile(rcPath, []byte("option notifications osc\n"), 0o644))
+	require.NoError(t, store.ReloadFromDisk(context.Background()))
+	require.Equal(t, "osc", store.Config().Options.Notifications,
+		"reload must re-execute the crushrc and pick up the new value")
+}
+
+// TestReloadFromDisk_FailingCrushrcKeepsOldConfig verifies that a crushrc
+// which fails to load during a reload does not clobber the in-memory config.
+// The reload must return an error and leave the previously-loaded config
+// intact (the swap happens only after a successful parse).
+func TestReloadFromDisk_FailingCrushrcKeepsOldConfig(t *testing.T) {
+	workDir, dataDir := isolateReloadEnv(t)
+	rcPath := filepath.Join(workDir, "crushrc")
+	require.NoError(t, os.WriteFile(rcPath, []byte("option notifications bell\n"), 0o644))
+
+	store, err := config.Load(workDir, dataDir, false)
+	require.NoError(t, err)
+	require.Equal(t, "bell", store.Config().Options.Notifications)
+
+	// Overwrite with a crushrc that errors at load time (unknown option key).
+	require.NoError(t, os.WriteFile(rcPath, []byte("option totally-bogus-key value\n"), 0o644))
+
+	err = store.ReloadFromDisk(context.Background())
+	require.Error(t, err, "a failing crushrc must surface a reload error")
+	require.Equal(t, "bell", store.Config().Options.Notifications,
+		"in-memory config must be preserved when a reload fails")
+}
+
+// TestReloadFromDisk_HangingCrushrcIsInterruptible is the core regression test
+// for the reload-path blocker: config reloads run while holding the store's
+// write lock, so a crushrc that blocks (busy loop, hung command substitution)
+// must be interruptible via the reload context rather than wedging the store
+// forever. A cancelled reload must return an error and leave the old config
+// in place. The test bounds its own wait so a regression can't hang CI.
+func TestReloadFromDisk_HangingCrushrcIsInterruptible(t *testing.T) {
+	workDir, dataDir := isolateReloadEnv(t)
+	rcPath := filepath.Join(workDir, "crushrc")
+	require.NoError(t, os.WriteFile(rcPath, []byte("option notifications bell\n"), 0o644))
+
+	store, err := config.Load(workDir, dataDir, false)
+	require.NoError(t, err)
+	require.Equal(t, "bell", store.Config().Options.Notifications)
+
+	// Overwrite with a crushrc that never terminates.
+	require.NoError(t, os.WriteFile(rcPath, []byte("while true; do :; done\n"), 0o644))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
+	t.Cleanup(cancel)
+
+	done := make(chan error, 1)
+	go func() {
+		done <- store.ReloadFromDisk(ctx)
+	}()
+
+	select {
+	case err := <-done:
+		require.Error(t, err, "a cancelled reload must fail, not succeed")
+	case <-time.After(3 * time.Second):
+		t.Fatal("ReloadFromDisk did not return after context cancellation; the store would be wedged")
+	}
+
+	require.Equal(t, "bell", store.Config().Options.Notifications,
+		"in-memory config must be preserved when a reload is cancelled")
+}
+
+// TestLoad_TracksNotYetCreatedGlobalCrushrc verifies that config.Load tracks
+// the global crushrc path even when the file does not exist yet, so a crushrc
+// created after startup is detected as a staleness change. Previously only
+// successfully-loaded paths were tracked, so a mid-session global crushrc went
+// unnoticed until something else triggered a reload.
+//
+// Project-level crushrc files are discovered by walking the tree for existing
+// files, so a not-yet-created project crushrc is still only picked up on the
+// next reload; the global path is the common case this covers.
+func TestLoad_TracksNotYetCreatedGlobalCrushrc(t *testing.T) {
+	workDir, dataDir := isolateReloadEnv(t)
+	globalRC := filepath.Join(t.TempDir(), "crushrc")
+	t.Setenv("CRUSH_GLOBAL_CONFIG", filepath.Dir(globalRC))
+
+	// A provider must be configured so Load runs past its early
+	// "not configured" return and reaches the staleness snapshot capture.
+	require.NoError(t, os.WriteFile(
+		filepath.Join(workDir, "crushrc"),
+		[]byte("provider add openai --api-key k\n"), 0o644,
+	))
+
+	// Load with no global crushrc present.
+	store, err := config.Load(workDir, dataDir, false)
+	require.NoError(t, err)
+	require.False(t, store.ConfigStaleness().Dirty, "fresh load should be clean")
+
+	// Create the global crushrc after startup.
+	require.NoError(t, os.WriteFile(globalRC, []byte("option debug true\n"), 0o644))
+
+	staleness := store.ConfigStaleness()
+	require.True(t, staleness.Dirty, "creating a global crushrc must be detected")
+	require.Contains(t, staleness.Changed, globalRC)
+}

internal/config/reload_hooks_test.go

@@ -0,0 +1,102 @@
+package config_test
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/charmbracelet/crush/internal/hooks"
+	"github.com/stretchr/testify/require"
+)
+
+// TestReloadFromDisk_CompilesHookMatchers is a regression test for a bug
+// where ReloadFromDisk dropped the compiled matcher regex on every hook,
+// causing a matcher like "^bash$" to match every tool call after any
+// SetConfigField-triggered reload.
+//
+// The assertion is phrased in terms of observable Runner behavior (not
+// internal field presence) so it stays valid if the Runner later owns
+// matcher compilation itself.
+func TestReloadFromDisk_CompilesHookMatchers(t *testing.T) {
+	// No t.Parallel(): we Setenv HOME/XDG_CONFIG_HOME to isolate from the
+	// developer's real global config, which may define its own hooks.
+	isolated := t.TempDir()
+	t.Setenv("HOME", isolated)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(isolated, ".config"))
+	t.Setenv("XDG_DATA_HOME", filepath.Join(isolated, ".local", "share"))
+
+	workDir := t.TempDir()
+	dataDir := t.TempDir()
+	configPath := filepath.Join(workDir, "crush.json")
+	cfgJSON := `{
+        "hooks": {
+            "PreToolUse": [
+                {"matcher": "^bash$", "command": "exit 0"}
+            ]
+        }
+    }`
+	require.NoError(t, os.WriteFile(configPath, []byte(cfgJSON), 0o600))
+
+	store, err := config.Load(workDir, dataDir, false)
+	require.NoError(t, err)
+
+	// Sanity: hook filtering works immediately after Load.
+	assertHookFilters(t, store)
+
+	require.NoError(t, store.ReloadFromDisk(context.Background()))
+
+	// The actual regression check: filtering must still work after a
+	// reload, not silently collapse to match-everything.
+	assertHookFilters(t, store)
+}
+
+// assertHookFilters builds a Runner from the store's current hooks and
+// verifies the "^bash$" matcher rejects a non-bash tool while accepting
+// bash.
+func assertHookFilters(t *testing.T, store *config.ConfigStore) {
+	t.Helper()
+	preHooks := store.Config().Hooks[hooks.EventPreToolUse]
+	require.Len(t, preHooks, 1)
+
+	runner := hooks.NewRunner(preHooks, t.TempDir(), t.TempDir())
+
+	nonMatch, err := runner.Run(context.Background(), hooks.EventPreToolUse, "sess", "view", `{}`)
+	require.NoError(t, err)
+	require.Equal(t, 0, nonMatch.HookCount, "view must not match ^bash$ matcher")
+
+	match, err := runner.Run(context.Background(), hooks.EventPreToolUse, "sess", "bash", `{}`)
+	require.NoError(t, err)
+	require.Equal(t, 1, match.HookCount, "bash must match ^bash$ matcher")
+}
+
+// TestSetConfigField_AutoReload_PreservesHookMatcherFiltering verifies the
+// dominant real-world trigger path: config writes call autoReload,
+// autoReload calls ReloadFromDisk, and hook matching must remain correct.
+func TestSetConfigField_AutoReload_PreservesHookMatcherFiltering(t *testing.T) {
+	isolated := t.TempDir()
+	t.Setenv("HOME", isolated)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(isolated, ".config"))
+	t.Setenv("XDG_DATA_HOME", filepath.Join(isolated, ".local", "share"))
+
+	workDir := t.TempDir()
+	dataDir := t.TempDir()
+	configPath := filepath.Join(workDir, "crush.json")
+	cfgJSON := `{
+        "hooks": {
+            "PreToolUse": [
+                {"matcher": "^bash$", "command": "exit 0"}
+            ]
+        }
+    }`
+	require.NoError(t, os.WriteFile(configPath, []byte(cfgJSON), 0o600))
+
+	store, err := config.Load(workDir, dataDir, false)
+	require.NoError(t, err)
+	assertHookFilters(t, store)
+
+	require.NoError(t, store.SetConfigField(config.ScopeGlobal, "options.debug", true))
+
+	assertHookFilters(t, store)
+}

internal/config/resolve_real_test.go

@@ -0,0 +1,512 @@
+package config
+
+import (
+	"fmt"
+	"maps"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/charmbracelet/crush/internal/env"
+	"github.com/stretchr/testify/require"
+)
+
+// These tests exercise the full shell-expansion path (no mocks,
+// no injected Expander) to catch regressions that only surface when
+// internal/shell actually runs the value. Table-level unit tests with
+// fake expanders live in resolve_test.go.
+
+// realShellResolver builds a resolver backed by a shell env that
+// contains PATH + the caller-supplied overrides. Production callers
+// get PATH for free via env.New(); these tests need it so $(cat ...)
+// and similar inner commands can resolve.
+func realShellResolver(vars map[string]string) VariableResolver {
+	m := map[string]string{"PATH": os.Getenv("PATH")}
+	maps.Copy(m, vars)
+	return NewShellVariableResolver(env.NewFromMap(m))
+}
+
+func writeTempFile(t *testing.T, content string) string {
+	t.Helper()
+	dir := t.TempDir()
+	p := filepath.Join(dir, "secret")
+	require.NoError(t, os.WriteFile(p, []byte(content), 0o600))
+	return p
+}
+
+// TestResolvedEnv_RealShell_Success covers the shell constructs the
+// PLAN calls out: $(cat tempfile) with and without trailing newline,
+// ${VAR:-default} for unset vars, literal-space preservation around
+// $(...), nested parens, quoted args inside $(echo ...), and a
+// glob-like literal round-tripping unchanged.
+func TestResolvedEnv_RealShell_Success(t *testing.T) {
+	t.Parallel()
+
+	// filepath.ToSlash so Windows temp paths (C:\Users\...) survive
+	// being injected into a shell command string — the embedded shell
+	// treats backslashes as escapes, forward slashes work on every OS.
+	withNL := filepath.ToSlash(writeTempFile(t, "token-with-nl\n"))
+	noNL := filepath.ToSlash(writeTempFile(t, "token-no-nl"))
+
+	m := MCPConfig{
+		Env: map[string]string{
+			// POSIX strips exactly one trailing newline from $(...)
+			// output, so both forms land on the same value.
+			"TOK_NL": fmt.Sprintf("$(cat %s)", withNL),
+			"TOK_NO": fmt.Sprintf("$(cat %s)", noNL),
+
+			// ${VAR:-default} must not error on unset: this is the
+			// opt-in escape hatch for "empty is fine".
+			"FALLBACK": "${MCP_MISSING:-fallback}",
+
+			// Leading/trailing literal spaces around $(...) must be
+			// preserved — single-value contract, no field splitting.
+			"PADDED": "  $(echo v)  ",
+
+			// ")" inside a quoted arg to echo is a regression guard
+			// for the old hand-rolled paren matcher.
+			"PAREN": `$(echo ")")`,
+
+			// Embedded space inside a quoted arg must survive
+			// verbatim; no word-splitting side effect.
+			"SPACEY": `$(echo "a b")`,
+
+			// Glob-like literals must not expand.
+			"GLOB": "*.go",
+		},
+	}
+
+	got, err := m.ResolvedEnv(realShellResolver(nil))
+	require.NoError(t, err)
+
+	// ResolvedEnv returns "KEY=value" sorted by key.
+	want := []string{
+		"FALLBACK=fallback",
+		"GLOB=*.go",
+		"PADDED=  v  ",
+		"PAREN=)",
+		"SPACEY=a b",
+		"TOK_NL=token-with-nl",
+		"TOK_NO=token-no-nl",
+	}
+	require.Equal(t, want, got)
+}
+
+// TestResolvedEnv_RealShell_DoesNotMutate pins that both success and
+// failure paths leave m.Env untouched. Prior behaviour rewrote the
+// value in place on error; that was the exact mechanism that shipped
+// empty credentials to MCP servers.
+func TestResolvedEnv_RealShell_DoesNotMutate(t *testing.T) {
+	t.Parallel()
+
+	t.Run("success path leaves Env untouched", func(t *testing.T) {
+		t.Parallel()
+		m := MCPConfig{Env: map[string]string{"TOKEN": "$(echo shh)"}}
+		orig := maps.Clone(m.Env)
+
+		_, err := m.ResolvedEnv(realShellResolver(nil))
+		require.NoError(t, err)
+		require.Equal(t, orig, m.Env)
+	})
+
+	t.Run("failure path leaves Env untouched", func(t *testing.T) {
+		t.Parallel()
+		m := MCPConfig{Env: map[string]string{"BROKEN": "$(false)"}}
+		orig := maps.Clone(m.Env)
+
+		_, err := m.ResolvedEnv(realShellResolver(nil))
+		require.Error(t, err)
+		require.Equal(t, orig, m.Env, "map must be preserved on error")
+	})
+}
+
+// TestResolvedEnv_RealShell_Idempotent pins the pure-function contract:
+// two calls on the same config return deeply-equal slices.
+func TestResolvedEnv_RealShell_Idempotent(t *testing.T) {
+	t.Parallel()
+
+	m := MCPConfig{
+		Env: map[string]string{
+			"A": "$(echo one)",
+			"B": "$(echo two)",
+			"C": "literal",
+		},
+	}
+	r := realShellResolver(nil)
+
+	first, err := m.ResolvedEnv(r)
+	require.NoError(t, err)
+	second, err := m.ResolvedEnv(r)
+	require.NoError(t, err)
+	require.Equal(t, first, second)
+}
+
+// TestResolvedEnv_RealShell_Deterministic guards against Go's
+// randomized map iteration leaking into the returned slice order.
+func TestResolvedEnv_RealShell_Deterministic(t *testing.T) {
+	t.Parallel()
+
+	m := MCPConfig{Env: map[string]string{
+		"Z": "z",
+		"A": "a",
+		"M": "m",
+	}}
+
+	got, err := m.ResolvedEnv(realShellResolver(nil))
+	require.NoError(t, err)
+	require.True(t, slices.IsSorted(got), "env slice must be sorted; got %v", got)
+}
+
+// TestResolvedEnv_RealShell_UnsetExpandsEmpty pins the lenient
+// default: an unset bare $VAR expands to the empty string, matching
+// bash. The silent-empty-credential class of bug is prevented by the
+// pure-function error-returning contract of ResolvedEnv, so we don't
+// rely on nounset to catch typo'd variable names. Users who want
+// strict behaviour for a required credential opt in per-reference
+// with ${VAR:?msg}; see TestResolvedEnv_RealShell_ColonQuestionIsStrict.
+func TestResolvedEnv_RealShell_UnsetExpandsEmpty(t *testing.T) {
+	t.Parallel()
+
+	m := MCPConfig{Env: map[string]string{
+		// Intentional typo: user meant $FORGEJO_TOKEN. Under the
+		// lenient default this expands to "" rather than erroring,
+		// matching bash's behaviour on bare $VAR.
+		"FORGEJO_ACCESS_TOKEN": "$FORGJO_TOKEN",
+	}}
+	got, err := m.ResolvedEnv(realShellResolver(nil))
+	require.NoError(t, err, "unset var must expand to empty, not error")
+	require.Equal(t, []string{"FORGEJO_ACCESS_TOKEN="}, got)
+}
+
+// TestResolvedEnv_RealShell_ColonQuestionIsStrict pins the opt-in
+// strictness contract: ${VAR:?msg} must hard-error when VAR is unset,
+// regardless of the global NoUnset toggle. This is the recommended
+// mechanism for required credentials under the lenient default, so a
+// future refactor that accidentally swallows ${VAR:?...} errors would
+// silently ship empty tokens to MCP servers again.
+func TestResolvedEnv_RealShell_ColonQuestionIsStrict(t *testing.T) {
+	t.Parallel()
+
+	m := MCPConfig{Env: map[string]string{
+		"FORGEJO_ACCESS_TOKEN": "${FORGJO_TOKEN:?set FORGJO_TOKEN}",
+	}}
+	got, err := m.ResolvedEnv(realShellResolver(nil))
+	require.Error(t, err, "${VAR:?msg} must error when VAR is unset")
+	require.Nil(t, got)
+	// The resolver wraps with the env key and the user-written
+	// template; the inner shell error carries the :? message so
+	// users learn which credential is missing and why.
+	msg := err.Error()
+	require.Contains(t, msg, "FORGEJO_ACCESS_TOKEN")
+	require.Contains(t, msg, "${FORGJO_TOKEN:?set FORGJO_TOKEN}")
+	require.Contains(t, msg, "set FORGJO_TOKEN")
+}
+
+// TestResolvedEnv_RealShell_FailureDetail pins that a failing inner
+// command surfaces enough detail (exit code + stderr on POSIX, the
+// underlying OS error on Windows where coreutils runs in-process) to
+// diagnose without forcing the user to re-run the command by hand.
+// Also verifies the template is included so they know which Env
+// entry blew up.
+func TestResolvedEnv_RealShell_FailureDetail(t *testing.T) {
+	t.Parallel()
+
+	// Forward slashes so the path survives shell-string injection on
+	// Windows; see TestResolvedEnv_RealShell_Success for the same note.
+	missing := filepath.ToSlash(filepath.Join(t.TempDir(), "definitely-not-here"))
+	m := MCPConfig{Env: map[string]string{
+		"FORGEJO_ACCESS_TOKEN": fmt.Sprintf("$(cat %s)", missing),
+	}}
+
+	_, err := m.ResolvedEnv(realShellResolver(nil))
+	require.Error(t, err)
+	msg := err.Error()
+	require.Contains(t, msg, "FORGEJO_ACCESS_TOKEN", "must identify the failing env var")
+	require.Contains(t, msg, missing, "must include the template so users see what failed")
+
+	// Inner diagnostic detail must survive. POSIX surfaces "exit
+	// status N" + stderr; Windows' in-process coreutils surfaces the
+	// Go OS error instead. Accept either shape so the test is
+	// portable without weakening the intent.
+	lower := strings.ToLower(msg)
+	hasDetail := strings.Contains(lower, "exit status") ||
+		strings.Contains(lower, "no such file") ||
+		strings.Contains(lower, "cannot find")
+	require.True(t, hasDetail, "must surface inner error detail: %s", msg)
+}
+
+// TestResolvedHeaders_RealShell_FailurePreservesOriginal pins two
+// invariants simultaneously: on failure the returned map is nil (not
+// a partially-populated map) and the receiver's Headers map is
+// unchanged. A test that only asserted on the returned value could
+// hide an in-place mutation regression.
+func TestResolvedHeaders_RealShell_FailurePreservesOriginal(t *testing.T) {
+	t.Parallel()
+
+	m := MCPConfig{Headers: map[string]string{
+		"Authorization": "Bearer $(false)",
+		"X-Static":      "kept",
+	}}
+	orig := maps.Clone(m.Headers)
+
+	got, err := m.ResolvedHeaders(realShellResolver(nil))
+	require.Error(t, err)
+	require.Nil(t, got, "headers map must be nil on failure")
+	require.Contains(t, err.Error(), "header Authorization")
+	require.Equal(t, orig, m.Headers, "receiver Headers must be preserved")
+}
+
+// TestResolvedHeaders_RealShell_DropEmpty verifies that a header
+// whose value resolves to the empty string is omitted from the
+// returned map. Covers the three ways a value can legitimately land
+// on empty — unset bare $VAR under lenient nounset, a literal "",
+// and a non-failing command whose stdout is empty — and also pins
+// that a failing $(cmd) still errors rather than silently dropping.
+func TestResolvedHeaders_RealShell_DropEmpty(t *testing.T) {
+	t.Parallel()
+
+	t.Run("unset $VAR is absent", func(t *testing.T) {
+		t.Parallel()
+		m := MCPConfig{Headers: map[string]string{
+			"X-Missing": "$MCP_HEADER_NEVER_SET",
+			"X-Kept":    "present",
+		}}
+		got, err := m.ResolvedHeaders(realShellResolver(nil))
+		require.NoError(t, err)
+		_, present := got["X-Missing"]
+		require.False(t, present, "unset bare $VAR → empty → header dropped")
+		require.Equal(t, "present", got["X-Kept"])
+	})
+
+	t.Run("literal empty string is absent", func(t *testing.T) {
+		t.Parallel()
+		m := MCPConfig{Headers: map[string]string{
+			"X-Custom": "",
+			"X-Kept":   "present",
+		}}
+		got, err := m.ResolvedHeaders(realShellResolver(nil))
+		require.NoError(t, err)
+		_, present := got["X-Custom"]
+		require.False(t, present, "literal empty-string header must be dropped")
+		require.Equal(t, "present", got["X-Kept"])
+	})
+
+	t.Run("$(echo) is absent", func(t *testing.T) {
+		t.Parallel()
+		m := MCPConfig{Headers: map[string]string{
+			"X-Empty": "$(echo)",
+			"X-Kept":  "present",
+		}}
+		got, err := m.ResolvedHeaders(realShellResolver(nil))
+		require.NoError(t, err)
+		_, present := got["X-Empty"]
+		require.False(t, present, "$(echo) → empty → header dropped")
+		require.Equal(t, "present", got["X-Kept"])
+	})
+
+	t.Run("$(false) errors and does not mutate", func(t *testing.T) {
+		t.Parallel()
+		m := MCPConfig{Headers: map[string]string{
+			"X-Broken": "$(false)",
+			"X-Kept":   "present",
+		}}
+		orig := maps.Clone(m.Headers)
+
+		got, err := m.ResolvedHeaders(realShellResolver(nil))
+		require.Error(t, err)
+		require.Empty(t, got, "map must be nil/empty on failure, not a partial")
+		require.Contains(t, err.Error(), "header X-Broken")
+		require.Equal(t, orig, m.Headers, "receiver Headers must be preserved")
+	})
+}
+
+// TestResolvedArgs_RealShell exercises both success and failure for
+// m.Args symmetrically with Env. Args are ordered so error messages
+// must identify a positional index, not a key.
+func TestResolvedArgs_RealShell(t *testing.T) {
+	t.Parallel()
+
+	t.Run("success expands each element", func(t *testing.T) {
+		t.Parallel()
+		m := MCPConfig{Args: []string{"--token", "$(echo shh)", "--host", "example.com"}}
+		got, err := m.ResolvedArgs(realShellResolver(nil))
+		require.NoError(t, err)
+		require.Equal(t, []string{"--token", "shh", "--host", "example.com"}, got)
+	})
+
+	t.Run("failure identifies offending index", func(t *testing.T) {
+		t.Parallel()
+		m := MCPConfig{Args: []string{"--token", "$(false)"}}
+		orig := slices.Clone(m.Args)
+
+		got, err := m.ResolvedArgs(realShellResolver(nil))
+		require.Error(t, err)
+		require.Nil(t, got)
+		require.Contains(t, err.Error(), "arg 1")
+		require.Equal(t, orig, m.Args, "receiver Args must be preserved")
+	})
+
+	t.Run("nil args returns nil, no error", func(t *testing.T) {
+		t.Parallel()
+		m := MCPConfig{}
+		got, err := m.ResolvedArgs(realShellResolver(nil))
+		require.NoError(t, err)
+		require.Nil(t, got)
+	})
+}
+
+// TestLSPConfig_ResolvedArgs_RealShell exercises both success and
+// failure for l.Args symmetrically with MCP args. Args are ordered so
+// error messages must identify a positional index, not a key.
+func TestLSPConfig_ResolvedArgs_RealShell(t *testing.T) {
+	t.Parallel()
+
+	t.Run("success expands $VAR in each element", func(t *testing.T) {
+		t.Parallel()
+		l := LSPConfig{Args: []string{"--root", "$HOME", "--flag", "literal"}}
+		r := realShellResolver(map[string]string{"HOME": "/home/tester"})
+		got, err := l.ResolvedArgs(r)
+		require.NoError(t, err)
+		require.Equal(t, []string{"--root", "/home/tester", "--flag", "literal"}, got)
+	})
+
+	t.Run("failure identifies offending index", func(t *testing.T) {
+		t.Parallel()
+		l := LSPConfig{Args: []string{"--root", "$(false)"}}
+		orig := slices.Clone(l.Args)
+
+		got, err := l.ResolvedArgs(realShellResolver(nil))
+		require.Error(t, err)
+		require.Nil(t, got)
+		require.Contains(t, err.Error(), "arg 1")
+		require.Equal(t, orig, l.Args, "receiver Args must be preserved")
+	})
+
+	t.Run("nil args returns nil, no error", func(t *testing.T) {
+		t.Parallel()
+		l := LSPConfig{}
+		got, err := l.ResolvedArgs(realShellResolver(nil))
+		require.NoError(t, err)
+		require.Nil(t, got)
+	})
+}
+
+// TestLSPConfig_ResolvedEnv_RealShell pins the LSP env contract:
+// success expands $VAR, failure wraps with the key name, and the
+// receiver map is never mutated. The shape is map[string]string
+// (not the MCP []string form) because powernap.ClientConfig.Environment
+// takes a map directly.
+func TestLSPConfig_ResolvedEnv_RealShell(t *testing.T) {
+	t.Parallel()
+
+	t.Run("success expands $VAR", func(t *testing.T) {
+		t.Parallel()
+		l := LSPConfig{Env: map[string]string{"GOPATH": "$HOME/go"}}
+		r := realShellResolver(map[string]string{"HOME": "/home/tester"})
+		got, err := l.ResolvedEnv(r)
+		require.NoError(t, err)
+		require.Equal(t, map[string]string{"GOPATH": "/home/tester/go"}, got)
+	})
+
+	t.Run("failure identifies offending key", func(t *testing.T) {
+		t.Parallel()
+		l := LSPConfig{Env: map[string]string{
+			"GOPATH": "$(false)",
+			"OTHER":  "literal",
+		}}
+		orig := maps.Clone(l.Env)
+
+		got, err := l.ResolvedEnv(realShellResolver(nil))
+		require.Error(t, err)
+		require.Nil(t, got)
+		require.Contains(t, err.Error(), `env "GOPATH"`)
+		require.Equal(t, orig, l.Env, "receiver Env must be preserved")
+	})
+
+	t.Run("idempotent and non-mutating", func(t *testing.T) {
+		t.Parallel()
+		l := LSPConfig{Env: map[string]string{
+			"A": "$(echo one)",
+			"B": "literal",
+		}}
+		orig := maps.Clone(l.Env)
+		r := realShellResolver(nil)
+
+		first, err := l.ResolvedEnv(r)
+		require.NoError(t, err)
+		second, err := l.ResolvedEnv(r)
+		require.NoError(t, err)
+		require.Equal(t, first, second)
+		require.Equal(t, orig, l.Env, "receiver Env must be preserved")
+	})
+}
+
+// TestLSPConfig_IdentityResolver pins the client-mode contract: both
+// ResolvedArgs and ResolvedEnv round-trip the template verbatim under
+// IdentityResolver and never error on unset variables. Local
+// expansion would double-expand when the server does its own — this
+// has to stay a pure pass-through.
+func TestLSPConfig_IdentityResolver(t *testing.T) {
+	t.Parallel()
+
+	l := LSPConfig{
+		Args: []string{"--root", "$LSP_ROOT", "$(vault read -f lsp)"},
+		Env: map[string]string{
+			"GOPATH": "$HOME/go",
+			"TOKEN":  "$(cat /run/secrets/x)",
+		},
+	}
+	r := IdentityResolver()
+
+	args, err := l.ResolvedArgs(r)
+	require.NoError(t, err)
+	require.Equal(t, l.Args, args)
+
+	envs, err := l.ResolvedEnv(r)
+	require.NoError(t, err)
+	require.Equal(t, l.Env, envs)
+}
+
+// TestMCPConfig_IdentityResolver pins the client-mode contract: every
+// Resolved* method round-trips the template verbatim and never errors
+// on unset variables. Local expansion would double-expand when the
+// server does its own — this has to stay a pure pass-through.
+func TestMCPConfig_IdentityResolver(t *testing.T) {
+	t.Parallel()
+
+	m := MCPConfig{
+		Command: "$CMD",
+		Args:    []string{"--token", "$MCP_MISSING_TOKEN", "$(vault read -f secret)"},
+		Env: map[string]string{
+			"TOKEN": "$(cat /run/secrets/x)",
+			"HOST":  "$MCP_MISSING_HOST",
+		},
+		Headers: map[string]string{
+			"Authorization": "Bearer $(vault read -f token)",
+		},
+		URL: "https://$MCP_HOST/$(vault read -f path)",
+	}
+	r := IdentityResolver()
+
+	args, err := m.ResolvedArgs(r)
+	require.NoError(t, err)
+	require.Equal(t, m.Args, args)
+
+	envs, err := m.ResolvedEnv(r)
+	require.NoError(t, err)
+	// Sorted "KEY=value".
+	require.Equal(t, []string{
+		"HOST=$MCP_MISSING_HOST",
+		"TOKEN=$(cat /run/secrets/x)",
+	}, envs)
+
+	headers, err := m.ResolvedHeaders(r)
+	require.NoError(t, err)
+	require.Equal(t, m.Headers, headers)
+
+	u, err := m.ResolvedURL(r)
+	require.NoError(t, err)
+	require.Equal(t, m.URL, u)
+}

internal/config/resolve_test.go

@@ -0,0 +1,229 @@
+package config
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/charmbracelet/crush/internal/env"
+	"github.com/stretchr/testify/require"
+)
+
+// fakeExpander returns a canned value/error for the last passed value and
+// records the context, raw value, and env slice it was called with. It
+// lets the config-layer tests assert on delegation behaviour without
+// spinning up a real interpreter — real-shell coverage lives in
+// internal/shell/expand_test.go and resolve_real_test.go.
+type fakeExpander struct {
+	expand    func(ctx context.Context, value string, env []string) (string, error)
+	lastValue string
+	lastEnv   []string
+	calls     int
+}
+
+func (f *fakeExpander) Expand(ctx context.Context, value string, env []string) (string, error) {
+	f.calls++
+	f.lastValue = value
+	f.lastEnv = env
+	if f.expand == nil {
+		return value, nil
+	}
+	return f.expand(ctx, value, env)
+}
+
+func TestShellVariableResolver_DelegatesToExpander(t *testing.T) {
+	t.Parallel()
+
+	fe := &fakeExpander{
+		expand: func(_ context.Context, value string, _ []string) (string, error) {
+			if value == "hello $FOO" {
+				return "hello bar", nil
+			}
+			return value, nil
+		},
+	}
+
+	e := env.NewFromMap(map[string]string{"FOO": "bar"})
+	r := NewShellVariableResolver(e, WithExpander(fe.Expand))
+
+	got, err := r.ResolveValue("hello $FOO")
+	require.NoError(t, err)
+	require.Equal(t, "hello bar", got)
+	require.Equal(t, 1, fe.calls)
+	require.Equal(t, "hello $FOO", fe.lastValue)
+	require.Contains(t, fe.lastEnv, "FOO=bar")
+}
+
+func TestShellVariableResolver_LoneDollarIsError(t *testing.T) {
+	t.Parallel()
+
+	// Lone "$" must short-circuit before reaching the expander: the
+	// underlying shell parser would accept it as a literal, but this
+	// resolver has historically rejected it and callers depend on
+	// that early-fail behaviour.
+	fe := &fakeExpander{}
+	r := NewShellVariableResolver(env.NewFromMap(nil), WithExpander(fe.Expand))
+
+	_, err := r.ResolveValue("$")
+	require.Error(t, err)
+	require.Equal(t, 0, fe.calls, "expander must not be called for lone $")
+}
+
+func TestShellVariableResolver_PassesThroughLiterals(t *testing.T) {
+	t.Parallel()
+
+	fe := &fakeExpander{
+		expand: func(_ context.Context, value string, _ []string) (string, error) {
+			return value, nil
+		},
+	}
+	r := NewShellVariableResolver(env.NewFromMap(nil), WithExpander(fe.Expand))
+
+	got, err := r.ResolveValue("plain-string")
+	require.NoError(t, err)
+	require.Equal(t, "plain-string", got)
+}
+
+func TestShellVariableResolver_WrapsErrorsWithTemplate(t *testing.T) {
+	t.Parallel()
+
+	inner := errors.New("cat: /run/secrets/x: permission denied")
+	fe := &fakeExpander{
+		expand: func(_ context.Context, _ string, _ []string) (string, error) {
+			return "", inner
+		},
+	}
+	r := NewShellVariableResolver(env.NewFromMap(nil), WithExpander(fe.Expand))
+
+	_, err := r.ResolveValue("$(cat /run/secrets/x)")
+	require.Error(t, err)
+	require.ErrorIs(t, err, inner)
+	require.Contains(t, err.Error(), "$(cat /run/secrets/x)")
+	require.Contains(t, err.Error(), "permission denied")
+}
+
+func TestSanitizeResolveError(t *testing.T) {
+	t.Parallel()
+
+	t.Run("nil passes through", func(t *testing.T) {
+		t.Parallel()
+		require.NoError(t, sanitizeResolveError("anything", nil))
+	})
+
+	t.Run("includes template and wraps inner", func(t *testing.T) {
+		t.Parallel()
+		inner := errors.New("cat: /run/secrets/x: permission denied")
+		got := sanitizeResolveError("$(cat /run/secrets/x)", inner)
+		require.Error(t, got)
+		require.ErrorIs(t, got, inner)
+		require.Contains(t, got.Error(), "$(cat /run/secrets/x)")
+		require.Contains(t, got.Error(), "permission denied")
+	})
+
+	t.Run("unwrap preserves original for errors.Is", func(t *testing.T) {
+		t.Parallel()
+		inner := errors.New("sentinel")
+		got := sanitizeResolveError("$FOO", inner)
+		require.ErrorIs(t, got, inner)
+	})
+
+	t.Run("truncates over-budget inner message", func(t *testing.T) {
+		t.Parallel()
+		// Inner message holds far more than the budget. After
+		// sanitization the rendered inner portion must not exceed
+		// maxResolveErrBytes, and the characters beyond the budget
+		// (marked by a distinct tail sentinel) must be gone.
+		const tailSentinel = "TAIL_SENTINEL_BEYOND_BUDGET"
+		body := strings.Repeat("x", maxResolveErrBytes)
+		inner := errors.New(body + tailSentinel)
+
+		got := sanitizeResolveError("$TEMPLATE", inner)
+		require.Error(t, got)
+
+		prefix := `resolving "$TEMPLATE": `
+		rendered := got.Error()
+		require.True(
+			t,
+			strings.HasPrefix(rendered, prefix),
+			"rendered error must start with template prefix",
+		)
+		innerRendered := strings.TrimPrefix(rendered, prefix)
+		require.LessOrEqual(
+			t,
+			len(innerRendered),
+			maxResolveErrBytes,
+			"inner message must be bounded to maxResolveErrBytes",
+		)
+		require.NotContains(
+			t,
+			rendered,
+			tailSentinel,
+			"content past the budget must not leak",
+		)
+	})
+
+	t.Run("replaces non-printable bytes", func(t *testing.T) {
+		t.Parallel()
+		// NUL, BEL, ESC, DEL, and a UTF-8 high byte should all be
+		// scrubbed to '?'. Tab and newline are preserved because
+		// they show up legitimately in command stderr.
+		inner := errors.New("ok\x00bad\x07\x1b\x7f\xffend\ttab\nline")
+		got := sanitizeResolveError("$T", inner)
+		rendered := got.Error()
+
+		require.NotContains(t, rendered, "\x00")
+		require.NotContains(t, rendered, "\x07")
+		require.NotContains(t, rendered, "\x1b")
+		require.NotContains(t, rendered, "\x7f")
+		require.NotContains(t, rendered, "\xff")
+		require.Contains(t, rendered, "ok?bad????end\ttab\nline")
+	})
+
+	t.Run("scrubbing does not depend on shell.ExpandValue upstream", func(t *testing.T) {
+		t.Parallel()
+		// A custom Expander can inject arbitrary error text. The
+		// config-layer helper is the single chokepoint; it must
+		// bound + scrub regardless of the error source.
+		nasty := strings.Repeat("A", maxResolveErrBytes+64) + "\x00BEYOND"
+		fe := &fakeExpander{
+			expand: func(_ context.Context, _ string, _ []string) (string, error) {
+				return "", errors.New(nasty)
+			},
+		}
+		r := NewShellVariableResolver(env.NewFromMap(nil), WithExpander(fe.Expand))
+
+		_, err := r.ResolveValue("$T")
+		require.Error(t, err)
+		require.NotContains(t, err.Error(), "BEYOND", "over-budget tail must not leak")
+		require.NotContains(t, err.Error(), "\x00", "non-printables must be scrubbed")
+	})
+}
+
+func TestScrubErrorMessage(t *testing.T) {
+	t.Parallel()
+
+	t.Run("bounds output to maxResolveErrBytes", func(t *testing.T) {
+		t.Parallel()
+		got := scrubErrorMessage(strings.Repeat("a", maxResolveErrBytes*3))
+		require.Len(t, got, maxResolveErrBytes)
+	})
+
+	t.Run("preserves printable ASCII tab and newline", func(t *testing.T) {
+		t.Parallel()
+		require.Equal(t, "a\tb\nc d!", scrubErrorMessage("a\tb\nc d!"))
+	})
+
+	t.Run("replaces control and non-ASCII bytes", func(t *testing.T) {
+		t.Parallel()
+		require.Equal(t, "a?b??c", scrubErrorMessage("a\x01b\x1b\xe2c"))
+	})
+}
+
+func TestNewShellVariableResolver(t *testing.T) {
+	testEnv := env.NewFromMap(map[string]string{"TEST": "value"})
+	resolver := NewShellVariableResolver(testEnv)
+
+	require.NotNil(t, resolver)
+	require.Implements(t, (*VariableResolver)(nil), resolver)
+}

internal/config/scope.go

@@ -0,0 +1,29 @@
+package config
+
+import "fmt"
+
+// Scope determines which config file is targeted for read/write operations.
+type Scope int
+
+const (
+	// ScopeGlobal targets the global data config (~/.local/share/crush/crush.json).
+	ScopeGlobal Scope = iota
+	// ScopeWorkspace targets the workspace config (.crush/crush.json).
+	ScopeWorkspace
+)
+
+// String returns a human-readable label for the scope.
+func (s Scope) String() string {
+	switch s {
+	case ScopeGlobal:
+		return "global"
+	case ScopeWorkspace:
+		return "workspace"
+	default:
+		return fmt.Sprintf("Scope(%d)", int(s))
+	}
+}
+
+// ErrNoWorkspaceConfig is returned when a workspace-scoped write is
+// attempted on a ConfigStore that has no workspace config path.
+var ErrNoWorkspaceConfig = fmt.Errorf("no workspace config path configured")

internal/config/scopeb_race_test.go

@@ -0,0 +1,74 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+)
+
+// TestScopeB_InPlaceMutationRace probes whether the store's in-place field
+// mutators (e.g. SetCompactMode) race with concurrent Config() readers that
+// walk the same field. This is the "Scope B" race left open after the
+// pointer-swap fix. Run with -race.
+// TestScopeB_InPlaceMutationRace verifies that the store's typed field
+// mutators (e.g. SetCompactMode) no longer race concurrent Config()
+// readers walking the same field. Copy-on-write publishing means the
+// mutator swaps in a fresh Config rather than writing through the live
+// pointer, so a reader always sees an immutable snapshot. Run with -race.
+func TestScopeB_InPlaceMutationRace(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "crush.json")
+
+	t.Setenv("CRUSH_GLOBAL_CONFIG", dir)
+	t.Setenv("CRUSH_GLOBAL_DATA", dir)
+	resetProviderState()
+	t.Cleanup(resetProviderState)
+
+	cfg := `{
+		"models": {"large": {"provider": "openai", "model": "gpt-4"}},
+		"providers": {"openai": {"api_key": "k", "models": [{"id": "gpt-4", "name": "GPT-4"}]}},
+		"options": {"tui": {"compact_mode": false}}
+	}`
+	if err := os.WriteFile(configPath, []byte(cfg), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	store, err := Load(dir, dir, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	store.globalDataPath = configPath
+
+	var wg sync.WaitGroup
+	stop := make(chan struct{})
+
+	// Reader: walks Options.TUI.CompactMode, the field SetCompactMode writes.
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for {
+			select {
+			case <-stop:
+				return
+			default:
+				c := store.Config()
+				if c != nil && c.Options != nil {
+					_ = c.Options.TUI.CompactMode
+				}
+			}
+		}
+	}()
+
+	// Writer: flips compact mode, mutating Options in place.
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for i := 0; i < 50; i++ {
+			_ = store.SetCompactMode(ScopeGlobal, i%2 == 0)
+		}
+		close(stop)
+	}()
+
+	wg.Wait()
+}

internal/config/shellconfig_hook_test.go

@@ -0,0 +1,37 @@
+package config_test
+
+import (
+	"testing"
+
+	"github.com/charmbracelet/crush/internal/hooks"
+	"github.com/stretchr/testify/require"
+)
+
+func TestShellConfigHookAdd(t *testing.T) {
+	store := loadCrushSh(t, `hook add PreToolUse --matcher "^bash$" --command "echo hi" --name greet --timeout 10`)
+
+	hs := store.Config().Hooks[hooks.EventPreToolUse]
+	require.Len(t, hs, 1)
+	require.Equal(t, "greet", hs[0].Name)
+	require.Equal(t, "^bash$", hs[0].Matcher)
+	require.Equal(t, "echo hi", hs[0].Command)
+	require.Equal(t, 10, hs[0].Timeout)
+}
+
+func TestShellConfigHookRemoveByName(t *testing.T) {
+	store := loadCrushSh(t, `hook add PreToolUse --command a --name keep
+hook add PreToolUse --command b --name drop
+hook remove PreToolUse --name drop`)
+
+	hs := store.Config().Hooks[hooks.EventPreToolUse]
+	require.Len(t, hs, 1)
+	require.Equal(t, "keep", hs[0].Name)
+}
+
+func TestShellConfigHookClearEvent(t *testing.T) {
+	store := loadCrushSh(t, `hook add PreToolUse --command a --name a
+hook add PreToolUse --command b --name b
+hook remove PreToolUse`)
+
+	require.Empty(t, store.Config().Hooks[hooks.EventPreToolUse])
+}

internal/config/shellconfig_lsp_test.go

@@ -0,0 +1,28 @@
+package config_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestShellConfigLSPAdd(t *testing.T) {
+	store := loadCrushSh(t, `lsp add gopls --command gopls --filetypes go --filetypes mod --root-markers go.mod --timeout 60`)
+
+	l, ok := store.Config().LSP["gopls"]
+	require.True(t, ok, "gopls LSP should be configured")
+	require.Equal(t, "gopls", l.Command)
+	require.Subset(t, l.FileTypes, []string{"go", "mod"})
+	require.Contains(t, l.RootMarkers, "go.mod")
+	require.Equal(t, 60, l.Timeout)
+}
+
+func TestShellConfigLSPRemove(t *testing.T) {
+	store := loadCrushSh(t, `lsp add keepls --command keep-server
+lsp add dropls --command drop-server
+lsp remove dropls`)
+
+	lsps := store.Config().LSP
+	require.Contains(t, lsps, "keepls")
+	require.NotContains(t, lsps, "dropls")
+}

internal/config/shellconfig_option_test.go

@@ -0,0 +1,134 @@
+package config_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestShellConfigOptionBooleans(t *testing.T) {
+	store := loadCrushSh(t, `option debug true
+option progress false
+option auto-lsp false`)
+
+	opts := store.Config().Options
+	require.True(t, opts.Debug, "debug should be on")
+	require.NotNil(t, opts.Progress)
+	require.False(t, *opts.Progress, "progress should be off")
+	require.NotNil(t, opts.AutoLSP)
+	require.False(t, *opts.AutoLSP, "auto-lsp should be off")
+}
+
+// Config phrases this field negatively (disable_metrics) but the command
+// exposes it positively. "metrics false" must land as disable_metrics = true.
+func TestShellConfigOptionPositiveMetricsFalse(t *testing.T) {
+	store := loadCrushSh(t, `option metrics false`)
+	require.True(t, store.Config().Options.DisableMetrics, "metrics off => disable_metrics true")
+}
+
+// The bare positive form defaults to true, which inverts to disable = false.
+func TestShellConfigOptionPositiveMetricsBare(t *testing.T) {
+	store := loadCrushSh(t, `option metrics`)
+	require.False(t, store.Config().Options.DisableMetrics, "metrics on => disable_metrics false")
+}
+
+func TestShellConfigOptionUI(t *testing.T) {
+	store := loadCrushSh(t, `option ui compact true
+option ui diff split
+option ui transparent false
+option ui mouse false
+option ui scrollbar always
+option ui completions-max-depth 4
+option ui completions-max-items 200`)
+
+	ui := store.Config().Options.TUI
+	require.NotNil(t, ui)
+	require.True(t, ui.CompactMode)
+	require.Equal(t, "split", ui.DiffMode)
+	require.NotNil(t, ui.Transparent)
+	require.False(t, *ui.Transparent)
+	require.NotNil(t, ui.Mouse)
+	require.False(t, *ui.Mouse)
+	require.Equal(t, "always", ui.Scrollbar)
+	require.NotNil(t, ui.Completions.MaxDepth)
+	require.Equal(t, 4, *ui.Completions.MaxDepth)
+	require.NotNil(t, ui.Completions.MaxItems)
+	require.Equal(t, 200, *ui.Completions.MaxItems)
+}
+
+func TestShellConfigOptionUIRejectsInvalidValue(t *testing.T) {
+	_, err := loadCrushShErr(t, `option ui diff side-by-side`)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "expects unified or split")
+}
+
+func TestShellConfigOptionAttribution(t *testing.T) {
+	store := loadCrushSh(t, `option attribution-trailer-style none
+option attribution-generated-with false`)
+
+	attribution := store.Config().Options.Attribution
+	require.NotNil(t, attribution)
+	require.Equal(t, "none", string(attribution.TrailerStyle))
+	require.False(t, attribution.GeneratedWith)
+}
+
+func TestShellConfigOptionAttributionTrailerStylePreservesGeneratedWithDefault(t *testing.T) {
+	store := loadCrushSh(t, `option attribution-trailer-style co-authored-by`)
+
+	attribution := store.Config().Options.Attribution
+	require.NotNil(t, attribution)
+	require.Equal(t, "co-authored-by", string(attribution.TrailerStyle))
+	require.True(t, attribution.GeneratedWith)
+}
+
+func TestShellConfigOptionAttributionGeneratedWithCaseInsensitive(t *testing.T) {
+	store := loadCrushSh(t, `option attribution-generated-with YES`)
+
+	require.NotNil(t, store.Config().Options.Attribution)
+	require.True(t, store.Config().Options.Attribution.GeneratedWith)
+}
+
+func TestShellConfigOptionAttributionRejectsInvalidStyle(t *testing.T) {
+	_, err := loadCrushShErr(t, `option attribution-trailer-style bogus`)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "expects none, co-authored-by, or assisted-by")
+}
+
+func TestShellConfigOptionListAppends(t *testing.T) {
+	store := loadCrushSh(t, `option disable-skill crush-config
+option disable-skill jq`)
+
+	require.Subset(t, store.Config().Options.DisabledSkills, []string{"crush-config", "jq"})
+}
+
+// reset wipes values added earlier (or via source) while keeping anything
+// added after it — observable in the effective config.
+func TestShellConfigOptionReset(t *testing.T) {
+	store := loadCrushSh(t, `option skill-path ./inherited-a
+option skill-path ./inherited-b
+option reset skill-path
+option skill-path ./mine`)
+
+	paths := store.Config().Options.SkillsPaths
+	require.Contains(t, paths, "./mine")
+	require.NotContains(t, paths, "./inherited-a")
+	require.NotContains(t, paths, "./inherited-b")
+}
+
+func TestShellConfigOptionUnknownKeyFails(t *testing.T) {
+	_, err := loadCrushShErr(t, `option bogus-key value`)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "unknown key")
+}
+
+func TestShellConfigOptionDisableToolRemoved(t *testing.T) {
+	_, err := loadCrushShErr(t, `option disable-tool bash`)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "unknown key")
+}
+
+func TestShellConfigOptionResetRejectsNonList(t *testing.T) {
+	_, err := loadCrushShErr(t, `option reset debug`)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "not one")
+}

internal/config/shellconfig_precedence_test.go

@@ -0,0 +1,35 @@
+package config_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/stretchr/testify/require"
+)
+
+// TestShellConfigDotCrushrcTakesPrecedence verifies that a project-local
+// .crushrc overrides crushrc in the same directory on conflicting settings.
+func TestShellConfigDotCrushrcTakesPrecedence(t *testing.T) {
+	isolated := t.TempDir()
+	t.Setenv("HOME", isolated)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(isolated, ".config"))
+	t.Setenv("XDG_DATA_HOME", filepath.Join(isolated, ".local", "share"))
+
+	workDir := t.TempDir()
+	dataDir := t.TempDir()
+	require.NoError(t, os.WriteFile(
+		filepath.Join(workDir, "crushrc"),
+		[]byte("option notifications bell\n"), 0o644,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(workDir, ".crushrc"),
+		[]byte("option notifications osc\n"), 0o644,
+	))
+
+	store, err := config.Load(workDir, dataDir, false)
+	require.NoError(t, err)
+	require.Equal(t, "osc", store.Config().Options.Notifications,
+		".crushrc should win over crushrc")
+}

internal/config/shellconfig_provider_test.go

@@ -0,0 +1,85 @@
+package config_test
+
+import (
+	"slices"
+	"testing"
+
+	"charm.land/catwalk/pkg/catwalk"
+	"github.com/charmbracelet/crush/internal/config"
+	"github.com/stretchr/testify/require"
+)
+
+func TestShellConfigProviderAddAndModel(t *testing.T) {
+	store := loadCrushSh(t, `provider add myllm \
+  --type openai-compat \
+  --base-url "http://localhost:1234/v1" \
+  --api-key "sk-test" \
+  --discover-models false \
+  --extra-body '{"service_tier":"flex"}' \
+  --provider-options '{"region":"local"}'
+provider add myllm \
+  --extra-body '{"stream":true}' \
+  --provider-options '{"mode":"test"}'
+model add myllm/foo-1 --name "Foo 1" --context-window 8000 \
+  --price-input 1.25 --price-output 5 \
+  --price-cache-create 2 --price-cache-hit 0.25
+model large myllm/foo-1 \
+  --top-p 0.9 --top-k 40 \
+  --frequency-penalty 0.2 --presence-penalty 0.1 \
+  --provider-options '{"routing":{"tier":"fast"}}'
+model large myllm/foo-1 --provider-options '{"timeout":30}'`)
+
+	cfg := store.Config()
+
+	p, ok := cfg.Providers.Get("myllm")
+	require.True(t, ok, "myllm provider should be configured")
+	require.Equal(t, "sk-test", p.APIKey)
+	require.Equal(t, "http://localhost:1234/v1", p.BaseURL)
+	require.NotNil(t, p.AutoDiscoverModels)
+	require.False(t, *p.AutoDiscoverModels)
+	require.Equal(t, "flex", p.ExtraBody["service_tier"])
+	require.Equal(t, true, p.ExtraBody["stream"])
+	require.Equal(t, "local", p.ProviderOptions["region"])
+	require.Equal(t, "test", p.ProviderOptions["mode"])
+	require.True(
+		t,
+		slices.ContainsFunc(p.Models, func(m catwalk.Model) bool { return m.ID == "foo-1" }),
+		"custom model foo-1 should be in the provider catalog",
+	)
+	model := p.Models[0]
+	require.Equal(t, 1.25, model.CostPer1MIn)
+	require.Equal(t, 5.0, model.CostPer1MOut)
+	require.Equal(t, 2.0, model.CostPer1MInCached)
+	require.Equal(t, 0.25, model.CostPer1MOutCached)
+
+	large := cfg.Models[config.SelectedModelTypeLarge]
+	require.Equal(t, "myllm", large.Provider)
+	require.Equal(t, "foo-1", large.Model)
+	require.NotNil(t, large.TopP)
+	require.Equal(t, 0.9, *large.TopP)
+	require.NotNil(t, large.TopK)
+	require.Equal(t, int64(40), *large.TopK)
+	require.NotNil(t, large.FrequencyPenalty)
+	require.Equal(t, 0.2, *large.FrequencyPenalty)
+	require.NotNil(t, large.PresencePenalty)
+	require.Equal(t, 0.1, *large.PresencePenalty)
+	require.Equal(t, map[string]any{
+		"routing": map[string]any{"tier": "fast"},
+		"timeout": float64(30),
+	}, large.ProviderOptions)
+}
+
+func TestShellConfigProviderRemove(t *testing.T) {
+	// Both providers get a model so they survive provider configuration
+	// (model-less providers are dropped); the only difference is the remove.
+	store := loadCrushSh(t, `provider add keepme --type openai-compat --base-url "http://localhost:1/v1" --api-key k
+model add keepme/m1 --name M1
+provider add dropme --type openai-compat --base-url "http://localhost:2/v1" --api-key k
+model add dropme/m2 --name M2
+provider remove dropme`)
+
+	_, keep := store.Config().Providers.Get("keepme")
+	_, drop := store.Config().Providers.Get("dropme")
+	require.True(t, keep, "keepme should remain")
+	require.False(t, drop, "dropme should be gone after remove")
+}

internal/config/store.go

@@ -0,0 +1,1430 @@
+package config
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"maps"
+	"os"
+	"path/filepath"
+	"slices"
+	"sync"
+	"time"
+
+	"charm.land/catwalk/pkg/catwalk"
+	hyperp "github.com/charmbracelet/crush/internal/agent/hyper"
+	"github.com/charmbracelet/crush/internal/env"
+	"github.com/charmbracelet/crush/internal/lock"
+	"github.com/charmbracelet/crush/internal/oauth"
+	"github.com/charmbracelet/crush/internal/oauth/copilot"
+	"github.com/charmbracelet/crush/internal/oauth/hyper"
+	"github.com/charmbracelet/crush/internal/oauth/openai"
+	"github.com/tidwall/gjson"
+	"github.com/tidwall/sjson"
+	"golang.org/x/sync/singleflight"
+)
+
+// configLockDeadline bounds how long lockConfig waits for the
+// cross-process flock before giving up. A few seconds is plenty for
+// honest contention; longer suggests something is wedged.
+const configLockDeadline = 5 * time.Second
+
+// refreshLockDeadline bounds how long RefreshOAuthToken waits for the
+// per-provider cross-process refresh lock. It must exceed the token
+// exchange HTTP timeout (30s) so that a peer mid-exchange is given time
+// to finish and publish its result, which we then adopt instead of
+// running our own exchange. Running our own would reuse an
+// already-rotated refresh token and trip the provider's reuse detection,
+// revoking the whole token family.
+const refreshLockDeadline = 45 * time.Second
+
+// credentialWriteLockDeadline bounds how long a credential write (e.g.
+// storing the token from a fresh interactive login) waits for the
+// per-provider refresh lock. It is deliberately shorter than
+// refreshLockDeadline because a user is watching: if a peer is wedged we
+// would rather write and risk a rare clobber than hang the UI.
+const credentialWriteLockDeadline = 10 * time.Second
+
+// fileSnapshot captures metadata about a config file at a point in time.
+type fileSnapshot struct {
+	Path    string
+	Exists  bool
+	Size    int64
+	ModTime int64 // UnixNano
+}
+
+// RuntimeOverrides holds per-session settings that are never persisted to
+// disk. They are applied on top of the loaded Config and survive only for
+// the lifetime of the process (or workspace).
+type RuntimeOverrides struct {
+	SkipPermissionRequests bool
+	// EnabledChannels lists the MCP servers opted in as channels for this
+	// session (via the --channels flag). A server present in MCP config only
+	// pushes channel events when it also appears here. Entries may be written
+	// as "server:<name>" or as a bare "<name>".
+	EnabledChannels []string
+	// Models records the model choices made in this instance, whether
+	// persisted or not. They are reapplied after a config reload so that a
+	// selection made here always outranks whatever the shared config file
+	// happens to hold — see pinPreferredModelLocked.
+	Models map[SelectedModelType]SelectedModel
+}
+
+// ConfigStore is the single entry point for all config access. It owns the
+// pure-data Config, runtime state (working directory, resolver, known
+// providers), and persistence to both global and workspace config files.
+//
+// mu serialises all config file mutations (SetConfigFields,
+// RemoveConfigField, RefreshOAuthToken) to prevent both in-process
+// goroutine races and, together with the shared lock.File, cross-process
+// races on the config file.
+//
+// writeMu serialises every operation that produces a new in-memory Config:
+// the typed copy-on-write mutators (SetCompactMode, UpdatePreferredModel,
+// ...) and ReloadFromDisk. Typed mutators take Lock; autoReload takes
+// TryLock so a write triggered re-entrantly during a reload (e.g.
+// configureProviders calling RemoveConfigField) skips the nested reload
+// instead of deadlocking. This is what lets published Configs be treated
+// as immutable: a mutator clones, mutates the clone, and swaps it in under
+// writeMu rather than mutating the live Config in place.
+type ConfigStore struct {
+	config             *Config
+	workingDir         string
+	resolver           VariableResolver
+	globalDataPath     string   // ~/.local/share/crush/crush.json
+	workspacePath      string   // .crush/crush.json
+	loadedPaths        []string // config files that were successfully loaded
+	knownProviders     []catwalk.Provider
+	overrides          RuntimeOverrides
+	trackedConfigPaths []string                // unique, normalized config file paths
+	snapshots          map[string]fileSnapshot // path -> snapshot at last capture
+
+	// configMu guards the config pointer field against concurrent
+	// readers (Config) and the writeMu-serialised swap (setConfig). It
+	// protects the pointer word only; the pointed-to Config is treated
+	// as immutable once published, since both reloads and typed mutators
+	// build a fresh Config rather than mutating the live one.
+	configMu sync.RWMutex
+
+	mu      sync.Mutex   // serialises config file writes
+	writeMu sync.RWMutex // serialises in-memory config production (mutators + reload); RLock for readers
+
+	// refreshSF collapses concurrent in-process OAuth refreshes for the
+	// same provider into a single attempt. Combined with the per-provider
+	// cross-process refresh lock, it ensures only one token exchange runs
+	// at a time. See RefreshOAuthToken.
+	refreshSF singleflight.Group
+
+	// exchangeToken performs the provider-specific OAuth token exchange.
+	// It is a field so tests can substitute a fake exchange without making
+	// real network calls. Production code leaves it nil, and exchange falls
+	// back to the real provider clients.
+	exchangeToken func(ctx context.Context, providerID, refreshToken string) (*oauth.Token, error)
+
+	// fetchOpenAIModels fetches the ChatGPT model catalog. A field for the
+	// same reason as exchangeToken: tests stub it to avoid network calls,
+	// production leaves it nil and refetchOpenAIModels calls the real one.
+	fetchOpenAIModels func(ctx context.Context, token *oauth.Token) ([]catwalk.Model, error)
+
+	// authSignalMu guards authSignals, which maps provider IDs to
+	// channels that WaitForTokenChange blocks on. SignalAuthComplete
+	// closes the channel to unblock waiters; a new channel is created
+	// on the next wait.
+	authSignalMu sync.Mutex
+	authSignals  map[string]chan struct{}
+}
+
+// Config returns the pure-data config struct (read-only after load).
+//
+// The pointer read is guarded by configMu so it can never tear against
+// the reload swap in reloadFromDiskLocked. Reloads build a brand-new
+// Config and swap it in rather than mutating the live one, so holding the
+// returned pointer stays safe even across a concurrent reload — the reader
+// keeps reading its (now immutable) snapshot.
+func (s *ConfigStore) Config() *Config {
+	s.configMu.RLock()
+	defer s.configMu.RUnlock()
+	return s.config
+}
+
+// setConfig atomically swaps the active config pointer under configMu.
+// Used by the reload path; in-place field mutators leave the pointer
+// untouched and run under mu instead.
+func (s *ConfigStore) setConfig(cfg *Config) {
+	s.configMu.Lock()
+	defer s.configMu.Unlock()
+	s.config = cfg
+}
+
+// WorkingDir returns the current working directory.
+func (s *ConfigStore) WorkingDir() string {
+	return s.workingDir
+}
+
+// Resolver returns the variable resolver.
+func (s *ConfigStore) Resolver() VariableResolver {
+	s.writeMu.RLock()
+	defer s.writeMu.RUnlock()
+	return s.resolver
+}
+
+// Resolve resolves a variable reference using the configured resolver.
+func (s *ConfigStore) Resolve(key string) (string, error) {
+	s.writeMu.RLock()
+	r := s.resolver
+	s.writeMu.RUnlock()
+	if r == nil {
+		return "", fmt.Errorf("no variable resolver configured")
+	}
+	return r.ResolveValue(key)
+}
+
+// KnownProviders returns the list of known providers.
+func (s *ConfigStore) KnownProviders() []catwalk.Provider {
+	s.writeMu.RLock()
+	defer s.writeMu.RUnlock()
+	return s.knownProviders
+}
+
+// RefetchHyperProvider re-fetches the Hyper provider catalog from the
+// remote API and updates the in-memory known providers list and config.
+// This is called after OAuth authentication completes so the latest
+// models are available without restarting.
+func (s *ConfigStore) RefetchHyperProvider(ctx context.Context) error {
+	// Build a fresh client that reads the API key from the live config,
+	// not the stale snapshot captured at startup. The syncer's original
+	// client closes over the startup config and would send an expired
+	// token after OAuth re-authentication.
+	freshClient := realHyperClient{
+		baseURL:    hyperp.BaseURL(),
+		resolveKey: func() string { return resolveHyperAPIKey(s.Config()) },
+	}
+	hyperSyncer.SetClient(freshClient)
+
+	hyperProvider, err := hyperSyncer.Refetch(ctx)
+	if err != nil {
+		return fmt.Errorf("failed to refetch Hyper provider: %w", err)
+	}
+	if hyperProvider.ID == "" {
+		return nil
+	}
+
+	s.writeMu.Lock()
+	defer s.writeMu.Unlock()
+
+	// Replace or insert the Hyper entry in knownProviders.
+	found := false
+	for i, p := range s.knownProviders {
+		if string(p.ID) == string(hyperProvider.ID) {
+			s.knownProviders[i] = hyperProvider
+			found = true
+			break
+		}
+	}
+	if !found {
+		s.knownProviders = append([]catwalk.Provider{hyperProvider}, s.knownProviders...)
+	}
+
+	// Update the Hyper provider config with the refreshed model list
+	// and endpoint. Use cloneForWrite so readers always see a consistent
+	// snapshot (the store's contract forbids in-place config mutation).
+	nc := s.config.cloneForWrite()
+	if pc, ok := nc.Providers.Get(string(hyperProvider.ID)); ok {
+		pc.Models = hyperProvider.Models
+		if hyperProvider.APIEndpoint != "" {
+			pc.BaseURL = hyperProvider.APIEndpoint
+		}
+		nc.Providers.Set(string(hyperProvider.ID), pc)
+	}
+	s.setConfig(nc)
+
+	// Also update the memoized provider list so callers of
+	// config.Providers() (e.g. the models dialog) see fresh data.
+	UpdateProviderInList(hyperProvider)
+
+	s.SetupAgents()
+	return nil
+}
+
+// SetupAgents configures the coder and task agents on the config.
+func (s *ConfigStore) SetupAgents() {
+	s.Config().SetupAgents()
+}
+
+// Overrides returns the runtime overrides for this store.
+func (s *ConfigStore) Overrides() *RuntimeOverrides {
+	s.writeMu.RLock()
+	defer s.writeMu.RUnlock()
+	return &s.overrides
+}
+
+// LoadedPaths returns the config file paths that were successfully loaded.
+func (s *ConfigStore) LoadedPaths() []string {
+	s.writeMu.RLock()
+	defer s.writeMu.RUnlock()
+	return slices.Clone(s.loadedPaths)
+}
+
+// lockConfig acquires both the in-process mutex and a cross-process flock
+// on the config file for the given scope. Callers that need to do I/O
+// between reading and writing (e.g. an HTTP token exchange) must use
+// lockConfig explicitly rather than atomicWrite.
+//
+// The returned release function drops both locks. Callers must call it
+// as soon as the file access is complete — no I/O should be performed
+// while the lock is held.
+func (s *ConfigStore) lockConfig(scope Scope) (func(), error) {
+	s.mu.Lock()
+	path, err := s.configPath(scope)
+	if err != nil {
+		s.mu.Unlock()
+		return nil, err
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		s.mu.Unlock()
+		return nil, fmt.Errorf("create config directory: %w", err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), configLockDeadline)
+	defer cancel()
+	release, err := lock.File(ctx, path+".lock")
+	if err != nil {
+		s.mu.Unlock()
+		return nil, fmt.Errorf("acquire config lock: %w", err)
+	}
+	return func() {
+		release()
+		s.mu.Unlock()
+	}, nil
+}
+
+// atomicWrite handles the lock-read-transform-write-unlock cycle for
+// config file mutations. The fn callback receives the current file
+// contents (raw bytes, or {} if the file is missing) and must return the
+// new contents. fn must be pure — no I/O, no network calls.
+func (s *ConfigStore) atomicWrite(scope Scope, fn func(current []byte) ([]byte, error)) error {
+	unlock, err := s.lockConfig(scope)
+	if err != nil {
+		return err
+	}
+	defer unlock()
+
+	path, err := s.configPath(scope)
+	if err != nil {
+		return err
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			data = []byte("{}")
+		} else {
+			return fmt.Errorf("read config file: %w", err)
+		}
+	}
+
+	newData, err := fn(data)
+	if err != nil {
+		return err
+	}
+
+	return atomicWriteFile(path, newData, 0o600)
+}
+
+// configPath returns the file path for the given scope.
+func (s *ConfigStore) configPath(scope Scope) (string, error) {
+	switch scope {
+	case ScopeWorkspace:
+		if s.workspacePath == "" {
+			return "", ErrNoWorkspaceConfig
+		}
+		return s.workspacePath, nil
+	default:
+		return s.globalDataPath, nil
+	}
+}
+
+// HasConfigField checks whether a key exists in the config file for the given
+// scope.
+func (s *ConfigStore) HasConfigField(scope Scope, key string) bool {
+	path, err := s.configPath(scope)
+	if err != nil {
+		return false
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return false
+	}
+	return gjson.Get(string(data), key).Exists()
+}
+
+// SetConfigField sets a key/value pair in the config file for the given scope.
+// After a successful write, it automatically reloads config to keep in-memory
+// state fresh.
+func (s *ConfigStore) SetConfigField(scope Scope, key string, value any) error {
+	return s.SetConfigFields(scope, map[string]any{key: value})
+}
+
+// SetConfigFields sets multiple key/value pairs in the config file for the
+// given scope in a single write, then reloads in-memory state from disk.
+//
+// Use this for arbitrary external edits where the in-memory effect of the
+// change is not known ahead of time. The typed mutators (which know exactly
+// what changed) go through update instead and skip the reload.
+//
+// The write is protected by an in-process mutex and a cross-process flock
+// to prevent races between concurrent writers in different processes.
+func (s *ConfigStore) SetConfigFields(scope Scope, kv map[string]any) error {
+	if err := s.writeConfigFields(scope, kv); err != nil {
+		return err
+	}
+	// Auto-reload to keep in-memory state fresh after config edits.
+	// We use context.Background() since this is an internal operation that
+	// shouldn't be cancelled by user context.
+	if err := s.autoReload(context.Background()); err != nil {
+		// Log warning but don't fail the write - disk is already updated.
+		slog.Warn("Config file updated but failed to reload in-memory state", "error", err)
+	}
+	return nil
+}
+
+// writeConfigFields persists key/value pairs to the config file. It does not
+// touch in-memory config state or the staleness snapshot: callers either
+// reload (SetConfigFields, whose reload recaptures the snapshot) or have
+// already published an updated clone and capture the snapshot themselves
+// (update). Both of those run under writeMu, which is what keeps the
+// snapshot map free of concurrent writers.
+func (s *ConfigStore) writeConfigFields(scope Scope, kv map[string]any) error {
+	// Sort keys for deterministic output regardless of map iteration
+	// order. This also ensures consistent results when callers pass
+	// overlapping JSONPath keys (e.g. "a" and "a.b").
+	keys := make([]string, 0, len(kv))
+	for k := range kv {
+		keys = append(keys, k)
+	}
+	slices.Sort(keys)
+
+	return s.atomicWrite(scope, func(data []byte) ([]byte, error) {
+		v := string(data)
+		for _, key := range keys {
+			var sErr error
+			if v, sErr = sjson.Set(v, key, kv[key]); sErr != nil {
+				return nil, fmt.Errorf("failed to set config field %s: %w", key, sErr)
+			}
+		}
+		return []byte(v), nil
+	})
+}
+
+// mutateInMemory applies a copy-on-write change to the config without
+// persisting. Under writeMu it clones the live config, lets mutate edit the
+// clone, and publishes it. This is the single primitive every in-memory
+// config change goes through, so a published Config is never mutated in
+// place and readers always see a consistent snapshot.
+func (s *ConfigStore) mutateInMemory(mutate func(*Config)) {
+	s.writeMu.Lock()
+	defer s.writeMu.Unlock()
+
+	nc := s.Config().cloneForWrite()
+	mutate(nc)
+	s.setConfig(nc)
+}
+
+// update applies a copy-on-write change and persists the reported fields.
+// mutate edits the clone and returns the JSON-path fields to write to disk;
+// because the clone already reflects the change, no reload is needed.
+// Returning an empty map publishes the clone without a disk write.
+func (s *ConfigStore) update(scope Scope, mutate func(*Config) map[string]any) error {
+	s.writeMu.Lock()
+	defer s.writeMu.Unlock()
+	return s.updateLocked(scope, mutate)
+}
+
+// updateLocked is the lock-free core of update. Caller must hold writeMu.
+func (s *ConfigStore) updateLocked(scope Scope, mutate func(*Config) map[string]any) error {
+	nc := s.Config().cloneForWrite()
+	fields := mutate(nc)
+	s.setConfig(nc)
+	if len(fields) == 0 {
+		return nil
+	}
+	if err := s.writeConfigFields(scope, fields); err != nil {
+		return err
+	}
+	// Refresh the staleness snapshot so the file watcher does not treat
+	// our own write as an external change. Safe to touch the snapshot map
+	// here because we hold writeMu.
+	if path, err := s.configPath(scope); err == nil {
+		s.captureStalenessSnapshot(append(slices.Clone(s.loadedPaths), path))
+	}
+	return nil
+}
+
+// OverridePreferredModel sets the preferred model for the given type in
+// memory only, without persisting. It is for per-run overrides (such as the
+// non-interactive --model flags) that must not be written to the user's
+// config file.
+func (s *ConfigStore) OverridePreferredModel(modelType SelectedModelType, model SelectedModel) {
+	s.mutateInMemory(func(c *Config) {
+		if c.Models == nil {
+			c.Models = make(map[SelectedModelType]SelectedModel)
+		}
+		c.Models[modelType] = model
+		s.pinPreferredModelLocked(modelType, model)
+	})
+}
+
+// pinPreferredModelLocked records a model choice made in this instance so
+// that a later config reload cannot replace it with a choice made
+// somewhere else. Several Crush instances share one global config file, so
+// a reload triggered by an unrelated write (a token refresh, say) would
+// otherwise import whichever model a sibling instance last selected and
+// switch models out from under the user mid-session.
+//
+// Caller must hold writeMu.
+func (s *ConfigStore) pinPreferredModelLocked(modelType SelectedModelType, model SelectedModel) {
+	if s.overrides.Models == nil {
+		s.overrides.Models = make(map[SelectedModelType]SelectedModel)
+	}
+	s.overrides.Models[modelType] = model
+}
+
+// RemoveConfigField removes a key from the config file for the given scope.
+// After a successful write, it automatically reloads config to keep in-memory
+// state fresh.
+//
+// The write is protected by an in-process mutex and a cross-process flock.
+func (s *ConfigStore) RemoveConfigField(scope Scope, key string) error {
+	err := s.atomicWrite(scope, func(data []byte) ([]byte, error) {
+		v, sErr := sjson.Delete(string(data), key)
+		if sErr != nil {
+			return nil, fmt.Errorf("failed to delete config field %s: %w", key, sErr)
+		}
+		return []byte(v), nil
+	})
+	if err != nil {
+		return err
+	}
+
+	if err := s.autoReload(context.Background()); err != nil {
+		slog.Warn("Config file updated but failed to reload in-memory state", "error", err)
+	}
+
+	return nil
+}
+
+// UpdatePreferredModel updates the preferred model for the given type and
+// persists it to the config file at the given scope. The selected model and
+// the recent-models list are written together in a single config write.
+//
+// The write skips the full disk reparse/reload (which would rebuild the
+// provider catalog and agents on every model switch and dominate selection
+// latency); agents are refreshed separately by the caller (see
+// UpdateAgentModel).
+func (s *ConfigStore) UpdatePreferredModel(scope Scope, modelType SelectedModelType, model SelectedModel) error {
+	return s.update(scope, func(c *Config) map[string]any {
+		return s.updatePreferredModelFields(c, modelType, model)
+	})
+}
+
+// updatePreferredModelFields builds the fields map for persisting a preferred
+// model change. Shared between UpdatePreferredModel and direct updateLocked
+// callers (e.g. Load). Caller must hold writeMu.
+func (s *ConfigStore) updatePreferredModelFields(c *Config, modelType SelectedModelType, model SelectedModel) map[string]any {
+	if c.Models == nil {
+		c.Models = make(map[SelectedModelType]SelectedModel)
+	}
+	c.Models[modelType] = model
+	s.pinPreferredModelLocked(modelType, model)
+
+	fields := map[string]any{
+		fmt.Sprintf("models.%s", modelType): model,
+	}
+	if updated, changed := nextRecentModels(c, modelType, model); changed {
+		if c.RecentModels == nil {
+			c.RecentModels = make(map[SelectedModelType][]SelectedModel)
+		}
+		c.RecentModels[modelType] = updated
+		fields[fmt.Sprintf("recent_models.%s", modelType)] = updated
+	}
+	return fields
+}
+
+// SetCompactMode sets the compact mode setting and persists it.
+func (s *ConfigStore) SetCompactMode(scope Scope, enabled bool) error {
+	return s.update(scope, func(c *Config) map[string]any {
+		c.ensureTUI().CompactMode = enabled
+		return map[string]any{"options.tui.compact_mode": enabled}
+	})
+}
+
+// SetTransparentBackground sets the transparent background setting and persists it.
+func (s *ConfigStore) SetTransparentBackground(scope Scope, enabled bool) error {
+	return s.update(scope, func(c *Config) map[string]any {
+		c.ensureTUI().Transparent = &enabled
+		return map[string]any{"options.tui.transparent": enabled}
+	})
+}
+
+// SetProviderAPIKey sets the API key for a provider and persists it.
+// The OpenAI provider holds exactly one credential: storing a ChatGPT
+// token removes a previously entered API key, and storing an API key
+// removes a previous ChatGPT login.
+func (s *ConfigStore) SetProviderAPIKey(scope Scope, providerID string, apiKey any) error {
+	var providerConfig ProviderConfig
+	var exists bool
+	var setKeyOrToken func()
+	isToken := false
+
+	switch v := apiKey.(type) {
+	case string:
+		if err := s.SetConfigField(scope, fmt.Sprintf("providers.%s.api_key", providerID), v); err != nil {
+			return fmt.Errorf("failed to save api key to config file: %w", err)
+		}
+		setKeyOrToken = func() {
+			providerConfig.APIKey = v
+			if providerID == string(catwalk.InferenceProviderOpenAI) {
+				// Either OAuth or an API key, never both: the login
+				// leaves nothing usable on the API-key side behind.
+				providerConfig.OAuthToken = nil
+				providerConfig.ChatGPTModels = nil
+			}
+		}
+		if providerID == string(catwalk.InferenceProviderOpenAI) {
+			// Either OAuth or an API key, never both: the new key
+			// leaves nothing usable on the ChatGPT side behind.
+			if err := s.RemoveConfigField(scope, fmt.Sprintf("providers.%s.oauth", providerID)); err != nil {
+				return err
+			}
+			if err := s.RemoveConfigField(scope, fmt.Sprintf("providers.%s.chatgpt_models", providerID)); err != nil {
+				return err
+			}
+		}
+	case *oauth.Token:
+		// Hold the refresh lock across the write so a peer's in-flight
+		// token exchange cannot land on top of a credential the user just
+		// obtained interactively — which would silently invalidate the
+		// login they only just completed.
+		fields := map[string]any{
+			fmt.Sprintf("providers.%s.oauth", providerID): v,
+		}
+		if providerID != string(catwalk.InferenceProviderOpenAI) {
+			fields[fmt.Sprintf("providers.%s.api_key", providerID)] = v.AccessToken
+		}
+		if err := s.withRefreshLock(providerID, func() error {
+			return s.SetConfigFields(scope, fields)
+		}); err != nil {
+			return err
+		}
+		if providerID == string(catwalk.InferenceProviderOpenAI) {
+			// Either OAuth or an API key, never both: the login retires
+			// any key that came before it.
+			if err := s.RemoveConfigField(scope, fmt.Sprintf("providers.%s.api_key", providerID)); err != nil {
+				return err
+			}
+		}
+		setKeyOrToken = func() {
+			providerConfig.OAuthToken = v
+			if providerID == string(catwalk.InferenceProviderOpenAI) {
+				isToken = true
+				providerConfig.APIKey = ""
+				return
+			}
+			providerConfig.APIKey = v.AccessToken
+			if providerID == string(catwalk.InferenceProviderCopilot) {
+				providerConfig.SetupGitHubCopilot()
+			}
+		}
+	}
+
+	cfg := s.Config()
+	providerConfig, exists = cfg.Providers.Get(providerID)
+	if exists {
+		setKeyOrToken()
+		cfg.Providers.Set(providerID, providerConfig)
+	} else {
+		var foundProvider *catwalk.Provider
+		for _, p := range s.knownProviders {
+			if string(p.ID) == providerID {
+				foundProvider = &p
+				break
+			}
+		}
+
+		if foundProvider != nil {
+			providerConfig = ProviderConfig{
+				ID:           providerID,
+				Name:         foundProvider.Name,
+				BaseURL:      foundProvider.APIEndpoint,
+				Type:         foundProvider.Type,
+				Disable:      false,
+				ExtraHeaders: make(map[string]string),
+				ExtraParams:  make(map[string]string),
+				Models:       foundProvider.Models,
+			}
+			setKeyOrToken()
+		} else {
+			return fmt.Errorf("provider with ID %s not found in known providers", providerID)
+		}
+		cfg.Providers.Set(providerID, providerConfig)
+	}
+
+	// After authenticating with Hyper, re-fetch the provider catalog so
+	// the latest models are available without restarting.
+	if providerID == "hyper" {
+		if refetchErr := s.RefetchHyperProvider(context.Background()); refetchErr != nil {
+			slog.Warn("Failed to refetch Hyper provider after auth", "error", refetchErr)
+		}
+	}
+	// After authenticating with a ChatGPT account, fetch the Codex model
+	// catalog the subscription grants and persist it so the models
+	// dialog can offer it beside the API-key catalog.
+	if providerID == string(catwalk.InferenceProviderOpenAI) && isToken {
+		s.refetchOpenAIModels(context.Background(), scope)
+	}
+	return nil
+}
+
+// refetchOpenAIModels stores the Codex model catalog the ChatGPT plan
+// grants next to the provider's API-key models. Best effort: a failure
+// leaves the existing catalog in place and the login still succeeds.
+func (s *ConfigStore) refetchOpenAIModels(ctx context.Context, scope Scope) {
+	cfg := s.Config()
+	pc, ok := cfg.Providers.Get(string(catwalk.InferenceProviderOpenAI))
+	if !ok || pc.OAuthToken == nil {
+		return
+	}
+	fetchModels := s.fetchOpenAIModels
+	if fetchModels == nil {
+		fetchModels = openai.Models
+	}
+	models, err := fetchModels(ctx, pc.OAuthToken)
+	if err != nil {
+		slog.Warn("Failed to fetch ChatGPT model catalog after auth", "error", err)
+		return
+	}
+	if err := s.update(scope, func(c *Config) map[string]any {
+		p, ok := c.Providers.Get(string(catwalk.InferenceProviderOpenAI))
+		if !ok {
+			return nil
+		}
+		p.ChatGPTModels = models
+		c.Providers.Set(string(catwalk.InferenceProviderOpenAI), p)
+		return map[string]any{
+			"providers.openai.chatgpt_models": models,
+		}
+	}); err != nil {
+		slog.Warn("Failed to persist ChatGPT model catalog", "error", err)
+	}
+}
+
+// RefetchOpenAIChatGPTModels fills in the ChatGPT model catalog when the
+// OpenAI provider is signed in but has none — because the fetch at login
+// time failed, or the credentials predate the catalog. A no-op once the
+// catalog exists, so callers can invoke it freely on model updates.
+func (s *ConfigStore) RefetchOpenAIChatGPTModels(ctx context.Context) {
+	cfg := s.Config()
+	pc, ok := cfg.Providers.Get(string(catwalk.InferenceProviderOpenAI))
+	if !ok || pc.OAuthToken == nil || len(pc.ChatGPTModels) > 0 {
+		return
+	}
+	s.refetchOpenAIModels(ctx, ScopeGlobal)
+}
+
+// RefreshOAuthToken refreshes the OAuth token for the given provider.
+//
+// Providers like Hyper rotate refresh tokens: each exchange consumes the
+// caller's refresh token, issues a new pair, and revokes the old one. If
+// two crush instances (or two goroutines) refresh concurrently with the
+// same stored refresh token, the second exchange reuses an already-revoked
+// token, trips the provider's reuse detection, and revokes the entire
+// token family — leaving both with dead tokens even though each refresh
+// "succeeded".
+//
+// To prevent that, refreshes are single-flighted at two levels:
+//
+//   - In-process: refreshSF collapses concurrent goroutines for the same
+//     provider into one attempt.
+//   - Cross-process: a per-provider advisory lock is held across the whole
+//     read-decide-exchange-write cycle, so only one process exchanges at a
+//     time. A process that acquires the lock after a peer rotated finds the
+//     peer's fresh token on disk and adopts it instead of exchanging.
+func (s *ConfigStore) RefreshOAuthToken(ctx context.Context, scope Scope, providerID string) error {
+	key := fmt.Sprintf("%d\x00%s", scope, providerID)
+	_, err, _ := s.refreshSF.Do(key, func() (any, error) {
+		return nil, s.refreshOAuthTokenLocked(ctx, scope, providerID)
+	})
+	return err
+}
+
+// refreshOAuthTokenLocked performs the cross-process single-flighted
+// refresh. It is invoked through refreshSF, so at most one goroutine per
+// provider runs it at a time within this process.
+func (s *ConfigStore) refreshOAuthTokenLocked(ctx context.Context, scope Scope, providerID string) error {
+	cfg := s.Config()
+	providerConfig, exists := cfg.Providers.Get(providerID)
+	if !exists {
+		return fmt.Errorf("provider %s not found", providerID)
+	}
+	if providerConfig.OAuthToken == nil {
+		return fmt.Errorf("provider %s does not have an OAuth token", providerID)
+	}
+	entryToken := providerConfig.OAuthToken
+
+	// Acquire the per-provider cross-process refresh lock. This is a
+	// dedicated lock file, not the config-write lock, and it does not take
+	// s.mu — so the network exchange below cannot stall unrelated config
+	// operations. The deadline exceeds the exchange timeout so that a peer
+	// mid-exchange has time to publish a token we can adopt. Lock ordering:
+	// the refresh lock is always taken before the config-write lock (via
+	// SetConfigFields), never the reverse, so no deadlock is possible.
+	lockCtx, cancel := context.WithTimeout(ctx, refreshLockDeadline)
+	defer cancel()
+	release, lockErr := lock.File(lockCtx, s.refreshLockPath(providerID))
+	if lockErr != nil {
+		// Could not acquire the lock (peer wedged or deadline hit). Prefer a
+		// usable token already on disk over forcing our own exchange, which
+		// would risk reusing a rotated refresh token.
+		if diskToken := s.usableDiskToken(scope, providerID, entryToken); diskToken != nil {
+			slog.Warn("Refresh lock unavailable; adopting token from disk", "provider", providerID, "error", lockErr)
+			return s.applyToken(providerConfig, diskToken, providerID)
+		}
+		return fmt.Errorf("acquire refresh lock for provider %s: %w", providerID, lockErr)
+	}
+	defer release()
+
+	// Now that we hold the lock, disk is the authority on which credential
+	// is current: a peer may have rotated ours away while we waited. Adopt
+	// a newer token outright when it is still usable, and otherwise switch
+	// to its refresh token for the exchange below. Presenting our own
+	// already-rotated refresh token would trip the provider's reuse
+	// detection and revoke the whole family, forcing an interactive login.
+	if diskToken := s.newerDiskToken(scope, providerID, entryToken); diskToken != nil {
+		if !diskToken.IsExpired() {
+			slog.Info("Adopting token refreshed by another session", "provider", providerID)
+			return s.applyToken(providerConfig, diskToken, providerID)
+		}
+		slog.Info("Exchanging with refresh token rotated by another session", "provider", providerID)
+		entryToken = diskToken
+	}
+
+	// Disk still holds our token (or no newer peer token exists) and we hold
+	// the lock, so we are the sole exchanger. Perform the exchange.
+	refreshedToken, refreshErr := s.exchange(ctx, providerID, entryToken.RefreshToken)
+	if refreshErr != nil {
+		// The exchange may have failed because a peer rotated the refresh
+		// token in a window we did not cover. Re-check disk: adopt a usable
+		// token, or retry once with the peer's newer refresh token.
+		if diskToken := s.newerDiskToken(scope, providerID, entryToken); diskToken != nil {
+			if !diskToken.IsExpired() {
+				slog.Info("Adopting token refreshed by another session after exchange failure", "provider", providerID)
+				return s.applyToken(providerConfig, diskToken, providerID)
+			}
+			slog.Info("Retrying exchange with refresh token rotated by another session", "provider", providerID)
+			refreshedToken, refreshErr = s.exchange(ctx, providerID, diskToken.RefreshToken)
+		}
+	}
+	if refreshErr != nil {
+		return fmt.Errorf("failed to refresh OAuth token for provider %s: %w", providerID, refreshErr)
+	}
+
+	slog.Info("Successfully refreshed OAuth token", "provider", providerID)
+	if err := s.applyToken(providerConfig, refreshedToken, providerID); err != nil {
+		return err
+	}
+
+	if err := s.SetConfigFields(scope, tokenFields(providerID, refreshedToken)); err != nil {
+		return fmt.Errorf("failed to persist refreshed token: %w", err)
+	}
+	return nil
+}
+
+// tokenFields builds the config fields that persist an OAuth token. The
+// OpenAI provider does not mirror the access token into api_key so a
+// manually entered API key can coexist with the ChatGPT login.
+func tokenFields(providerID string, token *oauth.Token) map[string]any {
+	fields := map[string]any{
+		fmt.Sprintf("providers.%s.oauth", providerID): token,
+	}
+	if providerID != string(catwalk.InferenceProviderOpenAI) {
+		fields[fmt.Sprintf("providers.%s.api_key", providerID)] = token.AccessToken
+	}
+	return fields
+}
+
+// WaitForTokenChange blocks until SignalAuthComplete is called for the
+// given provider or the context is cancelled. It is used by OnAuthRefresh
+// callbacks to wait for interactive re-authentication to complete before
+// retrying a failed request. The channel is created atomically with the
+// wait registration so a concurrent SignalAuthComplete cannot miss it.
+func (s *ConfigStore) WaitForTokenChange(ctx context.Context, providerID string) error {
+	s.authSignalMu.Lock()
+	ch, ok := s.authSignals[providerID]
+	if !ok {
+		ch = make(chan struct{})
+		if s.authSignals == nil {
+			s.authSignals = make(map[string]chan struct{})
+		}
+		s.authSignals[providerID] = ch
+	}
+	s.authSignalMu.Unlock()
+
+	select {
+	case <-ch:
+		// Remove the consumed signal so a subsequent
+		// SignalAuthComplete does not close an already-closed
+		// channel.
+		s.authSignalMu.Lock()
+		if s.authSignals[providerID] == ch {
+			delete(s.authSignals, providerID)
+		}
+		s.authSignalMu.Unlock()
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+// SignalAuthComplete unblocks any goroutine waiting in WaitForTokenChange
+// for the given provider. If no waiter exists yet, it pre-creates and
+// immediately closes the channel so a subsequent WaitForTokenChange
+// returns without blocking. This eliminates the race where the signal
+// fires before the waiter registers.
+func (s *ConfigStore) SignalAuthComplete(providerID string) {
+	s.authSignalMu.Lock()
+	defer s.authSignalMu.Unlock()
+	if ch, ok := s.authSignals[providerID]; ok {
+		delete(s.authSignals, providerID)
+		select {
+		case <-ch:
+			// Already closed by a previous signal; nothing to do.
+		default:
+			close(ch)
+		}
+	} else {
+		// No waiter yet. Pre-create a closed channel so the next
+		// WaitForTokenChange returns immediately.
+		if s.authSignals == nil {
+			s.authSignals = make(map[string]chan struct{})
+		}
+		ch := make(chan struct{})
+		close(ch)
+		s.authSignals[providerID] = ch
+	}
+}
+
+// newerDiskToken returns the on-disk token for the provider when it is
+// newer than entryToken — i.e. another session (possibly in another
+// process) has already rotated the credential. It returns nil when disk
+// holds nothing newer than what we started with.
+//
+// Newness is judged by expiry as well as identity, so a config file that
+// somehow holds an older token cannot drag us backwards. The result may
+// itself be expired: providers that rotate refresh tokens invalidate ours
+// the moment a peer refreshes, so the peer's refresh token is the only one
+// the provider will still accept even after its access token ages out.
+// Callers decide whether to adopt the token wholesale or merely borrow its
+// refresh token.
+func (s *ConfigStore) newerDiskToken(scope Scope, providerID string, entryToken *oauth.Token) *oauth.Token {
+	diskToken, err := s.loadTokenFromDisk(scope, providerID)
+	if err != nil {
+		slog.Warn("Failed to read token from config file", "provider", providerID, "error", err)
+		return nil
+	}
+	if diskToken == nil {
+		return nil
+	}
+	if diskToken.AccessToken == entryToken.AccessToken {
+		// Same token we started with; nobody rotated since.
+		return nil
+	}
+	if diskToken.RefreshToken == "" && entryToken.RefreshToken != "" {
+		// Adopting would strand us with no way to refresh later, and
+		// there is nothing to borrow for an exchange.
+		return nil
+	}
+	if diskToken.ExpiresAt < entryToken.ExpiresAt {
+		// Older than ours; nothing to gain from adopting it.
+		return nil
+	}
+	return diskToken
+}
+
+// usableDiskToken returns the on-disk token only when it is both newer
+// than entryToken and still valid, meaning it can be adopted as-is with
+// no exchange at all.
+func (s *ConfigStore) usableDiskToken(scope Scope, providerID string, entryToken *oauth.Token) *oauth.Token {
+	diskToken := s.newerDiskToken(scope, providerID, entryToken)
+	if diskToken == nil || diskToken.IsExpired() {
+		return nil
+	}
+	return diskToken
+}
+
+// exchange performs the provider-specific OAuth token exchange. Tests may
+// override it via the exchangeToken field; production uses the real
+// provider clients.
+func (s *ConfigStore) exchange(ctx context.Context, providerID, refreshToken string) (*oauth.Token, error) {
+	if s.exchangeToken != nil {
+		return s.exchangeToken(ctx, providerID, refreshToken)
+	}
+	switch providerID {
+	case string(catwalk.InferenceProviderCopilot):
+		return copilot.RefreshToken(ctx, refreshToken)
+	case string(catwalk.InferenceProviderOpenAI):
+		return openai.RefreshToken(ctx, refreshToken)
+	case hyperp.Name:
+		return hyper.ExchangeToken(ctx, refreshToken)
+	default:
+		return nil, fmt.Errorf("OAuth refresh not supported for provider %s", providerID)
+	}
+}
+
+// withRefreshLock runs fn while holding the per-provider cross-process
+// refresh lock, so a credential write cannot interleave with a peer's
+// token exchange. Acquisition is best effort: when the lock cannot be
+// taken in time, fn runs anyway rather than blocking a write the user is
+// waiting on.
+func (s *ConfigStore) withRefreshLock(providerID string, fn func() error) error {
+	ctx, cancel := context.WithTimeout(context.Background(), credentialWriteLockDeadline)
+	defer cancel()
+	release, err := lock.File(ctx, s.refreshLockPath(providerID))
+	if err != nil {
+		slog.Warn("Writing credentials without the refresh lock", "provider", providerID, "error", err)
+		return fn()
+	}
+	defer release()
+	return fn()
+}
+
+// refreshLockPath returns the path to the per-provider cross-process refresh
+// lock file. Lock files live under a dedicated locks/ subdirectory of the
+// data dir so they do not clutter the config directory. The file is created
+// on demand by lock.File and is never removed (flock keys on inode, not
+// path).
+func (s *ConfigStore) refreshLockPath(providerID string) string {
+	dir := filepath.Join(filepath.Dir(s.globalDataPath), "locks")
+	_ = os.MkdirAll(dir, 0o755)
+	return filepath.Join(dir, fmt.Sprintf("%s.refresh.lock", providerID))
+}
+
+// applyToken updates the in-memory provider config with the given token.
+func (s *ConfigStore) applyToken(providerConfig ProviderConfig, token *oauth.Token, providerID string) error {
+	providerConfig.OAuthToken = token
+	// The OpenAI provider holds exactly one credential, so a ChatGPT
+	// token means there is no API key side by side with it.
+	if providerID != string(catwalk.InferenceProviderOpenAI) {
+		providerConfig.APIKey = token.AccessToken
+	}
+	if providerID == string(catwalk.InferenceProviderCopilot) {
+		providerConfig.SetupGitHubCopilot()
+	}
+	s.Config().Providers.Set(providerID, providerConfig)
+	return nil
+}
+
+// loadTokenFromDisk reads the OAuth token for the given provider from the
+// config file on disk. Returns nil if the token is not found or matches the
+// current in-memory token.
+func (s *ConfigStore) loadTokenFromDisk(scope Scope, providerID string) (*oauth.Token, error) {
+	path, err := s.configPath(scope)
+	if err != nil {
+		return nil, err
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+
+	oauthKey := fmt.Sprintf("providers.%s.oauth", providerID)
+	oauthResult := gjson.Get(string(data), oauthKey)
+	if !oauthResult.Exists() {
+		return nil, nil
+	}
+
+	var token oauth.Token
+	if err := json.Unmarshal([]byte(oauthResult.Raw), &token); err != nil {
+		return nil, err
+	}
+
+	if token.AccessToken == "" {
+		return nil, nil
+	}
+
+	return &token, nil
+}
+
+// nextRecentModels computes the recent-models list for the given type
+// after recording the supplied model at the front, operating on the
+// provided config without persisting anything. It returns the new slice
+// and whether it differs from cfg's current list. Callers fold the result
+// into a clone they are about to publish.
+func nextRecentModels(cfg *Config, modelType SelectedModelType, model SelectedModel) ([]SelectedModel, bool) {
+	if model.Provider == "" || model.Model == "" {
+		return nil, false
+	}
+
+	eq := func(a, b SelectedModel) bool {
+		return a.Provider == b.Provider && a.Model == b.Model
+	}
+
+	entry := SelectedModel{
+		Provider: model.Provider,
+		Model:    model.Model,
+	}
+
+	current := cfg.RecentModels[modelType]
+	withoutCurrent := slices.DeleteFunc(slices.Clone(current), func(existing SelectedModel) bool {
+		return eq(existing, entry)
+	})
+
+	updated := append([]SelectedModel{entry}, withoutCurrent...)
+	if len(updated) > maxRecentModelsPerType {
+		updated = updated[:maxRecentModelsPerType]
+	}
+
+	if slices.EqualFunc(current, updated, eq) {
+		return current, false
+	}
+
+	return updated, true
+}
+
+// NewTestStore creates a ConfigStore for testing purposes.
+func NewTestStore(cfg *Config, loadedPaths ...string) *ConfigStore {
+	return &ConfigStore{
+		config:      cfg,
+		loadedPaths: loadedPaths,
+		resolver:    NewShellVariableResolver(env.New()),
+	}
+}
+
+// ImportCopilot attempts to import a GitHub Copilot token from disk.
+func (s *ConfigStore) ImportCopilot() (*oauth.Token, bool) {
+	if s.HasConfigField(ScopeGlobal, "providers.copilot.api_key") || s.HasConfigField(ScopeGlobal, "providers.copilot.oauth") {
+		return nil, false
+	}
+
+	diskToken, hasDiskToken := copilot.RefreshTokenFromDisk()
+	if !hasDiskToken {
+		return nil, false
+	}
+
+	slog.Info("Found existing GitHub Copilot token on disk. Authenticating...")
+	token, err := copilot.RefreshToken(context.TODO(), diskToken)
+	if err != nil {
+		slog.Error("Unable to import GitHub Copilot token", "error", err)
+		return nil, false
+	}
+
+	if err := s.SetProviderAPIKey(ScopeGlobal, string(catwalk.InferenceProviderCopilot), token); err != nil {
+		return token, false
+	}
+
+	if err := s.SetConfigFields(ScopeGlobal, map[string]any{
+		"providers.copilot.api_key": token.AccessToken,
+		"providers.copilot.oauth":   token,
+	}); err != nil {
+		slog.Error("Unable to save GitHub Copilot token to disk", "error", err)
+	}
+
+	slog.Info("GitHub Copilot successfully imported")
+	return token, true
+}
+
+// StalenessResult contains the result of a staleness check.
+type StalenessResult struct {
+	Dirty   bool
+	Changed []string
+	Missing []string
+	Errors  map[string]error // stat errors by path
+}
+
+// ConfigStaleness checks whether any tracked config files have changed on disk
+// since the last snapshot. Returns dirty=true if any files changed or went
+// missing, along with sorted lists of affected paths. Stat errors are
+// captured in Errors map but still treated as non-existence for dirty detection.
+func (s *ConfigStore) ConfigStaleness() StalenessResult {
+	var result StalenessResult
+	result.Errors = make(map[string]error)
+
+	for _, path := range s.trackedConfigPaths {
+		snapshot, hadSnapshot := s.snapshots[path]
+
+		info, err := os.Stat(path)
+		exists := err == nil && !info.IsDir()
+
+		if err != nil && !os.IsNotExist(err) {
+			// Capture permission/IO errors separately from non-existence
+			result.Errors[path] = err
+			result.Dirty = true
+		}
+
+		if !exists {
+			if hadSnapshot && snapshot.Exists {
+				// File existed before but now missing
+				result.Missing = append(result.Missing, path)
+				result.Dirty = true
+			}
+			continue
+		}
+
+		// File exists now
+		if !hadSnapshot || !snapshot.Exists {
+			// File didn't exist before but does now
+			result.Changed = append(result.Changed, path)
+			result.Dirty = true
+			continue
+		}
+
+		// Check for content or metadata changes
+		if snapshot.Size != info.Size() || snapshot.ModTime != info.ModTime().UnixNano() {
+			result.Changed = append(result.Changed, path)
+			result.Dirty = true
+		}
+	}
+
+	// Sort for deterministic output
+	slices.Sort(result.Changed)
+	slices.Sort(result.Missing)
+
+	return result
+}
+
+// RefreshStalenessSnapshot captures fresh snapshots of all tracked config files.
+// Call this after reloading config to clear dirty state.
+func (s *ConfigStore) RefreshStalenessSnapshot() error {
+	if s.snapshots == nil {
+		s.snapshots = make(map[string]fileSnapshot)
+	}
+
+	for _, path := range s.trackedConfigPaths {
+		info, err := os.Stat(path)
+		exists := err == nil && !info.IsDir()
+
+		snapshot := fileSnapshot{
+			Path:   path,
+			Exists: exists,
+		}
+
+		if exists {
+			snapshot.Size = info.Size()
+			snapshot.ModTime = info.ModTime().UnixNano()
+		}
+
+		s.snapshots[path] = snapshot
+	}
+
+	return nil
+}
+
+// CaptureStalenessSnapshot captures snapshots for the given paths, building the
+// tracked config paths list. Paths are deduplicated and normalized.
+func (s *ConfigStore) CaptureStalenessSnapshot(paths []string) {
+	// Build unique set of normalized paths
+	seen := make(map[string]struct{})
+	for _, p := range paths {
+		if p == "" {
+			continue
+		}
+		// Normalize path
+		abs, err := filepath.Abs(p)
+		if err != nil {
+			abs = p
+		}
+		seen[abs] = struct{}{}
+	}
+
+	// Also track workspace and global config paths if set
+	if s.workspacePath != "" {
+		abs, err := filepath.Abs(s.workspacePath)
+		if err == nil {
+			seen[abs] = struct{}{}
+		}
+	}
+	if s.globalDataPath != "" {
+		abs, err := filepath.Abs(s.globalDataPath)
+		if err == nil {
+			seen[abs] = struct{}{}
+		}
+	}
+
+	// Build sorted list for deterministic ordering
+	s.trackedConfigPaths = make([]string, 0, len(seen))
+	for p := range seen {
+		s.trackedConfigPaths = append(s.trackedConfigPaths, p)
+	}
+	slices.Sort(s.trackedConfigPaths)
+
+	// Capture initial snapshots
+	s.RefreshStalenessSnapshot()
+}
+
+// captureStalenessSnapshot is an alias for CaptureStalenessSnapshot for internal use.
+func (s *ConfigStore) captureStalenessSnapshot(paths []string) {
+	s.CaptureStalenessSnapshot(paths)
+}
+
+// ReloadFromDisk re-runs the config load/merge flow and updates the in-memory
+// config atomically. It rebuilds the staleness snapshot after successful reload.
+// On failure, the store state is rolled back to its previous state.
+// Concurrent calls are serialised via writeMu.
+func (s *ConfigStore) ReloadFromDisk(ctx context.Context) error {
+	if s.workingDir == "" {
+		return fmt.Errorf("cannot reload: working directory not set")
+	}
+	s.writeMu.Lock()
+	defer s.writeMu.Unlock()
+	return s.reloadFromDiskLocked(ctx)
+}
+
+// reloadFromDiskLocked performs the actual reload. Caller must hold writeMu.
+func (s *ConfigStore) reloadFromDiskLocked(ctx context.Context) error {
+	// Migrate deprecated disable_notifications before reloading config.
+	migrateDisableNotifications()
+
+	configPaths := lookupConfigs(s.workingDir)
+	cfg, loadedPaths, err := loadFromConfigPaths(ctx, configPaths)
+	if err != nil {
+		return fmt.Errorf("failed to reload config: %w", err)
+	}
+
+	// Apply defaults (using existing data directory if set)
+	var dataDir string
+	if cur := s.Config(); cur != nil && cur.Options != nil {
+		dataDir = cur.Options.DataDirectory
+	}
+	cfg.setDefaults(s.workingDir, dataDir)
+
+	// Merge workspace config if present
+	workspacePath := filepath.Join(cfg.Options.DataDirectory, fmt.Sprintf("%s.json", appName))
+	if wsData, err := os.ReadFile(workspacePath); err == nil && len(wsData) > 0 {
+		if !json.Valid(wsData) {
+			return fmt.Errorf("invalid JSON in config file %s", workspacePath)
+		}
+		merged, mergeErr := loadFromBytes(append([][]byte{mustMarshalConfig(cfg)}, wsData))
+		if mergeErr == nil {
+			dataDir := cfg.Options.DataDirectory
+			*cfg = *merged
+			cfg.setDefaults(s.workingDir, dataDir)
+			loadedPaths = append(loadedPaths, workspacePath)
+		}
+	}
+
+	// Validate hooks after all config merging is complete so matcher
+	// regexes are recompiled on the reloaded config (mirrors Load).
+	if err := cfg.ValidateHooks(); err != nil {
+		return fmt.Errorf("invalid hook configuration on reload: %w", err)
+	}
+
+	// Save current state for potential rollback BEFORE configureProviders,
+	// which may write to disk via RemoveConfigField (e.g. removing stale
+	// OAuth providers). Capturing after would snapshot a config that has
+	// already been mutated, and the rollback would restore corrupted state.
+	oldConfig := s.Config()
+	oldLoadedPaths := s.loadedPaths
+	oldResolver := s.resolver
+	oldKnownProviders := s.knownProviders
+	oldOverrides := s.overrides
+	oldWorkspacePath := s.workspacePath
+
+	// Preserve runtime overrides
+	overrides := s.overrides
+
+	// Reapply model choices made in this instance. The global config file is
+	// shared, so it may now name a model a sibling instance selected; a
+	// reload triggered by an unrelated write must not swap the user's model
+	// mid-session. An external edit to the config still takes effect for any
+	// model type this instance never chose.
+	maps.Copy(cfg.Models, overrides.Models)
+
+	// Reconfigure providers
+	env := env.New()
+	resolver := NewShellVariableResolver(env)
+
+	// Apply top-level env vars before configuring providers so variables
+	// like AWS_PROFILE are visible to the AWS SDK credential chain.
+	cfg.applyEnv(resolver)
+
+	providers, err := Providers(cfg)
+	if err != nil {
+		if len(providers) == 0 {
+			return fmt.Errorf("failed to load providers during reload: %w", err)
+		}
+		slog.Warn("Reload continuing with the previously known providers", "error", err)
+	}
+
+	if err := cfg.configureProviders(ctx, s, env, resolver, providers); err != nil {
+		return fmt.Errorf("failed to configure providers during reload: %w", err)
+	}
+
+	// Update store state BEFORE running model/agent setup (so they see new config)
+	s.setConfig(cfg)
+	s.loadedPaths = loadedPaths
+	s.resolver = resolver
+	s.knownProviders = providers
+	s.overrides = overrides
+	s.workspacePath = workspacePath
+
+	// Mirror startup flow: setup models and agents against NEW config.
+	var setupErr error
+	if !cfg.IsConfigured() {
+		slog.Warn("No providers configured after reload")
+	} else {
+		resolved, resolveErr := resolveSelectedModels(cfg, providers)
+		if resolveErr != nil {
+			setupErr = fmt.Errorf("failed to configure selected models during reload: %w", resolveErr)
+		} else {
+			cfg.Models[SelectedModelTypeLarge] = resolved.Large
+			cfg.Models[SelectedModelTypeSmall] = resolved.Small
+			s.SetupAgents()
+		}
+	}
+
+	// Rollback on setup failure
+	if setupErr != nil {
+		s.setConfig(oldConfig)
+		s.loadedPaths = oldLoadedPaths
+		s.resolver = oldResolver
+		s.knownProviders = oldKnownProviders
+		s.overrides = oldOverrides
+		s.workspacePath = oldWorkspacePath
+		return setupErr
+	}
+
+	// Rebuild staleness tracking. Track every discovered config path, not
+	// just the ones that loaded, so a config file created after this reload
+	// is detected as a change on the next staleness check.
+	s.captureStalenessSnapshot(append(slices.Clone(configPaths), loadedPaths...))
+
+	return nil
+}
+
+// autoReload conditionally reloads config from disk after writes.
+// It returns nil (no error) for expected skip cases: when auto-reload is
+// disabled during load/reload flows, or when working directory is not set
+// (e.g., during testing). Only actual reload failures return an error.
+func (s *ConfigStore) autoReload(ctx context.Context) error {
+	if s.workingDir == "" {
+		return nil // Expected skip: working directory not set
+	}
+	// Skip if a reload is already in progress. This handles both
+	// concurrent auto-reloads after parallel writes and re-entrant
+	// calls from configureProviders during a reload.
+	//
+	// Note: if a write completes after the in-progress reload has
+	// already read the config file, that write won't be reflected in
+	// memory until the next reload. This is acceptable because writes
+	// are rare and the next user action or file-watch tick will pick
+	// up the change. Callers that need guaranteed fresh state after a
+	// write should call ReloadFromDisk explicitly.
+	if !s.writeMu.TryLock() {
+		return nil
+	}
+	defer s.writeMu.Unlock()
+	return s.reloadFromDiskLocked(ctx)
+}

internal/config/update_model_bench_test.go

@@ -0,0 +1,108 @@
+package config
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// BenchmarkUpdatePreferredModel measures the full write cost of a single
+// model selection, which is what the user experiences when picking a model
+// in the TUI. It guards against regressing back to a full config reload on
+// every selection.
+func BenchmarkUpdatePreferredModel(b *testing.B) {
+	dir := b.TempDir()
+	configPath := filepath.Join(dir, "crush.json")
+
+	b.Setenv("CRUSH_GLOBAL_CONFIG", dir)
+	b.Setenv("CRUSH_GLOBAL_DATA", dir)
+	resetProviderState()
+	b.Cleanup(resetProviderState)
+
+	cfg := `{
+		"models": {
+			"large": {"provider": "openai", "model": "gpt-4"},
+			"small": {"provider": "openai", "model": "gpt-4o-mini"}
+		},
+		"providers": {
+			"openai": {
+				"api_key": "test-key",
+				"models": [
+					{"id": "gpt-4", "name": "GPT-4"},
+					{"id": "gpt-4o", "name": "GPT-4o"},
+					{"id": "gpt-4o-mini", "name": "GPT-4o mini"}
+				]
+			},
+			"anthropic": {
+				"api_key": "test-key-2",
+				"models": [
+					{"id": "claude-3", "name": "Claude 3"},
+					{"id": "claude-3-5", "name": "Claude 3.5"}
+				]
+			}
+		}
+	}`
+	if err := os.WriteFile(configPath, []byte(cfg), 0o600); err != nil {
+		b.Fatal(err)
+	}
+
+	store, err := Load(dir, dir, false)
+	if err != nil {
+		b.Fatal(err)
+	}
+	store.globalDataPath = configPath
+
+	models := []SelectedModel{
+		{Provider: "openai", Model: "gpt-4"},
+		{Provider: "anthropic", Model: "claude-3"},
+		{Provider: "openai", Model: "gpt-4o"},
+		{Provider: "anthropic", Model: "claude-3-5"},
+	}
+
+	b.ReportAllocs()
+	i := 0
+	for b.Loop() {
+		m := models[i%len(models)]
+		if err := store.UpdatePreferredModel(ScopeGlobal, SelectedModelTypeLarge, m); err != nil {
+			b.Fatal(err)
+		}
+		i++
+	}
+}
+
+// BenchmarkReloadFromDisk isolates the full reload cost for comparison with
+// BenchmarkUpdatePreferredModel.
+func BenchmarkReloadFromDisk(b *testing.B) {
+	dir := b.TempDir()
+	configPath := filepath.Join(dir, "crush.json")
+
+	b.Setenv("CRUSH_GLOBAL_CONFIG", dir)
+	b.Setenv("CRUSH_GLOBAL_DATA", dir)
+	resetProviderState()
+	b.Cleanup(resetProviderState)
+
+	cfg := `{
+		"models": {"large": {"provider": "openai", "model": "gpt-4"}},
+		"providers": {
+			"openai": {"api_key": "test-key", "models": [{"id": "gpt-4", "name": "GPT-4"}]}
+		}
+	}`
+	if err := os.WriteFile(configPath, []byte(cfg), 0o600); err != nil {
+		b.Fatal(err)
+	}
+
+	store, err := Load(dir, dir, false)
+	if err != nil {
+		b.Fatal(err)
+	}
+	store.globalDataPath = configPath
+
+	ctx := context.Background()
+	b.ReportAllocs()
+	for b.Loop() {
+		if err := store.ReloadFromDisk(ctx); err != nil {
+			b.Fatal(err)
+		}
+	}
+}

internal/csync/doc.go

@@ -0,0 +1,3 @@
+// Package csync provides concurrent data structures for safe access in
+// multi-threaded environments.
+package csync

internal/csync/maps.go

@@ -0,0 +1,174 @@
+package csync
+
+import (
+	"encoding/json"
+	"iter"
+	"maps"
+	"sync"
+)
+
+// Map is a concurrent map implementation that provides thread-safe access.
+type Map[K comparable, V any] struct {
+	inner map[K]V
+	mu    sync.RWMutex
+}
+
+// NewMap creates a new thread-safe map with the specified key and value types.
+func NewMap[K comparable, V any]() *Map[K, V] {
+	return &Map[K, V]{
+		inner: make(map[K]V),
+	}
+}
+
+// NewMapFrom creates a new thread-safe map from an existing map.
+func NewMapFrom[K comparable, V any](m map[K]V) *Map[K, V] {
+	return &Map[K, V]{
+		inner: m,
+	}
+}
+
+// NewLazyMap creates a new lazy-loaded map. The provided load function is
+// executed in a separate goroutine to populate the map.
+func NewLazyMap[K comparable, V any](load func() map[K]V) *Map[K, V] {
+	m := &Map[K, V]{}
+	m.mu.Lock()
+	go func() {
+		defer m.mu.Unlock()
+		m.inner = load()
+	}()
+	return m
+}
+
+// Reset replaces the inner map with the new one.
+func (m *Map[K, V]) Reset(input map[K]V) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.inner = input
+}
+
+// Set sets the value for the specified key in the map.
+func (m *Map[K, V]) Set(key K, value V) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.inner[key] = value
+}
+
+// Del deletes the specified key from the map.
+func (m *Map[K, V]) Del(key K) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.inner, key)
+}
+
+// CompareAndDelete deletes the key only if the current value matches the
+// expected pointer. Returns true if the deletion occurred. This is the
+// ABA-safe cleanup primitive: it prevents a deferred cleanup from removing
+// a value that was replaced by a newer writer in the window between the
+// explicit Del and the deferred Del.
+func (m *Map[K, V]) CompareAndDelete(key K, expected any) bool {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	current, ok := m.inner[key]
+	if !ok {
+		return false
+	}
+	if any(current) != expected {
+		return false
+	}
+	delete(m.inner, key)
+	return true
+}
+
+// Get gets the value for the specified key from the map.
+func (m *Map[K, V]) Get(key K) (V, bool) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	v, ok := m.inner[key]
+	return v, ok
+}
+
+// Len returns the number of items in the map.
+func (m *Map[K, V]) Len() int {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return len(m.inner)
+}
+
+// GetOrSet gets and returns the key if it exists, otherwise, it executes the
+// given function, set its return value for the given key, and returns it.
+func (m *Map[K, V]) GetOrSet(key K, fn func() V) V {
+	got, ok := m.Get(key)
+	if ok {
+		return got
+	}
+	value := fn()
+	m.Set(key, value)
+	return value
+}
+
+// Take gets an item and then deletes it.
+func (m *Map[K, V]) Take(key K) (V, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	v, ok := m.inner[key]
+	delete(m.inner, key)
+	return v, ok
+}
+
+// Copy returns a copy of the inner map.
+func (m *Map[K, V]) Copy() map[K]V {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return maps.Clone(m.inner)
+}
+
+// Seq2 returns an iter.Seq2 that yields key-value pairs from the map.
+func (m *Map[K, V]) Seq2() iter.Seq2[K, V] {
+	dst := m.Copy()
+	return func(yield func(K, V) bool) {
+		for k, v := range dst {
+			if !yield(k, v) {
+				return
+			}
+		}
+	}
+}
+
+// Seq returns an iter.Seq that yields values from the map.
+func (m *Map[K, V]) Seq() iter.Seq[V] {
+	return func(yield func(V) bool) {
+		for _, v := range m.Seq2() {
+			if !yield(v) {
+				return
+			}
+		}
+	}
+}
+
+var (
+	_ json.Unmarshaler = &Map[string, any]{}
+	_ json.Marshaler   = &Map[string, any]{}
+)
+
+// JSONSchemaAlias returns the underlying map type for JSON schema generation.
+// Value receiver is required because github.com/invopop/jsonschema checks
+// interface satisfaction on the non-pointer type after stripping pointers.
+func (Map[K, V]) JSONSchemaAlias() any { //nolint
+	m := map[K]V{}
+	return m
+}
+
+// UnmarshalJSON implements json.Unmarshaler.
+func (m *Map[K, V]) UnmarshalJSON(data []byte) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.inner = make(map[K]V)
+	return json.Unmarshal(data, &m.inner)
+}
+
+// MarshalJSON implements json.Marshaler.
+func (m *Map[K, V]) MarshalJSON() ([]byte, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return json.Marshal(m.inner)
+}

internal/csync/maps_test.go

@@ -0,0 +1,770 @@
+package csync
+
+import (
+	"encoding/json"
+	"maps"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewMap(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	require.NotNil(t, m)
+	require.NotNil(t, m.inner)
+	require.Equal(t, 0, m.Len())
+}
+
+func TestNewMapFrom(t *testing.T) {
+	t.Parallel()
+
+	original := map[string]int{
+		"key1": 1,
+		"key2": 2,
+	}
+
+	m := NewMapFrom(original)
+	require.NotNil(t, m)
+	require.Equal(t, original, m.inner)
+	require.Equal(t, 2, m.Len())
+
+	value, ok := m.Get("key1")
+	require.True(t, ok)
+	require.Equal(t, 1, value)
+}
+
+func TestNewLazyMap(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		t.Helper()
+
+		waiter := sync.Mutex{}
+		waiter.Lock()
+		var loadCalled atomic.Bool
+
+		loadFunc := func() map[string]int {
+			waiter.Lock()
+			defer waiter.Unlock()
+			loadCalled.Store(true)
+			return map[string]int{
+				"key1": 1,
+				"key2": 2,
+			}
+		}
+
+		m := NewLazyMap(loadFunc)
+		require.NotNil(t, m)
+
+		waiter.Unlock() // Allow the load function to proceed
+		time.Sleep(100 * time.Millisecond)
+		require.True(t, loadCalled.Load())
+		require.Equal(t, 2, m.Len())
+
+		value, ok := m.Get("key1")
+		require.True(t, ok)
+		require.Equal(t, 1, value)
+	})
+}
+
+func TestMap_Reset(t *testing.T) {
+	t.Parallel()
+
+	m := NewMapFrom(map[string]int{
+		"a": 10,
+	})
+
+	m.Reset(map[string]int{
+		"b": 20,
+	})
+	value, ok := m.Get("b")
+	require.True(t, ok)
+	require.Equal(t, 20, value)
+	require.Equal(t, 1, m.Len())
+}
+
+func TestMap_Set(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+
+	m.Set("key1", 42)
+	value, ok := m.Get("key1")
+	require.True(t, ok)
+	require.Equal(t, 42, value)
+	require.Equal(t, 1, m.Len())
+
+	m.Set("key1", 100)
+	value, ok = m.Get("key1")
+	require.True(t, ok)
+	require.Equal(t, 100, value)
+	require.Equal(t, 1, m.Len())
+}
+
+func TestMap_GetOrSet(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+
+	require.Equal(t, 42, m.GetOrSet("key1", func() int { return 42 }))
+	require.Equal(t, 42, m.GetOrSet("key1", func() int { return 99999 }))
+	require.Equal(t, 1, m.Len())
+}
+
+func TestMap_Get(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+
+	value, ok := m.Get("nonexistent")
+	require.False(t, ok)
+	require.Equal(t, 0, value)
+
+	m.Set("key1", 42)
+	value, ok = m.Get("key1")
+	require.True(t, ok)
+	require.Equal(t, 42, value)
+}
+
+func TestMap_Del(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("key1", 42)
+	m.Set("key2", 100)
+
+	require.Equal(t, 2, m.Len())
+
+	m.Del("key1")
+	_, ok := m.Get("key1")
+	require.False(t, ok)
+	require.Equal(t, 1, m.Len())
+
+	value, ok := m.Get("key2")
+	require.True(t, ok)
+	require.Equal(t, 100, value)
+
+	m.Del("nonexistent")
+	require.Equal(t, 1, m.Len())
+}
+
+func TestMap_Len(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	require.Equal(t, 0, m.Len())
+
+	m.Set("key1", 1)
+	require.Equal(t, 1, m.Len())
+
+	m.Set("key2", 2)
+	require.Equal(t, 2, m.Len())
+
+	m.Del("key1")
+	require.Equal(t, 1, m.Len())
+
+	m.Del("key2")
+	require.Equal(t, 0, m.Len())
+}
+
+// TestMap_CompareAndDelete verifies that CompareAndDelete only removes the
+// entry when the stored pointer matches the expected value. This is the
+// ABA-safe cleanup primitive used by the dispatch completion path to prevent
+// a deferred cleanup from wiping a newer run's entry.
+func TestMap_CompareAndDelete(t *testing.T) {
+	t.Parallel()
+
+	type entry struct{ val int }
+	m := NewMap[string, *entry]()
+
+	original := &entry{val: 1}
+	m.Set("k", original)
+
+	// Matching pointer: deletion succeeds.
+	require.True(t, m.CompareAndDelete("k", any(original)))
+	_, ok := m.Get("k")
+	require.False(t, ok)
+
+	// Re-set with a new value, try to delete with the stale pointer.
+	second := &entry{val: 2}
+	m.Set("k", second)
+	require.False(t, m.CompareAndDelete("k", any(original)), "stale pointer must not delete")
+	got, ok := m.Get("k")
+	require.True(t, ok)
+	require.Equal(t, 2, got.val)
+
+	// Missing key: returns false.
+	require.False(t, m.CompareAndDelete("absent", any(original)))
+}
+
+func TestMap_Take(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("key1", 42)
+	m.Set("key2", 100)
+
+	require.Equal(t, 2, m.Len())
+
+	value, ok := m.Take("key1")
+	require.True(t, ok)
+	require.Equal(t, 42, value)
+	require.Equal(t, 1, m.Len())
+
+	_, exists := m.Get("key1")
+	require.False(t, exists)
+
+	value, ok = m.Get("key2")
+	require.True(t, ok)
+	require.Equal(t, 100, value)
+}
+
+func TestMap_Take_NonexistentKey(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("key1", 42)
+
+	value, ok := m.Take("nonexistent")
+	require.False(t, ok)
+	require.Equal(t, 0, value)
+	require.Equal(t, 1, m.Len())
+
+	value, ok = m.Get("key1")
+	require.True(t, ok)
+	require.Equal(t, 42, value)
+}
+
+func TestMap_Take_EmptyMap(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+
+	value, ok := m.Take("key1")
+	require.False(t, ok)
+	require.Equal(t, 0, value)
+	require.Equal(t, 0, m.Len())
+}
+
+func TestMap_Take_SameKeyTwice(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("key1", 42)
+
+	value, ok := m.Take("key1")
+	require.True(t, ok)
+	require.Equal(t, 42, value)
+	require.Equal(t, 0, m.Len())
+
+	value, ok = m.Take("key1")
+	require.False(t, ok)
+	require.Equal(t, 0, value)
+	require.Equal(t, 0, m.Len())
+}
+
+func TestMap_Seq2(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("key1", 1)
+	m.Set("key2", 2)
+	m.Set("key3", 3)
+
+	collected := maps.Collect(m.Seq2())
+
+	require.Equal(t, 3, len(collected))
+	require.Equal(t, 1, collected["key1"])
+	require.Equal(t, 2, collected["key2"])
+	require.Equal(t, 3, collected["key3"])
+}
+
+func TestMap_Seq2_EarlyReturn(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("key1", 1)
+	m.Set("key2", 2)
+	m.Set("key3", 3)
+
+	count := 0
+	for range m.Seq2() {
+		count++
+		if count == 2 {
+			break
+		}
+	}
+
+	require.Equal(t, 2, count)
+}
+
+func TestMap_Seq2_EmptyMap(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+
+	count := 0
+	for range m.Seq2() {
+		count++
+	}
+
+	require.Equal(t, 0, count)
+}
+
+func TestMap_Seq(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("key1", 1)
+	m.Set("key2", 2)
+	m.Set("key3", 3)
+
+	collected := make([]int, 0)
+	for v := range m.Seq() {
+		collected = append(collected, v)
+	}
+
+	require.Equal(t, 3, len(collected))
+	require.Contains(t, collected, 1)
+	require.Contains(t, collected, 2)
+	require.Contains(t, collected, 3)
+}
+
+func TestMap_Seq_EarlyReturn(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("key1", 1)
+	m.Set("key2", 2)
+	m.Set("key3", 3)
+
+	count := 0
+	for range m.Seq() {
+		count++
+		if count == 2 {
+			break
+		}
+	}
+
+	require.Equal(t, 2, count)
+}
+
+func TestMap_Seq_EmptyMap(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+
+	count := 0
+	for range m.Seq() {
+		count++
+	}
+
+	require.Equal(t, 0, count)
+}
+
+func TestMap_MarshalJSON(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("key1", 1)
+	m.Set("key2", 2)
+
+	data, err := json.Marshal(m)
+	require.NoError(t, err)
+
+	result := &Map[string, int]{}
+	err = json.Unmarshal(data, result)
+	require.NoError(t, err)
+	require.Equal(t, 2, result.Len())
+	v1, _ := result.Get("key1")
+	v2, _ := result.Get("key2")
+	require.Equal(t, 1, v1)
+	require.Equal(t, 2, v2)
+}
+
+func TestMap_MarshalJSON_EmptyMap(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+
+	data, err := json.Marshal(m)
+	require.NoError(t, err)
+	require.Equal(t, "{}", string(data))
+}
+
+func TestMap_UnmarshalJSON(t *testing.T) {
+	t.Parallel()
+
+	jsonData := `{"key1": 1, "key2": 2}`
+
+	m := NewMap[string, int]()
+	err := json.Unmarshal([]byte(jsonData), m)
+	require.NoError(t, err)
+
+	require.Equal(t, 2, m.Len())
+	value, ok := m.Get("key1")
+	require.True(t, ok)
+	require.Equal(t, 1, value)
+
+	value, ok = m.Get("key2")
+	require.True(t, ok)
+	require.Equal(t, 2, value)
+}
+
+func TestMap_UnmarshalJSON_EmptyJSON(t *testing.T) {
+	t.Parallel()
+
+	jsonData := `{}`
+
+	m := NewMap[string, int]()
+	err := json.Unmarshal([]byte(jsonData), m)
+	require.NoError(t, err)
+	require.Equal(t, 0, m.Len())
+}
+
+func TestMap_UnmarshalJSON_InvalidJSON(t *testing.T) {
+	t.Parallel()
+
+	jsonData := `{"key1": 1, "key2":}`
+
+	m := NewMap[string, int]()
+	err := json.Unmarshal([]byte(jsonData), m)
+	require.Error(t, err)
+}
+
+func TestMap_UnmarshalJSON_OverwritesExistingData(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[string, int]()
+	m.Set("existing", 999)
+
+	jsonData := `{"key1": 1, "key2": 2}`
+	err := json.Unmarshal([]byte(jsonData), m)
+	require.NoError(t, err)
+
+	require.Equal(t, 2, m.Len())
+	_, ok := m.Get("existing")
+	require.False(t, ok)
+
+	value, ok := m.Get("key1")
+	require.True(t, ok)
+	require.Equal(t, 1, value)
+}
+
+func TestMap_JSONRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	original := NewMap[string, int]()
+	original.Set("key1", 1)
+	original.Set("key2", 2)
+	original.Set("key3", 3)
+
+	data, err := json.Marshal(original)
+	require.NoError(t, err)
+
+	restored := NewMap[string, int]()
+	err = json.Unmarshal(data, restored)
+	require.NoError(t, err)
+
+	require.Equal(t, original.Len(), restored.Len())
+
+	for k, v := range original.Seq2() {
+		restoredValue, ok := restored.Get(k)
+		require.True(t, ok)
+		require.Equal(t, v, restoredValue)
+	}
+}
+
+func TestMap_ConcurrentAccess(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[int, int]()
+	const numGoroutines = 100
+	const numOperations = 100
+
+	var wg sync.WaitGroup
+	wg.Add(numGoroutines)
+
+	for i := range numGoroutines {
+		go func(id int) {
+			defer wg.Done()
+			for j := range numOperations {
+				key := id*numOperations + j
+				m.Set(key, key*2)
+				value, ok := m.Get(key)
+				require.True(t, ok)
+				require.Equal(t, key*2, value)
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	require.Equal(t, numGoroutines*numOperations, m.Len())
+}
+
+func TestMap_ConcurrentReadWrite(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[int, int]()
+	const numReaders = 50
+	const numWriters = 50
+	const numOperations = 100
+
+	for i := range 1000 {
+		m.Set(i, i)
+	}
+
+	var wg sync.WaitGroup
+	wg.Add(numReaders + numWriters)
+
+	for range numReaders {
+		go func() {
+			defer wg.Done()
+			for j := range numOperations {
+				key := j % 1000
+				value, ok := m.Get(key)
+				if ok {
+					require.Equal(t, key, value)
+				}
+				_ = m.Len()
+			}
+		}()
+	}
+
+	for i := range numWriters {
+		go func(id int) {
+			defer wg.Done()
+			for j := range numOperations {
+				key := 1000 + id*numOperations + j
+				m.Set(key, key)
+				if j%10 == 0 {
+					m.Del(key)
+				}
+			}
+		}(i)
+	}
+
+	wg.Wait()
+}
+
+func TestMap_ConcurrentSeq2(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[int, int]()
+	for i := range 100 {
+		m.Set(i, i*2)
+	}
+
+	var wg sync.WaitGroup
+	const numIterators = 10
+
+	wg.Add(numIterators)
+	for range numIterators {
+		go func() {
+			defer wg.Done()
+			count := 0
+			for k, v := range m.Seq2() {
+				require.Equal(t, k*2, v)
+				count++
+			}
+			require.Equal(t, 100, count)
+		}()
+	}
+
+	wg.Wait()
+}
+
+func TestMap_ConcurrentSeq(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[int, int]()
+	for i := range 100 {
+		m.Set(i, i*2)
+	}
+
+	var wg sync.WaitGroup
+	const numIterators = 10
+
+	wg.Add(numIterators)
+	for range numIterators {
+		go func() {
+			defer wg.Done()
+			count := 0
+			values := make(map[int]bool)
+			for v := range m.Seq() {
+				values[v] = true
+				count++
+			}
+			require.Equal(t, 100, count)
+			for i := range 100 {
+				require.True(t, values[i*2])
+			}
+		}()
+	}
+
+	wg.Wait()
+}
+
+func TestMap_ConcurrentTake(t *testing.T) {
+	t.Parallel()
+
+	m := NewMap[int, int]()
+	const numItems = 1000
+
+	for i := range numItems {
+		m.Set(i, i*2)
+	}
+
+	var wg sync.WaitGroup
+	const numWorkers = 10
+	taken := make([][]int, numWorkers)
+
+	wg.Add(numWorkers)
+	for i := range numWorkers {
+		go func(workerID int) {
+			defer wg.Done()
+			taken[workerID] = make([]int, 0)
+			for j := workerID; j < numItems; j += numWorkers {
+				if value, ok := m.Take(j); ok {
+					taken[workerID] = append(taken[workerID], value)
+				}
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	require.Equal(t, 0, m.Len())
+
+	allTaken := make(map[int]bool)
+	for _, workerTaken := range taken {
+		for _, value := range workerTaken {
+			require.False(t, allTaken[value], "Value %d was taken multiple times", value)
+			allTaken[value] = true
+		}
+	}
+
+	require.Equal(t, numItems, len(allTaken))
+	for i := range numItems {
+		require.True(t, allTaken[i*2], "Expected value %d to be taken", i*2)
+	}
+}
+
+func TestMap_TypeSafety(t *testing.T) {
+	t.Parallel()
+
+	stringIntMap := NewMap[string, int]()
+	stringIntMap.Set("key", 42)
+	value, ok := stringIntMap.Get("key")
+	require.True(t, ok)
+	require.Equal(t, 42, value)
+
+	intStringMap := NewMap[int, string]()
+	intStringMap.Set(42, "value")
+	strValue, ok := intStringMap.Get(42)
+	require.True(t, ok)
+	require.Equal(t, "value", strValue)
+
+	structMap := NewMap[string, struct{ Name string }]()
+	structMap.Set("key", struct{ Name string }{Name: "test"})
+	structValue, ok := structMap.Get("key")
+	require.True(t, ok)
+	require.Equal(t, "test", structValue.Name)
+}
+
+func TestMap_InterfaceCompliance(t *testing.T) {
+	t.Parallel()
+
+	var _ json.Marshaler = &Map[string, any]{}
+	var _ json.Unmarshaler = &Map[string, any]{}
+}
+
+func BenchmarkMap_Set(b *testing.B) {
+	m := NewMap[int, int]()
+
+	for i := 0; b.Loop(); i++ {
+		m.Set(i, i*2)
+	}
+}
+
+func BenchmarkMap_Get(b *testing.B) {
+	m := NewMap[int, int]()
+	for i := range 1000 {
+		m.Set(i, i*2)
+	}
+
+	for i := 0; b.Loop(); i++ {
+		m.Get(i % 1000)
+	}
+}
+
+func BenchmarkMap_Seq2(b *testing.B) {
+	m := NewMap[int, int]()
+	for i := range 1000 {
+		m.Set(i, i*2)
+	}
+
+	for b.Loop() {
+		for range m.Seq2() {
+		}
+	}
+}
+
+func BenchmarkMap_Seq(b *testing.B) {
+	m := NewMap[int, int]()
+	for i := range 1000 {
+		m.Set(i, i*2)
+	}
+
+	for b.Loop() {
+		for range m.Seq() {
+		}
+	}
+}
+
+func BenchmarkMap_Take(b *testing.B) {
+	m := NewMap[int, int]()
+	for i := range 1000 {
+		m.Set(i, i*2)
+	}
+
+	b.ResetTimer()
+	for i := 0; b.Loop(); i++ {
+		key := i % 1000
+		m.Take(key)
+		if i%1000 == 999 {
+			b.StopTimer()
+			for j := range 1000 {
+				m.Set(j, j*2)
+			}
+			b.StartTimer()
+		}
+	}
+}
+
+func BenchmarkMap_ConcurrentReadWrite(b *testing.B) {
+	m := NewMap[int, int]()
+	for i := range 1000 {
+		m.Set(i, i*2)
+	}
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		i := 0
+		for pb.Next() {
+			if i%2 == 0 {
+				m.Get(i % 1000)
+			} else {
+				m.Set(i+1000, i*2)
+			}
+			i++
+		}
+	})
+}

internal/csync/slices.go

@@ -0,0 +1,121 @@
+package csync
+
+import (
+	"iter"
+	"sync"
+)
+
+// LazySlice is a thread-safe lazy-loaded slice.
+type LazySlice[K any] struct {
+	inner []K
+	wg    sync.WaitGroup
+}
+
+// NewLazySlice creates a new slice and runs the [load] function in a goroutine
+// to populate it.
+func NewLazySlice[K any](load func() []K) *LazySlice[K] {
+	s := &LazySlice[K]{}
+	s.wg.Go(func() {
+		s.inner = load()
+	})
+	return s
+}
+
+// Seq returns an iterator that yields elements from the slice.
+func (s *LazySlice[K]) Seq() iter.Seq[K] {
+	s.wg.Wait()
+	return func(yield func(K) bool) {
+		for _, v := range s.inner {
+			if !yield(v) {
+				return
+			}
+		}
+	}
+}
+
+// Slice is a thread-safe slice implementation that provides concurrent access.
+type Slice[T any] struct {
+	inner []T
+	mu    sync.RWMutex
+}
+
+// NewSlice creates a new thread-safe slice.
+func NewSlice[T any]() *Slice[T] {
+	return &Slice[T]{
+		inner: make([]T, 0),
+	}
+}
+
+// NewSliceFrom creates a new thread-safe slice from an existing slice.
+func NewSliceFrom[T any](s []T) *Slice[T] {
+	inner := make([]T, len(s))
+	copy(inner, s)
+	return &Slice[T]{
+		inner: inner,
+	}
+}
+
+// Append adds an element to the end of the slice.
+func (s *Slice[T]) Append(items ...T) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.inner = append(s.inner, items...)
+}
+
+// Get returns the element at the specified index.
+func (s *Slice[T]) Get(index int) (T, bool) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	var zero T
+	if index < 0 || index >= len(s.inner) {
+		return zero, false
+	}
+	return s.inner[index], true
+}
+
+// Len returns the number of elements in the slice.
+func (s *Slice[T]) Len() int {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return len(s.inner)
+}
+
+// SetSlice replaces the entire slice with a new one.
+func (s *Slice[T]) SetSlice(items []T) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.inner = make([]T, len(items))
+	copy(s.inner, items)
+}
+
+// Seq returns an iterator that yields elements from the slice.
+func (s *Slice[T]) Seq() iter.Seq[T] {
+	return func(yield func(T) bool) {
+		for _, v := range s.Seq2() {
+			if !yield(v) {
+				return
+			}
+		}
+	}
+}
+
+// Seq2 returns an iterator that yields index-value pairs from the slice.
+func (s *Slice[T]) Seq2() iter.Seq2[int, T] {
+	items := s.Copy()
+	return func(yield func(int, T) bool) {
+		for i, v := range items {
+			if !yield(i, v) {
+				return
+			}
+		}
+	}
+}
+
+// Copy returns a copy of the inner slice.
+func (s *Slice[T]) Copy() []T {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	items := make([]T, len(s.inner))
+	copy(items, s.inner)
+	return items
+}

internal/csync/slices_test.go

@@ -0,0 +1,214 @@
+package csync
+
+import (
+	"slices"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestLazySlice_Seq(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		t.Helper()
+		data := []string{"a", "b", "c"}
+		s := NewLazySlice(func() []string {
+			time.Sleep(10 * time.Millisecond) // Small delay to ensure loading happens
+			return data
+		})
+		require.Equal(t, data, slices.Collect(s.Seq()))
+	})
+}
+
+func TestLazySlice_SeqWaitsForLoading(t *testing.T) {
+	t.Parallel()
+	synctest.Test(t, func(t *testing.T) {
+		t.Helper()
+
+		var loaded atomic.Bool
+		data := []string{"x", "y", "z"}
+
+		s := NewLazySlice(func() []string {
+			time.Sleep(100 * time.Millisecond)
+			loaded.Store(true)
+			return data
+		})
+
+		require.False(t, loaded.Load(), "should not be loaded immediately")
+		require.Equal(t, data, slices.Collect(s.Seq()))
+		require.True(t, loaded.Load(), "should be loaded after Seq")
+	})
+}
+
+func TestLazySlice_EmptySlice(t *testing.T) {
+	t.Parallel()
+	s := NewLazySlice(func() []string {
+		return []string{}
+	})
+	require.Empty(t, slices.Collect(s.Seq()))
+}
+
+func TestLazySlice_EarlyBreak(t *testing.T) {
+	t.Parallel()
+
+	synctest.Test(t, func(t *testing.T) {
+		t.Helper()
+		data := []string{"a", "b", "c", "d", "e"}
+		s := NewLazySlice(func() []string {
+			time.Sleep(10 * time.Millisecond) // Small delay to ensure loading happens
+			return data
+		})
+
+		var result []string
+		for v := range s.Seq() {
+			result = append(result, v)
+			if len(result) == 2 {
+				break
+			}
+		}
+
+		require.Equal(t, []string{"a", "b"}, result)
+	})
+}
+
+func TestSlice(t *testing.T) {
+	t.Run("NewSlice", func(t *testing.T) {
+		s := NewSlice[int]()
+		require.Equal(t, 0, s.Len())
+	})
+
+	t.Run("NewSliceFrom", func(t *testing.T) {
+		original := []int{1, 2, 3}
+		s := NewSliceFrom(original)
+		require.Equal(t, 3, s.Len())
+
+		// Verify it's a copy, not a reference
+		original[0] = 999
+		val, ok := s.Get(0)
+		require.True(t, ok)
+		require.Equal(t, 1, val)
+	})
+
+	t.Run("Append", func(t *testing.T) {
+		s := NewSlice[string]()
+		s.Append("hello")
+		s.Append("world")
+
+		require.Equal(t, 2, s.Len())
+		val, ok := s.Get(0)
+		require.True(t, ok)
+		require.Equal(t, "hello", val)
+
+		val, ok = s.Get(1)
+		require.True(t, ok)
+		require.Equal(t, "world", val)
+	})
+
+	t.Run("Get", func(t *testing.T) {
+		s := NewSliceFrom([]string{"a", "b", "c"})
+
+		val, ok := s.Get(1)
+		require.True(t, ok)
+		require.Equal(t, "b", val)
+
+		// Out of bounds
+		_, ok = s.Get(10)
+		require.False(t, ok)
+
+		// Negative index
+		_, ok = s.Get(-1)
+		require.False(t, ok)
+	})
+
+	t.Run("SetSlice", func(t *testing.T) {
+		s := NewSlice[int]()
+		s.Append(1)
+		s.Append(2)
+
+		newItems := []int{10, 20, 30}
+		s.SetSlice(newItems)
+
+		require.Equal(t, 3, s.Len())
+		require.Equal(t, newItems, slices.Collect(s.Seq()))
+
+		// Verify it's a copy
+		newItems[0] = 999
+		val, ok := s.Get(0)
+		require.True(t, ok)
+		require.Equal(t, 10, val)
+	})
+
+	t.Run("Slice", func(t *testing.T) {
+		original := []int{1, 2, 3}
+		s := NewSliceFrom(original)
+
+		copied := slices.Collect(s.Seq())
+		require.Equal(t, original, copied)
+
+		// Verify it's a copy
+		copied[0] = 999
+		val, ok := s.Get(0)
+		require.True(t, ok)
+		require.Equal(t, 1, val)
+	})
+
+	t.Run("Seq", func(t *testing.T) {
+		s := NewSliceFrom([]int{1, 2, 3})
+
+		var result []int
+		for v := range s.Seq() {
+			result = append(result, v)
+		}
+
+		require.Equal(t, []int{1, 2, 3}, result)
+	})
+
+	t.Run("SeqWithIndex", func(t *testing.T) {
+		s := NewSliceFrom([]string{"a", "b", "c"})
+
+		var indices []int
+		var values []string
+		for i, v := range s.Seq2() {
+			indices = append(indices, i)
+			values = append(values, v)
+		}
+
+		require.Equal(t, []int{0, 1, 2}, indices)
+		require.Equal(t, []string{"a", "b", "c"}, values)
+	})
+
+	t.Run("ConcurrentAccess", func(t *testing.T) {
+		s := NewSlice[int]()
+		const numGoroutines = 100
+		const itemsPerGoroutine = 10
+
+		var wg sync.WaitGroup
+
+		// Concurrent appends
+		for i := range numGoroutines {
+			wg.Add(2)
+			go func(start int) {
+				defer wg.Done()
+				for j := range itemsPerGoroutine {
+					s.Append(start*itemsPerGoroutine + j)
+				}
+			}(i)
+			go func() {
+				defer wg.Done()
+				for range itemsPerGoroutine {
+					s.Len() // Just read the length
+				}
+			}()
+		}
+
+		wg.Wait()
+
+		// Should have all items
+		require.Equal(t, numGoroutines*itemsPerGoroutine, s.Len())
+	})
+}

internal/csync/value.go

@@ -0,0 +1,44 @@
+package csync
+
+import (
+	"reflect"
+	"sync"
+)
+
+// Value is a generic thread-safe wrapper for any value type.
+//
+// For slices, use [Slice]. For maps, use [Map]. Pointers are not supported.
+type Value[T any] struct {
+	v  T
+	mu sync.RWMutex
+}
+
+// NewValue creates a new Value with the given initial value.
+//
+// Panics if t is a pointer, slice, or map. Use the dedicated types for those.
+func NewValue[T any](t T) *Value[T] {
+	v := reflect.ValueOf(t)
+	switch v.Kind() {
+	case reflect.Pointer:
+		panic("csync.Value does not support pointer types")
+	case reflect.Slice:
+		panic("csync.Value does not support slice types; use csync.Slice")
+	case reflect.Map:
+		panic("csync.Value does not support map types; use csync.Map")
+	}
+	return &Value[T]{v: t}
+}
+
+// Get returns the current value.
+func (v *Value[T]) Get() T {
+	v.mu.RLock()
+	defer v.mu.RUnlock()
+	return v.v
+}
+
+// Set updates the value.
+func (v *Value[T]) Set(t T) {
+	v.mu.Lock()
+	defer v.mu.Unlock()
+	v.v = t
+}

internal/csync/value_test.go

@@ -0,0 +1,97 @@
+package csync
+
+import (
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestValue_GetSet(t *testing.T) {
+	t.Parallel()
+
+	v := NewValue(42)
+	require.Equal(t, 42, v.Get())
+
+	v.Set(100)
+	require.Equal(t, 100, v.Get())
+}
+
+func TestValue_ZeroValue(t *testing.T) {
+	t.Parallel()
+
+	v := NewValue("")
+	require.Equal(t, "", v.Get())
+
+	v.Set("hello")
+	require.Equal(t, "hello", v.Get())
+}
+
+func TestValue_Struct(t *testing.T) {
+	t.Parallel()
+
+	type config struct {
+		Name  string
+		Count int
+	}
+
+	v := NewValue(config{Name: "test", Count: 1})
+	require.Equal(t, config{Name: "test", Count: 1}, v.Get())
+
+	v.Set(config{Name: "updated", Count: 2})
+	require.Equal(t, config{Name: "updated", Count: 2}, v.Get())
+}
+
+func TestValue_PointerPanics(t *testing.T) {
+	t.Parallel()
+
+	require.Panics(t, func() {
+		NewValue(&struct{}{})
+	})
+}
+
+func TestValue_SlicePanics(t *testing.T) {
+	t.Parallel()
+
+	require.Panics(t, func() {
+		NewValue([]string{"a", "b"})
+	})
+}
+
+func TestValue_MapPanics(t *testing.T) {
+	t.Parallel()
+
+	require.Panics(t, func() {
+		NewValue(map[string]int{"a": 1})
+	})
+}
+
+func TestValue_ConcurrentAccess(t *testing.T) {
+	t.Parallel()
+
+	v := NewValue(0)
+	var wg sync.WaitGroup
+
+	// Concurrent writers.
+	for i := range 100 {
+		wg.Add(1)
+		go func(val int) {
+			defer wg.Done()
+			v.Set(val)
+		}(i)
+	}
+
+	// Concurrent readers.
+	for range 100 {
+		wg.Go(func() {
+			_ = v.Get()
+		})
+	}
+
+	wg.Wait()
+
+	// Value should be one of the set values (0-99).
+	got := v.Get()
+	require.GreaterOrEqual(t, got, 0)
+	require.Less(t, got, 100)
+}

internal/csync/versionedmap.go

@@ -0,0 +1,56 @@
+package csync
+
+import (
+	"iter"
+	"sync/atomic"
+)
+
+// NewVersionedMap creates a new versioned, thread-safe map.
+func NewVersionedMap[K comparable, V any]() *VersionedMap[K, V] {
+	return &VersionedMap[K, V]{
+		m: NewMap[K, V](),
+	}
+}
+
+// VersionedMap is a thread-safe map that keeps track of its version.
+type VersionedMap[K comparable, V any] struct {
+	m *Map[K, V]
+	v atomic.Uint64
+}
+
+// Get gets the value for the specified key from the map.
+func (m *VersionedMap[K, V]) Get(key K) (V, bool) {
+	return m.m.Get(key)
+}
+
+// Set sets the value for the specified key in the map and increments the version.
+func (m *VersionedMap[K, V]) Set(key K, value V) {
+	m.m.Set(key, value)
+	m.v.Add(1)
+}
+
+// Del deletes the specified key from the map and increments the version.
+func (m *VersionedMap[K, V]) Del(key K) {
+	m.m.Del(key)
+	m.v.Add(1)
+}
+
+// Seq2 returns an iter.Seq2 that yields key-value pairs from the map.
+func (m *VersionedMap[K, V]) Seq2() iter.Seq2[K, V] {
+	return m.m.Seq2()
+}
+
+// Copy returns a copy of the inner map.
+func (m *VersionedMap[K, V]) Copy() map[K]V {
+	return m.m.Copy()
+}
+
+// Len returns the number of items in the map.
+func (m *VersionedMap[K, V]) Len() int {
+	return m.m.Len()
+}
+
+// Version returns the current version of the map.
+func (m *VersionedMap[K, V]) Version() uint64 {
+	return m.v.Load()
+}

internal/csync/versionedmap_test.go

@@ -0,0 +1,89 @@
+package csync
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestVersionedMap_Set(t *testing.T) {
+	t.Parallel()
+
+	vm := NewVersionedMap[string, int]()
+	require.Equal(t, uint64(0), vm.Version())
+
+	vm.Set("key1", 42)
+	require.Equal(t, uint64(1), vm.Version())
+
+	value, ok := vm.Get("key1")
+	require.True(t, ok)
+	require.Equal(t, 42, value)
+}
+
+func TestVersionedMap_Del(t *testing.T) {
+	t.Parallel()
+
+	vm := NewVersionedMap[string, int]()
+	vm.Set("key1", 42)
+	initialVersion := vm.Version()
+
+	vm.Del("key1")
+	require.Equal(t, initialVersion+1, vm.Version())
+
+	_, ok := vm.Get("key1")
+	require.False(t, ok)
+}
+
+func TestVersionedMap_VersionIncrement(t *testing.T) {
+	t.Parallel()
+
+	vm := NewVersionedMap[string, int]()
+	initialVersion := vm.Version()
+
+	// Setting a value should increment the version
+	vm.Set("key1", 42)
+	require.Equal(t, initialVersion+1, vm.Version())
+
+	// Deleting a value should increment the version
+	vm.Del("key1")
+	require.Equal(t, initialVersion+2, vm.Version())
+
+	// Deleting a non-existent key should still increment the version
+	vm.Del("nonexistent")
+	require.Equal(t, initialVersion+3, vm.Version())
+}
+
+func TestVersionedMap_ConcurrentAccess(t *testing.T) {
+	t.Parallel()
+
+	vm := NewVersionedMap[int, int]()
+	const numGoroutines = 100
+	const numOperations = 100
+
+	// Initial version
+	initialVersion := vm.Version()
+
+	// Perform concurrent Set and Del operations
+	for i := range numGoroutines {
+		go func(id int) {
+			for j := range numOperations {
+				key := id*numOperations + j
+				vm.Set(key, key*2)
+				vm.Del(key)
+			}
+		}(i)
+	}
+
+	// Wait for operations to complete by checking the version
+	// This is a simplified check - in a real test you might want to use sync.WaitGroup
+	expectedMinVersion := initialVersion + uint64(numGoroutines*numOperations*2)
+
+	// Allow some time for operations to complete
+	for vm.Version() < expectedMinVersion {
+		// Busy wait - in a real test you'd use proper synchronization
+	}
+
+	// Final version should be at least the expected minimum
+	require.GreaterOrEqual(t, vm.Version(), expectedMinVersion)
+	require.Equal(t, 0, vm.Len())
+}

internal/diff/diff.go

@@ -0,0 +1,29 @@
+package diff
+
+import (
+	"strings"
+
+	"github.com/aymanbagabas/go-udiff"
+)
+
+// GenerateDiff creates a unified diff from two file contents
+func GenerateDiff(beforeContent, afterContent, fileName string) (string, int, int) {
+	fileName = strings.TrimPrefix(fileName, "/")
+
+	var (
+		unified   = udiff.Unified("a/"+fileName, "b/"+fileName, beforeContent, afterContent)
+		additions = 0
+		removals  = 0
+	)
+
+	lines := strings.SplitSeq(unified, "\n")
+	for line := range lines {
+		if strings.HasPrefix(line, "+") && !strings.HasPrefix(line, "+++") {
+			additions++
+		} else if strings.HasPrefix(line, "-") && !strings.HasPrefix(line, "---") {
+			removals++
+		}
+	}
+
+	return unified, additions, removals
+}

internal/diffdetect/detect.go

@@ -0,0 +1,36 @@
+package diffdetect
+
+import "strings"
+
+// Signal describes which unified-diff markers were found while scanning text.
+type Signal struct {
+	HasHunk       bool
+	HasFileHeader bool
+	HasGitHeader  bool
+}
+
+// Inspect scans content for unified-diff markers.
+func Inspect(content string) Signal {
+	var signal Signal
+	for line := range strings.SplitSeq(content, "\n") {
+		if strings.HasPrefix(line, "@@") {
+			signal.HasHunk = true
+		}
+		if strings.HasPrefix(line, "--- ") || strings.HasPrefix(line, "+++ ") {
+			signal.HasFileHeader = true
+		}
+		if strings.HasPrefix(line, "diff --git ") {
+			signal.HasGitHeader = true
+		}
+	}
+	return signal
+}
+
+// IsUnifiedDiff reports whether content appears to be a unified diff.
+func IsUnifiedDiff(content string) bool {
+	signal := Inspect(content)
+	if signal.HasGitHeader && signal.HasFileHeader {
+		return true
+	}
+	return signal.HasHunk && signal.HasFileHeader
+}

internal/diffdetect/detect_test.go

@@ -0,0 +1,152 @@
+package diffdetect
+
+import "testing"
+
+func TestInspect(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		content string
+		want    Signal
+	}{
+		{
+			name: "git unified diff",
+			content: `diff --git a/main.go b/main.go
+--- a/main.go
++++ b/main.go
+@@ -1,2 +1,3 @@
+ package main
++import "fmt"
+`,
+			want: Signal{HasHunk: true, HasFileHeader: true, HasGitHeader: true},
+		},
+		{
+			name: "non-git unified diff",
+			content: `--- old.c
++++ old.c
+@@ -1 +1 @@
+-old
++new
+`,
+			want: Signal{HasHunk: true, HasFileHeader: true, HasGitHeader: false},
+		},
+		{
+			name:    "plain text",
+			content: "hello world",
+			want:    Signal{},
+		},
+		{
+			name:    "hunk only",
+			content: "@@ -1 +1 @@\n-old\n+new\n",
+			want:    Signal{HasHunk: true},
+		},
+		{
+			name:    "headers only",
+			content: "--- a/file\n+++ b/file\n",
+			want:    Signal{HasFileHeader: true},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := Inspect(tt.content)
+			if got != tt.want {
+				t.Errorf("Inspect() = %+v, want %+v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsUnifiedDiff(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		content string
+		want    bool
+	}{
+		{
+			name: "github-style multi-file diff",
+			content: `diff --git a/one.txt b/one.txt
+--- a/one.txt
++++ b/one.txt
+@@ -1 +1 @@
+-a
++b
+diff --git a/two.txt b/two.txt
+--- a/two.txt
++++ b/two.txt
+@@ -1 +1 @@
+-c
++d
+`,
+			want: true,
+		},
+		{
+			name: "non-git unified patch",
+			content: `--- a/old.c
++++ b/old.c
+@@ -1,3 +1,4 @@
+ #include <stdio.h>
+-int main() {
++int main(int argc, char **argv) {
+     return 0;
+ }
+`,
+			want: true,
+		},
+		{
+			name: "new file from dev null",
+			content: `--- /dev/null
++++ newfile.txt
+@@ -0,0 +1,2 @@
++hello
++world
+`,
+			want: true,
+		},
+		{
+			name: "markdown false positive candidate",
+			content: `- Item one
+- Item two
++ Bonus item
+- Item three
+`,
+			want: false,
+		},
+		{
+			name: "headers without hunk",
+			content: `--- a/somefile.txt
++++ b/somefile.txt
+Just some content here
+No hunk markers at all
+`,
+			want: false,
+		},
+		{
+			name: "hunk without headers",
+			content: `@@ -1,3 +1,4 @@
+ some line
+-another line
++changed line
+`,
+			want: false,
+		},
+		{
+			name:    "empty",
+			content: "",
+			want:    false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			if got := IsUnifiedDiff(tt.content); got != tt.want {
+				t.Errorf("IsUnifiedDiff() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

internal/filetracker/service.go

@@ -0,0 +1,93 @@
+// Package filetracker provides functionality to track file reads in sessions.
+package filetracker
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/charmbracelet/crush/internal/db"
+)
+
+// Service defines the interface for tracking file reads in sessions.
+type Service interface {
+	// RecordRead records when a file was read.
+	RecordRead(ctx context.Context, sessionID, path string)
+
+	// LastReadTime returns when a file was last read.
+	// Returns zero time if never read.
+	LastReadTime(ctx context.Context, sessionID, path string) time.Time
+
+	// ListReadFiles returns the paths of all files read in a session.
+	ListReadFiles(ctx context.Context, sessionID string) ([]string, error)
+}
+
+type service struct {
+	q *db.Queries
+}
+
+// NewService creates a new file tracker service.
+func NewService(q *db.Queries) Service {
+	return &service{q: q}
+}
+
+// RecordRead records when a file was read.
+func (s *service) RecordRead(ctx context.Context, sessionID, path string) {
+	if err := s.q.RecordFileRead(ctx, db.RecordFileReadParams{
+		SessionID: sessionID,
+		Path:      relpath(path),
+	}); err != nil {
+		slog.Error("Error recording file read", "error", err, "file", path)
+	}
+}
+
+// LastReadTime returns when a file was last read.
+// Returns zero time if never read.
+func (s *service) LastReadTime(ctx context.Context, sessionID, path string) time.Time {
+	readFile, err := s.q.GetFileRead(ctx, db.GetFileReadParams{
+		SessionID: sessionID,
+		Path:      relpath(path),
+	})
+	if err != nil {
+		return time.Time{}
+	}
+
+	return time.Unix(readFile.ReadAt, 0)
+}
+
+func relpath(path string) string {
+	path = filepath.Clean(path)
+	basepath, err := os.Getwd()
+	if err != nil {
+		slog.Warn("Error getting basepath", "error", err)
+		return path
+	}
+	relpath, err := filepath.Rel(basepath, path)
+	if err != nil {
+		slog.Warn("Error getting relpath", "error", err)
+		return path
+	}
+	return relpath
+}
+
+// ListReadFiles returns the paths of all files read in a session.
+func (s *service) ListReadFiles(ctx context.Context, sessionID string) ([]string, error) {
+	readFiles, err := s.q.ListSessionReadFiles(ctx, sessionID)
+	if err != nil {
+		return nil, fmt.Errorf("listing read files: %w", err)
+	}
+
+	basepath, err := os.Getwd()
+	if err != nil {
+		return nil, fmt.Errorf("getting working directory: %w", err)
+	}
+
+	paths := make([]string, 0, len(readFiles))
+	for _, rf := range readFiles {
+		paths = append(paths, filepath.Join(basepath, rf.Path))
+	}
+	return paths, nil
+}

internal/filetracker/service_test.go

@@ -0,0 +1,116 @@
+package filetracker
+
+import (
+	"context"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"github.com/charmbracelet/crush/internal/db"
+	"github.com/stretchr/testify/require"
+)
+
+type testEnv struct {
+	ctx context.Context
+	q   *db.Queries
+	svc Service
+}
+
+func setupTest(t *testing.T) *testEnv {
+	t.Helper()
+
+	conn, err := db.Connect(t.Context(), t.TempDir())
+	require.NoError(t, err)
+	t.Cleanup(func() { conn.Close() })
+
+	q := db.New(conn)
+	return &testEnv{
+		ctx: t.Context(),
+		q:   q,
+		svc: NewService(q),
+	}
+}
+
+func (e *testEnv) createSession(t *testing.T, sessionID string) {
+	t.Helper()
+	_, err := e.q.CreateSession(e.ctx, db.CreateSessionParams{
+		ID:    sessionID,
+		Title: "Test Session",
+	})
+	require.NoError(t, err)
+}
+
+func TestService_RecordRead(t *testing.T) {
+	env := setupTest(t)
+
+	sessionID := "test-session-1"
+	path := "/path/to/file.go"
+	env.createSession(t, sessionID)
+
+	env.svc.RecordRead(env.ctx, sessionID, path)
+
+	lastRead := env.svc.LastReadTime(env.ctx, sessionID, path)
+	require.False(t, lastRead.IsZero(), "expected non-zero time after recording read")
+	require.WithinDuration(t, time.Now(), lastRead, 2*time.Second)
+}
+
+func TestService_LastReadTime_NotFound(t *testing.T) {
+	env := setupTest(t)
+
+	lastRead := env.svc.LastReadTime(env.ctx, "nonexistent-session", "/nonexistent/path")
+	require.True(t, lastRead.IsZero(), "expected zero time for unread file")
+}
+
+func TestService_RecordRead_UpdatesTimestamp(t *testing.T) {
+	env := setupTest(t)
+
+	sessionID := "test-session-2"
+	path := "/path/to/file.go"
+	env.createSession(t, sessionID)
+
+	env.svc.RecordRead(env.ctx, sessionID, path)
+	firstRead := env.svc.LastReadTime(env.ctx, sessionID, path)
+	require.False(t, firstRead.IsZero())
+
+	synctest.Test(t, func(t *testing.T) {
+		time.Sleep(100 * time.Millisecond)
+		synctest.Wait()
+		env.svc.RecordRead(env.ctx, sessionID, path)
+		secondRead := env.svc.LastReadTime(env.ctx, sessionID, path)
+
+		require.False(t, secondRead.Before(firstRead), "second read time should not be before first")
+	})
+}
+
+func TestService_RecordRead_DifferentSessions(t *testing.T) {
+	env := setupTest(t)
+
+	path := "/shared/file.go"
+	session1, session2 := "session-1", "session-2"
+	env.createSession(t, session1)
+	env.createSession(t, session2)
+
+	env.svc.RecordRead(env.ctx, session1, path)
+
+	lastRead1 := env.svc.LastReadTime(env.ctx, session1, path)
+	require.False(t, lastRead1.IsZero())
+
+	lastRead2 := env.svc.LastReadTime(env.ctx, session2, path)
+	require.True(t, lastRead2.IsZero(), "session 2 should not see session 1's read")
+}
+
+func TestService_RecordRead_DifferentPaths(t *testing.T) {
+	env := setupTest(t)
+
+	sessionID := "test-session-3"
+	path1, path2 := "/path/to/file1.go", "/path/to/file2.go"
+	env.createSession(t, sessionID)
+
+	env.svc.RecordRead(env.ctx, sessionID, path1)
+
+	lastRead1 := env.svc.LastReadTime(env.ctx, sessionID, path1)
+	require.False(t, lastRead1.IsZero())
+
+	lastRead2 := env.svc.LastReadTime(env.ctx, sessionID, path2)
+	require.True(t, lastRead2.IsZero(), "path2 should not be recorded")
+}

internal/lock/lock.go

@@ -0,0 +1,75 @@
+// Package lock provides cross-process advisory file locking.
+//
+// File acquires an exclusive lock on the file at path, blocking until
+// the context is cancelled (or its deadline elapses). TryFile does the
+// same but returns ErrContended immediately if the lock is already
+// held. In both cases the returned release function drops the lock and
+// closes the underlying file descriptor.
+//
+// The lock is released automatically by the kernel on process
+// termination (including crash), so no stale-lock recovery is needed.
+//
+// The lock file at path is created if it does not exist. It is never
+// unlinked — flock is keyed by inode, not path, and unlinking could
+// create a window where two processes lock different inodes at the
+// same path.
+//
+// This is the canonical file-locking helper for Crush. Callers should
+// prefer it over rolling their own platform-specific code.
+package lock
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+)
+
+// ErrContended is returned by TryFile when the lock is already held by
+// another process.
+var ErrContended = errors.New("file lock is held by another process")
+
+// File acquires an exclusive advisory lock on the file at path, blocking
+// until the lock is acquired or ctx is cancelled. It returns a release
+// function that drops the lock and closes the underlying file descriptor.
+//
+// Pass a context with a deadline (e.g. context.WithTimeout) to bound the
+// wait. Pass context.Background() to block indefinitely.
+func File(ctx context.Context, path string) (func(), error) {
+	f, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE, 0o600)
+	if err != nil {
+		return nil, fmt.Errorf("open lock file %q: %w", path, err)
+	}
+
+	release, err := lockFile(ctx, f)
+	if err != nil {
+		f.Close()
+		return nil, err
+	}
+
+	return func() {
+		release()
+		f.Close()
+	}, nil
+}
+
+// TryFile is like File but returns ErrContended immediately if the lock
+// is already held by another process. Use this when you want to fail
+// fast rather than wait.
+func TryFile(path string) (func(), error) {
+	f, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE, 0o600)
+	if err != nil {
+		return nil, fmt.Errorf("open lock file %q: %w", path, err)
+	}
+
+	release, err := tryLockFile(f)
+	if err != nil {
+		f.Close()
+		return nil, err
+	}
+
+	return func() {
+		release()
+		f.Close()
+	}, nil
+}

internal/lock/lock_test.go

@@ -0,0 +1,168 @@
+package lock
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestTryFile_AcquiresWhenFree(t *testing.T) {
+	t.Parallel()
+	path := filepath.Join(t.TempDir(), "test.lock")
+
+	release, err := TryFile(path)
+	require.NoError(t, err)
+	require.NotNil(t, release)
+	release()
+}
+
+func TestTryFile_ReturnsErrContendedWhenHeld(t *testing.T) {
+	t.Parallel()
+	path := filepath.Join(t.TempDir(), "test.lock")
+
+	release, err := TryFile(path)
+	require.NoError(t, err)
+	t.Cleanup(release)
+
+	_, err = TryFile(path)
+	require.ErrorIs(t, err, ErrContended)
+}
+
+func TestTryFile_ReacquireAfterRelease(t *testing.T) {
+	t.Parallel()
+	path := filepath.Join(t.TempDir(), "test.lock")
+
+	release, err := TryFile(path)
+	require.NoError(t, err)
+	release()
+
+	release2, err := TryFile(path)
+	require.NoError(t, err)
+	t.Cleanup(release2)
+}
+
+func TestFile_AcquiresWhenFree(t *testing.T) {
+	t.Parallel()
+	path := filepath.Join(t.TempDir(), "test.lock")
+
+	release, err := File(context.Background(), path)
+	require.NoError(t, err)
+	t.Cleanup(release)
+}
+
+func TestFile_BlocksThenSucceeds(t *testing.T) {
+	t.Parallel()
+	path := filepath.Join(t.TempDir(), "test.lock")
+
+	release, err := TryFile(path)
+	require.NoError(t, err)
+
+	// Release the lock after a short delay so the blocking acquirer
+	// can complete within the test timeout.
+	go func() {
+		time.Sleep(150 * time.Millisecond)
+		release()
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	release2, err := File(ctx, path)
+	require.NoError(t, err, "should acquire after first releases")
+	release2()
+}
+
+func TestFile_RespectsContextDeadline(t *testing.T) {
+	t.Parallel()
+	path := filepath.Join(t.TempDir(), "test.lock")
+
+	release, err := TryFile(path)
+	require.NoError(t, err)
+	t.Cleanup(release)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	_, err = File(ctx, path)
+	elapsed := time.Since(start)
+	require.Error(t, err)
+	require.True(t, errors.Is(err, context.DeadlineExceeded), "expected deadline exceeded, got %v", err)
+	require.Less(t, elapsed, 1*time.Second, "should return promptly after deadline")
+}
+
+func TestFile_RespectsContextCancellation(t *testing.T) {
+	t.Parallel()
+	path := filepath.Join(t.TempDir(), "test.lock")
+
+	release, err := TryFile(path)
+	require.NoError(t, err)
+	t.Cleanup(release)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() {
+		_, err := File(ctx, path)
+		done <- err
+	}()
+
+	time.Sleep(50 * time.Millisecond)
+	cancel()
+
+	select {
+	case err := <-done:
+		require.ErrorIs(t, err, context.Canceled)
+	case <-time.After(2 * time.Second):
+		t.Fatal("File did not return after context cancellation")
+	}
+}
+
+// TestFile_ConcurrentAcquirers verifies that multiple blocking acquirers
+// queue up correctly: each gets the lock in turn, exactly one at a time.
+func TestFile_ConcurrentAcquirers(t *testing.T) {
+	t.Parallel()
+	path := filepath.Join(t.TempDir(), "test.lock")
+
+	const n = 5
+	var (
+		mu       sync.Mutex
+		inside   int
+		maxSeen  int
+		finished int
+	)
+	var wg sync.WaitGroup
+	wg.Add(n)
+	for range n {
+		go func() {
+			defer wg.Done()
+			ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+			defer cancel()
+			release, err := File(ctx, path)
+			if err != nil {
+				t.Errorf("acquire failed: %v", err)
+				return
+			}
+			mu.Lock()
+			inside++
+			if inside > maxSeen {
+				maxSeen = inside
+			}
+			mu.Unlock()
+
+			time.Sleep(20 * time.Millisecond)
+
+			mu.Lock()
+			inside--
+			finished++
+			mu.Unlock()
+			release()
+		}()
+	}
+	wg.Wait()
+
+	require.Equal(t, n, finished)
+	require.Equal(t, 1, maxSeen, "lock must be mutually exclusive")
+}

internal/lock/lock_unix.go

@@ -0,0 +1,45 @@
+//go:build !windows
+
+package lock
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	"golang.org/x/sys/unix"
+)
+
+// retrySleep is the interval between non-blocking flock retries in the
+// blocking File path. Small enough that contention resolution feels
+// snappy; large enough that we don't burn a CPU spinning.
+const retrySleep = 100 * time.Millisecond
+
+func lockFile(ctx context.Context, f *os.File) (func(), error) {
+	for {
+		err := unix.Flock(int(f.Fd()), unix.LOCK_EX|unix.LOCK_NB)
+		if err == nil {
+			return func() { _ = unix.Flock(int(f.Fd()), unix.LOCK_UN) }, nil
+		}
+		if !errors.Is(err, unix.EWOULDBLOCK) {
+			return nil, fmt.Errorf("flock: %w", err)
+		}
+		select {
+		case <-ctx.Done():
+			return nil, fmt.Errorf("acquire lock: %w", ctx.Err())
+		case <-time.After(retrySleep):
+		}
+	}
+}
+
+func tryLockFile(f *os.File) (func(), error) {
+	if err := unix.Flock(int(f.Fd()), unix.LOCK_EX|unix.LOCK_NB); err != nil {
+		if errors.Is(err, unix.EWOULDBLOCK) {
+			return nil, ErrContended
+		}
+		return nil, fmt.Errorf("flock: %w", err)
+	}
+	return func() { _ = unix.Flock(int(f.Fd()), unix.LOCK_UN) }, nil
+}

internal/lock/lock_windows.go

@@ -0,0 +1,57 @@
+//go:build windows
+
+package lock
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"math"
+	"os"
+	"time"
+
+	"golang.org/x/sys/windows"
+)
+
+// retrySleep is the interval between non-blocking lock retries in the
+// blocking File path.
+const retrySleep = 100 * time.Millisecond
+
+func lockFile(ctx context.Context, f *os.File) (func(), error) {
+	h := windows.Handle(f.Fd())
+	for {
+		ol := new(windows.Overlapped)
+		flags := uint32(windows.LOCKFILE_EXCLUSIVE_LOCK | windows.LOCKFILE_FAIL_IMMEDIATELY)
+		err := windows.LockFileEx(h, flags, 0, math.MaxUint32, math.MaxUint32, ol)
+		if err == nil {
+			return func() {
+				ol := new(windows.Overlapped)
+				_ = windows.UnlockFileEx(windows.Handle(f.Fd()), 0, math.MaxUint32, math.MaxUint32, ol)
+			}, nil
+		}
+		if !errors.Is(err, windows.ERROR_LOCK_VIOLATION) && !errors.Is(err, windows.ERROR_IO_PENDING) {
+			return nil, fmt.Errorf("LockFileEx: %w", err)
+		}
+		select {
+		case <-ctx.Done():
+			return nil, fmt.Errorf("acquire lock: %w", ctx.Err())
+		case <-time.After(retrySleep):
+		}
+	}
+}
+
+func tryLockFile(f *os.File) (func(), error) {
+	h := windows.Handle(f.Fd())
+	ol := new(windows.Overlapped)
+	flags := uint32(windows.LOCKFILE_EXCLUSIVE_LOCK | windows.LOCKFILE_FAIL_IMMEDIATELY)
+	if err := windows.LockFileEx(h, flags, 0, math.MaxUint32, math.MaxUint32, ol); err != nil {
+		if errors.Is(err, windows.ERROR_LOCK_VIOLATION) || errors.Is(err, windows.ERROR_IO_PENDING) {
+			return nil, ErrContended
+		}
+		return nil, fmt.Errorf("LockFileEx: %w", err)
+	}
+	return func() {
+		ol := new(windows.Overlapped)
+		_ = windows.UnlockFileEx(windows.Handle(f.Fd()), 0, math.MaxUint32, math.MaxUint32, ol)
+	}, nil
+}

internal/logout/choose.go

@@ -0,0 +1,160 @@
+package logout
+
+import (
+	"errors"
+	"strings"
+
+	"charm.land/bubbles/v2/help"
+	"charm.land/bubbles/v2/key"
+	tea "charm.land/bubbletea/v2"
+	"charm.land/lipgloss/v2"
+)
+
+type chooseKeyMap struct {
+	Up      key.Binding
+	Down    key.Binding
+	Confirm key.Binding
+	Cancel  key.Binding
+}
+
+func defaultChooseKeyMap() chooseKeyMap {
+	return chooseKeyMap{
+		Up:      key.NewBinding(key.WithKeys("up", "k"), key.WithHelp("↑/↓", "select")),
+		Down:    key.NewBinding(key.WithKeys("down", "j"), key.WithHelp("", "")),
+		Confirm: key.NewBinding(key.WithKeys("enter"), key.WithHelp("enter", "confirm")),
+		Cancel:  key.NewBinding(key.WithKeys("ctrl+c", "esc"), key.WithHelp("esc", "cancel")),
+	}
+}
+
+func (k chooseKeyMap) ShortHelp() []key.Binding {
+	return []key.Binding{k.Up, k.Confirm, k.Cancel}
+}
+
+func (k chooseKeyMap) FullHelp() [][]key.Binding {
+	return [][]key.Binding{{k.Up, k.Down, k.Confirm, k.Cancel}}
+}
+
+// chooseModel is the Bubble Tea model for a multiple choice question with
+// a ">" cursor.
+type chooseModel struct {
+	question string
+	options  []string
+	cursor   int
+	chosen   int
+
+	help   help.Model
+	keymap chooseKeyMap
+
+	quitting   bool
+	blankLines int
+	width      int
+}
+
+func newChooseModel(question string, options []string) chooseModel {
+	return chooseModel{
+		question: question,
+		options:  options,
+		chosen:   -1,
+		help:     help.New(),
+		keymap:   defaultChooseKeyMap(),
+	}
+}
+
+// runChoose runs the multiple choice TUI and returns the selected option
+// index, or -1 when canceled.
+func runChoose(question string, options []string) (int, error) {
+	p := tea.NewProgram(newChooseModel(question, options))
+	final, err := p.Run()
+	if err != nil {
+		return -1, err
+	}
+	m, ok := final.(chooseModel)
+	if !ok {
+		return -1, errors.New("unexpected choose program model")
+	}
+	return m.chosen, nil
+}
+
+// Init initializes the choose TUI.
+func (m chooseModel) Init() tea.Cmd {
+	return nil
+}
+
+// Update handles messages for the choose TUI.
+func (m chooseModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	switch msg := msg.(type) {
+	case tea.WindowSizeMsg:
+		m.width = msg.Width
+		m.help.SetWidth(msg.Width)
+		return m, nil
+
+	case tea.KeyPressMsg:
+		switch {
+		case key.Matches(msg, m.keymap.Cancel):
+			m.quitting = true
+			m.blankLines = m.contentHeight()
+			return m, tea.Quit
+		case key.Matches(msg, m.keymap.Confirm):
+			m.chosen = m.cursor
+			m.quitting = true
+			m.blankLines = m.contentHeight()
+			return m, tea.Quit
+		case key.Matches(msg, m.keymap.Up):
+			m.cursor--
+			if m.cursor < 0 {
+				m.cursor = len(m.options) - 1
+			}
+			return m, nil
+		case key.Matches(msg, m.keymap.Down):
+			m.cursor++
+			if m.cursor >= len(m.options) {
+				m.cursor = 0
+			}
+			return m, nil
+		}
+	}
+	return m, nil
+}
+
+// content renders the full choose view. The trailing zero-width space
+// keeps the final blank line alive (the renderer erases trailing empty
+// lines).
+func (m chooseModel) content() string {
+	var b strings.Builder
+
+	b.WriteString("\n  ")
+	b.WriteString(questionStyle.Render(m.question))
+	b.WriteString("\n\n")
+	for i, option := range m.options {
+		if i == m.cursor {
+			b.WriteString("  " + choiceSelectedStyle.Render("> "+option))
+		} else {
+			b.WriteString("    " + option)
+		}
+		if i < len(m.options)-1 {
+			b.WriteString("\n")
+		}
+	}
+	b.WriteString("\n\n  ")
+	b.WriteString(m.help.View(m.keymap))
+	b.WriteString("\n")
+	return b.String()
+}
+
+// contentHeight returns the height of the current view in lines.
+func (m chooseModel) contentHeight() int {
+	return lipgloss.Height(m.content())
+}
+
+// View renders the choose TUI.
+func (m chooseModel) View() tea.View {
+	if m.quitting {
+		// Render the same number of blank lines as the last frame so the
+		// renderer overwrites it and the TUI disappears on exit. A truly
+		// empty view doesn't work under Fang's wrapped output: the renderer
+		// drops the touched-lines buffer when the height shrinks to zero
+		// and leaves the frame on screen.
+		return tea.NewView("")
+	}
+	return tea.NewView(m.content())
+}