fix(mac): retry stale launchd bootstrap

BunsDev · BunsDev · commit 2d81aa7e1086 · 2026-05-14T02:33:27.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- macOS/Gateway: retry LaunchAgent bootstrap once after booting out an already-registered launchd job, while keeping headless/sudo installs on the logged-in GUI-session guidance path. Refs #46153 and #48476. Thanks @BunsDev.
 - Security/sandbox: include Windows `USERPROFILE` in the sandbox blocked home roots so credential-bearing binds (such as `.codex`, `.openclaw`, or `.ssh` under the Windows user profile) are denied even when `HOME` points at a different shell home. (#63074) Thanks @luoyanglang.
 - Models config/auth: stop inferring provider env-var markers from broad `^[A-Z_][A-Z0-9_]*$` strings, and resolve config-backed provider `apiKey` values only through structured env SecretRefs (`secrets.providers[id]` / `secrets.defaults`), so unrelated env vars cannot accidentally become provider credentials. Thanks @sallyom.
 - Media fetch: skip allocating and buffering the response body for bodyless media responses (HEAD probes and 204-style empty bodies), avoiding wasted heap on streams that carry no payload. Thanks @shakkernerd.
diff --git a/src/daemon/launchd.test.ts b/src/daemon/launchd.test.ts
@@ -28,6 +28,8 @@ const state = vi.hoisted(() => ({
   printFailuresRemaining: 0,
   bootstrapError: "",
   bootstrapCode: 1,
+  bootstrapFailuresRemaining: Number.POSITIVE_INFINITY,
+  bootstrapResults: [] as Array<{ stderr: string; code: number }>,
   kickstartError: "",
   kickstartCode: 1,
   kickstartFailuresRemaining: 0,
@@ -187,7 +189,12 @@ vi.mock("./exec-file.js", () => ({
       return { stdout: "", stderr: "", code: 0 };
     }
     if (call[0] === "bootstrap") {
-      if (state.bootstrapError) {
+      const queued = state.bootstrapResults.shift();
+      if (queued) {
+        return { stdout: "", stderr: queued.stderr, code: queued.code };
+      }
+      if (state.bootstrapError && state.bootstrapFailuresRemaining > 0) {
+        state.bootstrapFailuresRemaining -= 1;
         return { stdout: "", stderr: state.bootstrapError, code: state.bootstrapCode };
       }
       state.serviceLoaded = true;
@@ -288,6 +295,8 @@ beforeEach(() => {
   state.printFailuresRemaining = 0;
   state.bootstrapError = "";
   state.bootstrapCode = 1;
+  state.bootstrapFailuresRemaining = Number.POSITIVE_INFINITY;
+  state.bootstrapResults.length = 0;
   state.kickstartError = "";
   state.kickstartCode = 1;
   state.kickstartFailuresRemaining = 0;
@@ -511,6 +520,46 @@ describe("launchd install", () => {
     expect(installKickstartIndex).toBe(-1);
   });
 
+  it("retries bootstrap once after booting out an already-registered LaunchAgent", async () => {
+    const env = createDefaultLaunchdEnv();
+    state.bootstrapError =
+      "Could not bootstrap service: 5: Input/output error: already exists in domain for gui/501";
+    state.bootstrapCode = 5;
+    state.bootstrapFailuresRemaining = 1;
+
+    await installLaunchAgent({
+      env,
+      stdout: new PassThrough(),
+      programArguments: defaultProgramArguments,
+    });
+
+    const { domain, serviceId } = expectLaunchctlEnableBootstrapOrder(env);
+    const plistPath = resolveLaunchAgentPlistPath(env);
+    expect(state.launchctlCalls).toContainEqual(["bootout", domain, plistPath]);
+    expect(state.launchctlCalls).toContainEqual(["bootout", serviceId]);
+    expect(countMatching(state.launchctlCalls, (call) => call[0] === "bootstrap")).toBe(2);
+  });
+
+  it("reports the retry bootstrap error when already-registered recovery fails differently", async () => {
+    const env = createDefaultLaunchdEnv();
+    state.bootstrapResults.push(
+      {
+        stderr:
+          "Could not bootstrap service: 5: Input/output error: already exists in domain for gui/501",
+        code: 5,
+      },
+      { stderr: "Bootstrap failed: 125: Domain does not support specified action", code: 125 },
+    );
+
+    await expect(
+      installLaunchAgent({
+        env,
+        stdout: new PassThrough(),
+        programArguments: defaultProgramArguments,
+      }),
+    ).rejects.toThrow("launchctl bootstrap failed: Bootstrap failed: 125");
+  });
+
   it("writes LaunchAgent environment to an owner-only env file when provided", async () => {
     const env = createDefaultLaunchdEnv();
     const tmpDir = "/Users/test/.openclaw/tmp";
diff --git a/src/daemon/launchd.ts b/src/daemon/launchd.ts
@@ -315,6 +315,25 @@ async function bootstrapLaunchAgentOrThrow(params: {
       actionHint: params.actionHint,
     });
   }
+  if (isAlreadyBootstrappedDetail(detail, boot.code)) {
+    const bootout = await execLaunchctl(["bootout", params.serviceTarget]);
+    if (bootout.code !== 0 && !isLaunchctlNotLoaded(bootout)) {
+      throw new Error(`launchctl bootout failed: ${formatLaunchctlResultDetail(bootout)}`);
+    }
+    const retry = await execLaunchctl(["bootstrap", params.domain, params.plistPath]);
+    if (retry.code === 0) {
+      return;
+    }
+    const retryDetail = (retry.stderr || retry.stdout).trim();
+    if (isUnsupportedGuiDomain(retryDetail)) {
+      throwBootstrapGuiSessionError({
+        detail: retryDetail,
+        domain: params.domain,
+        actionHint: params.actionHint,
+      });
+    }
+    throw new Error(`launchctl bootstrap failed: ${retryDetail}`);
+  }
   throw new Error(`launchctl bootstrap failed: ${detail}`);
 }
 
@@ -529,6 +548,16 @@ function isUnsupportedGuiDomain(detail: string): boolean {
   );
 }
 
+function isAlreadyBootstrappedDetail(detail: string, code?: number): boolean {
+  const normalized = normalizeLowercaseStringOrEmpty(detail);
+  return (
+    normalized.includes("already bootstrapped") ||
+    normalized.includes("already loaded") ||
+    normalized.includes("already exists in domain") ||
+    (code === 5 && normalized.includes("input/output error"))
+  );
+}
+
 function formatLaunchctlResultDetail(res: {
   stdout: string;
   stderr: string;
