Summary

• Problem: DEFAULT_AI_ASSISTANT env var unconditionally overwrites config.assistant in applyEnvOverrides(), silently masking any value saved via the Web UI Settings page.
• Why it matters: In Docker deployments, users who save "Default Assistant = Claude" via Settings see the change reflected until they reload — then it reverts to whatever DEFAULT_AI_ASSISTANT is set to. The save is effectively a no-op with no error shown.
• What changed: applyEnvOverrides() now treats DEFAULT_AI_ASSISTANT as a fallback default — it only applies when neither the global config nor the repo config has an explicit assistant set. Explicit config-file values win.
• What did not change: Streaming mode env vars (TELEGRAM_STREAMING_MODE, etc.) still behave as hard overrides — they have no UI-save path, so no fallback guard is needed there.

UX Journey

Before

User (Docker, DEFAULT_AI_ASSISTANT=codex)
────
Opens Settings ──────────▶  GET /api/config → { assistant: "codex" }
Selects Claude  ──────────▶  PATCH /api/config → writes defaultAssistant: claude to config.yaml ✅
Reloads page    ──────────▶  GET /api/config → { assistant: "codex" }  ← bug: env var wins again
User sees "codex" selected despite having saved "claude"

After

User (Docker, DEFAULT_AI_ASSISTANT=codex)
────
Opens Settings ──────────▶  GET /api/config → { assistant: "codex" }   (env fallback, no config yet)
Selects Claude  ──────────▶  PATCH /api/config → writes defaultAssistant: claude to config.yaml ✅
Reloads page    ──────────▶  GET /api/config → { assistant: "claude" }  ← [fixed: config file wins]
User sees "claude" selected — save is persistent

Architecture Diagram

Before

loadConfig()
  ├── loadGlobalConfig()           reads ~/.archon/config.yaml
  ├── mergeGlobalConfig()          sets config.assistant = globalConfig.defaultAssistant
  ├── loadRepoConfig() [optional]
  ├── mergeRepoConfig() [optional]
  └── applyEnvOverrides(config)    UNCONDITIONALLY sets config.assistant = DEFAULT_AI_ASSISTANT
                                   ↑ always wins regardless of saved config

After

loadConfig()
  ├── loadGlobalConfig()           reads ~/.archon/config.yaml
  ├── mergeGlobalConfig()          sets config.assistant = globalConfig.defaultAssistant
  ├── loadRepoConfig() [optional]  captured as repoConfig
  ├── mergeRepoConfig() [optional]
  └── applyEnvOverrides(config, globalConfig, repoConfig)
        [~] hasExplicitConfig = globalConfig.defaultAssistant || repoConfig.assistant
        [~] if (!hasExplicitConfig) → apply env var  (fallback only)
            if (hasExplicitConfig)  → skip env var   (config file wins)

Connection inventory:

Label Snapshot

• Risk: risk: low
• Size: size: XS
• Scope: core:config
• Module: core:config-loader

Change Metadata

• Change type: bug
• Primary scope: core

Linked Issue

• Closes Settings default assistant save is masked by DEFAULT_AI_ASSISTANT in Docker #1171

Validation Evidence (required)

bun run validate

All seven checks passed on the first run:

• Evidence provided: full bun run validate run captured in validation artifact
• No commands skipped

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No

The change only affects the precedence of a config-file value versus an env var — no new surfaces, no secret handling.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? Yes — semantics of DEFAULT_AI_ASSISTANT change: it is now a fallback, not a hard override. Operators who relied on the env var to permanently lock the assistant (even against user saves) will see different behavior. The expected and documented use case (provide a default for fresh installs) continues to work correctly.
• Database migration needed? No

Human Verification (required)

• Verified scenarios: unit tests cover (C1) env applies when no config sets assistant, (C2) global config assistant wins over env, (C3) repo config assistant wins over env
• Edge cases checked: invalid provider in env + config set → env skipped entirely (no throw); no config + no env → default 'claude' from getDefaults() unchanged
• What was not verified: end-to-end round-trip via a live Docker container with DEFAULT_AI_ASSISTANT=codex — covered by unit tests at the same precedence layer

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: loadConfig() — called by every API handler that reads config (GET /api/config, PATCH /api/config/assistants, workflow routes)
• Potential unintended effects: none anticipated; only the DEFAULT_AI_ASSISTANT precedence is changed; all other env overrides in applyEnvOverrides are unchanged
• Guardrails/monitoring for early detection: the three new/updated unit tests act as a regression guard

Rollback Plan (required)

• Fast rollback: git revert e847dad6 restores the unconditional override
• Feature flags or config toggles: none
• Observable failure symptoms: GET /api/config returns env-var provider instead of saved provider after a UI save

Risks and Mitigations

• Risk: operators who used DEFAULT_AI_ASSISTANT as a hard lock (preventing users from changing the assistant) will lose that capability
  • Mitigation: this was never documented behavior; the env var is documented as a "default". The correct way to lock a value is to not expose the Settings UI or to enforce it at the config-file level. The new behavior matches the documented intent.

Summary by CodeRabbit

• Bug Fixes

  • Fixed DEFAULT_AI_ASSISTANT environment variable to correctly function as a fallback only when no config file explicitly sets an assistant, ensuring configuration files take proper precedence.

• Documentation

  • Updated configuration reference to clarify DEFAULT_AI_ASSISTANT fallback behavior and precedence rules with config settings.