@indigoai-us/hq-cli 5.345.202 → 5.345.204

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

@@ -163,6 +163,105 @@ export declare function classifyWindowsTask(run: RunCommand, task: string, host:
 /** What to tell the user when HQ did not stop pid `pid` because it could not verify it. */
 export declare function oldDaemonWarning(pid: number, reason: string): string;
 export declare function installDaemonUnit(host: DaemonHost, options: InstallOptions, deps: InstallDeps): DaemonUnitResult;
+/** Install-level bootstrap retries after launchd left the job unloaded. */
+export declare const DAEMON_BOOTSTRAP_RETRIES = 3;
+export declare const DAEMON_BOOTSTRAP_RETRY_MS = 2000;
+/**
+ * Bootstrap the daemon agent again when an install left it unloaded, up to
+ * DAEMON_BOOTSTRAP_RETRIES times, then kickstart it. Returns the error that
+ * says the agent is not loaded when every retry failed.
+ */
+export declare function retryLaunchdBootstrap(plistPath: string, run: RunCommand, uid: number, sleep?: SleepFn): {
+    ok: boolean;
+    error?: string;
+};
+export interface RefreshDaemonPlistResult {
+    /**
+     * - `none`: no daemon plist here (not installed; nothing to upgrade);
+     * - `current`: the plist already loads without HQ.app;
+     * - `rewritten`: the plist was rewritten; it was not loaded, so nothing was reloaded;
+     * - `reloaded`: the plist was rewritten and launchd now runs the new definition.
+     */
+    action: "none" | "current" | "rewritten" | "reloaded";
+    plistPath: string;
+    /** The rewrite or reload did not finish; what is left and how to fix it. */
+    error?: string;
+}
+/**
+ * Upgrade a daemon LaunchAgent written by an older install (run through the
+ * HQ.app launcher and associated with the app's bundle, which launchd skips
+ * at login) to the app-independent form, and reload it when it is loaded.
+ *
+ * Nothing but `hq daemon install` used to rewrite the unit, so a machine that
+ * only ever self-updated kept the old plist. This runs from `hq daemon start`,
+ * and from the detached helper the managed daemon spawns at startup when it
+ * finds the old plist (see daemonPlistNeedsRefresh). It must not run inside
+ * the daemon's own job: the bootout would end the caller before the bootstrap.
+ */
+export declare function refreshDaemonPlist(host: Pick<DaemonHost, "home" | "uid">, deps: {
+    run: RunCommand;
+    sleep?: SleepFn;
+}): RefreshDaemonPlistResult;
+/** The daemon plist on disk still runs through HQ.app or names its bundle. */
+export declare function daemonPlistNeedsRefresh(home: string): boolean;
+/**
+ * Who runs the daemon right now, as the service manager and the pid lock see it:
+ *
+ * - `managed`: the OS unit is loaded (and, where the manager reports one, its
+ *   pid is the daemon holding the lock), so it comes back after a crash or login;
+ * - `unmanaged`: a daemon holds the lock, but the OS unit is not loaded or runs
+ *   a different process (started by hand, or as the desktop app's child);
+ * - `not-loaded`: the OS unit is not loaded and no daemon runs.
+ */
+export type DaemonSupervision = "managed" | "unmanaged" | "not-loaded";
+export interface DaemonServiceStatus {
+    supervision: DaemonSupervision;
+    /** Which service manager was asked. */
+    manager: "launchd" | "systemd-user" | "systemd-system" | "schtasks" | "none";
+    /** The unit file (plist, unit, task) is present. */
+    unitInstalled: boolean;
+    /** The manager has the unit loaded / enabled. */
+    loaded: boolean;
+    /** The manager reports the unit's process as running. */
+    active: boolean;
+    /** The manager's pid for the unit, when it reports one. */
+    managerPid?: number;
+    /** The pid of the live daemon holding the lock, or null. */
+    daemonPid: number | null;
+    /** One line for people: what the manager said. */
+    detail: string;
+    /**
+     * Problems with the unit that do not change who runs the daemon now, such
+     * as a plist launchd skips at login. One line each, with the fix.
+     */
+    warnings?: string[];
+}
+export declare function describeSupervision(status: DaemonServiceStatus): string;
+/**
+ * Ask launchd, systemd or Task Scheduler whether the daemon's unit is loaded,
+ * and combine that with the pid lock. `daemonPid` is the live daemon from the
+ * lock (null when none runs).
+ */
+export declare function daemonServiceStatus(host: Pick<DaemonHost, "platform" | "home" | "uid" | "systemUnitDir" | "windowsSid" | "windowsUser">, run: RunCommand, daemonPid: number | null): DaemonServiceStatus;
+export interface StartDaemonResult {
+    /**
+     * What was done: nothing (already running), loaded the unit, started it, or
+     * reloaded it after rewriting an older install's plist (macOS).
+     */
+    action: "already-running" | "loaded" | "started" | "reloaded";
+    status: DaemonServiceStatus;
+    /** macOS: what happened to an older install's plist before starting. */
+    refresh?: RefreshDaemonPlistResult;
+}
+/**
+ * `hq daemon start`: load the daemon's OS unit when the manager does not have
+ * it, then start it. The unit file must already exist (the caller installs it
+ * first when it does not). Throws when the manager refuses.
+ */
+export declare function startDaemonUnit(host: DaemonHost, deps: InstallDeps & {
+    daemonPid: () => number | null;
+    waitMs?: number;
+}): StartDaemonResult;
 /**
  * PowerShell script that lists Windows sessions as `id|state|DOMAIN\user`
  * lines through WTSEnumerateSessions and WTSQuerySessionInformation. State is

package/dist/lib/daemon/install.js

@@ -18,8 +18,9 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { activateLaunchd, blockingSleep, deactivateLaunchd, defaultRunCommand, installLaunchdPlist, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "../service-manager/launchd.js";
-import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdUnitPath, } from "../service-manager/systemd.js";
+import { activateLaunchd, blockingSleep, bootstrapLaunchd, launchdJobInfo, launchdServiceTarget, deactivateLaunchd, defaultRunCommand, installLaunchdPlist, launchdIsLoaded, launchdPlistPath, launchdPlistProgramArguments, renderLaunchdPlist, } from "../service-manager/launchd.js";
+import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdUnitInfo, systemdUnitPath, } from "../service-manager/systemd.js";
+import { appIndependentLaunchdPlist } from "../service-manager/migration.js";
 import { escapeXml, shellQuote } from "../service-manager/types.js";
 import { readPidLock } from "../mesh/live/daemon/pid-lock.js";
 import { userToolDirs } from "./tools.js";
@@ -108,6 +109,7 @@ function daemonSpec(host) {
         env: host.env ?? {},
         restartSec: 10,
         unitName: DAEMON_SYSTEMD_UNIT,
+        independentOfApp: true,
     };
 }
 function serviceHost(host) {
@@ -454,16 +456,51 @@ export function installDaemonUnit(host, options, deps) {
             });
         }
         catch (err) {
+            const run = deps.run ?? defaultRunCommand;
+            const message = err instanceof Error ? err.message : String(err);
+            const installed = fs.existsSync(plan.unitPath);
+            // The reload gave up with the job unloaded: try the bootstrap again
+            // before reporting, since an unloaded agent never starts at login.
+            if (installed && !launchdIsLoaded(DAEMON_LAUNCHD_LABEL, run, host.uid)) {
+                const retried = retryLaunchdBootstrap(plan.unitPath, run, host.uid, deps.sleep);
+                if (retried.ok)
+                    return { kind: plan.kind, unitPath: plan.unitPath, installed: true, running: true };
+                return { kind: plan.kind, unitPath: plan.unitPath, installed, running: false, error: `${message}\n${retried.error}` };
+            }
+            // The reload failed but launchd still runs the previous definition: a
+            // daemon is running under launchd. Say so, and that the new plist is only
+            // read at the next load (login, or hq daemon start after a bootout).
+            if (installed && launchdIsLoaded(DAEMON_LAUNCHD_LABEL, run, host.uid)) {
+                return {
+                    kind: plan.kind,
+                    unitPath: plan.unitPath,
+                    installed: true,
+                    running: true,
+                    warning: `The daemon is still running under launchd with its previous definition. ${message}`,
+                };
+            }
             return {
                 kind: plan.kind,
                 unitPath: plan.unitPath,
-                installed: fs.existsSync(plan.unitPath),
-                running: launchdIsLoaded(DAEMON_LAUNCHD_LABEL, deps.run ?? defaultRunCommand, host.uid),
-                error: err instanceof Error ? err.message : String(err),
+                installed,
+                running: false,
+                error: message,
             };
         }
-        if (!plist.loaded)
-            return { kind: plan.kind, unitPath: plan.unitPath, installed: true, running: false };
+        if (!plist.loaded) {
+            // installLaunchdPlist found the job unloaded after activating it. That is
+            // a failure, never a quiet success: retry the bootstrap, then report it.
+            const retried = retryLaunchdBootstrap(plan.unitPath, deps.run ?? defaultRunCommand, host.uid, deps.sleep);
+            if (!retried.ok) {
+                return {
+                    kind: plan.kind,
+                    unitPath: plan.unitPath,
+                    installed: true,
+                    running: false,
+                    error: retried.error,
+                };
+            }
+        }
     }
     else if (plan.kind === "schtasks")
         fs.writeFileSync(plan.unitPath, encodeWindowsTaskXml(plan.rendered));
@@ -507,6 +544,278 @@ export function installDaemonUnit(host, options, deps) {
         };
     }
 }
+/** Install-level bootstrap retries after launchd left the job unloaded. */
+export const DAEMON_BOOTSTRAP_RETRIES = 3;
+export const DAEMON_BOOTSTRAP_RETRY_MS = 2_000;
+/**
+ * Bootstrap the daemon agent again when an install left it unloaded, up to
+ * DAEMON_BOOTSTRAP_RETRIES times, then kickstart it. Returns the error that
+ * says the agent is not loaded when every retry failed.
+ */
+export function retryLaunchdBootstrap(plistPath, run, uid, sleep = blockingSleep) {
+    let last = "";
+    for (let attempt = 1; attempt <= DAEMON_BOOTSTRAP_RETRIES; attempt++) {
+        const r = bootstrapLaunchd(plistPath, run, uid, { sleep });
+        if (r.ok && launchdJobInfo(DAEMON_LAUNCHD_LABEL, run, uid).loaded) {
+            run("launchctl", ["kickstart", launchdServiceTarget(plistPath, uid)]);
+            return { ok: true };
+        }
+        last = r.error ?? "launchd does not list the job after bootstrap";
+        if (attempt < DAEMON_BOOTSTRAP_RETRIES)
+            sleep(DAEMON_BOOTSTRAP_RETRY_MS);
+    }
+    const target = launchdServiceTarget(plistPath, uid);
+    return {
+        ok: false,
+        error: `launchctl bootstrap gui/${uid} ${plistPath} failed ${DAEMON_BOOTSTRAP_RETRIES} times: ${last}. ` +
+            `${target} is NOT loaded, so the daemon will not start at login. Retry with: hq daemon start`,
+    };
+}
+/**
+ * Upgrade a daemon LaunchAgent written by an older install (run through the
+ * HQ.app launcher and associated with the app's bundle, which launchd skips
+ * at login) to the app-independent form, and reload it when it is loaded.
+ *
+ * Nothing but `hq daemon install` used to rewrite the unit, so a machine that
+ * only ever self-updated kept the old plist. This runs from `hq daemon start`,
+ * and from the detached helper the managed daemon spawns at startup when it
+ * finds the old plist (see daemonPlistNeedsRefresh). It must not run inside
+ * the daemon's own job: the bootout would end the caller before the bootstrap.
+ */
+export function refreshDaemonPlist(host, deps) {
+    const plistPath = launchdPlistPath(host.home, { label: DAEMON_LAUNCHD_LABEL });
+    if (!fs.existsSync(plistPath))
+        return { action: "none", plistPath };
+    const source = fs.readFileSync(plistPath, "utf8");
+    let updated;
+    try {
+        updated = appIndependentLaunchdPlist(source);
+    }
+    catch (err) {
+        return { action: "current", plistPath, error: `${err instanceof Error ? err.message : String(err)}: ${plistPath}. Run: hq daemon install` };
+    }
+    if (updated === null) {
+        // The file is current, but an earlier reload may have failed and left
+        // launchd running the old definition: reload it so it matches the file.
+        if (!loadedJobRunsThroughApp(launchdJobInfo(DAEMON_LAUNCHD_LABEL, deps.run, host.uid)))
+            return { action: "current", plistPath };
+    }
+    else {
+        const mode = fs.statSync(plistPath).mode & 0o777;
+        const tmp = `${plistPath}.${process.pid}.refresh.tmp`;
+        fs.writeFileSync(tmp, updated, { mode });
+        fs.renameSync(tmp, plistPath);
+        if (!launchdIsLoaded(DAEMON_LAUNCHD_LABEL, deps.run, host.uid))
+            return { action: "rewritten", plistPath };
+    }
+    try {
+        activateLaunchd(plistPath, deps.run, host.uid, { sleep: deps.sleep });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (launchdIsLoaded(DAEMON_LAUNCHD_LABEL, deps.run, host.uid)) {
+            // The old definition still runs; the rewritten file is what launchd reads at login.
+            return { action: "rewritten", plistPath, error: message };
+        }
+        const retried = retryLaunchdBootstrap(plistPath, deps.run, host.uid, deps.sleep);
+        if (!retried.ok)
+            return { action: "rewritten", plistPath, error: `${message}\n${retried.error}` };
+    }
+    return { action: "reloaded", plistPath };
+}
+/** launchd's loaded copy of the daemon job runs through the HQ.app launcher. */
+function loadedJobRunsThroughApp(job) {
+    return job.loaded && job.arguments !== undefined && job.arguments.includes("--hq-launchd-task");
+}
+/** The daemon plist on disk still runs through HQ.app or names its bundle. */
+export function daemonPlistNeedsRefresh(home) {
+    const plistPath = launchdPlistPath(home, { label: DAEMON_LAUNCHD_LABEL });
+    try {
+        return appIndependentLaunchdPlist(fs.readFileSync(plistPath, "utf8")) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+export function describeSupervision(status) {
+    switch (status.supervision) {
+        case "managed":
+            return `running under the service manager (${status.detail})`;
+        case "unmanaged":
+            return `running outside the service manager (${status.detail}); it will not come back after a crash or restart. Run: hq daemon start`;
+        case "not-loaded":
+            return `not loaded (${status.detail}). Run: hq daemon start`;
+    }
+}
+/**
+ * Ask launchd, systemd or Task Scheduler whether the daemon's unit is loaded,
+ * and combine that with the pid lock. `daemonPid` is the live daemon from the
+ * lock (null when none runs).
+ */
+export function daemonServiceStatus(host, run, daemonPid) {
+    const classify = (base, pidsComparable = false) => {
+        // Loaded but not running (launchd throttling a restart) is still managed:
+        // the manager brings it back. A live daemon the manager does not report
+        // as running was started some other way. When the unit runs node directly
+        // its pid must be the daemon's: a different pid is a second daemon that
+        // lost the lock (for example to one the desktop app hosts) and is being
+        // respawned. An older install's plist runs the HQ.app launcher, whose pid
+        // is never the daemon's, so pids are not compared there.
+        let supervision;
+        if (!base.loaded)
+            supervision = daemonPid !== null ? "unmanaged" : "not-loaded";
+        else if (daemonPid !== null && !base.active)
+            supervision = "unmanaged";
+        else if (pidsComparable && daemonPid !== null && base.managerPid !== undefined && base.managerPid !== daemonPid) {
+            supervision = "unmanaged";
+        }
+        else
+            supervision = "managed";
+        return { ...base, supervision, daemonPid };
+    };
+    switch (host.platform) {
+        case "darwin": {
+            const plist = launchdPlistPath(host.home, { label: DAEMON_LAUNCHD_LABEL });
+            const unitInstalled = fs.existsSync(plist);
+            const job = launchdJobInfo(DAEMON_LAUNCHD_LABEL, run, host.uid);
+            const target = `gui/${host.uid}/${DAEMON_LAUNCHD_LABEL}`;
+            let fileNodeDirect;
+            try {
+                fileNodeDirect = unitInstalled && !launchdPlistProgramArguments(fs.readFileSync(plist, "utf8")).includes("--hq-launchd-task");
+            }
+            catch {
+                fileNodeDirect = false;
+            }
+            // What runs now is the loaded job, which differs from the file on disk
+            // after a rewrite whose reload failed: go by the job when launchd prints it.
+            const jobThroughApp = loadedJobRunsThroughApp(job);
+            const nodeDirect = job.loaded && job.arguments !== undefined ? !jobThroughApp : fileNodeDirect;
+            const warnings = [];
+            if (unitInstalled && daemonPlistNeedsRefresh(host.home)) {
+                warnings.push(`${plist} still runs through HQ.app, so launchd skips the daemon at login. Run: hq daemon start`);
+            }
+            else if (jobThroughApp) {
+                warnings.push(`launchd still runs the daemon's previous definition, which goes through HQ.app; ${plist} was rewritten but not reloaded. Run: hq daemon start`);
+            }
+            const pidMismatch = nodeDirect && job.pid !== undefined && daemonPid !== null && job.pid !== daemonPid;
+            const detail = job.loaded
+                ? `launchd ${target}: ${job.state ?? "loaded"}${job.pid ? `, pid ${job.pid}` : ""}` +
+                    (pidMismatch ? `, not the daemon holding the lock (pid ${daemonPid})` : "")
+                : `launchd has no ${target}${unitInstalled ? "" : ` and ${plist} is missing`}`;
+            return classify({
+                manager: "launchd",
+                unitInstalled,
+                loaded: job.loaded,
+                active: job.loaded && (job.pid !== undefined || job.state === "running"),
+                ...(job.pid ? { managerPid: job.pid } : {}),
+                detail,
+                ...(warnings.length > 0 ? { warnings } : {}),
+            }, nodeDirect);
+        }
+        case "linux": {
+            const systemUnit = path.join(host.systemUnitDir, DAEMON_SYSTEMD_UNIT);
+            const userUnit = path.join(host.home, ".config", "systemd", "user", DAEMON_SYSTEMD_UNIT);
+            const scope = fs.existsSync(systemUnit) ? "system" : "user";
+            const unitInstalled = scope === "system" || fs.existsSync(userUnit);
+            const info = systemdUnitInfo(DAEMON_SYSTEMD_UNIT, run, scope);
+            return classify({
+                manager: scope === "system" ? "systemd-system" : "systemd-user",
+                unitInstalled,
+                loaded: unitInstalled && info.enabled,
+                active: info.active,
+                ...(info.pid ? { managerPid: info.pid } : {}),
+                detail: `systemd ${scope} ${DAEMON_SYSTEMD_UNIT}: ${info.enabledState}, ${info.activeState}${info.pid ? `, pid ${info.pid}` : ""}`,
+            }, true);
+        }
+        case "win32": {
+            const task = windowsTaskName({ windowsSid: host.windowsSid, windowsUser: host.windowsUser });
+            const probe = run("schtasks.exe", ["/Query", "/TN", task, "/FO", "CSV", "/NH"]);
+            const loaded = probe.status === 0;
+            const active = loaded && /,\s*"?Running"?\s*$/i.test(probe.stdout.replace(/\0/g, "").trim());
+            return classify({
+                manager: "schtasks",
+                unitInstalled: loaded,
+                loaded,
+                active,
+                detail: loaded ? `Scheduled Task ${task}${active ? " is running" : " is not running"}` : `no Scheduled Task ${task}`,
+            });
+        }
+        default:
+            return { supervision: daemonPid !== null ? "unmanaged" : "not-loaded", manager: "none", unitInstalled: false, loaded: false, active: false, daemonPid, detail: `${host.platform} has no supported service manager` };
+    }
+}
+/**
+ * `hq daemon start`: load the daemon's OS unit when the manager does not have
+ * it, then start it. The unit file must already exist (the caller installs it
+ * first when it does not). Throws when the manager refuses.
+ */
+export function startDaemonUnit(host, deps) {
+    const sleep = deps.sleep ?? blockingSleep;
+    // An older install's plist runs through HQ.app and is skipped at login:
+    // rewrite it first, so the unit this loads or starts is the fixed one.
+    const previousPid = deps.daemonPid();
+    const refresh = host.platform === "darwin" ? refreshDaemonPlist(host, { run: deps.run, sleep }) : undefined;
+    const withRefresh = refresh && (refresh.action === "rewritten" || refresh.action === "reloaded" || refresh.error) ? { refresh } : {};
+    const waitForManaged = (action, previousPid) => {
+        const waitMs = deps.waitMs ?? 15_000;
+        const ready = (s) => s.supervision === "managed" && s.daemonPid !== null && (previousPid === null || s.daemonPid !== previousPid);
+        let status = daemonServiceStatus(host, deps.run, deps.daemonPid());
+        for (let waited = 0; waited < waitMs && !ready(status); waited += 500) {
+            sleep(500);
+            status = daemonServiceStatus(host, deps.run, deps.daemonPid());
+        }
+        return { action, status, ...withRefresh };
+    };
+    if (refresh?.action === "reloaded")
+        return waitForManaged("reloaded", previousPid);
+    const before = daemonServiceStatus(host, deps.run, deps.daemonPid());
+    if (before.supervision === "managed" && before.daemonPid !== null)
+        return { action: "already-running", status: before, ...withRefresh };
+    let action = "started";
+    switch (before.manager) {
+        case "launchd": {
+            const plist = launchdPlistPath(host.home, { label: DAEMON_LAUNCHD_LABEL });
+            const target = launchdServiceTarget(plist, host.uid);
+            if (!before.loaded) {
+                const r = retryLaunchdBootstrap(plist, deps.run, host.uid, sleep);
+                if (!r.ok)
+                    throw new Error(r.error);
+                action = "loaded";
+            }
+            else {
+                const kick = deps.run("launchctl", ["kickstart", target]);
+                if (kick.status !== 0)
+                    throw commandError(`launchctl kickstart ${target}`, kick);
+            }
+            break;
+        }
+        case "systemd-user":
+        case "systemd-system": {
+            const prefix = before.manager === "systemd-user" ? ["--user"] : [];
+            if (before.manager === "systemd-system" && !host.isRoot) {
+                throw new Error("The daemon runs as a system unit on this box; starting it needs root. Run: sudo hq daemon start");
+            }
+            deps.run("systemctl", [...prefix, "daemon-reload"]);
+            const enable = deps.run("systemctl", [...prefix, "enable", "--now", DAEMON_SYSTEMD_UNIT]);
+            if (enable.status !== 0)
+                throw commandError(["systemctl", ...prefix, "enable", "--now", DAEMON_SYSTEMD_UNIT].join(" "), enable);
+            if (!before.loaded)
+                action = "loaded";
+            break;
+        }
+        case "schtasks": {
+            const task = windowsTaskName(host);
+            const r = deps.run("schtasks.exe", ["/Run", "/TN", task]);
+            if (r.status !== 0)
+                throw commandError("schtasks /Run", r);
+            break;
+        }
+        case "none":
+            throw new Error(`${host.platform} has no supported service manager; start the daemon with: hq daemon run`);
+    }
+    // Wait for the manager's daemon to take the lock.
+    return waitForManaged(action, null);
+}
 /** A lock record names a different daemon than `previous` (new pid or new start time). */
 function isNewDaemon(now, previous) {
     return !previous || now.pid !== previous.pid || now.ts !== previous.ts;

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

@@ -16,7 +16,7 @@
  * user can edit), and a restore checks each one lands in the system unit
  * folder, so nobody but root decides what gets installed there.
  */
-import type { RunCommand } from "../service-manager/launchd.js";
+import { type RunCommand, type SleepFn } from "../service-manager/launchd.js";
 import { type LegacyUnit } from "./legacy.js";
 export interface AdoptedUnit extends LegacyUnit {
     /** Where the unit's definition (plist, unit file, task XML) was moved. */
@@ -43,6 +43,8 @@ export interface MigrateDeps {
         uid: number;
     };
     now?: () => number;
+    /** Blocking sleep for launchd bootstrap retries (tests inject). */
+    sleep?: SleepFn;
     /** Tests inject a failing writer. */
     writeRecord?: (recordPath: string, units: AdoptedUnit[]) => void;
 }

package/dist/lib/daemon/migrate.js

@@ -18,6 +18,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { bootstrapLaunchd } from "../service-manager/launchd.js";
 import { legacyMeshUnitsToRetire } from "./legacy.js";
 import { ensurePrivateDir } from "./paths.js";
 export function readAdoptedUnits(recordPath) {
@@ -102,7 +103,16 @@ function adoptOne(unit, deps) {
             }
             if (!fs.existsSync(unit.path))
                 return { movedTo: unit.path, definitionMissing: true };
-            moveFile(unit.path, to);
+            try {
+                moveFile(unit.path, to);
+            }
+            catch (err) {
+                // The agent is booted out but its plist did not move: load it again,
+                // so a failed takeover never leaves the service off.
+                const back = bootstrapLaunchd(unit.path, deps.run, deps.uid, { sleep: deps.sleep });
+                const reloaded = back.ok ? "it was loaded again" : `loading it again also failed (${back.error}); load it with: launchctl bootstrap gui/${deps.uid} ${unit.path}`;
+                throw new Error(`${err.message}; ${reloaded}`, { cause: err });
+            }
             return { movedTo: to };
         }
         case "systemd-user":
@@ -198,7 +208,9 @@ function restoreOne(unit, deps) {
             if (unit.definitionMissing)
                 throw new Error("the original LaunchAgent plist is missing; this unit cannot be restored");
             moveBack(unit, unit.path);
-            must(deps.run, "launchctl", ["bootstrap", `gui/${deps.uid}`, unit.path]);
+            const loaded = bootstrapLaunchd(unit.path, deps.run, deps.uid, { sleep: deps.sleep });
+            if (!loaded.ok)
+                throw new Error(`launchctl bootstrap gui/${deps.uid} ${unit.path} failed after ${loaded.attempts} attempts: ${loaded.error}`);
             return;
         }
         case "systemd-user":

package/dist/lib/daemon/plist-refresh.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Upgrade an older install's daemon LaunchAgent without a manual
+ * `hq daemon install`.
+ *
+ * Self-update and `hq update` restart the daemon through a control request and
+ * never rewrite its unit, so a Mac that only ever self-updated keeps the plist
+ * that runs through HQ.app and names its bundle, which launchd skips at login.
+ * When the managed daemon starts and finds that plist, it spawns a detached
+ * `hq daemon start`, which rewrites the plist and reloads it (see
+ * refreshDaemonPlist). The helper runs in its own session, outside the
+ * daemon's job, so the bootout that ends this daemon does not end the helper
+ * before it bootstraps the new definition.
+ */
+/** At most one helper per this long, so a rewrite that keeps failing cannot loop. */
+export declare const PLIST_REFRESH_RETRY_MS: number;
+export declare const PLIST_REFRESH_MARKER = "plist-refresh.json";
+export type PlistRefreshOutcome = "not-applicable" | "current" | "recent" | "spawned";
+export interface PlistRefreshDeps {
+    platform: NodeJS.Platform;
+    /** Started by launchd (`daemon run --managed`) and not hosted by an app. */
+    managedByLaunchd: boolean;
+    home: string;
+    /** ~/.hq/daemon: holds the marker and the helper's log. */
+    daemonRoot: string;
+    nodeBinary: string;
+    hqBinary: string;
+    env: NodeJS.ProcessEnv;
+    now?: () => number;
+    needsRefresh?: (home: string) => boolean;
+    spawnHelper?: (command: string, args: string[], logPath: string, env: NodeJS.ProcessEnv) => void;
+    log: (level: "info" | "warn", line: string) => void;
+}
+export declare function scheduleDaemonPlistRefresh(deps: PlistRefreshDeps): PlistRefreshOutcome;
+//# sourceMappingURL=plist-refresh.d.ts.map

package/dist/lib/daemon/plist-refresh.js

@@ -0,0 +1,62 @@
+/**
+ * Upgrade an older install's daemon LaunchAgent without a manual
+ * `hq daemon install`.
+ *
+ * Self-update and `hq update` restart the daemon through a control request and
+ * never rewrite its unit, so a Mac that only ever self-updated keeps the plist
+ * that runs through HQ.app and names its bundle, which launchd skips at login.
+ * When the managed daemon starts and finds that plist, it spawns a detached
+ * `hq daemon start`, which rewrites the plist and reloads it (see
+ * refreshDaemonPlist). The helper runs in its own session, outside the
+ * daemon's job, so the bootout that ends this daemon does not end the helper
+ * before it bootstraps the new definition.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { daemonPlistNeedsRefresh } from "./install.js";
+import { ensurePrivateDir } from "./paths.js";
+/** At most one helper per this long, so a rewrite that keeps failing cannot loop. */
+export const PLIST_REFRESH_RETRY_MS = 60 * 60_000;
+export const PLIST_REFRESH_MARKER = "plist-refresh.json";
+function defaultSpawnHelper(command, args, logPath, env) {
+    const fd = fs.openSync(logPath, "a", 0o600);
+    try {
+        const child = spawn(command, args, { detached: true, stdio: ["ignore", fd, fd], env });
+        child.unref();
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function scheduleDaemonPlistRefresh(deps) {
+    if (deps.platform !== "darwin" || !deps.managedByLaunchd)
+        return "not-applicable";
+    if (!(deps.needsRefresh ?? daemonPlistNeedsRefresh)(deps.home))
+        return "current";
+    const now = (deps.now ?? Date.now)();
+    const marker = path.join(deps.daemonRoot, PLIST_REFRESH_MARKER);
+    try {
+        const last = JSON.parse(fs.readFileSync(marker, "utf8"));
+        if (typeof last.attemptedAt === "number" && now - last.attemptedAt < PLIST_REFRESH_RETRY_MS) {
+            deps.log("warn", "the daemon LaunchAgent still runs through HQ.app; a rewrite was tried within the last hour. Run: hq daemon start");
+            return "recent";
+        }
+    }
+    catch {
+        // No marker yet.
+    }
+    ensurePrivateDir(path.join(deps.daemonRoot, "logs"));
+    const tmp = `${marker}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify({ attemptedAt: now })}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, marker);
+    // launchd marks its jobs' processes with XPC_SERVICE_NAME; the helper is not the job.
+    const env = { ...deps.env };
+    delete env.XPC_SERVICE_NAME;
+    const logPath = path.join(deps.daemonRoot, "logs", "plist-refresh.log");
+    (deps.spawnHelper ?? defaultSpawnHelper)(deps.nodeBinary, [deps.hqBinary, "daemon", "start"], logPath, env);
+    deps.log("info", "the daemon LaunchAgent runs through HQ.app, which launchd skips at login; started `hq daemon start` to rewrite and reload it " +
+        `(log: ${logPath})`);
+    return "spawned";
+}
+//# sourceMappingURL=plist-refresh.js.map