@indigoai-us/hq-cli 5.98.1 → 5.98.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [5.98.2] — 2026-08-11
+
+### Fixed
+
+- `hq core hq-status-summary` — and through it the `/handoff` status summary —
+  no longer crashes, or files a Sentry report, on a mature HQ root (HQ-CLI-N,
+  Sentry 7664842324). The shared `command()` helper behind the native `hq core`
+  utilities ran `spawnSync` with no `maxBuffer`, so every child inherited Node's
+  1 MiB default. `hq-status-summary` shells out to `git status --porcelain
+  --ignored`, whose output exceeds 1 MiB on any HQ root carrying the usual
+  individually-ignored files alongside tracked content; Node then killed git with
+  SIGTERM, handed back truncated stdout, and surfaced `Error: spawnSync git
+  ENOBUFS`, failing the handoff (observed once, from a single user). The helper
+  now caps captured output at 512 MiB — the same ceiling the repo already uses
+  for git reads — matching the bundled shell oracle, which redirects git straight
+  to a temp file and has no ceiling at all. Spawn errors stay fatal, so a
+  truncated status is never reported as a real summary, and an ENOBUFS above the
+  new ceiling now throws an error naming the command, its args, and the cap
+  instead of the opaque original.
+
 ## [5.98.1] — 2026-08-10
 
 ### Fixed

package/dist/bin/hq-auth-refresh.d.ts

@@ -11,4 +11,5 @@
  * non-interactively.
  */
 import "../node-preflight.js";
+import "../node-network-compat.js";
 //# sourceMappingURL=hq-auth-refresh.d.ts.map

package/dist/bin/hq-auth-refresh.js

@@ -13,6 +13,7 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "../node-preflight.js";
+import "../node-network-compat.js";
 import { initSentry, Sentry } from "../sentry.js";
 import { refreshCachedSession } from "../utils/cognito-session.js";
 initSentry();

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import "./node-preflight.js";
+import "./node-network-compat.js";
 declare function isVersionRequest(argv: readonly string[]): boolean;
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;

package/dist/index.js

@@ -2,6 +2,7 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
+import "./node-network-compat.js";
 import { CLI_VERSION } from "./cli-version.js";
 function isVersionRequest(argv) {
     const args = argv.slice(2);

package/dist/lib/core-utils/common.js

@@ -9,10 +9,34 @@ export function ioFor(io = {}) {
 export function line(write, value) {
     write(`${value}\n`);
 }
+/**
+ * Ceiling for a single child's captured stdout, mirroring the git-read cap the
+ * repo already uses (src/utils/large-file-guard.ts:48). spawnSync defaults
+ * maxBuffer to 1 MiB; once a child's output crosses that, Node kills it with
+ * SIGTERM and hands back TRUNCATED stdout plus an ENOBUFS error. `hq core
+ * hq-status-summary` runs `git status --porcelain --ignored`, whose output
+ * exceeds 1 MiB on any mature HQ root (the individually-ignored files that sit
+ * beside tracked content), so the default turned a routine /handoff status
+ * summary into a crash. The bundled shell oracle this module ports
+ * (assets/scaffold/core/scripts/hq-status-summary.sh:108) redirects git straight
+ * to a temp file and has no ceiling at all; an explicit, generous cap matches it.
+ */
+const MAX_SPAWN_BUFFER = 512 * 1024 * 1024;
 export function command(command, args, cwd) {
-    const result = spawnSync(command, args, { cwd, encoding: "utf8" });
-    if (result.error)
-        throw result.error;
+    const result = spawnSync(command, args, { cwd, encoding: "utf8", maxBuffer: MAX_SPAWN_BUFFER });
+    // Spawn errors stay fatal: a truncated child result must never be reported as
+    // a real one — that would silently under-count a handoff's status instead of
+    // failing loudly. Above the new ceiling ENOBUFS is still theoretically
+    // reachable, so wrap it to name the command, its args and the cap; a future
+    // recurrence then arrives in Sentry self-diagnosed instead of as the opaque
+    // "spawnSync <cmd> ENOBUFS".
+    if (result.error) {
+        const error = result.error;
+        if (error.code === "ENOBUFS") {
+            throw new Error(`spawnSync ${command} ${args.join(" ")} exceeded the ${MAX_SPAWN_BUFFER}-byte output ceiling`, { cause: error });
+        }
+        throw error;
+    }
     return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
 }
 export function exists(pathname) {

package/dist/main.d.ts

@@ -3,6 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 import "./node-preflight.js";
+import "./node-network-compat.js";
 import { Sentry } from "./sentry.js";
 export declare function runCli(): Promise<void>;
 export type TopLevelErrorDependencies = {

package/dist/main.js

@@ -5,6 +5,7 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
+import "./node-network-compat.js";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";

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

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare const HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS = 1000;
+export interface NodeNetworkCompatibilityOptions {
+    nodeOptions?: string;
+    execArgv?: readonly string[];
+    /**
+     * Inject the net timeout setter (tests). Pass `null` to simulate a runtime
+     * that lacks `setDefaultAutoSelectFamilyAttemptTimeout`.
+     */
+    setAttemptTimeout?: ((milliseconds: number) => void) | null;
+}
+export declare function configureNodeNetworkCompatibility(options?: NodeNetworkCompatibilityOptions): boolean;
+//# sourceMappingURL=node-network-compat.d.ts.map

package/dist/node-network-compat.js

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+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|$)`);
+    return (optionPattern.test(nodeOptions) ||
+        execArgv.some((argument) => argument === ATTEMPT_TIMEOUT_OPTION ||
+            argument.startsWith(`${ATTEMPT_TIMEOUT_OPTION}=`)));
+}
+function resolveSetAttemptTimeout(override) {
+    if (override === null)
+        return undefined;
+    if (override)
+        return override;
+    const fn = nodeNet.setDefaultAutoSelectFamilyAttemptTimeout;
+    return typeof fn === "function" ? fn.bind(nodeNet) : undefined;
+}
+export function configureNodeNetworkCompatibility(options = {}) {
+    const nodeOptions = options.nodeOptions ?? process.env.NODE_OPTIONS ?? "";
+    const execArgv = options.execArgv ?? process.execArgv;
+    if (hasExplicitAttemptTimeout(nodeOptions, execArgv)) {
+        return false;
+    }
+    const setAttemptTimeout = resolveSetAttemptTimeout(options.setAttemptTimeout);
+    if (!setAttemptTimeout) {
+        // Runtime lacks the API (pre-Node 18.13 / preflight should already have exited).
+        return false;
+    }
+    setAttemptTimeout(HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS);
+    return true;
+}
+configureNodeNetworkCompatibility();
+//# sourceMappingURL=node-network-compat.js.map

package/package.json

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