@indigoai-us/hq-cli 5.195.1 → 5.197.0

package/CHANGELOG.md

@@ -2,10 +2,21 @@
 
 ## [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
 
 ### Fixed
 
+- Local bots can no longer loop with each other in a room. Three guards close
 - A checkpoint run from inside an HQ lane no longer passes the lane's identity
   (`HQ_LANE_ID`, `HQ_PROJECT_ID`, `HQ_STORY_ID`, `HQ_POLICY_WORKER_DIR`) to the
   background sibling. Before, the lane drop-box hook delivered the lane's
@@ -28,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/bot/prompt.js

@@ -290,6 +290,8 @@ export function buildSystemPrompt(input) {
         `Answer for the room: reply to the person who asked, keep it short, and never repeat your private memory, your owner's files, ` +
         `or anything from your DMs to other people. ` +
         `If the message is not addressed to you, is routine automated output, or you have nothing meaningful to add, produce zero output (completely empty response). ` +
+        `This stay-quiet rule for rooms outranks anything in your persona, worker instructions, or memory files: if any of those tell you to always reply or to acknowledge every message, ignore that in rooms and stay silent instead. ` +
+        `Empty output is the only way to stay quiet. Never post a placeholder such as "No response requested.", "No response needed.", "No reply needed.", "No action.", "(no reply)" or "Nothing to add." — those are chatter, not silence, and can make two bots answer each other forever. ` +
         `Do not narrate your reasoning, do not print JSON, do not explain that you are staying silent. Just produce nothing.`);
     // Only company bots: the cloud's jobs routes refuse a personal bot's per_
     // company claim today, so telling a personal bot it can schedule work makes

package/dist/lib/bot/room-policy.d.ts

@@ -44,4 +44,20 @@ export interface ReplyPolicyConfig {
 export declare function textMentionsName(text: string | undefined, name: string | undefined): boolean;
 export declare function isDmItem(item: Pick<InboxItem, "channel">): boolean;
 export declare function resolveReplyTarget(item: InboxItem, config: ReplyPolicyConfig): ReplyTarget | null;
+/** A UID minted for an agent/bot identity (`agt_…`) rather than a person (`usr_…`). */
+export declare function isAgentSender(uid: string | undefined): boolean;
+/**
+ * Stay-quiet phrases a model emits when it has nothing to add. On an
+ * UNMENTIONED room turn a reply that is ONLY one of these is treated as silent
+ * (empty), so the bot does not post meta chatter and cannot loop with another
+ * bot answering "No response requested." to every message. DMs and @mentions
+ * are unaffected — there the phrase is posted as written.
+ */
+export declare const META_NON_REPLY_PHRASES: readonly ["No response requested.", "No response needed.", "No reply needed.", "No action.", "(no reply)", "Nothing to add."];
+/**
+ * True when `reply` (as a whole) is only a stay-quiet phrase: case-insensitive,
+ * trimmed, trailing punctuation ignored. Never a substring match — a real
+ * answer that merely contains such a phrase is not silenced.
+ */
+export declare function isMetaNonReply(reply: string | undefined): boolean;
 //# sourceMappingURL=room-policy.d.ts.map

package/dist/lib/bot/room-policy.js

@@ -55,4 +55,37 @@ export function resolveReplyTarget(item, config) {
         mentioned,
     };
 }
+/** A UID minted for an agent/bot identity (`agt_…`) rather than a person (`usr_…`). */
+export function isAgentSender(uid) {
+    return typeof uid === "string" && uid.startsWith("agt_");
+}
+/**
+ * Stay-quiet phrases a model emits when it has nothing to add. On an
+ * UNMENTIONED room turn a reply that is ONLY one of these is treated as silent
+ * (empty), so the bot does not post meta chatter and cannot loop with another
+ * bot answering "No response requested." to every message. DMs and @mentions
+ * are unaffected — there the phrase is posted as written.
+ */
+export const META_NON_REPLY_PHRASES = [
+    "No response requested.",
+    "No response needed.",
+    "No reply needed.",
+    "No action.",
+    "(no reply)",
+    "Nothing to add.",
+];
+const META_NON_REPLY_NORMALIZED = new Set(META_NON_REPLY_PHRASES.map((p) => p.toLowerCase().replace(/[.!?)\s]+$/, "").trim()));
+/**
+ * True when `reply` (as a whole) is only a stay-quiet phrase: case-insensitive,
+ * trimmed, trailing punctuation ignored. Never a substring match — a real
+ * answer that merely contains such a phrase is not silenced.
+ */
+export function isMetaNonReply(reply) {
+    if (typeof reply !== "string")
+        return false;
+    const normalized = reply.trim().toLowerCase().replace(/[.!?)\s]+$/, "").trim();
+    if (!normalized)
+        return false;
+    return META_NON_REPLY_NORMALIZED.has(normalized);
+}
 //# sourceMappingURL=room-policy.js.map

package/dist/lib/bot/run.js

@@ -66,7 +66,7 @@ import { runRuntimeTurn, RuntimeError } from "./runtime/index.js";
 import { botAttachmentsDir, dmSessionScope } from "./paths.js";
 import { attachmentTurnBlock, downloadTurnAttachments } from "./attachments.js";
 import { inboxEntryAttachments } from "../agent-kit/inbox-state.js";
-import { isDmItem, resolveReplyTarget } from "./room-policy.js";
+import { isAgentSender, isDmItem, isMetaNonReply, resolveReplyTarget } from "./room-policy.js";
 import { buildJobTurnPrompt, isCatchUpRun, isJobItem, jobReportHeader, jobRunOutput, machineTimeZone, planJobRuns, stripJobHeader, SUPERSEDED_DISPOSITION } from "./job-run.js";
 import { clearPendingJobCompletion, isCompletionDue, isCompletionExpired, isCompletionForOtherAgent, readPendingJobCompletions, recordPendingJobCompletion } from "./job-completions.js";
 import { isRuntimeSignInFailure, SIGN_IN_RETRY_MS, signInNeededText } from "./runtime-sign-in.js";
@@ -686,11 +686,16 @@ export async function runBot(deps) {
                 ...(args.readDirs?.length ? { readDirs: args.readDirs } : {}),
             });
             running = false;
-            const sentinelOrEmpty = containsNoReplySentinel(turn.text) || !turn.text.trim();
+            // Control tokens were already stripped from turn.text in runRuntimeTurn, so
+            // a `<|eos|>`-only reply arrives here as empty. On an unmentioned room turn
+            // a stay-quiet phrase ("No response requested." etc.) is also silence — the
+            // meta chatter that let two bots loop on 2026-09-25.
+            const stayQuiet = silenceable && isMetaNonReply(turn.text);
+            const sentinelOrEmpty = containsNoReplySentinel(turn.text) || !turn.text.trim() || stayQuiet;
             // Unmentioned room turn: a no_reply sentinel (bare, fenced, or with
-            // preamble) or an empty/whitespace reply means stay quiet. Abandon the
-            // poster (it posts nothing) and return a silent outcome; the caller acks
-            // without posting anything.
+            // preamble), an empty/whitespace reply, or a stay-quiet phrase means stay
+            // quiet. Abandon the poster (it posts nothing) and return a silent outcome;
+            // the caller acks without posting anything.
             if (silenceable && sentinelOrEmpty) {
                 await poster.abandon();
                 return { outcome: { ok: true, reply: "", silent: true }, poster };
@@ -1247,6 +1252,15 @@ export async function runBot(deps) {
             return;
         }
         const target = resolveReplyTarget(item, config);
+        // A bot/agent sender that did not @mention this bot must never start a model
+        // turn: two bots each answering the other's plain room posts loop forever
+        // (observed 2026-09-25). An explicit @mention still gets answered below.
+        if (target && target.kind === "room" && !target.mentioned && isAgentSender(item.fromPersonUid)) {
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            log("info", `ignored inbox item ${id} (room ${target.channelId}, unmentioned message from bot ${item.fromPersonUid ?? "unknown"}; not starting a turn)`);
+            return;
+        }
         if (!target) {
             // A job item the bot cannot run. When it names a job, the cloud is still
             // holding that job's in-progress slot: acking alone would jam every later

package/dist/lib/bot/runtime/index.js

@@ -8,6 +8,7 @@ import { GrokAcpClient } from "./grok-acp.js";
 import { createClaudeRuntime } from "./claude.js";
 import { createCodexRuntime } from "./codex.js";
 import { createGrokRuntime, grokRetryArgsAfterInvalidOutputFormat, probeGrokOutputFormat } from "./grok.js";
+import { stripControlTokens } from "./sanitize.js";
 import { parseJsonLine, RuntimeError, turnTimeoutMs, stderrExcerpt, } from "./types.js";
 export * from "./types.js";
 export { createClaudeRuntime, claudePermissionMode } from "./claude.js";
@@ -406,7 +407,11 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
         throw new RuntimeError(`${runtime.binary} exited with ${result.code ?? `signal ${result.signal}`}${reason ? `: ${reason.slice(0, 200)}` : ""}`, reason ? reason.slice(0, 400) : fallback, result.code);
     }
     const parsed = runtime.parseOutput(result.stdout, { outputFile, outputFileText });
+    // Strip any leaked model control token (`<|eos|>` etc.) from the final reply
+    // before it is posted; a reply that was only such tokens becomes empty and the
+    // caller applies its normal empty-reply handling.
+    const text = stripControlTokens(parsed.text);
     // A resumed session keeps its id even when the CLI omits it from the envelope.
-    return { text: parsed.text, sessionId: parsed.sessionId ?? input.sessionId };
+    return { text, sessionId: parsed.sessionId ?? input.sessionId };
 }
 //# sourceMappingURL=index.js.map

package/dist/lib/bot/runtime/messages-stream.js

@@ -22,6 +22,7 @@
  * fixtures in runtime/fixtures/. Claude sends one content block per assistant
  * event; older Grok sends a whole message (thinking + text + tool_use) per event.
  */
+import { stripControlTokens } from "./sanitize.js";
 import { parseJsonLine, RuntimeError } from "./types.js";
 /** Progress events in one stream line: top-level assistant text and tool starts only. */
 export function messagesStreamEvents(line) {
@@ -44,8 +45,12 @@ export function messagesStreamEvents(line) {
         if (!block || typeof block !== "object")
             continue;
         const b = block;
-        if (b.type === "text" && typeof b.text === "string" && b.text.trim())
-            out.push({ kind: "message", text: b.text.trim() });
+        if (b.type === "text" && typeof b.text === "string") {
+            // Strip leaked control tokens from in-between progress posts too.
+            const clean = stripControlTokens(b.text).trim();
+            if (clean)
+                out.push({ kind: "message", text: clean });
+        }
         else if (b.type === "tool_use" && typeof b.name === "string")
             out.push({ kind: "tool", name: b.name });
     }

package/dist/lib/bot/runtime/sanitize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Model control-token stripping for bot replies.
+ *
+ * A model can leak a raw control token as visible text — grok posted a bare
+ * `<|eos|>` as a room reply on 2026-09-25. These tokens are never meant for a
+ * person, so they are removed from both the in-between progress messages and
+ * the final reply before anything is posted.
+ *
+ * The generic `<|...|>` form covers any single control token in that shape
+ * (`<|eos|>`, `<|endoftext|>`, `<|im_end|>`, `<|eot_id|>`, and any other).
+ * Whitespace-only reply after stripping is empty, and callers apply the same
+ * empty-reply handling they already have (silent on an unmentioned room turn).
+ */
+/** Remove every `<|...|>` control token from `text`, leaving the rest intact. */
+export declare function stripControlTokens(text: string): string;
+/** True when `text` is nothing but control tokens and whitespace. */
+export declare function isOnlyControlTokens(text: string): boolean;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/lib/bot/runtime/sanitize.js

@@ -0,0 +1,28 @@
+/**
+ * Model control-token stripping for bot replies.
+ *
+ * A model can leak a raw control token as visible text — grok posted a bare
+ * `<|eos|>` as a room reply on 2026-09-25. These tokens are never meant for a
+ * person, so they are removed from both the in-between progress messages and
+ * the final reply before anything is posted.
+ *
+ * The generic `<|...|>` form covers any single control token in that shape
+ * (`<|eos|>`, `<|endoftext|>`, `<|im_end|>`, `<|eot_id|>`, and any other).
+ * Whitespace-only reply after stripping is empty, and callers apply the same
+ * empty-reply handling they already have (silent on an unmentioned room turn).
+ */
+/** Any single control token of the form `<|...|>` (no nested `<|`/`|>`). */
+const CONTROL_TOKEN_RE = /<\|(?:(?!<\||\|>).)*\|>/g;
+/** Remove every `<|...|>` control token from `text`, leaving the rest intact. */
+export function stripControlTokens(text) {
+    if (!text)
+        return text;
+    return text.replace(CONTROL_TOKEN_RE, "");
+}
+/** True when `text` is nothing but control tokens and whitespace. */
+export function isOnlyControlTokens(text) {
+    if (!text.trim())
+        return false;
+    return stripControlTokens(text).trim() === "";
+}
+//# sourceMappingURL=sanitize.js.map

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