@indigoai-us/hq-cli 5.151.0 → 5.152.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.152.0] — 2026-09-23
+
+### Fixed
+
+- `hq mesh daemon install` (plain and `--if-stale`) now bootouts, bootstraps, and kickstarts the LaunchAgent after writing the plist. Bootstrap retries launchd `5: Input/output error` up to five times, one second apart. After a CLI upgrade, a loaded job whose program no longer matches the plist is reloaded the same way.
+
 ## [5.151.0] — 2026-09-23
 
 - `hq report publish` no longer fails when another app it cannot see holds the report's address. It publishes at the next free address (`<slug>-2`, then `-3`) and saves that address on the report.

package/dist/commands/mesh.js

@@ -36,6 +36,7 @@ import { readLegacyBacklog } from "../lib/mesh/live/emit-replay.js";
 import { resolveMeshEmitMode, writeMeshConfigMode, } from "../lib/mesh/live/daemon/mode.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
 import { buildInstallPaths, collectDaemonDoctor, daemonServiceStatus, findAncestorHqRoot, resolveInstallHqRoot, detectPlatform, formatCliIdentityLines, formatDaemonDoctor, installDaemonIfStale, installDaemonService, readDaemonState, resolveAbsoluteNodeBinary, resolveRunningCliEntry, runMeshDaemon, uninstallDaemonService, daemonDir, } from "../lib/mesh/live/daemon/index.js";
+import { defaultRunCommand } from "../lib/service-manager/launchd.js";
 import { workContextRoot } from "../lib/work-context/paths.js";
 import { formatMigrateConfirmation, submitSessionMigration, } from "../lib/work-context/migrate.js";
 import { formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, submitOrganizeDecision, } from "../lib/work-context/organize.js";
@@ -2050,6 +2051,7 @@ async function runDaemonInstall(opts) {
         platform: detectPlatform(),
         paths,
         systemUser: opts.systemUser,
+        run: defaultRunCommand,
     });
     if (opts.json) {
         console.log(JSON.stringify({

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

@@ -12,7 +12,7 @@
  * Tests must not actually install services — use a temp HOME/prefix.
  */
 import * as fs from "node:fs";
-import { type RunCommand } from "../../../service-manager/launchd.js";
+import { type RunCommand, type SleepFn } from "../../../service-manager/launchd.js";
 export type DaemonInstallPlatform = "darwin" | "linux" | "win32" | "other";
 /** Result of one schtasks.exe invocation (tests inject; never the real binary). */
 export interface SchtasksResult {
@@ -93,11 +93,6 @@ export interface RestartDaemonResult {
     restarted: boolean;
     message?: string;
 }
-/**
- * Restart the installed user daemon after a CLI upgrade. This is deliberately
- * best-effort: an update must remain successful if a user has no service,
- * launchctl/systemd is unavailable, or the user manager is not running.
- */
 export declare function restartDaemonServiceIfInstalled(opts?: {
     platform?: DaemonInstallPlatform;
     home?: string;
@@ -110,7 +105,10 @@ export declare function restartDaemonServiceIfInstalled(opts?: {
     writeFileSync?: typeof fs.writeFileSync;
     run?: (command: string, args: string[]) => {
         status: number | null;
+        stdout?: string;
+        stderr?: string;
     };
+    sleep?: SleepFn;
     /** Windows: terminate the recorded daemon pid after `schtasks /End` (tests inject). */
     kill?: (pid: number) => void;
 }): RestartDaemonResult;
@@ -149,6 +147,7 @@ export declare function installDaemonIfStale(opts: {
     systemUser?: string;
     run?: RunCommand;
     uid?: number;
+    sleep?: SleepFn;
     writeFileSync?: typeof fs.writeFileSync;
     mkdirSync?: typeof fs.mkdirSync;
     reloadSystemd?: () => {
@@ -282,6 +281,10 @@ export declare function installDaemonService(opts: {
         stderr: string;
     };
     windowsLegacyTaskPresent?: boolean;
+    /** launchctl/systemctl seam — when set on darwin, bootout/bootstrap/kickstart after writing the plist. */
+    run?: RunCommand;
+    uid?: number;
+    sleep?: SleepFn;
 }): InstallResult;
 export declare function uninstallDaemonService(opts: {
     platform?: DaemonInstallPlatform;

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

@@ -22,7 +22,7 @@ import { isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot, verifyHqR
 import { defaultPidLockDeps, pidLockStatus, readPidLock } from "./pid-lock.js";
 import { retireLegacyListen } from "./legacy-listen.js";
 import { readDaemonState } from "./state.js";
-import { activateLaunchd } from "../../../service-manager/launchd.js";
+import { activateLaunchd, launchdPlistProgramArguments, launchdProgramArgumentsDiffer, parseLaunchctlPrintArguments, } from "../../../service-manager/launchd.js";
 import { activateSystemd } from "../../../service-manager/systemd.js";
 /**
  * `schtasks /End` terminates the task's root process only. The daemon is
@@ -139,13 +139,30 @@ function migrateLegacyDaemonUnit(opts) {
  * best-effort: an update must remain successful if a user has no service,
  * launchctl/systemd is unavailable, or the user manager is not running.
  */
+function asRunCommand(run) {
+    return (command, args) => {
+        const result = run(command, args);
+        return {
+            status: result.status,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+        };
+    };
+}
 export function restartDaemonServiceIfInstalled(opts = {}) {
     const platform = opts.platform ?? detectPlatform();
     const home = opts.home ?? os.homedir();
     const existsSync = opts.existsSync ?? fs.existsSync;
     const readFileSync = opts.readFileSync ?? fs.readFileSync;
     const writeFileSync = opts.writeFileSync ?? fs.writeFileSync;
-    const run = opts.run ?? ((command, args) => spawnSync(command, args, { stdio: "ignore" }));
+    const run = opts.run ?? ((command, args) => {
+        const result = spawnSync(command, args, { encoding: "utf8" });
+        return {
+            status: result.status,
+            stdout: typeof result.stdout === "string" ? result.stdout : "",
+            stderr: result.error ? result.error.message : (typeof result.stderr === "string" ? result.stderr : ""),
+        };
+    });
     try {
         migrateLegacyDaemonUnit({ platform, home, hqRoot: opts.hqRoot, env: opts.env, existsSync, readFileSync, writeFileSync, run });
         if (platform === "darwin") {
@@ -155,7 +172,22 @@ export function restartDaemonServiceIfInstalled(opts = {}) {
             const uid = opts.uid ?? process.getuid?.();
             if (typeof uid !== "number")
                 return { attempted: false, restarted: false };
-            const result = run("launchctl", ["kickstart", "-k", `gui/${uid}/${LAUNCHD_LABEL}`]);
+            const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+            const printed = run("launchctl", ["print", target]);
+            const loadedArgs = parseLaunchctlPrintArguments(printed.stdout ?? "");
+            const rawPlist = readFileSync(plist);
+            const plistText = Buffer.isBuffer(rawPlist) ? rawPlist.toString("utf8") : String(rawPlist);
+            const plistArgs = launchdPlistProgramArguments(plistText);
+            if (launchdProgramArgumentsDiffer(loadedArgs, plistArgs)) {
+                try {
+                    activateLaunchd(plist, asRunCommand(run), uid, { sleep: opts.sleep });
+                    return { attempted: true, restarted: true };
+                }
+                catch {
+                    return { attempted: true, restarted: false };
+                }
+            }
+            const result = run("launchctl", ["kickstart", "-k", target]);
             return { attempted: true, restarted: result.status === 0 };
         }
         if (platform === "linux") {
@@ -306,11 +338,11 @@ export function installDaemonIfStale(opts) {
         kill: opts.kill,
         runCommand: opts.runCommand,
         windowsLegacyTaskPresent: opts.windowsLegacyTaskPresent,
+        run,
+        uid: opts.uid,
+        sleep: opts.sleep,
     });
-    if (platform === "darwin") {
-        activateLaunchd(opts.paths.plistPath, run, opts.uid);
-    }
-    else if (platform === "linux" && !opts.systemUser && !opts.paths.systemUser) {
+    if (platform === "linux" && !opts.systemUser && !opts.paths.systemUser) {
         activateSystemd(SYSTEMD_UNIT_NAME, run);
     }
     return {
@@ -753,7 +785,12 @@ export function installDaemonService(opts) {
         const rendered = renderLaunchdPlist(paths);
         mkdirSync(paths.launchAgentsDir, { recursive: true });
         writeFileSync(paths.plistPath, rendered, { mode: 0o600 });
-        opts.activate?.(platform, paths.plistPath);
+        if (opts.run) {
+            activateLaunchd(paths.plistPath, opts.run, opts.uid, { sleep: opts.sleep });
+        }
+        else {
+            opts.activate?.(platform, paths.plistPath);
+        }
         return {
             platform,
             action: "install",

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

@@ -9,9 +9,8 @@ import { type RunCommand } from "./launchd.js";
 import { type ServiceHostPaths, type ServicePlatform, type ServiceSpec } from "./types.js";
 export type { ServiceSpec, ServiceHostPaths, ServicePlatform } from "./types.js";
 export { detectServicePlatform } from "./types.js";
-export { renderLaunchdPlist } from "./launchd.js";
+export { defaultRunCommand, renderLaunchdPlist } from "./launchd.js";
 export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
-export declare const defaultRunCommand: RunCommand;
 export interface ServiceManagerDeps {
     platform?: ServicePlatform;
     run?: RunCommand;

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

@@ -4,22 +4,13 @@
  * injectable so the kit tests exercise the real rendering and dispatch
  * without touching the host's service manager.
  */
-import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
-import { activateLaunchd, deactivateLaunchd, launchAgentsDir, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "./launchd.js";
+import { activateLaunchd, deactivateLaunchd, defaultRunCommand, launchAgentsDir, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "./launchd.js";
 import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdIsActive, systemdUnitName, systemdUnitPath, systemdUserDir, } from "./systemd.js";
 import { detectServicePlatform, } from "./types.js";
 export { detectServicePlatform } from "./types.js";
-export { renderLaunchdPlist } from "./launchd.js";
+export { defaultRunCommand, renderLaunchdPlist } from "./launchd.js";
 export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
-export const defaultRunCommand = (cmd, args) => {
-    const r = spawnSync(cmd, args, { encoding: "utf8" });
-    return {
-        status: r.status,
-        stdout: r.stdout ?? "",
-        stderr: r.error ? r.error.message : (r.stderr ?? ""),
-    };
-};
 function unitPathFor(platform, home, spec) {
     return platform === "darwin" ? launchdPlistPath(home, spec) : systemdUnitPath(home, spec);
 }

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

@@ -16,8 +16,36 @@ export type RunCommand = (cmd: string, args: string[]) => {
     stdout: string;
     stderr: string;
 };
-/** (Re)load a plist: bootout is best-effort (not loaded yet is fine). */
-export declare function activateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
+export type SleepFn = (ms: number) => void;
+/** 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 defaultRunCommand: RunCommand;
+export declare function launchdServiceTarget(plistPath: string, uid?: number): string;
+/** launchd returns EIO (5) when bootstrap races the previous job's exit. */
+export declare function isRetryableLaunchdBootstrap(r: {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}): boolean;
+/** ProgramArguments from a LaunchAgent plist. */
+export declare function launchdPlistProgramArguments(plist: string): string[];
+/**
+ * Arguments of a loaded job from `launchctl print gui/<uid>/<label>`.
+ * Prefers the `arguments = { ... }` block; falls back to `program =`.
+ */
+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.
+ */
+export declare function activateLaunchd(plistPath: string, run: RunCommand, uid?: number, opts?: {
+    sleep?: SleepFn;
+}): void;
 export declare function deactivateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
 export declare function launchdIsLoaded(label: string, run: RunCommand, uid?: number): boolean;
 //# sourceMappingURL=launchd.d.ts.map

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

@@ -6,6 +6,7 @@
  * picks up a changed plist). Command execution is injected so tests never
  * touch launchctl.
  */
+import { spawnSync } from "node:child_process";
 import * as os from "node:os";
 import * as path from "node:path";
 import { escapeXml, } from "./types.js";
@@ -59,17 +60,92 @@ ${envXml}
 </plist>
 `;
 }
+/** 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 defaultRunCommand = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8" });
+    return {
+        status: r.status,
+        stdout: typeof r.stdout === "string" ? r.stdout : "",
+        stderr: r.error ? r.error.message : (typeof r.stderr === "string" ? r.stderr : ""),
+    };
+};
+function blockingSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 function guiDomain(uid = os.userInfo().uid) {
     return `gui/${uid}`;
 }
-/** (Re)load a plist: bootout is best-effort (not loaded yet is fine). */
-export function activateLaunchd(plistPath, run, uid) {
+export function launchdServiceTarget(plistPath, uid) {
+    return `${guiDomain(uid)}/${path.basename(plistPath, ".plist")}`;
+}
+function bootstrapErrorText(r) {
+    return `${r.stderr} ${r.stdout} exit ${r.status ?? ""}`;
+}
+/** launchd returns EIO (5) when bootstrap races the previous job's exit. */
+export function isRetryableLaunchdBootstrap(r) {
+    if (r.status === 0)
+        return false;
+    return /Input\/output error|\bEIO\b|Bootstrap failed: 5|Boot-strap failed: 5/i.test(bootstrapErrorText(r));
+}
+function unescapeXml(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+/** ProgramArguments from a LaunchAgent plist. */
+export function launchdPlistProgramArguments(plist) {
+    const block = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (!block)
+        return [];
+    return [...block[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => unescapeXml(m[1]));
+}
+/**
+ * Arguments of a loaded job from `launchctl print gui/<uid>/<label>`.
+ * Prefers the `arguments = { ... }` block; falls back to `program =`.
+ */
+export function parseLaunchctlPrintArguments(stdout) {
+    const block = /(?:program\s+)?arguments\s*=\s*\{([^}]*)\}/i.exec(stdout);
+    if (block) {
+        return block[1]
+            .split(/\r?\n/)
+            .map((line) => line.trim().replace(/;+$/, ""))
+            .filter((line) => line.length > 0);
+    }
+    const program = /^\s*program\s*=\s*(.+?);?\s*$/m.exec(stdout);
+    return program ? [program[1].trim()] : [];
+}
+export function launchdProgramArgumentsDiffer(loaded, plist) {
+    if (loaded.length === 0 || plist.length === 0)
+        return loaded.length !== plist.length;
+    if (loaded.length !== plist.length)
+        return true;
+    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.
+ */
+export function activateLaunchd(plistPath, run, uid, opts) {
     const domain = guiDomain(uid);
-    run("launchctl", ["bootout", domain, plistPath]);
-    const r = run("launchctl", ["bootstrap", domain, plistPath]);
-    if (r.status !== 0) {
-        throw new Error(`launchctl bootstrap failed for ${plistPath}: ${r.stderr.trim() || r.stdout.trim() || `exit ${r.status}`}`);
+    const target = launchdServiceTarget(plistPath, uid);
+    run("launchctl", ["bootout", target]);
+    const sleep = opts?.sleep ?? blockingSleep;
+    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);
+        last = run("launchctl", ["bootstrap", domain, plistPath]);
+    }
+    if (last.status !== 0) {
+        throw new Error(`launchctl bootstrap failed for ${plistPath}: ${last.stderr.trim() || last.stdout.trim() || `exit ${last.status}`}`);
     }
+    run("launchctl", ["kickstart", "-k", target]);
 }
 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.151.0",
+  "version": "5.152.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {