@indigoai-us/hq-cli 5.177.0 → 5.178.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.178.0] — 2026-09-24
+
+### Fixed
+
+- Reloading a macOS LaunchAgent (`hq mesh daemon install`, including `--if-stale` and the post-update restart, `hq daemon install`, `hq agent kit` services, and bot agents) now waits for `launchctl bootout` to finish before bootstrapping. Before, bootstrap could race the old job's teardown, fail with "Bootstrap failed: 5: Input/output error", and leave the service unloaded with nothing running. Bootstrap now polls `launchctl print` for up to 10 seconds, retries EIO with backoff (0.5s to 8s), and on final failure either restarts the still-loaded previous job or reports that the service is NOT loaded with the `launchctl bootstrap` command to fix it.
+
 ## [5.177.0] — 2026-09-24
 
 ### Added

package/dist/lib/bot/daemon.js

@@ -15,6 +15,7 @@ import * as path from "node:path";
 import { spawn } from "node:child_process";
 import { resolveHqBinary, resolveNodeBinary, preferStableHqBinary } from "../mesh/live/daemon/install.js";
 import { botLogPath, launchdLabel } from "./paths.js";
+import { reloadLaunchd } from "../service-manager/launchd.js";
 import { nodeBinaryProblem, preferStableNodeBinary } from "../node-binary.js";
 export function detectBotPlatform(platform = process.platform) {
     if (platform === "darwin")
@@ -171,22 +172,17 @@ function bootoutLaunchd(p, deps) {
 }
 /**
  * `launchctl bootout` returns before the job is actually gone; a `bootstrap`
- * issued right away fails ("service already loaded" / EIO) and the old job
- * then finishes unloading, leaving nothing running even though `print` said
- * loaded a moment ago. Wait for the unload, then bootstrap with retries.
+ * issued right away fails with EIO and the old job then finishes unloading,
+ * leaving nothing running. Shared with the mesh daemon and kit services:
+ * wait for the unload, then bootstrap with backoff.
  */
 function rebootstrapLaunchd(p, deps) {
     const launchctl = deps.launchctl;
-    const sleep = deps.sleepMs ?? blockingSleep;
-    launchctl(["bootout", `${launchdDomain(deps.uid)}/${p.label}`]);
-    for (let i = 0; i < 20 && launchdLoaded(p, deps); i++)
-        sleep(250);
-    let r = launchctl(["bootstrap", launchdDomain(deps.uid), p.plistPath]);
-    for (let i = 0; i < 3 && !r.ok; i++) {
-        sleep(500);
-        r = launchctl(["bootstrap", launchdDomain(deps.uid), p.plistPath]);
-    }
-    return r;
+    const run = (_cmd, args) => {
+        const r = launchctl(args);
+        return { status: r.ok ? 0 : 1, stdout: r.stdout, stderr: r.stderr };
+    };
+    return reloadLaunchd(p.plistPath, run, deps.uid ?? os.userInfo().uid, { sleep: deps.sleepMs ?? blockingSleep });
 }
 function launchdLoaded(p, deps) {
     if (!deps.launchctl)
@@ -397,17 +393,24 @@ export function installBotDaemon(p, deps = {}) {
         if (deps.launchctl) {
             // bootout first so a re-install picks up a changed plist.
             const r = rebootstrapLaunchd(p, deps);
-            loaded = r.ok || launchdLoaded(p, deps);
-            if (!loaded) {
+            if (!r.ok) {
+                const detail = `launchctl bootstrap failed after ${r.bootstrapAttempts} attempts: ${(r.error ?? "").slice(0, 200)}`;
+                if (r.loaded) {
+                    // The previous definition survived the bootout; keep it running.
+                    deps.launchctl(["kickstart", "-k", `${launchdDomain(deps.uid)}/${p.label}`]);
+                }
                 return {
                     platform,
                     action: "install",
                     installed: true,
-                    loaded: false,
+                    loaded: r.loaded,
                     dest: p.plistPath,
-                    message: `Wrote ${p.plistPath} but launchctl bootstrap failed: ${(r.stderr || r.stdout).trim().slice(0, 200)}`,
+                    message: r.loaded
+                        ? `Wrote ${p.plistPath} but ${detail}. The previous definition of ${p.label} is still loaded and was restarted; the rewritten plist is not active yet.`
+                        : `Wrote ${p.plistPath} but ${detail}. ${p.label} is NOT loaded. Load it with: launchctl bootstrap ${launchdDomain(deps.uid)} ${p.plistPath}`,
                 };
             }
+            loaded = true;
         }
         return {
             platform,

package/dist/lib/daemon/install.d.ts

@@ -15,7 +15,7 @@
  * services are added. Every service-manager call goes through `run`, so tests
  * never touch launchctl, systemctl or schtasks.
  */
-import { type RunCommand } from "../service-manager/launchd.js";
+import { type RunCommand, type SleepFn } from "../service-manager/launchd.js";
 import type { MachineType } from "./machine-type.js";
 export declare const DAEMON_LAUNCHD_LABEL = "ai.getindigo.hq-daemon";
 export declare const DAEMON_SYSTEMD_UNIT = "hq-daemon.service";
@@ -63,6 +63,8 @@ export interface DaemonUnitResult {
 }
 export interface InstallDeps {
     run: RunCommand;
+    /** Blocking sleep for the launchd reload wait (tests inject). */
+    sleep?: SleepFn;
 }
 export declare const ROOT_REFUSAL = "hq daemon runs its services as the machine's login user, never as root.";
 /**

package/dist/lib/daemon/install.js

@@ -204,10 +204,10 @@ export function planDaemonUnit(host, options) {
 function commandError(what, r) {
     return new Error(`${what} failed: ${r.stderr.trim() || r.stdout.trim() || `exit ${r.status}`}`);
 }
-function activate(plan, host, run) {
+function activate(plan, host, run, sleep) {
     switch (plan.kind) {
         case "launchd":
-            activateLaunchd(plan.unitPath, run, host.uid);
+            activateLaunchd(plan.unitPath, run, host.uid, { sleep });
             return;
         case "systemd-user":
             activateSystemd(DAEMON_SYSTEMD_UNIT, run);
@@ -251,7 +251,7 @@ export function installDaemonUnit(host, options, deps) {
     else
         fs.writeFileSync(plan.unitPath, plan.rendered, { mode: plan.kind === "systemd-system" ? 0o644 : 0o600 });
     try {
-        activate(plan, host, deps.run);
+        activate(plan, host, deps.run, deps.sleep);
         return { kind: plan.kind, unitPath: plan.unitPath, installed: true, running: true };
     }
     catch (err) {

package/dist/lib/mesh/live/daemon/install.js

@@ -184,8 +184,8 @@ export function restartDaemonServiceIfInstalled(opts = {}) {
                     activateLaunchd(plist, asRunCommand(run), uid, { sleep: opts.sleep });
                     return { attempted: true, restarted: true };
                 }
-                catch {
-                    return { attempted: true, restarted: false };
+                catch (err) {
+                    return { attempted: true, restarted: false, message: err instanceof Error ? err.message : String(err) };
                 }
             }
             const result = run("launchctl", ["kickstart", "-k", target]);

package/dist/lib/service-manager/launchd.d.ts

@@ -17,10 +17,14 @@ export type RunCommand = (cmd: string, args: string[]) => {
     stderr: string;
 };
 export type SleepFn = (ms: number) => void;
+/** How long to wait for a booted-out job to leave launchd before bootstrapping anyway. */
+export declare const LAUNCHD_UNLOAD_DEADLINE_MS = 10000;
+/** Interval between `launchctl print` polls while the old job unloads. */
+export declare const LAUNCHD_UNLOAD_POLL_MS = 250;
+/** Backoff before each bootstrap retry on EIO (one retry per entry). */
+export declare const LAUNCHD_BOOTSTRAP_BACKOFF_MS: readonly number[];
 /** Bootstrap attempts after bootout (first try + EIO retries). */
-export declare const LAUNCHD_BOOTSTRAP_ATTEMPTS = 5;
-/** Delay between bootstrap retries while the old job is still exiting. */
-export declare const LAUNCHD_BOOTSTRAP_RETRY_MS = 1000;
+export declare const LAUNCHD_BOOTSTRAP_ATTEMPTS: number;
 export declare const defaultRunCommand: RunCommand;
 export declare function launchdServiceTarget(plistPath: string, uid?: number): string;
 /** launchd returns EIO (5) when bootstrap races the previous job's exit. */
@@ -38,13 +42,46 @@ export declare function launchdPlistProgramArguments(plist: string): string[];
 export declare function parseLaunchctlPrintArguments(stdout: string): string[];
 export declare function launchdProgramArgumentsDiffer(loaded: string[], plist: string[]): boolean;
 /**
- * (Re)load a plist so launchd picks up a rewritten ProgramArguments.
- * bootout is best-effort (not loaded yet is fine). bootstrap retries EIO a
- * bounded number of times — bootout returns before the old job has actually
- * exited. kickstart then starts the newly loaded program.
+ * Poll `launchctl print <target>` until the label is gone. Returns false when
+ * it is still loaded at the deadline. Elapsed time is counted in slept
+ * intervals so an injected sleep keeps tests deterministic.
+ */
+export declare function waitForLaunchdUnload(target: string, run: RunCommand, opts?: {
+    sleep?: SleepFn;
+    deadlineMs?: number;
+}): boolean;
+export interface LaunchdReloadResult {
+    /** bootstrap of the plist succeeded. */
+    ok: boolean;
+    /** The label is present in launchd after the reload (new or previous definition). */
+    loaded: boolean;
+    /** The previous job was still loaded when the unload deadline passed. */
+    unloadTimedOut: boolean;
+    bootstrapAttempts: number;
+    /** Last bootstrap error when !ok. */
+    error?: string;
+}
+/**
+ * bootout, wait for the label to actually leave launchd, then bootstrap with
+ * backoff on EIO. `launchctl bootout` returns before launchd finishes tearing
+ * the job down, and a bootstrap issued in that window fails with
+ * "Bootstrap failed: 5: Input/output error" — after which the old job
+ * finishes unloading and nothing is left running.
+ */
+export declare function reloadLaunchd(plistPath: string, run: RunCommand, uid?: number, opts?: {
+    sleep?: SleepFn;
+    unloadDeadlineMs?: number;
+}): LaunchdReloadResult;
+/**
+ * (Re)load a plist so launchd picks up a rewritten ProgramArguments, then
+ * kickstart it. Never leaves the service silently unloaded: when bootstrap
+ * keeps failing but the previous job is still loaded, that job is restarted
+ * and the error says so; when nothing is loaded, the error says the service
+ * is NOT loaded and gives the command to load it.
  */
 export declare function activateLaunchd(plistPath: string, run: RunCommand, uid?: number, opts?: {
     sleep?: SleepFn;
+    unloadDeadlineMs?: number;
 }): void;
 export declare function deactivateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
 export declare function launchdIsLoaded(label: string, run: RunCommand, uid?: number): boolean;

package/dist/lib/service-manager/launchd.js

@@ -60,10 +60,14 @@ ${envXml}
 </plist>
 `;
 }
+/** How long to wait for a booted-out job to leave launchd before bootstrapping anyway. */
+export const LAUNCHD_UNLOAD_DEADLINE_MS = 10_000;
+/** Interval between `launchctl print` polls while the old job unloads. */
+export const LAUNCHD_UNLOAD_POLL_MS = 250;
+/** Backoff before each bootstrap retry on EIO (one retry per entry). */
+export const LAUNCHD_BOOTSTRAP_BACKOFF_MS = [500, 1000, 2000, 4000, 8000];
 /** Bootstrap attempts after bootout (first try + EIO retries). */
-export const LAUNCHD_BOOTSTRAP_ATTEMPTS = 5;
-/** Delay between bootstrap retries while the old job is still exiting. */
-export const LAUNCHD_BOOTSTRAP_RETRY_MS = 1000;
+export const LAUNCHD_BOOTSTRAP_ATTEMPTS = LAUNCHD_BOOTSTRAP_BACKOFF_MS.length + 1;
 export const defaultRunCommand = (cmd, args) => {
     const r = spawnSync(cmd, args, { encoding: "utf8" });
     return {
@@ -127,25 +131,76 @@ export function launchdProgramArgumentsDiffer(loaded, plist) {
     return loaded.some((value, i) => value !== plist[i]);
 }
 /**
- * (Re)load a plist so launchd picks up a rewritten ProgramArguments.
- * bootout is best-effort (not loaded yet is fine). bootstrap retries EIO a
- * bounded number of times — bootout returns before the old job has actually
- * exited. kickstart then starts the newly loaded program.
+ * Poll `launchctl print <target>` until the label is gone. Returns false when
+ * it is still loaded at the deadline. Elapsed time is counted in slept
+ * intervals so an injected sleep keeps tests deterministic.
  */
-export function activateLaunchd(plistPath, run, uid, opts) {
+export function waitForLaunchdUnload(target, run, opts) {
+    const sleep = opts?.sleep ?? blockingSleep;
+    const deadline = opts?.deadlineMs ?? LAUNCHD_UNLOAD_DEADLINE_MS;
+    for (let waited = 0; run("launchctl", ["print", target]).status === 0; waited += LAUNCHD_UNLOAD_POLL_MS) {
+        if (waited >= deadline)
+            return false;
+        sleep(LAUNCHD_UNLOAD_POLL_MS);
+    }
+    return true;
+}
+/**
+ * bootout, wait for the label to actually leave launchd, then bootstrap with
+ * backoff on EIO. `launchctl bootout` returns before launchd finishes tearing
+ * the job down, and a bootstrap issued in that window fails with
+ * "Bootstrap failed: 5: Input/output error" — after which the old job
+ * finishes unloading and nothing is left running.
+ */
+export function reloadLaunchd(plistPath, run, uid, opts) {
     const domain = guiDomain(uid);
     const target = launchdServiceTarget(plistPath, uid);
-    run("launchctl", ["bootout", target]);
     const sleep = opts?.sleep ?? blockingSleep;
+    // bootout is best-effort: "not loaded" on a first install is fine.
+    run("launchctl", ["bootout", target]);
+    const unloaded = waitForLaunchdUnload(target, run, { sleep, deadlineMs: opts?.unloadDeadlineMs });
     let last = run("launchctl", ["bootstrap", domain, plistPath]);
-    for (let attempt = 1; attempt < LAUNCHD_BOOTSTRAP_ATTEMPTS && last.status !== 0 && isRetryableLaunchdBootstrap(last); attempt++) {
-        sleep(LAUNCHD_BOOTSTRAP_RETRY_MS);
+    let attempts = 1;
+    for (const backoff of LAUNCHD_BOOTSTRAP_BACKOFF_MS) {
+        if (last.status === 0 || !isRetryableLaunchdBootstrap(last))
+            break;
+        sleep(backoff);
         last = run("launchctl", ["bootstrap", domain, plistPath]);
+        attempts++;
+    }
+    if (last.status === 0) {
+        return { ok: true, loaded: true, unloadTimedOut: !unloaded, bootstrapAttempts: attempts };
+    }
+    return {
+        ok: false,
+        loaded: run("launchctl", ["print", target]).status === 0,
+        unloadTimedOut: !unloaded,
+        bootstrapAttempts: attempts,
+        error: last.stderr.trim() || last.stdout.trim() || `exit ${last.status}`,
+    };
+}
+/**
+ * (Re)load a plist so launchd picks up a rewritten ProgramArguments, then
+ * kickstart it. Never leaves the service silently unloaded: when bootstrap
+ * keeps failing but the previous job is still loaded, that job is restarted
+ * and the error says so; when nothing is loaded, the error says the service
+ * is NOT loaded and gives the command to load it.
+ */
+export function activateLaunchd(plistPath, run, uid, opts) {
+    const domain = guiDomain(uid);
+    const target = launchdServiceTarget(plistPath, uid);
+    const r = reloadLaunchd(plistPath, run, uid, opts);
+    if (r.ok) {
+        run("launchctl", ["kickstart", "-k", target]);
+        return;
     }
-    if (last.status !== 0) {
-        throw new Error(`launchctl bootstrap failed for ${plistPath}: ${last.stderr.trim() || last.stdout.trim() || `exit ${last.status}`}`);
+    const detail = `launchctl bootstrap failed for ${plistPath} after ${r.bootstrapAttempts} attempts: ${r.error}`;
+    if (r.loaded) {
+        run("launchctl", ["kickstart", "-k", target]);
+        throw new Error(`${detail}. The previous definition of ${target} is still loaded and was restarted; ` +
+            `the rewritten plist is not active yet. Retry, or run: launchctl bootout ${target} && launchctl bootstrap ${domain} ${plistPath}`);
     }
-    run("launchctl", ["kickstart", "-k", target]);
+    throw new Error(`${detail}. ${target} is NOT loaded and will not run until it is. Load it with: launchctl bootstrap ${domain} ${plistPath}`);
 }
 export function deactivateLaunchd(plistPath, run, uid) {
     run("launchctl", ["bootout", guiDomain(uid), plistPath]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.177.0",
+  "version": "5.178.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {