@indigoai-us/hq-cli 5.162.0 → 5.163.0

package/dist/lib/daemon/handoff.js

@@ -0,0 +1,136 @@
+/**
+ * Lets commands that manage one service on their own (`hq bot start`, and the
+ * older per-service installers such as `hq mesh daemon install`) hand the job
+ * to the daemon when the daemon runs that service, so a second copy is never
+ * started or installed beside it.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { DEFAULT_SERVICES, enabledServices, isServiceName } from "./catalog.js";
+import { readDaemonConfig, writeDaemonConfig } from "./config.js";
+import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from "./install.js";
+import { isDaemonProcess, runningDaemonPid } from "./lock.js";
+import { detectMachineType } from "./machine-type.js";
+import { daemonPaths } from "./paths.js";
+import { writeControlRequest } from "./requests.js";
+/** Statuses where the daemon itself owns the unit's process. */
+const OWNED = new Set(["running", "backoff", "exited", "idle", "stopped"]);
+/** The live daemon's state, or null when no daemon is running. */
+function liveState(paths, alive) {
+    if (runningDaemonPid(paths.lockPath, alive) === null)
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(paths.statePath, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw new Error(`could not read hq daemon state at ${paths.statePath}: ${err.message}`);
+    }
+}
+/** A live daemon runs `unitId` (or held it after it was stopped from outside). */
+export function daemonSupervises(paths, unitId, alive = (pid) => isDaemonProcess(pid)) {
+    const unit = liveState(paths, alive)?.units?.find((u) => u.id === unitId);
+    return unit !== undefined && OWNED.has(unit.status);
+}
+/**
+ * A live daemon runs the service `unitId` belongs to (`bots` for
+ * `bots:<name>`), so it will run this instance once its plan includes it. For
+ * a bot created since the daemon last read its plan; the caller must first
+ * rule out an older unit that runs the instance itself.
+ */
+export function daemonWillSupervise(paths, unitId, alive = (pid) => isDaemonProcess(pid)) {
+    const service = unitId.split(":")[0];
+    if (liveState(paths, alive)?.units?.some((u) => u.service === service))
+        return true;
+    // The first bot on a fresh daemon: no bots unit is planned yet, but the saved config turns the service on.
+    return isServiceName(service) && daemonRunsService(paths, service, alive);
+}
+/** The live daemon's child for `unitId` is `pid` (a bot started before the daemon is not). */
+export function daemonOwnsProcess(paths, unitId, pid, alive = (p) => isDaemonProcess(p)) {
+    return liveState(paths, alive)?.units?.find((u) => u.id === unitId)?.pid === pid;
+}
+/** A live daemon has `service` enabled for its saved machine type, whether or not it has planned a unit for it yet. */
+export function daemonRunsService(paths, service, alive = (pid) => isDaemonProcess(pid)) {
+    if (runningDaemonPid(paths.lockPath, alive) === null)
+        return false;
+    const config = readDaemonConfig(paths.configPath);
+    return config.machineType !== undefined && enabledServices(config.machineType, config).includes(service);
+}
+/** Ask the running daemon to (re)start a unit it supervises. */
+export function askDaemonToStart(paths, unitId) {
+    writeControlRequest(paths.requestsDir, { action: "restart", unit: unitId });
+}
+/** Ask the running daemon to stop a unit and keep it down until it is started again. */
+export function askDaemonToStop(paths, unitId) {
+    writeControlRequest(paths.requestsDir, { action: "stop", unit: unitId });
+}
+/** The `hq daemon` OS unit is installed on this machine (for this user, or as the box's system unit). */
+export function daemonUnitInstalled(host) {
+    switch (host.platform) {
+        case "darwin":
+            return fs.existsSync(path.join(host.home, "Library", "LaunchAgents", `${DAEMON_LAUNCHD_LABEL}.plist`));
+        case "win32":
+            return host.windowsTaskExists(DAEMON_WINDOWS_TASK);
+        default:
+            return (fs.existsSync(path.join(host.home, ".config", "systemd", "user", DAEMON_SYSTEMD_UNIT)) ||
+                fs.existsSync(path.join(host.systemUnitDir ?? SYSTEM_UNIT_DIR, DAEMON_SYSTEMD_UNIT)));
+    }
+}
+/**
+ * For an older per-service install command: when hq daemon is installed here,
+ * make sure it runs `services` and return what to tell the user instead of
+ * installing a separate unit. Returns null when hq daemon is not installed, so
+ * the older install runs exactly as before.
+ */
+export function handOffInstall(opts) {
+    if (!opts.installed)
+        return null;
+    const config = readDaemonConfig(opts.paths.configPath);
+    let rootNote = "";
+    if (opts.hqRoot && config.hqRoot !== opts.hqRoot) {
+        config.hqRoot = opts.hqRoot;
+        rootNote = ` Its HQ folder is now ${opts.hqRoot}.`;
+    }
+    const defaults = DEFAULT_SERVICES[opts.machineType];
+    let changed = false;
+    for (const service of opts.services) {
+        if (config.disable.includes(service)) {
+            config.disable = config.disable.filter((s) => s !== service);
+            changed = true;
+        }
+        if (!defaults.includes(service) && !config.enable.includes(service)) {
+            config.enable = [...config.enable, service];
+            changed = true;
+        }
+    }
+    if (changed || rootNote)
+        writeDaemonConfig(opts.paths.configPath, config);
+    const names = opts.services.join(", ");
+    return `hq daemon runs ${names} on this machine, so there is nothing separate to install.${rootNote} See \`hq daemon status\`.`;
+}
+/** handOffInstall for this machine and user, for the older install commands. */
+export function handOffInstallHere(services, env = process.env, opts = {}) {
+    const home = os.homedir();
+    const installed = daemonUnitInstalled({
+        platform: process.platform,
+        home,
+        windowsTaskExists: (task) => spawnSync("schtasks.exe", ["/Query", "/TN", task], { encoding: "utf8", windowsHide: true }).status === 0,
+    });
+    if (!installed)
+        return null;
+    const paths = daemonPaths(home, env);
+    const config = readDaemonConfig(paths.configPath);
+    const machineType = detectMachineType(undefined, {
+        platform: process.platform,
+        env,
+        home,
+        savedType: config.machineType,
+        existsSync: fs.existsSync,
+        readFileSync: (p) => fs.readFileSync(p, "utf8"),
+    }).type;
+    return handOffInstall({ paths, installed, machineType, services, hqRoot: opts.hqRoot });
+}
+//# sourceMappingURL=handoff.js.map

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

@@ -0,0 +1,76 @@
+/**
+ * Install / uninstall the ONE OS unit that runs `node <hq> daemon run --managed`.
+ * `--managed` tells the daemon a service manager relaunches it when it exits,
+ * which is how it restarts itself onto a new CLI version after an update.
+ *
+ * - macOS: LaunchAgent ai.getindigo.hq-daemon (RunAtLoad + KeepAlive)
+ * - Linux, per-user: systemd user unit hq-daemon.service
+ * - Linux, system (outposts and agent boxes): /etc/systemd/system/hq-daemon.service
+ *   running as the box's login user; needs root
+ * - Windows: per-user logon Scheduled Task ai.getindigo.hq-daemon
+ * - anything else: no unit; the caller prints the command to run
+ *
+ * The unit never names services. `hq daemon run` reads the machine type and
+ * overrides from ~/.hq/daemon/config.json, so the unit does not change when
+ * 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 { MachineType } from "./machine-type.js";
+export declare const DAEMON_LAUNCHD_LABEL = "ai.getindigo.hq-daemon";
+export declare const DAEMON_SYSTEMD_UNIT = "hq-daemon.service";
+export declare const DAEMON_WINDOWS_TASK = "ai.getindigo.hq-daemon";
+export declare const SYSTEM_UNIT_DIR = "/etc/systemd/system";
+export type InstallScope = "user" | "system";
+export interface DaemonHost {
+    platform: NodeJS.Platform;
+    home: string;
+    nodeBinary: string;
+    hqBinary: string;
+    /** ~/.hq/daemon (or HQ_DAEMON_DIR). */
+    daemonDir: string;
+    uid: number;
+    isRoot: boolean;
+    /** `DOMAIN\user` the Windows task runs as. */
+    windowsUser: string;
+    /** conhost.exe path when `--headless` is supported, else undefined. */
+    windowsHeadlessLauncher: string | undefined;
+    /** Where system units are written (tests point this at a temp dir). */
+    systemUnitDir: string;
+    /** Extra environment baked into the unit (PATH of the installing shell, HQ_DAEMON_DIR). */
+    env?: Record<string, string>;
+}
+export interface InstallOptions {
+    scope: InstallScope;
+    /** Login user a system unit runs as. Required for scope "system". */
+    runAsUser?: string;
+    /** That user's home directory, from the account database. Required for scope "system". */
+    runAsHome?: string;
+}
+export interface DaemonUnitPlan {
+    kind: "launchd" | "systemd-user" | "systemd-system" | "schtasks" | "manual";
+    unitPath: string;
+    rendered: string;
+    manualCommand?: string;
+}
+export interface DaemonUnitResult {
+    kind: DaemonUnitPlan["kind"];
+    unitPath: string;
+    installed: boolean;
+    running: boolean;
+    error?: string;
+    manualCommand?: string;
+}
+export interface InstallDeps {
+    run: RunCommand;
+}
+/** Boxes run the daemon as a system unit; everything else per user. */
+export declare function installScopeFor(machineType: MachineType): InstallScope;
+export declare function planDaemonUnit(host: DaemonHost, options: InstallOptions): DaemonUnitPlan;
+export declare function installDaemonUnit(host: DaemonHost, options: InstallOptions, deps: InstallDeps): DaemonUnitResult;
+export declare function uninstallDaemonUnit(host: DaemonHost, options: InstallOptions, deps: InstallDeps): {
+    kind: DaemonUnitPlan["kind"];
+    unitPath: string;
+    removed: boolean;
+};
+//# sourceMappingURL=install.d.ts.map

package/dist/lib/daemon/install.js

@@ -0,0 +1,299 @@
+/**
+ * Install / uninstall the ONE OS unit that runs `node <hq> daemon run --managed`.
+ * `--managed` tells the daemon a service manager relaunches it when it exits,
+ * which is how it restarts itself onto a new CLI version after an update.
+ *
+ * - macOS: LaunchAgent ai.getindigo.hq-daemon (RunAtLoad + KeepAlive)
+ * - Linux, per-user: systemd user unit hq-daemon.service
+ * - Linux, system (outposts and agent boxes): /etc/systemd/system/hq-daemon.service
+ *   running as the box's login user; needs root
+ * - Windows: per-user logon Scheduled Task ai.getindigo.hq-daemon
+ * - anything else: no unit; the caller prints the command to run
+ *
+ * The unit never names services. `hq daemon run` reads the machine type and
+ * overrides from ~/.hq/daemon/config.json, so the unit does not change when
+ * services are added. Every service-manager call goes through `run`, so tests
+ * never touch launchctl, systemctl or schtasks.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { activateLaunchd, deactivateLaunchd, launchdPlistPath, renderLaunchdPlist, } from "../service-manager/launchd.js";
+import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdUnitPath, } from "../service-manager/systemd.js";
+import { escapeXml, shellQuote } from "../service-manager/types.js";
+import { readPidLock } from "../mesh/live/daemon/pid-lock.js";
+export const DAEMON_LAUNCHD_LABEL = "ai.getindigo.hq-daemon";
+export const DAEMON_SYSTEMD_UNIT = "hq-daemon.service";
+export const DAEMON_WINDOWS_TASK = "ai.getindigo.hq-daemon";
+export const SYSTEM_UNIT_DIR = "/etc/systemd/system";
+/** Boxes run the daemon as a system unit; everything else per user. */
+export function installScopeFor(machineType) {
+    return machineType === "outpost" || machineType === "agent-box" ? "system" : "user";
+}
+function daemonSpec(host) {
+    return {
+        name: "daemon",
+        label: DAEMON_LAUNCHD_LABEL,
+        description: "HQ daemon: runs this machine's HQ background services",
+        args: ["daemon", "run", "--managed"],
+        logPath: path.join(host.daemonDir, "logs", "daemon.stdout.log"),
+        workingDir: host.daemonDir,
+        env: host.env ?? {},
+        restartSec: 10,
+        unitName: DAEMON_SYSTEMD_UNIT,
+    };
+}
+function serviceHost(host) {
+    return { home: host.home, nodeBinary: host.nodeBinary, hqBinary: host.hqBinary };
+}
+/**
+ * Output goes to the journal: an `append:` log file would be created by
+ * systemd as root inside the user's home, and the daemon (running as the user)
+ * writes its own logs under ~/.hq/daemon/logs.
+ */
+function renderSystemdSystemUnit(host, user, userHome) {
+    const exec = [host.nodeBinary, host.hqBinary, "daemon", "run", "--managed"].map(shellQuote).join(" ");
+    const env = {
+        ...host.env,
+        HOME: userHome,
+        PATH: host.env?.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+    };
+    const envLines = Object.entries(env)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `Environment=${shellQuote(`${k}=${v}`)}`)
+        .join("\n");
+    return `[Unit]
+Description=HQ daemon: runs this machine's HQ background services (user=${user})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${user}
+ExecStart=${exec}
+WorkingDirectory=${userHome}
+Restart=always
+RestartSec=10
+KillMode=control-group
+TimeoutStopSec=20
+${envLines}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function windowsArgQuote(value) {
+    if (/^[A-Za-z0-9_.:\\/-]+$/.test(value))
+        return value;
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Logon-triggered task for the installing user. InteractiveToken is what an
+ * unprivileged install can register, so the task runs while the user is
+ * logged on. `conhost.exe --headless` keeps a console window from opening.
+ */
+function renderWindowsTaskXml(host) {
+    const user = escapeXml(host.windowsUser);
+    const nodeArg = windowsArgQuote(host.nodeBinary);
+    const hqArg = windowsArgQuote(host.hqBinary);
+    const command = host.windowsHeadlessLauncher ?? host.nodeBinary;
+    // A task cannot set environment variables, so an HQ_DAEMON_DIR override
+    // travels as an argument.
+    const dirOverride = host.env?.HQ_DAEMON_DIR;
+    const runArgs = dirOverride ? `daemon run --managed --daemon-dir ${windowsArgQuote(dirOverride)}` : "daemon run --managed";
+    const args = host.windowsHeadlessLauncher ? `--headless ${nodeArg} ${hqArg} ${runArgs}` : `${hqArg} ${runArgs}`;
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <URI>\\${DAEMON_WINDOWS_TASK}</URI>
+    <Description>HQ daemon: runs this machine's HQ background services</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${user}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${user}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>true</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <DisallowStartOnRemoteAppSession>false</DisallowStartOnRemoteAppSession>
+    <UseUnifiedSchedulingEngine>true</UseUnifiedSchedulingEngine>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${escapeXml(command)}</Command>
+      <Arguments>${escapeXml(args)}</Arguments>
+      <WorkingDirectory>${escapeXml(host.daemonDir)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+/** schtasks reads task XML as UTF-16 LE with a BOM. */
+function encodeWindowsTaskXml(rendered) {
+    return Buffer.from(`\uFEFF${rendered}`, "utf16le");
+}
+export function planDaemonUnit(host, options) {
+    const spec = daemonSpec(host);
+    if (host.platform === "darwin") {
+        return { kind: "launchd", unitPath: launchdPlistPath(host.home, spec), rendered: renderLaunchdPlist(spec, serviceHost(host)) };
+    }
+    if (host.platform === "linux") {
+        if (options.scope === "system") {
+            if (!options.runAsUser) {
+                throw new Error("A system install needs the box's login user. Provisioning writes it to /etc/hq/machine-type (user=<name>).");
+            }
+            if (!options.runAsHome)
+                throw new Error(`Could not find the home directory of ${options.runAsUser}.`);
+            return {
+                kind: "systemd-system",
+                unitPath: path.join(host.systemUnitDir, DAEMON_SYSTEMD_UNIT),
+                rendered: renderSystemdSystemUnit(host, options.runAsUser, options.runAsHome),
+            };
+        }
+        return { kind: "systemd-user", unitPath: systemdUnitPath(host.home, spec), rendered: renderSystemdUserUnit(spec, serviceHost(host)) };
+    }
+    if (host.platform === "win32") {
+        return {
+            kind: "schtasks",
+            unitPath: path.join(host.daemonDir, `${DAEMON_WINDOWS_TASK}.xml`),
+            rendered: renderWindowsTaskXml(host),
+        };
+    }
+    const manualCommand = [host.nodeBinary, host.hqBinary, "daemon", "run"].map(shellQuote).join(" ");
+    return { kind: "manual", unitPath: "", rendered: "", manualCommand };
+}
+function commandError(what, r) {
+    return new Error(`${what} failed: ${r.stderr.trim() || r.stdout.trim() || `exit ${r.status}`}`);
+}
+function activate(plan, host, run) {
+    switch (plan.kind) {
+        case "launchd":
+            activateLaunchd(plan.unitPath, run, host.uid);
+            return;
+        case "systemd-user":
+            activateSystemd(DAEMON_SYSTEMD_UNIT, run);
+            return;
+        case "systemd-system": {
+            const reload = run("systemctl", ["daemon-reload"]);
+            if (reload.status !== 0)
+                throw commandError("systemctl daemon-reload", reload);
+            const enable = run("systemctl", ["enable", "--now", DAEMON_SYSTEMD_UNIT]);
+            if (enable.status !== 0)
+                throw commandError(`systemctl enable --now ${DAEMON_SYSTEMD_UNIT}`, enable);
+            run("systemctl", ["restart", DAEMON_SYSTEMD_UNIT]);
+            return;
+        }
+        case "schtasks": {
+            const create = run("schtasks.exe", ["/Create", "/TN", DAEMON_WINDOWS_TASK, "/XML", plan.unitPath, "/F"]);
+            if (create.status !== 0)
+                throw commandError("schtasks /Create", create);
+            const start = run("schtasks.exe", ["/Run", "/TN", DAEMON_WINDOWS_TASK]);
+            if (start.status !== 0)
+                throw commandError("schtasks /Run", start);
+            return;
+        }
+        case "manual":
+            return;
+    }
+}
+export function installDaemonUnit(host, options, deps) {
+    const plan = planDaemonUnit(host, options);
+    if (plan.kind === "manual") {
+        return { kind: plan.kind, unitPath: "", installed: false, running: false, manualCommand: plan.manualCommand };
+    }
+    if (plan.kind === "systemd-system" && !host.isRoot) {
+        throw new Error("Installing the daemon on a box writes a system unit, which needs root. Run: sudo hq daemon install");
+    }
+    fs.mkdirSync(path.dirname(plan.unitPath), { recursive: true });
+    if (plan.kind !== "systemd-system")
+        fs.mkdirSync(path.join(host.daemonDir, "logs"), { recursive: true });
+    if (plan.kind === "schtasks")
+        fs.writeFileSync(plan.unitPath, encodeWindowsTaskXml(plan.rendered));
+    else
+        fs.writeFileSync(plan.unitPath, plan.rendered, { mode: plan.kind === "systemd-system" ? 0o644 : 0o600 });
+    try {
+        activate(plan, host, deps.run);
+        return { kind: plan.kind, unitPath: plan.unitPath, installed: true, running: true };
+    }
+    catch (err) {
+        return {
+            kind: plan.kind,
+            unitPath: plan.unitPath,
+            installed: true,
+            running: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export function uninstallDaemonUnit(host, options, deps) {
+    // A system uninstall does not need the login user; only the unit path matters.
+    const plan = host.platform === "linux" && options.scope === "system"
+        ? { kind: "systemd-system", unitPath: path.join(host.systemUnitDir, DAEMON_SYSTEMD_UNIT), rendered: "" }
+        : planDaemonUnit(host, options);
+    if (plan.kind === "manual")
+        return { kind: plan.kind, unitPath: plan.unitPath, removed: false };
+    // A registered task is removed even when its XML file has gone missing.
+    const present = fs.existsSync(plan.unitPath) ||
+        (plan.kind === "schtasks" && deps.run("schtasks.exe", ["/Query", "/TN", DAEMON_WINDOWS_TASK]).status === 0);
+    if (!present)
+        return { kind: plan.kind, unitPath: plan.unitPath, removed: false };
+    switch (plan.kind) {
+        case "launchd":
+            deactivateLaunchd(plan.unitPath, deps.run, host.uid);
+            break;
+        case "systemd-user":
+            deactivateSystemd(DAEMON_SYSTEMD_UNIT, deps.run);
+            break;
+        case "systemd-system": {
+            if (!host.isRoot)
+                throw new Error("Removing the box's system unit needs root. Run: sudo hq daemon uninstall");
+            const disable = deps.run("systemctl", ["disable", "--now", DAEMON_SYSTEMD_UNIT]);
+            // Keep the unit file so a later uninstall still finds it.
+            if (disable.status !== 0)
+                throw commandError(`systemctl disable --now ${DAEMON_SYSTEMD_UNIT}`, disable);
+            deps.run("systemctl", ["daemon-reload"]);
+            break;
+        }
+        case "schtasks": {
+            deps.run("schtasks.exe", ["/End", "/TN", DAEMON_WINDOWS_TASK]);
+            // Ending the task stops only its root process (conhost when --headless is
+            // used); node and the services it runs keep going. End the recorded
+            // daemon's whole process tree.
+            const owner = readPidLock(path.join(host.daemonDir, "daemon.pid"));
+            if (owner && owner.pid !== process.pid) {
+                deps.run("taskkill.exe", ["/PID", String(owner.pid), "/T", "/F"]);
+            }
+            const del = deps.run("schtasks.exe", ["/Delete", "/TN", DAEMON_WINDOWS_TASK, "/F"]);
+            // Keep the XML so a later uninstall still finds the task.
+            if (del.status !== 0)
+                throw commandError(`schtasks /Delete /TN ${DAEMON_WINDOWS_TASK}`, del);
+            break;
+        }
+    }
+    fs.rmSync(plan.unitPath, { force: true });
+    return { kind: plan.kind, unitPath: plan.unitPath, removed: true };
+}
+//# sourceMappingURL=install.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * Units HQ installed before `hq daemon`, one per service. While one of these
+ * still runs a service, the daemon leaves that service alone instead of
+ * starting a second copy, and `hq daemon migrate` lists it.
+ *
+ * Detection only reads the filesystem (and asks schtasks on Windows). Nothing
+ * here stops or removes a unit.
+ */
+import type { ServiceName } from "./catalog.js";
+export interface LegacyUnit {
+    /** Daemon unit id it overlaps with (`mesh`, `bots:<name>`, ...). */
+    unitId: string;
+    service: ServiceName;
+    kind: "launchd" | "systemd-user" | "systemd-system" | "schtasks";
+    name: string;
+    path?: string;
+    /** False for units owned by another product (the desktop app's own agent). */
+    migratable: boolean;
+}
+export interface LegacyProbeDeps {
+    platform: NodeJS.Platform;
+    home: string;
+    existsSync: (p: string) => boolean;
+    listDir: (dir: string) => string[];
+    windowsTaskExists: (taskName: string) => boolean;
+}
+export declare function describeLegacyUnit(unit: LegacyUnit): string;
+export declare function findLegacyUnits(deps: LegacyProbeDeps): LegacyUnit[];
+/**
+ * unit id → description of the migratable legacy unit that still runs it.
+ * Units owned by another product (the desktop app) are handled by the plan's
+ * own checks, because `hq daemon migrate` will never take them over.
+ */
+export declare function legacyOwnerLookup(units: readonly LegacyUnit[]): (unitId: string) => string | null;
+//# sourceMappingURL=legacy.d.ts.map

package/dist/lib/daemon/legacy.js

@@ -0,0 +1,120 @@
+/**
+ * Units HQ installed before `hq daemon`, one per service. While one of these
+ * still runs a service, the daemon leaves that service alone instead of
+ * starting a second copy, and `hq daemon migrate` lists it.
+ *
+ * Detection only reads the filesystem (and asks schtasks on Windows). Nothing
+ * here stops or removes a unit.
+ */
+import * as path from "node:path";
+const KIT_SERVICES = ["sync", "inbox", "heartbeat"];
+/** Box units rendered by hq-pro-agents / `outposts self-deploy`, mapped to the service they overlap. */
+const SYSTEM_UNITS = [
+    ["hq-mesh-daemon.service", "mesh"],
+    ["outpost-sync.service", "sync"],
+    ["outpost-full-sync.timer", "sync"],
+    ["hq-agent-sync.service", "sync"],
+    ["outpost-session-heartbeat.service", "heartbeat"],
+    ["hq-agent-heartbeat.timer", "heartbeat"],
+    ["hq-agent-inbox.service", "inbox"],
+    ["hq-agent-qmd-index.timer", "search-index"],
+    ["outpost-jobs-reconcile.timer", "jobs-reconcile"],
+    ["outpost-runner.service", "remote-control"],
+    ["outpost-codex-runner.service", "remote-control"],
+    ["hq-cli-update.timer", "updater"],
+];
+const KIND_LABEL = {
+    launchd: "LaunchAgent",
+    "systemd-user": "systemd user unit",
+    "systemd-system": "systemd unit",
+    schtasks: "scheduled task",
+};
+export function describeLegacyUnit(unit) {
+    return `${KIND_LABEL[unit.kind]} ${unit.name}`;
+}
+function safeList(deps, dir) {
+    try {
+        return deps.listDir(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+function darwinUnits(deps) {
+    const dir = path.join(deps.home, "Library", "LaunchAgents");
+    const units = [];
+    const at = (label) => path.join(dir, `${label}.plist`);
+    const add = (unitId, service, label, migratable = true) => units.push({ unitId, service, kind: "launchd", name: label, path: at(label), migratable });
+    if (deps.existsSync(at("ai.getindigo.hq-mesh-daemon")))
+        add("mesh", "mesh", "ai.getindigo.hq-mesh-daemon");
+    for (const file of safeList(deps, dir).sort()) {
+        const m = /^ai\.getindigo\.hq-bot\.(.+)\.plist$/.exec(file);
+        if (m)
+            add(`bots:${m[1]}`, "bots", `ai.getindigo.hq-bot.${m[1]}`);
+    }
+    for (const s of KIT_SERVICES) {
+        const label = `ai.getindigo.hq-agent.${s}`;
+        if (deps.existsSync(at(label)))
+            add(s, s, label);
+    }
+    if (deps.existsSync(at("ai.indigo.hq-sync-menubar")))
+        add("sync", "sync", "ai.indigo.hq-sync-menubar", false);
+    return units;
+}
+function linuxUnits(deps) {
+    const userDir = path.join(deps.home, ".config", "systemd", "user");
+    const units = [];
+    const user = (unitId, service, name) => units.push({ unitId, service, kind: "systemd-user", name, path: path.join(userDir, name), migratable: true });
+    if (deps.existsSync(path.join(userDir, "hq-mesh-daemon.service")))
+        user("mesh", "mesh", "hq-mesh-daemon.service");
+    for (const file of safeList(deps, userDir).sort()) {
+        const m = /^hq-bot-(.+)\.service$/.exec(file);
+        if (m)
+            user(`bots:${m[1]}`, "bots", file);
+    }
+    for (const s of KIT_SERVICES) {
+        const name = `hq-agent-${s}.service`;
+        if (deps.existsSync(path.join(userDir, name)))
+            user(s, s, name);
+    }
+    if (deps.existsSync(path.join(userDir, "hq-lanes-reconcile.timer"))) {
+        user("lanes-reconcile", "lanes-reconcile", "hq-lanes-reconcile.timer");
+    }
+    const systemDir = "/etc/systemd/system";
+    for (const [name, service] of SYSTEM_UNITS) {
+        const file = path.posix.join(systemDir, name);
+        if (deps.existsSync(file)) {
+            units.push({ unitId: service, service, kind: "systemd-system", name, path: file, migratable: true });
+        }
+    }
+    return units;
+}
+function windowsUnits(deps) {
+    const task = "ai.getindigo.hq-mesh-daemon";
+    return deps.windowsTaskExists(task)
+        ? [{ unitId: "mesh", service: "mesh", kind: "schtasks", name: task, migratable: true }]
+        : [];
+}
+export function findLegacyUnits(deps) {
+    if (deps.platform === "darwin")
+        return darwinUnits(deps);
+    if (deps.platform === "linux")
+        return linuxUnits(deps);
+    if (deps.platform === "win32")
+        return windowsUnits(deps);
+    return [];
+}
+/**
+ * unit id → description of the migratable legacy unit that still runs it.
+ * Units owned by another product (the desktop app) are handled by the plan's
+ * own checks, because `hq daemon migrate` will never take them over.
+ */
+export function legacyOwnerLookup(units) {
+    return (unitId) => {
+        const hit = units.find((u) => u.unitId === unitId && u.migratable);
+        return hit ? describeLegacyUnit(hit) : null;
+    };
+}
+//# sourceMappingURL=legacy.js.map