@indigoai-us/hq-cli 5.196.0 → 5.197.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.197.0] — 2026-09-25
+
+### Fixed
+
+- Process-wide hq-flags gates now resolve with the active company's identifier when a company is bound.
+- Concurrent `hq lanes` updates now wait for an in-progress project story-ledger
+  lock receipt, avoiding transient `story_ledger_lock_invalid` errors.
+
 ## [5.196.0] — 2026-09-25
 
 ## [5.195.1] — 2026-09-25
@@ -31,6 +39,10 @@
   full name (for example "Chaudhry Hassaan Saleem" and "Hassaan Saleem"), is
   held back and reported as a suspect duplicate.
 
+- `hq auth` and other CLI fetches can opt into IPv4-first networking through the
+  default-off `cli.network.force-ipv4` hq-flags gate. The canary is bounded and
+  keeps explicit Node network options in control.
+
 ## [5.194.0] — 2026-09-25
 
 ### Added

package/dist/lib/flag-registry-worker.js

@@ -2,13 +2,24 @@
 import { parentPort, workerData } from "node:worker_threads";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { createFlagClient } from "@indigoai-us/hq-flags-client";
-const endpoint = workerData.endpoint;
+const data = workerData;
+const endpoint = data.endpoint;
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+const COMPANY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 async function refresh() {
     if (!parentPort || typeof endpoint !== "string" || endpoint.trim() === "")
         return;
     try {
+        const companyUid = typeof data.companyUid === "string" && COMPANY_UID_RE.test(data.companyUid)
+            ? data.companyUid
+            : undefined;
+        const companyIdentifiers = Array.isArray(data.companyIdentifiers)
+            ? data.companyIdentifiers.filter((value) => typeof value === "string" && COMPANY_SLUG_RE.test(value))
+            : [];
         const client = createFlagClient({
             endpoint,
+            ...(companyUid ? { companyUid } : {}),
+            ...(companyIdentifiers.length ? { companyIdentifiers } : {}),
             getToken: () => loadCachedTokens()?.idToken ?? "",
             refreshIntervalMs: 0,
             onError: () => { },

package/dist/lib/flag-registry.js

@@ -7,8 +7,15 @@
  */
 import { Worker } from "node:worker_threads";
 import { isFlagSnapshot, readLocalOverride, resolveFlag, } from "@indigoai-us/hq-flags-client";
+import { readMachineCompanyBinding } from "./work-context/company.js";
+import { readSessionState } from "./work-context/state.js";
+import { workContextRoot } from "./work-context/paths.js";
+import { readCompaniesManifestMap } from "./work-context/repo-remote.js";
+import { resolveDefaultHqRoot } from "../utils/cognito-session.js";
 /** Dedicated endpoint configuration; this is intentionally not HQ_PRO_API_URL. */
 export const FLAG_REGISTRY_ENDPOINT_ENV = "HQ_FLAGS_API_URL";
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+const COMPANY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 let heldSnapshot = null;
 let processReader = null;
 function processLocalOverride(flagKey) {
@@ -17,14 +24,66 @@ function processLocalOverride(flagKey) {
 function localOverrideOrFallback(flagKey, legacyFallback) {
     return processLocalOverride(flagKey) ?? legacyFallback();
 }
-function processSnapshotReader() {
+function normalizedCompanyUid(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_UID_RE.test(candidate) ? candidate : undefined;
+}
+function normalizedCompanySlug(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_SLUG_RE.test(candidate) ? candidate : undefined;
+}
+/**
+ * Resolve only an explicit machine/session company binding. Device defaults
+ * and cwd/repository heuristics do not scope process-wide feature flags.
+ */
+function processCompanyContext(env = process.env) {
+    const explicitUid = normalizedCompanyUid(env.HQ_COMPANY_UID);
+    const explicitSlug = normalizedCompanySlug(env.HQ_COMPANY_SLUG);
+    if (explicitUid || explicitSlug) {
+        return { companyUid: explicitUid, companySlug: explicitSlug };
+    }
+    const machine = readMachineCompanyBinding(env);
+    const spawnValue = env.HQ_SPAWN_COMPANY?.trim();
+    const spawnSlug = normalizedCompanySlug(spawnValue);
+    const machineContext = spawnValue && COMPANY_UID_RE.test(spawnValue)
+        ? { companyUid: spawnValue }
+        : spawnSlug
+            ? { companySlug: spawnSlug }
+            : {
+                companyUid: normalizedCompanyUid(machine?.uid),
+                companySlug: normalizedCompanySlug(machine?.slug),
+            };
+    if (machineContext.companyUid || machineContext.companySlug)
+        return machineContext;
+    const sessionId = env.HQ_SESSION_ID?.trim();
+    if (!sessionId)
+        return {};
+    const session = readSessionState(sessionId, workContextRoot(undefined, env));
+    if (session?.contextStatus !== "bound" || session.companyConfidence === "device_default") {
+        return {};
+    }
+    return {
+        companyUid: normalizedCompanyUid(session.companyUid),
+        companySlug: normalizedCompanySlug(session.companySlug),
+    };
+}
+function companyUidForContext(context, env = process.env) {
+    if (context.companyUid)
+        return context.companyUid;
+    if (!context.companySlug)
+        return undefined;
+    const hqRoot = resolveDefaultHqRoot({ env });
+    const manifestUid = readCompaniesManifestMap(hqRoot)?.[context.companySlug]?.cloud_uid;
+    return typeof manifestUid === "string" ? normalizedCompanyUid(manifestUid) : undefined;
+}
+function processSnapshotReader(companyIdentifiers) {
     return {
         isEnabled(flagKey, lookup = {}) {
             return resolveFlag({
                 flagKey,
                 env: process.env,
                 snapshot: heldSnapshot,
-                companyIdentifiers: [],
+                companyIdentifiers,
                 lookup,
             }).value;
         },
@@ -45,9 +104,18 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
     const endpoint = (dependencies.endpoint ?? process.env[FLAG_REGISTRY_ENDPOINT_ENV] ?? "").trim();
     if (!endpoint)
         return null;
-    processReader = processSnapshotReader();
+    const company = processCompanyContext();
+    const companyUid = companyUidForContext(company);
+    const companyIdentifiers = [companyUid, company.companySlug].filter((value) => Boolean(value));
+    processReader = processSnapshotReader(companyIdentifiers);
     try {
-        const worker = (dependencies.createWorker ?? ((filename, options) => new Worker(filename, options)))(new URL("./flag-registry-worker.js", import.meta.url), { workerData: { endpoint } });
+        const worker = (dependencies.createWorker ?? ((filename, options) => new Worker(filename, options)))(new URL("./flag-registry-worker.js", import.meta.url), {
+            workerData: {
+                endpoint,
+                ...(companyUid ? { companyUid } : {}),
+                ...(company.companySlug ? { companyIdentifiers: [company.companySlug] } : {}),
+            },
+        });
         worker.on("message", (value) => {
             if (isFlagSnapshot(value))
                 heldSnapshot = value;

package/dist/lib/lanes/story-ledger.js

@@ -122,6 +122,11 @@ function lockPathFor(filePath) {
 function lockOwnerPath(lockPath) {
     return path.join(lockPath, "owner.json");
 }
+function isInvalidLockOwnerReceipt(err, lockPath) {
+    return err instanceof LanesError &&
+        err.error === "story_ledger_lock_invalid" &&
+        err.details.path === lockOwnerPath(lockPath);
+}
 function readLockOwner(lockPath) {
     const ownerPath = lockOwnerPath(lockPath);
     let contents;
@@ -157,15 +162,17 @@ function lockSleep(deps, ms) {
 }
 function restoreMovedLockWithoutReplacement(lockPath, stalePath) {
     const entries = fs.readdirSync(stalePath);
-    if (entries.some((entry) => entry !== "owner.json")) {
+    const isOwnerTemp = (entry) => /^\.owner-[a-f0-9]{24}\.tmp$/.test(entry);
+    if (entries.some((entry) => entry !== "owner.json" && !isOwnerTemp(entry))) {
         throw new Error("Unexpected entry in moved story ledger lock");
     }
-    const ownerContents = entries.includes("owner.json")
-        ? fs.readFileSync(lockOwnerPath(stalePath), "utf8")
-        : undefined;
+    const files = entries.map((entry) => ({
+        name: entry,
+        contents: fs.readFileSync(path.join(stalePath, entry), "utf8"),
+    }));
     fs.mkdirSync(lockPath);
-    if (ownerContents !== undefined) {
-        fs.writeFileSync(lockOwnerPath(lockPath), ownerContents, {
+    for (const file of files) {
+        fs.writeFileSync(path.join(lockPath, file.name), file.contents, {
             encoding: "utf8",
             flag: "wx",
             mode: 0o600,
@@ -186,10 +193,18 @@ function clearStaleLock(lockPath, deps) {
     if (!stat.isDirectory() || stat.isSymbolicLink()) {
         throw new LanesError("story_ledger_lock_invalid", "Story ledger lock path is not a regular directory: " + lockPath, { path: lockPath });
     }
-    const ownerRead = readLockOwner(lockPath);
-    const hasOwnerToken = hasLockOwnerToken(ownerRead);
+    let ownerRead;
+    try {
+        ownerRead = readLockOwner(lockPath);
+    }
+    catch (err) {
+        if (!isInvalidLockOwnerReceipt(err, lockPath) || lockNow(deps) - stat.mtimeMs >= LOCK_STALE_MS) {
+            throw err;
+        }
+        return false;
+    }
     let lockAt = stat.mtimeMs;
-    if (hasOwnerToken && typeof ownerRead.owner.at === "string") {
+    if (hasLockOwnerToken(ownerRead) && typeof ownerRead.owner.at === "string") {
         const parsedAt = Date.parse(ownerRead.owner.at);
         if (Number.isFinite(parsedAt))
             lockAt = parsedAt;
@@ -207,7 +222,26 @@ function clearStaleLock(lockPath, deps) {
         throw err;
     }
     const moved = fs.lstatSync(stalePath);
-    const movedOwnerRead = readLockOwner(stalePath);
+    let movedOwnerRead;
+    try {
+        movedOwnerRead = readLockOwner(stalePath);
+    }
+    catch (err) {
+        if (!isInvalidLockOwnerReceipt(err, stalePath))
+            throw err;
+        const stillFresh = lockNow(deps) - moved.mtimeMs < LOCK_STALE_MS;
+        try {
+            // Put the moved directory back before retrying or reporting the invalid receipt.
+            restoreMovedLockWithoutReplacement(lockPath, stalePath);
+        }
+        catch {
+            throw new LanesError("story_ledger_lock_race", "A replacement story ledger lock was preserved at " + stalePath +
+                " because it could not safely be restored to " + lockPath, { path: lockPath, preserved_path: stalePath });
+        }
+        if (stillFresh)
+            return false;
+        throw err;
+    }
     let movedLockAt = moved.mtimeMs;
     if (hasLockOwnerToken(movedOwnerRead) && typeof movedOwnerRead.owner.at === "string") {
         const parsedAt = Date.parse(movedOwnerRead.owner.at);
@@ -239,7 +273,14 @@ function acquireLedgerLock(filePath, deps) {
     while (lockNow(deps) - started < timeoutMs) {
         try {
             fs.mkdirSync(lockPath);
-            fs.writeFileSync(lockOwnerPath(lockPath), JSON.stringify({ pid: process.pid, token, at: new Date(lockNow(deps)).toISOString() }) + "\n", { mode: 0o600 });
+            const ownerTempPath = path.join(lockPath, ".owner-" + token + ".tmp");
+            try {
+                fs.writeFileSync(ownerTempPath, JSON.stringify({ pid: process.pid, token, at: new Date(lockNow(deps)).toISOString() }) + "\n", { encoding: "utf8", flag: "wx", mode: 0o600 });
+                fs.renameSync(ownerTempPath, lockOwnerPath(lockPath));
+            }
+            finally {
+                fs.rmSync(ownerTempPath, { force: true });
+            }
             return { lockPath, token };
         }
         catch (err) {

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.197.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {