Summary

• Problem: Two macOS LaunchAgent lifecycle bugs in src/daemon/launchd.ts. (1) openclaw gateway stop unconditionally called launchctl disable before stopping, permanently suppressing KeepAlive auto-recovery — so a later crash or timeout would never respawn the gateway without a manual launchctl enable. (2) repairLaunchAgentBootstrap fell through to launchctl kickstart unconditionally in the already-loaded branch, restarting a healthy running service and disconnecting active WebUI/Discord sessions.
• Why it matters: Issue openclaw gateway stop calls launchctl disable unconditionally, breaks KeepAlive auto-recovery #77934 caused a 55-minute production outage (second multi-hour incident in a week) because a prior gateway stop left the service disabled — so KeepAlive failed to respawn after a timeout. Issue [Bug]: macOS LaunchAgent repair kickstarts already-loaded running gateway #77428 caused unnecessary gateway restarts and session drops every time the repair path ran against a running gateway.
• What changed: stopLaunchAgent default path now calls launchctl bootout only; persistent disable is opt-in via new --disable flag on openclaw gateway stop. repairLaunchAgentBootstrap calls readLaunchAgentRuntime in the already-loaded branch and skips kickstart if the service is already running. disable?: boolean added to GatewayServiceControlArgs, both DaemonLifecycleOptions types, and threaded through runServiceStop.
• What did NOT change: All security gates, deny-lists, and stop fallback paths in the --disable branch are preserved exactly. No behavior change on Linux (systemd) or Windows (schtasks). No gateway protocol or RPC changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes openclaw gateway stop calls launchctl disable unconditionally, breaks KeepAlive auto-recovery #77934
• Closes [Bug]: macOS LaunchAgent repair kickstarts already-loaded running gateway #77428
• This PR fixes a bug or regression

Real behavior proof

• Behavior or issue addressed: On macOS, openclaw gateway stop unconditionally called launchctl disable, permanently suppressing KeepAlive so the gateway would not respawn after unexpected crashes. A subsequent openclaw gateway start also required a manual launchctl enable first.
• Real environment tested: Source-level reproduction only — confirmed against src/daemon/launchd.ts:605 on 2daf3d332ff0 (current main still calls launchctl disable unconditionally before launchctl stop). No live macOS launchd environment available from this contributor.
• Exact steps or command run after this patch: openclaw gateway stop (default path hits launchctl bootout); openclaw gateway stop --disable (hits launchctl disable + launchctl stop)
• Evidence after fix: Unit test output — 50/50 tests pass in src/daemon/launchd.test.ts including new tests: "stops LaunchAgent via bootout by default", "stops LaunchAgent with disable+stop when --disable is passed", "skips kickstart when already-loaded service is actively running". Live macOS terminal output is not available from this contributor; requesting proof: override from a maintainer.
• Observed result after fix: Source diff confirms launchctl bootout replaces launchctl disable in the default stop path (src/daemon/launchd.ts). The --disable flag threads through GatewayServiceControlArgs → stopLaunchAgent for the old persistent-disable behavior.
• What was not tested: Live macOS launchd KeepAlive respawn after kill, --disable survival across reboot — no macOS machine available.

Root Cause (if applicable)

• Root cause (openclaw gateway stop calls launchctl disable unconditionally, breaks KeepAlive auto-recovery #77934): stopLaunchAgent called launchctl disable unconditionally (src/daemon/launchd.ts) to prevent launchd from immediately respawning the process after launchctl stop. This is correct for an operator-initiated stop, but the persistent disable state survived subsequent crashes — so KeepAlive could not fire until a manual launchctl enable was run.
• Root cause ([Bug]: macOS LaunchAgent repair kickstarts already-loaded running gateway #77428): repairLaunchAgentBootstrap detected the already-loaded bootstrap result and fell through to launchctl kickstart without checking whether the service was already running. Any healthy running gateway that triggered the repair path was unnecessarily restarted.
• Missing detection / guardrail: No runtime-state check before kickstart; no opt-out for the persistent disable on normal stop.
• Contributing context: openclaw gateway restart correctly calls launchctl enable before bootstrap (via launchd-restart-handoff.ts), so restarts recovered cleanly — but a plain stop followed by an unexpected crash had no recovery path.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/daemon/launchd.test.ts
• Scenario the test should lock in: Default stopLaunchAgent calls bootout only, never disable or launchctl stop. stopLaunchAgent({ disable: true }) calls disable + stop with no bootout on success. repairLaunchAgentBootstrap skips kickstart when readLaunchAgentRuntime reports status: "running". repairLaunchAgentBootstrap still kickstarts when service is stopped or state is unknown.
• Why this is the smallest reliable guardrail: The launchd functions are pure async wrappers around execLaunchctl; unit tests with mocked execFileUtf8 cover the exact conditional branches without requiring a real macOS environment.
• Existing test that already covered this: None — the bugs were untested. The existing "stops LaunchAgent by disabling relaunch" test was asserting the wrong (buggy) behavior.
• If no new test is added, why not: N/A — 5 new tests added, 9 existing tests updated.

User-visible / Behavior Changes

• openclaw gateway stop (macOS): default behavior changed — no longer calls launchctl disable; uses launchctl bootout instead. KeepAlive auto-recovery survives future crashes after a stop.
• openclaw gateway stop --disable (macOS): new flag — opts into the old persistent-disable behavior. Use when you explicitly want the gateway to stay down across crashes until next gateway start.
• openclaw gateway stop on Linux and Windows: no change — --disable flag is accepted by the CLI but ignored by systemd and schtasks stop implementations.
• repairLaunchAgentBootstrap: no longer restarts a running gateway. Behavior is unchanged when the service is stopped or state is unknown.

Diagram (if applicable)

Before (default stop):
[gateway stop] -> launchctl disable -> launchctl stop
                        |
             KeepAlive permanently suppressed
                        |
             crash -> gateway stays dead (outage)

After (default stop):
[gateway stop] -> launchctl bootout
                        |
             Job removed from domain, disable state untouched
                        |
             crash -> KeepAlive respawns gateway

After (stop --disable):
[gateway stop --disable] -> launchctl disable -> launchctl stop
                                  |
                        Same as old default (explicit opt-in)

Before (repair, already-loaded):
bootstrap -> already-loaded -> launchctl kickstart (unconditional)
                                      |
                           Running gateway restarted -> sessions dropped

After (repair, already-loaded):
bootstrap -> already-loaded -> readLaunchAgentRuntime
                                      |
                            status=running -> return ok, no kickstart
                            status=stopped -> launchctl kickstart
                            status=unknown -> launchctl kickstart (safe fallback)

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No — launchctl bootout replaces launchctl disable + stop in the default path; both are local macOS system calls with identical privilege requirements.
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS (M-series, Node v22)
• Runtime/container: npm global install, launchd LaunchAgent (gui/$UID/ai.openclaw.gateway)
• Model/provider: N/A
• Integration/channel: N/A
• Relevant config: KeepAlive: true, RunAtLoad: true in generated plist

Steps

1. Install OpenClaw and confirm gateway is running: openclaw status
2. Run openclaw gateway stop
3. Check: launchctl print gui/$UID/ai.openclaw.gateway → should return "Could not find service" (not disabled)
4. Run openclaw gateway start → gateway starts
5. Kill gateway process directly: kill $(pgrep -f "openclaw gateway")
6. Wait ThrottleInterval seconds → gateway respawns via KeepAlive
7. Run openclaw gateway stop --disable → verify service is disabled; KeepAlive does not respawn

Expected

• Steps 1–6: gateway respawns after crash without manual intervention
• Step 7: service stays down until openclaw gateway start

Actual (before fix)

• Step 2 permanently disabled KeepAlive → step 5 crash left gateway dead → manual launchctl enable + bootstrap required

Evidence

• Failing test/log before + passing after — 9 existing tests updated from buggy assertions; 5 new tests added; 50/50 pass
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: Default stop path uses bootout confirmed via test mock assertions on launchctlCalls; --disable path preserves full disable+stop+fallback chain; repair skips kickstart on running service; repair still kickstarts on stopped service; all failure/fallback paths for both fixes tested.
• Edge cases checked: Service already not loaded (bootout returns "not loaded" → handled by isLaunchctlNotLoaded); readLaunchAgentRuntime returns "unknown" (falls through to kickstart — safe conservative default); --disable on Linux/Windows (flag accepted, ignored by systemd/schtasks stop implementations).
• What you did not verify: Live macOS Crabbox end-to-end run with real launchctl calls (Crabbox unavailable). Integration e2e test at launchd.integration.e2e.test.ts covers the stop path structurally but does not run against a real launchd domain in CI.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes — default gateway stop behavior changes, but the new behavior is strictly safer. No config or env changes needed.
• Config/env changes? No
• Migration needed? No — operators who relied on gateway stop to permanently suppress KeepAlive should add --disable to their scripts or automations.

Risks and Mitigations

• Risk: Default bootout does not prevent launchd from reloading the plist on next login (KeepAlive: true + RunAtLoad: true are in the plist). A user who stops the gateway and reboots may see it auto-start.
  • Mitigation: This is the intended behavior of KeepAlive: true. Operators who want permanent suppression across reboots should use --disable or openclaw gateway uninstall. Documented in the --disable flag description.
• Risk: readLaunchAgentRuntime adds one launchctl print call in the already-loaded repair branch.
  • Mitigation: The already-loaded branch is only hit when launchctl bootstrap returns exit 130 or "already exists in domain" — an edge case on repair paths, not the hot path. Single synchronous shell call; negligible latency.