@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/daemon.js

@@ -0,0 +1,877 @@
+/**
+ * `hq daemon` — one supervisor for every HQ background service on a machine.
+ *
+ *   hq daemon                     status (same as `hq daemon status`)
+ *   hq daemon install             detect the machine type, install the one OS unit
+ *   hq daemon run                 what the OS unit runs; starts the default services
+ *   hq daemon status [--json]
+ *   hq daemon logs [unit] [--follow] [--lines N]
+ *   hq daemon restart [unit] | trigger <unit>
+ *   hq daemon enable|disable <service...>   per-machine overrides
+ *   hq daemon migrate             list the older units it would take over (read-only)
+ *   hq daemon uninstall [--purge]
+ *
+ * Hidden from `hq --help` while it rolls out.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { major as semverMajor, valid as validSemver } from "semver";
+import { DEFAULT_SERVICES, SERVICE_DESCRIPTIONS, enabledServices, hqCloudUnits } from "../lib/daemon/catalog.js";
+import { applyServiceToggle, effectiveSyncOwner, readDaemonConfig, writeDaemonConfig } from "../lib/daemon/config.js";
+import { daemonUnitInstalled } from "../lib/daemon/handoff.js";
+import { adoptLegacyUnits, readAdoptedUnits, restoreLegacyUnits } from "../lib/daemon/migrate.js";
+import { ROOT_REFUSAL, SYSTEM_UNIT_DIR, daemonRootRefusal, installDaemonUnit, installScopeFor, uninstallDaemonUnit, } from "../lib/daemon/install.js";
+import { describeLegacyUnit, findLegacyUnits } from "../lib/daemon/legacy.js";
+import { isDaemonProcess, runningDaemonPid } from "../lib/daemon/lock.js";
+import { bundledHqCloud } from "../lib/daemon/hq-cloud.js";
+import { MACHINE_TYPE_MARKER_PATH, detectMachineType, homeFromPasswd, } from "../lib/daemon/machine-type.js";
+import { daemonPaths } from "../lib/daemon/paths.js";
+import { processCommandLine } from "../lib/daemon/lock.js";
+import { writeControlRequest } from "../lib/daemon/requests.js";
+import { isSyncRunnerCommandLine, readWatchRunnerOwnerStatus, watchRunnerOwnerStatusPath } from "../lib/daemon/sync-runner.js";
+import { getSyncModeForCompany, setSyncMode } from "./sync-mode.js";
+import { resolveDefaultHqRoot } from "../utils/cognito-session.js";
+class DaemonCommandError extends Error {
+}
+/**
+ * The HQ folder install records: --hq-root, else the CLI's shared resolution
+ * (HQ_ROOT, the tree around the current folder, the folder the installer or
+ * menubar recorded, the well-known locations). Undefined when none resolves.
+ */
+/** Validate `hq daemon run --host`; the desktop app is the only host. */
+export function parseDaemonHost(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "desktop")
+        return value;
+    throw new Error(`--host must be "desktop" (got "${value}")`);
+}
+export function resolveDaemonHqRoot(flag, where) {
+    if (flag)
+        return path.resolve(flag);
+    try {
+        return resolveDefaultHqRoot({ onMissing: "throw", env: where.env, cwd: where.cwd, home: where.home });
+    }
+    catch {
+        // resolveDefaultHqRoot throws only when nothing resolves; install then
+        // says the folder is not set.
+        return undefined;
+    }
+}
+async function loadDefaults(over) {
+    const env = over.env ?? process.env;
+    const home = over.home ?? os.homedir();
+    const platform = over.platform ?? process.platform;
+    const needsBinaries = over.nodeBinary === undefined || over.hqBinary === undefined;
+    const mesh = needsBinaries || over.windowsUser === undefined ? await import("../lib/mesh/live/daemon/install.js") : null;
+    const serviceManager = over.run ? null : await import("../lib/service-manager/index.js");
+    const run = over.run ?? serviceManager.defaultRunCommand;
+    return {
+        env,
+        home,
+        platform,
+        out: over.out ?? ((l) => console.log(l)),
+        err: over.err ?? ((l) => console.error(l)),
+        run,
+        nodeBinary: over.nodeBinary ?? mesh.resolveAbsoluteNodeBinary(),
+        hqBinary: over.hqBinary ?? mesh.resolveHqBinary(),
+        uid: over.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0),
+        isRoot: over.isRoot ?? (typeof process.getuid === "function" && process.getuid() === 0),
+        fileExists: over.fileExists ?? fs.existsSync,
+        readFile: over.readFile ?? ((p) => fs.readFileSync(p, "utf8")),
+        writeFile: over.writeFile ??
+            ((p, text) => {
+                fs.mkdirSync(path.dirname(p), { recursive: true });
+                fs.writeFileSync(p, text, { mode: 0o644 });
+            }),
+        legacyUnits: over.legacyUnits ??
+            ((dir) => findLegacyUnits({
+                platform,
+                home: dir ?? home,
+                existsSync: fs.existsSync,
+                listDir: (dir) => fs.readdirSync(dir),
+                launchdJobLoaded: (label) => run("launchctl", ["print", `gui/${process.getuid?.() ?? 0}/${label}`]).status === 0,
+                windowsTaskExists: (task) => run("schtasks.exe", ["/Query", "/TN", task]).status === 0,
+            })),
+        resolveHqRoot: over.resolveHqRoot ?? ((flag) => resolveDaemonHqRoot(flag, { env, cwd: process.cwd(), home })),
+        userHome: over.userHome ?? ((user) => loginHome(user, run)),
+        daemonAlive: over.daemonAlive ?? ((pid) => isDaemonProcess(pid)),
+        windowsUser: over.windowsUser ?? (platform === "win32" ? mesh.resolveWindowsUser(env) : ""),
+        windowsHeadlessLauncher: over.windowsHeadlessLauncher ?? (platform === "win32" ? mesh.resolveWindowsHeadlessLauncher(env) : undefined),
+        systemUnitDir: over.systemUnitDir ?? SYSTEM_UNIT_DIR,
+        syncModeClient: over.syncModeClient,
+        systemRecordPath: over.systemRecordPath ?? path.join(SYSTEM_ADOPTED_ROOT, "adopted.json"),
+    };
+}
+function detect(d, flag, config) {
+    return detectMachineType(flag, {
+        platform: d.platform,
+        env: d.env,
+        home: d.home,
+        savedType: config.machineType,
+        existsSync: d.fileExists,
+        readFileSync: d.readFile,
+    });
+}
+function describeServices(machineType, config) {
+    return enabledServices(machineType, config).map((s) => `  ${s.padEnd(16)} ${SERVICE_DESCRIPTIONS[s]}`);
+}
+function hostFor(d, paths, pathEnv) {
+    const env = {};
+    if (pathEnv && d.env.PATH)
+        env.PATH = d.env.PATH;
+    if (d.env.HQ_DAEMON_DIR)
+        env.HQ_DAEMON_DIR = d.env.HQ_DAEMON_DIR;
+    return {
+        platform: d.platform,
+        home: d.home,
+        nodeBinary: d.nodeBinary,
+        hqBinary: d.hqBinary,
+        daemonDir: paths.root,
+        uid: d.uid,
+        isRoot: d.isRoot,
+        windowsUser: d.windowsUser ?? "",
+        windowsHeadlessLauncher: d.windowsHeadlessLauncher,
+        systemUnitDir: d.systemUnitDir ?? SYSTEM_UNIT_DIR,
+        env,
+    };
+}
+/**
+ * The login user's home from the account database: `getent` covers LDAP and
+ * other NSS sources, /etc/passwd covers hosts without it. Accounts are not
+ * required to live under /home (root, service accounts under /var/lib).
+ */
+function loginHome(user, run) {
+    const entry = run("getent", ["passwd", user]);
+    const fromGetent = entry.status === 0 ? homeFromPasswd(entry.stdout, user) : null;
+    if (fromGetent)
+        return fromGetent;
+    let passwd;
+    try {
+        passwd = fs.readFileSync("/etc/passwd", "utf8");
+    }
+    catch (err) {
+        throw new DaemonCommandError(`Could not look up the home directory of ${user}: ${err.message}`);
+    }
+    const fromFile = homeFromPasswd(passwd, user);
+    if (!fromFile)
+        throw new DaemonCommandError(`The login user ${user} from /etc/hq/machine-type does not exist on this machine.`);
+    return fromFile;
+}
+/**
+ * Where the daemon's files are for this machine. On boxes the system unit runs
+ * as the login user, so its files live in that user's home, not root's.
+ */
+function hostPaths(d, flag, userFlag) {
+    const own = daemonPaths(d.home, d.env);
+    const detected = detect(d, flag, readDaemonConfig(own.configPath));
+    if (installScopeFor(detected.type) !== "system")
+        return { paths: own, detected };
+    // An explicit --user, then the marker or the outpost runner's User=, then
+    // the account that ran sudo.
+    const sudoUser = d.env.SUDO_USER?.trim();
+    const runAsUser = userFlag ?? detected.runAsUser ?? (sudoUser && sudoUser !== "root" ? sudoUser : undefined);
+    if (runAsUser === "root")
+        throw new DaemonCommandError(`${ROOT_REFUSAL} Pass the box's login user with --user <name>.`);
+    if (!runAsUser) {
+        throw new DaemonCommandError("A box install needs the login user the daemon runs as: pass --user <name>, or provisioning writes it to /etc/hq/machine-type (user=<name>).");
+    }
+    const paths = daemonPaths(d.userHome(runAsUser), d.env);
+    if (flag !== undefined || userFlag !== undefined)
+        return { paths, detected, runAsUser };
+    // Root normally has no saved config; the login user's saved type is the real one.
+    const saved = readDaemonConfig(paths.configPath);
+    const again = saved.machineType ? detect(d, undefined, saved) : detected;
+    return { paths, detected: again, runAsUser: again.runAsUser ?? runAsUser };
+}
+/** hostPaths for the everyday verbs: a box without a known login user falls back to this user's own files. */
+function currentHost(d) {
+    try {
+        return hostPaths(d, undefined);
+    }
+    catch (err) {
+        if (!(err instanceof DaemonCommandError))
+            throw err;
+        const paths = daemonPaths(d.home, d.env);
+        return { paths, detected: detect(d, undefined, readDaemonConfig(paths.configPath)) };
+    }
+}
+/** Files root writes for a box's daemon must stay readable by the login user it runs as. */
+function handOver(d, host) {
+    if (host.runAsUser && d.isRoot)
+        d.run("chown", ["-R", `${host.runAsUser}:`, host.paths.root]);
+}
+async function runInstall(d, opts) {
+    const { paths, detected, runAsUser } = hostPaths(d, opts.machineType, opts.user);
+    const scope = installScopeFor(detected.type);
+    // A per-user unit installed by root would run every service as root.
+    const refusal = scope === "user" ? daemonRootRefusal(d.isRoot, detected.type) : null;
+    if (refusal)
+        throw new DaemonCommandError(refusal);
+    const config = {
+        ...readDaemonConfig(paths.configPath),
+        machineType: detected.type,
+    };
+    const hqRoot = d.resolveHqRoot(opts.hqRoot) ?? config.hqRoot;
+    if (hqRoot)
+        config.hqRoot = hqRoot;
+    writeDaemonConfig(paths.configPath, config);
+    for (const w of detected.warnings ?? [])
+        d.err(`warning: ${w}`);
+    d.out(`Machine type: ${detected.type} (${detected.detail})`);
+    d.out(hqRoot ? `HQ folder: ${hqRoot}` : "HQ folder: not set (sync, lanes and search wait until `hq daemon install --hq-root <path>`)");
+    d.out("Services that start automatically:");
+    for (const line of describeServices(detected.type, config))
+        d.out(line);
+    const migratable = d.legacyUnits().filter((u) => u.migratable);
+    for (const u of migratable) {
+        d.out(`Note: ${describeLegacyUnit(u)} still runs ${u.unitId}. The daemon leaves it alone until \`hq daemon migrate\` takes it over.`);
+    }
+    // A box worked out from its runner unit, --user or sudo gets the marker file
+    // provisioning would have written: `migrate --apply` moves the runner unit
+    // aside, and later root commands (uninstall) must still find the box's type
+    // and login user.
+    if (scope === "system" && runAsUser && d.isRoot && !d.fileExists(MACHINE_TYPE_MARKER_PATH)) {
+        d.writeFile(MACHINE_TYPE_MARKER_PATH, `type=${detected.type}\nuser=${runAsUser}\n`);
+    }
+    const runAsHome = runAsUser ? d.userHome(runAsUser) : undefined;
+    const result = installDaemonUnit(hostFor(d, paths, scope === "user"), { scope, runAsUser, runAsHome }, { run: d.run });
+    handOver(d, { paths, detected, runAsUser });
+    if (result.kind === "manual") {
+        d.out(`This platform has no supported service manager. Start the daemon yourself with:\n  ${result.manualCommand}`);
+        return;
+    }
+    if (!result.running) {
+        throw new DaemonCommandError(`Installed ${result.unitPath}, but it did not start: ${result.error ?? "unknown error"}`);
+    }
+    d.out(`Installed and started: ${result.unitPath}`);
+}
+/** Root acting for a box's login user needs that user's uid to reach their systemd manager. */
+function loginUid(d, user) {
+    const r = d.run("id", ["-u", user]);
+    const uid = Number(r.stdout.trim());
+    if (r.status !== 0 || !Number.isInteger(uid) || uid < 0 || r.stdout.trim() === "") {
+        throw new DaemonCommandError(`Could not look up the uid of ${user}.`);
+    }
+    return uid;
+}
+/** Where the older units are: a box's login user's home when root runs this for them. */
+function legacyUnitsFor(d, host) {
+    return d.isRoot && host.runAsUser ? d.legacyUnits(d.userHome(host.runAsUser)) : d.legacyUnits();
+}
+function migrateDeps(d, paths, runAsUser) {
+    return {
+        run: d.run,
+        uid: d.uid,
+        isRoot: d.isRoot,
+        userUnitsOwner: d.isRoot && runAsUser ? { user: runAsUser, uid: loginUid(d, runAsUser) } : undefined,
+        adoptedDir: path.join(paths.root, "adopted"),
+        recordPath: path.join(paths.root, "adopted.json"),
+        // Box system units: root-owned, outside the login user's daemon folder (which handOver chowns to that user).
+        systemAdoptedDir: path.join(SYSTEM_ADOPTED_ROOT, "adopted"),
+        systemRecordPath: d.systemRecordPath ?? path.join(SYSTEM_ADOPTED_ROOT, "adopted.json"),
+        systemUnitDir: d.systemUnitDir ?? SYSTEM_UNIT_DIR,
+    };
+}
+const SYSTEM_ADOPTED_ROOT = "/var/lib/hq/daemon";
+/** Every unit the daemon took over that has not been given back (the system store only when root can read it). */
+function unrestoredUnits(d, migrate) {
+    const own = readAdoptedUnits(migrate.recordPath);
+    return d.isRoot ? [...own, ...readAdoptedUnits(migrate.systemRecordPath)] : own;
+}
+async function runUninstall(d, opts) {
+    const host = currentHost(d);
+    const { paths, detected } = host;
+    // Only a restore acts on the login user's units.
+    const migrate = migrateDeps(d, paths, opts.restoreLegacy ? host.runAsUser : undefined);
+    const adopted = unrestoredUnits(d, migrate);
+    if (opts.purge && !opts.restoreLegacy && adopted.length > 0) {
+        throw new DaemonCommandError(`hq daemon took over ${adopted.map((u) => u.unitId).join(", ")}, and their original units are kept in ${migrate.adoptedDir}. ` +
+            "Run `hq daemon uninstall --restore-legacy --purge` to give them back first, so --purge does not delete them.");
+    }
+    const result = uninstallDaemonUnit(hostFor(d, paths, false), { scope: installScopeFor(detected.type) }, { run: d.run });
+    d.out(result.removed ? `Removed ${result.unitPath}` : "hq daemon was not installed.");
+    if (opts.restoreLegacy) {
+        const restored = restoreLegacyUnits(migrate);
+        for (const u of restored.restored)
+            d.out(`Gave ${u.unitId} back to ${describeLegacyUnit(u)}`);
+        for (const f of restored.failed)
+            d.err(`Could not give ${f.unit.unitId} back to ${describeLegacyUnit(f.unit)}: ${f.error}`);
+        if (restored.restored.length === 0 && restored.failed.length === 0)
+            d.out("hq daemon had not taken over any older units.");
+        if (restored.failed.length > 0) {
+            handOver(d, host);
+            throw new DaemonCommandError(`Some units were not restored; they are still listed in ${migrate.recordPath}.`);
+        }
+    }
+    if (opts.purge) {
+        fs.rmSync(paths.root, { recursive: true, force: true });
+        d.out(`Deleted ${paths.root}`);
+    }
+    else {
+        d.out(`Kept settings in ${paths.configPath}`);
+    }
+}
+function readState(paths) {
+    try {
+        return JSON.parse(fs.readFileSync(paths.statePath, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw new DaemonCommandError(`could not read ${paths.statePath}: ${err.message}`);
+    }
+}
+function formatUnit(u) {
+    const detail = u.status === "running" && u.pid
+        ? `pid ${u.pid}`
+        : u.status === "idle" && u.lastResult
+            ? `last run ${u.lastResult}`
+            : (u.reason ?? "");
+    const restarts = u.restarts > 0 ? ` (restarted ${u.restarts}x)` : "";
+    return `  ${u.id.padEnd(22)} ${u.status.padEnd(12)} ${detail}${restarts}`;
+}
+async function runStatus(d, opts) {
+    const host = currentHost(d);
+    const { paths } = host;
+    const pid = runningDaemonPid(paths.lockPath, d.daemonAlive);
+    const state = pid ? readState(paths) : null;
+    const config = readDaemonConfig(paths.configPath);
+    if (opts.json) {
+        d.out(JSON.stringify({ running: pid !== null, pid, machineType: state?.machineType ?? config.machineType ?? null, units: state?.units ?? [] }, null, 2));
+        return;
+    }
+    if (!pid || !state) {
+        const { detected } = host;
+        d.out(`hq daemon is not running. Machine type: ${detected.type} (${detected.detail}).`);
+        d.out("Default services for this machine:");
+        for (const line of describeServices(detected.type, config))
+            d.out(line);
+        return;
+    }
+    d.out(`hq daemon is running (pid ${pid}) on a ${state.machineType} machine.`);
+    for (const u of state.units)
+        d.out(formatUnit(u));
+}
+function tailLines(file, lines) {
+    const text = fs.readFileSync(file, "utf8");
+    return text.split("\n").filter((l, i, all) => i < all.length - 1 || l !== "").slice(-lines);
+}
+async function runLogs(d, unit, opts) {
+    const { paths } = currentHost(d);
+    const file = unit ? paths.unitLogPath(unit) : paths.supervisorLogPath;
+    if (!fs.existsSync(file))
+        throw new DaemonCommandError(`No log yet at ${file}`);
+    const n = Number(opts.lines ?? 50);
+    for (const line of tailLines(file, Number.isFinite(n) && n > 0 ? n : 50))
+        d.out(line);
+    if (!opts.follow)
+        return;
+    let offset = fs.statSync(file).size;
+    await new Promise(() => {
+        setInterval(() => {
+            const size = fs.statSync(file).size;
+            if (size < offset)
+                offset = 0;
+            if (size === offset)
+                return;
+            const fd = fs.openSync(file, "r");
+            const buf = Buffer.alloc(size - offset);
+            fs.readSync(fd, buf, 0, buf.length, offset);
+            fs.closeSync(fd);
+            offset = size;
+            process.stdout.write(buf.toString("utf8"));
+        }, 500);
+    });
+}
+function queueRequest(d, request, what) {
+    const host = currentHost(d);
+    const { paths } = host;
+    writeControlRequest(paths.requestsDir, request);
+    handOver(d, host);
+    const running = runningDaemonPid(paths.lockPath, d.daemonAlive) !== null;
+    d.out(running ? `Asked the daemon to ${what}.` : `Queued "${what}"; the daemon is not running, so it applies when it starts.`);
+}
+function daemonSyncModeClient(d) {
+    if (d.syncModeClient)
+        return d.syncModeClient();
+    return (async () => {
+        const [{ VaultClient }, { buildVaultConfig, ensureCognitoToken }] = await Promise.all([
+            import("@indigoai-us/hq-cloud"),
+            import("../utils/cognito-session.js"),
+        ]);
+        const token = await ensureCognitoToken();
+        return new VaultClient(buildVaultConfig(token));
+    })();
+}
+function daemonSyncStatus(d) {
+    const host = currentHost(d);
+    const { paths } = host;
+    const config = readDaemonConfig(paths.configPath);
+    const daemonPid = runningDaemonPid(paths.lockPath, d.daemonAlive);
+    const daemonState = daemonPid === null ? null : readState(paths);
+    const syncUnit = daemonState?.units.find((unit) => unit.id === "sync");
+    const hqRoot = config.hqRoot ?? d.env.HQ_ROOT?.trim();
+    let ownerStatusCandidate = null;
+    if (hqRoot) {
+        try {
+            ownerStatusCandidate = readWatchRunnerOwnerStatus(watchRunnerOwnerStatusPath(hqRoot, d.home, d.env));
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            d.err(`Could not read sync runner owner status; treating it as unavailable: ${detail}`);
+        }
+    }
+    const ownerCommandLine = ownerStatusCandidate
+        ? processCommandLine(ownerStatusCandidate.pid, { platform: d.platform, run: d.run })
+        : null;
+    const ownerStatus = ownerCommandLine && isSyncRunnerCommandLine(ownerCommandLine)
+        ? ownerStatusCandidate
+        : null;
+    return {
+        running: syncUnit?.status === "running",
+        paused: config.syncPaused === true,
+        syncOwner: effectiveSyncOwner(config, host.detected.type),
+        owner: ownerStatus?.owner ?? (syncUnit?.status === "running" ? "hq-daemon" : null),
+        runnerPid: ownerStatus?.pid ?? syncUnit?.pid ?? null,
+        hqCloudVersion: ownerStatus?.version ?? null,
+        lastHeartbeat: syncUnit?.lastHeartbeatAt ?? ownerStatus?.heartbeatAt ?? null,
+        lastPassResult: syncUnit?.lastPassResult ?? null,
+        unitStatus: syncUnit?.status ?? "not-running",
+        reason: syncUnit?.reason ?? null,
+        logPath: paths.unitLogPath("sync"),
+    };
+}
+async function runDaemonSyncStatus(d, opts) {
+    const status = daemonSyncStatus(d);
+    if (opts.json) {
+        d.out(JSON.stringify(status, null, 2));
+        return;
+    }
+    d.out(`Sync ${status.running ? "running" : status.unitStatus}${status.paused ? " (paused)" : ""}.`);
+    d.out(`Configured sync owner: ${status.syncOwner}.`);
+    d.out(`Owner: ${status.owner ?? "none"}; runner pid: ${status.runnerPid ?? "none"}; hq-cloud: ${status.hqCloudVersion ?? "unknown"}.`);
+    if (status.reason)
+        d.out(`Reason: ${status.reason}`);
+    d.out(`Log: ${status.logPath}`);
+}
+function queueDaemonSyncControl(d, request) {
+    const host = currentHost(d);
+    writeControlRequest(host.paths.requestsDir, request);
+    handOver(d, host);
+    return runningDaemonPid(host.paths.lockPath, d.daemonAlive) !== null;
+}
+async function runDaemonSyncNow(d, opts) {
+    const host = currentHost(d);
+    const config = readDaemonConfig(host.paths.configPath);
+    if (config.syncPaused)
+        throw new DaemonCommandError("sync is paused; run `hq daemon sync resume` first");
+    if (!enabledServices(host.detected.type, config).includes("sync")) {
+        throw new DaemonCommandError("sync is disabled for this machine; run `hq daemon enable sync` first");
+    }
+    const running = queueDaemonSyncControl(d, { action: "restart", unit: "sync" });
+    const result = { accepted: true, action: "restart-sync-runner", daemonRunning: running };
+    d.out(opts.json ? JSON.stringify(result, null, 2) : running ? "Asked the daemon to start a fresh sync pass." : "Queued a fresh sync pass for the next daemon start.");
+}
+async function runDaemonSyncInstantSyncSet(d, enabled, opts) {
+    const host = currentHost(d);
+    const config = readDaemonConfig(host.paths.configPath);
+    const changed = config.instantSyncEnabled !== enabled;
+    if (changed)
+        writeDaemonConfig(host.paths.configPath, { ...config, instantSyncEnabled: enabled });
+    const daemonRunning = runningDaemonPid(host.paths.lockPath, d.daemonAlive) !== null;
+    if (changed && daemonRunning)
+        queueDaemonSyncControl(d, { action: "restart-daemon" });
+    const result = { instantSyncEnabled: enabled, persisted: true, daemonRestartRequested: changed && daemonRunning };
+    d.out(opts.json ? JSON.stringify(result, null, 2) : `Instant Sync ${enabled ? "enabled" : "disabled"}${daemonRunning ? "; asked the daemon to restart" : "; saved for the next daemon start"}.`);
+}
+async function runDaemonSyncPause(d, paused, opts) {
+    const host = currentHost(d);
+    const config = readDaemonConfig(host.paths.configPath);
+    if (config.syncPaused !== paused)
+        writeDaemonConfig(host.paths.configPath, { ...config, syncPaused: paused });
+    const daemonRunning = queueDaemonSyncControl(d, { action: "reconcile" });
+    const result = { paused, persisted: true, daemonRunning };
+    d.out(opts.json ? JSON.stringify(result, null, 2) : `Sync ${paused ? "paused" : "resumed"}${daemonRunning ? "" : "; the setting will apply when the daemon starts"}.`);
+}
+async function runDaemonSyncTakeOwnership(d, opts) {
+    const host = currentHost(d);
+    const config = readDaemonConfig(host.paths.configPath);
+    if (config.syncOwner !== "daemon")
+        writeDaemonConfig(host.paths.configPath, { ...config, syncOwner: "daemon" });
+    const daemonRunning = queueDaemonSyncControl(d, { action: "reconcile" });
+    const result = { syncOwner: "daemon", persisted: true, daemonRunning };
+    d.out(opts.json ? JSON.stringify(result, null, 2) : `Daemon sync ownership persisted${daemonRunning ? "; asked the daemon to reconcile" : "; it applies when the daemon starts"}.`);
+}
+async function runDaemonSyncModeGet(d, companySlug, opts) {
+    const result = await getSyncModeForCompany({ companySlug, vaultClient: await daemonSyncModeClient(d) });
+    const value = {
+        companySlug: result.companySlug,
+        membershipId: result.membershipId,
+        mode: result.config.syncMode,
+        isDefault: result.config.isDefault,
+        ...(result.config.updatedAt ? { updatedAt: result.config.updatedAt } : {}),
+    };
+    d.out(opts.json ? JSON.stringify(value, null, 2) : `${value.companySlug}: ${value.mode}${value.isDefault ? " (default)" : ""}`);
+}
+async function runDaemonSyncModeSet(d, companySlug, mode, opts) {
+    if (mode !== "all" && mode !== "shared") {
+        throw new DaemonCommandError(`Invalid sync mode '${mode}'. Use all or shared.`);
+    }
+    const result = await setSyncMode({
+        mode,
+        companySlug,
+        vaultClient: await daemonSyncModeClient(d),
+    });
+    const value = {
+        companySlug: result.companySlug,
+        membershipId: result.membershipId,
+        previousMode: result.previousMode,
+        mode: result.newMode,
+        isDefault: result.newConfig.isDefault,
+        ...(result.newConfig.updatedAt ? { updatedAt: result.newConfig.updatedAt } : {}),
+    };
+    d.out(opts.json ? JSON.stringify(value, null, 2) : `${value.companySlug}: ${value.previousMode} → ${value.mode}`);
+}
+async function runToggle(d, action, services) {
+    const host = currentHost(d);
+    const { paths } = host;
+    const config = readDaemonConfig(paths.configPath);
+    const machineType = host.detected.type;
+    const next = applyServiceToggle(config, action, services, DEFAULT_SERVICES[machineType]);
+    writeDaemonConfig(paths.configPath, next);
+    handOver(d, host);
+    d.out(`Services for this ${machineType} machine:`);
+    for (const line of describeServices(machineType, next))
+        d.out(line);
+    d.out("A running daemon picks this up within 15 seconds.");
+}
+async function runPinHqCloud(d, version, opts) {
+    if (opts.clear === Boolean(version)) {
+        throw new DaemonCommandError("Pass one exact semver version, or use --clear.");
+    }
+    const host = currentHost(d);
+    const { paths } = host;
+    const config = readDaemonConfig(paths.configPath);
+    if (opts.clear) {
+        delete config.hqCloudVersion;
+        writeDaemonConfig(paths.configPath, config);
+        handOver(d, host);
+        d.out("Cleared the hq-cloud version pin.");
+    }
+    else {
+        if (!version || validSemver(version) !== version) {
+            throw new DaemonCommandError(`Invalid hq-cloud version "${version ?? ""}". Pass an exact semver version, including prereleases if needed.`);
+        }
+        const bundled = bundledHqCloud();
+        if (!bundled || semverMajor(bundled.version) !== semverMajor(version)) {
+            throw new DaemonCommandError(`The hq-cloud pin must use the same major version as the bundled hq-cloud${bundled ? ` (${semverMajor(bundled.version)})` : ""}.`);
+        }
+        writeDaemonConfig(paths.configPath, { ...config, hqCloudVersion: version });
+        handOver(d, host);
+        d.out(`Pinned hq-cloud to ${version}.`);
+    }
+    d.out("Run `hq daemon trigger updater`; wait for the hq-cloud update or current-version message in `hq daemon logs updater`, then restart `hq daemon restart sync`, `hq daemon restart heartbeat`, and `hq daemon restart session-host`.");
+}
+async function runMigrate(d, opts) {
+    const host = currentHost(d);
+    const units = legacyUnitsFor(d, host);
+    if (units.length === 0) {
+        d.out("No older HQ background units found. Nothing to migrate.");
+        return;
+    }
+    if (opts.apply) {
+        // Stopping the older units with nothing installed to replace them would
+        // leave their services off.
+        const installed = daemonUnitInstalled({
+            platform: d.platform,
+            home: d.home,
+            systemUnitDir: d.systemUnitDir,
+            windowsTaskExists: (task) => d.run("schtasks.exe", ["/Query", "/TN", task]).status === 0,
+        });
+        if (!installed) {
+            throw new DaemonCommandError("hq daemon is not installed here yet. Run `hq daemon install` first, then `hq daemon migrate --apply`.");
+        }
+        const result = adoptLegacyUnits(units, migrateDeps(d, host.paths, host.runAsUser));
+        handOver(d, host);
+        for (const a of result.adopted)
+            d.out(`Took over ${a.unitId} from ${describeLegacyUnit(a)}`);
+        for (const s of result.skipped)
+            d.out(`Left ${s.unit.unitId} to ${describeLegacyUnit(s.unit)}: ${s.reason}`);
+        for (const f of result.failed)
+            d.err(`Could not take over ${f.unit.unitId} from ${describeLegacyUnit(f.unit)}: ${f.error}`);
+        if (result.adopted.length > 0) {
+            d.out("The daemon starts these services within a minute. `hq daemon uninstall --restore-legacy` puts the old units back.");
+        }
+        if (result.failed.length > 0)
+            throw new DaemonCommandError("Some units could not be taken over; they are still running as before.");
+        return;
+    }
+    for (const u of units) {
+        if (u.migratable)
+            d.out(`Would take over ${u.unitId} from ${describeLegacyUnit(u)}${u.path ? ` (${u.path})` : ""}`);
+        else
+            d.out(`Leaving ${u.unitId} to ${describeLegacyUnit(u)} (owned by the HQ desktop app)`);
+    }
+    d.out("Nothing was changed. `hq daemon migrate --apply` takes them over.");
+}
+async function runServiceSelfUpdate(d) {
+    const [{ daemonSelfUpdate }, { hostToolUpdater, runDaemonUpdater, updaterEnv }, { TOOL_NAMES }, { cliSelfUpdatable }, { updateManagedHqCloud },] = await Promise.all([
+        import("../utils/self-update.js"),
+        import("../lib/daemon/updater.js"),
+        import("../lib/daemon/tools.js"),
+        import("../lib/daemon/run.js"),
+        import("../lib/daemon/hq-cloud.js"),
+    ]);
+    const { paths, detected } = currentHost(d);
+    const env = updaterEnv(d.env);
+    const result = await runDaemonUpdater({
+        // Same guard as every self-update: never replace a dev checkout or a project's copy with a global install.
+        updateCli: cliSelfUpdatable() ? () => daemonSelfUpdate({ env }) : null,
+        tools: TOOL_NAMES.map((name) => hostToolUpdater(name, env, d.home)),
+        updateHqCloud: async () => updateManagedHqCloud(paths.root, env),
+        hqCloudUnits: hqCloudUnits(detected.type, enabledServices(detected.type, readDaemonConfig(paths.configPath))),
+        requestDaemonRestart: () => writeControlRequest(paths.requestsDir, { action: "restart-daemon" }),
+        requestRestart: (unit) => writeControlRequest(paths.requestsDir, { action: "restart", unit }),
+        log: d.out,
+    });
+    if (!result.ok)
+        process.exitCode = 1;
+}
+async function runTmuxService(d, opts) {
+    const { runRemoteControlHost, toolFingerprint } = await import("../lib/daemon/remote-control.js");
+    const { findOnPath } = await import("../lib/daemon/run.js");
+    const hqRoot = d.env.HQ_ROOT?.trim();
+    if (!hqRoot)
+        throw new DaemonCommandError(`${opts.label} needs HQ_ROOT (the daemon sets it from the saved HQ folder)`);
+    const tmux = findOnPath("tmux", d.env);
+    if (!tmux)
+        throw new DaemonCommandError("tmux is not installed");
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once("SIGTERM", stop);
+    process.once("SIGINT", stop);
+    try {
+        process.exitCode = await runRemoteControlHost({
+            tmux,
+            session: opts.session,
+            cwd: hqRoot,
+            argv: opts.argv,
+            label: opts.label,
+            // Only a new version of the tool restarts the session: not a same-version
+            // reinstall, and not an hq-cli release (the host's own code rarely matters).
+            binaryFingerprint: () => toolFingerprint(opts.watch),
+            now: () => Date.now(),
+            run: d.run,
+            pollMs: 5_000,
+            signal: controller.signal,
+            sleep: (ms) => new Promise((resolve) => {
+                const timer = setTimeout(resolve, ms);
+                controller.signal.addEventListener("abort", () => {
+                    clearTimeout(timer);
+                    resolve();
+                }, { once: true });
+            }),
+            log: d.out,
+        });
+    }
+    finally {
+        process.off("SIGTERM", stop);
+        process.off("SIGINT", stop);
+    }
+}
+/** The claude or codex a remote-control host runs: --claude/--codex, else the one installed now. */
+async function hostTool(d, name, given) {
+    const [{ serviceTool }, { findUserBinary }] = await Promise.all([
+        import("../lib/daemon/remote-control.js"),
+        import("../lib/daemon/run.js"),
+    ]);
+    try {
+        return serviceTool(name, given, (tool) => findUserBinary(tool, d.env, d.home));
+    }
+    catch (err) {
+        throw new DaemonCommandError(err.message);
+    }
+}
+async function runServiceRemoteControl(d, opts) {
+    const { TMUX_SESSION, remoteControlArgs } = await import("../lib/daemon/remote-control.js");
+    const claude = await hostTool(d, "claude", opts.claude);
+    await runTmuxService(d, {
+        session: TMUX_SESSION,
+        argv: [claude, ...remoteControlArgs({ name: opts.name, permissionMode: opts.permissionMode })],
+        label: "claude remote-control",
+        watch: claude,
+    });
+}
+async function runServiceCodexRemoteControl(d, opts) {
+    const { CODEX_TMUX_SESSION } = await import("../lib/daemon/remote-control.js");
+    const codex = await hostTool(d, "codex", opts.codex);
+    await runTmuxService(d, {
+        session: CODEX_TMUX_SESSION,
+        argv: ["bash", opts.script],
+        label: "codex remote-control",
+        watch: codex,
+    });
+}
+export function registerDaemonCommand(program, over = {}) {
+    let resolved = null;
+    const deps = () => (resolved ??= loadDefaults(over));
+    const wrap = (fn) => async (...args) => {
+        const d = await deps();
+        try {
+            await fn(d, ...args);
+        }
+        catch (err) {
+            d.err(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    };
+    const daemon = program
+        .command("daemon", { hidden: true })
+        .description("Run all of this machine's HQ background services under one supervisor")
+        .action(wrap((d) => runStatus(d, {})));
+    daemon
+        .command("install")
+        .description("Detect this machine's type, install the daemon, and start its default services")
+        .option("--machine-type <type>", "desktop | self-hosted | outpost | agent-box | agent-kit (skips detection)")
+        .option("--hq-root <path>", "HQ folder the services work against")
+        .option("--user <login>", "on a box: the login user the daemon runs as (never root)")
+        .action(wrap((d, opts) => runInstall(d, opts)));
+    daemon
+        .command("uninstall")
+        .description("Stop the daemon and remove its OS unit")
+        .option("--purge", "Also delete ~/.hq/daemon (settings, state and logs)")
+        .option("--restore-legacy", "Give the services `hq daemon migrate --apply` took over back to their original units")
+        .action(wrap((d, opts) => runUninstall(d, opts)));
+    daemon
+        .command("run")
+        .description("Run the supervisor (this is what the OS unit starts)")
+        .option("--foreground", "Also print the supervisor log to the terminal")
+        .option("--daemon-dir <path>", "Use this folder instead of ~/.hq/daemon (how the Windows task passes HQ_DAEMON_DIR)")
+        .option("--managed", "Started by the OS unit, which starts the daemon again whenever it exits")
+        .option("--host <app>", "Run as a child of this app (only \"desktop\"), which has handed sync over to the daemon")
+        .action(wrap(async (d, opts) => {
+        const host = parseDaemonHost(opts.host);
+        const { runDaemon } = await import("../lib/daemon/run.js");
+        // Services inherit this environment, so they see the same folder.
+        const env = opts.daemonDir ? { ...d.env, HQ_DAEMON_DIR: opts.daemonDir } : d.env;
+        process.exitCode = await runDaemon({
+            foreground: opts.foreground,
+            managed: opts.managed,
+            host,
+            home: d.home,
+            env,
+            nodeBinary: d.nodeBinary,
+            hqBinary: d.hqBinary,
+        });
+    }));
+    daemon
+        .command("status")
+        .description("Show the machine type and each service's state")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runStatus(d, opts)));
+    const sync = daemon
+        .command("sync")
+        .description("Inspect and control the daemon's company sync runner");
+    sync
+        .command("status")
+        .description("Show sync ownership, heartbeat, last pass and log path")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncStatus(d, opts)));
+    sync
+        .command("now")
+        .description("Start a fresh sync pass immediately")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncNow(d, opts)));
+    const instantSync = sync.command("instant-sync").description("Control daemon Instant Sync");
+    instantSync
+        .command("set <state>")
+        .description("Set whether daemon sync uses Instant Sync")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, state, opts) => {
+        if (state !== "on" && state !== "off")
+            throw new DaemonCommandError("Use on or off for Instant Sync.");
+        return runDaemonSyncInstantSyncSet(d, state === "on", opts);
+    }));
+    sync
+        .command("pause")
+        .description("Pause daemon sync until resumed")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncPause(d, true, opts)));
+    sync
+        .command("resume")
+        .description("Resume daemon sync after a pause")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncPause(d, false, opts)));
+    sync
+        .command("take-ownership")
+        .description("Persist daemon ownership of desktop sync and reconcile")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncTakeOwnership(d, opts)));
+    const mode = sync.command("mode").description("Read or change a company's sync footprint");
+    mode
+        .command("get <company>")
+        .description("Read a company's current all/shared sync mode")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, company, opts) => runDaemonSyncModeGet(d, company, opts)));
+    mode
+        .command("set <company> <mode>")
+        .description("Set a company's sync mode to all or shared")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, company, mode, opts) => runDaemonSyncModeSet(d, company, mode, opts)));
+    daemon
+        .command("logs [unit]")
+        .description("Print the supervisor log, or one service's log")
+        .option("-f, --follow", "Keep printing new lines")
+        .option("-n, --lines <n>", "How many lines to print first", "50")
+        .action(wrap((d, unit, opts) => runLogs(d, unit, opts)));
+    daemon
+        .command("restart [unit]")
+        .description("Restart one service, or every running service")
+        .action(wrap(async (d, unit) => queueRequest(d, unit ? { action: "restart", unit } : { action: "restart" }, unit ? `restart ${unit}` : "restart all services")));
+    daemon
+        .command("trigger <unit>")
+        .description("Run a scheduled service now (for example search-index)")
+        .action(wrap(async (d, unit) => queueRequest(d, { action: "trigger", unit }, `run ${unit} now`)));
+    daemon
+        .command("enable <services...>")
+        .description("Turn services on for this machine, beyond its defaults")
+        .action(wrap((d, services) => runToggle(d, "enable", services)));
+    daemon
+        .command("disable <services...>")
+        .description("Turn default services off for this machine")
+        .action(wrap((d, services) => runToggle(d, "disable", services)));
+    daemon
+        .command("pin-hq-cloud [version]")
+        .description("Pin hq-cloud to an exact version, or clear the pin")
+        .option("--clear", "Clear the saved hq-cloud version pin")
+        .action(wrap((d, version, opts) => runPinHqCloud(d, version, opts)));
+    daemon
+        .command("migrate")
+        .description("List the older HQ background units the daemon would take over; --apply takes them over")
+        .option("--apply", "Stop the older units and let the daemon run their services")
+        .action(wrap((d, opts) => runMigrate(d, opts)));
+    const service = daemon
+        .command("service", { hidden: true })
+        .description("Entry points the daemon runs for services that have no command of their own");
+    service
+        .command("self-update")
+        .description("Update the hq CLI, Claude, Codex and Grok, then restart the daemon onto a new CLI")
+        .action(wrap((d) => runServiceSelfUpdate(d)));
+    service
+        .command("remote-control")
+        .description("Keep `claude remote-control` running in a tmux session in the HQ folder")
+        .option("--claude <path>", "claude binary (default: the one installed for this user)")
+        .requiredOption("--name <name>", "remote-control session name")
+        .option("--permission-mode <mode>", "claude --permission-mode")
+        .action(wrap((d, opts) => runServiceRemoteControl(d, opts)));
+    service
+        .command("codex-remote-control")
+        .description("Keep the box's Codex remote-control runner going in a tmux session, restarting it after a Codex update")
+        .requiredOption("--script <path>", "the box's Codex runner script")
+        .option("--codex <path>", "codex binary, watched for updates (default: the one installed for this user)")
+        .action(wrap((d, opts) => runServiceCodexRemoteControl(d, opts)));
+    return daemon;
+}
+//# sourceMappingURL=daemon.js.map