@indigoai-us/hq-cli 5.109.3 → 5.109.5

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.109.5] — 2026-09-10
+
+## [5.109.4] — 2026-09-09
+
+### Fixed
+
+- A sign-in that never comes back no longer dead-ends. `hq integrations connect`
+  used to say "Timed out waiting for the browser sign-in. Run the connect
+  command again." — right for one of the three things that cause it and useless
+  for the other two. An app that will not accept HQ's temporary local return
+  address does not redirect back at all, so its refusal reaches HQ as silence;
+  retrying from the terminal fails identically every time. So does an app that
+  needs your workspace or instance address before its sign-in page will load.
+  HQ cannot tell these apart, so it now names all three and gives the recovery
+  for each: run it again, finish in the console (which uses a fixed address the
+  app accepts), or re-run with `--mcp-url` pointed at your own instance.
+
 ## [5.109.3] — 2026-09-09
 
 ### Fixed

package/dist/commands/integrations-connect.js

@@ -22,7 +22,7 @@ import { DEFAULT_VAULT_API_URL, ensureCognitoIdToken, } from "../utils/cognito-s
 import { getCompanyUid } from "../utils/vault-api.js";
 import { IntegrationsCliError, bareProvider, connectionDomain, fetchAdminSurface, printJson, revokedConnectionDetails, resolveConnection, } from "./integrations-core.js";
 import { completeOAuth, discoverDocs, installIntegration, listCatalog, pullBlueprint, startOAuth, } from "./integrations-api.js";
-import { startLoopbackListener } from "./integrations-oauth.js";
+import { OAUTH_LOOPBACK_TIMEOUT_CODE, startLoopbackListener, } from "./integrations-oauth.js";
 /** hq-pro's machine code for "this endpoint needs a browser sign-in". */
 const OAUTH_REQUIRED_CODE = "INTEGRATION_FACTORY_OAUTH_REQUIRED";
 /**
@@ -518,7 +518,17 @@ async function connectViaOAuth(token, companyUid, target, opts) {
                 console.error(`Open this URL to sign in:\n  ${started.authorizationUrl}`);
             });
         }
-        const code = await pendingCode;
+        let code;
+        try {
+            code = await pendingCode;
+        }
+        catch (err) {
+            if (err instanceof IntegrationsCliError &&
+                err.code === OAUTH_LOOPBACK_TIMEOUT_CODE) {
+                return loopbackTimeoutHandoff(target, opts);
+            }
+            throw err;
+        }
         return await completeOAuth(token, companyUid, { state: started.state, code });
     }
     finally {
@@ -594,6 +604,56 @@ function targetSelectionHint(opts) {
     return undefined;
 }
 /** Shared tail of every console handoff: the page, then what to connect there. */
+/**
+ * The loopback callback never arrived. Offer every recovery, claim no cause.
+ *
+ * This used to say "Timed out waiting for the browser sign-in. Run the connect
+ * command again." — advice that is right for one of the three things that
+ * produce this timeout and useless for the other two, with nothing to tell the
+ * user which they hit:
+ *
+ *   1. They did not finish in time. Retrying works.
+ *   2. The provider rejected HQ's `127.0.0.1:<port>` redirect_uri. RFC 8252
+ *      allows the variable port; plenty of providers demand an exactly
+ *      registered URI anyway and show their own error page. Because the URI is
+ *      unregistered they will not redirect to it, so their refusal reaches HQ
+ *      as silence. Retrying from the terminal fails identically forever; the
+ *      console's pinned callback IS registered, so finishing there works.
+ *   3. The app needs a workspace/instance address before its sign-in page will
+ *      load at all. Its generic authorize URL cannot complete for anyone.
+ *      `--mcp-url` already takes an instance-specific endpoint — the capability
+ *      exists, it was just never mentioned at the moment it is needed.
+ *
+ * HQ genuinely cannot tell these apart from here, so it names all three rather
+ * than picking one and sounding certain.
+ */
+function loopbackTimeoutHandoff(target, opts) {
+    console.error(chalk.yellow(`The sign-in for ${target.label} never came back, so nothing was connected.`));
+    console.error("Three things cause this, and HQ cannot tell which from here:");
+    console.error("  1. The sign-in was not finished in time — run the same command again.");
+    console.error(`  2. ${target.label} will not accept HQ's temporary local address as a ` +
+        "return URL. Retrying here always fails; finish it in the console " +
+        "instead, which uses a fixed address the app accepts.");
+    console.error(`  3. ${target.label} needs your workspace or instance address before its ` +
+        "sign-in page works at all. Re-run with that server's own endpoint:\n" +
+        "     hq integrations connect --mcp-url https://<your-workspace>.example.com/mcp");
+    const url = consoleIntegrationsUrl(opts.company, consoleOrigin());
+    printConsoleDestination(target, opts, url);
+    // Nothing was connected, so the command must not exit 0. Returning null the
+    // way consoleHandoff does would let `connectApp` complete normally and hand a
+    // script a success it did not get — the same unbacked claim this whole change
+    // is about, made in the exit status instead of in prose.
+    //
+    // A handoff and a timeout are different outcomes and deserve different exit
+    // codes: consoleHandoff means HQ knows what happens next and has routed you
+    // there, while this means the sign-in failed and HQ cannot say why. Set the
+    // status directly rather than throwing, so the three routes above stay the
+    // whole message instead of being followed by a duplicate headline — the same
+    // print-then-mark-failed shape integrations.ts already uses for a tool call
+    // that ran and failed.
+    process.exitCode = 1;
+    return null;
+}
 function printConsoleDestination(target, opts, url) {
     if (url) {
         console.error(`Open this page and connect ${target.label} from it:\n  ${url}`);

package/dist/commands/integrations-oauth.d.ts

@@ -19,6 +19,17 @@
  * as `OAUTH_REDIRECT_URI_NOT_ALLOWED` at connect time.
  */
 export declare const LOOPBACK_CALLBACK_PATH = "/hq/integrations/oauth/callback";
+/**
+ * The loopback callback never arrived before the bound.
+ *
+ * Deliberately a code and not a message match: this is the ONLY signal HQ gets
+ * for a provider that rejects the ephemeral `127.0.0.1:<port>` redirect_uri,
+ * because such a provider refuses to redirect to an unregistered address and
+ * so sends nothing back at all. It is also what a person who simply did not
+ * finish in time produces. The two are indistinguishable from here, which is
+ * exactly why the caller must offer both recoveries rather than assert one.
+ */
+export declare const OAUTH_LOOPBACK_TIMEOUT_CODE = "OAUTH_LOOPBACK_TIMEOUT";
 /**
  * Turn an `?error=` redirect into what to tell the user, and whether it is
  * their doing.

package/dist/commands/integrations-oauth.js

@@ -23,6 +23,17 @@ import { IntegrationsCliError } from "./integrations-core.js";
 export const LOOPBACK_CALLBACK_PATH = "/hq/integrations/oauth/callback";
 /** How long to wait for the browser round trip before giving the port back. */
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * The loopback callback never arrived before the bound.
+ *
+ * Deliberately a code and not a message match: this is the ONLY signal HQ gets
+ * for a provider that rejects the ephemeral `127.0.0.1:<port>` redirect_uri,
+ * because such a provider refuses to redirect to an unregistered address and
+ * so sends nothing back at all. It is also what a person who simply did not
+ * finish in time produces. The two are indistinguishable from here, which is
+ * exactly why the caller must offer both recoveries rather than assert one.
+ */
+export const OAUTH_LOOPBACK_TIMEOUT_CODE = "OAUTH_LOOPBACK_TIMEOUT";
 /**
  * The authorization-endpoint error codes RFC 6749 §4.1.2.1 defines. Anything
  * outside this set is reported as `other`: the value arrives in a redirect
@@ -250,7 +261,13 @@ export async function startLoopbackListener(opts = {}) {
                 }
                 timer = setTimeout(() => {
                     close();
-                    reject(new IntegrationsCliError("Timed out waiting for the browser sign-in. Run the connect command again.", { expected: true }));
+                    reject(new IntegrationsCliError("The sign-in never came back.", 
+                    // Typed, so the caller can offer the recovery routes without
+                    // matching on this sentence. A timeout is NOT self-evidently
+                    // "you were too slow": a provider that refuses HQ's ephemeral
+                    // loopback redirect_uri generally will not redirect back to it
+                    // at all, so its refusal reaches this branch as silence.
+                    { expected: true, code: OAUTH_LOOPBACK_TIMEOUT_CODE }));
                 }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
                 // Don't let a pending sign-in wait keep an otherwise-finished process
                 // alive: the explicit timeout above is the bound, not the event loop.

package/dist/utils/network-transport-error.js

@@ -53,11 +53,21 @@ const TRANSPORT_CODE_REASONS = {
  * Recognized undici error names, for builds where the `code` property is
  * absent but the typed error still identifies itself (the shape Sentry
  * recorded for HQ-CLI-G was `ConnectTimeoutError`).
+ *
+ * `TimeoutError` is the DOMException `AbortSignal.timeout(...)` rejects a
+ * bounded `fetch()` with when the peer accepts the connection but never answers
+ * — Sentry HQ-CLI-1P (issue 7716090679). It is the one transport failure here
+ * that identifies itself ONLY by name: its legacy DOMException `code` is the
+ * NUMBER 23, so the string-typed `readStringProperty(node, "code")` above skips
+ * it, and it carries no `cause` to walk, leaving just the name. `AbortError` is
+ * deliberately NOT listed — a caller-initiated abort is not a transport fault
+ * and must stay reportable.
  */
 const TRANSPORT_NAME_REASONS = {
     ConnectTimeoutError: "the connection timed out",
     HeadersTimeoutError: "the server did not respond in time",
     SocketError: "the connection closed unexpectedly",
+    TimeoutError: "the server did not respond in time",
 };
 /**
  * Depth cap for `cause` traversal. A self-referential or mutually-referential

package/dist/utils/vault-api.js

@@ -19,6 +19,24 @@ import { planGateErrorFromResponse } from './plan-gate-error.js';
  * whole-process watchdog.
  */
 const IDENTITY_LOOKUP_TIMEOUT_MS = 15_000;
+/**
+ * The identity-lookup abort bound, in milliseconds. Defaults to the shipped
+ * IDENTITY_LOOKUP_TIMEOUT_MS (15s). An optional HQ_IDENTITY_LOOKUP_TIMEOUT_MS
+ * override (clamped to a sane 100..120_000 ms window; absent or non-numeric
+ * input keeps the 15s default) exists purely so the artifact E2E can force the
+ * abort in well under a second instead of stalling a spawned CLI for the full
+ * 15s per case. It does NOT change shipped behaviour: with the var unset every
+ * call uses 15s exactly as before.
+ */
+function identityLookupTimeoutMs() {
+    const raw = process.env.HQ_IDENTITY_LOOKUP_TIMEOUT_MS?.trim();
+    if (!raw)
+        return IDENTITY_LOOKUP_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return IDENTITY_LOOKUP_TIMEOUT_MS;
+    return Math.min(120_000, Math.max(100, Math.trunc(parsed)));
+}
 /**
  * Best-effort peek of a 2xx JSON body for plan-limit status (US-016).
  *
@@ -279,7 +297,7 @@ async function resolveCompanyByUid(token, uid) {
     const res = await vaultApiFetch({
         token,
         path: `/entity/${encodeURIComponent(uid)}`,
-        signal: AbortSignal.timeout(IDENTITY_LOOKUP_TIMEOUT_MS),
+        signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
         raiseIfUnauthorized(res);
@@ -312,7 +330,7 @@ async function resolveSlugInCallerNamespace(token, slug) {
         token,
         path: '/entity/check-slug/me',
         query: { type: 'company', slug },
-        signal: AbortSignal.timeout(IDENTITY_LOOKUP_TIMEOUT_MS),
+        signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
         raiseIfUnauthorized(res);
@@ -336,7 +354,28 @@ async function resolveCompanyUid(token, ref) {
     // PRIMARY PATH — caller-scoped slug resolution. Resolves the slug to the
     // caller's OWN company (unique within their namespace by the invariant
     // above), making a stranger's same-slug company invisible.
-    const mine = await resolveSlugInCallerNamespace(token, ref);
+    //
+    // A non-2xx already degrades to the global fallback below (via `return null`).
+    // A TRANSPORT failure must degrade the SAME way, not abort the command:
+    // `resolveSlugInCallerNamespace`'s fetch is bounded by AbortSignal.timeout, so
+    // a vault gateway that accepts the connection but never answers rejects with a
+    // DOMException named `TimeoutError`. Before this catch, that rejection threw
+    // straight out of `resolveCompanyUid`, skipped the global by-slug lookup, and
+    // — being unclassified by main.ts — filed a Sentry crash report instead of an
+    // actionable connectivity message (Sentry HQ-CLI-1P / issue 7716090679).
+    // Degrade ONLY on a recognized transport failure; re-throw everything else
+    // unchanged, so a genuine hq-cli defect stays fatal and the 401 AuthError that
+    // `raiseIfUnauthorized` throws still short-circuits before any fallback.
+    let mine;
+    try {
+        mine = await resolveSlugInCallerNamespace(token, ref);
+    }
+    catch (err) {
+        if (networkTransportErrorCode(err) === null) {
+            throw err;
+        }
+        mine = null;
+    }
     if (mine) {
         return mine;
     }
@@ -347,7 +386,7 @@ async function resolveCompanyUid(token, ref) {
     const res = await vaultApiFetch({
         token,
         path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
-        signal: AbortSignal.timeout(IDENTITY_LOOKUP_TIMEOUT_MS),
+        signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
         raiseIfUnauthorized(res);
@@ -374,7 +413,7 @@ async function resolveCompanyFromMemberships(token) {
     const res = await vaultApiFetch({
         token,
         path: '/membership/me',
-        signal: AbortSignal.timeout(IDENTITY_LOOKUP_TIMEOUT_MS),
+        signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
         throw new Error("Failed to fetch memberships — run `hq login` and try again");
@@ -421,7 +460,7 @@ export async function resolveCallerPersonUid(token, baseUrl) {
         token,
         path: '/entity/by-type/person',
         baseUrl,
-        signal: AbortSignal.timeout(IDENTITY_LOOKUP_TIMEOUT_MS),
+        signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
         throw new Error("Failed to fetch person entity — run `hq login` and try again");

package/package.json

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