Greptile Summary

This PR correctly fixes a latent restart failure in the macOS LaunchAgent lifecycle by adding launchctl enable before bootstrap in restartLaunchAgent(), matching the identical guard that already existed in installLaunchAgent(). The root cause (launchd persisting a "disabled" state across bootout) is real and the fix is the right solution.

What's fixed:

• The enable call is inserted at exactly the right point — after waitForPidExit and before bootstrap — consistent with installLaunchAgent.
• The test properly asserts the full bootout → enable → bootstrap → kickstart ordering.

Remaining gap:
The repairLaunchAgentBootstrap function (lines 202–218) calls bootstrap directly without an enable guard, making it vulnerable to the same "disabled state" failure that this PR addresses. Because this is the recovery/repair path, leaving it unguarded could be more harmful than the original restartLaunchAgent bug.

Confidence Score: 3/5

• The fix is correct and safe to merge, but a sibling recovery function has the same gap, leaving a latent bug in the repair path.
• The core PR change is a targeted, correct fix that mirrors an existing pattern. Tests are updated appropriately for the main restart path. However, the repairLaunchAgentBootstrap function has the identical missing enable guard. Since this is the recovery/repair path, hitting this bug there would be more harmful than in the main flow. Score is 3 rather than 4 because this unaddressed gap in a critical recovery function is a meaningful concern.
• The repairLaunchAgentBootstrap function in src/daemon/launchd.ts (lines 202–218) should receive the same enable guard before its bootstrap call to prevent the same class of failure in the recovery path.

_{Last reviewed commit: e6cbd10}

🔒 Aisle Security Analysis

We found 1 potential security issue(s) in this PR:

1. 🔵 Unvalidated OPENCLAW_LAUNCHD_LABEL allows arbitrary launchctl service enable and plist path traversal during restart/repair

Description

resolveLaunchAgentLabel() accepts an override from env.OPENCLAW_LAUNCHD_LABEL with no validation. The new change unconditionally runs launchctl enable using that label before bootstrapping.

Security impact if the caller’s environment is attacker-influenced (e.g., higher-privileged automation invoking this code while inheriting untrusted env):

• Arbitrary service enable: An attacker can set OPENCLAW_LAUNCHD_LABEL to an unintended launchd label, causing launchctl enable gui/<uid>/<label> to run. Because the result is not checked, the function may still proceed/fail later while the enable side-effect remains.
• Arbitrary plist bootstrap path via path traversal/absolute path injection: The same label is used to construct the plist path as .../Library/LaunchAgents/${label}.plist via path.posix.join(...). If label contains /, .., or begins with /, this can resolve outside ~/Library/LaunchAgents/ and cause launchctl bootstrap to attempt to load an arbitrary plist path.

Vulnerable code (new behavior):

const label = resolveLaunchAgentLabel({ env });
const plistPath = resolveLaunchAgentPlistPath(env);
await execLaunchctl(["enable", `${domain}/${label}`]);
const boot = await execLaunchctl(["bootstrap", domain, plistPath]);

Label source + plist path construction:

const envLabel = args?.env?.OPENCLAW_LAUNCHD_LABEL?.trim();
if (envLabel) return envLabel;
...
return path.posix.join(home, "Library", "LaunchAgents", `${label}.plist`);

Recommendation

Treat OPENCLAW_LAUNCHD_LABEL as untrusted input and constrain it to safe, expected values.

1. Validate/allowlist labels before using them in any launchctl operation:

function assertSafeLaunchdLabel(label: string): string {
  ​// Reverse-DNS style, no slashes, no traversal, reasonable charset.
  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,200}$/.test(label)) {
    throw new Error(`Invalid launchd label: ${label}`);
  }
  if (label.includes("/") || label.includes("\\") || label.includes("..")) {
    throw new Error(`Invalid launchd label: ${label}`);
  }
  return label;
}

const label = assertSafeLaunchdLabel(resolveLaunchAgentLabel({ env }));

If overrides are not required in production, remove OPENCLAW_LAUNCHD_LABEL support or restrict it to a fixed allowlist (e.g., ai.openclaw.gateway and ai.openclaw.node).

2. Harden plist path resolution: after building the path, resolve it and ensure it stays under the intended directory.

const launchAgentsDir = path.posix.join(home, "Library", "LaunchAgents");
const plistPath = path.posix.join(launchAgentsDir, `${label}.plist`);
const resolved = path.posix.normalize(plistPath);
if (!resolved.startsWith(`${launchAgentsDir}/`)) {
  throw new Error("Resolved plist path escapes LaunchAgents directory");
}

3. Consider checking the exit code from launchctl enable and failing closed when it errors, to avoid partial side-effects that are hard to reason about.

Analyzed PR: #39237 at commit 5334675

_{Last updated on: 2026-03-09T02:26:04Z}

Addressed the gap flagged by @greptile-apps — pushed a second commit that adds the same enable guard to repairLaunchAgentBootstrap (lines 209-213).

All three LaunchAgent lifecycle paths (install, restart, repair) now consistently call launchctl enable before bootstrap to clear any persisted "disabled" state.

Updated test verifies the enable → bootstrap → kickstart ordering in the repair path as well.

Perfect! The fix looks good. All three LaunchAgent paths now have the same defensive enable call before bootstrap:

1. installLaunchAgent (line 417) ✓
2. restartLaunchAgent (line 471) ✓
3. repairLaunchAgentBootstrap (line 209) ✓

The comments match, and the tests correctly verify the ordering. This completely closes the gap — no more silent bootstrap failures from persisted "disabled" state.

Landed via temp rebase onto main.

• Gate: pnpm check && pnpm build && pnpm test
• Land commit: 43e649d
• Merge commit: 44beb7b

Thanks @scoootscooob!