fix(mac): surface stale updater launchd jobs

steipete · steipete · commit 7acbb2260c4a · 2026-05-15T08:20:55.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -36,6 +36,7 @@ Docs: https://docs.openclaw.ai
 - Control UI: rotate browser service-worker caches per build so updated Gateways are less likely to keep serving stale dashboard bundles that trigger protocol mismatch errors.
 - Control UI/WebChat: let sidebar markdown code-block Copy buttons use the same delegated clipboard handler as chat messages. (#58709) Thanks @tikitoki.
 - Discord/streaming: only mark partial draft previews delivered after final edit or fallback delivery succeeds, so failed finalization cleanup removes stale truncated drafts instead of leaving them as the visible reply. Fixes #82035. Thanks @compoodment.
+- macOS/Gateway: surface leftover `ai.openclaw.update.*` launchd updater jobs in `openclaw gateway status --deep` and doctor so post-update launchd loops point at the stale job cleanup. Fixes #81859. Thanks @BKF-Gitty.
 - Config/doctor: rotate capped `.clobbered.*` repair snapshots by artifact timestamp so repeated repairs keep the newest forensic copy instead of preserving only the first capped set. (#82012) Thanks @Kaspre.
 - Telegram: initialize the bot before isolated polling drains spooled updates so default isolated polling no longer retries every update with `Bot not initialized` and stalls replies. Fixes #81973. (#81975) Thanks @neeravmakwana.
 - Telegram: apply method-aware Bot API request timeouts to direct message/action clients so `openclaw message delete --channel telegram` no longer waits on grammY's 500-second default when the API request wedges. Fixes #81908. Thanks @DashLabsDev.
diff --git a/src/cli/daemon-cli/status.gather.test.ts b/src/cli/daemon-cli/status.gather.test.ts
@@ -28,6 +28,7 @@ const loadGatewayTlsRuntime = vi.fn(async (_cfg?: unknown) => ({
   fingerprintSha256: "sha256:11:22:33:44",
 }));
 const findExtraGatewayServices = vi.fn(async (_env?: unknown, _opts?: unknown) => []);
+const findStaleOpenClawUpdateLaunchdJobs = vi.fn(async () => []);
 const inspectPortUsage = vi.fn(async (port: number) => ({
   port,
   status: "free" as const,
@@ -139,6 +140,10 @@ vi.mock("../../daemon/inspect.js", () => ({
   findExtraGatewayServices: (env: unknown, opts?: unknown) => findExtraGatewayServices(env, opts),
 }));
 
+vi.mock("../../daemon/launchd.js", () => ({
+  findStaleOpenClawUpdateLaunchdJobs: () => findStaleOpenClawUpdateLaunchdJobs(),
+}));
+
 vi.mock("../../daemon/service-audit.js", () => ({
   auditGatewayServiceConfig: (opts: unknown) => auditGatewayServiceConfig(opts),
 }));
@@ -210,6 +215,8 @@ describe("gatherDaemonStatus", () => {
     delete process.env.DAEMON_GATEWAY_PASSWORD;
     callGatewayStatusProbe.mockClear();
     createConfigIOCalls.mockClear();
+    findStaleOpenClawUpdateLaunchdJobs.mockReset();
+    findStaleOpenClawUpdateLaunchdJobs.mockResolvedValue([]);
     loadGatewayTlsRuntime.mockClear();
     inspectGatewayRestart.mockClear();
     readGatewayRestartHandoffSync.mockClear();
@@ -440,6 +447,31 @@ describe("gatherDaemonStatus", () => {
     expect(status.service.restartHandoff?.supervisorMode).toBe("launchd");
   });
 
+  it.runIf(process.platform === "darwin")(
+    "surfaces stale updater launchd jobs only during deep status",
+    async () => {
+      findStaleOpenClawUpdateLaunchdJobs.mockResolvedValueOnce([
+        {
+          label: "ai.openclaw.update.2026.5.12",
+          lastExitStatus: 127,
+        },
+      ]);
+
+      const status = await gatherDaemonStatus({
+        rpc: {},
+        probe: false,
+        deep: true,
+      });
+
+      expect(status.service.staleUpdateLaunchdJobs).toEqual([
+        {
+          label: "ai.openclaw.update.2026.5.12",
+          lastExitStatus: 127,
+        },
+      ]);
+    },
+  );
+
   it("does not read restart handoffs during normal status", async () => {
     await gatherDaemonStatus({
       rpc: {},
@@ -448,6 +480,7 @@ describe("gatherDaemonStatus", () => {
     });
 
     expect(readGatewayRestartHandoffSync).not.toHaveBeenCalled();
+    expect(findStaleOpenClawUpdateLaunchdJobs).not.toHaveBeenCalled();
   });
 
   it("uses the fast config path for plain same-file status reads", async () => {
diff --git a/src/cli/daemon-cli/status.gather.ts b/src/cli/daemon-cli/status.gather.ts
@@ -14,6 +14,7 @@ import type {
 } from "../../config/types.js";
 import { readLastGatewayErrorLine } from "../../daemon/diagnostics.js";
 import type { FindExtraGatewayServicesOptions } from "../../daemon/inspect.js";
+import type { StaleOpenClawUpdateLaunchdJob } from "../../daemon/launchd.js";
 import type { ServiceConfigAudit } from "../../daemon/service-audit.js";
 import type { GatewayServiceRuntime } from "../../daemon/service-runtime.js";
 import { resolveGatewayService } from "../../daemon/service.js";
@@ -97,6 +98,7 @@ const gatewayProbeAuthModuleLoader = createLazyImportLoader(
   () => import("../../gateway/probe-auth.js"),
 );
 const daemonInspectModuleLoader = createLazyImportLoader(() => import("../../daemon/inspect.js"));
+const launchdModuleLoader = createLazyImportLoader(() => import("../../daemon/launchd.js"));
 const serviceAuditModuleLoader = createLazyImportLoader(
   () => import("../../daemon/service-audit.js"),
 );
@@ -112,6 +114,10 @@ function loadDaemonInspectModule() {
   return daemonInspectModuleLoader.load();
 }
 
+function loadLaunchdModule() {
+  return launchdModuleLoader.load();
+}
+
 function loadServiceAuditModule() {
   return serviceAuditModuleLoader.load();
 }
@@ -268,6 +274,7 @@ export type DaemonStatus = {
     runtime?: GatewayServiceRuntime;
     configAudit?: ServiceConfigAudit;
     restartHandoff?: GatewayRestartHandoff;
+    staleUpdateLaunchdJobs?: StaleOpenClawUpdateLaunchdJob[];
   };
   config?: {
     cli: ConfigSummary;
@@ -511,6 +518,12 @@ export async function gatherDaemonStatus(
         )
         .catch(() => [])
     : [];
+  const staleUpdateLaunchdJobs =
+    opts.deep && process.platform === "darwin"
+      ? await loadLaunchdModule()
+          .then(({ findStaleOpenClawUpdateLaunchdJobs }) => findStaleOpenClawUpdateLaunchdJobs())
+          .catch(() => [])
+      : [];
 
   const timeoutMs =
     parseStrictPositiveInteger(opts.rpc.timeout ?? undefined) ??
@@ -595,6 +608,7 @@ export async function gatherDaemonStatus(
       runtime,
       configAudit,
       ...(restartHandoff ? { restartHandoff } : {}),
+      ...(staleUpdateLaunchdJobs.length > 0 ? { staleUpdateLaunchdJobs } : {}),
     },
     config: {
       cli: cliConfigSummary,
diff --git a/src/cli/daemon-cli/status.print.test.ts b/src/cli/daemon-cli/status.print.test.ts
@@ -126,6 +126,40 @@ describe("printDaemonStatus", () => {
     expectMockLineContains(runtime.error, formatCliCommand("openclaw gateway restart"));
   });
 
+  it("prints stale updater launchd job guidance", () => {
+    printDaemonStatus(
+      {
+        service: {
+          label: "LaunchAgent",
+          loaded: true,
+          loadedText: "loaded",
+          notLoadedText: "not loaded",
+          runtime: { status: "running", pid: 8000 },
+          staleUpdateLaunchdJobs: [
+            {
+              label: "ai.openclaw.update.2026.5.12",
+              lastExitStatus: 127,
+            },
+          ],
+        },
+        gateway: {
+          bindMode: "loopback",
+          bindHost: "127.0.0.1",
+          port: 18789,
+          portSource: "env/config",
+          probeUrl: "ws://127.0.0.1:18789",
+        },
+        extraServices: [],
+      },
+      { json: false },
+    );
+
+    expectMockLineContains(runtime.error, "Stale OpenClaw updater launchd job(s) detected.");
+    expectMockLineContains(runtime.error, "ai.openclaw.update.2026.5.12");
+    expectMockLineContains(runtime.error, "launchctl remove <label>");
+    expectMockLineContains(runtime.error, formatCliCommand("openclaw gateway restart"));
+  });
+
   it("prints probe kind and capability separately", () => {
     printDaemonStatus(
       {
diff --git a/src/cli/daemon-cli/status.print.ts b/src/cli/daemon-cli/status.print.ts
@@ -341,6 +341,22 @@ export function printDaemonStatus(status: DaemonStatus, opts: { json: boolean })
     spacer();
   }
 
+  if (service.staleUpdateLaunchdJobs?.length) {
+    defaultRuntime.error(errorText("Stale OpenClaw updater launchd job(s) detected."));
+    for (const job of service.staleUpdateLaunchdJobs) {
+      const exitStatus =
+        job.lastExitStatus !== undefined ? `, last exit ${job.lastExitStatus}` : "";
+      const pid = job.pid !== undefined ? `, pid ${job.pid}` : "";
+      defaultRuntime.error(errorText(`- ${job.label}${pid}${exitStatus}`));
+    }
+    defaultRuntime.error(
+      errorText(
+        `Fix after confirming no update is running: launchctl remove <label>, then run ${formatCliCommand("openclaw gateway restart")}.`,
+      ),
+    );
+    spacer();
+  }
+
   for (const line of renderPortDiagnosticsForCli(status, rpc?.ok)) {
     defaultRuntime.error(errorText(line));
   }
diff --git a/src/commands/doctor-platform-notes.launchctl-env-overrides.test.ts b/src/commands/doctor-platform-notes.launchctl-env-overrides.test.ts
@@ -1,6 +1,9 @@
 import { describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
-import { noteMacLaunchctlGatewayEnvOverrides } from "./doctor-platform-notes.js";
+import {
+  noteMacLaunchctlGatewayEnvOverrides,
+  noteMacStaleOpenClawUpdateLaunchdJobs,
+} from "./doctor-platform-notes.js";
 
 function requireNoteCall(noteFn: { mock: { calls: unknown[][] } }, index = 0): unknown[] {
   const call = noteFn.mock.calls[index];
@@ -91,3 +94,42 @@ describe("noteMacLaunchctlGatewayEnvOverrides", () => {
     expect(noteFn).not.toHaveBeenCalled();
   });
 });
+
+describe("noteMacStaleOpenClawUpdateLaunchdJobs", () => {
+  it("prints stale updater job cleanup guidance on macOS", async () => {
+    const noteFn = vi.fn();
+    const findJobs = vi.fn(async () => [
+      {
+        label: "ai.openclaw.update.2026.5.12",
+        lastExitStatus: 127,
+      },
+    ]);
+
+    await noteMacStaleOpenClawUpdateLaunchdJobs({
+      platform: "darwin",
+      findJobs,
+      noteFn,
+    });
+
+    expect(findJobs).toHaveBeenCalledTimes(1);
+    const [message, title] = requireNoteCall(noteFn);
+    expect(title).toBe("Gateway (macOS)");
+    expect(message).toContain("Stale OpenClaw updater launchd job(s) detected");
+    expect(message).toContain("ai.openclaw.update.2026.5.12");
+    expect(message).toContain("launchctl remove <label>");
+    expect(message).toContain("openclaw gateway restart");
+  });
+
+  it("does nothing when no stale updater jobs exist", async () => {
+    const noteFn = vi.fn();
+    const findJobs = vi.fn(async () => []);
+
+    await noteMacStaleOpenClawUpdateLaunchdJobs({
+      platform: "darwin",
+      findJobs,
+      noteFn,
+    });
+
+    expect(noteFn).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/commands/doctor-platform-notes.ts b/src/commands/doctor-platform-notes.ts
@@ -3,8 +3,10 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { formatCliCommand } from "../cli/command-format.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { hasConfiguredSecretInput } from "../config/types.secrets.js";
+import { findStaleOpenClawUpdateLaunchdJobs } from "../daemon/launchd.js";
 import { normalizeOptionalString } from "../shared/string-coerce.js";
 import { note } from "../terminal/note.js";
 import { shortenHomePath } from "../utils.js";
@@ -35,6 +37,35 @@ export async function noteMacLaunchAgentOverrides() {
   note(lines.join("\n"), "Gateway (macOS)");
 }
 
+export async function noteMacStaleOpenClawUpdateLaunchdJobs(deps?: {
+  platform?: NodeJS.Platform;
+  findJobs?: typeof findStaleOpenClawUpdateLaunchdJobs;
+  noteFn?: typeof note;
+}) {
+  const platform = deps?.platform ?? process.platform;
+  if (platform !== "darwin") {
+    return;
+  }
+  const jobs = await (deps?.findJobs ?? findStaleOpenClawUpdateLaunchdJobs)().catch(() => []);
+  if (jobs.length === 0) {
+    return;
+  }
+
+  const lines = [
+    "- Stale OpenClaw updater launchd job(s) detected.",
+    ...jobs.map((job) => {
+      const exitStatus =
+        job.lastExitStatus !== undefined ? `, last exit ${job.lastExitStatus}` : "";
+      const pid = job.pid !== undefined ? `, pid ${job.pid}` : "";
+      return `- ${job.label}${pid}${exitStatus}`;
+    }),
+    "- Fix after confirming no update is running:",
+    "  launchctl remove <label>",
+    `  ${formatCliCommand("openclaw gateway restart")}`,
+  ];
+  (deps?.noteFn ?? note)(lines.join("\n"), "Gateway (macOS)");
+}
+
 async function launchctlGetenv(name: string): Promise<string | undefined> {
   try {
     const result = await execFileAsync("/bin/launchctl", ["getenv", name], { encoding: "utf8" });
diff --git a/src/commands/doctor.fast-path-mocks.ts b/src/commands/doctor.fast-path-mocks.ts
@@ -36,6 +36,7 @@ vi.mock("./doctor-memory-search.js", () => ({
 vi.mock("./doctor-platform-notes.js", () => ({
   noteStartupOptimizationHints: vi.fn(),
   noteMacLaunchAgentOverrides: vi.fn().mockResolvedValue(undefined),
+  noteMacStaleOpenClawUpdateLaunchdJobs: vi.fn().mockResolvedValue(undefined),
   noteMacLaunchctlGatewayEnvOverrides: vi.fn().mockResolvedValue(undefined),
 }));
 
diff --git a/src/daemon/launchd.test.ts b/src/daemon/launchd.test.ts
@@ -8,8 +8,10 @@ import {
 } from "./launchd-plist.js";
 import {
   installLaunchAgent,
+  findStaleOpenClawUpdateLaunchdJobs,
   isLaunchAgentListed,
   parseLaunchctlPrint,
+  parseLaunchctlListOpenClawUpdateJobs,
   readLaunchAgentProgramArguments,
   readLaunchAgentRuntime,
   repairLaunchAgentBootstrap,
@@ -418,6 +420,45 @@ describe("launchctl list detection", () => {
     });
     expect(listed).toBe(false);
   });
+
+  it("parses stale OpenClaw updater jobs from launchctl list", () => {
+    const jobs = parseLaunchctlListOpenClawUpdateJobs(
+      [
+        "123 0 ai.openclaw.gateway",
+        "- 127 ai.openclaw.update.2026.5.12",
+        "8142 0 ai.openclaw.update.2026.5.13-beta.1",
+        "- 0 com.example.other",
+      ].join("\n"),
+    );
+
+    expect(jobs).toEqual([
+      {
+        label: "ai.openclaw.update.2026.5.12",
+        lastExitStatus: 127,
+      },
+      {
+        label: "ai.openclaw.update.2026.5.13-beta.1",
+        pid: 8142,
+        lastExitStatus: 0,
+      },
+    ]);
+  });
+
+  it.runIf(process.platform === "darwin")(
+    "finds stale OpenClaw updater jobs via launchctl list",
+    async () => {
+      state.listOutput = "- 127 ai.openclaw.update.2026.5.12\n";
+
+      const jobs = await findStaleOpenClawUpdateLaunchdJobs();
+
+      expect(jobs).toEqual([
+        {
+          label: "ai.openclaw.update.2026.5.12",
+          lastExitStatus: 127,
+        },
+      ]);
+    },
+  );
 });
 
 describe("launchd bootstrap repair", () => {
diff --git a/src/daemon/launchd.ts b/src/daemon/launchd.ts
diff --git a/src/flows/doctor-health-contributions.ts b/src/flows/doctor-health-contributions.ts
