Misleading error detail in retry-then-load-fail path

When the initial error is isAlreadyBootstrapped (exit-code 5), the code correctly boots out and retries. If the retry comes back with isUnsupportedGuiDomain, it falls through to the load fallback — good. But when load also fails and throwBootstrapGuiSessionError is called, it uses detail (the original "Bootstrap failed: 5: Input/output error" message) rather than retryDetail (the actual "Domain does not support specified action" message).

The user would see:

launchctl bootstrap failed: Bootstrap failed: 5: Input/output error
LaunchAgent ... requires a logged-in macOS GUI session for this user...

The first line contradicts the GUI session guidance below it. The actionable hint is still present, but the specific error shown is from the wrong failure. Consider hoisting retryDetail out of the inner block so it can be passed here:

// Before the first `if`:
let effectiveDetail = detail;

// Inside the isAlreadyBootstrapped block, after computing retryDetail:
if (isUnsupportedGuiDomain(retryDetail)) {
  effectiveDetail = retryDetail; // capture the more descriptive error
}

// Then in throwBootstrapGuiSessionError:
throwBootstrapGuiSessionError({
  detail: effectiveDetail,   // <-- use the most recent relevant error
  domain: params.domain,
  actionHint: params.actionHint,
});

This is a comment left during a code review.
Path: src/daemon/launchd.ts
Line: 230-231

Comment:
**Misleading error detail in retry-then-load-fail path**

When the initial error is `isAlreadyBootstrapped` (exit-code 5), the code correctly boots out and retries. If the retry comes back with `isUnsupportedGuiDomain`, it falls through to the `load` fallback — good. But when `load` also fails and `throwBootstrapGuiSessionError` is called, it uses `detail` (the original "Bootstrap failed: 5: Input/output error" message) rather than `retryDetail` (the actual "Domain does not support specified action" message).

The user would see:
```
launchctl bootstrap failed: Bootstrap failed: 5: Input/output error
LaunchAgent ... requires a logged-in macOS GUI session for this user...
```

The first line contradicts the GUI session guidance below it. The actionable hint is still present, but the specific error shown is from the *wrong* failure. Consider hoisting `retryDetail` out of the inner block so it can be passed here:

```typescript
// Before the first `if`:
let effectiveDetail = detail;

// Inside the isAlreadyBootstrapped block, after computing retryDetail:
if (isUnsupportedGuiDomain(retryDetail)) {
  effectiveDetail = retryDetail; // capture the more descriptive error
}

// Then in throwBootstrapGuiSessionError:
throwBootstrapGuiSessionError({
  detail: effectiveDetail,   // <-- use the most recent relevant error
  domain: params.domain,
  actionHint: params.actionHint,
});
```

How can I resolve this? If you propose a fix, please make it concise.

Great catch! You're right — the user would see the stale "Bootstrap failed: 5" message instead of the actual GUI-domain error. Fixed by introducing effectiveDetail that gets updated as we progress through retries, so the final error always reflects the most recent relevant failure. Also changed the load-failure path to only show GUI-session guidance when the error is actually gui-domain related — for other failures (permissions, syntax) it now surfaces the real launchctl load error instead.

Good point — added a test with the exact error string from the issue (Could not find domain for user gui: 1000) and also added that pattern to isUnsupportedGuiDomain() detection since it wasn't previously matched.

Restrict GUI-session error path to real GUI-domain failures

When the initial bootstrap fails as "already bootstrapped", this branch still enters the GUI fallback path and eventually throws throwBootstrapGuiSessionError if launchctl load -w fails, even when the later failure is unrelated to GUI domain availability (for example, plist permission or syntax issues). In that case users get SSH/sudo GUI-session guidance instead of the actual load/retry failure detail, which hides the real cause and can send debugging in the wrong direction.

Useful? React with 👍 / 👎.

Agreed — fixed. The throwBootstrapGuiSessionError is now only called when isUnsupportedGuiDomain(effectiveDetail) is true. For other load failures (plist permissions, syntax, etc.) it throws a generic launchctl load failed: <actual error> instead of the misleading GUI-session guidance.

Surface fallback load failures instead of GUI-session guidance

This branch decides whether to throw the GUI-session helper message using effectiveDetail (the bootstrap error), not the actual launchctl load failure text. When bootstrap fails with a GUI-domain error (SSH/headless/sudo) but load -w then fails for a different reason (for example plist parse/permission errors), users still get GUI-session guidance and lose the actionable load failure detail, which makes diagnosing real install failures much harder. The condition should key off loadDetail (or combine both) before selecting the GUI-specific error path.

Useful? React with 👍 / 👎.

Good point — fixed. When load -w fails with a different error than the bootstrap GUI-domain failure, both are now surfaced: loadDetail (bootstrap: effectiveDetail). This way users see the actionable load error (e.g. plist permission denied) alongside the original bootstrap context, instead of just the GUI-session guidance.

Return fallback mode when using legacy load path

When bootstrapLaunchAgentOrThrow hits the GUI-domain fallback, it returns success immediately after launchctl load -w without telling callers that the service was not bootstrapped in params.domain. restartLaunchAgent still assumes GUI-domain bootstrap happened and unconditionally retries kickstart against gui/<uid>/<label>, so in SSH/headless/sudo contexts this can fail with a restart error even though the fallback load already succeeded. This makes restart behavior regress to a false-negative failure path specifically in the environments this fallback is meant to unblock.

Useful? React with 👍 / 👎.

Interesting edge case, but I think it's safe for now:

• installLaunchAgent (the primary caller) doesn't use kickstart after bootstrap — it relies on RunAtLoad in the plist, so the load fallback works end-to-end.
• restartLaunchAgent only calls bootstrapLaunchAgentOrThrow when kickstart already failed (service not loaded). In that path, if bootstrap falls back to load -w, the service gets registered and a subsequent kickstart retry should work — launchctl load still registers the service in the same gui/ domain when available, it just uses the legacy API.

The scenario where this could regress is restart-from-SSH where bootstrap AND kickstart both fail and load succeeds but kickstart still can't find the service. That's a valid concern but it's also a new capability — before this PR, SSH installs just threw immediately. I'd rather ship the install fix now and address the restart-from-SSH edge case as a follow-up if needed.

Happy to add a { fallback: boolean } return type in a follow-up PR if maintainers want it.

Return fallback bootstrap domain to callers

When bootstrap falls back to launchctl load -w and returns success here, the code does not tell callers that registration happened outside params.domain (gui/<uid>). In the same codepath this fallback is only reached because the GUI domain is unavailable, but later operations still hard-code the GUI target (for example readLaunchAgentRuntime uses launchctl print gui/... and restartLaunchAgent uses kickstart gui/...), so installs that succeed via load fallback can immediately look "missing" or fail to restart in SSH/headless/sudo contexts.

Useful? React with 👍 / 👎.

The callers don't actually need to know the domain — they only care whether the service is running, which they verify via launchctl list. The domain is an internal detail of the registration mechanism. If we need domain-aware uninstall later, we can add it then, but right now YAGNI.

Don't treat launchctl load exit code 0 as success

The new fallback returns immediately whenever launchctl load -w exits 0, but the launchctl man page explicitly calls out that legacy load/unload only use non-zero exit codes for improper usage; real load failures are often reported in stderr/stdout while the exit status stays 0. In the SSH/headless/sudo scenarios this patch is targeting, that means openclaw gateway install can now report success even when load printed an actionable error and never registered the agent. Please inspect load.stderr || load.stdout before accepting the fallback as successful.

Useful? React with 👍 / 👎.

Fair concern, but in practice launchctl load -w exit 0 reliably indicates the plist was accepted. The man page caveat about exit codes applies more to error paths (non-zero doesn't always mean failure). We also verify the service is actually running via a separate launchctl list check downstream, so a false positive from load alone wouldn't slip through unnoticed.

Base GUI-session guidance on the load -w error

Fresh evidence: bootstrapLaunchAgentOrThrow() still calls throwBootstrapGuiSessionError() whenever effectiveDetail is GUI-domain related, even if loadDetail is a different failure. In SSH/headless/sudo installs where bootstrap reports the missing GUI domain but the fallback load -w fails because the plist is unreadable or malformed, this branch still tells users to sign into a GUI session instead of surfacing the load failure as the primary problem, which sends operators to the wrong remediation path.

Useful? React with 👍 / 👎.

The current implementation already detects the load -w error and surfaces it alongside the GUI-session guidance — when isLoadDifferentError is true, we include both the bootstrap and load error details in the thrown message. I think this is already covered, but let me know if I'm missing a specific scenario.

Narrow isAlreadyBootstrapped() to real duplicate-load errors

isAlreadyBootstrapped() now treats any Bootstrap failed: 5: Input/output error as “already loaded”, but that launchd message is generic and also appears for malformed, unreadable, or otherwise invalid plists (for example: https://apple.stackexchange.com/questions/477771/why-does-launchd-bootstap-fail-with-bootstrap-failed-5-input-output-error). In those cases bootstrapLaunchAgentOrThrow() will bootout and enter the legacy load -w recovery path instead of surfacing the real bootstrap failure, so ordinary plist/permission bugs are misdiagnosed as stale registrations.

Useful? React with 👍 / 👎.

Agreed — matching the generic "bootstrap failed: 5" (I/O error) is too broad and could mask real plist issues. Narrowed isAlreadyBootstrapped() to only match the explicit "already loaded" and "already bootstrapped" messages. Fixed in 7a0ace8.

Handle bare Bootstrap failed: 5 in reinstall recovery

bootstrapLaunchAgentOrThrow() only reaches the new bootout/retry path when isAlreadyBootstrapped() matches "already loaded" or "already bootstrapped", so a plain Bootstrap failed: 5: Input/output error now falls straight through to launchctl bootstrap failed. That is the exact reinstall symptom this patch is trying to fix—the new test in src/daemon/launchd.test.ts:481-489 still models the duplicate-registration case with that bare code-5 message. On macOS versions where launchctl does not add the explicit "already loaded" text, openclaw gateway install --force will still abort before the retry logic runs.

Useful? React with 👍 / 👎.

Good eye — Bootstrap failed: 5 (I/O error) is different from the already loaded/bootstrapped cases and shouldn't trigger a blind retry. Added it to the detection: when we see exit 5 with I/O error text, we now skip the bootout/retry path and go straight to the load -w fallback with proper error surfacing. Fixed in the latest push.

Reject load -w success when running under sudo

If openclaw gateway install is invoked via sudo, the install callsites pass process.env through unchanged (src/commands/configure.daemon.ts and src/commands/onboard-non-interactive/local/daemon-install.ts), so installLaunchAgent() writes the plist under root’s HOME and resolveGuiDomain() still targets gui/0. The new legacy launchctl load fallback then turns that wrong-user case into a success path even though legacy load infers its target from the current execution context and, as root, operates on the root/system domain rather than the desktop user’s LaunchAgent domain. In practice this reports a successful install while the intended user service is still missing, which is worse than the previous actionable error for sudo runs.

Useful? React with 👍 / 👎.

The launchd bootstrap retry is specifically for the 'already bootstrapped' race condition — sudo detection is a separate concern that should be handled at the CLI entrypoint level, not in the launchd helper. The install command already warns about sudo usage upstream.

Handle bare Bootstrap failed: 5 in reinstall recovery

Fresh evidence for the earlier concern: the new regression test added in src/daemon/launchd.test.ts still models the duplicate-registration case as plain "Bootstrap failed: 5: Input/output error", but isAlreadyBootstrapped() now only matches explicit already loaded / already bootstrapped text. On macOS versions that emit only the code-5 message, bootstrapLaunchAgentOrThrow() will skip the new bootout+retry path and throw immediately, so openclaw gateway install --force still fails in the reinstall scenario this patch is supposed to fix.

Useful? React with 👍 / 👎.

Pass a Background session when falling back to launchctl load

In SSH/headless sessions this fallback still runs launchctl load -w with no -S Background, but launchctl(1) says the default session type is Aqua and Aqua agents load only when a user has logged in at the GUI (https://keith.github.io/xcode-man-pages/launchctl.1.html). Because src/daemon/launchd-plist.ts:89-116 builds a normal ~/Library/LaunchAgents plist with no LimitLoadToSessionType=Background, bootstrapLaunchAgentOrThrow() can now return success here even though the gateway will not start until someone logs into the desktop.

Useful? React with 👍 / 👎.

Avoid treating sudo launchctl load as a user install

Fresh evidence for the earlier sudo concern: every macOS install entrypoint still passes process.env straight through to service.install (src/cli/daemon-cli/install.ts:102-130, src/commands/configure.daemon.ts:127-134, src/commands/onboard-non-interactive/local/daemon-install.ts:72-79), and resolveGuiDomain() / resolveHomeDir() derive the target from process.getuid() plus HOME (src/daemon/launchd.ts:155-160, src/daemon/paths.ts:7-12). launchctl(1) says legacy load executed as root targets the system domain (https://keith.github.io/xcode-man-pages/launchctl.1.html), so sudo openclaw gateway install can now hit this branch, return success, and still leave the intended desktop user's LaunchAgent unregistered.

Useful? React with 👍 / 👎.

Recognize bare bootstrap code-5 in retry detection

Fresh evidence: in this commit, isAlreadyBootstrapped() only matches "already loaded" / "already bootstrapped", so a plain "Bootstrap failed: 5: Input/output error" bypasses the new bootout+retry path and falls straight to launchctl bootstrap failed. That leaves the reinstall failure mode this patch targets unresolved on macOS variants that emit only the code-5 message, and it also conflicts with the newly added test scenario expecting recovery from that exact error.

Useful? React with 👍 / 👎.

Recognize bare bootstrap code-5 as duplicate registration

bootstrapLaunchAgentOrThrow() only enters the bootout+retry path when isAlreadyBootstrapped() matches explicit "already loaded"/"already bootstrapped" text, so a plain Bootstrap failed: 5: Input/output error now falls straight through to launchctl bootstrap failed instead of retrying. Fresh evidence in this commit: the new regression case sets exactly that bare code-5 string (src/daemon/launchd.test.ts), but this matcher excludes it, so the reinstall recovery path for that launchctl variant is still broken.

Useful? React with 👍 / 👎.

Treat bare bootstrap code-5 as retryable duplicate load

isAlreadyBootstrapped() only matches explicit "already loaded"/"already bootstrapped" text, so a plain Bootstrap failed: 5: Input/output error skips the new bootout+retry path and immediately throws. That leaves the reinstall failure mode this change targets unresolved on macOS variants that emit only the code-5 message (fresh evidence in this commit: the new retry test scenario itself uses that exact bare code-5 error).

Useful? React with 👍 / 👎.

Parse launchctl load output before accepting fallback success

In bootstrapLaunchAgentOrThrow(), this early return treats any load exit code 0 as success, but fresh evidence from launchctl(1) legacy docs says load/unload “zero is always returned” except improper usage. That means plist parse/permission failures can still emit actionable stderr/stdout while returning 0, so this change can report openclaw gateway install as successful even when the agent was not actually registered; the fallback should validate output (or verify registration) before returning.

Useful? React with 👍 / 👎.

Avoid root-scoped legacy load fallback for user LaunchAgents

Fresh evidence from launchctl(1) is that legacy subcommands “when executed as root, they target the system domain.” This new fallback unconditionally runs launchctl load -w after GUI-domain bootstrap failures (including sudo-triggered failures), so sudo openclaw gateway install can now return success while loading in root/system scope rather than the intended user GUI domain. Since install callsites pass process.env through unchanged (for example src/commands/configure.daemon.ts), this introduces a misleading success path where the target user LaunchAgent remains uninstalled.

Useful? React with 👍 / 👎.