Module background_config 

The tray icon and background-service mode, resolved by the launcher at startup — docs/specs/SPEC_OS_NOTIFICATIONS_SYSTEM_2026_09_24.md §4.1.

Why this module exists

tray::start_if_enabled reads AGENTMUX_TRAY + AGENTMUX_BACKGROUND_SERVICE from the launcher’s own environment. Before this module, nothing ever put them there:

• --background (what every auto-start artifact passes) was only mapped to env on the host Command (host_spawn.rs), so an auto-started instance got background semantics in the host but no tray icon — the “invisible background service” WS4 exists to prevent.
• There was no setting at all, so the tray was reachable only by exporting two env vars before launching.

Resolving once here, before any thread or child exists, and writing the result into the launcher’s own env fixes both: the tray reads it, the macOS headless-pump branch in main reads it, and every child (host) inherits it.

Two switches, two defaults

They are separate questions and must not be conflated (#3785 did, and turned background mode on for everyone; see docs/reports/REPORT_TRAY_BACKGROUND_DEFAULT_ON_2026_09_28.md):

• Tray icon ("app:showtray") — on by default. Shown while AgentMux runs. Only an explicit false hides it.
• Background mode ("app:runinbackground") — keep running after the last window closes. Opt-in: only an explicit true turns it on, so a fresh install quits on last-window-close.

Background mode always implies the tray: a resident process must show an icon, so app:showtray: false is overridden while background mode is on. And if the tray cannot start (e.g. Linux without a StatusNotifier host), the host is spawned without background mode (tray::unavailable), so closing the last window quits.

Precedence

Background: AGENTMUX_BACKGROUND_SERVICE already set (developer override) → on; otherwise --background → on; otherwise the setting. Tray: background on, or AGENTMUX_TRAY already set → on; otherwise the setting. A settings file that cannot be read or parsed leaves both at their default (the user’s real choice is unknown): background off, tray on.

Structs

Resolved

What the launcher exports.

Settings

The two settings as stored, with their defaults applied.

Constants

BACKGROUND_KEY

Settings keys. Flat namespace:key, like every other settings.json entry.

ENV_BACKGROUND 🔒

ENV_TRAY 🔒

TRAY_KEY

Functions

apply

Resolve both switches and export the ones that are on into the launcher’s own environment.

config_dir 🔒

Best-effort config dir (holds settings.json), resolved the same way splash_config does — early and failure-tolerant.

read_settings

Read both settings from a settings.json file. Each key keeps its default unless it holds a bool; a missing or unreadable file yields the defaults.

resolve

Pure decision, so every input combination is unit-testable.