@indigoai-us/hq-cli 5.345.1 → 5.345.2

package/dist/hq-cloud-sync-runner/package.json

@@ -0,0 +1 @@
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.33","bundleSha256":"ac95a726e29b0c0db65da6753d3c4e249f3f8a0cf7d56fe7579ac1804a14f34f","formatVersion":1}

package/dist/index.js

@@ -138,8 +138,9 @@ function packageUseErrorClass(error) {
     return typeof value.name === "string" ? value.name : "unknown";
 }
 function dispatchWithPackageUseLease(entryUrl, dispatch, loadLease = async () => {
-    const { acquireCurrentPackageUseLease } = await import("./utils/package-use-lease.js");
+    const { acquireCurrentPackageUseLease, signalPackageUseLeaseBootstrapHandoff } = await import("./utils/package-use-lease.js");
     acquireCurrentPackageUseLease();
+    signalPackageUseLeaseBootstrapHandoff();
 }, updateRequestPending = async () => {
     const { currentPackageUseUpdatePending } = await import("./utils/package-use-lease.js");
     return currentPackageUseUpdatePending();

package/dist/lib/daemon/hq-child-bootstrap-stage.d.ts

@@ -0,0 +1,22 @@
+/** Atomic, content-addressed staging for the daemon's replace-independent hq launcher. */
+import * as fs from "node:fs";
+export declare const HQ_CHILD_BOOTSTRAP_FILE = "hq-child-bootstrap.mjs";
+export type HqChildBootstrapStageErrorCode = "SOURCE_MISSING" | "STAGE_INVALID" | "COPY_FAILED" | "HASH_MISMATCH" | "FSYNC_FAILED" | "RENAME_FAILED";
+export declare class HqChildBootstrapStageError extends Error {
+    readonly code: HqChildBootstrapStageErrorCode;
+    constructor(code: HqChildBootstrapStageErrorCode, message: string, options?: ErrorOptions);
+}
+export interface StagedHqChildBootstrap {
+    directory: string;
+    bootstrapPath: string;
+    sha256: string;
+}
+export interface StageHqChildBootstrapOptions {
+    sourcePath?: string;
+    daemonRoot: string;
+    copyFile?: typeof fs.copyFileSync;
+    renameDirectory?: (from: string, to: string) => void;
+}
+/** Stage only a complete, content-verified bootstrap; temporary siblings are never selected. */
+export declare function stageHqChildBootstrap(options: StageHqChildBootstrapOptions): StagedHqChildBootstrap;
+//# sourceMappingURL=hq-child-bootstrap-stage.d.ts.map

package/dist/lib/daemon/hq-child-bootstrap-stage.js

@@ -0,0 +1,127 @@
+/** Atomic, content-addressed staging for the daemon's replace-independent hq launcher. */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensurePrivateDir } from "./paths.js";
+export const HQ_CHILD_BOOTSTRAP_FILE = "hq-child-bootstrap.mjs";
+export class HqChildBootstrapStageError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "HqChildBootstrapStageError";
+    }
+}
+function fail(code, message, cause) {
+    if (cause instanceof HqChildBootstrapStageError)
+        throw cause;
+    throw new HqChildBootstrapStageError(code, message, cause === undefined ? undefined : { cause });
+}
+function hashFile(file) {
+    return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+function syncFile(file) {
+    const fd = fs.openSync(file, "r");
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function syncDirectory(directory) {
+    const fd = fs.openSync(directory, fs.constants.O_RDONLY);
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function readStage(directory, expectedHash) {
+    if (!fs.existsSync(directory))
+        return null;
+    const bootstrapPath = path.join(directory, HQ_CHILD_BOOTSTRAP_FILE);
+    try {
+        if (!fs.statSync(bootstrapPath).isFile() || hashFile(bootstrapPath) !== expectedHash) {
+            fail("STAGE_INVALID", "An existing daemon hq bootstrap stage is invalid; preserving it");
+        }
+    }
+    catch (error) {
+        fail("STAGE_INVALID", "Unable to validate the existing daemon hq bootstrap stage", error);
+    }
+    return { directory, bootstrapPath, sha256: expectedHash };
+}
+/** Stage only a complete, content-verified bootstrap; temporary siblings are never selected. */
+export function stageHqChildBootstrap(options) {
+    const sourcePath = options.sourcePath ?? path.join(path.dirname(fileURLToPath(import.meta.url)), HQ_CHILD_BOOTSTRAP_FILE);
+    try {
+        if (!fs.statSync(sourcePath).isFile())
+            fail("SOURCE_MISSING", "The daemon hq bootstrap source is missing");
+    }
+    catch (error) {
+        fail("SOURCE_MISSING", "Unable to access the daemon hq bootstrap source", error);
+    }
+    let expectedHash;
+    try {
+        expectedHash = hashFile(sourcePath);
+    }
+    catch (error) {
+        fail("SOURCE_MISSING", "Unable to read the daemon hq bootstrap source", error);
+    }
+    const stageRoot = path.join(options.daemonRoot, "bundles", "hq-child-bootstrap");
+    const selectedDirectory = path.join(stageRoot, expectedHash);
+    const existing = readStage(selectedDirectory, expectedHash);
+    if (existing)
+        return existing;
+    let tempDirectory;
+    let failureCode = "COPY_FAILED";
+    try {
+        ensurePrivateDir(stageRoot);
+        tempDirectory = path.join(stageRoot, `.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`);
+        fs.mkdirSync(tempDirectory, { mode: 0o700 });
+        (options.copyFile ?? fs.copyFileSync)(sourcePath, path.join(tempDirectory, HQ_CHILD_BOOTSTRAP_FILE));
+        const stagedPath = path.join(tempDirectory, HQ_CHILD_BOOTSTRAP_FILE);
+        if (hashFile(stagedPath) !== expectedHash)
+            fail("HASH_MISMATCH", "The staged daemon hq bootstrap hash does not match");
+        failureCode = "FSYNC_FAILED";
+        syncFile(stagedPath);
+        syncDirectory(tempDirectory);
+        failureCode = "RENAME_FAILED";
+        try {
+            (options.renameDirectory ?? fs.renameSync)(tempDirectory, selectedDirectory);
+        }
+        catch (error) {
+            if (error.code === "EEXIST" || error.code === "ENOTEMPTY") {
+                const raced = readStage(selectedDirectory, expectedHash);
+                if (raced) {
+                    fs.rmSync(tempDirectory, { recursive: true, force: true });
+                    return raced;
+                }
+            }
+            fail("RENAME_FAILED", "Unable to atomically select the daemon hq bootstrap", error);
+        }
+        tempDirectory = undefined;
+        failureCode = "FSYNC_FAILED";
+        syncDirectory(stageRoot);
+    }
+    catch (error) {
+        if (tempDirectory) {
+            try {
+                fs.rmSync(tempDirectory, { recursive: true, force: true });
+            }
+            catch (cleanupError) {
+                fail("COPY_FAILED", "Unable to remove the temporary daemon hq bootstrap stage", new AggregateError([error, cleanupError]));
+            }
+        }
+        if (error instanceof HqChildBootstrapStageError)
+            throw error;
+        fail(failureCode, "Unable to stage the daemon hq bootstrap", error);
+    }
+    const staged = readStage(selectedDirectory, expectedHash);
+    if (!staged)
+        fail("FSYNC_FAILED", "The completed daemon hq bootstrap failed validation");
+    return staged;
+}
+//# sourceMappingURL=hq-child-bootstrap-stage.js.map

package/dist/lib/daemon/hq-child-bootstrap.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=hq-child-bootstrap.d.mts.map

package/dist/lib/daemon/hq-child-bootstrap.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// This staged launcher intentionally imports Node built-ins only. It waits for
+// the desktop update protocol and publishes its own lease before reading the
+// replaceable CLI entry, then hands that lease off after the child publishes
+// its normal package-use lease.
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { performance } from "node:perf_hooks";
+const UPDATE_REQUEST = "update.pending.json";
+const HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_HANDOFF_TOKEN";
+const LEASE_WAIT_MS = 30_000;
+function packageUseStateDirectory() {
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (!localAppData)
+            throw new Error("LOCALAPPDATA is unavailable for the HQ CLI package-use lease");
+        return path.join(localAppData, "hq-cli", "state", "package-use");
+    }
+    return path.join(process.env.XDG_STATE_HOME?.trim() || path.join(os.homedir(), ".local", "state"), "hq-cli", "package-use");
+}
+function normalizedPrefix(prefix) {
+    let normalized = fs.realpathSync.native(prefix).replace(/\\/g, "/");
+    normalized = normalized.replace(/^\\\\\?\\UNC\\/i, "//").replace(/^\\\\\?\\/, "");
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function getLeaseDirectory(prefix) {
+    const digest = createHash("sha256").update(normalizedPrefix(prefix), "utf8").digest("hex");
+    return path.join(packageUseStateDirectory(), digest);
+}
+function updateRequestIsActive(requestPath) {
+    let request;
+    try {
+        request = JSON.parse(fs.readFileSync(requestPath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw new Error("Unable to read the HQ CLI update request");
+    }
+    const pid = request.pid;
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        throw new Error("The HQ CLI update request is invalid");
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        if (error.code === "ESRCH") {
+            fs.rmSync(requestPath, { force: true });
+            return false;
+        }
+    }
+    return true;
+}
+let requestedSignal = null;
+let child = null;
+const forwardedSignals = process.platform === "win32"
+    ? ["SIGINT", "SIGTERM"]
+    : ["SIGINT", "SIGTERM", "SIGHUP"];
+for (const signal of forwardedSignals) {
+    process.on(signal, () => {
+        requestedSignal = signal;
+        if (child?.pid && child.exitCode === null && child.signalCode === null)
+            child.kill(signal);
+    });
+}
+async function waitForRequestToClear(requestPath, started) {
+    while (updateRequestIsActive(requestPath)) {
+        if (requestedSignal)
+            throw new Error(`Interrupted by ${requestedSignal}`);
+        if (Date.now() - started >= LEASE_WAIT_MS)
+            throw new Error("The HQ CLI package is being updated; retry after it finishes");
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+async function acquireBootstrapLease(prefix, version) {
+    const directory = getLeaseDirectory(prefix);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const requestPath = path.join(directory, UPDATE_REQUEST);
+    const record = {
+        pid: process.pid,
+        start_time_ms: Math.floor(performance.timeOrigin),
+        hq_version: version,
+    };
+    const leasePath = path.join(directory, `${record.pid}-${record.start_time_ms}.json`);
+    const tempPath = `${leasePath}.${randomBytes(8).toString("hex")}.tmp`;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        await waitForRequestToClear(requestPath, Date.now());
+        try {
+            fs.writeFileSync(tempPath, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
+            fs.renameSync(tempPath, leasePath);
+        }
+        catch (error) {
+            fs.rmSync(tempPath, { force: true });
+            throw new Error("Unable to publish the daemon hq bootstrap lease", { cause: error });
+        }
+        if (!updateRequestIsActive(requestPath))
+            return { directory, leasePath };
+        fs.rmSync(leasePath, { force: true });
+    }
+    throw new Error("An HQ CLI update is waiting for the package lease; retry when it finishes");
+}
+function resolveInstalledEntry(prefix) {
+    const packageName = path.join("@indigoai-us", "hq-cli");
+    const packageRoots = [
+        path.join(prefix, "lib", "node_modules", packageName),
+        path.join(prefix, "node_modules", packageName),
+    ];
+    for (const packageRoot of packageRoots) {
+        let metadata;
+        try {
+            metadata = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT" || error.code === "ENOTDIR")
+                continue;
+            throw new Error("Unable to read the installed HQ CLI package metadata", { cause: error });
+        }
+        if (metadata.name !== "@indigoai-us/hq-cli" || typeof metadata.bin?.hq !== "string")
+            continue;
+        const entry = path.resolve(packageRoot, metadata.bin.hq);
+        const relative = path.relative(packageRoot, entry);
+        if (relative.startsWith(`..${path.sep}`) || relative === ".." || path.isAbsolute(relative)) {
+            throw new Error("The installed HQ CLI entry is outside its package directory");
+        }
+        if (fs.statSync(entry).isFile())
+            return entry;
+    }
+    throw new Error("The installed HQ CLI entry could not be resolved after the update request cleared");
+}
+function relaySignal(signal) {
+    for (const forwarded of forwardedSignals)
+        process.removeAllListeners(forwarded);
+    process.kill(process.pid, signal);
+    throw new Error(`Unable to relay ${signal}`);
+}
+async function run() {
+    const [prefix, version, ...args] = process.argv.slice(2);
+    if (!prefix || !version)
+        throw new Error("The daemon hq bootstrap arguments are invalid");
+    const lease = await acquireBootstrapLease(prefix, version);
+    const token = randomBytes(16).toString("hex");
+    const markerPathFor = (pid) => path.join(lease.directory, `handoff-${pid}-${token}.handoff`);
+    let handoffMarker = null;
+    let leaseReleased = false;
+    const releaseLease = () => {
+        if (leaseReleased)
+            return;
+        leaseReleased = true;
+        fs.rmSync(lease.leasePath, { force: true });
+    };
+    try {
+        if (requestedSignal)
+            return relaySignal(requestedSignal);
+        // This resolution is deliberately after the update request is clear and
+        // after the bootstrap lease record protects the package from replacement.
+        const entry = resolveInstalledEntry(prefix);
+        child = spawn(process.execPath, [entry, ...args], {
+            env: { ...process.env, [HANDOFF_ENV]: token },
+            stdio: "inherit",
+            windowsHide: true,
+        });
+        child.once("error", (error) => {
+            process.stderr.write(`hq daemon child bootstrap could not start the CLI (${error.code ?? error.name})\n`);
+        });
+        if (child.pid !== undefined)
+            handoffMarker = markerPathFor(child.pid);
+        const exit = await new Promise((resolve, reject) => {
+            if (!child)
+                return reject(new Error("The HQ CLI child did not start"));
+            child.once("error", reject);
+            child.once("exit", (code, signal) => resolve({ code, signal }));
+            const poll = setInterval(() => {
+                if (!handoffMarker || leaseReleased || !fs.existsSync(handoffMarker))
+                    return;
+                fs.rmSync(handoffMarker, { force: true });
+                releaseLease();
+            }, 20);
+            child.once("exit", () => clearInterval(poll));
+            child.once("error", () => clearInterval(poll));
+        });
+        if (!leaseReleased)
+            releaseLease();
+        if (handoffMarker)
+            fs.rmSync(handoffMarker, { force: true });
+        if (requestedSignal)
+            return relaySignal(requestedSignal);
+        if (exit.signal)
+            return relaySignal(exit.signal);
+        return exit.code ?? 1;
+    }
+    finally {
+        if (!leaseReleased)
+            releaseLease();
+        if (handoffMarker)
+            fs.rmSync(handoffMarker, { force: true });
+    }
+}
+void run().then((code) => { process.exitCode = code; }, (error) => {
+    const signal = requestedSignal;
+    process.stderr.write(`hq daemon child bootstrap failed (${error instanceof Error ? error.name : "unknown"})\n`);
+    if (signal)
+        relaySignal(signal);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=hq-child-bootstrap.mjs.map

package/dist/lib/daemon/hq-cloud.d.ts

@@ -17,6 +17,9 @@ export interface PickedHqCloud extends HqCloudCopy {
     /** Set when a version is pinned but that version is not the installed managed copy. */
     pinnedVersionMissing?: string;
 }
+export type ManagedHqCloud = PickedHqCloud & {
+    source: "managed";
+};
 export declare function managedHqCloudDir(daemonRoot: string): string;
 /** The package folder inside the updater's install prefix. */
 export declare function managedHqCloudRoot(daemonRoot: string): string;
@@ -56,6 +59,8 @@ export declare function hqCloudInstallCommand(prefix: string, version: string, p
 export declare function bundledHqCloud(): HqCloudCopy | null;
 /** The hq-cloud the daemon should run right now. */
 export declare function currentHqCloud(daemonRoot: string): PickedHqCloud | null;
+/** After the CLI package lease is released, only daemon-owned package files are eligible. */
+export declare function currentHqCloudAfterLeaseRelease(daemonRoot: string, expectedVersion?: string | null): ManagedHqCloud | null;
 export interface HqCloudUpdateOutcome {
     ok: boolean;
     from: string | null;

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

@@ -132,6 +132,20 @@ export function currentHqCloud(daemonRoot) {
     const pinnedVersion = readDaemonConfig(path.join(daemonRoot, "config.json")).hqCloudVersion;
     return pickHqCloud(bundledHqCloud(), readHqCloudCopy(managedHqCloudRoot(daemonRoot)), (copy) => hqCloudRunners(copy.root).syncRunner !== null, pinnedVersion);
 }
+/** After the CLI package lease is released, only daemon-owned package files are eligible. */
+export function currentHqCloudAfterLeaseRelease(daemonRoot, expectedVersion) {
+    const config = readDaemonConfig(path.join(daemonRoot, "config.json"));
+    const managed = readHqCloudCopy(managedHqCloudRoot(daemonRoot));
+    if (!managed || !hqCloudRunners(managed.root).syncRunner)
+        return null;
+    if (config.hqCloudVersion && config.hqCloudVersion !== managed.version)
+        return null;
+    const expected = parseVersion(config.hqCloudVersion ?? expectedVersion ?? "");
+    const actual = parseVersion(managed.version);
+    if (!expected || !actual || expected[0] !== actual[0])
+        return null;
+    return { ...managed, source: "managed" };
+}
 function runNpm(file, args, shell, env) {
     return spawnSync(file, args, {
         encoding: "utf8",

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

@@ -9,6 +9,7 @@ import { type UnitPlan } from "./catalog.js";
 import { type LegacyUnit } from "./legacy.js";
 import { type DaemonLockResult } from "./lock.js";
 import { type MachineType } from "./machine-type.js";
+import { type PickedHqCloud } from "./hq-cloud.js";
 import { type HostApp } from "./supervisor.js";
 export declare const LOG_ROTATE_BYTES: number;
 /** Exit code for "restart me": non-zero so every service manager relaunches (Windows tasks only restart on failure). */
@@ -34,9 +35,34 @@ export interface RunDaemonOptions {
     env?: NodeJS.ProcessEnv;
     nodeBinary: string;
     hqBinary: string;
-    /** Called after the initial supervisor plan has finished package-backed startup reads. */
-    onStartupReadsComplete?: () => void;
+    /** Called after initial reads; returns true only when the lease was actually released. */
+    onStartupReadsComplete?: () => boolean | void;
+    /** Test seam; defaults to the payload emitted by the hq-cli package build. */
+    syncRunnerBundleDirectory?: string;
+    /** Test seam; the replaceable hq-cli package root. */
+    cliPackageRoot?: string | null;
+    /** Test seam; the npm prefix whose installed hq entry is protected by package-use leases. */
+    cliPackagePrefix?: string | null;
+    /** Test seam for atomic staging failure coverage. */
+    hqChildBootstrapSourcePath?: string;
 }
+export type SyncRunnerSource = {
+    kind: "staged-sync";
+    runnerPath: string;
+} | {
+    kind: "managed-full-package";
+    runnerPath: string | null;
+} | {
+    kind: "bundled-full-package";
+    runnerPath: string | null;
+} | {
+    kind: "unavailable";
+    runnerPath: null;
+};
+export declare function syncRunnerSourceForPlan(stagedRunnerPath: string | null, hqCloud: PickedHqCloud | null, legacyBundledRunnerPath?: string | null): SyncRunnerSource;
+/** Whether every executable in the first service plan remains usable after the CLI package is replaced. */
+export declare function daemonPlanCanReleasePackageUseLease(plans: readonly UnitPlan[], replaceablePackageRoots: readonly string[], stagingFailed: boolean, hqBootstrapReady?: boolean): boolean;
+export declare function daemonHqChildCommand(nodeBinary: string, hqBinary: string, args: readonly string[], bootstrapPath: string | null, packagePrefix: string | null): [string, string[]];
 export declare function resolveSyncRunnerPath(): string | null;
 /** The hosted desktop app uses this env value when planning daemon services. */
 export declare function daemonInstantSyncEnabled(env: NodeJS.ProcessEnv, configured?: boolean): boolean;