@indigoai-us/hq-cli 5.108.20 → 5.108.21

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [5.108.21] — 2026-09-07
+
+### Fixed
+
+- A large `hq files cat`/`hq files get`/`hq files browse`/`hq files search`
+  download no longer dies part-way through with an unexplained crash (Sentry
+  HQ-CLI-5 — 7596554539). Every company-mode vault read goes through a presigned
+  GET, and the CLI handed the caller the download's response body *before anyone
+  started reading it*. Node's bundled `undici` builds that body stream with a
+  zero high-water mark, so the first chunk pauses its HTTP parser until a
+  consumer pulls — and the download loop ran a synchronous `mkdirSync` before it
+  began pulling. When S3 closed the connection inside that gap, undici's
+  socket-end handler tripped an internal `assert(!this.paused)` and threw an
+  `AssertionError` from a background tick that no `try/catch` around the download
+  could see, so `@sentry/node` filed it as a fatal and the process exited
+  mid-download. The presigned GET is now drained into memory before its body is
+  handed on whenever the response declares a length at or below 32 MiB (which
+  covers every object the CLI reads today), removing the paused-parser window
+  entirely; larger or unmeasured responses keep streaming, and the destination
+  directory is now created *before* the download is issued so no synchronous
+  filesystem call sits inside the read window on that path either. The observable
+  output of every `hq files` subcommand is unchanged.
+
 ## [5.108.20] — 2026-09-07
 
 ### Fixed

package/dist/commands/files-browse.d.ts

@@ -403,6 +403,28 @@ export interface RunGetResult {
  * HQ root itself, which is too broad to do implicitly.
  */
 export declare function runGet(input: RunGetInput): Promise<RunGetResult>;
+/**
+ * Upper bound (bytes) on a presigned download we drain into memory before
+ * handing the caller a Body (HQ-CLI-5).
+ *
+ * fetch()'s response body is an undici ReadableStream with a zero high-water
+ * mark: the first chunk drives desiredSize to 0 and undici PAUSES its llhttp
+ * parser until a consumer pulls. `getObject` used to hand that still-paused
+ * stream straight to the orchestrators, which each run a synchronous fs call
+ * before they start pulling. If S3 sends its connection FIN inside that gap,
+ * undici's socket-end handler trips `assert(!this.paused)` in Parser.finish and
+ * throws an AssertionError from a process tick — outside any try/catch — that
+ * @sentry/node files as an uncaught fatal and that kills the CLI mid-download.
+ *
+ * Draining the body up front removes the pause entirely (the same
+ * buffer-then-rewrap posture peekPlanLimitStatus uses in vault-api.ts). We cap
+ * it so a very large object still streams and never buffers into a small agent
+ * box's memory; a response above the ceiling (or with no declared length) keeps
+ * the streaming path, whose residual window is narrowed by the mkdirSync hoist
+ * in runGet/runCat. 32 MiB comfortably covers every object hq-cli reads today
+ * (vault JSON + images) while staying well under a 4 GB host's headroom.
+ */
+export declare const PRESIGN_BUFFER_MAX_BYTES: number;
 /**
  * Build a COMPANY-mode browse client backed by the list + presign API. The
  * access token + companyUid are captured here; the orchestrator just calls

package/dist/commands/files-browse.js

@@ -318,6 +318,15 @@ export async function runCat(input) {
         // COMPANY mode (HQ-59): GetObject → presign GET. No STS vend, no direct S3.
         s3 = requireCompanyClient(input.companyClient)({ companyUid: entity.uid });
     }
+    // HQ-CLI-5: when writing to --out, create the parent directory BEFORE issuing
+    // the presigned GET, so no synchronous filesystem call sits between receiving
+    // the body and the nextTick resume that starts pulling it — that gap is what
+    // left undici's HTTP parser paused into the socket FIN. The guard above
+    // already validated absOut is outside the protected companies/ tree, so its
+    // parent is outside too.
+    if (absOut !== undefined) {
+        fs.mkdirSync(path.dirname(absOut), { recursive: true });
+    }
     const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: s3Key })));
     if (!resp.Body) {
         throw new Error(`GetObject for '${key}' returned no body.`);
@@ -331,10 +340,6 @@ export async function runCat(input) {
         bytesWritten += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
     });
     if (absOut !== undefined) {
-        // Ensure the parent directory exists — but ONLY if it's also outside
-        // the protected tree (the guard already validated absOut itself; the
-        // parent of an outside-tree path is by definition outside too).
-        fs.mkdirSync(path.dirname(absOut), { recursive: true });
         await pipeline(body, fs.createWriteStream(absOut));
         return {
             bytesWritten,
@@ -536,12 +541,17 @@ export async function runGet(input) {
         else {
             destAbs = path.join(hqRoot, "companies", slug, key);
         }
+        // HQ-CLI-5: create the destination directory BEFORE issuing the presigned
+        // GET, so no synchronous filesystem call sits between receiving the body
+        // and starting to pull it — that gap is what left undici's HTTP parser
+        // paused into the socket FIN. Buffered downloads no longer keep a live
+        // socket at all; this also closes the window on the streaming branch.
+        fs.mkdirSync(path.dirname(destAbs), { recursive: true });
         const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })));
         if (!resp.Body) {
             throw new Error(`GetObject for '${key}' returned no body.`);
         }
         const body = resp.Body;
-        fs.mkdirSync(path.dirname(destAbs), { recursive: true });
         await pipeline(body, fs.createWriteStream(destAbs));
         bytesWritten += fs.statSync(destAbs).size;
         destinations.push(destAbs);
@@ -557,6 +567,28 @@ export async function runGet(input) {
 }
 // ── CLI registration ────────────────────────────────────────────────────────
 const defaultS3Factory = ({ region, credentials }) => new S3Client({ region, credentials });
+/**
+ * Upper bound (bytes) on a presigned download we drain into memory before
+ * handing the caller a Body (HQ-CLI-5).
+ *
+ * fetch()'s response body is an undici ReadableStream with a zero high-water
+ * mark: the first chunk drives desiredSize to 0 and undici PAUSES its llhttp
+ * parser until a consumer pulls. `getObject` used to hand that still-paused
+ * stream straight to the orchestrators, which each run a synchronous fs call
+ * before they start pulling. If S3 sends its connection FIN inside that gap,
+ * undici's socket-end handler trips `assert(!this.paused)` in Parser.finish and
+ * throws an AssertionError from a process tick — outside any try/catch — that
+ * @sentry/node files as an uncaught fatal and that kills the CLI mid-download.
+ *
+ * Draining the body up front removes the pause entirely (the same
+ * buffer-then-rewrap posture peekPlanLimitStatus uses in vault-api.ts). We cap
+ * it so a very large object still streams and never buffers into a small agent
+ * box's memory; a response above the ceiling (or with no declared length) keeps
+ * the streaming path, whose residual window is narrowed by the mkdirSync hoist
+ * in runGet/runCat. 32 MiB comfortably covers every object hq-cli reads today
+ * (vault JSON + images) while staying well under a 4 GB host's headroom.
+ */
+export const PRESIGN_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
 /**
  * Build a COMPANY-mode browse client backed by the list + presign API. The
  * access token + companyUid are captured here; the orchestrator just calls
@@ -616,9 +648,31 @@ export function createCompanyPresignClient(input) {
         if (!dl.ok) {
             throw new Error(`Failed to download '${key}' (HTTP ${dl.status})`);
         }
-        // fetch() yields a web ReadableStream; the orchestrators consume Body as a
-        // Node Readable (body.on('data') + stream pipeline), so adapt it. An empty
-        // body (no stream) becomes an empty Readable.
+        // HQ-CLI-5: when the response declares a length at or below the ceiling,
+        // DRAIN it here — read the whole body before send() resolves and replay it
+        // from memory. That removes undici's paused-parser window entirely: by the
+        // time the orchestrators pull, there is no live socket left to hit
+        // `assert(!this.paused)` on its FIN. `Number(null)` is 0, so guard the
+        // absent header explicitly (NaN) — an unmeasured body must keep streaming,
+        // never look like a zero-length buffer.
+        const declaredLengthHeader = dl.headers.get("content-length");
+        const declaredLength = declaredLengthHeader === null ? NaN : Number(declaredLengthHeader);
+        const canBuffer = Number.isFinite(declaredLength) &&
+            declaredLength >= 0 &&
+            declaredLength <= PRESIGN_BUFFER_MAX_BYTES;
+        if (canBuffer) {
+            const buf = Buffer.from(await dl.arrayBuffer());
+            return {
+                Body: Readable.from(buf),
+                $metadata: {},
+            };
+        }
+        // Above the ceiling, or no declared length: keep streaming so a very large
+        // object is never buffered whole. fetch() yields a web ReadableStream; the
+        // orchestrators consume Body as a Node Readable (body.on('data') + stream
+        // pipeline), so adapt it. An empty body (no stream) becomes an empty
+        // Readable. The mkdirSync hoist in runGet/runCat narrows the residual
+        // paused-parser window on this branch.
         const nodeBody = dl.body
             ? Readable.fromWeb(dl.body)
             : Readable.from([]);

package/package.json

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