Summary

• Problem: When an agent triggers a gateway restart in supervised (launchd) mode, the process exits expecting KeepAlive: true to respawn it. But launchd's ThrottleInterval (60s since fix(gateway): add ThrottleInterval to prevent launchd restart loop #27650) delays the restart, leaving the gateway unresponsive for a full minute on every intentional restart.
• Why it matters: Agent-triggered restarts (via /restart or gateway-tool) should be near-instant. The 60s ThrottleInterval is correct for crash-loop prevention (fix(gateway): add ThrottleInterval to prevent launchd restart loop #27650), but penalizes deliberate restarts unnecessarily.
• What changed: process-respawn.ts now calls triggerOpenClawRestart() (explicit launchctl kickstart -k) on macOS when OPENCLAW_LAUNCHD_LABEL is set, before returning mode: "supervised". Falls back to mode: "failed" on kickstart error so run-loop.ts can do in-process restart.
• What did NOT change (scope boundary): No changes to restart.ts, run-loop.ts, plist generation, or ThrottleInterval value. No new shell commands — reuses existing triggerOpenClawRestart().

Change Type (select all)

• Bug fix
• Feature
• Refactor
• 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 Bug: gateway restart race condition causes launchd restart loop (macOS) #26904
• Related [Bug]: LaunchAgent KeepAlive: true causes restart loop when App and launchd both manage gateway lifecycle #20257
• Related [macOS] launchd 快速重启被误判为崩溃循环导致服务被卸载 #19138
• Complements fix(gateway): add ThrottleInterval to prevent launchd restart loop #27650 (added ThrottleInterval=60 for crash-loop prevention; this PR bypasses that delay for intentional restarts)

User-visible / Behavior Changes

Agent-triggered restarts on macOS now come back within seconds instead of waiting 60s (ThrottleInterval). No config changes required.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No — reuses existing triggerOpenClawRestart() which already calls launchctl kickstart
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS (Apple Silicon, Sequoia 26.2)
• Runtime/container: Node.js via launchd LaunchAgent
• Model/provider: Any
• Integration/channel (if any): Any — triggered by agent /restart command
• Relevant config (redacted): LaunchAgent plist with KeepAlive: true, ThrottleInterval: 60

Steps

1. Gateway running via launchd LaunchAgent with KeepAlive: true and ThrottleInterval: 60
2. Agent triggers /restart or gateway-tool restart
3. process-respawn.ts detects supervised mode, exits with code 0

Expected

• Gateway restarts within seconds via explicit launchctl kickstart -k

Actual (before fix)

• Gateway exits and waits 60s for launchd ThrottleInterval before restarting

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

pnpm test:fast src/infra/process-respawn.test.ts — 9/9 passing (including 2 new kickstart tests + updated stock-plist test).

Human Verification (required)

• Verified scenarios: Patched build installed locally, gateway running with patched code, OPENCLAW_LAUNCHD_LABEL confirmed in plist
• Edge cases checked: Kickstart failure path (bad label → falls back to mode: "failed"); non-macOS platforms skip kickstart; missing OPENCLAW_LAUNCHD_LABEL skips kickstart
• What you did not verify: Live agent-triggered /restart end-to-end (ready for testing now — patched build is installed and gateway is running)

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No — OPENCLAW_LAUNCHD_LABEL is already set by the launchd plist
• Migration needed? No
• If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Revert single commit; or unset OPENCLAW_LAUNCHD_LABEL env to skip the new code path entirely
• Files/config to restore: src/infra/process-respawn.ts only
• Known bad symptoms reviewers should watch for: Gateway not restarting at all (kickstart returns error but mode: "failed" fallback not triggering in run-loop.ts)

Risks and Mitigations

• Risk: triggerOpenClawRestart() could fail silently on edge-case launchd configs
  • Mitigation: Failure returns mode: "failed" with detail string; run-loop.ts already handles this with in-process restart fallback + warning log

🤖 Generated with Claude Code