@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/daemon/migrate.js

@@ -0,0 +1,265 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+import { legacyMeshUnitsToRetire } from "./legacy.js";
+import { ensurePrivateDir } from "./paths.js";
+export function readAdoptedUnits(recordPath) {
+    let text;
+    try {
+        text = fs.readFileSync(recordPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const parsed = JSON.parse(text);
+    if (!Array.isArray(parsed))
+        throw new Error(`${recordPath} is not a list of adopted units`);
+    return parsed;
+}
+function writeAdoptedUnits(recordPath, units) {
+    ensurePrivateDir(path.dirname(recordPath));
+    const tmp = `${recordPath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(units, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, recordPath);
+}
+function storeFor(kind, deps) {
+    return kind === "systemd-system"
+        ? { dir: deps.systemAdoptedDir, record: deps.systemRecordPath }
+        : { dir: deps.adoptedDir, record: deps.recordPath };
+}
+/** The saved definition's file name, prefixed with the unit kind so a user and a system unit of the same name never collide. */
+function savedName(unit) {
+    return unit.kind === "schtasks" ? `schtasks-${unit.name}.xml` : `${unit.kind}-${path.basename(unit.path ?? unit.name)}`;
+}
+/** Run a service-manager command; throw with its stderr when it fails. */
+function must(run, cmd, args) {
+    const r = run(cmd, args);
+    if (r.status !== 0) {
+        const detail = r.stderr.trim().split("\n").slice(-2).join(" ").slice(0, 300);
+        throw new Error(`${cmd} ${args.join(" ")} failed${detail ? `: ${detail}` : ` (exit ${r.status})`}`);
+    }
+    return r.stdout;
+}
+/** `systemctl` for a unit: `--user` units go to their owner's manager, as that user when root acts for them. */
+function systemctl(unit, deps, args) {
+    if (unit.kind !== "systemd-user")
+        return ["systemctl", args];
+    const owner = deps.isRoot ? deps.userUnitsOwner : undefined;
+    if (!owner)
+        return ["systemctl", ["--user", ...args]];
+    return [
+        "runuser",
+        ["-u", owner.user, "--", "env", `XDG_RUNTIME_DIR=/run/user/${owner.uid}`, "systemctl", "--user", ...args],
+    ];
+}
+function moveFile(from, to) {
+    ensurePrivateDir(path.dirname(to));
+    try {
+        fs.renameSync(from, to);
+    }
+    catch (err) {
+        if (err.code !== "EXDEV")
+            throw err;
+        fs.copyFileSync(from, to);
+        fs.rmSync(from);
+    }
+}
+/** schtasks /Create /XML reads UTF-16LE with a BOM, the format /Query /XML declares. */
+function encodeTaskXml(xml) {
+    return Buffer.from(`\uFEFF${xml.replace(/^\uFEFF/, "")}`, "utf16le");
+}
+function adoptOne(unit, deps) {
+    const to = path.join(storeFor(unit.kind, deps).dir, savedName(unit));
+    switch (unit.kind) {
+        case "launchd": {
+            if (!unit.path)
+                throw new Error(`no plist path for ${unit.name}`);
+            const target = `gui/${deps.uid}/${unit.name}`;
+            const bootout = deps.run("launchctl", ["bootout", target]);
+            // bootout also fails when the agent is not loaded, which is fine; any
+            // other failure leaves it running, so do not take it over.
+            if (bootout.status !== 0 && deps.run("launchctl", ["print", target]).status === 0) {
+                must(deps.run, "launchctl", ["bootout", target]);
+            }
+            if (!fs.existsSync(unit.path))
+                return { movedTo: unit.path, definitionMissing: true };
+            moveFile(unit.path, to);
+            return { movedTo: to };
+        }
+        case "systemd-user":
+        case "systemd-system": {
+            if (!unit.path)
+                throw new Error(`no unit file path for ${unit.name}`);
+            must(deps.run, ...systemctl(unit, deps, ["disable", "--now", unit.name]));
+            moveFile(unit.path, to);
+            deps.run(...systemctl(unit, deps, ["daemon-reload"]));
+            return { movedTo: to };
+        }
+        case "schtasks": {
+            const xml = must(deps.run, "schtasks.exe", ["/Query", "/TN", unit.name, "/XML"]);
+            ensurePrivateDir(path.dirname(to));
+            fs.writeFileSync(to, encodeTaskXml(xml), { mode: 0o600 });
+            deps.run("schtasks.exe", ["/End", "/TN", unit.name]);
+            must(deps.run, "schtasks.exe", ["/Delete", "/TN", unit.name, "/F"]);
+            return { movedTo: to };
+        }
+    }
+}
+export function adoptLegacyUnits(units, deps) {
+    const now = deps.now ?? Date.now;
+    const write = deps.writeRecord ?? writeAdoptedUnits;
+    const result = { adopted: [], skipped: [], failed: [] };
+    const records = new Map();
+    const recordOf = (store) => {
+        if (!records.has(store.record))
+            records.set(store.record, readAdoptedUnits(store.record));
+        return records.get(store.record);
+    };
+    for (const unit of units) {
+        if (!unit.migratable) {
+            result.skipped.push({ unit, reason: "owned by the HQ desktop app" });
+            continue;
+        }
+        if (unit.kind === "systemd-system" && !deps.isRoot) {
+            result.skipped.push({ unit, reason: "a system unit; run `sudo hq daemon migrate --apply`" });
+            continue;
+        }
+        const store = storeFor(unit.kind, deps);
+        let adoptedFields;
+        try {
+            adoptedFields = adoptOne(unit, deps);
+        }
+        catch (err) {
+            result.failed.push({ unit, error: err.message });
+            continue;
+        }
+        const adopted = { ...unit, ...adoptedFields, adoptedAt: now() };
+        const next = [...recordOf(store), adopted];
+        try {
+            // Record each unit as soon as it is moved, so a failure later in the
+            // list never loses track of one already taken over.
+            write(store.record, next);
+            records.set(store.record, next);
+            result.adopted.push(adopted);
+        }
+        catch (err) {
+            // Without a record nothing could restore it, so put it back now.
+            let rollback = "";
+            try {
+                restoreOne(adopted, deps);
+            }
+            catch (restoreErr) {
+                rollback = `; putting it back also failed (${restoreErr.message}), its definition is at ${adopted.movedTo}`;
+            }
+            result.failed.push({ unit, error: `could not record the takeover: ${err.message}${rollback}` });
+        }
+    }
+    return result;
+}
+/** Move the definition back, unless an earlier restore that failed later already did. */
+function moveBack(unit, to) {
+    if (!fs.existsSync(unit.movedTo) && fs.existsSync(to))
+        return;
+    moveFile(unit.movedTo, to);
+}
+const SYSTEM_UNIT_NAME = /^[A-Za-z0-9@._-]+\.(service|timer)$/;
+/** A system record entry may only put a .service or .timer file back into the system unit folder, from the root-owned store. */
+function checkSystemEntry(unit, deps) {
+    const expectedPath = path.join(deps.systemUnitDir, unit.name);
+    const expectedSaved = path.join(deps.systemAdoptedDir, savedName(unit));
+    if (!SYSTEM_UNIT_NAME.test(unit.name) || unit.path !== expectedPath || unit.movedTo !== expectedSaved) {
+        throw new Error(`the recorded unit ${unit.name} does not go back into the system unit folder ${deps.systemUnitDir}; not restoring it`);
+    }
+}
+function restoreOne(unit, deps) {
+    switch (unit.kind) {
+        case "launchd": {
+            if (!unit.path)
+                throw new Error(`no plist path recorded for ${unit.name}`);
+            if (unit.definitionMissing)
+                throw new Error("the original LaunchAgent plist is missing; this unit cannot be restored");
+            moveBack(unit, unit.path);
+            must(deps.run, "launchctl", ["bootstrap", `gui/${deps.uid}`, unit.path]);
+            return;
+        }
+        case "systemd-user":
+        case "systemd-system": {
+            if (!unit.path)
+                throw new Error(`no unit file path recorded for ${unit.name}`);
+            if (unit.kind === "systemd-system" && !deps.isRoot) {
+                throw new Error("a system unit; run `sudo hq daemon uninstall --restore-legacy`");
+            }
+            moveBack(unit, unit.path);
+            deps.run(...systemctl(unit, deps, ["daemon-reload"]));
+            must(deps.run, ...systemctl(unit, deps, ["enable", "--now", unit.name]));
+            return;
+        }
+        case "schtasks":
+            must(deps.run, "schtasks.exe", ["/Create", "/TN", unit.name, "/XML", unit.movedTo, "/F"]);
+            // Keep the saved XML until the task has started, so a failed start can be retried.
+            must(deps.run, "schtasks.exe", ["/Run", "/TN", unit.name]);
+            fs.rmSync(unit.movedTo, { force: true });
+            return;
+    }
+}
+/** Retire the migratable legacy mesh job and emit the daemon's operator-facing result lines. */
+export function retireLegacyMeshUnits(units, options, deps, log) {
+    const selected = legacyMeshUnitsToRetire(units, options);
+    const result = adoptLegacyUnits(selected, deps);
+    for (const unit of result.adopted)
+        log("info", `retired legacy ${unit.unitId} unit ${unit.name}; hq daemon now owns mesh`);
+    for (const failure of result.failed)
+        log("warn", `could not retire legacy ${failure.unit.unitId} unit ${failure.unit.name}: ${failure.error}`);
+    return result;
+}
+function restoreFrom(record, deps, check, result) {
+    const units = readAdoptedUnits(record);
+    if (units.length === 0)
+        return;
+    const remaining = [];
+    for (const unit of units) {
+        try {
+            check(unit);
+            restoreOne(unit, deps);
+            result.restored.push(unit);
+        }
+        catch (err) {
+            result.failed.push({ unit, error: err.message });
+            remaining.push(unit);
+        }
+    }
+    writeAdoptedUnits(record, remaining);
+}
+export function restoreLegacyUnits(deps) {
+    const result = { restored: [], failed: [] };
+    restoreFrom(deps.recordPath, deps, (unit) => {
+        // The login user can edit this record; a system unit is only ever restored from root-owned storage.
+        if (unit.kind === "systemd-system") {
+            throw new Error("system units are only restored from the root-owned record; this entry was not written by hq daemon migrate");
+        }
+    }, result);
+    // Only root can read (or act on) the system store.
+    if (deps.isRoot)
+        restoreFrom(deps.systemRecordPath, deps, (unit) => checkSystemEntry(unit, deps), result);
+    return result;
+}
+//# sourceMappingURL=migrate.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Per-host daemon files. These describe this machine's processes, so they live
+ * under ~/.hq/daemon and never under a synced HQ folder. Service logs can hold
+ * private output, so the folders are 0700 and the files 0600.
+ */
+export interface DaemonPaths {
+    root: string;
+    configPath: string;
+    statePath: string;
+    lockPath: string;
+    logsDir: string;
+    requestsDir: string;
+    supervisorLogPath: string;
+    unitLogPath: (unitId: string) => string;
+    /** The FIFO a unit that speaks the sync protocol writes its stdout to (see protocol-tail.ts); kept out of logs/ so nothing reading logs drains it. */
+    unitProtocolPath: (unitId: string) => string;
+}
+export declare function daemonPaths(home?: string, env?: NodeJS.ProcessEnv): DaemonPaths;
+/** Create `dir` (and any missing parents) readable only by its owner, and tighten it if it already exists. */
+export declare function ensurePrivateDir(dir: string): void;
+/** Open a log file for appending, creating it (and its folder) owner-only. */
+export declare function openPrivateAppend(file: string): number;
+export declare function appendPrivate(file: string, text: string): void;
+//# sourceMappingURL=paths.d.ts.map

package/dist/lib/daemon/paths.js

@@ -0,0 +1,43 @@
+/**
+ * Per-host daemon files. These describe this machine's processes, so they live
+ * under ~/.hq/daemon and never under a synced HQ folder. Service logs can hold
+ * private output, so the folders are 0700 and the files 0600.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export function daemonPaths(home = os.homedir(), env = process.env) {
+    const root = env.HQ_DAEMON_DIR?.trim() || path.join(home, ".hq", "daemon");
+    const logsDir = path.join(root, "logs");
+    return {
+        root,
+        configPath: path.join(root, "config.json"),
+        statePath: path.join(root, "state.json"),
+        lockPath: path.join(root, "daemon.pid"),
+        logsDir,
+        requestsDir: path.join(root, "requests"),
+        supervisorLogPath: path.join(logsDir, "daemon.log"),
+        unitLogPath: (unitId) => path.join(logsDir, `${unitId.replace(/[^A-Za-z0-9_.-]/g, "-")}.log`),
+        unitProtocolPath: (unitId) => path.join(root, "protocol", `${unitId.replace(/[^A-Za-z0-9_.-]/g, "-")}.fifo`),
+    };
+}
+/** Create `dir` (and any missing parents) readable only by its owner, and tighten it if it already exists. */
+export function ensurePrivateDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(dir, 0o700);
+}
+/** Open a log file for appending, creating it (and its folder) owner-only. */
+export function openPrivateAppend(file) {
+    ensurePrivateDir(path.dirname(file));
+    return fs.openSync(file, "a", 0o600);
+}
+export function appendPrivate(file, text) {
+    const fd = openPrivateAppend(file);
+    try {
+        fs.writeSync(fd, text);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/lib/daemon/protocol-tail.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A service's protocol output read from a named pipe instead of an anonymous
+ * one.
+ *
+ * An anonymous pipe loses its reader when the daemon exits, so a service
+ * writing to one cannot be handed to the next daemon. Here the service's
+ * stdout is a FIFO it holds open for reading and writing, so it always has a
+ * reader and never gets EPIPE. Each daemon polls the FIFO without blocking and
+ * feeds what it reads to the supervisor as the child's stdout. On a handoff
+ * the daemon stops reading without draining, so output it has not read stays
+ * in the kernel buffer for the next daemon, and nothing accumulates on disk.
+ */
+export interface ProtocolTail {
+    /** "data" carries each chunk read; "end" fires once, after close(). */
+    on(event: "data" | "end", handler: (chunk?: Buffer | string) => void): ProtocolTail;
+    /** The service exited: read what is left, emit "end" and stop polling. */
+    close(): void;
+    /** Handing over: stop polling without reading, leaving the rest for the next daemon. */
+    detach(): void;
+}
+/** Make `file` a FIFO, replacing anything else found there. */
+export declare function ensureProtocolFifo(file: string): void;
+/**
+ * The service's stdout. Opened for reading and writing, so the FIFO keeps a
+ * reader while no daemon has it open and the service's writes never fail.
+ */
+export declare function openProtocolWriter(file: string): number;
+export declare function createProtocolTail(file: string, opts?: {
+    pollMs?: number;
+    setInterval?: (fn: () => void, ms: number) => unknown;
+    clearInterval?: (handle: unknown) => void;
+}): ProtocolTail;
+//# sourceMappingURL=protocol-tail.d.ts.map

package/dist/lib/daemon/protocol-tail.js

@@ -0,0 +1,131 @@
+/**
+ * A service's protocol output read from a named pipe instead of an anonymous
+ * one.
+ *
+ * An anonymous pipe loses its reader when the daemon exits, so a service
+ * writing to one cannot be handed to the next daemon. Here the service's
+ * stdout is a FIFO it holds open for reading and writing, so it always has a
+ * reader and never gets EPIPE. Each daemon polls the FIFO without blocking and
+ * feeds what it reads to the supervisor as the child's stdout. On a handoff
+ * the daemon stops reading without draining, so output it has not read stays
+ * in the kernel buffer for the next daemon, and nothing accumulates on disk.
+ */
+import { spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ensurePrivateDir } from "./paths.js";
+const POLL_MS = 1_000;
+const READ_CHUNK_BYTES = 64 * 1024;
+/** Make `file` a FIFO, replacing anything else found there. */
+export function ensureProtocolFifo(file) {
+    ensurePrivateDir(path.dirname(file));
+    try {
+        if (fs.lstatSync(file).isFIFO())
+            return;
+        fs.rmSync(file, { force: true });
+    }
+    catch {
+        // Missing: created below.
+    }
+    const r = spawnSync("mkfifo", ["-m", "600", file], { encoding: "utf8" });
+    if (r.error)
+        throw r.error;
+    if (r.status !== 0)
+        throw new Error(`mkfifo ${file} failed: ${(r.stderr ?? "").trim() || `exit ${r.status}`}`);
+}
+/**
+ * The service's stdout. Opened for reading and writing, so the FIFO keeps a
+ * reader while no daemon has it open and the service's writes never fail.
+ */
+export function openProtocolWriter(file) {
+    return fs.openSync(file, fs.constants.O_RDWR);
+}
+export function createProtocolTail(file, opts = {}) {
+    const events = new EventEmitter();
+    const setI = opts.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+    const clearI = opts.clearInterval ?? ((h) => clearInterval(h));
+    let fd = null;
+    let done = false;
+    const open = () => {
+        if (fd !== null)
+            return fd;
+        try {
+            fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+        }
+        catch {
+            fd = null;
+        }
+        return fd;
+    };
+    const read = () => {
+        const handle = open();
+        if (handle === null)
+            return;
+        const buf = Buffer.alloc(READ_CHUNK_BYTES);
+        for (;;) {
+            let n;
+            try {
+                n = fs.readSync(handle, buf, 0, buf.length, null);
+            }
+            catch (err) {
+                // EAGAIN: nothing written since the last read.
+                if (err.code === "EAGAIN")
+                    return;
+                throw err;
+            }
+            if (n <= 0)
+                return;
+            events.emit("data", Buffer.from(buf.subarray(0, n)));
+        }
+    };
+    const stop = () => {
+        done = true;
+        clearI(timer);
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // already closed
+            }
+            fd = null;
+        }
+    };
+    const timer = setI(() => {
+        try {
+            read();
+        }
+        catch {
+            // An unreadable FIFO reads as silence; the heartbeat watchdog restarts the service.
+        }
+    }, opts.pollMs ?? POLL_MS);
+    timer.unref?.();
+    // Open now, so the FIFO has a reader before the service starts writing.
+    open();
+    const tail = {
+        on(event, handler) {
+            events.on(event, handler);
+            return tail;
+        },
+        close() {
+            if (done)
+                return;
+            try {
+                read();
+            }
+            catch {
+                // nothing more to read
+            }
+            stop();
+            events.emit("end");
+        },
+        detach() {
+            if (done)
+                return;
+            stop();
+        },
+    };
+    return tail;
+}
+//# sourceMappingURL=protocol-tail.js.map

package/dist/lib/daemon/remote-control.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The remote-control service hosts (`hq daemon service remote-control` and
+ * `codex-remote-control`).
+ *
+ * Like the outpost runners, the command (`claude remote-control`, or the box's
+ * Codex runner) runs inside a detached tmux session so it has a terminal. This
+ * host process starts the session and watches it; the daemon supervises the
+ * host:
+ *
+ * - the session ends -> the host exits 1 and the daemon restarts it with
+ *   backoff (replacing the runner's `while true` loop and its watchdogs);
+ * - the daemon stops the host -> the host kills the session and exits 0;
+ * - a new version of the tool is installed (the updater, or the tool's own
+ *   auto-updater) -> once the session has been quiet for 10 minutes, or after
+ *   2 hours at the latest, the host kills the session and exits 0, and the
+ *   daemon starts it again on the new version. Reinstalling the same version
+ *   (a long-running Claude session's auto-updater does that every few
+ *   minutes) and hq-cli releases leave the session alone.
+ *
+ * The tmux server is a private socket (`-L hq-daemon`), so it never touches a
+ * user's own tmux sessions.
+ */
+import type { RunCommand } from "../service-manager/launchd.js";
+export declare const TMUX_SESSION = "remote-control";
+export declare const CODEX_TMUX_SESSION = "codex-remote-control";
+export declare function remoteControlArgs(opts: {
+    name: string;
+    permissionMode?: string;
+}): string[];
+/**
+ * The session name a box's own runner script passes to `claude remote-control`
+ * (`--name outpost-1-2`), so taking the runner over keeps the name people see.
+ */
+export declare function runnerSessionName(script: string): string | null;
+/**
+ * Which version of a tool is installed: the npm package that installs the
+ * binary (`name@version`), else the binary's real path and size. A native
+ * install's link points at a versioned file, so its real path is the version.
+ * The mtime is left out on purpose: reinstalling the same version rewrites
+ * the file, and that must not restart the session. Null while the tool
+ * cannot be read.
+ */
+export declare function toolFingerprint(bin: string): string | null;
+/**
+ * The tool a host runs: the path it was given, else the one found now. The
+ * daemon's plan leaves the path out, so a reinstall that briefly removes the
+ * tool's link cannot change the plan and restart the session.
+ */
+export declare function serviceTool(name: string, given: string | undefined, find: (name: string) => string | null): string;
+/** A tool updated on disk restarts its session once quiet this long... */
+export declare const IDLE_BEFORE_RESTART_MS: number;
+/** ...or after this long, however busy the session is. */
+export declare const MAX_RESTART_WAIT_MS: number;
+export interface RemoteControlHostDeps {
+    tmux: string;
+    /** tmux session name on the daemon's private socket. */
+    session: string;
+    /** Folder the command starts in (the HQ folder). */
+    cwd: string;
+    /** The command to keep running, binary first. */
+    argv: string[];
+    /** Name used in log lines ("claude remote-control"). */
+    label: string;
+    /** Identity of the tool's binary on disk; a change means it was updated. Null when it cannot be read. */
+    binaryFingerprint: () => string | null;
+    now: () => number;
+    run: RunCommand;
+    sleep: (ms: number) => Promise<void>;
+    pollMs: number;
+    signal: AbortSignal;
+    log: (line: string) => void;
+}
+export declare function runRemoteControlHost(deps: RemoteControlHostDeps): Promise<number>;
+//# sourceMappingURL=remote-control.d.ts.map