Installed gateway daemons ignore the fatal-config exit code and crash-loop on bad config

[MervinPraison]

Summary

The gateway process is careful to signal its restart intent to a supervisor: it exits 78 (EX_CONFIG) for a fatal/unfixable configuration error ("stop restarting me") and 75 (EX_TEMPFAIL) for a transient failure ("please restart me"). But the daemon units the SDK installs — systemd, launchd and the Windows scheduled task — all restart unconditionally, so the 78 signal is discarded and a genuinely broken config produces an infinite crash-loop (a fresh process every ~5 seconds) instead of a clean stop. This defeats the restart-intent contract the runtime already implements and turns an operator typo into a log-flooding, API-hammering loop that only stops when a human notices.

Current behaviour

The runtime emits the intent-carrying exit codes correctly:

# src/praisonai-bot/praisonai_bot/cli/features/gateway.py  (~L126, L194, L256)
#   * 75 (EX_TEMPFAIL) — transient failure; ask the supervisor to restart
#   * 78 (EX_CONFIG)   — fatal configuration error (do not restart)
...
        return GATEWAY_FATAL_CONFIG_EXIT_CODE       # 78
...
        except FatalConfigError as e:
            ...

Core even ships the classifier and a restart-loop guard for exactly this purpose (GATEWAY_FATAL_CONFIG_EXIT_CODE, GATEWAY_RESTART_EXIT_CODE, classify_exit_reason, RestartLoopGuard in praisonaiagents/gateway/protocols.py).

But the generated supervisor units throw the signal away:

# src/praisonai-bot/praisonai_bot/daemon/systemd.py  (~L44)
ExecStart={python} -m praisonai_bot gateway start --config {abs_config}
Restart=always      # ← ignores exit code; restarts even on 78 (fatal config)
RestartSec=5

<!-- src/praisonai-bot/praisonai_bot/daemon/launchd.py  (~L63) -->
<key>KeepAlive</key>
<true/>              <!-- ← always relaunch, regardless of exit status -->

The Windows backend (src/praisonai-bot/praisonai_bot/daemon/windows.py, scheduled task PraisonAIGateway) likewise has no exit-code-aware stop condition.

Net effect: Restart=always / KeepAlive=true restart the gateway even when it just told the OS "my config is fatally broken, do not restart me". The operator sees a process that flaps forever, each boot re-parsing the same broken config and (depending on where it fails) re-hitting provider/channel APIs.

Desired behaviour

The installed daemons should honour the exit-code contract the runtime already speaks:

• Exit 78 (fatal config) ⇒ the supervisor stops and does not restart, leaving a clear "stopped: fatal config" status for the operator to fix.
• Exit 75 (transient) and unexpected crashes ⇒ restart, ideally with backoff.
• Clean exit 0 ⇒ stay stopped.
• Restart storms are bounded (tie in the existing RestartLoopGuard) so even a mis-mapped case cannot hammer the machine.

Layer placement

• Primary layer: wrapper (praisonai-bot) — the daemon unit generators own the OS supervision policy and are where the exit-code mapping must be written.
• Why not core: core already provides the contract (GATEWAY_FATAL_CONFIG_EXIT_CODE, classify_exit_reason, RestartLoopGuard); nothing is missing there — this is purely about the wrapper's generated units consuming it.
• Why not tools: daemon/service management is not an agent-callable integration.
• Why not plugins: OS service installation is core wrapper operator tooling, not an opt-in lifecycle hook.
• Secondary touch: none required (core contract already exists).
• 3-way surface (CLI + YAML + Python): no — this is service-install output, surfaced via praisonai gateway install.

Proposed approach

• Extension point: the unit templates in daemon/{systemd,launchd,windows}.py, mapping the existing core exit codes to per-OS restart directives.

# systemd (sketch)
Restart=on-failure
RestartSec=5
SuccessExitStatus=0
RestartPreventExitStatus=78    # GATEWAY_FATAL_CONFIG_EXIT_CODE — do not restart on fatal config
StartLimitIntervalSec=60
StartLimitBurst=5              # bounded restarts, mirrors RestartLoopGuard

<!-- launchd (sketch): crash-only relaunch, and stop on fatal config -->
<key>KeepAlive</key>
<dict>
  <key>SuccessfulExit</key><false/>
  <key>Crashed</key><true/>
</dict>
<!-- plus a wrapper that maps exit 78 to a non-relaunch stop -->

Resolution sketch

# Before (today): fatal config → infinite crash-loop
$ praisonai gateway install && journalctl --user -u praisonai-bot -f
gateway: EX_CONFIG (78) fatal configuration error
<5s later> gateway: EX_CONFIG (78) fatal configuration error
<5s later> gateway: EX_CONFIG (78) fatal configuration error   # forever

# After (proposed): fatal config → stop, wait for the operator
$ praisonai gateway install && journalctl --user -u praisonai-bot -f
gateway: EX_CONFIG (78) fatal configuration error
systemd: praisonai-bot.service: start request repeated too quickly / not restarting (RestartPreventExitStatus=78)
$ praisonai gateway status
  daemon: stopped (fatal config — fix gateway.yaml and re-start)

Severity

High — an unattended 24/7 daemon is the intended production deployment. A crash-looping gateway floods logs, wastes CPU, and can repeatedly hit LLM/channel APIs on each boot attempt, all from a single bad edit — while the runtime is already signalling the correct "stop" intent that the units silently ignore.

Validation

• src/praisonai-bot/praisonai_bot/cli/features/gateway.py — returns GATEWAY_FATAL_CONFIG_EXIT_CODE (78) on FatalConfigError and documents 75/78 semantics (~L126, L194, L256).
• src/praisonai-bot/praisonai_bot/daemon/systemd.py:45 — Restart=always, no RestartPreventExitStatus.
• src/praisonai-bot/praisonai_bot/daemon/launchd.py:63 — KeepAlive is <true/> (unconditional relaunch).
• src/praisonai-bot/praisonai_bot/daemon/windows.py — scheduled task with no exit-code-aware stop.
• praisonaiagents/gateway/protocols.py — GATEWAY_FATAL_CONFIG_EXIT_CODE, classify_exit_reason, RestartLoopGuard already exist and are unused by the unit generators.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job • claude/issue-3160-20260718-0914 • [Create PR ➔](https://github.com/MervinPraison/PraisonAI/compare/main...claude/issue-3160-20260718-0914?quick_pull=1&title=Issue%20%233160%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%233160%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Fix: installed daemons now honour the gateway fatal-config exit code

• Read AGENTS.md & architecture rules
• Inspect daemon generators (systemd/launchd/windows) & core exit-code contract
• Implement exit-code-aware restart directives
• Test (updated + new unit assertions; manually validated generated units)
• Commit, push & open PR

PR: #3162

What changed (wrapper praisonai-bot only)

The runtime already emits 78 (EX_CONFIG, "do not restart") and 75 (EX_TEMPFAIL, "restart"), but the generated units restarted unconditionally, causing an infinite crash-loop on a bad config. Mapped the existing core contract onto per-OS directives:

• systemd (daemon/systemd.py:52): Restart=on-failure, SuccessExitStatus=0, RestartPreventExitStatus=78, plus StartLimitIntervalSec=60/StartLimitBurst=5 to bound restart storms (mirrors RestartLoopGuard).
• launchd (daemon/launchd.py:70): KeepAlive changed from <true/> to a dict (SuccessfulExit=false, Crashed=true) + ThrottleInterval=30. launchd has no exit-code-specific stop, so a fatal exit is bounded by throttle + the runtime guard rather than relaunching every ~5s.
• windows (daemon/windows.py): scheduled-task command and startup .cmd wrapped so exit 78 maps to a clean stop.

No core changes — the contract already exists in praisonaiagents/gateway/protocols.py; this only makes the wrapper consume it. Backward-compatible, minimal, no new params/deps.

Note: pytest isn't installed in this CI runner, so I validated the generated unit/plist/script output via direct imports instead of the pytest runner. CI will run the updated tests.
• Branch: claude/issue-3160-20260718-0914