@indigoai-us/hq-cli 5.109.3 → 5.109.4

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [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/package.json

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