@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/daemon/flag.js

@@ -0,0 +1,59 @@
+/**
+ * Feature flags read by the daemon. The daemon runs for weeks, so each read
+ * asks the registry again instead of holding a per-process answer, and it
+ * reads as off unless the registry itself says on (or a local override does).
+ */
+import { createFlagClient, readLocalOverride, } from "@indigoai-us/hq-flags-client";
+import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+import { resolveProcessFlagCompanyContext } from "../flag-registry.js";
+/** Outposts hand running services to the next daemon on a CLI update instead of restarting them all. */
+export const SUPERVISOR_HANDOFF_FLAG = "daemon.supervisor-handoff";
+/** Self-updates build the new CLI beside the running one and swap it in, so `hq` never disappears mid-update. */
+export const STAGED_SELF_UPDATE_FLAG = "cli.staged-self-update";
+const READ_TIMEOUT_MS = 5_000;
+export async function readDaemonFlag(flagKey, options = {}) {
+    const env = options.env ?? process.env;
+    const override = readLocalOverride(flagKey, env);
+    if (override !== null)
+        return override;
+    let failed = false;
+    const onError = (error) => {
+        failed = true;
+        options.onError?.(error);
+    };
+    let client;
+    try {
+        const company = resolveProcessFlagCompanyContext(env);
+        // Signed out reads as off without reaching the registry.
+        const token = await (options.getToken ?? (() => ensureCognitoIdToken({ interactive: false })))();
+        if (typeof token !== "string" || token.trim() === "")
+            return false;
+        client = (options.createClient ?? createFlagClient)({
+            endpoint: resolveFlagRegistryEndpoint(undefined, env),
+            getToken: () => token,
+            env: {},
+            refreshIntervalMs: 0,
+            requestTimeoutMs: READ_TIMEOUT_MS,
+            ...(company.companyUid ? { companyUid: company.companyUid } : {}),
+            ...(company.companySlug ? { companyIdentifiers: [company.companySlug] } : {}),
+            onError,
+        });
+        await client.ready();
+        const resolution = client.explain(flagKey, { fallback: false });
+        return !failed && resolution.source === "snapshot" && resolution.value === true;
+    }
+    catch (error) {
+        onError(error);
+        return false;
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch {
+            // closing a one-shot client cannot change the answer
+        }
+    }
+}
+//# sourceMappingURL=flag.js.map

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

@@ -0,0 +1,56 @@
+/**
+ * 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 { type ServiceName } from "./catalog.js";
+import { type MachineType } from "./machine-type.js";
+import { type DaemonPaths } from "./paths.js";
+/** A live daemon runs `unitId` (or held it after it was stopped from outside). */
+export declare function daemonSupervises(paths: DaemonPaths, unitId: string, alive?: (pid: number) => boolean): boolean;
+/**
+ * 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 declare function daemonWillSupervise(paths: DaemonPaths, unitId: string, alive?: (pid: number) => boolean): boolean;
+/** The live daemon's child for `unitId` is `pid` (a bot started before the daemon is not). */
+export declare function daemonOwnsProcess(paths: DaemonPaths, unitId: string, pid: number, alive?: (pid: number) => boolean): boolean;
+/** A live daemon has `service` enabled for its saved machine type, whether or not it has planned a unit for it yet. */
+export declare function daemonRunsService(paths: DaemonPaths, service: ServiceName, alive?: (pid: number) => boolean): boolean;
+/** Ask the running daemon to (re)start a unit it supervises. */
+export declare function askDaemonToStart(paths: DaemonPaths, unitId: string): void;
+/** Ask the running daemon to stop a unit and keep it down until it is started again. */
+export declare function askDaemonToStop(paths: DaemonPaths, unitId: string): void;
+/** A live daemon runs as the desktop app's child, which counts as installed even though no OS unit exists. */
+export declare function hostedDaemonRunning(paths: DaemonPaths, alive?: (pid: number) => boolean): boolean;
+export interface DaemonUnitHost {
+    platform: NodeJS.Platform;
+    home: string;
+    systemUnitDir?: string;
+    windowsTaskExists: (task: string) => boolean;
+}
+/** The `hq daemon` OS unit is installed on this machine (for this user, or as the box's system unit). */
+export declare function daemonUnitInstalled(host: DaemonUnitHost): boolean;
+/**
+ * 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 declare function handOffInstall(opts: {
+    paths: DaemonPaths;
+    installed: boolean;
+    machineType: MachineType;
+    services: readonly ServiceName[];
+    /** An HQ folder the older command was explicitly given; the daemon runs its services against it. */
+    hqRoot?: string;
+}): string | null;
+/** handOffInstall for this machine and user, for the older install commands. */
+export declare function handOffInstallHere(services: readonly ServiceName[], env?: NodeJS.ProcessEnv, opts?: {
+    hqRoot?: string;
+    ifStale?: boolean;
+}): string | null;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/lib/daemon/handoff.js

@@ -0,0 +1,161 @@
+/**
+ * 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"]);
+const RECENT_HOSTED_DAEMON_MS = 5 * 60_000;
+/** The updater's postinstall may run in the short gap before the desktop app relaunches its daemon. */
+function recentlyHostedDaemon(paths) {
+    if (!fs.existsSync(paths.statePath))
+        return false;
+    const state = JSON.parse(fs.readFileSync(paths.statePath, "utf8"));
+    const age = Date.now() - (state.updatedAt ?? 0);
+    return state.host === "desktop" && age >= 0 && age <= RECENT_HOSTED_DAEMON_MS;
+}
+/** 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 });
+}
+/** A live daemon runs as the desktop app's child, which counts as installed even though no OS unit exists. */
+export function hostedDaemonRunning(paths, alive = (pid) => isDaemonProcess(pid)) {
+    try {
+        return liveState(paths, alive)?.host === "desktop";
+    }
+    catch {
+        return false;
+    }
+}
+/** 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 paths = daemonPaths(home, env);
+    const config = readDaemonConfig(paths.configPath);
+    if (opts.ifStale && services.every((service) => config.disable.includes(service))) {
+        return `hq daemon has ${services.join(", ")} disabled, so the older service will not be installed.`;
+    }
+    const installed = daemonUnitInstalled({
+        platform: process.platform,
+        home,
+        windowsTaskExists: (task) => spawnSync("schtasks.exe", ["/Query", "/TN", task], { encoding: "utf8", windowsHide: true }).status === 0,
+    }) || hostedDaemonRunning(paths);
+    if (!installed) {
+        if (opts.ifStale && services.includes("mesh") && recentlyHostedDaemon(paths)) {
+            return `hq daemon recently hosted mesh on this machine, so the older mesh service will not be installed during its restart.`;
+        }
+        return null;
+    }
+    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/hq-cloud.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Which hq-cloud the daemon runs sync, the outpost heartbeat and the session host from.
+ *
+ * The hq CLI ships with a copy of hq-cloud, but hq-cloud releases more often
+ * than the CLI. The updater keeps a newer copy of the same major version in
+ * `<daemon dir>/hq-cloud`, and the daemon runs whichever of the two is newer.
+ * A different major version is never used: it may not match this CLI.
+ */
+export declare const HQ_CLOUD_PACKAGE = "@indigoai-us/hq-cloud";
+export interface HqCloudCopy {
+    /** The package folder (the one holding its package.json). */
+    root: string;
+    version: string;
+}
+export interface PickedHqCloud extends HqCloudCopy {
+    source: "bundled" | "managed";
+    /** Set when a version is pinned but that version is not the installed managed copy. */
+    pinnedVersionMissing?: string;
+}
+export declare function managedHqCloudDir(daemonRoot: string): string;
+/** The package folder inside the updater's install prefix. */
+export declare function managedHqCloudRoot(daemonRoot: string): string;
+/**
+ * `usable` says whether a copy has what the daemon runs; a newer managed copy
+ * that fails it (an interrupted or damaged install) is passed over.
+ */
+export declare function pickHqCloud(bundled: HqCloudCopy | null, managed: HqCloudCopy | null, usable?: (copy: HqCloudCopy) => boolean, pinnedVersion?: string): PickedHqCloud | null;
+export interface HqCloudRunners {
+    syncRunner: string | null;
+    /** `hq-outpost-heartbeat`, which older hq-cloud releases do not have. */
+    heartbeat: string | null;
+    /** `hq-outpost-session-host`, which older hq-cloud releases do not have. */
+    sessionHost: string | null;
+}
+export declare function hqCloudRunners(root: string, exists?: (p: string) => boolean): HqCloudRunners;
+/**
+ * Ask npm for every release of the bundled major version, no older than the
+ * bundled copy. The updater installs the newest one exactly: `npm install` with
+ * a range keeps an installed copy that already satisfies it, so a range alone
+ * never moves 6.18.1 to 6.18.2.
+ */
+export declare function hqCloudLatestCommand(bundledVersion: string, platform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+    shell: boolean;
+};
+/** The newest release in `npm view --json` output with the bundled major version, never older than it. */
+export declare function latestSameMajor(npmViewJson: string, bundledVersion: string): string | null;
+/** Install one exact hq-cloud version into the updater's folder. */
+export declare function hqCloudInstallCommand(prefix: string, version: string, platform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+    shell: boolean;
+};
+/** The copy bundled with this CLI. */
+export declare function bundledHqCloud(): HqCloudCopy | null;
+/** The hq-cloud the daemon should run right now. */
+export declare function currentHqCloud(daemonRoot: string): PickedHqCloud | null;
+export interface HqCloudUpdateOutcome {
+    ok: boolean;
+    from: string | null;
+    to: string | null;
+    detail?: string;
+}
+interface NpmRunResult {
+    status: number | null;
+    stdout?: string | null;
+    stderr?: string | null;
+    error?: Error;
+}
+export interface UpdateHqCloudDeps {
+    run?: (file: string, args: string[], shell: boolean, env: NodeJS.ProcessEnv) => NpmRunResult;
+    bundled?: HqCloudCopy | null;
+    platform?: NodeJS.Platform;
+}
+/** Install or update the updater's copy, as this (the login) user. */
+export declare function updateManagedHqCloud(daemonRoot: string, env: NodeJS.ProcessEnv, deps?: UpdateHqCloudDeps): HqCloudUpdateOutcome;
+export {};
+//# sourceMappingURL=hq-cloud.d.ts.map

package/dist/lib/daemon/hq-cloud.js

@@ -0,0 +1,183 @@
+/**
+ * Which hq-cloud the daemon runs sync, the outpost heartbeat and the session host from.
+ *
+ * The hq CLI ships with a copy of hq-cloud, but hq-cloud releases more often
+ * than the CLI. The updater keeps a newer copy of the same major version in
+ * `<daemon dir>/hq-cloud`, and the daemon runs whichever of the two is newer.
+ * A different major version is never used: it may not match this CLI.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { readDaemonConfig } from "./config.js";
+import { buildSpawnPlan } from "../../utils/windows-spawn.js";
+export const HQ_CLOUD_PACKAGE = "@indigoai-us/hq-cloud";
+export function managedHqCloudDir(daemonRoot) {
+    return path.join(daemonRoot, "hq-cloud");
+}
+/** The package folder inside the updater's install prefix. */
+export function managedHqCloudRoot(daemonRoot) {
+    return path.join(managedHqCloudDir(daemonRoot), "node_modules", ...HQ_CLOUD_PACKAGE.split("/"));
+}
+function parseVersion(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(v.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function newer(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return false;
+}
+/**
+ * `usable` says whether a copy has what the daemon runs; a newer managed copy
+ * that fails it (an interrupted or damaged install) is passed over.
+ */
+export function pickHqCloud(bundled, managed, usable = () => true, pinnedVersion) {
+    if (!bundled)
+        return null;
+    const b = parseVersion(bundled.version);
+    const m = managed ? parseVersion(managed.version) : null;
+    if (pinnedVersion) {
+        if (managed && managed.version === pinnedVersion && b && m && m[0] === b[0] && usable(managed)) {
+            return { ...managed, source: "managed" };
+        }
+        // The pinned version is not installed yet (the updater installs it). Keep
+        // running the newest usable copy meanwhile instead of dropping to an older
+        // bundled one, and report the missing pin.
+        return { ...pickNewest(bundled, managed, b, m, usable), pinnedVersionMissing: pinnedVersion };
+    }
+    return pickNewest(bundled, managed, b, m, usable);
+}
+function pickNewest(bundled, managed, b, m, usable) {
+    if (managed && b && m && m[0] === b[0] && newer(m, b) && usable(managed))
+        return { ...managed, source: "managed" };
+    return { ...bundled, source: "bundled" };
+}
+export function hqCloudRunners(root, exists = fs.existsSync) {
+    const bin = (name) => {
+        const p = path.join(root, "dist", "bin", name);
+        return exists(p) ? p : null;
+    };
+    return {
+        syncRunner: bin("sync-runner.js"),
+        heartbeat: bin("outpost-heartbeat.js"),
+        sessionHost: bin("outpost-session-host.js"),
+    };
+}
+/**
+ * Ask npm for every release of the bundled major version, no older than the
+ * bundled copy. The updater installs the newest one exactly: `npm install` with
+ * a range keeps an installed copy that already satisfies it, so a range alone
+ * never moves 6.18.1 to 6.18.2.
+ */
+export function hqCloudLatestCommand(bundledVersion, platform = process.platform) {
+    const plan = buildSpawnPlan("npm", ["view", `${HQ_CLOUD_PACKAGE}@^${bundledVersion}`, "version", "--json"], platform);
+    return { file: plan.cmd, args: plan.args, shell: plan.shell };
+}
+/** The newest release in `npm view --json` output with the bundled major version, never older than it. */
+export function latestSameMajor(npmViewJson, bundledVersion) {
+    const b = parseVersion(bundledVersion);
+    if (!b)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(npmViewJson);
+    }
+    catch {
+        return null;
+    }
+    const versions = typeof parsed === "string" ? [parsed] : Array.isArray(parsed) ? parsed : [];
+    let best = null;
+    for (const text of versions) {
+        if (typeof text !== "string" || !/^\d+\.\d+\.\d+$/.test(text))
+            continue;
+        const v = parseVersion(text);
+        if (v[0] !== b[0] || newer(b, v))
+            continue;
+        if (!best || newer(v, best.v))
+            best = { text, v };
+    }
+    return best?.text ?? null;
+}
+/** Install one exact hq-cloud version into the updater's folder. */
+export function hqCloudInstallCommand(prefix, version, platform = process.platform) {
+    // npm is a .cmd on Windows and needs the shell, so every argument is quoted for it.
+    const plan = buildSpawnPlan("npm", ["install", "--prefix", prefix, "--no-audit", "--no-fund", "--omit=dev", `${HQ_CLOUD_PACKAGE}@${version}`], platform);
+    return { file: plan.cmd, args: plan.args, shell: plan.shell };
+}
+function readHqCloudCopy(root) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? { root, version: pkg.version } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The copy bundled with this CLI. */
+export function bundledHqCloud() {
+    try {
+        const require = createRequire(import.meta.url);
+        return readHqCloudCopy(path.dirname(require.resolve(`${HQ_CLOUD_PACKAGE}/package.json`)));
+    }
+    catch {
+        return null;
+    }
+}
+/** The hq-cloud the daemon should run right now. */
+export function currentHqCloud(daemonRoot) {
+    const pinnedVersion = readDaemonConfig(path.join(daemonRoot, "config.json")).hqCloudVersion;
+    return pickHqCloud(bundledHqCloud(), readHqCloudCopy(managedHqCloudRoot(daemonRoot)), (copy) => hqCloudRunners(copy.root).syncRunner !== null, pinnedVersion);
+}
+function runNpm(file, args, shell, env) {
+    return spawnSync(file, args, {
+        encoding: "utf8",
+        env,
+        timeout: 10 * 60_000,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        shell,
+    });
+}
+function npmFailure(r) {
+    const tail = `${r.stderr ?? ""}\n${r.stdout ?? ""}`.trim().split("\n").slice(-3).join(" ").slice(0, 400);
+    return tail || (r.error ? r.error.message : `npm exited ${r.status ?? "by signal"}`);
+}
+/** Install or update the updater's copy, as this (the login) user. */
+export function updateManagedHqCloud(daemonRoot, env, deps = {}) {
+    const run = deps.run ?? runNpm;
+    const platform = deps.platform ?? process.platform;
+    const pinnedVersion = readDaemonConfig(path.join(daemonRoot, "config.json")).hqCloudVersion;
+    const bundled = deps.bundled !== undefined ? deps.bundled : bundledHqCloud();
+    const from = currentHqCloud(daemonRoot)?.version ?? null;
+    if (!bundled)
+        return { ok: false, from, to: null, detail: "this CLI install has no bundled hq-cloud to match" };
+    const prefix = managedHqCloudDir(daemonRoot);
+    try {
+        fs.mkdirSync(prefix, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        return { ok: false, from, to: null, detail: `could not create ${prefix}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    let version = pinnedVersion;
+    if (!version) {
+        const view = hqCloudLatestCommand(bundled.version, platform);
+        const r = run(view.file, view.args, view.shell, env);
+        if (r.status !== 0)
+            return { ok: false, from, to: null, detail: `could not look up the newest hq-cloud: ${npmFailure(r)}` };
+        const latest = latestSameMajor(r.stdout ?? "", bundled.version);
+        if (!latest) {
+            return { ok: false, from, to: null, detail: `npm listed no hq-cloud release at or above ${bundled.version} in the same major version` };
+        }
+        version = latest;
+    }
+    const cmd = hqCloudInstallCommand(prefix, version, platform);
+    const r = run(cmd.file, cmd.args, cmd.shell, env);
+    if (r.status !== 0)
+        return { ok: false, from, to: null, detail: npmFailure(r) };
+    return { ok: true, from, to: currentHqCloud(daemonRoot)?.version ?? null };
+}
+//# sourceMappingURL=hq-cloud.js.map

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

@@ -0,0 +1,85 @@
+/**
+ * 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, type SleepFn } from "../service-manager/launchd.js";
+import type { MachineType } from "./machine-type.js";
+export declare const DAEMON_LAUNCHD_LABEL = "ai.getindigo.hq-daemon";
+export declare const DAEMON_SYSTEMD_UNIT = "hq-daemon.service";
+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;
+    /** Blocking sleep for the launchd reload wait (tests inject). */
+    sleep?: SleepFn;
+}
+export declare const ROOT_REFUSAL = "hq daemon runs its services as the machine's login user, never as root.";
+/**
+ * Why the daemon must not run here as root, or null when it may. Agent kits
+ * are the one exception: they run in containers where root is often the only
+ * account.
+ */
+export declare function daemonRootRefusal(isRoot: boolean, machineType: MachineType): string | null;
+/** 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