@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/daemon/lock.js

@@ -0,0 +1,138 @@
+/**
+ * One `hq daemon run` per user per machine: a pid file created with `wx`,
+ * taken over only when the recorded process is gone. Same file format as the
+ * mesh daemon's lock (`pid=<n>\nts=<unix seconds>`).
+ *
+ * Replacing a stale lock is guarded by a short-lived `<lock>.takeover` claim,
+ * so two starters that both saw the same stale owner cannot both win. A claim
+ * left behind by a starter that died mid-takeover expires after
+ * TAKEOVER_TTL_MS.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readPidLock } from "../mesh/live/daemon/pid-lock.js";
+import { ensurePrivateDir } from "./paths.js";
+export const TAKEOVER_TTL_MS = 30_000;
+/**
+ * The process exists and this user can signal it. EPERM means it belongs to
+ * another user, so it cannot be this user's daemon.
+ */
+export function isProcessAlive(pid, kill = (p, s) => process.kill(p, s)) {
+    try {
+        kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const defaultCommandLineDeps = () => ({
+    platform: process.platform,
+    run: (cmd, args) => {
+        const r = spawnSync(cmd, args, { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+        return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+    },
+});
+/** The process's command line, or null when it cannot be read. */
+export function processCommandLine(pid, deps = defaultCommandLineDeps()) {
+    const r = deps.platform === "win32"
+        ? deps.run("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            `(Get-CimInstance Win32_Process -Filter "ProcessId=${Math.trunc(pid)}").CommandLine`,
+        ])
+        : deps.run("ps", ["-ww", "-o", "args=", "-p", String(pid)]);
+    if (r.status !== 0)
+        return null;
+    const line = r.stdout.trim();
+    return line || null;
+}
+/**
+ * The pid is alive and is an `hq daemon run`. After a reboot the pid in an old
+ * lock file often belongs to an unrelated program; that must not keep the
+ * daemon from starting.
+ */
+export function isDaemonProcess(pid, deps = { alive: (p) => isProcessAlive(p), commandLine: (p) => processCommandLine(p) }) {
+    if (!deps.alive(pid))
+        return false;
+    const cmd = deps.commandLine(pid);
+    return cmd === null || /\bdaemon\s+run\b/.test(cmd);
+}
+function claimTakeover(claim, pid, now) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            fs.writeFileSync(claim, `pid=${pid}\n`, { flag: "wx", mode: 0o600 });
+            return true;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            let age;
+            try {
+                age = now() - fs.statSync(claim).mtimeMs;
+            }
+            catch (statErr) {
+                if (statErr.code === "ENOENT")
+                    continue;
+                throw statErr;
+            }
+            if (age <= TAKEOVER_TTL_MS)
+                return false;
+            fs.rmSync(claim, { force: true });
+        }
+    }
+    return false;
+}
+export function acquireDaemonLock(lockPath, pid = process.pid, alive = isDaemonProcess, now = Date.now) {
+    ensurePrivateDir(path.dirname(lockPath));
+    const body = `pid=${pid}\nts=${Math.floor(now() / 1000)}\n`;
+    const claim = `${lockPath}.takeover`;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            fs.writeFileSync(lockPath, body, { flag: "wx", mode: 0o600 });
+            return { ok: true };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        const owner = readPidLock(lockPath);
+        if (owner && owner.pid !== pid && alive(owner.pid))
+            return { ok: false, owner };
+        // Another starter is replacing the same stale lock; let it.
+        if (!claimTakeover(claim, pid, now))
+            return { ok: false, owner: null };
+        try {
+            // Re-check under the claim: the lock may have been replaced since the read above.
+            const current = readPidLock(lockPath);
+            if (current && current.pid !== pid && alive(current.pid))
+                return { ok: false, owner: current };
+            fs.rmSync(lockPath, { force: true });
+            try {
+                fs.writeFileSync(lockPath, body, { flag: "wx", mode: 0o600 });
+                return { ok: true };
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+        }
+        finally {
+            fs.rmSync(claim, { force: true });
+        }
+    }
+    throw new Error(`could not take the daemon lock at ${lockPath}`);
+}
+export function releaseDaemonLock(lockPath, pid = process.pid) {
+    const owner = readPidLock(lockPath);
+    if (owner?.pid === pid)
+        fs.rmSync(lockPath, { force: true });
+}
+/** The live supervisor's pid, or null when none is running. */
+export function runningDaemonPid(lockPath, alive = isDaemonProcess) {
+    const owner = readPidLock(lockPath);
+    return owner && alive(owner.pid) ? owner.pid : null;
+}
+//# sourceMappingURL=lock.js.map

package/dist/lib/daemon/machine-type.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which kind of machine `hq daemon` is running on. The machine type picks the
+ * default service list, so nobody has to name services for a normal setup.
+ *
+ * Resolution order (first match wins):
+ *   1. `--machine-type` flag
+ *   2. the type saved in ~/.hq/daemon/config.json by an earlier install
+ *   3. /etc/hq/machine-type, written by box provisioning (may name a login user)
+ *   3b. an outpost runner unit (outposts provisioned before the marker)
+ *   4. agent-kit machine credentials present → agent-kit
+ *   5. running in a container → agent-kit
+ *   6. macOS or Windows → desktop
+ *   7. any other host → self-hosted
+ */
+declare const MACHINE_TYPES: readonly ["desktop", "self-hosted", "outpost", "agent-box", "agent-kit"];
+export type MachineType = (typeof MACHINE_TYPES)[number];
+export declare const MACHINE_TYPE_MARKER_PATH = "/etc/hq/machine-type";
+type MachineTypeSource = "flag" | "config" | "marker" | "outpost-units" | "agent-kit-creds" | "container" | "platform";
+export interface MachineTypeResult {
+    type: MachineType;
+    source: MachineTypeSource;
+    /** Plain-language reason, printed by `hq daemon status` and install. */
+    detail: string;
+    /** Login user the system unit runs as (from the marker file). */
+    runAsUser?: string;
+    /** Problems found on the way (for example an unreadable marker file). */
+    warnings?: string[];
+}
+export interface DetectMachineTypeDeps {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    home: string;
+    savedType: string | undefined;
+    existsSync: (p: string) => boolean;
+    readFileSync: (p: string) => string;
+}
+export declare function isMachineType(value: unknown): value is MachineType;
+/**
+ * Marker format: either a bare type on the first line, or `type=<type>` with an
+ * optional `user=<login>` line. `#` comments and blank lines are ignored.
+ */
+export declare function parseMachineTypeMarker(text: string): {
+    type: MachineType;
+    user?: string;
+} | null;
+export declare function detectMachineType(flag: string | undefined, deps: DetectMachineTypeDeps): MachineTypeResult;
+/** The home directory of `user` in passwd-format text, or null when the account is not listed. */
+export declare function homeFromPasswd(passwd: string, user: string): string | null;
+export {};
+//# sourceMappingURL=machine-type.d.ts.map

package/dist/lib/daemon/machine-type.js

@@ -0,0 +1,159 @@
+/**
+ * Which kind of machine `hq daemon` is running on. The machine type picks the
+ * default service list, so nobody has to name services for a normal setup.
+ *
+ * Resolution order (first match wins):
+ *   1. `--machine-type` flag
+ *   2. the type saved in ~/.hq/daemon/config.json by an earlier install
+ *   3. /etc/hq/machine-type, written by box provisioning (may name a login user)
+ *   3b. an outpost runner unit (outposts provisioned before the marker)
+ *   4. agent-kit machine credentials present → agent-kit
+ *   5. running in a container → agent-kit
+ *   6. macOS or Windows → desktop
+ *   7. any other host → self-hosted
+ */
+import * as path from "node:path";
+import { AGENT_DIR_ENV, MACHINE_CREDS_NAME, agentRootDir } from "../agent-kit/paths.js";
+const MACHINE_TYPES = ["desktop", "self-hosted", "outpost", "agent-box", "agent-kit"];
+export const MACHINE_TYPE_MARKER_PATH = "/etc/hq/machine-type";
+/** The Claude runner unit outpost provisioning installs; its `User=` is the box's login user. */
+const OUTPOST_RUNNER_UNIT = "/etc/systemd/system/outpost-runner.service";
+export function isMachineType(value) {
+    return typeof value === "string" && MACHINE_TYPES.includes(value);
+}
+const ACCOUNT_NAME = /^[a-z_][a-z0-9_-]{0,31}$/i;
+/**
+ * Marker format: either a bare type on the first line, or `type=<type>` with an
+ * optional `user=<login>` line. `#` comments and blank lines are ignored.
+ */
+export function parseMachineTypeMarker(text) {
+    let type;
+    let user;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq === -1) {
+            type ??= line;
+            continue;
+        }
+        const key = line.slice(0, eq).trim();
+        const value = line.slice(eq + 1).trim();
+        if (key === "type")
+            type = value;
+        else if (key === "user")
+            user = value;
+    }
+    if (!isMachineType(type))
+        return null;
+    if (user !== undefined && !ACCOUNT_NAME.test(user))
+        return null;
+    // The daemon never runs as root, so root is never taken as the login user.
+    return user && user !== "root" ? { type, user } : { type };
+}
+function platformName(platform) {
+    if (platform === "darwin")
+        return "macOS";
+    if (platform === "win32")
+        return "Windows";
+    return platform;
+}
+function withWarnings(result, warnings) {
+    return warnings.length > 0 ? { ...result, warnings } : result;
+}
+function readMarker(deps, warnings) {
+    if (!deps.existsSync(MACHINE_TYPE_MARKER_PATH))
+        return null;
+    try {
+        const marker = parseMachineTypeMarker(deps.readFileSync(MACHINE_TYPE_MARKER_PATH));
+        if (!marker)
+            warnings.push(`${MACHINE_TYPE_MARKER_PATH} does not name a known machine type; ignored it`);
+        return marker;
+    }
+    catch (err) {
+        warnings.push(`could not read ${MACHINE_TYPE_MARKER_PATH}: ${err.message}`);
+        return null;
+    }
+}
+/** The login user the outpost runner unit runs as, or undefined (never root). */
+function outpostRunnerUser(deps) {
+    if (!deps.existsSync(OUTPOST_RUNNER_UNIT))
+        return undefined;
+    let text;
+    try {
+        text = deps.readFileSync(OUTPOST_RUNNER_UNIT);
+    }
+    catch {
+        return undefined;
+    }
+    const user = /^\s*User\s*=\s*(\S+)\s*$/m.exec(text)?.[1];
+    return user && user !== "root" && ACCOUNT_NAME.test(user) ? user : undefined;
+}
+/**
+ * Box types run as the login user the provisioning marker names, or else the
+ * user the outpost runner unit runs as, however the type itself was chosen.
+ */
+function withMarkerUser(result, deps) {
+    if (result.type !== "outpost" && result.type !== "agent-box")
+        return result;
+    const warnings = [];
+    const user = readMarker(deps, warnings)?.user ?? outpostRunnerUser(deps);
+    return withWarnings(user ? { ...result, runAsUser: user } : result, warnings);
+}
+/**
+ * Where a dedicated agent-kit host keeps its identity: an explicit
+ * HQ_MACHINE_CREDS_FILE or HQ_AGENT_DIR, else ~/.hq-agent itself. A local
+ * bot's identity under ~/.hq-agent/<name> sits beside a person's desktop and
+ * does not make the machine an agent kit.
+ */
+function hostAgentCredsPath(home, env) {
+    const credsFile = env.HQ_MACHINE_CREDS_FILE?.trim();
+    if (credsFile)
+        return credsFile;
+    const dir = env[AGENT_DIR_ENV]?.trim() || agentRootDir(home);
+    return path.join(dir, MACHINE_CREDS_NAME);
+}
+export function detectMachineType(flag, deps) {
+    if (flag !== undefined) {
+        if (!isMachineType(flag)) {
+            throw new Error(`Unknown machine type "${flag}". Use one of: ${MACHINE_TYPES.join(", ")}.`);
+        }
+        return withMarkerUser({ type: flag, source: "flag", detail: "set with --machine-type" }, deps);
+    }
+    if (isMachineType(deps.savedType)) {
+        return withMarkerUser({ type: deps.savedType, source: "config", detail: "saved by an earlier install" }, deps);
+    }
+    const warnings = [];
+    const marker = readMarker(deps, warnings);
+    if (marker) {
+        return withMarkerUser({ type: marker.type, source: "marker", detail: `from ${MACHINE_TYPE_MARKER_PATH}` }, deps);
+    }
+    // Outposts provisioned before the marker existed still have their runner unit.
+    if (deps.platform === "linux" && deps.existsSync(OUTPOST_RUNNER_UNIT)) {
+        return withWarnings(withMarkerUser({ type: "outpost", source: "outpost-units", detail: `outpost runner at ${OUTPOST_RUNNER_UNIT}` }, deps), warnings);
+    }
+    const kitCreds = hostAgentCredsPath(deps.home, deps.env);
+    if (deps.existsSync(kitCreds)) {
+        return withWarnings({ type: "agent-kit", source: "agent-kit-creds", detail: `agent kit credentials at ${kitCreds}` }, warnings);
+    }
+    if (deps.env.HQ_CONTAINER === "1" || deps.existsSync("/.dockerenv")) {
+        return withWarnings({ type: "agent-kit", source: "container", detail: "running in a container" }, warnings);
+    }
+    if (deps.platform === "darwin" || deps.platform === "win32") {
+        return withWarnings({ type: "desktop", source: "platform", detail: platformName(deps.platform) }, warnings);
+    }
+    return withWarnings({ type: "self-hosted", source: "platform", detail: `${platformName(deps.platform)} host` }, warnings);
+}
+/** The home directory of `user` in passwd-format text, or null when the account is not listed. */
+export function homeFromPasswd(passwd, user) {
+    for (const line of passwd.split(/\r?\n/)) {
+        if (!line || line.startsWith("#"))
+            continue;
+        const fields = line.split(":");
+        if (fields[0] === user && fields.length >= 7)
+            return fields[5] || null;
+    }
+    return null;
+}
+//# sourceMappingURL=machine-type.js.map

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

@@ -0,0 +1,77 @@
+/**
+ * Taking over the units HQ installed before `hq daemon` (`hq daemon migrate
+ * --apply`) and giving them back (`hq daemon uninstall --restore-legacy`).
+ *
+ * Adopting a unit stops it and moves its definition into ~/.hq/daemon/adopted,
+ * so legacy detection no longer finds it and the daemon starts the service
+ * itself on its next plan. Each adopted unit is recorded in adopted.json with
+ * where its definition went, which is exactly what restore needs to put it
+ * back. A unit whose stop fails is left where it was and not recorded.
+ *
+ * Units owned by another product (the desktop app's sync agent) are never
+ * touched, and box system units need root. Root on a box stops and restarts
+ * the login user's own units through that user's systemd manager, since
+ * root's `systemctl --user` reaches only root's. System units are recorded and
+ * saved in root-owned storage (not the login user's daemon folder, which the
+ * user can edit), and a restore checks each one lands in the system unit
+ * folder, so nobody but root decides what gets installed there.
+ */
+import type { RunCommand } from "../service-manager/launchd.js";
+import { type LegacyUnit } from "./legacy.js";
+export interface AdoptedUnit extends LegacyUnit {
+    /** Where the unit's definition (plist, unit file, task XML) was moved. */
+    movedTo: string;
+    adoptedAt: number;
+    /** Launchd job was loaded, but its source plist no longer existed. */
+    definitionMissing?: true;
+}
+export interface MigrateDeps {
+    run: RunCommand;
+    uid: number;
+    isRoot: boolean;
+    /** The login user's store: ~/.hq/daemon/adopted and adopted.json. */
+    adoptedDir: string;
+    recordPath: string;
+    /** Root-owned store for box system units. */
+    systemAdoptedDir: string;
+    systemRecordPath: string;
+    /** Where box system units live (/etc/systemd/system); restores must land here. */
+    systemUnitDir: string;
+    /** Root on a box: the login user whose systemd user units these are. */
+    userUnitsOwner?: {
+        user: string;
+        uid: number;
+    };
+    now?: () => number;
+    /** Tests inject a failing writer. */
+    writeRecord?: (recordPath: string, units: AdoptedUnit[]) => void;
+}
+export interface AdoptResult {
+    adopted: AdoptedUnit[];
+    skipped: {
+        unit: LegacyUnit;
+        reason: string;
+    }[];
+    failed: {
+        unit: LegacyUnit;
+        error: string;
+    }[];
+}
+export interface RestoreResult {
+    restored: AdoptedUnit[];
+    failed: {
+        unit: AdoptedUnit;
+        error: string;
+    }[];
+}
+export declare function readAdoptedUnits(recordPath: string): AdoptedUnit[];
+export declare function adoptLegacyUnits(units: readonly LegacyUnit[], deps: MigrateDeps): AdoptResult;
+/** Retire the migratable legacy mesh job and emit the daemon's operator-facing result lines. */
+export declare function retireLegacyMeshUnits(units: readonly LegacyUnit[], options: {
+    platform: NodeJS.Platform;
+    managed: boolean;
+    hosted: boolean;
+    meshEnabled: boolean;
+}, deps: MigrateDeps, log: (level: "info" | "warn", message: string) => void): AdoptResult;
+export declare function restoreLegacyUnits(deps: MigrateDeps): RestoreResult;
+//# sourceMappingURL=migrate.d.ts.map