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 CallbackConfig struct {
	// OnSessionCompleteURL receives a POST when a backlog item transitions to
	// BacklogStatusDone. Empty string means disabled.
	OnSessionCompleteURL string `json:"on_session_complete_url,omitempty"`
	// OnSessionStaleURL receives a POST the first time a work session is
	// detected stale (StuckReasonStaleWork). Empty string means disabled.
	OnSessionStaleURL string `json:"on_session_stale_url,omitempty"`
	// OnQueueItemCreatedURL receives a POST when an item is added to the
	// review queue. Empty string means disabled.
	OnQueueItemCreatedURL string `json:"on_queue_item_created_url,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"`
	// Remotes is a named list of SSH-reachable remote hosts sessions can be
	// created against (ssh-remote-workspaces feature). Holds connection
	// coordinates only — no SSH key material; see RemoteConfig's doc
	// comment. Looked up by name via RemoteByName.
	Remotes []RemoteConfig `json:"remotes,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"`
	// ClaimantHostID is a randomly generated identifier for THIS physical process/config
	// directory, generated on first use and persisted here. Recorded on backlog ItemSession
	// rows to show which host/process claimed or attached a session (see
	// GetOrCreateClaimantHostID). Stable across restarts of this same process/config dir;
	// distinct across different hosts and across different STAPLER_SQUAD_INSTANCE-namespaced
	// config dirs on the same machine, since each gets its own config.json. Unrelated to
	// STAPLER_SQUAD_INSTANCE (which only namespaces config/state directories on a single
	// machine) and unrelated to session/contexts.go's CloudContext.InstanceID (a cloud
	// provider's instance identifier, not populated for local/dev sessions).
	ClaimantHostID string `json:"claimant_host_id,omitempty"`
	// MaxAutoReworkIterations caps how many automated work sessions the backlog auto-reopen
	// loop will spawn for a single item before leaving it for manual review. 0 = use the
	// default (20). Individual items can also override this via
	// BacklogItemData.ReworkCapOverride (0 = unlimited for that item, >0 = that item's own
	// cap) — see effectiveReworkCap in server/services/backlog_service_triage.go.
	MaxAutoReworkIterations int `json:"max_auto_rework_iterations,omitempty"`
	// MaxConcurrentBacklogWorkItems caps how many distinct backlog items may be
	// "in_progress" at the same time. 0 = use the default (2). Values above
	// maxConcurrentBacklogWorkItemsHardCeiling are clamped to the ceiling.
	MaxConcurrentBacklogWorkItems int `json:"max_concurrent_backlog_work_items,omitempty"`
	// AutoSpawnReadyItems controls whether "ready" backlog items (post-triage, plan
	// approved or SkipPlanning) automatically claim a free WIP slot and spawn a work
	// session — in priority order (P1 first) — the moment one is free, without a
	// human clicking "Spawn Session". A *bool, not bool: the zero value of bool
	// can't represent "unset" the way 0 does for the int settings above, and this
	// setting's default is true (unlike SkipReviewGate/AutoCreatePR's per-item
	// false-by-default opt-ins), so nil must mean "use the default", not "disabled".
	// Pass explicit false to require manual spawning instead.
	AutoSpawnReadyItems *bool `json:"auto_spawn_ready_items,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"`
	// Quota holds configuration for the account-wide session-quota gate that
	// pauses/resumes backlog automation based on inferred quota headroom.
	Quota QuotaConfig `json:"quota,omitempty"`
	// TmuxExecGate bounds concurrent tmux subprocess execution across all processes.
	TmuxExecGate TmuxExecGateConfig `json:"tmux_exec_gate,omitempty"`
	// SessionRetention holds configuration for the automatic session-retention cleanup sweep.
	SessionRetention SessionRetentionConfig `json:"session_retention,omitempty"`
	// StaleSession holds configuration for stale-session detection (inactivity threshold
	// and notify-on-stale toggle).
	StaleSession StaleSessionConfig `json:"stale_session,omitempty"`
	// Callbacks holds the global singleton outbound-callback URLs (webhook-triggers
	// Phase 5, FR7) fired by CallbackDispatcher on session-complete/session-stale/
	// queue-item-created lifecycle events.
	Callbacks CallbackConfig `json:"callbacks,omitempty"`
	// Slack holds configuration for the Slack review-queue notification
	// feature. Secret fields are ciphertext only — see ADR-001.
	Slack SlackConfig `json:"slack,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"`
	// GitHubEnterpriseHosts registers GitHub Enterprise Server instances (beyond
	// github.com) with their own OAuth App client IDs, enabling device-flow login,
	// PR polling, and link detection against those hosts. Empty means github.com only.
	GitHubEnterpriseHosts []GitHubEnterpriseHost `json:"github_enterprise_hosts,omitempty"`

	// StreamHubSessionOverrides forces the terminal-multi-connection-streaming
	// project's PathHubOwned resolution for specific named tmux sessions,
	// regardless of the global STAPLER_SQUAD_USE_STREAM_HUB default — the
	// per-session canary mechanism (Story 3.3.1). Keys are tmux session
	// names; an absent key means "no override, use the global default".
	// Consulted via streamhub.SetSessionOverrideLookup, wired at process
	// startup in server/services so package session/streamhub never imports
	// package config directly.
	StreamHubSessionOverrides map[string]bool `json:"stream_hub_session_overrides,omitempty"`
	// RollbackRehearsalCompletedAt records when Story 3.3.2's rollback
	// rehearsal (flip STAPLER_SQUAD_USE_STREAM_HUB's per-session override on
	// for a disposable session, use it briefly, remove the override, confirm
	// a clean reconnect under the legacy path) was last completed
	// successfully. nil means "never completed". ResolveGlobalStreamHubDefault
	// refuses to let the *global* default resolve to true until this is set
	// (pre-mortem P1 #4's mechanical gate) — the per-session override above
	// is unaffected by this gate. Set via RecordRollbackRehearsalCompleted.
	RollbackRehearsalCompletedAt *time.Time `json:"rollback_rehearsal_completed_at,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 GitHubEnterpriseHost struct {
	// Host is the bare hostname (no scheme, no trailing slash), e.g. "github.example.com".
	Host string `json:"host"`
	// ClientID is the OAuth App client ID registered on that GHES instance.
	ClientID string `json:"client_id"`
}

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 LauncherPreset struct {
	ID          string   `json:"id"`
	Label       string   `json:"label"`
	Argv        []string `json:"argv"`
	Program     string   `json:"program,omitempty"`
	DefaultPath string   `json:"default_path,omitempty"`
}

type LauncherPresetsFile struct {
	Version int              `json:"version"`
	Presets []LauncherPreset `json:"presets"`
}

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 QuotaConfig struct {
	// Enabled gates the entire feature. When false, the gate is a no-op and
	// BacklogController's toggle behaves exactly as it does today. Default: false.
	Enabled bool `json:"enabled,omitempty"`
	// PauseBelowHeadroomPct is the soft/proactive threshold: backlog is paused
	// once estimated headroom drops below this percentage. Default: 20.0.
	PauseBelowHeadroomPct float64 `json:"pause_below_headroom_pct,omitempty"`
	// ResumeMarginPct is added to PauseBelowHeadroomPct to form the resume
	// threshold, avoiding flapping right at the pause line. Default: 15.0.
	ResumeMarginPct float64 `json:"resume_margin_pct,omitempty"`
	// ConsecutiveTicksToPause is how many consecutive below-threshold reconcile
	// ticks are required before the soft signal pauses backlog. Default: 2.
	ConsecutiveTicksToPause int `json:"consecutive_ticks_to_pause,omitempty"`
	// ConsecutiveTicksToResume is how many consecutive above-threshold reconcile
	// ticks are required before the soft signal resumes backlog. Default: 3.
	ConsecutiveTicksToResume int `json:"consecutive_ticks_to_resume,omitempty"`
	// AssumedWindowTokenBudget is the operator-supplied assumed token budget for
	// the trailing 5h window. Anthropic publishes no real budget, so this must be
	// calibrated manually; 0 (the default) disables the soft/percentage signal
	// entirely, leaving only the hard/reactive rate-limit override active.
	AssumedWindowTokenBudget int64 `json:"assumed_window_token_budget,omitempty"`
	// RateLimitWindowMinutes is how long a detected rate-limit event keeps the
	// hard/reactive override active. Default: 30.
	RateLimitWindowMinutes int `json:"rate_limit_window_minutes,omitempty"`
	// ManualOverrideGraceMinutes is how long after a detected manual override the
	// notification cooldown is bypassed for the next auto-transition. Default: 10.
	ManualOverrideGraceMinutes int `json:"manual_override_grace_minutes,omitempty"`
	// ForegroundThrottleDelaySeconds is how long the foreground-session dispatch
	// throttle stays active after the most recently observed foreground activity.
	// Default: 300.
	ForegroundThrottleDelaySeconds int `json:"foreground_throttle_delay_seconds,omitempty"`
}

type RemoteConfig struct {
	// Name is the unique, user-chosen identifier for this remote (e.g.
	// "prod-box"), referenced by session-creation flows. Not a hostname and
	// not required to resolve as one.
	Name string `json:"name"`
	// Host is the SSH-reachable hostname or address (e.g. "prod.example.com"
	// or "10.0.0.5"). Not a full "user@host" string — see User for the
	// login name — and not a URL (no scheme, no path, no port suffix; use a
	// standard SSH config Host block for non-default ports).
	Host string `json:"host"`
	// User is the SSH login username on the remote host. Not a local
	// username and not validated against the remote's actual user list at
	// save time.
	User string `json:"user"`
	// BasePath is the absolute filesystem path on the remote host under
	// which session worktrees/directories are created (e.g.
	// "/srv/workspaces"). Not a local path and not created automatically by
	// saving this config — it must already exist (or be creatable) on the
	// remote.
	BasePath string `json:"base_path"`
	// IdentityRef is an opaque, non-secret pointer to the SSH identity
	// (private key + optional passphrase) that authenticates to this
	// remote, resolved at connection time via sshremote.KeyStore against the
	// OS keychain. It is NOT a filesystem path to a key file, NOT the key's
	// raw bytes, and NOT the passphrase itself — no key material is ever
	// stored in config.json. An empty value means no identity has been
	// registered yet for this remote.
	IdentityRef string `json:"identity_ref"`
}

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 SessionRetentionConfig struct {
	// Enabled controls whether the retention sweep runs. A pointer so a config
	// saved before this field existed (nil) can be distinguished from an explicit
	// `false` — nil defaults to enabled, matching AutoSpawnReadyItems's pattern.
	Enabled *bool `json:"enabled,omitempty"`
	// RetentionDays is how many days after a session is archived before the sweep
	// is eligible to delete it (still subject to safety checks). Default: 14.
	RetentionDays int `json:"retention_days,omitempty"`
}

type SessionType string

type SlackConfig struct {
	// WebhookURLEncrypted is the AES-256-GCM-encrypted Slack Incoming Webhook
	// URL, or empty if not configured. Never store or log the plaintext value.
	WebhookURLEncrypted string `json:"webhook_url_encrypted,omitempty"`
	// SigningSecretEncrypted is the AES-256-GCM-encrypted Slack app signing
	// secret (Phase 2, used to verify interactive-button callbacks), or empty
	// if not configured. Never store or log the plaintext value.
	SigningSecretEncrypted string `json:"signing_secret_encrypted,omitempty"`
	// NotifyOnQueueItem controls whether a Slack message is sent when an item
	// enters the review queue. Default: false (opt-in).
	NotifyOnQueueItem bool `json:"notify_on_queue_item,omitempty"`
	// QueueDepthThreshold is the review-queue depth at which a digest
	// notification is sent (edge-triggered: one digest per burst). 0 disables
	// depth-based notifications.
	QueueDepthThreshold int `json:"queue_depth_threshold,omitempty"`
	// ApprovalEnabled controls whether outbound Slack messages include
	// interactive allow/deny buttons (Phase 2) and whether the interactive
	// callback route is registered. Default: false.
	ApprovalEnabled bool `json:"approval_enabled,omitempty"`
	// DashboardBaseURL is the base URL used to build "view in dashboard" links
	// in Slack messages. Empty string means links are omitted.
	DashboardBaseURL string `json:"dashboard_base_url,omitempty"`
}

type StaleSessionConfig struct {
	// ThresholdMinutes is how many minutes of inactivity before a session is
	// considered stale. Default: 30.
	ThresholdMinutes int `json:"threshold_minutes,omitempty"`
	// NotifyEnabled controls whether a notification is sent when a session goes
	// stale. A pointer so a config saved before this field existed (nil) can be
	// distinguished from an explicit `false` — nil defaults to enabled, matching
	// SessionRetentionConfig.Enabled's pattern.
	NotifyEnabled *bool `json:"notify_enabled,omitempty"`
}

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"`

	// ResyncFastLaneSlots is the number of concurrent tmux subprocess execution
	// slots reserved for terminal-resync traffic when the
	// "terminal:resync-exec-gate-fast-lane" feature flag is on, so resync calls
	// don't contend with other tmux exec traffic for the shared Slots pool.
	// Zero or unset means "use the default" — see ResyncFastLaneSlotsOrDefault.
	// Default: 4.
	ResyncFastLaneSlots int `json:"resyncFastLaneSlots"`

	// InputFastLaneSlots is the number of concurrent tmux subprocess execution
	// slots reserved for keystroke input traffic (the legacy per-keystroke
	// send-keys path used when STAPLER_SQUAD_USE_CONTROL_MODE=false), so a
	// poller flooding the shared Slots pool with capture-pane calls never
	// makes user keystrokes queue behind it. Zero or unset means "use the
	// default" — see InputFastLaneSlotsOrDefault. Default: 4.
	InputFastLaneSlots int `json:"inputFastLaneSlots"`
}

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"`
}