config

type ActionConfig struct {
	Type string `toml:"type"` // command | session | scenario | message | tracker

	// command:
	Command  string `toml:"command"`
	Repo     string `toml:"repo"`     // required for schedule commands; rejected for watch
	Timeout  string `toml:"timeout"`  // max run time; default 5m
	Mutating bool   `toml:"mutating"` // may write its execution root; rejected in v1
	Sandbox  *bool  `toml:"sandbox"`  // nil => default true; false runs unconfined
	// SandboxConfig is extra sandbox grants merged onto the base command profile,
	// mirroring the MCP-server pattern (MCPServerConfig.SandboxConfig).
	SandboxConfig *SandboxConfig `toml:"sandbox_config"`

	// session:
	Prompt string `toml:"prompt"`
	Agent  string `toml:"agent"`
	Model  string `toml:"model"`
	Ensure bool   `toml:"ensure"` // idempotent ensure-reviewer (watch source only)
	// AutoCleanup soft-deletes a trigger-spawned session once it stops, so a
	// finished briefing/report session doesn't clutter `gr list`. It is a union
	// of bool and string: absent/false/"" disables it; true (or "always")
	// deletes on any stop; "on_success" deletes only on a clean (exit 0) stop.
	// Decoded as any so TOML can supply either a bool or the string enum; use
	// AutoCleanupMode to normalise. Session action only.
	AutoCleanup any `toml:"auto_cleanup"`
	// IdleTimeout auto-stops the spawned session after it sits idle (agent at
	// rest, no attached client) this long, overriding the agent default. A Go
	// duration ("1m", "5m"). Session action only. When unset, an
	// auto_cleanup="always" session defaults to a short idle window so a finished
	// briefing reaps itself promptly (finish -> idle-stop -> soft-delete); see
	// SessionIdleTimeout.
	IdleTimeout string `toml:"idle_timeout"`

	// scenario:
	Scenario string `toml:"scenario"`

	// tracker: keep live sessions in sync with an issue tracker. On each
	// scheduled fire the daemon polls the tracker for active issues and
	// reconciles sessions against them — spawning one per active issue (seeded
	// with the templated Prompt above) and reaping the session when its issue
	// leaves the active state. Schedule source only. See TrackerConfig and
	// docs/design/2026-07-16-tracker-poll-action.md.
	Tracker *TrackerConfig `toml:"tracker"`

	// message:
	Body string `toml:"body"`

	// notify (any action type): when NotifyOnComplete is set, the daemon fires a
	// proactive push notification (see [notifications]) once the action finishes
	// firing. NotifyMessage is the body (templated with the trigger vars;
	// defaults to a generic "<name> completed"); NotifyPriority is low/normal/high
	// (defaults to normal, or high when the action errored).
	NotifyOnComplete bool   `toml:"notify_on_complete"`
	NotifyMessage    string `toml:"notify_message"`
	NotifyPriority   string `toml:"notify_priority"`

	Deliver DeliverConfig `toml:"deliver"`
}

type Agent struct {
	Command      string            `json:"command"                 toml:"command"`
	Args         []string          `json:"args,omitempty"          toml:"args"`
	ResumeArgs   []string          `json:"resume_args,omitempty"   toml:"resume_args"`
	ForkArgs     []string          `json:"fork_args,omitempty"     toml:"fork_args"`
	Env          map[string]string `json:"env,omitempty"           toml:"env"`
	IdleTimeout  string            `json:"idle_timeout,omitempty"  toml:"idle_timeout"`
	InjectPrompt *bool             `json:"inject_prompt,omitempty" toml:"inject_prompt"`
	// PromptInjection selects HOW graith delivers its operating prompt to this
	// agent (append_system_prompt / cursor_rules / developer_instructions /
	// none). It is distinct from InjectPrompt, which is the on/off switch. An
	// empty value falls back to name-based detection so the built-in claude,
	// cursor, and codex agents work without explicit config; a custom agent
	// must set this to receive a prompt at all. Validated in Config.Validate.
	// See issue #1232.
	PromptInjection   string                     `json:"prompt_injection,omitempty"    toml:"prompt_injection"`
	PreTrustWorkspace *bool                      `json:"pre_trust_workspace,omitempty" toml:"pre_trust_workspace"`
	Sandbox           SandboxConfig              `json:"sandbox"                       toml:"sandbox"`
	MCPServers        map[string]MCPServerConfig `json:"mcp_servers,omitempty"         toml:"mcp_servers"`
	ValidateModel     string                     `json:"validate_model,omitempty"      toml:"validate_model"`
	// InterruptCount is how many times the interrupt byte (Ctrl-C, 0x03) is sent
	// to interrupt this agent, and InterruptDelayMs is the pause in milliseconds
	// between successive sends. Some agent TUIs ignore a single Ctrl-C and need
	// two rapid presses to actually interrupt (Claude's TUI wants ~200ms apart),
	// so both are configurable per agent. Unset means the built-in defaults
	// (count 1, delay 0). See issue #620.
	InterruptCount   *int `json:"interrupt_count,omitempty"    toml:"interrupt_count"`
	InterruptDelayMs *int `json:"interrupt_delay_ms,omitempty" toml:"interrupt_delay_ms"`
	// HeadlessCapable marks an agent as supporting headless stream-json mode
	// (issue #1075). Unset means not capable — only agents explicitly flagged
	// (Claude Code in v1) may run headless, so a --headless request against an
	// unsupported agent fails closed rather than silently downgrading.
	HeadlessCapable *bool `json:"headless_capable,omitempty" toml:"headless_capable"`
	// AddDirArgs is the flag template graith uses to grant the agent access to an
	// additional directory — each included repo's co-located worktree. It is
	// expanded once per directory with {dir} bound to that path (see
	// AddDirArgsFor). An empty AddDirArgs means the agent's CLI has no such flag,
	// so its included worktrees are exposed only via the GRAITH_INCLUDE_*_PATH env
	// vars; this replaces the former hard-coded agentSupportsAddDir allowlist so a
	// custom agent can opt in from config alone (issue #1236). Built-in
	// claude/codex/cursor set ["--add-dir", "{dir}"].
	AddDirArgs []string `json:"add_dir_args,omitempty" toml:"add_dir_args"`
	// HeadlessArgs is the argv prefix graith prepends when launching this agent in
	// headless stream-json mode (issue #1075); the agent's own template-expanded
	// args follow it. Only consulted for a headless session. Moving it here (from
	// the former hard-coded headlessArgs) lets a custom headless_capable agent
	// define its own control-channel flags (issue #1236). Built-in claude sets the
	// `-p --output-format stream-json …` flags.
	HeadlessArgs []string `json:"headless_args,omitempty" toml:"headless_args"`
	// OptionArgs are conditional argv groups appended after the base args on every
	// launch (create/resume/fork). Each group's Args are template-expanded and
	// appended only when its When template variable resolves non-empty, so an
	// unset option leaves the agent's own default untouched — e.g. codex's
	// ["--model", "{model}"] gated on `when = "model"`. This moves the formerly
	// hard-coded codex adapter (model / profile / reasoning-effort / service-tier
	// / search / approval flags) into config so custom agents can define their own
	// conditional flags (issue #1236).
	OptionArgs []AgentOptionArg `json:"option_args,omitempty" toml:"option_args"`
}

type AgentOptionArg struct {
	// When names the template variable that gates this group: the args are
	// emitted only when the variable resolves to a non-empty value ("true" for a
	// boolean such as web_search). An empty When emits the group unconditionally.
	When string `json:"when,omitempty" toml:"when"`
	// Args are the argv templates emitted when the gate passes. They are expanded
	// with the same TemplateVars as the base args plus the option variables.
	Args []string `json:"args" toml:"args"`
}

type Approvals struct {
	// Enabled controls whether the PreToolUse approve-request gating hook is
	// installed. nil (unset) means disabled: the status/lifecycle hooks are
	// still installed but the approval gate is not, because unattended agents
	// otherwise see their own tool calls as human-rejected and the OS sandbox
	// is the intended guardrail. Set to true to opt back into human approval
	// gating.
	Enabled *bool `toml:"enabled"`
	// Backend selects who makes the automated decision: "" (none — always
	// prompt the human), "command"/"external" (delegate to a command over
	// graith's JSON contract), "localmost" (the real localmost binary over its
	// native protocol), or "builtin" (graith's built-in localmost-compatible
	// engine). It is the canonical selector; Mode is the deprecated predecessor.
	Backend string           `toml:"backend"`
	Mode    string           `toml:"mode"`
	AutoPop bool             `toml:"auto_pop"`
	Timeout string           `toml:"timeout"`
	Command string           `toml:"command"`
	Builtin ApprovalsBuiltin `toml:"builtin"`

	// CommandTimeout bounds a single external "command"/"external" backend
	// invocation; LocalmostTimeout bounds a single "localmost" binary check.
	// Both default to defaultBackendExecTimeout (5s) when unset (see
	// CommandTimeoutDuration/LocalmostTimeoutDuration). Each must be positive,
	// no larger than maxBackendExecTimeout, and strictly shorter than the
	// enclosing human/headless approval Timeout so a hung backend cannot outlive
	// the deadline that encloses it — a class of bug that previously caused
	// approval-behaviour glitches (see #244). Validate enforces this hierarchy.
	CommandTimeout   string `toml:"command_timeout"`
	LocalmostTimeout string `toml:"localmost_timeout"`
}

type ApprovalsBuiltin struct {
	// Config is the path to a localmost-format config.json (allow/deny rules).
	Config string `toml:"config"`

	// Allow and Deny are the inline allow/deny rulesets. Each element is either
	// a bare rule string ("@arg @*") or a table with per-rule keys
	// (rule/unless/redirect/pipe). They are decoded as []any so both TOML forms
	// — an array of strings and an array of tables ([[approvals.builtin.allow]])
	// — are accepted, then converted to the localmost schema (see InlineJSON).
	Allow []any `toml:"allow"`
	Deny  []any `toml:"deny"`

	// AllowSafeXargs and AskNoninteractive mirror the localmost top-level flags.
	// nil means unset (the engine's default of true applies).
	AllowSafeXargs    *bool `toml:"allowSafeXargs"`
	AskNoninteractive *bool `toml:"askNoninteractive"`
}

type CodexOptions struct {
	Profile         string `json:"profile,omitempty"`
	ReasoningEffort string `json:"reasoning_effort,omitempty"`
	ServiceTier     string `json:"service_tier,omitempty"`
	WebSearch       bool   `json:"web_search,omitempty"`
	ApprovalPolicy  string `json:"approval_policy,omitempty"`
}

type CompletionConfig struct {
	Event   string `toml:"event"`
	Session string `toml:"session"`
}

type Config struct {
	DefaultAgent     string             `toml:"default_agent"`
	GitHubUsername   string             `toml:"github_username"`
	BranchPrefix     string             `toml:"branch_prefix"`
	DataDir          string             `toml:"data_dir"`
	FetchOnCreate    bool               `toml:"fetch_on_create"`
	AgentPrompt      string             `toml:"agent_prompt"`
	AllowedRepoPaths []string           `toml:"allowed_repo_paths"`
	Repos            []RepoConfig       `toml:"repos"`
	StatusBar        StatusBar          `toml:"status_bar"`
	Keybindings      Keybindings        `toml:"keybindings"`
	Notifications    Notifications      `toml:"notifications"`
	Messages         Messages           `toml:"messages"`
	Delete           Delete             `toml:"delete"`
	GC               GCConfig           `toml:"gc"`
	Todo             TodoConfig         `toml:"todo"`
	Sandbox          SandboxConfig      `toml:"sandbox"`
	Approvals        Approvals          `toml:"approvals"`
	Status           StatusConfig       `toml:"status"`
	GitPull          GitPullConfig      `toml:"git_pull"`
	Launch           LaunchConfig       `toml:"launch"`
	PRWatch          PRWatchConfig      `toml:"pr_watch"`
	MCPServers       []MCPServerConfig  `toml:"mcp_servers"`
	Overlay          Overlay            `toml:"overlay"`
	Orchestrator     OrchestratorConfig `toml:"orchestrator"`
	Remote           RemoteConfig       `toml:"remote"`
	Input            InputConfig        `toml:"input"`
	Agents           map[string]Agent   `toml:"agents"`
	Triggers         []TriggerConfig    `toml:"trigger"`          // [[trigger]] array
	TriggersRuntime  TriggersRuntime    `toml:"triggers"`         // [triggers] table (daemon-wide settings)
	Headless         HeadlessConfig     `toml:"headless"`         // [headless] table (issue #1075)
	Updates          UpdatesConfig      `toml:"updates"`          // [updates] table (issue #1253)
	Detection        DetectionConfig    `toml:"detection"`        // [detection] table (issue #1241)
	ConfigReload     ConfigReload       `toml:"config"`           // [config] table (issue #1237)
	Tools            ToolsConfig        `toml:"tools"`            // [tools] table (issue #1238)
	Git              GitConfig          `toml:"git"`              // [git] table (issue #1238)
	Connection       ConnectionConfig   `toml:"connection"`       // [connection] table (issue #1242)
	TokenAccounting  TokenAccounting    `toml:"token_accounting"` // [token_accounting] table (issue #1244)
	ResourceMonitor  ResourceMonitor    `toml:"resource_monitor"` // [resource_monitor] table (issue #1244)
	Migration        MigrationConfig    `toml:"migration"`        // [migration] table (issue #1250)
	Transcript       TranscriptConfig   `toml:"transcript"`       // [transcript] table (issue #1250)
	Limits           LimitsConfig       `toml:"limits"`           // [limits] table (issue #1252)
	Lifecycle        LifecycleConfig    `toml:"lifecycle"`        // [lifecycle] table (issue #1243)
	Terminal         TerminalConfig     `toml:"terminal"`         // [terminal] table (issue #1254)

	// Warnings collects non-fatal configuration problems detected at load time
	// (e.g. conflicting keybindings). They are surfaced to the user but do not
	// prevent startup. Not serialised. See issue #1233.
	Warnings []string `toml:"-"`

	// SourceDir is the absolute directory containing the config.toml this Config
	// was loaded from. It anchors relative paths in the config (currently the
	// [tools] executable overrides) so they mean the same file regardless of the
	// process working directory or a later exec.Cmd.Dir. Empty for an in-memory
	// Default() with no source file. Not serialised. See issue #1293.
	SourceDir string `toml:"-"`
}

type ConfigReload struct {
	// ReloadDebounce is the quiet period the file watcher waits after the last
	// write before reloading. Empty, unparseable, or non-positive uses the
	// default (ConfigReloadDebounceDefault).
	ReloadDebounce string `toml:"reload_debounce"`
}

type ConnectionConfig struct {
	// DialTimeout bounds a single Unix-socket dial to the local daemon
	// (default "500ms").
	DialTimeout string `toml:"dial_timeout"`
	// HandshakeTimeout bounds the local-daemon handshake exchange, so a stale
	// or wedged socket can't hang a command forever (default "5s").
	HandshakeTimeout string `toml:"handshake_timeout"`
	// StartTimeout is the aggregate bound while EnsureDaemon waits for a freshly
	// spawned daemon to begin answering handshakes (default "5s"). Individual
	// dial/handshake policies are capped at the time remaining.
	StartTimeout string `toml:"start_timeout"`
	// StartPollInterval is how often EnsureDaemon re-probes the socket while
	// waiting for a spawned daemon to come up (default "50ms").
	StartPollInterval string `toml:"start_poll_interval"`
	// ReconnectTimeout bounds the attach disconnect-recovery retry before the
	// client gives up reattaching (default "10s").
	ReconnectTimeout string `toml:"reconnect_timeout"`
	// ReconnectInterval is how often the attach recovery loop re-probes the
	// daemon while reconnecting (default "250ms").
	ReconnectInterval string `toml:"reconnect_interval"`
	// RemoteDialTimeout bounds the TCP dial to a paired remote daemon
	// (default "10s").
	RemoteDialTimeout string `toml:"remote_dial_timeout"`
	// RemoteHandshakeTimeout bounds the remote handshake plus
	// proof-of-possession exchange (default "15s").
	RemoteHandshakeTimeout string `toml:"remote_handshake_timeout"`
	// RemotePairingTimeout bounds how long the CLI waits for the remote human to
	// approve `gr pair`, and should sit just past the daemon's pending-pairing
	// TTL (default "11m").
	RemotePairingTimeout string `toml:"remote_pairing_timeout"`
}

type Delete struct {
	Retention         string `toml:"retention"`
	PurgeStartupDelay string `toml:"purge_startup_delay"`
	PurgeInterval     string `toml:"purge_interval"`
}

type DeliverConfig struct {
	Inbox    string `toml:"inbox"`    // session name, "orchestrator", or a template like "{session_name}"
	Topic    string `toml:"topic"`    // pub/sub topic
	Store    string `toml:"store"`    // store key (prefix "shared:" for the shared store)
	Wake     bool   `toml:"wake"`     // resume a non-orchestrator stopped inbox target
	Required bool   `toml:"required"` // delivery failure fails a completion action and gates on_success cleanup
}

type DetectionConfig struct {
	// ScanInterval is how often the detection loop scans PTY scrollback to
	// classify low-risk agent status (active/ready). Empty uses the default
	// (DetectionScanIntervalDefault).
	ScanInterval string `toml:"scan_interval"`
	// FetchInterval is how often the detection loop refreshes remote tracking
	// refs (`git fetch`) so the diverged-from-base count stays fresh. Empty uses
	// the default (DetectionFetchIntervalDefault).
	FetchInterval string `toml:"fetch_interval"`
	// FetchTimeout bounds a single per-repo `git fetch` so a slow or hung remote
	// can't stall the fetch pass for other sessions. Empty uses the default
	// (DetectionFetchTimeoutDefault).
	FetchTimeout string `toml:"fetch_timeout"`
	// SilentThreshold is how long a running session's PTY may produce zero
	// output before the daemon warns it is silent (issue #1087). Empty uses the
	// default (DetectionSilentThresholdDefault).
	SilentThreshold string `toml:"silent_threshold"`
	// AdoptedGrace is the window after daemon-upgrade PTY adoption during which
	// an unknown detection result falls back to the previous status instead of
	// clobbering it. Empty uses the default (DetectionAdoptedGraceDefault).
	AdoptedGrace string `toml:"adopted_grace"`
	// RecentOutputWindow is the age below which recent PTY output alone implies
	// the agent is active when pattern matching is inconclusive. Empty uses the
	// default (DetectionRecentOutputWindowDefault).
	RecentOutputWindow string `toml:"recent_output_window"`
	// HookStartWindow is how long a SessionStart hook report stays authoritative
	// over PTY scraping. Empty uses the default (DetectionHookStartWindowDefault).
	HookStartWindow string `toml:"hook_start_window"`
	// HookActivityWindow is how long a tool-use hook report (UserPromptSubmit,
	// PreToolUse, PostToolUse) stays authoritative. Empty uses the default
	// (DetectionHookActivityWindowDefault).
	HookActivityWindow string `toml:"hook_activity_window"`
	// HookTerminalWindow is how long a terminal hook report (ready/approval:
	// Stop, idle_prompt, permission_prompt, PermissionRequest) stays
	// authoritative. Empty uses the default (DetectionHookTerminalWindowDefault).
	HookTerminalWindow string `toml:"hook_terminal_window"`
}

type GCConfig struct {
	OrphanMinAge string `toml:"orphan_min_age"`
}

type GCXConfig struct {
	Event          string   `toml:"event"`           // oncall_alert_group (v1; default)
	Context        string   `toml:"context"`         // gcx context (required; credentials remain owned by gcx)
	Every          string   `toml:"every"`           // poll cadence; default 1m
	Timeout        string   `toml:"timeout"`         // timeout for each gcx invocation; default 30s
	OnCallUserID   string   `toml:"oncall_user_id"`  // stable human user PK; paired with ScheduleIDs
	ScheduleIDs    []string `toml:"schedule_ids"`    // schedules used for the current-on-call gate
	TeamIDs        []string `toml:"team_ids"`        // optional alert-group team filters
	IntegrationIDs []string `toml:"integration_ids"` // optional alert-group integration filters
	States         []string `toml:"states"`          // firing|acknowledged|resolved|silenced; default firing
	MaxAge         string   `toml:"max_age"`         // alert lookback and seen-ID retention; default 24h
	Limit          int      `toml:"limit"`           // result cap; reaching it fails closed; default 100
}

type GitConfig struct {
	// FetchTimeout bounds a single `git fetch` (default "2m").
	FetchTimeout string `toml:"fetch_timeout"`
	// MergeTimeout bounds a single fast-forward merge in the git-pull loop
	// (default "2m").
	MergeTimeout string `toml:"merge_timeout"`
	// UsernameTimeout bounds GitHub-username discovery, which may invoke `gh`
	// (default "15s").
	UsernameTimeout string `toml:"username_timeout"`
}

type GitPullConfig struct {
	Enabled  bool   `toml:"enabled"`
	Interval string `toml:"interval"`
}

type HeadlessConfig struct {
	Experimental bool `toml:"experimental"`
	Default      bool `toml:"default"`
	// MaxLineBytes bounds a single stream-json line read from the agent's stdout.
	// Large tool outputs or base64 images exceed the 64KiB default scanner token,
	// so the driver raises the cap. 0/negative uses HeadlessMaxLineBytesDefault.
	MaxLineBytes int `toml:"max_line_bytes"`
	// ControlTimeout bounds how long a synchronous control request waits for its
	// matching control_response before failing. Empty/unparseable/non-positive
	// uses HeadlessControlTimeoutDefault.
	ControlTimeout string `toml:"control_timeout"`
	// InterruptTimeout bounds the interrupt control round-trip; it is much shorter
	// than ControlTimeout because a caller interrupting an agent wants a prompt
	// fall-through to SIGINT. Empty/unparseable/non-positive uses
	// HeadlessInterruptTimeoutDefault.
	InterruptTimeout string `toml:"interrupt_timeout"`
	// PreviewBytes bounds how much scrollback tail the overlay preview and
	// screen_preview control message render. 0/negative uses
	// HeadlessPreviewBytesDefault.
	PreviewBytes int `toml:"preview_bytes"`
}

type InputConfig struct {
	// DragArrowKeys enables touch/hold-and-drag arrow keys:
	// press-and-hold the left mouse button then drag to emit discrete arrow-key
	// presses to the focused pane. Off by default because it repurposes
	// left-drag (which terminals otherwise use for text selection). Mouse-wheel
	// scrolling is always passed through unchanged.
	DragArrowKeys bool `toml:"drag_arrow_keys"`
	// DragArrowThreshold is the number of cells of drag movement that produces
	// one arrow-key press. Values below 1 fall back to the default.
	DragArrowThreshold int `toml:"drag_arrow_threshold"`
}

type Keybindings struct {
	Prefix              string `toml:"prefix"`
	NewSession          string `toml:"new_session"`
	ForkSession         string `toml:"fork_session"`
	DeleteSession       string `toml:"delete_session"`
	Detach              string `toml:"detach"`
	SessionList         string `toml:"session_list"`
	NextSession         string `toml:"next_session"`
	PrevSession         string `toml:"prev_session"`
	LastSession         string `toml:"last_session"`
	ResumeSession       string `toml:"resume_session"`
	RenameSession       string `toml:"rename_session"`
	Search              string `toml:"search"`
	ScrollMode          string `toml:"scroll_mode"`
	Shell               string `toml:"shell"`
	OrchestratorSession string `toml:"orchestrator_session"`
	// Prefix-action commands issued from an attached session (prefix key then
	// one of these). Previously hard-coded as m/a/r (issue #1233).
	Messages       string `toml:"messages"`
	Approvals      string `toml:"approvals"`
	RestartSession string `toml:"restart_session"`
	// Overlay holds the keys used inside the full-screen terminal overlays
	// (dashboard, approval prompt, message viewer, scroll pager). See #1233.
	Overlay OverlayKeybindings `toml:"overlay"`
}

type LaunchConfig struct {
	// MaxConcurrent bounds how many agent spawns may be in their startup window
	// at once. Values < 1 fall back to the default (LaunchMaxConcurrentDefault).
	MaxConcurrent int `toml:"max_concurrent"`
	// StartupTimeout is how long a session may stay running with no output before
	// the startup watchdog kills and restarts it fresh. "0" disables the
	// watchdog; empty uses the default (LaunchStartupTimeoutDefault).
	StartupTimeout string `toml:"startup_timeout"`
	// SettleTimeout caps how long a launch holds its throttle slot waiting for
	// the session's first output before releasing it anyway. Empty uses the
	// default (LaunchSettleTimeoutDefault); "0" releases immediately after spawn.
	SettleTimeout string `toml:"settle_timeout"`
	// MaxRestarts caps how many consecutive startup-watchdog restarts a single
	// session may receive before it is marked errored instead of restarted again,
	// preventing a restart storm for a fundamentally-broken session (#1092). The
	// counter resets once the session produces output. Values < 1 fall back to the
	// default (LaunchMaxRestartsDefault). To turn the watchdog off entirely, set
	// startup_timeout to "0" rather than dropping this to zero.
	MaxRestarts int `toml:"max_restarts"`
	// WatchdogInterval is how often the startup watchdog scans for stuck sessions.
	// Empty, unparseable, or non-positive uses the default
	// (LaunchWatchdogIntervalDefault); a zero cadence would busy-loop. Read once
	// when the watchdog loop starts, so a change takes effect on the next daemon
	// (re)start.
	WatchdogInterval string `toml:"watchdog_interval"`
	// SlotPollInterval is how often a held throttle slot polls a freshly-spawned
	// session for its first output before releasing. Empty, unparseable, or
	// non-positive uses the default (LaunchSlotPollIntervalDefault); a zero cadence
	// would busy-loop.
	SlotPollInterval string `toml:"slot_poll_interval"`
}

type LifecycleConfig struct {
	// ConvertSettleTimeout bounds how long ConvertToInteractive waits for an
	// interrupted headless process to settle and exit before escalating to
	// SIGTERM. Empty or non-positive uses the default (ConvertSettleTimeoutDefault).
	ConvertSettleTimeout string `toml:"convert_settle_timeout"`
	// ConvertKillTimeout bounds the SIGTERM step before the final SIGKILL. Empty
	// or non-positive uses the default (ConvertKillTimeoutDefault).
	ConvertKillTimeout string `toml:"convert_kill_timeout"`
	// ConvertForceKillTimeout bounds the final wait after SIGKILL so a process
	// whose Done() never closes can't stall the convert forever. Empty or
	// non-positive uses the default (ConvertForceKillTimeoutDefault).
	ConvertForceKillTimeout string `toml:"convert_force_kill_timeout"`
	// MassExitWindow is the rolling window over which many near-simultaneous
	// session exits are counted as a likely external signal (OOM killer/jetsam).
	// Empty or non-positive uses the default (MassExitWindowDefault).
	MassExitWindow string `toml:"mass_exit_window"`
	// MassExitThreshold is how many exits within MassExitWindow trigger the
	// mass-exit warning. Values < 1 fall back to the default (MassExitThresholdDefault).
	MassExitThreshold int `toml:"mass_exit_threshold"`
	// ProcessKillGrace is how long killProcessGroup waits after SIGTERM before
	// sending SIGKILL to a session's process group. Empty or non-positive uses the
	// default (ProcessKillGraceDefault).
	ProcessKillGrace string `toml:"process_kill_grace"`
	// AdoptedTimeout is the safety deadline the adopted-PTY babysit loop applies
	// when it cannot verify process identity by start time. Empty or non-positive
	// uses the default (AdoptedTimeoutDefault). Applies to sessions adopted after
	// the change (daemon upgrade).
	AdoptedTimeout string `toml:"adopted_timeout"`
	// AdoptedPollInterval is how often the adopted-PTY babysit loop polls for
	// process exit. Empty or non-positive uses the default
	// (AdoptedPollIntervalDefault); a zero cadence would busy-loop.
	AdoptedPollInterval string `toml:"adopted_poll_interval"`
	// ScrollbackHydrationBytes is how many bytes of the scrollback tail are
	// replayed into an adopted session's virtual screen at adopt time. Values < 0
	// fall back to the default (ScrollbackHydrationBytesDefault); "0" disables
	// hydration.
	ScrollbackHydrationBytes int `toml:"scrollback_hydration_bytes"`
	// InputDelay is the pause between writing text and the submit carriage return
	// in WriteInputAndSubmit, so a TUI doesn't treat text+CR as a paste. Empty,
	// unparseable, or non-positive uses the default (InputDelayDefault) — a zero
	// pause would defeat the paste guard. Applies to sessions launched after the
	// change.
	InputDelay string `toml:"input_delay"`
	// DefaultCols / DefaultRows are the terminal geometry used by daemon launch
	// paths (watchdog restart, orchestrator, scenarios, triggers, adoption) when
	// no client geometry is available. Values < 1 fall back to the defaults
	// (DefaultColsDefault / DefaultRowsDefault). Applies to sessions launched
	// after the change; an attaching client resizes to its real geometry.
	DefaultCols int `toml:"default_cols"`
	DefaultRows int `toml:"default_rows"`
	// MaxLogBytes caps the per-session scrollback log file. Values < 0 fall back
	// to the default (MaxLogBytesDefault); "0" means unlimited. Applies to sessions
	// launched (or adopted) after the change.
	MaxLogBytes int64 `toml:"max_log_bytes"`
}

type LimitsConfig struct {
	// LogLines is the default number of trailing output lines shown when a
	// `lines`/`-n` count is not given: `gr logs`, `gr mcp logs`, the scrollback
	// replayed to a client on attach, and the MCP log reader all share it. Values
	// < 1 fall back to the default (LimitsLogLinesDefault).
	LogLines int `toml:"log_lines"`
	// WaitScanLines bounds how much existing scrollback `gr wait --contains`
	// scans for an already-present match before it starts following live output.
	// Values < 1 fall back to the default (LimitsWaitScanLinesDefault).
	WaitScanLines int `toml:"wait_scan_lines"`
	// WaitBufferBytes bounds the retained partial line in the live `gr wait`
	// matcher so a long stream without a newline can't grow the buffer without
	// limit. Values < 1 fall back to the default (LimitsWaitBufferBytesDefault).
	WaitBufferBytes int `toml:"wait_buffer_bytes"`
	// MCPLogReadBytes bounds how many trailing bytes of an MCP server log file
	// are read before splitting into lines, keeping a huge log from being loaded
	// whole. Values < 1 fall back to the default (LimitsMCPLogReadBytesDefault).
	MCPLogReadBytes int `toml:"mcp_log_read_bytes"`
	// ApprovalDisplayBytes caps the tool input shown in the approval overlay and
	// broadcast to attached clients (the full input is still what backends
	// evaluate). Values < 1 fall back to the default
	// (LimitsApprovalDisplayBytesDefault).
	ApprovalDisplayBytes int `toml:"approval_display_bytes"`
	// LastMessageRunes bounds the agent's final Stop message the status hook
	// forwards to the daemon, so a large final output never becomes an unbounded
	// control frame. Counted in runes (never splits a multi-byte character).
	// Values < 1 fall back to the default (LimitsLastMessageRunesDefault).
	LastMessageRunes int `toml:"last_message_runes"`
	// InboxPreviewBytes bounds the unread-inbox preview injected into a session's
	// SessionStart hook context. Values < 1 fall back to the default
	// (LimitsInboxPreviewBytesDefault).
	InboxPreviewBytes int `toml:"inbox_preview_bytes"`
}

type MCPServerConfig struct {
	Name          string            `json:"-"              toml:"name"`
	Command       string            `json:"command"        toml:"command"`
	Args          []string          `json:"args,omitempty" toml:"args,omitempty"`
	Env           map[string]string `json:"env,omitempty"  toml:"env,omitempty"`
	Disabled      bool              `json:"-"              toml:"disabled,omitempty"`
	Sandbox       *bool             `json:"-"              toml:"sandbox,omitempty"`
	SandboxConfig *SandboxConfig    `json:"-"              toml:"sandbox_config,omitempty"`
}

type Messages struct {
	// MaxAge is the message-retention window: messages older than this are swept
	// by the cleanup loop. An empty value or an explicit "0" is the documented
	// "retain forever" sentinel (no age-based cleanup). A non-empty value is
	// validated at load: an unparseable or negative duration is rejected so a typo
	// cannot silently turn a bounded-retention deployment into keep-forever
	// (issue #1321). Reloadable.
	MaxAge       string `toml:"max_age"`
	MaxPerStream int    `toml:"max_per_stream"`
	// ConversationPageSize is the page size applied when a msg_conversation
	// request supplies a non-positive limit. Values < 1 fall back to the default
	// (MessagesConversationPageSizeDefault). Reloadable.
	ConversationPageSize int `toml:"conversation_page_size"`
	// ConversationMaxLimit is the hard cap on how many messages a single
	// msg_conversation request may sort, bounding a local perf/DoS footgun. Values
	// < 1 fall back to the default (MessagesConversationMaxLimitDefault); a value
	// above MessagesConversationMaxLimitCeiling is rejected at load. Reloadable.
	ConversationMaxLimit int `toml:"conversation_max_limit"`
	// JailListLimit caps how many quarantined comments a jail listing returns
	// (newest first), so the query can't force an unbounded allocation. Values < 1
	// fall back to the default (MessagesJailListLimitDefault); a value above
	// MessagesJailListLimitCeiling is rejected at load. Reloadable.
	JailListLimit int `toml:"jail_list_limit"`
	// SubscriberBuffer is the per-subscriber pub/sub channel capacity. A slow
	// reader that fills its buffer drops further messages until it drains (the
	// stored log stays authoritative), so this is a load-tuning knob for
	// installations with bursty fan-out. Values < 1 fall back to the default
	// (MessagesSubscriberBufferDefault); a value above
	// MessagesSubscriberBufferCeiling is rejected at load. Restart-only.
	SubscriberBuffer int `toml:"subscriber_buffer"`
	// BusyTimeout is the SQLite busy_timeout for the messages database — how long
	// a contended operation waits for the lock before erroring. It is graith's
	// database operation deadline. Empty/unset uses the default
	// (MessagesBusyTimeoutDefault, 5s). An explicit value must parse and fall in
	// [SQLiteBusyTimeoutResolution, MessagesBusyTimeoutCeiling] (1ms–5m):
	// SQLite's busy_timeout has millisecond resolution, so a positive sub-1ms
	// value would collapse to busy_timeout(0) and disable lock waiting, and it —
	// along with any unparseable, non-positive, or above-ceiling value — is
	// rejected at load. Restart-only.
	BusyTimeout string `toml:"busy_timeout"`
}

type MigrationConfig struct {
	// HealthWindow is how long Migrate waits to confirm the target agent survived
	// startup before declaring the migration successful. Empty/unparseable/
	// non-positive uses MigrationHealthWindowDefault.
	HealthWindow string `toml:"health_window"`
}

type NotificationTiming struct {
	// CoalesceWindow is how long an identical (title+message+priority) push
	// notification is dropped as a duplicate, coalescing rapid-fire events. Empty
	// uses the default (NotifyCoalesceWindowDefault); "0" disables coalescing.
	CoalesceWindow string `toml:"coalesce_window"`
	// DispatchTimeout bounds a single backend dispatch (osascript / notifier app /
	// command) so a hung helper can't block the caller. Empty or non-positive uses
	// the default (NotifyDispatchTimeoutDefault).
	DispatchTimeout string `toml:"dispatch_timeout"`
	// InboxIdleTimeout is how long an attached session's PTY must be free of user
	// input before an inbox notification or `gr type` input is injected, so it
	// doesn't land mid-type. Empty or non-positive uses the default
	// (NotifyInboxIdleTimeoutDefault).
	InboxIdleTimeout string `toml:"inbox_idle_timeout"`
	// InboxMaxWait caps the total wait for user idle before an inbox notification
	// or `gr type` input is injected regardless. Empty or non-positive uses the
	// default (NotifyInboxMaxWaitDefault).
	InboxMaxWait string `toml:"inbox_max_wait"`
	// InboxCooldown is the minimum interval between unread-inbox notifications to
	// one session, throttling repeat nudges. Empty uses the default
	// (NotifyInboxCooldownDefault); "0" disables the cooldown.
	InboxCooldown string `toml:"inbox_cooldown"`
	// InboxDetachedDelay is the settle delay before notifying a session with no
	// attached client (no user-idle signal to wait on). Empty uses the default
	// (NotifyInboxDetachedDelayDefault); "0" notifies immediately.
	InboxDetachedDelay string `toml:"inbox_detached_delay"`
}

type Notifications struct {
	Enabled    bool   `toml:"enabled"`
	OnApproval bool   `toml:"on_approval"`
	OnStopped  bool   `toml:"on_stopped"`
	Command    string `toml:"command"`
	// Backend selects how proactive `gr notify` push notifications are delivered:
	// "macos" (osascript desktop notification; the default when unset) or
	// "command" (run [notifications] command with GRAITH_NOTIFY_* env vars). Other
	// backends (ntfy/pushover/slack) are planned follow-ups and rejected for now.
	Backend string `toml:"backend"`
	// MaxPerHour rate-limits low/normal push notifications over a rolling hour so a
	// misbehaving trigger can't storm the user. <=0 uses DefaultNotifyMaxPerHour.
	// High-priority notifications bypass this limit.
	MaxPerHour int `toml:"max_per_hour"`
	// QuietHoursStart / QuietHoursEnd define a daily window ("HH:MM", 24-hour) in
	// which low/normal push notifications are suppressed. The window may wrap past
	// midnight (start > end, e.g. 22:00-07:00). Both must be set to take effect.
	// High-priority notifications bypass quiet hours.
	QuietHoursStart string `toml:"quiet_hours_start"`
	QuietHoursEnd   string `toml:"quiet_hours_end"`
	// Timing carries the low-level coalescing, dispatch, and PTY-injection
	// timing knobs under [notifications.timing]. Every field is optional and
	// resolves to its documented default through the NotificationTiming accessors,
	// so leaving the table out preserves the historical behaviour (issue #1245).
	Timing NotificationTiming `toml:"timing"`
}

type OrchestratorConfig struct {
	Enabled     bool                      `toml:"enabled"`
	Agent       string                    `toml:"agent"`
	Model       string                    `toml:"model"`
	IdleTimeout string                    `toml:"idle_timeout"`
	Prompt      string                    `toml:"prompt"`
	PromptFile  string                    `toml:"prompt_file"`
	Sandbox     OrchestratorSandboxConfig `toml:"sandbox"`
	Restart     OrchestratorRestartConfig `toml:"restart"`
}

type OrchestratorRestartConfig struct {
	// InitialBackoff is the first restart delay in geometric mode (Schedule empty).
	// Empty uses OrchestratorInitialBackoffDefault.
	InitialBackoff string `toml:"initial_backoff"`
	// MaxBackoff caps the restart delay in geometric mode. Empty uses
	// OrchestratorMaxBackoffDefault.
	MaxBackoff string `toml:"max_backoff"`
	// Multiplier grows the delay each attempt in geometric mode. Values <= 1 fall
	// back to OrchestratorMultiplierDefault.
	Multiplier float64 `toml:"multiplier"`
	// Schedule is an explicit list of per-attempt delays. When set it overrides
	// the geometric knobs; the last entry repeats for attempts beyond its length.
	Schedule []string `toml:"schedule"`
	// StableReset is how long a run must last before its exit resets the backoff
	// level to 0. Empty uses OrchestratorStableResetDefault.
	StableReset string `toml:"stable_reset"`
	// FreshStartThreshold is the number of consecutive restarts after which the
	// orchestrator is relaunched fresh (new agent session id). Values < 1 fall
	// back to OrchestratorFreshStartThresholdDefault.
	FreshStartThreshold int `toml:"fresh_start_threshold"`
}

type OrchestratorSandboxConfig struct {
	ReadDirs   []string `toml:"read_dirs"`
	WriteDirs  []string `toml:"write_dirs"`
	ReadFiles  []string `toml:"read_files"`
	WriteFiles []string `toml:"write_files"`
}

type Overlay struct {
	ShortcutKeys string `toml:"shortcut_keys"`
}

type OverlayKeybindings struct {
	// Shared navigation, applied across the overlays.
	Up       string `toml:"up"`
	Down     string `toml:"down"`
	PageUp   string `toml:"page_up"`
	PageDown string `toml:"page_down"`
	Top      string `toml:"top"`
	Bottom   string `toml:"bottom"`
	Confirm  string `toml:"confirm"`
	Cancel   string `toml:"cancel"`
	// Dashboard actions.
	DashboardAttach string `toml:"dashboard_attach"`
	DashboardStop   string `toml:"dashboard_stop"`
	DashboardDelete string `toml:"dashboard_delete"`
	DashboardResume string `toml:"dashboard_resume"`
	// Approval prompt actions.
	ApprovalAllow    string `toml:"approval_allow"`
	ApprovalDeny     string `toml:"approval_deny"`
	ApprovalAllowAll string `toml:"approval_allow_all"`
	// Message viewer actions.
	MessagePin         string `toml:"message_pin"`
	MessageExpandAll   string `toml:"message_expand_all"`
	MessageCollapseAll string `toml:"message_collapse_all"`
	MessageNextConv    string `toml:"message_next_conversation"`
	MessagePrevConv    string `toml:"message_prev_conversation"`
}

type PRWatchAdvancedConfig struct {
	// BaseTick is the base poll-loop cadence (per-session gating paces the actual
	// gh calls below it). Default 15s. Applied when the watch loop starts.
	BaseTick string `toml:"base_tick"`
	// BatchSize caps how many sessions are polled per tick, bounding gh load on a
	// large fleet. Default 3.
	BatchSize int `toml:"batch_size"`
	// NoPRNegativeCache is how long a branch with no PR is left before re-resolving
	// on the ordinary timer. Default 5m.
	NoPRNegativeCache string `toml:"no_pr_negative_cache"`
	// CommentBodyMaxBytes truncates each delivered PR-comment body to this many
	// bytes, bounding notification size. Default 1024.
	CommentBodyMaxBytes int `toml:"comment_body_max_bytes"`
	// NotificationRateLimit / NotificationRateWindow are the per-session rolling
	// anti-thrash backstop: at most this many notifications per window to one
	// session. Defaults 5 per 30m.
	NotificationRateLimit  int    `toml:"notification_rate_limit"`
	NotificationRateWindow string `toml:"notification_rate_window"`
	// UntrustedAuthorPromptRate / UntrustedAuthorPromptWindow bound the untrusted
	// comment-author trust prompt to the orchestrator (a security surface — a busy
	// public PR churning drive-by commenters must not flood it). Defaults 5 per 30m.
	UntrustedAuthorPromptRate   int    `toml:"untrusted_author_prompt_rate"`
	UntrustedAuthorPromptWindow string `toml:"untrusted_author_prompt_window"`
	// MaxPromptedAuthors bounds the persisted set of already-surfaced untrusted
	// authors so it can't grow without limit. Default 5000.
	MaxPromptedAuthors int `toml:"max_prompted_authors"`
	// KickCooldown is the minimum interval between git-ref-triggered immediate polls
	// of one session (belt-and-braces over the ref-watch debounce). Default 3s.
	KickCooldown string `toml:"kick_cooldown"`
	// KickChannelSize is the buffered kick-channel capacity; a full channel drops
	// the (best-effort) kick. Default 64. Applied when the watch state is built.
	KickChannelSize int `toml:"kick_channel_size"`
	// KickedNoPRBackoff is the short re-poll delay after a kicked poll finds no PR
	// yet (a push is usually moments before `gh pr create`), instead of parking on
	// the full negative cache. Default 20s.
	KickedNoPRBackoff string `toml:"kicked_no_pr_backoff"`
	// RefReconcileInterval is how often the git-ref watcher set is reconciled
	// against live sessions. Default 2s. Applied when the ref-watch loop starts.
	RefReconcileInterval string `toml:"ref_reconcile_interval"`
	// RefDebounce coalesces the burst of ref/reflog writes one push/commit/checkout
	// produces into a single kick. Default 750ms.
	RefDebounce string `toml:"ref_debounce"`
	// GHTimeout is the per-command timeout for the daemon's `gh` invocations, so a
	// hung gh can never stall the loop. Default 5s.
	GHTimeout string `toml:"gh_timeout"`
}

type PRWatchConfig struct {
	Enabled               bool   `toml:"enabled"`
	NotifyCIFailures      bool   `toml:"notify_ci_failures"`
	NotifyMergeConflicts  bool   `toml:"notify_merge_conflicts"`
	NotifyReviewComments  bool   `toml:"notify_review_comments"`
	NotifyPRComments      bool   `toml:"notify_pr_comments"`
	NotifyReviewDecisions bool   `toml:"notify_review_decisions"`
	NotifyPRLifecycle     bool   `toml:"notify_pr_lifecycle"`
	NotifyCIRecovery      bool   `toml:"notify_ci_recovery"`
	PollPending           string `toml:"poll_pending"`
	PollTerminal          string `toml:"poll_terminal"`
	PollMerged            string `toml:"poll_merged"`
	MaxNotificationsPerPR int    `toml:"max_notifications_per_pr"`
	Debounce              string `toml:"debounce"`
	// CommentAuthorAllowlist trusts individual comment authors by login,
	// case-insensitively and matched against the full "<name>[bot]" string. It is
	// the ONLY way to trust a bot or GitHub App (their author_association is
	// unreliable — a bot can carry NONE or CONTRIBUTOR), and also covers named
	// humans. Defaults empty; discovery is via the orchestrator trust prompt.
	CommentAuthorAllowlist []string `toml:"comment_author_allowlist"`
	// TrustedAuthorAssociations is the set of GitHub author_association values
	// treated as trusted. Defaults to OWNER/MEMBER/COLLABORATOR when unset (the
	// "has write access to, or is a member of the org that owns, the repo" tier);
	// CONTRIBUTOR is deliberately excluded. Values are normalised to upper-case
	// via TrustedAssociationSet.
	TrustedAuthorAssociations []string `toml:"trusted_author_associations"`
	// NotifyUntrustedAuthors, when true, sends a one-time metadata-only message to
	// the orchestrator the first time a comment from a not-yet-trusted author is
	// seen, so the human can decide whether to allowlist them. It NEVER carries
	// the untrusted comment body. False disables the prompt entirely (silent drop,
	// still logged).
	NotifyUntrustedAuthors bool `toml:"notify_untrusted_authors"`
	// Advanced holds the low-level watcher-tuning knobs (loop cadence, batch size,
	// caches, rate limits, ref-watch timing, gh timeout). Every field is optional
	// and falls back to a sensible default via the accessors below, so a config
	// that omits [pr_watch.advanced] entirely behaves exactly as before. Expose
	// these only for operators who need to trade off load, latency, retention, and
	// prompt-injection surface — the defaults suit ordinary use.
	Advanced PRWatchAdvancedConfig `toml:"advanced"`
}

type PairRate struct {
	Count int
	Per   time.Duration
}

type Paths struct {
	Profile        string
	AppName        string
	ConfigFile     string
	DataDir        string
	RuntimeDir     string
	SocketPath     string
	PIDFile        string
	StateFile      string
	HumanTokenFile string
	LogDir         string
	DaemonLog      string
	MessagesDB     string
	TodosDB        string
	TmpDir         string
}

type RemoteConfig struct {
	// Enabled turns the remote listener on. Off by default; when false the rest
	// of the block is not validated so a disabled block never blocks startup.
	Enabled bool `toml:"enabled"`
	// Mode selects the transport: "tsnet" (embedded Tailscale via tsnet) or
	// "interface" (bind the host's existing tailnet interface IP).
	Mode string `toml:"mode"`
	// Hostname is the tsnet node name / MagicDNS label and the remote TLS
	// certificate name.
	Hostname string `toml:"hostname"`
	// Port is the TCP port the listener binds.
	Port int `toml:"port"`
	// AuthKeyFile is the path to a tsnet auth key (tsnet mode only).
	AuthKeyFile string `toml:"auth_key_file"`
	// Tags are the tsnet ACL tags applied to the node (tsnet mode only).
	Tags []string `toml:"tags"`
	// AllowTailnetUsers is the WhoIs allowlist (Gate 1). Entries are either a
	// tailnet user email or a "tag:"-prefixed tag. A bare "tag:" entry opts
	// tagged nodes in; with no tag entry, tagged nodes are disallowed.
	AllowTailnetUsers []string `toml:"allow_tailnet_users"`
	// RequirePairing requires per-device pairing (Gate 2) for human-level
	// rights. Defaults to true; false is UNSAFE (trusts the tailnet identity
	// alone) and is restricted to read-only access — see the design doc §B.2.
	RequirePairing bool `toml:"require_pairing"`
	// PairRequestRate is the anti-flood limit on pending pair requests, written
	// "<n>/<unit>" (e.g. "5/min"); units are sec, min, or hour. Empty falls back
	// to the pair_fallback_count/pair_fallback_window rate below.
	PairRequestRate string `toml:"pair_request_rate"`
	// MaxPendingPairings caps how many unapproved pair requests may be
	// outstanding at once (anti-flood). 0 uses the default
	// (RemoteMaxPendingPairingsDefault); values outside [1,
	// RemoteMaxPendingPairingsMax] are a hard config error.
	MaxPendingPairings int `toml:"max_pending_pairings"`
	// PendingPairingTTL is how long an unapproved pair request lives before it
	// expires and can no longer be approved. Empty uses the default
	// (RemotePendingPairingTTLDefault); a parsed value outside
	// [RemotePendingPairingTTLMin, RemotePendingPairingTTLMax] is a hard error.
	PendingPairingTTL string `toml:"pending_pairing_ttl"`
	// PairFallbackCount is the request count of the rate limit applied when
	// pair_request_rate is unset. 0 uses the default
	// (RemotePairFallbackCountDefault); values outside [1,
	// RemotePairFallbackCountMax] are a hard config error.
	PairFallbackCount int `toml:"pair_fallback_count"`
	// PairFallbackWindow is the window of the rate limit applied when
	// pair_request_rate is unset. Empty uses the default
	// (RemotePairFallbackWindowDefault); a parsed value outside
	// [RemotePairFallbackWindowMin, RemotePairFallbackWindowMax] is a hard error.
	PairFallbackWindow string `toml:"pair_fallback_window"`
}

type RepoConfig struct {
	Path            string   `toml:"path"`
	AllowConcurrent bool     `toml:"allow_concurrent"`
	Singleton       bool     `toml:"singleton"`
	Includes        []string `toml:"includes"`
}

type ResourceMonitor struct {
	// SampleInterval is the cadence at which each session's process group is
	// snapshotted (and the per-session spacing that keeps a launch-burst kick
	// from replacing an established session's history). Empty, unparseable, or
	// non-positive uses the default (ResourceSampleIntervalDefault).
	SampleInterval string `toml:"sample_interval"`
	// SampleHistory is how many recent samples are retained per session (the
	// window shown in an abnormal-exit report). Values < 1 fall back to the
	// default (ResourceSampleHistoryDefault).
	SampleHistory int `toml:"sample_history"`
}

type SandboxConfig struct {
	Enabled  bool  `json:"enabled"            toml:"enabled"`
	Disabled *bool `json:"disabled,omitempty" toml:"disabled,omitempty"`
	// Backend selects the sandbox backend: "safehouse" (macOS only) or "nono"
	// (Linux + macOS). It has NO default — when the sandbox is enabled and
	// Backend is unset the daemon fails closed with an actionable error. This
	// is a deliberate pre-1.0 behaviour change (see the nono sandbox design doc).
	Backend string `json:"backend,omitempty" toml:"backend"`
	Command string `json:"command,omitempty" toml:"command"`
	// Profile (nono only) is the base profile graith's generated profile
	// extends. Empty means nono's built-in "default" (its audited deny groups +
	// base system paths). Set it to a maintained registry profile — e.g.
	// "always-further/claude" — to inherit that agent's upstream file grants
	// (its ~/.claude, ~/.claude.json, versioned binary dir, …) instead of
	// hand-listing them via write_files.
	//
	// nono resolves "extends" by MERGING the base profile with graith's
	// generated one. Collection fields (filesystem.allow/read,
	// environment.allow_vars, network.allow_domain, …) are UNIONED (append +
	// dedup) — graith's grants are added to, not substituted for, the base's;
	// only scalar fields (e.g. workdir.access, security.signal_mode) are
	// child-overridden. So graith's filesystem grants are always present, but
	// graith's env allowlist can only WIDEN the base profile's, it cannot narrow
	// it. A base profile that allows extra env vars, network
	// domains, set_vars, command policies, or session hooks (which run outside
	// the sandbox) therefore relaxes graith's baseline — so a custom profile is
	// only as tight as the operator has audited it to be. Choose a trusted,
	// least-privilege profile. nono's audited deny groups (deny_credentials, …)
	// are marked required and merged into every resolved profile regardless of
	// this field, so a custom base cannot silently drop the credential-deny
	// baseline. The safehouse backend has no profile concept and ignores it.
	Profile   string   `json:"profile,omitempty"    toml:"profile"`
	Features  []string `json:"features,omitempty"   toml:"features"`
	ReadDirs  []string `json:"read_dirs,omitempty"  toml:"read_dirs"`
	WriteDirs []string `json:"write_dirs,omitempty" toml:"write_dirs"`
	// ReadFiles / WriteFiles grant access to individual files rather than whole
	// directories. They exist for paths that can't be expressed as a directory
	// grant without over-sharing — most importantly single files that live
	// directly in $HOME (e.g. an agent's ~/.claude.json login file), where
	// granting the parent directory would expose unrelated secrets (.env, ssh
	// keys, tfvars). ReadFiles is read-only; WriteFiles is read+write, mirroring
	// the read_dirs / write_dirs convention (where "write" means read+write, not
	// nono's write-only mode). They map to the nono profile's
	// filesystem.read_file / filesystem.allow_file; the safehouse backend folds
	// them into its read-only / read-write path lists.
	ReadFiles  []string `json:"read_files,omitempty"  toml:"read_files"`
	WriteFiles []string `json:"write_files,omitempty" toml:"write_files"`
	// SignalMode controls whether the sandboxed process may signal other
	// processes. It maps to nono's security.signal_mode ("isolated",
	// "allow_same_sandbox", "allow_all"). Empty inherits nono's base-profile
	// default (allow_same_sandbox). safehouse ignores it. Setting "isolated"
	// makes graith's `process-control` semantics meaningful under nono (Phase 1
	// left it a no-op). See the nono sandbox design doc §C5.
	SignalMode string `json:"signal_mode,omitempty" toml:"signal_mode"`
	// Network is an optional egress policy. It maps to the nono profile's
	// network section (network.block / network.allow_domain). safehouse has no
	// network primitive and only warns. A network policy also raises the
	// enforcement floor: nono needs Landlock ABI v4 (kernel 6.7+) to filter
	// network, so a requested policy on an older kernel fails closed.
	Network *SandboxNetworkConfig `json:"network,omitempty" toml:"network"`
}

type SandboxNetworkConfig struct {
	// Block denies all outbound network access (nono is network-allowed by
	// default). Maps to network.block = true.
	Block bool `json:"block,omitempty" toml:"block"`
	// AllowDomains is the proxy allowlist. Maps to network.allow_domain. When
	// set, nono runs its L7 filtering proxy and only these domains are
	// reachable. Entries are plain hostnames or URL globs.
	AllowDomains []string `json:"allow_domains,omitempty" toml:"allow_domains"`
}

type ScenarioLifecycleConfig struct {
	Cleanup string `json:"cleanup,omitempty" toml:"cleanup"`
	Delay   string `json:"delay,omitempty"   toml:"delay"`
}

type ScheduleConfig struct {
	Cron     string `toml:"cron"`     // 5-field cron, or @hourly/@daily/@weekly/@monthly
	Every    string `toml:"every"`    // Go duration (supports "7d"): "15m", "1h30m"
	Timezone string `toml:"timezone"` // IANA zone for cron; default = daemon local time
}

type StatusBar struct {
	Enabled  bool   `toml:"enabled"`
	Position string `toml:"position"`
}

type StatusConfig struct {
	TTL string `toml:"ttl"`
}

type TemplateVars struct {
	Username                 string
	AgentSessionID           string
	SessionName              string
	SessionID                string
	WorktreePath             string
	ForkSourceAgentSessionID string
	Model                    string
	// Dir is the directory bound to {dir} when expanding an agent's
	// add_dir_args, once per granted worktree (see Agent.AddDirArgsFor). It is
	// empty in every other expansion context.
	Dir string
	// Profile, ReasoningEffort, ServiceTier, ApprovalPolicy, and WebSearch are
	// the Codex per-session options (issue #1186) surfaced as template variables
	// so an agent's conditional option_args groups (Agent.OptionArgsFor) can turn
	// them into CLI flags from config rather than hard-coded Go (issue #1236).
	// WebSearch is a boolean; it expands to "true" when set and "" otherwise, so
	// an option_args group can gate on it with `when = "web_search"`.
	Profile         string
	ReasoningEffort string
	ServiceTier     string
	ApprovalPolicy  string
	WebSearch       bool
}

type TerminalConfig struct {
	// RefreshInterval is the cadence at which the session picker, the dashboard,
	// and an attached status bar re-poll the daemon for fresh session state.
	// Empty, unparseable, or non-positive uses the default
	// (TerminalRefreshIntervalDefault); a zero cadence would busy-loop.
	RefreshInterval string `toml:"refresh_interval"`
	// SummaryWidth is the maximum visible width (in cells) of a `gr status`
	// summary shown against a session in the picker before it is truncated with
	// an ellipsis. Values < 1 fall back to the default (TerminalSummaryWidth).
	SummaryWidth int `toml:"summary_width"`
}

type TodoConfig struct {
	EmitEvents string `toml:"emit_events"` // "scenario" (default) | "all" | "off"
	ClaimLease string `toml:"claim_lease"` // Go duration; "" = 30m default; "0" disables
	Retention  string `toml:"retention"`   // Go duration; "" or "0" = keep done items forever
	// MaxTitle is the maximum todo title length in bytes. Values < 1 fall back to
	// the default (TodoMaxTitleDefault); a value above TodoMaxTitleCeiling — the
	// hard limit baked into the database CHECK constraint — is rejected at load.
	// Config may only tighten below the ceiling. Reloadable.
	MaxTitle int `toml:"max_title"`
	// MaxNote is the maximum todo note length in bytes. Values < 1 fall back to
	// the default (TodoMaxNoteDefault); a value above TodoMaxNoteCeiling — the
	// hard database CHECK ceiling — is rejected at load. Reloadable.
	MaxNote int `toml:"max_note"`
	// ListLimit caps how many items a single List/ListAll returns, so an in-scope
	// caller can't force an unbounded allocation or a long store-mutex hold. Values
	// < 1 fall back to the default (TodoListLimitDefault); a value above
	// TodoListLimitCeiling is rejected at load. Restart-only (fixed at store open).
	ListLimit int `toml:"list_limit"`
	// SweepInterval is how often the lease/retention sweep loop runs. Empty,
	// unparseable, or non-positive uses the default (TodoSweepIntervalDefault); a
	// zero cadence would busy-loop. Restart-only (the loop ticker is built once).
	SweepInterval string `toml:"sweep_interval"`
	// BusyTimeout is the SQLite busy_timeout for the todos database. The claim
	// contract ("loser gets zero rows") relies on a contended writer waiting rather
	// than erroring with SQLITE_BUSY, so this is load-bearing. Empty/unset uses the
	// default (TodoBusyTimeoutDefault, 5s). An explicit value must parse and fall
	// in [SQLiteBusyTimeoutResolution, TodoBusyTimeoutCeiling] (1ms–5m): SQLite's
	// busy_timeout has millisecond resolution, so a positive sub-1ms value would
	// collapse to busy_timeout(0) and disable the wait the claim contract depends
	// on, and it — along with any unparseable, non-positive, or above-ceiling
	// value — is rejected at load. Restart-only.
	BusyTimeout string `toml:"busy_timeout"`
}

type TokenAccounting struct {
	// PollInterval is the cadence at which the loop re-derives per-session token
	// usage from transcripts. Empty, unparseable, or non-positive uses the
	// default (TokenPollIntervalDefault); a zero cadence would busy-loop.
	PollInterval string `toml:"poll_interval"`
	// StartupDelay is the short first-tick delay after a daemon (re)start so
	// `gr tokens` isn't blank for a full interval. Empty or unparseable uses the
	// default (TokenStartupDelayDefault); an explicit "0" polls immediately.
	StartupDelay string `toml:"startup_delay"`
	// BatchSize bounds how many sessions are (re)parsed per tick so a large fleet
	// with big transcripts can't stall the loop. Values < 1 fall back to the
	// default (TokenBatchSizeDefault).
	BatchSize int `toml:"batch_size"`
}

type ToolsConfig struct {
	// Git is the git executable (default "git").
	Git string `toml:"git"`
	// GH is the GitHub CLI executable (default "gh").
	GH string `toml:"gh"`
	// GCX is the Grafana Cloud CLI executable used by gcx trigger sources
	// (default "gcx").
	GCX string `toml:"gcx"`
	// Shell runs notification and trigger commands as `<shell> -c <cmd>`
	// (default "sh").
	Shell string `toml:"shell"`
	// OSAScript is the macOS osascript executable used for desktop
	// notifications (default "osascript").
	OSAScript string `toml:"osascript"`
	// PS is the process-listing executable (default "/bin/ps").
	PS string `toml:"ps"`
	// Lsof is the open-files listing executable (default "/usr/sbin/lsof").
	Lsof string `toml:"lsof"`
}

type TrackerConfig struct {
	Provider      string   `toml:"provider"`       // "github" (v1); "" defaults to github
	Repo          string   `toml:"repo"`           // resolves the tracker + is the spawn repo (required)
	ActiveState   string   `toml:"active_state"`   // open | closed | all (default open)
	ActiveLabels  []string `toml:"active_labels"`  // active iff the issue has one of these (empty = any state-matching issue)
	Assignee      string   `toml:"assignee"`       // optional tracker assignee filter (e.g. "@me")
	Grace         string   `toml:"grace"`          // inactive this long before reaping; default 5m
	MaxConcurrent int      `toml:"max_concurrent"` // cap on live tracker sessions (0 = unlimited)
	Reap          string   `toml:"reap"`           // stop | delete | none (default stop)
	Limit         int      `toml:"limit"`          // max issues fetched per poll (default 50)
}

type TranscriptConfig struct {
	// MaxContextBytes is the approximate size budget for the rendered migration/
	// fork context document; older turns are elided to fit. 0/negative uses
	// TranscriptMaxContextBytesDefault.
	MaxContextBytes int `toml:"max_context_bytes"`
	// MaxToolOutputBytes caps each rendered tool-output block. 0/negative uses
	// TranscriptMaxToolOutputBytesDefault.
	MaxToolOutputBytes int `toml:"max_tool_output_bytes"`
	// MaxLineBytes is the scanner buffer cap for a single transcript line while
	// reading turns or summing usage (large tool outputs / base64 exceed the
	// 64KiB default). 0/negative uses TranscriptMaxLineBytesDefault.
	MaxLineBytes int `toml:"max_line_bytes"`
	// MaxMetadataLineBytes is the scanner buffer cap for the small metadata-only
	// scans (Codex rollout cwd / session-id lookup). 0/negative uses
	// TranscriptMaxMetadataBytesDefault.
	MaxMetadataLineBytes int `toml:"max_metadata_line_bytes"`
}

type TriggerConfig struct {
	Name       string            `toml:"name"`
	Enabled    *bool             `toml:"enabled"`    // nil => default true; explicit false disables
	Schedule   *ScheduleConfig   `toml:"schedule"`   // time-driven source
	Watch      *WatchConfig      `toml:"watch"`      // file-event source
	GCX        *GCXConfig        `toml:"gcx"`        // Grafana Cloud event source
	Completion *CompletionConfig `toml:"completion"` // scenario todo-completion edge
	Action     ActionConfig      `toml:"action"`
	Policy     TriggerPolicy     `toml:"policy"`
}

type TriggerPolicy struct {
	CatchUp   bool   `toml:"catch_up"`   // default false: never backfill missed fires
	Overlap   string `toml:"overlap"`    // "" or "skip" (default) | "allow" | "queue"(v2)
	RateLimit string `toml:"rate_limit"` // "N/duration"; default "5/30m"
}

type TriggerVars struct {
	Name            string // trigger name
	Date            string // e.g. 2026-07-11
	Datetime        string // RFC3339
	FireTime        string // scheduled/observed fire instant (RFC3339)
	SessionName     string // watch source: the bound session
	WorktreePath    string // watch source: the bound session's worktree
	ChangedFiles    string // watch source: comma-separated changed paths (or "")
	ChangeCount     string // watch source: number of changed paths
	ScenarioID      string // completion source: owning scenario ID
	ScenarioName    string // completion source: owning scenario name
	CompletionEpoch string // completion source: monotonically increasing epoch
	// Tracker action: the issue a spawned session is seeded from. These are known
	// template tokens (they live in this shared struct), so they expand to the
	// empty string — not an error — outside a tracker prompt; a genuinely unknown
	// token still errors.
	IssueNumber string // e.g. "643"
	IssueTitle  string
	IssueBody   string
	IssueURL    string
	IssueLabels string // comma-separated label names (or "")
	// GCX source: stable, structured event metadata. Raw alert title, labels,
	// annotations, and subject are deliberately excluded because external alert
	// text is untrusted input to an autonomous agent.
	GCXEventID       string
	GCXEventKind     string
	GCXEventState    string
	GCXEventURL      string
	GCXTeamID        string
	GCXIntegrationID string
	GCXStartedAt     string
}

type TriggersAdvancedConfig struct {
	// SchedulerTick is the trigger scheduler loop cadence. Cron granularity is one
	// minute, so this only bounds sub-minute "every" intervals and dispatch
	// latency. Default 1s. Applied when the scheduler loop starts.
	SchedulerTick string `toml:"scheduler_tick"`
	// RunHistoryMax caps how many past runs each trigger retains in its persisted
	// history. Default 20.
	RunHistoryMax int `toml:"run_history_max"`
	// WatchReconcileInterval is how often file-watch bindings are reconciled
	// against live sessions (creating, tearing down, and retrying degraded
	// bindings). Default 2s. Applied when the file-watch loop starts.
	WatchReconcileInterval string `toml:"watch_reconcile_interval"`
	// WatchRetryBaseBackoff is the delay before the first retry of a degraded
	// file-watch binding (e.g. one that hit fs.inotify.max_user_watches).
	// Subsequent retries back off exponentially from here. Default 5s.
	WatchRetryBaseBackoff string `toml:"watch_retry_base_backoff"`
	// WatchRetryMaxBackoff caps the exponential degraded-binding backoff so a
	// persistently degraded binding keeps retrying periodically. Default 5m.
	WatchRetryMaxBackoff string `toml:"watch_retry_max_backoff"`
	// WatchBuiltinIgnores is the daemon-wide set of directories/patterns never
	// watched by any file-watch trigger (on top of git ignore rules and per-trigger
	// watch.ignore). Omitting the key uses DefaultWatchBuiltinIgnores; an explicit
	// empty list ([]) keeps only the mandatory ignores. ".git"/".git/" are always
	// ignored regardless of this list (a watched .git churns constantly and creates
	// a feedback loop).
	WatchBuiltinIgnores []string `toml:"watch_builtin_ignores"`
	// CommandOutputCap truncates a command action's captured output to this many
	// bytes before delivery, bounding notification size. Default 4096.
	CommandOutputCap int `toml:"command_output_cap"`
}

type TriggersRuntime struct {
	MaxConcurrent int `toml:"max_concurrent"` // default 4
	// Advanced holds the low-level scheduler and file-watch tuning knobs (loop
	// cadence, run-history retention, degraded-binding backoff, the daemon-wide
	// watch ignore list, and the command-output cap). Every field is optional and
	// falls back to the historical default via the accessors below, so a config
	// that omits [triggers.advanced] behaves exactly as before. Expose these only
	// for operators who need to trade off detection latency, filesystem-watch
	// load, and notification size — the defaults suit ordinary use.
	Advanced TriggersAdvancedConfig `toml:"advanced"`
}

type UnknownKey struct {
	// Table is the dotted parent-table path, e.g. "agents.claude.sandbox".
	// Empty for top-level keys.
	Table string
	// Name is the unrecognised leaf key, e.g. "read_dir".
	Name string
	// Suggestion is the closest known key in the same table, or "" if none is
	// close enough to be worth a "did you mean".
	Suggestion string
}

type UpdatesConfig struct {
	// Enabled turns the update check on. Defaults to true via the embedded
	// default config; set false to disable all update-check network I/O.
	Enabled bool `toml:"enabled"`
	// Repository is the "owner/repo" whose latest release is queried. Empty uses
	// the canonical d0ugal/graith repository.
	Repository string `toml:"repository"`
	// Interval is how often the check refreshes (cached between checks). Empty
	// uses the 1h default; must parse as a duration.
	Interval string `toml:"interval"`
	// Timeout bounds the release HTTP request. Empty uses the 5s default; must
	// parse as a duration.
	Timeout string `toml:"timeout"`
}

type WatchConfig struct {
	Repo     string   `toml:"repo"`     // bind to sessions on this repo
	Role     string   `toml:"role"`     // bind to sessions with this scenario role
	Paths    []string `toml:"paths"`    // optional include globs (worktree-relative)
	Ignore   []string `toml:"ignore"`   // extra ignore globs (added to built-ins + .gitignore)
	Debounce string   `toml:"debounce"` // quiet-window; default 30s
}

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