config

type AliasConfig struct {
	// Name is the unique alias identifier (e.g. "myproj"). Must match ^[\w-]+$.
	Name string `json:"name"`
	// Group is an optional display group for palette organization.
	Group string `json:"group,omitempty"`
	// Path is the working directory for the session (supports ~/... expansion).
	Path string `json:"path,omitempty"`
	// Description is a human-readable summary shown in the palette.
	Description string `json:"description,omitempty"`
	// Profile is the named profile to apply when resolving defaults.
	Profile string `json:"profile,omitempty"`
	// Program overrides the default program (e.g. "aider").
	Program string `json:"program,omitempty"`
	// AutoYes auto-approves all prompts for this alias.
	AutoYes bool `json:"auto_yes,omitempty"`
	// Tags are pre-applied to sessions created from this alias.
	Tags []string `json:"tags,omitempty"`
	// EnvVars are environment variables set for sessions from this alias.
	EnvVars map[string]string `json:"env_vars,omitempty"`
	// CLIFlags are CLI flags appended to the program command for this alias.
	// At session creation, invocation-time extraFlags are appended after these.
	CLIFlags string `json:"cli_flags,omitempty"`
	// SessionType overrides the session creation mode for this alias.
	// SessionTypeDefault (empty) means use the default (directory session).
	SessionType SessionType `json:"session_type,omitempty"`
	// NamePrefix is prepended to the user-supplied session label when naming sessions.
	// For example, prefix "ssq-" + label "my-feature" → session name "ssq-my-feature".
	NamePrefix string `json:"name_prefix,omitempty"`
}

type AppState interface {
	// GetHelpScreensSeen returns the bitmask of seen help screens
	GetHelpScreensSeen() uint32
	// SetHelpScreensSeen updates the bitmask of seen help screens
	SetHelpScreensSeen(seen uint32) error
}

type BrowserPassthroughCDPConfig struct {
	// ScreencastQuality is the JPEG compression quality (1–100).
	// Default: 70.
	ScreencastQuality int `json:"screencast_quality,omitempty"`
	// ScreencastMaxWidth is the maximum frame width in pixels.
	// Default: 1280.
	ScreencastMaxWidth int `json:"screencast_max_width,omitempty"`
	// ScreencastMaxHeight is the maximum frame height in pixels.
	// Default: 800.
	ScreencastMaxHeight int `json:"screencast_max_height,omitempty"`
	// ScreencastMaxFPS is the target frame-rate cap (frames per second).
	// Default: 15 (one frame delivered every ~67 ms via everyNthFrame heuristic).
	ScreencastMaxFPS int `json:"screencast_max_fps,omitempty"`
}

type BrowserPassthroughConfig struct {
	// Enabled controls whether VNC is started for new sessions.
	// When nil (absent from config), VNC is enabled when required binaries are present.
	// Set to false to unconditionally disable VNC for all sessions.
	Enabled *bool `json:"enabled,omitempty"`
	// DisplayBase is the first X11 display number to allocate (e.g. 100 for :100).
	// Default: 100.
	DisplayBase int `json:"display_base,omitempty"`
	// DisplayRangeMax is the number of display numbers to search above DisplayBase.
	// Default: 100 (searches :100–:199).
	DisplayRangeMax int `json:"display_range_max,omitempty"`
	// Resolution is the Xvfb screen resolution string (WxHxDepth).
	// Default: "1280x800x24".
	Resolution string `json:"resolution,omitempty"`
	// CDP holds tunable parameters for the CDP screencast stream.
	// Absent (zero) values are filled in by CDPConfigOrDefault().
	CDP BrowserPassthroughCDPConfig `json:"cdp,omitempty"`
}

type CapacityConfig struct {
	// TransitionMode controls auto vs manual transition. Default: "manual".
	TransitionMode TransitionMode `json:"transition_mode,omitempty"`
	// ContextWindowWarnPct is the context usage percentage to trigger a warning. Default: 0.75.
	ContextWindowWarnPct float64 `json:"context_window_warn_pct,omitempty"`
	// ContextWindowAutoPct is the context usage percentage to trigger auto-transition (in auto mode). Default: 0.90.
	ContextWindowAutoPct float64 `json:"context_window_auto_pct,omitempty"`
	// RateLimitWarnRemaining triggers a warning when remaining requests fall below this. Default: 10.
	RateLimitWarnRemaining int `json:"rate_limit_warn_remaining,omitempty"`
	// CostBudgetUSD is the accumulated USD cost limit. 0 means no limit. Default: 0.
	CostBudgetUSD float64 `json:"cost_budget_usd,omitempty"`
	// PollIntervalSeconds controls limit API querying frequency. Default: 60.
	PollIntervalSeconds int `json:"poll_interval_seconds,omitempty"`
	// ProviderPriority lists fallback providers in order of preference.
	ProviderPriority []ProviderPriority `json:"provider_priority,omitempty"`
}

type ClaudeConfigManager struct {
	// contains filtered or unexported fields
}

type CommandExecutor interface {
	Command(name string, args ...string) *exec.Cmd
	Output(cmd *exec.Cmd) ([]byte, error)
	LookPath(file string) (string, error)
}

type Config struct {

	// ListenAddress is the address the HTTP server listens on.
	// Default: "localhost:8543". Set to "0.0.0.0:8543" for remote access.
	ListenAddress string `json:"listen_address"`
	// PasskeyRPID is the WebAuthn Relying Party ID (effective domain, no scheme/port).
	// Example: "192.168.1.42" or "myhost.local". Must match the hostname clients use.
	// Required when remote access is enabled.
	PasskeyRPID string `json:"passkey_rp_id"`
	// PasskeyEnabled controls whether passkey authentication is enforced.
	// Automatically set to true when non-localhost listen address is used.
	PasskeyEnabled bool `json:"passkey_enabled"`
	// DefaultProgram is the default program to run in new instances
	DefaultProgram string `json:"default_program"`
	// AutoYes is a flag to automatically accept all prompts.
	AutoYes bool `json:"auto_yes"`
	// DaemonPollInterval is the interval (ms) at which the daemon polls sessions for autoyes mode.
	DaemonPollInterval int `json:"daemon_poll_interval"`
	// BranchPrefix is the prefix used for git branches created by the application.
	BranchPrefix string `json:"branch_prefix"`
	// DetectNewSessions is a flag to enable detection of new sessions from other windows
	DetectNewSessions bool `json:"detect_new_sessions"`
	// SessionDetectionInterval is the interval (ms) at which the daemon checks for new sessions
	SessionDetectionInterval int `json:"session_detection_interval"`
	// StateRefreshInterval is the interval (ms) at which the state is refreshed from disk
	StateRefreshInterval int `json:"state_refresh_interval"`
	// LogsEnabled is a flag to enable logging to files
	LogsEnabled bool `json:"logs_enabled"`
	// LogsDir is the directory where logs are stored (defaults to ~/.stapler-squad/logs)
	LogsDir string `json:"logs_dir"`
	// LogMaxSize is the maximum size of a log file in megabytes before it gets rotated
	LogMaxSize int `json:"log_max_size"`
	// LogMaxFiles is the maximum number of rotated log files to keep (not including the current log file)
	LogMaxFiles int `json:"log_max_files"`
	// LogMaxAge is the maximum number of days to keep rotated log files
	LogMaxAge int `json:"log_max_age"`
	// LogCompress is a flag to enable compression of rotated log files
	LogCompress bool `json:"log_compress"`
	// UseSessionLogs is a flag to enable per-session log files
	UseSessionLogs bool `json:"use_session_logs"`
	// TmuxSessionPrefix allows customizing the tmux session prefix for process isolation
	TmuxSessionPrefix string `json:"tmux_session_prefix"`
	// PerformBackgroundHealthChecks enables non-blocking health checks for session maintenance
	PerformBackgroundHealthChecks bool `json:"perform_background_health_checks"`
	// KeyCategories defines custom category mappings for key bindings in help system
	KeyCategories map[string]string `json:"key_categories"`
	// VCSPreference controls which version control system to prefer when both are available
	// Options: "auto" (prefer JJ if available), "jj" (always use JJ), "git" (always use Git)
	VCSPreference string `json:"vcs_preference"`
	// AvailablePrograms is a list of detected CLI programs
	AvailablePrograms []string `json:"available_programs"`
	// ConfigVersion tracks the schema version for future migrations (1 = session_defaults added)
	ConfigVersion int `json:"config_version,omitempty"`
	// SessionDefaults holds named profiles, directory rules, and global defaults for new sessions.
	SessionDefaults SessionDefaults `json:"session_defaults,omitempty"`
	// Notifications holds the user's notification delivery preferences.
	Notifications NotificationPrefs `json:"notifications,omitempty"`
	// OneOffBaseDir is the base directory where one-off session directories are created.
	// Default: "~/oneoff". Tilde is expanded at runtime. Created automatically on first use.
	OneOffBaseDir string `json:"one_off_base_dir,omitempty"`
	// PyroscopeServerAddress is the Pyroscope server URL for continuous profiling.
	// Empty string (the default) disables continuous profiling.
	// Example: "http://localhost:4040"
	PyroscopeServerAddress string `json:"pyroscope_server_address,omitempty"`
	// NewProjectBaseDir is the base directory where new project directories are created.
	// Default: "~/Projects". Tilde is expanded at runtime. Created on first use.
	// Zero-value (empty string) is backwards-compatible — existing configs load without change.
	NewProjectBaseDir string `json:"new_project_base_dir,omitempty"`
	// MachineEncryptionKey is a base64-encoded 32-byte AES-256-GCM key for local data encryption.
	// Generated on first run and persisted here. Used to encrypt sensitive token data in ItemSource configs.
	MachineEncryptionKey string `json:"machine_encryption_key,omitempty"`
	// AnalyticsMaxRows is the maximum number of analytics events to retain in the database.
	// When exceeded, the oldest rows are deleted. 0 means no row-count limit.
	// Default: 100_000.
	AnalyticsMaxRows int `json:"analytics_max_rows,omitempty"`
	// AnalyticsMaxAgeDays is the maximum age in days of analytics events to retain.
	// Events older than this are deleted. 0 means no age limit.
	// Default: 90.
	AnalyticsMaxAgeDays int `json:"analytics_max_age_days,omitempty"`
	// BrowserPassthrough configures the per-session Xvfb + x11vnc virtual display feature.
	BrowserPassthrough BrowserPassthroughConfig `json:"browser_passthrough,omitempty"`
	// FeatureFlags stores the enabled/disabled state of named runtime feature flags.
	// Keys are machine names (e.g. "backlog"); values are booleans.
	// Absent key == disabled (false is the safe default for all flags).
	FeatureFlags map[string]bool `json:"feature_flags,omitempty"`
	// Hibernation holds configuration for the session hibernation feature.
	Hibernation HibernationConfig `json:"hibernation,omitempty"`
	// Capacity holds configuration for the provider capacity monitoring and transition feature.
	Capacity CapacityConfig `json:"capacity,omitempty"`
	// TmuxExecGate bounds concurrent tmux subprocess execution across all processes.
	TmuxExecGate TmuxExecGateConfig `json:"tmux_exec_gate,omitempty"`

	// EscapeAnalyticsCaptureLevel controls the verbosity of escape sequence capture.
	// Valid values: "full" (store raw bytes + hash), "summary" (type/length only), "off" (disabled).
	// Default: "summary".
	EscapeAnalyticsCaptureLevel string `json:"escapeAnalyticsCaptureLevel,omitempty"`
	// EscapeAnalyticsSamplingRate is the fraction of sessions to capture, in [0.0, 1.0].
	// 1.0 captures all sessions; 0.0 captures none.
	// A nil pointer means "unset" and defaults to 1.0 at load time.
	// Using a pointer allows 0.0 (capture nothing) to be distinguished from the zero value.
	// Default: 1.0.
	EscapeAnalyticsSamplingRate *float64 `json:"escapeAnalyticsSamplingRate,omitempty"`
	// EscapeAnalyticsMaxRowsPerSession is the maximum number of escape event rows stored per session.
	// Default: 10000.
	EscapeAnalyticsMaxRowsPerSession int `json:"escapeAnalyticsMaxRowsPerSession,omitempty"`
	// EscapeAnalyticsDisableOSCRedaction disables OSC payload redaction when true.
	// By default (false), OSC payloads (clipboard, window title, CWD) are redacted for security.
	// Set to true only if you explicitly need to capture raw OSC payload content.
	EscapeAnalyticsDisableOSCRedaction bool `json:"escapeAnalyticsDisableOSCRedaction,omitempty"`
	// EscapeAnalyticsRetentionDays is the number of days to retain escape event rows.
	// Default: 7.
	EscapeAnalyticsRetentionDays int `json:"escapeAnalyticsRetentionDays,omitempty"`
	// AnthropicAPIKey is the API key for the Anthropic AI API.
	// Used by the AI rule generation feature (GenerateSuggestedRule RPC).
	// Set via config.json or the ANTHROPIC_API_KEY environment variable.
	// Do not log this value.
	AnthropicAPIKey string `json:"anthropicApiKey,omitempty"`
	// ProcessManagerBackend selects the process manager implementation.
	// Valid values: "tmux" (default), "native" (Phase 2).
	// Empty string is backwards-compatible and defaults to "tmux".
	ProcessManagerBackend string `json:"process_manager_backend,omitempty"`
	// contains filtered or unexported fields
}

type ConfigFile struct {
	// Name is the filename (e.g., "CLAUDE.md", "settings.json", "agents.md")
	Name string
	// Path is the absolute path to the file
	Path string
	// Content is the file contents
	Content string
	// ModTime is the last modification timestamp
	ModTime time.Time
}

type DirectoryRule struct {
	// Path is the absolute path prefix to match (longest match wins).
	Path string `json:"path"`
	// Profile is the optional named profile to apply when this rule matches.
	Profile string `json:"profile,omitempty"`
	// Overrides are field-level overrides applied after the profile (if any).
	Overrides ProfileDefaults `json:"overrides,omitempty"`
}

type DiscoveryConfig struct {
	// Mode determines which types of instances to discover
	Mode DiscoveryMode `json:"mode"`

	// AllowExternalAttach controls whether users can attach to external instances
	AllowExternalAttach bool `json:"allow_external_attach"`

	// ConfirmExternalOperations requires confirmation before operations on external instances
	ConfirmExternalOperations bool `json:"confirm_external_operations"`

	// SocketPaths defines custom socket paths for discovery (optional)
	// Empty means use system defaults (/tmp/tmux-*/default)
	SocketPaths []string `json:"socket_paths"`

	// ExcludedSocketPaths defines socket paths to skip during discovery
	ExcludedSocketPaths []string `json:"excluded_socket_paths"`

	// DiscoverInterval is the interval (ms) at which external instances are scanned
	DiscoverInterval int `json:"discover_interval"`

	// AutoRefreshExternal enables automatic refresh of external instance metadata
	AutoRefreshExternal bool `json:"auto_refresh_external"`
}

type DiscoveryMode string

type HibernationConfig struct {
	// Enabled controls whether hibernation is active. Default: true.
	Enabled bool `json:"enabled"`
	// IdleTimeoutMinutes is the number of minutes a session must be idle before
	// the sweeper automatically hibernates it. Default: 20.
	IdleTimeoutMinutes int `json:"idle_timeout_minutes"`
	// ResourcePressureThreshold is the memory usage percentage at which the
	// sweeper begins hibernating idle sessions. Default: 85.
	ResourcePressureThreshold int `json:"resource_pressure_threshold_pct"`
	// CheckpointDir is the directory where hibernation checkpoint data is stored.
	// Default: "~/.stapler-squad/checkpoints". Tilde is expanded at runtime.
	CheckpointDir string `json:"checkpoint_dir"`
	// RetentionDays is the number of days to retain stale checkpoint data.
	// Default: 30.
	RetentionDays int `json:"retention_days"`
}

type NotificationPrefs struct {
	// PushEnabled controls whether web push notifications are sent.
	// Default is false (opt-in).
	PushEnabled bool `json:"push_enabled"`
}

type ProfileDefaults struct {
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	Program     string            `json:"program,omitempty"`
	AutoYes     bool              `json:"auto_yes,omitempty"`
	Tags        []string          `json:"tags,omitempty"`
	EnvVars     map[string]string `json:"env_vars,omitempty"`
	CLIFlags    string            `json:"cli_flags,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
	UpdatedAt   time.Time         `json:"updated_at"`
}

type ProviderPriority struct {
	CLI   string `json:"cli"`
	Model string `json:"model"`
}

type ResolvedDefaults struct {
	Program  string
	AutoYes  bool
	Tags     []string
	EnvVars  map[string]string
	CLIFlags string

	// Path is the working directory path from an alias (empty for non-alias resolution).
	Path string
	// Branch is the git branch hint from alias invocation (e.g. from @alias:branch).
	Branch string
	// SessionLabel is the session label from alias invocation (text between alias and --)
	SessionLabel string

	// Source tracking — which layers contributed to this result.
	UsedGlobal       bool
	UsedDirectory    bool
	UsedProfile      bool
	MatchedDirectory string
}

type SessionDefaults struct {
	// Program is the default AI program (e.g., "claude", "aider").
	Program string `json:"program,omitempty"`
	// AutoYes auto-approves prompts in new sessions.
	AutoYes bool `json:"auto_yes,omitempty"`
	// Tags are pre-applied to every new session.
	Tags []string `json:"tags,omitempty"`
	// EnvVars are environment variables passed to new sessions.
	EnvVars map[string]string `json:"env_vars,omitempty"`
	// CLIFlags are additional CLI flags for the program.
	CLIFlags string `json:"cli_flags,omitempty"`
	// Profiles maps profile name → profile configuration.
	Profiles map[string]ProfileDefaults `json:"profiles,omitempty"`
	// DirectoryRules are path-based rules matched against the session's working directory.
	DirectoryRules []DirectoryRule `json:"directory_rules,omitempty"`
	// Aliases are named session presets invoked via @name in the omnibar.
	Aliases []AliasConfig `json:"aliases,omitempty"`
}

type SessionType string

type State struct {
	// HelpScreensSeen is a bitmask tracking which help screens have been shown
	HelpScreensSeen uint32 `json:"help_screens_seen"`
	// UI stores the UI preferences and state
	UI UIState `json:"ui"`
	// contains filtered or unexported fields
}

type StateManager interface {
	AppState
	UIStateAccess

	// RefreshState reloads state from disk to detect changes made by other processes
	RefreshState() error

	// Close releases any resources held by the state manager
	Close() error
}

type TmuxExecGateConfig struct {
	// Slots is the number of concurrent tmux subprocess execution slots.
	// Zero or unset means "use the default" — see SlotsOrDefault. Default: 8.
	Slots int `json:"slots"`
}

type TransitionMode string

type UIState struct {
	// HidePaused controls whether paused sessions are filtered out
	HidePaused bool `json:"hide_paused"`
	// CategoryExpanded maps category names to their expanded state
	CategoryExpanded map[string]bool `json:"category_expanded"`
	// SearchMode tracks if search mode was active
	SearchMode bool `json:"search_mode"`
	// SearchQuery holds the last search query
	SearchQuery string `json:"search_query"`
	// SelectedIdx tracks the last selected session index
	SelectedIdx int `json:"selected_idx"`
}

type UIStateAccess interface {
	// GetUIState returns a copy of the current UI state
	GetUIState() UIState
	// SetHidePaused updates the hide paused filter state
	SetHidePaused(hidePaused bool) error
	// SetCategoryExpanded updates the expanded state for a category
	SetCategoryExpanded(category string, expanded bool) error
	// GetCategoryExpanded returns whether a category is expanded
	GetCategoryExpanded(category string) bool
	// SetSearchMode updates the search mode state
	SetSearchMode(searchMode bool, query string) error
	// GetSearchState returns the current search mode and query
	GetSearchState() (bool, string)
	// SetSelectedIndex updates the selected session index
	SetSelectedIndex(index int) error
	// GetSelectedIndex returns the last selected session index
	GetSelectedIndex() int
}

type WorkspaceMeta struct {
	WorkspaceID string    `json:"workspace_id"` // dir name (hash or instance name)
	Type        string    `json:"type"`         // "workspace", "instance", "shared"
	CWD         string    `json:"cwd"`
	Name        string    `json:"name"`       // last path component of CWD, or "Default"
	ConfigDir   string    `json:"config_dir"` // absolute path to this workspace dir
	LastUsed    time.Time `json:"last_used"`
}