Fixes #87199

Summary

• Problem: macOS LaunchAgent plists with service environment entries made the generated env-wrapper script the executable that launchd spawned; on permission-constrained home/state volumes that can fail at posix_spawn before the gateway starts.
• Solution: Generate shell-first LaunchAgent ProgramArguments (/bin/sh, wrapper path, env file path, then the gateway command) and keep legacy wrapper-first plists readable/rewriteable.
• What changed: src/daemon/launchd.ts, src/daemon/launchd-plist.ts, and src/daemon/launchd.test.ts now share the shell-first env-wrapper contract.
• What did NOT change: Service environment values still live in the owner-only generated env file, not in the plist; gateway CLI command construction remains the existing supported gateway --port <port> run path.

Real behavior proof

• Behavior or issue addressed: A generated macOS LaunchAgent must no longer directly spawn the generated env-wrapper from the user's home/state volume. The LaunchAgent should bootstrap and kickstart under macOS launchd, load the env file, start the gateway, and answer gateway health/status without Permission denied, EX_CONFIG, or posix_spawn failure.

• Real environment tested: macOS Darwin 25.5.0 arm64, Node v24.15.0, OpenClaw 2026.6.2 from PR worktree SHA e977dc1fc177. The proof used a temporary HOME/OPENCLAW_HOME/OPENCLAW_STATE_DIR and unique label ai.openclaw.launchd-proof-fa9d9c1f, then changed the generated wrapper mode from 0700 to 0600 before launchctl bootstrap to exercise the direct-wrapper-spawn permission surface.

• Exact steps or command run after this patch:

  PROOF_REPO=/Users/zhangguiping/daily_pr_work/openclaw-87199-proof \
  PROOF_PORT=19532 \
  PROOF_PRINT_CLEANUP=1 \
    node --import tsx /Users/zhangguiping/daily_pr_work/proofs/openclaw-issue-87199-evidence/macos-launchd-live-proof.mjs \
      > /Users/zhangguiping/daily_pr_work/proofs/openclaw-issue-87199-evidence/macos-launchd-live-proof-2.out \
      2> /Users/zhangguiping/daily_pr_work/proofs/openclaw-issue-87199-evidence/macos-launchd-live-proof-2.err
  
  launchctl bootout gui/501/ai.openclaw.launchd-proof-fa9d9c1f
  launchctl bootstrap gui/501 /var/folders/76/w5rbbmt53d9f9wzqs3kzq3580000gn/T/openclaw-launchd-proof-fa9d9c1f-As3pt8/Library/LaunchAgents/ai.openclaw.launchd-proof-fa9d9c1f.plist
  launchctl enable gui/501/ai.openclaw.launchd-proof-fa9d9c1f
  launchctl kickstart -k gui/501/ai.openclaw.launchd-proof-fa9d9c1f
  launchctl print gui/501/ai.openclaw.launchd-proof-fa9d9c1f
  node --import tsx src/entry.ts gateway call health --json --url ws://127.0.0.1:19532 --token <redacted> --timeout 5000
  node --import tsx src/entry.ts gateway status --json --url ws://127.0.0.1:19532 --token <redacted>
  launchctl bootout gui/501/ai.openclaw.launchd-proof-fa9d9c1f
  
  node scripts/run-vitest.mjs src/daemon/launchd.test.ts src/daemon/program-args.test.ts src/commands/daemon-install-helpers.test.ts
  pnpm format:check src/daemon/launchd.ts src/daemon/launchd-plist.ts src/daemon/launchd.test.ts
  node scripts/run-oxlint.mjs src/daemon/launchd.ts src/daemon/launchd-plist.ts src/daemon/launchd.test.ts
  git diff --check

• Evidence after fix: Live macOS launchd proof output from macos-launchd-live-proof-2.out:

  {
    "platform": "Darwin 25.5.0",
    "arch": "arm64",
    "node": "v24.15.0",
    "head": "e977dc1fc177",
    "label": "ai.openclaw.launchd-proof-fa9d9c1f",
    "serviceTarget": "gui/501/ai.openclaw.launchd-proof-fa9d9c1f",
    "port": 19532,
    "programArguments": [
      "/bin/sh",
      "/var/folders/.../.openclaw-state/service-env/ai.openclaw.launchd-proof-fa9d9c1f-env-wrapper.sh",
      "/var/folders/.../.openclaw-state/service-env/ai.openclaw.launchd-proof-fa9d9c1f.env",
      "/Users/zhangguiping/.nvm/versions/node/v24.15.0/bin/node",
      "--import",
      "tsx",
      "/Users/zhangguiping/daily_pr_work/openclaw-87199-proof/src/entry.ts",
      "gateway",
      "--port",
      "19532",
      "--allow-unconfigured"
    ],
    "plistExecutable": "/bin/sh",
    "secretInPlist": false,
    "envFileExists": true,
    "envFileContainsToken": true,
    "wrapperModeBefore": "0700",
    "wrapperModeAfter": "0600",
    "bootstrap": { "code": 0 },
    "enable": { "code": 0 },
    "kickstart": { "code": 0 },
    "runtime": { "status": "running", "state": "active", "pid": 85513, "cachedLabel": false },
    "gatewayHealth": { "code": 0, "stdout": { "ok": true } },
    "gatewayStatus": { "code": 0, "rpc": { "ok": true } },
    "gatewayStatusRpcOk": true,
    "noPermissionDenied": true
  }

  launchctl print gui/501/ai.openclaw.launchd-proof-fa9d9c1f showed the real service running from /bin/sh:

  state = running
  program = /bin/sh
  arguments = {
    /bin/sh
    /var/folders/.../.openclaw-state/service-env/ai.openclaw.launchd-proof-fa9d9c1f-env-wrapper.sh
    /var/folders/.../.openclaw-state/service-env/ai.openclaw.launchd-proof-fa9d9c1f.env
    /Users/zhangguiping/.nvm/versions/node/v24.15.0/bin/node
    --import
    tsx
    /Users/zhangguiping/daily_pr_work/openclaw-87199-proof/src/entry.ts
    gateway
    --port
    19532
    --allow-unconfigured
  }
  working directory = /Users/zhangguiping/daily_pr_work/openclaw-87199-proof
  pid = 85513
  

  Gateway RPC proof from the launchd-started process:

  gateway call health: code=0, ok=true, durationMs=43
  gateway status: code=0, service.runtime.status=running, service.runtime.state=active, rpc.ok=true, port.listeners[0].pid=85513, ppid=1
  launchd stdout tail: [gateway] ready; [heartbeat] started; [ws] ⇄ res ✓ health 50ms cached=true
  cleanup: launchctl bootout gui/501/ai.openclaw.launchd-proof-fa9d9c1f code=0
  

• Observed result after fix: macOS launchd successfully bootstrapped and kickstarted the generated LaunchAgent even after the generated wrapper was made non-executable (0600). The service ran as /bin/sh, loaded environment values from the generated env file, started the gateway on port 19532, and gateway call health plus gateway status both succeeded against the launchd-owned process. The live proof also confirms secrets stayed out of the plist (secretInPlist=false) while the env file contained the token (envFileContainsToken=true). The gateway command remains the existing supported gateway --port <port> form; this PR does not change it to a literal gateway run subcommand, and the launchd health/status proof shows that command starts the gateway correctly.

• What was not tested: I did not mount a separate external home volume. Instead, the proof used a temporary macOS HOME/state directory and changed the generated wrapper to 0600 before launchd bootstrap to cover the same direct-spawn permission failure surface that this patch removes. No other known gaps.

• Fix classification: Root cause fix.

Review findings addressed

• The LaunchAgent proof now runs on macOS with real launchctl bootstrap, launchctl kickstart, launchctl print, gateway call health, and gateway status against the generated service.
• The proof verifies the raw plist shape launchd consumes, confirms /bin/sh is the program launchd starts, confirms owner-only env-file loading, and confirms there is no Permission denied, EX_CONFIG, or posix_spawn failure in the launchd-started gateway path.

Regression Test Plan

• Coverage level: Unit test plus live macOS launchd proof.
• Target test file: src/daemon/launchd.test.ts.
• Scenario locked in: A LaunchAgent with service environment entries serializes raw ProgramArguments as /bin/sh, generated wrapper path, generated env file path, then the original gateway command; an old wrapper-first plist reads back and restart-rewrites into that same shell-first shape.
• Why this is the smallest reliable guardrail: The unit regression sits at the plist writer/readback boundary that launchd consumes, while the live proof exercises the macOS launchd runtime path without mocking launchd.
• src/daemon/program-args.test.ts remains green to confirm the existing gateway --port <port> command form is unchanged.
• src/commands/daemon-install-helpers.test.ts remains green to confirm service env planning still passes wrapper/env values through correctly.

Root Cause

• Root cause: When service environment entries existed, LaunchAgent generation wrote ProgramArguments as [wrapperPath, envFilePath, ...gatewayCommand]. On macOS setups where the generated wrapper lives on a permission-constrained home/state volume, launchd could fail at posix_spawn before the wrapper loaded the env file or execed the gateway. Status/readback code normalized the command for display, which hid the raw plist shape that launchd actually executes.
• Missing detection / guardrail: Tests asserted normalized program arguments but did not assert the raw generated plist array, and the earlier proof did not run real macOS launchctl bootstrap/kickstart against the generated LaunchAgent.

Merge risk

• Why it matters / User impact: Affected macOS users with service env entries, especially external-home setups, can get an immediately exiting gateway LaunchAgent. This keeps the gateway unavailable after install/restart.
• What did NOT change: This only changes macOS LaunchAgent env-wrapper serialization/readback; it does not change gateway CLI command construction, service env collection, provider auth, plist inline EnvironmentVariables, Linux/Windows service behavior, or the gateway --port <port> command shape.
• Architecture / source-of-truth check: The source-of-truth boundary is prepareLaunchAgentProgramArguments plus readLaunchAgentProgramArgumentsFromFile; generation and restart repair now share the same canonical shell-first wrapper contract while legacy wrapper-first plists are normalized only during read/rewrite.
• Risk labels considered: merge-risk:platform, merge-risk:compatibility.
• Risk explanation: The change affects macOS LaunchAgent plist generation and legacy plist rewrite behavior. It does not change gateway CLI command construction or embed env values into the plist.
• Why acceptable: The patch is limited to the launchd env-wrapper boundary, keeps old wrapper-first plists readable, preserves owner-only env-file loading, and now has focused tests plus a live macOS launchd proof for the generated command shape.
• Maintainer-ready confidence: High for the LaunchAgent env-wrapper root cause. The only remaining scope note is intentional: the gateway command remains the existing supported gateway --port <port> run path rather than changing CLI command construction in this PR.
• Patch quality notes: Minimal root-cause change at the LaunchAgent generation/readback source of truth; no fallback, retry, timeout, or status-only workaround.