@indigoai-us/hq-cli 5.345.201 → 5.345.203

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

package/dist/lib/daemon/run.js

@@ -36,6 +36,7 @@ import { createLanesReconcileWatcher } from "./lanes-reconcile-watcher.js";
 import { findLegacyUnits, legacyMeshUnitsToRetire, legacyOwnerLookup, } from "./legacy.js";
 import { readLegacySyncEnv } from "./legacy-sync-env.js";
 import { readVaultSyncSwitches, unreadableSwitchesWarning, writeVaultSyncSwitches } from "../vault-sync-switches.js";
+import { scheduleDaemonPlistRefresh } from "./plist-refresh.js";
 import { acquireDaemonLock, isProcessAlive, processCommandLine, releaseDaemonLock } from "./lock.js";
 import { retireLegacyMeshUnits } from "./migrate.js";
 import { daemonDir as meshDaemonDir, daemonPidPath as meshDaemonPidPath } from "../mesh/live/daemon/paths.js";
@@ -658,6 +659,21 @@ export async function runDaemon(opts) {
     }
     const hostNote = opts.host ? `, hosted by the ${opts.host} app` : "";
     log("info", `starting hq daemon (pid ${process.pid}) as ${machineType} (${detected.detail})${hostNote}`);
+    try {
+        scheduleDaemonPlistRefresh({
+            platform,
+            managedByLaunchd: opts.managed === true && opts.host === undefined,
+            home,
+            daemonRoot: paths.root,
+            nodeBinary: opts.nodeBinary,
+            hqBinary: opts.hqBinary,
+            env,
+            log,
+        });
+    }
+    catch (err) {
+        log("warn", `could not check the daemon LaunchAgent: ${err instanceof Error ? err.message : String(err)}`);
+    }
     // On Linux, services can outlive a daemon (KillMode=process). Adopt the ones
     // the previous daemon handed over and stop any others it left behind before
     // starting anything, so a service never runs twice.
@@ -1264,6 +1280,15 @@ export async function runDaemon(opts) {
             read: () => readUnitHolds(paths.holdsPath),
             write: (holds) => writeUnitHolds(paths.holdsPath, holds),
         },
+        pidAlive: (pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (err) {
+                return err.code === "EPERM";
+            }
+        },
         exitOutputTail: (unitId) => {
             // An adopted unit was started by an earlier daemon; its output start is unknown.
             const offset = unitLogOffsets.get(unitId);

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

@@ -0,0 +1,71 @@
+/**
+ * The daemon's sync-engine self-check (`hq daemon service sync-core-selfcheck`).
+ *
+ * It reads the supervisor's state and holds and finds engine units
+ * (`sync-core:<vault>`) that have been held, or failing without a heartbeat,
+ * for more than ATTENTION_AFTER_MS. When there are any, it sends one DM to the
+ * person signed in on this machine, at most once a day per machine whichever
+ * units are affected, naming every affected vault in that one DM. The 16-hour outage of 2026-11-03 was
+ * found by hand; this makes the next one reach the owner.
+ */
+import type { DaemonState, PersistedHolds } from "./supervisor.js";
+/** An engine unit that has been held or failing this long needs a person. */
+export declare const ATTENTION_AFTER_MS: number;
+/** This machine sends at most one self-check DM per this long. */
+export declare const REPORT_INTERVAL_MS: number;
+export interface EngineUnitProblem {
+    unitId: string;
+    /** Epoch ms since when the unit has been held or failing. */
+    since: number;
+    /** One line for the DM. */
+    what: string;
+}
+/** Engine units held, or failing without a heartbeat, for more than ATTENTION_AFTER_MS at `now`. */
+export declare function engineUnitsNeedingAttention(state: DaemonState | null, holds: PersistedHolds, now: number, 
+/** False for a vault that is skipped on this machine or not on the rollout. */
+wanted?: (vaultUid: string) => boolean): EngineUnitProblem[];
+export interface SelfCheckRecord {
+    lastSentAt: number;
+    /** Sorted unit ids last reported (for the log; the rate limit ignores them). */
+    units: string[];
+}
+export declare function readSelfCheckRecord(file: string): SelfCheckRecord | null;
+export declare function writeSelfCheckRecord(file: string, record: SelfCheckRecord): void;
+/**
+ * Send now: something is wrong and this machine has not sent a self-check DM
+ * in the last day. Which units are affected does not matter, so units that
+ * take turns failing cannot send a DM on every change.
+ */
+export declare function shouldReport(problems: EngineUnitProblem[], last: SelfCheckRecord | null, now: number): boolean;
+/** The DM text for the owner. Plain, with the commands that fix each case. */
+export declare function selfCheckMessage(problems: EngineUnitProblem[], machine: string, 
+/** A name for a vault (company slug, "personal"), when known. */
+vaultName?: (vaultUid: string) => string | undefined): {
+    body: string;
+    details: string;
+};
+export interface SelfCheckDeps {
+    statePath: string;
+    holdsPath: string;
+    recordPath: string;
+    now: () => number;
+    machine: string;
+    readState: () => DaemonState | null;
+    readHolds: () => PersistedHolds;
+    /** False for a vault that is skipped here or not on the rollout. Default: every vault. */
+    wanted?: (vaultUid: string) => boolean;
+    /** A name for a vault, for the DM. */
+    vaultName?: (vaultUid: string) => string | undefined;
+    /**
+     * Send the DM to the person signed in on this machine; resolves to who it
+     * went to, or null when no person is signed in (an agent identity).
+     */
+    sendToOwner: (message: {
+        body: string;
+        details: string;
+    }) => Promise<string | null>;
+    log: (line: string) => void;
+}
+export type SelfCheckOutcome = "healthy" | "reported" | "already-reported" | "no-owner";
+export declare function runSelfCheck(deps: SelfCheckDeps): Promise<SelfCheckOutcome>;
+//# sourceMappingURL=selfcheck.d.ts.map