@indigoai-us/hq-cli 5.162.0 → 5.164.0

package/dist/commands/mesh.js

@@ -52,6 +52,7 @@ import { resolveCompany } from "../lib/work-context/company.js";
 import { deriveRemoteOwnerSlug, deriveRepoIdentityKey, } from "../lib/work-context/repo-remote.js";
 import { promptRepoCompany, } from "../lib/work-context/repo-prompt.js";
 import { requeueQuarantinedOutbox } from "../lib/work-context/outbox.js";
+import { handOffInstallHere } from "../lib/daemon/handoff.js";
 export function formatCheckLines(threads, company, projectId) {
     if (threads.length === 0) {
         return ["Work mesh: no active project threads found."];
@@ -2047,6 +2048,14 @@ async function runDaemonRun(opts = {}) {
     });
 }
 async function runDaemonInstall(opts) {
+    // `hq daemon` runs mesh on this machine: installing a second unit would run it twice.
+    // An explicit --hq-root is verified the same way as below and saved for the daemon.
+    const explicitRoot = opts.hqRoot ? resolveInstallHqRoot({ explicit: opts.hqRoot }).root : undefined;
+    const handedOff = opts.systemUser ? null : handOffInstallHere(["mesh"], process.env, { hqRoot: explicitRoot });
+    if (handedOff) {
+        console.log(opts.json ? JSON.stringify({ ok: true, action: "hq-daemon", reinstalled: false, message: handedOff }) : handedOff);
+        return;
+    }
     // Verified root only: a repo's own .claude/ must never become the daemon's
     // HQ root (that path is persisted as trusted and used for attribution).
     const hqRoot = resolveInstallHqRoot({ explicit: opts.hqRoot });

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

@@ -0,0 +1,85 @@
+/**
+ * The `hq daemon` service catalog: every background service HQ runs, the
+ * default list for each machine type, and the concrete unit each service
+ * becomes on this host.
+ *
+ * Services run today's existing entrypoints (`hq mesh daemon run`,
+ * `hq bot run <name>`, `hq-sync-runner --watch`, ...) as child processes, so
+ * moving a service under the daemon does not change what it does. Services
+ * with no entrypoint yet stay in the catalog as `unavailable` so status shows
+ * them instead of silently dropping them.
+ */
+import type { MachineType } from "./machine-type.js";
+export declare const SERVICE_NAMES: readonly ["sync", "mesh", "heartbeat", "inbox", "bots", "remote-control", "session-host", "lanes-reconcile", "search-index", "jobs-reconcile", "updater", "housekeeping"];
+export type ServiceName = (typeof SERVICE_NAMES)[number];
+export declare function isServiceName(value: unknown): value is ServiceName;
+export declare const SERVICE_DESCRIPTIONS: Record<ServiceName, string>;
+/** The services each machine type runs without being asked. */
+export declare const DEFAULT_SERVICES: Record<MachineType, readonly ServiceName[]>;
+/** Defaults plus this host's overrides, in catalog order. Unknown names are ignored. */
+export declare function enabledServices(machineType: MachineType, overrides: {
+    enable: readonly string[];
+    disable: readonly string[];
+}): ServiceName[];
+export type UnitCommand = {
+    type: "hq";
+    args: string[];
+} | {
+    type: "node";
+    script: string;
+    args: string[];
+} | {
+    type: "exec";
+    file: string;
+    args: string[];
+} | {
+    type: "internal";
+    task: "rotate-logs";
+};
+export interface UnitBlock {
+    /** `waiting` clears on its own once the requirement appears; `unavailable` needs a newer CLI. */
+    state: "waiting" | "unavailable";
+    reason: string;
+}
+export interface UnitPlan {
+    /** Service name, or `<service>:<instance>` for per-instance services (bots). */
+    id: string;
+    service: ServiceName;
+    description: string;
+    kind: "long-running" | "scheduled";
+    /** Long-running units: restart after any exit, or only after a failure. */
+    restart: "always" | "on-failure";
+    intervalSec?: number;
+    initialDelaySec?: number;
+    command: UnitCommand | null;
+    env: Record<string, string>;
+    blocked?: UnitBlock;
+}
+export interface PlanContext {
+    machineType: MachineType;
+    platform: NodeJS.Platform;
+    home: string;
+    hqRoot: string | undefined;
+    /** hq-cloud's sync-runner.js, or null when it cannot be found. */
+    syncRunnerPath: string | null;
+    signedIn: boolean;
+    /** ~/.hq-agent/kit.json exists. */
+    kitConfigured: boolean;
+    /** The HQ desktop app runs its own sync on this machine. */
+    desktopAppManagesSync: boolean;
+    bots: readonly string[];
+    /** Name of a pre-daemon unit that still runs this unit id, or null. */
+    legacyOwner: (unitId: string) => string | null;
+    /** This CLI is a global install the updater can replace (not a project dependency). */
+    cliSelfUpdatable: boolean;
+    /** `<hqRoot>/core/scripts/outpost-jobs-reconcile.sh` when it exists. */
+    jobsReconcileScript: string | null;
+    /** Absolute paths of the claude and tmux binaries, or null when not installed. */
+    claudePath: string | null;
+    tmuxPath: string | null;
+    /** Short host name, used to name this machine's remote-control session. */
+    hostName: string;
+}
+/** Turn enabled services into concrete units for this host. */
+export declare function planUnits(services: readonly ServiceName[], ctx: PlanContext): UnitPlan[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/lib/daemon/catalog.js

@@ -0,0 +1,274 @@
+/**
+ * The `hq daemon` service catalog: every background service HQ runs, the
+ * default list for each machine type, and the concrete unit each service
+ * becomes on this host.
+ *
+ * Services run today's existing entrypoints (`hq mesh daemon run`,
+ * `hq bot run <name>`, `hq-sync-runner --watch`, ...) as child processes, so
+ * moving a service under the daemon does not change what it does. Services
+ * with no entrypoint yet stay in the catalog as `unavailable` so status shows
+ * them instead of silently dropping them.
+ */
+export const SERVICE_NAMES = [
+    "sync",
+    "mesh",
+    "heartbeat",
+    "inbox",
+    "bots",
+    "remote-control",
+    "session-host",
+    "lanes-reconcile",
+    "search-index",
+    "jobs-reconcile",
+    "updater",
+    "housekeeping",
+];
+export function isServiceName(value) {
+    return typeof value === "string" && SERVICE_NAMES.includes(value);
+}
+export const SERVICE_DESCRIPTIONS = {
+    sync: "keeps company vaults in sync with the cloud",
+    mesh: "Work Mesh Live presence",
+    heartbeat: "reports this machine's status to HQ",
+    inbox: "picks up the agent's incoming messages and tasks",
+    bots: "runs local bots",
+    "remote-control": "keeps Claude remote control running",
+    "session-host": "lets the desktop app open this machine's Claude sessions",
+    "lanes-reconcile": "cleans up stalled background lanes",
+    "search-index": "keeps local search up to date",
+    "jobs-reconcile": "keeps scheduled jobs matched to the cloud",
+    updater: "keeps the hq CLI and Codex up to date",
+    housekeeping: "rotates daemon logs",
+};
+/** The services each machine type runs without being asked. */
+export const DEFAULT_SERVICES = {
+    desktop: ["sync", "mesh", "heartbeat", "bots", "lanes-reconcile", "search-index", "housekeeping"],
+    "self-hosted": [
+        "sync",
+        "mesh",
+        "heartbeat",
+        "bots",
+        "session-host",
+        "lanes-reconcile",
+        "search-index",
+        "updater",
+        "housekeeping",
+    ],
+    outpost: [
+        "sync",
+        "mesh",
+        "heartbeat",
+        "remote-control",
+        "session-host",
+        "lanes-reconcile",
+        "search-index",
+        "jobs-reconcile",
+        "updater",
+        "housekeeping",
+    ],
+    "agent-box": ["mesh", "heartbeat", "inbox", "search-index", "updater", "housekeeping"],
+    "agent-kit": ["heartbeat", "inbox", "updater", "housekeeping"],
+};
+/** Defaults plus this host's overrides, in catalog order. Unknown names are ignored. */
+export function enabledServices(machineType, overrides) {
+    const defaults = DEFAULT_SERVICES[machineType];
+    return SERVICE_NAMES.filter((s) => (defaults.includes(s) || overrides.enable.includes(s)) && !overrides.disable.includes(s));
+}
+function base(service, over = {}) {
+    return {
+        id: service,
+        service,
+        description: SERVICE_DESCRIPTIONS[service],
+        kind: "long-running",
+        restart: "always",
+        command: null,
+        env: {},
+        ...over,
+    };
+}
+function unavailable(service, reason, over = {}) {
+    return base(service, { ...over, command: null, blocked: { state: "unavailable", reason } });
+}
+function firstBlock(checks) {
+    const hit = checks.find(([blocked]) => blocked);
+    return hit ? { state: "waiting", reason: hit[1] } : undefined;
+}
+const NO_HQ_ROOT = "no HQ folder configured (run `hq daemon install --hq-root <path>`)";
+const NOT_SIGNED_IN = "not signed in (run `hq login`)";
+const KIT_NOT_SET_UP = "the agent kit is not set up on this machine (run `hq agent kit install`)";
+function planService(service, ctx) {
+    const agentMachine = ctx.machineType === "agent-kit" || ctx.machineType === "agent-box";
+    switch (service) {
+        case "sync": {
+            if (!ctx.syncRunnerPath)
+                return [unavailable(service, "the hq-cloud sync runner is missing from this CLI install")];
+            const unit = base(service, {
+                command: {
+                    type: "node",
+                    script: ctx.syncRunnerPath,
+                    args: ["--companies", "--direction", "both", "--on-conflict", "keep", "--hq-root", ctx.hqRoot ?? "", "--watch"],
+                },
+            });
+            unit.blocked = firstBlock([
+                [ctx.desktopAppManagesSync, "the HQ desktop app is handling sync on this machine"],
+                [!ctx.hqRoot, NO_HQ_ROOT],
+                [!ctx.signedIn, NOT_SIGNED_IN],
+            ]);
+            return [unit];
+        }
+        case "mesh": {
+            const args = ["mesh", "daemon", "run", ...(ctx.hqRoot ? ["--hq-root", ctx.hqRoot] : [])];
+            return [base(service, { command: { type: "hq", args }, blocked: firstBlock([[!ctx.signedIn, NOT_SIGNED_IN]]) })];
+        }
+        case "heartbeat": {
+            if (agentMachine) {
+                return [
+                    base(service, {
+                        command: { type: "hq", args: ["agent", "kit", "run", "heartbeat"] },
+                        blocked: firstBlock([[!ctx.kitConfigured, KIT_NOT_SET_UP]]),
+                    }),
+                ];
+            }
+            if (ctx.machineType === "desktop") {
+                return [unavailable(service, "not available on desktop machines yet")];
+            }
+            return [
+                base(service, {
+                    command: { type: "hq", args: ["outposts", "heartbeat", "--home", ctx.home] },
+                    blocked: firstBlock([[!ctx.signedIn, NOT_SIGNED_IN]]),
+                }),
+            ];
+        }
+        case "inbox": {
+            if (!agentMachine)
+                return [unavailable(service, "only runs on agent machines")];
+            return [
+                base(service, {
+                    command: { type: "hq", args: ["agent", "kit", "run", "inbox"] },
+                    blocked: firstBlock([[!ctx.kitConfigured, KIT_NOT_SET_UP]]),
+                }),
+            ];
+        }
+        case "bots": {
+            if (ctx.bots.length === 0) {
+                return [base(service, { blocked: { state: "waiting", reason: "no local bots" } })];
+            }
+            return ctx.bots.map((name) => base(service, {
+                id: `bots:${name}`,
+                description: `runs the local bot ${name}`,
+                restart: "on-failure",
+                command: { type: "hq", args: ["bot", "run", name] },
+            }));
+        }
+        case "session-host":
+            return [
+                base(service, {
+                    command: { type: "hq", args: ["outposts", "session-host"] },
+                    env: ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {},
+                    blocked: firstBlock([[!ctx.signedIn, NOT_SIGNED_IN]]),
+                }),
+            ];
+        case "lanes-reconcile":
+            return [
+                base(service, {
+                    kind: "scheduled",
+                    intervalSec: 60,
+                    initialDelaySec: 30,
+                    command: { type: "hq", args: ["lanes", "reconcile"] },
+                    env: ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {},
+                    blocked: firstBlock([[!ctx.hqRoot, NO_HQ_ROOT]]),
+                }),
+            ];
+        case "search-index":
+            return [
+                base(service, {
+                    kind: "scheduled",
+                    intervalSec: 900,
+                    initialDelaySec: 120,
+                    command: { type: "hq", args: ["index", "sync", "--hq-root", ctx.hqRoot ?? ""] },
+                    blocked: firstBlock([[!ctx.hqRoot, NO_HQ_ROOT]]),
+                }),
+            ];
+        case "housekeeping":
+            return [
+                base(service, {
+                    kind: "scheduled",
+                    intervalSec: 3600,
+                    initialDelaySec: 60,
+                    command: { type: "internal", task: "rotate-logs" },
+                }),
+            ];
+        case "updater":
+            return [
+                base(service, {
+                    kind: "scheduled",
+                    intervalSec: 6 * 3600,
+                    initialDelaySec: 900,
+                    command: { type: "hq", args: ["daemon", "service", "self-update"] },
+                    blocked: firstBlock([
+                        [!ctx.cliSelfUpdatable, "this hq CLI is not a global install, so it is updated with the project or app that owns it"],
+                    ]),
+                }),
+            ];
+        case "jobs-reconcile": {
+            if (ctx.platform === "win32")
+                return [unavailable(service, "needs bash; not supported on Windows")];
+            const script = ctx.jobsReconcileScript;
+            return [
+                base(service, {
+                    kind: "scheduled",
+                    intervalSec: 600,
+                    initialDelaySec: 600,
+                    command: {
+                        type: "exec",
+                        file: "bash",
+                        args: [script ?? "", "--hq-root", ctx.hqRoot ?? "", "--ensure-hook", "--after-sync"],
+                    },
+                    env: ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {},
+                    blocked: firstBlock([
+                        [!ctx.hqRoot, NO_HQ_ROOT],
+                        [!script, "this HQ folder has no core/scripts/outpost-jobs-reconcile.sh"],
+                    ]),
+                }),
+            ];
+        }
+        case "remote-control": {
+            if (ctx.platform === "win32")
+                return [unavailable(service, "not supported on Windows yet")];
+            // Outposts keep the runner's session name and permission mode.
+            const outpost = ctx.machineType === "outpost";
+            const args = ["daemon", "service", "remote-control", "--claude", ctx.claudePath ?? "", "--name", outpost ? "outpost-1" : ctx.hostName];
+            if (outpost)
+                args.push("--permission-mode", "bypassPermissions");
+            return [
+                base(service, {
+                    command: { type: "hq", args },
+                    env: ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {},
+                    blocked: firstBlock([
+                        [!ctx.claudePath, "the claude CLI is not installed"],
+                        [!ctx.tmuxPath, "tmux is not installed (remote control runs Claude inside tmux)"],
+                        [!ctx.hqRoot, NO_HQ_ROOT],
+                    ]),
+                }),
+            ];
+        }
+    }
+}
+/** Turn enabled services into concrete units for this host. */
+export function planUnits(services, ctx) {
+    const units = [];
+    for (const service of services) {
+        for (const unit of planService(service, ctx)) {
+            const owner = unit.command ? ctx.legacyOwner(unit.id) : null;
+            if (owner && unit.blocked?.state !== "unavailable") {
+                unit.blocked = {
+                    state: "waiting",
+                    reason: `already run by ${owner}; \`hq daemon migrate\` will take it over`,
+                };
+            }
+            units.push(unit);
+        }
+    }
+    return units;
+}
+//# sourceMappingURL=catalog.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * ~/.hq/daemon/config.json — the machine type saved at install, the HQ folder
+ * the services work against, and per-host overrides. The default service list
+ * is NOT stored here: it lives in the catalog, so a release that adds a
+ * default service reaches every host of that machine type.
+ */
+import { type ServiceName } from "./catalog.js";
+import { type MachineType } from "./machine-type.js";
+export interface DaemonConfig {
+    version: 1;
+    machineType?: MachineType;
+    hqRoot?: string;
+    /** Services turned on here beyond the machine type's defaults. */
+    enable: string[];
+    /** Default services turned off here. */
+    disable: string[];
+}
+export declare function emptyDaemonConfig(): DaemonConfig;
+export declare function readDaemonConfig(file: string): DaemonConfig;
+export declare function writeDaemonConfig(file: string, config: DaemonConfig): void;
+/**
+ * Turn services on or off for this host, relative to the machine type's
+ * defaults: only differences from the defaults are stored.
+ */
+export declare function applyServiceToggle(config: DaemonConfig, action: "enable" | "disable", services: readonly string[], defaults: readonly ServiceName[]): DaemonConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/daemon/config.js

@@ -0,0 +1,85 @@
+/**
+ * ~/.hq/daemon/config.json — the machine type saved at install, the HQ folder
+ * the services work against, and per-host overrides. The default service list
+ * is NOT stored here: it lives in the catalog, so a release that adds a
+ * default service reaches every host of that machine type.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isServiceName } from "./catalog.js";
+import { isMachineType } from "./machine-type.js";
+import { ensurePrivateDir } from "./paths.js";
+export function emptyDaemonConfig() {
+    return { version: 1, enable: [], disable: [] };
+}
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+export function readDaemonConfig(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return emptyDaemonConfig();
+        throw err;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`hq daemon config at ${file} is not valid JSON: ${err.message}`);
+    }
+    if (!raw || typeof raw !== "object")
+        throw new Error(`hq daemon config at ${file} is not a JSON object`);
+    const obj = raw;
+    const config = { version: 1, enable: stringList(obj.enable), disable: stringList(obj.disable) };
+    if (isMachineType(obj.machineType))
+        config.machineType = obj.machineType;
+    if (typeof obj.hqRoot === "string" && obj.hqRoot.trim())
+        config.hqRoot = obj.hqRoot;
+    return config;
+}
+export function writeDaemonConfig(file, config) {
+    ensurePrivateDir(path.dirname(file));
+    const tmp = `${file}.${process.pid}.tmp`;
+    const ordered = { version: 1 };
+    if (config.machineType)
+        ordered.machineType = config.machineType;
+    if (config.hqRoot)
+        ordered.hqRoot = config.hqRoot;
+    ordered.enable = config.enable;
+    ordered.disable = config.disable;
+    fs.writeFileSync(tmp, `${JSON.stringify(ordered, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    fs.chmodSync(file, 0o600);
+}
+/**
+ * Turn services on or off for this host, relative to the machine type's
+ * defaults: only differences from the defaults are stored.
+ */
+export function applyServiceToggle(config, action, services, defaults) {
+    for (const s of services) {
+        if (!isServiceName(s))
+            throw new Error(`Unknown service "${s}".`);
+    }
+    const enable = new Set(config.enable);
+    const disable = new Set(config.disable);
+    for (const s of services) {
+        const isDefault = defaults.includes(s);
+        if (action === "enable") {
+            disable.delete(s);
+            if (!isDefault)
+                enable.add(s);
+        }
+        else {
+            enable.delete(s);
+            if (isDefault)
+                disable.add(s);
+        }
+    }
+    return { ...config, enable: [...enable], disable: [...disable] };
+}
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1,53 @@
+/**
+ * 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;
+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;
+}): string | null;
+//# sourceMappingURL=handoff.d.ts.map