@indigoai-us/hq-cli 5.196.0 → 5.198.0

package/dist/lib/lanes/tracker-store.js

@@ -0,0 +1,277 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { LanesError } from "./errors.js";
+const KIND_SET = new Set(["blocker", "kpi", "okr", "directive"]);
+const ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+function storeError(error, message, details = {}) {
+    return new LanesError(error, message, details);
+}
+function validateId(id) {
+    if (!ID_RE.test(id) || id === "." || id === "..") {
+        throw storeError("tracker_id_invalid", "Tracker record id must be a safe path segment", { id });
+    }
+}
+function recordPath(root, kind, id) {
+    validateId(id);
+    if (!KIND_SET.has(kind))
+        throw storeError("tracker_kind_invalid", "Unknown tracker record kind", { kind });
+    return path.join(root, kind, `${id}.json`);
+}
+function assertRealDirectory(directory) {
+    try {
+        const stat = fs.lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw storeError("tracker_store_path_invalid", "Tracker storage path must be a real directory", { path: directory });
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        fs.mkdirSync(directory, { mode: 0o700 });
+    }
+}
+function ensureKindDirectory(root, kind) {
+    assertRealDirectory(root);
+    const directory = path.join(root, kind);
+    assertRealDirectory(directory);
+    return directory;
+}
+function existingKindDirectory(root, kind) {
+    try {
+        const rootStat = fs.lstatSync(root);
+        if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+            throw storeError("tracker_store_path_invalid", "Tracker storage path must be a real directory", { path: root });
+        }
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const directory = path.join(root, kind);
+    try {
+        const kindStat = fs.lstatSync(directory);
+        if (!kindStat.isDirectory() || kindStat.isSymbolicLink()) {
+            throw storeError("tracker_store_path_invalid", "Tracker kind path must be a real directory", { path: directory });
+        }
+        return directory;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+function parseRecord(text, expectedKind, id, file) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw storeError("tracker_record_malformed", "Tracker record contains invalid JSON", { kind: expectedKind, id, path: file });
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw storeError("tracker_record_invalid", "Tracker record must be a JSON object", { kind: expectedKind, id, path: file });
+    }
+    const record = value;
+    if (record.schema_version !== "hq-lanes-tracker-record.v1" ||
+        record.kind !== expectedKind ||
+        record.id !== id ||
+        typeof record.company !== "string" || !record.company ||
+        typeof record.project_id !== "string" || !record.project_id ||
+        !Number.isSafeInteger(record.version) || (record.version ?? 0) < 1 ||
+        typeof record.created_at !== "string" || typeof record.updated_at !== "string") {
+        throw storeError("tracker_record_invalid", "Tracker record is missing valid common fields", { kind: expectedKind, id, path: file });
+    }
+    return record;
+}
+function writeExclusive(file, contents) {
+    const dir = path.dirname(file);
+    const temp = path.join(dir, `.${path.basename(file)}.${randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(temp, contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        // link is an atomic create-if-absent operation; rename would overwrite a
+        // concurrent creator's record if a generated id ever collided.
+        fs.linkSync(temp, file);
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            throw storeError("tracker_record_exists", "Tracker record id already exists", { path: file });
+        }
+        throw err;
+    }
+    finally {
+        removeTempFile(temp);
+    }
+}
+function removeTempFile(file) {
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+function withRecordLock(file, action) {
+    const lock = `${file}.lock`;
+    let fd;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            fd = fs.openSync(lock, "wx", 0o600);
+            fs.writeSync(fd, `${process.pid}\n`);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            // Recover a lock only when it is old and its owner is gone. Rechecking
+            // inode and mtime before unlinking avoids deleting a freshly replaced lock.
+            let first;
+            try {
+                first = fs.lstatSync(lock);
+            }
+            catch (statError) {
+                if (statError.code === "ENOENT")
+                    continue;
+                throw statError;
+            }
+            if (Date.now() - first.mtimeMs < 5 * 60_000) {
+                throw storeError("tracker_write_busy", "Tracker record is being updated; retry the command", { path: file });
+            }
+            let owner = null;
+            try {
+                const raw = fs.readFileSync(lock, "utf8").trim();
+                const parsed = Number(raw);
+                if (Number.isSafeInteger(parsed) && parsed > 0)
+                    owner = parsed;
+            }
+            catch (readError) {
+                if (readError.code !== "ENOENT")
+                    throw readError;
+            }
+            if (owner !== null) {
+                try {
+                    process.kill(owner, 0);
+                    throw storeError("tracker_write_busy", "Tracker record is being updated; retry the command", { path: file });
+                }
+                catch (probeError) {
+                    if (probeError instanceof LanesError)
+                        throw probeError;
+                    if (probeError.code !== "ESRCH")
+                        throw probeError;
+                }
+            }
+            try {
+                const second = fs.lstatSync(lock);
+                if (second.ino === first.ino && second.dev === first.dev && second.mtimeMs === first.mtimeMs)
+                    fs.unlinkSync(lock);
+            }
+            catch (unlinkError) {
+                if (unlinkError.code !== "ENOENT")
+                    throw unlinkError;
+            }
+        }
+    }
+    if (fd === undefined)
+        throw storeError("tracker_write_busy", "Tracker record is being updated; retry the command", { path: file });
+    try {
+        return action();
+    }
+    finally {
+        fs.closeSync(fd);
+        fs.unlinkSync(lock);
+    }
+}
+export function createLocalTrackerStore(projectDirectory, now = () => new Date()) {
+    const root = path.join(projectDirectory, "tracker");
+    const read = (kind, id) => {
+        const file = recordPath(root, kind, id);
+        let text;
+        try {
+            const stat = fs.lstatSync(file);
+            if (!stat.isFile() || stat.isSymbolicLink()) {
+                throw storeError("tracker_record_invalid", "Tracker record path must be a regular file", { kind, id, path: file });
+            }
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        return parseRecord(text, kind, id, file);
+    };
+    return {
+        read,
+        list(kind) {
+            const directory = existingKindDirectory(root, kind);
+            if (directory === null)
+                return [];
+            return fs.readdirSync(directory)
+                .filter((name) => name.endsWith(".json"))
+                .sort()
+                .map((name) => {
+                const id = name.slice(0, -5);
+                return read(kind, id);
+            })
+                .filter((record) => record !== null)
+                .sort((a, b) => b.updated_at.localeCompare(a.updated_at) || a.id.localeCompare(b.id));
+        },
+        create(input) {
+            const kind = input.kind;
+            const directory = ensureKindDirectory(root, kind);
+            const id = typeof input.id === "string" && input.id ? input.id : randomUUID();
+            const time = now().toISOString();
+            const record = {
+                ...input,
+                schema_version: "hq-lanes-tracker-record.v1",
+                kind,
+                id,
+                company: input.company,
+                project_id: input.project_id,
+                version: 1,
+                created_at: time,
+                updated_at: time,
+            };
+            writeExclusive(path.join(directory, `${id}.json`), `${JSON.stringify(record, null, 2)}\n`);
+            return record;
+        },
+        update(kind, id, expectedVersion, change) {
+            const file = recordPath(root, kind, id);
+            const directory = ensureKindDirectory(root, kind);
+            return withRecordLock(file, () => {
+                const current = read(kind, id);
+                if (!current)
+                    throw storeError("tracker_record_not_found", `Tracker ${kind} record ${id} was not found`, { kind, id });
+                if (current.version !== expectedVersion) {
+                    throw storeError("tracker_version_conflict", `Tracker record version conflict: expected ${expectedVersion}, found ${current.version}`, {
+                        kind, id, expected: expectedVersion, actual: current.version,
+                    });
+                }
+                const changed = change(current);
+                if (changed.id !== current.id || changed.kind !== current.kind || changed.company !== current.company || changed.project_id !== current.project_id || changed.created_at !== current.created_at) {
+                    throw storeError("tracker_update_invalid", "Tracker update cannot change record identity", { kind, id });
+                }
+                const next = {
+                    ...changed,
+                    schema_version: "hq-lanes-tracker-record.v1",
+                    version: current.version + 1,
+                    created_at: current.created_at,
+                    updated_at: now().toISOString(),
+                };
+                const temp = path.join(directory, `.${id}.${randomUUID()}.tmp`);
+                try {
+                    fs.writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+                    fs.renameSync(temp, file);
+                }
+                finally {
+                    removeTempFile(temp);
+                }
+                return next;
+            });
+        },
+    };
+}
+//# sourceMappingURL=tracker-store.js.map

package/dist/lib/search-index/embed-lock.d.ts

@@ -12,9 +12,10 @@ export type EmbedLockProcessEvents = Pick<NodeJS.Process, 'once'> & {
 };
 export type EmbedLockRunResult = 'ran' | 'skipped' | 'busy' | 'unavailable';
 /**
- * Serializes embeddings started through hq-cli only. A bare `qmd embed` (or
- * another tool that does not call this module) cannot participate, because qmd
- * is a third-party package and does not know about HQ's lock protocol.
+ * Serializes QMD writes started through HQ-managed hq-cli paths. A bare `qmd
+ * update` / `qmd embed` (or another tool that does not call this module) cannot
+ * participate, because qmd is a third-party package and does not know about
+ * HQ's lock protocol.
  */
 export declare const EMBED_LOCK_NAME = "qmd-reindex-bg.lock";
 export declare function defaultEmbedLockDependencies(env?: NodeJS.ProcessEnv): EmbedLockDependencies;
@@ -26,7 +27,7 @@ export declare function releaseEmbedLock(home: string, dependencies: EmbedLockDe
 /** Install signal and exit cleanup for a lock owner, returning an optional unregister hook. */
 export declare function installEmbedLockCleanup(cleanup: () => void, processEvents?: EmbedLockProcessEvents, exit?: (code: number) => void): () => void;
 /**
- * Run one synchronous embed while owning the shared lock.
+ * Run one synchronous QMD write or reindex pass while owning the shared lock.
  *
  * This deliberately does not install signal handlers. `run` is a synchronous
  * qmd child, so JavaScript cannot execute a cleanup handler until it returns;

package/dist/lib/search-index/embed-lock.js

@@ -1,9 +1,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 /**
- * Serializes embeddings started through hq-cli only. A bare `qmd embed` (or
- * another tool that does not call this module) cannot participate, because qmd
- * is a third-party package and does not know about HQ's lock protocol.
+ * Serializes QMD writes started through HQ-managed hq-cli paths. A bare `qmd
+ * update` / `qmd embed` (or another tool that does not call this module) cannot
+ * participate, because qmd is a third-party package and does not know about
+ * HQ's lock protocol.
  */
 export const EMBED_LOCK_NAME = 'qmd-reindex-bg.lock';
 export function defaultEmbedLockDependencies(env = process.env) {
@@ -261,7 +262,7 @@ export function installEmbedLockCleanup(cleanup, processEvents = process, exit =
     };
 }
 /**
- * Run one synchronous embed while owning the shared lock.
+ * Run one synchronous QMD write or reindex pass while owning the shared lock.
  *
  * This deliberately does not install signal handlers. `run` is a synchronous
  * qmd child, so JavaScript cannot execute a cleanup handler until it returns;

package/dist/lib/search-index/reindex-single-flight-flag.d.ts

@@ -0,0 +1,5 @@
+export declare const QMD_REINDEX_SINGLE_FLIGHT_FLAG = "qmd.reindex-single-flight";
+export declare const QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK = false;
+/** Keep all HQ-managed QMD writers coordinated only for explicitly enabled canaries. */
+export declare function qmdReindexSingleFlightEnabled(): boolean;
+//# sourceMappingURL=reindex-single-flight-flag.d.ts.map

package/dist/lib/search-index/reindex-single-flight-flag.js

@@ -0,0 +1,8 @@
+import { resolveProcessFlagGate } from "../flag-registry.js";
+export const QMD_REINDEX_SINGLE_FLIGHT_FLAG = "qmd.reindex-single-flight";
+export const QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK = false;
+/** Keep all HQ-managed QMD writers coordinated only for explicitly enabled canaries. */
+export function qmdReindexSingleFlightEnabled() {
+    return resolveProcessFlagGate(QMD_REINDEX_SINGLE_FLIGHT_FLAG, { fallback: QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK }, () => QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK);
+}
+//# sourceMappingURL=reindex-single-flight-flag.js.map

package/dist/node-network-compat-flag.d.ts

@@ -0,0 +1,19 @@
+import type { FlagClient, FlagClientOptions } from "@indigoai-us/hq-flags-client";
+export declare const NODE_NETWORK_FORCE_IPV4_FLAG = "cli.network.force-ipv4";
+export declare const NODE_NETWORK_FORCE_IPV4_FLAG_FALLBACK = false;
+export declare const NODE_NETWORK_FORCE_IPV4_FLAG_TIMEOUT_MS = 1500;
+type NetworkFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface NodeNetworkForceIpv4Dependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => NetworkFlagClient;
+    getToken?: () => string | Promise<string>;
+    reportFailure?: (error: unknown) => void;
+}
+/**
+ * Read the opt-in hq-flags gate before CLI dispatch. Local hq-flags overrides
+ * work without a token or endpoint; service decisions require a company
+ * identity and use a short request deadline so startup remains bounded.
+ */
+export declare function nodeNetworkForceIpv4Enabled(dependencies?: NodeNetworkForceIpv4Dependencies): Promise<boolean>;
+export {};
+//# sourceMappingURL=node-network-compat-flag.d.ts.map

package/dist/node-network-compat-flag.js

@@ -0,0 +1,87 @@
+import { createFlagClient, readLocalOverride } from "@indigoai-us/hq-flags-client";
+export const NODE_NETWORK_FORCE_IPV4_FLAG = "cli.network.force-ipv4";
+export const NODE_NETWORK_FORCE_IPV4_FLAG_FALLBACK = false;
+// Node waits up to 1s before trying the next address family. Keep this request
+// deadline above that wait so a dead IPv6 path can reach the usable IPv4 host.
+export const NODE_NETWORK_FORCE_IPV4_FLAG_TIMEOUT_MS = 1_500;
+function safeErrorClass(error) {
+    const name = error instanceof Error ? error.name : "UnknownError";
+    return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name)
+        ? name
+        : "UnknownError";
+}
+function reportFlagFailure(error) {
+    process.stderr.write("HQ network IPv4 flag lookup failed (" +
+        safeErrorClass(error) +
+        "); using default off.\n");
+}
+async function loadCachedIdToken() {
+    const { loadCachedTokens } = await import("@indigoai-us/hq-cloud");
+    return loadCachedTokens()?.idToken ?? "";
+}
+/**
+ * Read the opt-in hq-flags gate before CLI dispatch. Local hq-flags overrides
+ * work without a token or endpoint; service decisions require a company
+ * identity and use a short request deadline so startup remains bounded.
+ */
+export async function nodeNetworkForceIpv4Enabled(dependencies = {}) {
+    const env = dependencies.env ?? process.env;
+    const localOverride = readLocalOverride(NODE_NETWORK_FORCE_IPV4_FLAG, env);
+    if (localOverride !== null)
+        return localOverride;
+    const endpoint = env.HQ_FLAGS_API_URL?.trim() || "";
+    const companyUid = env.HQ_COMPANY_UID?.trim() || "";
+    if (!endpoint ||
+        !/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return NODE_NETWORK_FORCE_IPV4_FLAG_FALLBACK;
+    }
+    const companySlug = env.HQ_COMPANY_SLUG?.trim() || "";
+    let client;
+    let failed = false;
+    let failureReported = false;
+    let enabled = NODE_NETWORK_FORCE_IPV4_FLAG_FALLBACK;
+    const reportFailureOnce = (error) => {
+        failed = true;
+        if (failureReported)
+            return;
+        failureReported = true;
+        (dependencies.reportFailure ?? reportFlagFailure)(error);
+    };
+    try {
+        const token = await (dependencies.getToken ?? loadCachedIdToken)();
+        if (!token)
+            return NODE_NETWORK_FORCE_IPV4_FLAG_FALLBACK;
+        const createClient = dependencies.createClient ?? createFlagClient;
+        client = createClient({
+            endpoint,
+            companyUid,
+            ...(companySlug && /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/.test(companySlug)
+                ? { companyIdentifiers: [companySlug] }
+                : {}),
+            env: {},
+            getToken: () => token,
+            refreshIntervalMs: 0,
+            requestTimeoutMs: NODE_NETWORK_FORCE_IPV4_FLAG_TIMEOUT_MS,
+            onError: reportFailureOnce,
+        });
+        await client.ready();
+        if (!failed) {
+            enabled = client.isEnabled(NODE_NETWORK_FORCE_IPV4_FLAG, {
+                fallback: NODE_NETWORK_FORCE_IPV4_FLAG_FALLBACK,
+            });
+        }
+    }
+    catch (error) {
+        reportFailureOnce(error);
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch (error) {
+            reportFailureOnce(error);
+        }
+    }
+    return failed ? NODE_NETWORK_FORCE_IPV4_FLAG_FALLBACK : enabled;
+}
+//# sourceMappingURL=node-network-compat-flag.js.map

package/dist/node-network-compat.d.ts

@@ -1,31 +1,28 @@
 /**
  * Node network defaults for HQ CLI entry points.
  *
- * Node's default 250 ms address-family attempt window can fail on hosts where
- * IPv6 is advertised but black-holed. On affected WSL installations, undici's
- * fetch() reaches ETIMEDOUT before its usable IPv4 path completes. A 1 second
- * window fixes the connection while retaining Node's automatic family choice.
+ * The compatibility timeout remains the default. On a canary where IPv6 is
+ * advertised but unusable, the default-off hq-flags gate can also prefer IPv4
+ * and disable automatic family racing before the CLI issues its first request.
  *
- * Keep this module dependency-free and import it immediately after the Node
- * version preflight. Operators can retain a custom value through NODE_OPTIONS
- * or a direct Node CLI option; HQ only supplies the compatibility default when
- * neither is present.
- *
- * Use a namespace import of `node:net` (not a static named import of
- * `setDefaultAutoSelectFamilyAttemptTimeout`). Named ESM imports are linked
- * before any entry-module body runs — including `node-preflight` — so importing
- * a Node 18.13+/20.4+ API by name would turn unsupported runtimes into a
- * module-link SyntaxError instead of the preflight's upgrade message.
+ * Keep this module safe to import immediately after the Node version preflight.
+ * The hq-flags reader loads dynamically so an unsupported runtime exits through
+ * the preflight rather than failing during module linking.
  */
 export declare const HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS = 1000;
 export interface NodeNetworkCompatibilityOptions {
     nodeOptions?: string;
     execArgv?: readonly string[];
+    forceIpv4?: boolean;
     /**
-     * Inject the net timeout setter (tests). Pass `null` to simulate a runtime
-     * that lacks `setDefaultAutoSelectFamilyAttemptTimeout`.
+     * Inject the net timeout setter (tests). Pass null to simulate a runtime
+     * that lacks setDefaultAutoSelectFamilyAttemptTimeout.
      */
     setAttemptTimeout?: ((milliseconds: number) => void) | null;
+    /** Inject Node's automatic family selection setter (tests). */
+    setAutoSelectFamily?: ((enabled: boolean) => void) | null;
+    /** Inject Node's DNS result-order setter (tests). */
+    setDefaultResultOrder?: ((order: "ipv4first") => void) | null;
 }
 export declare function configureNodeNetworkCompatibility(options?: NodeNetworkCompatibilityOptions): boolean;
 //# sourceMappingURL=node-network-compat.d.ts.map

package/dist/node-network-compat.js

@@ -1,30 +1,35 @@
 /**
  * Node network defaults for HQ CLI entry points.
  *
- * Node's default 250 ms address-family attempt window can fail on hosts where
- * IPv6 is advertised but black-holed. On affected WSL installations, undici's
- * fetch() reaches ETIMEDOUT before its usable IPv4 path completes. A 1 second
- * window fixes the connection while retaining Node's automatic family choice.
+ * The compatibility timeout remains the default. On a canary where IPv6 is
+ * advertised but unusable, the default-off hq-flags gate can also prefer IPv4
+ * and disable automatic family racing before the CLI issues its first request.
  *
- * Keep this module dependency-free and import it immediately after the Node
- * version preflight. Operators can retain a custom value through NODE_OPTIONS
- * or a direct Node CLI option; HQ only supplies the compatibility default when
- * neither is present.
- *
- * Use a namespace import of `node:net` (not a static named import of
- * `setDefaultAutoSelectFamilyAttemptTimeout`). Named ESM imports are linked
- * before any entry-module body runs — including `node-preflight` — so importing
- * a Node 18.13+/20.4+ API by name would turn unsupported runtimes into a
- * module-link SyntaxError instead of the preflight's upgrade message.
+ * Keep this module safe to import immediately after the Node version preflight.
+ * The hq-flags reader loads dynamically so an unsupported runtime exits through
+ * the preflight rather than failing during module linking.
  */
+import * as nodeDns from "node:dns";
 import * as nodeNet from "node:net";
 export const HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS = 1000;
 const ATTEMPT_TIMEOUT_OPTION = "--network-family-autoselection-attempt-timeout";
 function hasExplicitAttemptTimeout(nodeOptions, execArgv) {
-    const optionPattern = new RegExp(`(?:^|\\s)${ATTEMPT_TIMEOUT_OPTION}(?:=|\\s|$)`);
+    const optionPattern = new RegExp("(?:^|\\s)" + ATTEMPT_TIMEOUT_OPTION + "(?:=|\\s|$)");
     return (optionPattern.test(nodeOptions) ||
         execArgv.some((argument) => argument === ATTEMPT_TIMEOUT_OPTION ||
-            argument.startsWith(`${ATTEMPT_TIMEOUT_OPTION}=`)));
+            argument.startsWith(ATTEMPT_TIMEOUT_OPTION + "=")));
+}
+function hasExplicitFamilySelection(nodeOptions, execArgv) {
+    const optionPattern = /(?:^|\s)(?:--network-family-autoselection|--enable-network-family-autoselection|--no-network-family-autoselection|--dns-result-order)(?:=|\s|$)/;
+    return (optionPattern.test(nodeOptions) ||
+        execArgv.some((argument) => argument === "--network-family-autoselection" ||
+            argument === "--enable-network-family-autoselection" ||
+            argument === "--no-network-family-autoselection" ||
+            argument === "--dns-result-order" ||
+            argument.startsWith("--network-family-autoselection=") ||
+            argument.startsWith("--enable-network-family-autoselection=") ||
+            argument.startsWith("--no-network-family-autoselection=") ||
+            argument.startsWith("--dns-result-order=")));
 }
 function resolveSetAttemptTimeout(override) {
     if (override === null)
@@ -34,19 +39,69 @@ function resolveSetAttemptTimeout(override) {
     const fn = nodeNet.setDefaultAutoSelectFamilyAttemptTimeout;
     return typeof fn === "function" ? fn.bind(nodeNet) : undefined;
 }
+function resolveSetAutoSelectFamily(override) {
+    if (override === null)
+        return undefined;
+    if (override)
+        return override;
+    const fn = nodeNet.setDefaultAutoSelectFamily;
+    return typeof fn === "function" ? fn.bind(nodeNet) : undefined;
+}
+function resolveSetDefaultResultOrder(override) {
+    if (override === null)
+        return undefined;
+    if (override)
+        return override;
+    const fn = nodeDns.setDefaultResultOrder;
+    return typeof fn === "function" ? fn.bind(nodeDns) : undefined;
+}
+function applyIpv4Preference(options, nodeOptions, execArgv) {
+    if (!options.forceIpv4 || hasExplicitFamilySelection(nodeOptions, execArgv)) {
+        return false;
+    }
+    const setAutoSelectFamily = resolveSetAutoSelectFamily(options.setAutoSelectFamily);
+    const setDefaultResultOrder = resolveSetDefaultResultOrder(options.setDefaultResultOrder);
+    if (!setAutoSelectFamily || !setDefaultResultOrder)
+        return false;
+    setDefaultResultOrder("ipv4first");
+    setAutoSelectFamily(false);
+    return true;
+}
 export function configureNodeNetworkCompatibility(options = {}) {
     const nodeOptions = options.nodeOptions ?? process.env.NODE_OPTIONS ?? "";
     const execArgv = options.execArgv ?? process.execArgv;
+    const ipv4Applied = applyIpv4Preference(options, nodeOptions, execArgv);
     if (hasExplicitAttemptTimeout(nodeOptions, execArgv)) {
-        return false;
+        return ipv4Applied;
     }
     const setAttemptTimeout = resolveSetAttemptTimeout(options.setAttemptTimeout);
     if (!setAttemptTimeout) {
-        // Runtime lacks the API (pre-Node 18.13 / preflight should already have exited).
-        return false;
+        // Runtime lacks the API; the Node preflight should already have exited.
+        return ipv4Applied;
     }
     setAttemptTimeout(HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS);
     return true;
 }
+async function applyHqFlaggedIpv4Preference() {
+    try {
+        const { nodeNetworkForceIpv4Enabled } = await import("./node-network-compat-flag.js");
+        if (nodeNetworkForceIpv4Enabled &&
+            (await nodeNetworkForceIpv4Enabled())) {
+            configureNodeNetworkCompatibility({ forceIpv4: true });
+        }
+    }
+    catch (error) {
+        const rawName = error instanceof Error ? error.name : "UnknownError";
+        const errorName = /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(rawName)
+            ? rawName
+            : "UnknownError";
+        process.stderr.write("HQ network IPv4 flag lookup failed (" +
+            errorName +
+            "); using default off.\n");
+    }
+}
+// Preserve the historical timeout before any flag request. If the hq-flags
+// lookup succeeds, the IPv4 preference is applied before command dispatch.
 configureNodeNetworkCompatibility();
+await applyHqFlaggedIpv4Preference();
 //# sourceMappingURL=node-network-compat.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.196.0",
+  "version": "5.198.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {