@indigoai-us/hq-cli 5.105.1 → 5.106.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [5.106.0] — 2026-09-02
+
+### Fixed
+
+- `hq integrations inspect` now accepts a pasted endpoint URL. Passing
+  `https://mcp.example.com/mcp` used to be treated as free-text search and
+  answered "No integrations.sh results found" for an app listed under exactly
+  that host; it is now looked up by host.
+
+### Changed
+
+- The Connect-an-app catalog now says when a listed app's availability could
+  not be re-confirmed on the last sweep. Such apps are tagged
+  `not recently verified` so a stale entry reads as unconfirmed rather than as
+  freshly checked. The apps are still listed and still connectable.
+
+## [5.105.2] — 2026-09-02
+
+### Fixed
+
+- The bundled cloud sync engine now uses `@indigoai-us/hq-cloud` 6.16.3.
+  Session logs include hidden files, retain capture state on large first runs,
+  continue capturing after one bad file, and are saved only after capture
+  succeeds.
+
 ## [5.105.1] — 2026-08-31
 
 ### Fixed

package/dist/commands/agents.d.ts

@@ -133,7 +133,7 @@ export interface ProvisionAgentInput {
     name: string;
     slug: string;
     codexAuthMode: "subscription" | "apiKey";
-    provider?: "codex" | "grok" | "claude";
+    provider?: "codex" | "grok" | "claude" | "agents-v2";
     codexApiKey?: string;
     idempotencyKey: string;
     title?: string;

package/dist/commands/agents.js

@@ -45,7 +45,7 @@ export const VALID_EFFORTS = new Set([
 /** Service-tier (speed) values hq-pro accepts on `runtime-config`. */
 export const VALID_TIERS = new Set(["default", "priority"]);
 /** Agent runtimes hq-pro accepts on `POST /v1/agents` (`AgentProvider`). */
-export const VALID_PROVIDERS = new Set(["codex", "grok", "claude"]);
+export const VALID_PROVIDERS = new Set(["codex", "grok", "claude", "agents-v2"]);
 /** Auth modes hq-pro accepts on `POST /v1/agents` (`CodexAuthMode`). */
 export const VALID_AUTH_MODES = new Set(["subscription", "apiKey"]);
 /** Customer-facing agent size keys served by hq-pro's authoritative catalog. */
@@ -764,7 +764,7 @@ export function registerAgentsCommand(program) {
         .description("Provision a new cloud agent (company-specific monthly price shown before creation)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--slug <slug>", "Agent slug (defaults to a slug of <name>)")
-        .option("--provider <provider>", "Runtime: codex | grok | claude (default codex). claude is subscription-only")
+        .option("--provider <provider>", "Runtime: codex | grok | claude | agents-v2 (default codex). claude is subscription-only; agents-v2 boots its brain box (codex, or grok via a grok-* model) and receives the v2 runtime post-boot")
         .option("--auth-mode <mode>", "Auth: subscription | apiKey (default subscription)", "subscription")
         .option("--api-key-env <VAR>", "Env var holding the API key for --auth-mode apiKey (never pass the key as a flag)")
         .option("--title <title>", "Org-chart job title")

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

@@ -22,6 +22,17 @@ export interface CatalogEntry {
      */
     source?: "hq-discovered" | "integrations.sh" | "hq-recommended";
     authClass?: "none" | "key" | "oauth";
+    /**
+     * Present when the app is listed on a CARRIED-FORWARD verdict: the latest
+     * catalog generation's probe answered HTTP 403, which establishes nothing,
+     * so the previous run's classification was kept rather than dropping the app
+     * on ambiguous evidence.
+     *
+     * The app is still offered — this qualifies the listing, it does not retract
+     * it. Absent (never `false`) on a freshly verified entry, so "no claim" and
+     * "claim is false" stay distinguishable.
+     */
+    verificationCarriedForward?: true;
     /** Opaque server-owned id; prefer it over echoing connection details back. */
     entryId?: string;
 }
@@ -186,6 +197,21 @@ export interface OAuthStartInput {
      * omitting it pins the console callback instead.
      */
     redirectUri?: string;
+    /**
+     * An OAuth app the admin registered with the provider themselves, for the
+     * providers that refuse to register HQ dynamically (they only issue
+     * confidential clients). hq-pro reads these ONLY on the direct `mcpUrl`
+     * path — a catalog, domain, or discovery-receipt connect keeps server-owned
+     * client resolution and drops them silently — so callers must pin an
+     * `mcpUrl` alongside them rather than hoping they were honoured.
+     */
+    clientId?: string;
+    /**
+     * The registered app's secret, for a confidential client. Optional: a public
+     * client is a `clientId` on its own. hq-pro keeps it on the server-side
+     * state row and attaches it at code exchange; it is never logged.
+     */
+    clientSecret?: string;
 }
 export declare function startOAuth(token: string, companyUid: string, input: OAuthStartInput): Promise<OAuthStartResult>;
 export declare function completeOAuth(token: string, companyUid: string, input: {

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

@@ -26,5 +26,25 @@ import { Command } from "commander";
 export declare function assertAuthMode(value: string | undefined): void;
 /** Single-quote a value for a copy-pasteable shell command. */
 export declare function shellQuote(value: string): string;
+/**
+ * The console that fronts the control plane this CLI is pointed at.
+ *
+ * A handoff must land on the console for the SAME backend, because that
+ * console starts its own OAuth flow against its own backend. Sending a staging
+ * session to the production console would connect the app in the wrong place —
+ * so when the control plane is overridden and its console cannot be derived,
+ * return undefined and say so rather than guess a host.
+ *
+ * `HQ_CONSOLE_URL` is the explicit override; otherwise the console is the
+ * control-plane host with its `hqapi.` prefix removed.
+ */
+export declare function consoleOrigin(vaultApiUrl?: string): string | undefined;
+/**
+ * The console's Integrations page for a company, the console root when the
+ * caller never named one (a single-membership session resolves the company
+ * server-side, so hq-cli holds a uid here, not a slug — and the console routes
+ * by slug), or undefined when the console for this control plane is unknown.
+ */
+export declare function consoleIntegrationsUrl(companySlug: string | undefined, origin: string | undefined): string | undefined;
 export declare function registerConnectCommands(integrations: Command): void;
 //# sourceMappingURL=integrations-connect.d.ts.map

package/dist/commands/integrations-connect.js

@@ -18,7 +18,7 @@
  */
 import chalk from "chalk";
 import open from "open";
-import { ensureCognitoIdToken } from "../utils/cognito-session.js";
+import { DEFAULT_VAULT_API_URL, ensureCognitoIdToken, } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
 import { IntegrationsCliError, bareProvider, connectionDomain, printJson, revokedConnectionDetails, resolveConnection, } from "./integrations-core.js";
 import { completeOAuth, discoverDocs, installIntegration, listCatalog, pullBlueprint, startOAuth, } from "./integrations-api.js";
@@ -61,6 +61,21 @@ const CONSOLE_HANDOFF_CODES = new Set([
     "OAUTH_REDIRECT_URI_NOT_ALLOWED",
     "OAUTH_LOOPBACK_NOT_SUPPORTED",
 ]);
+/**
+ * Codes meaning "this provider will not register HQ automatically; an admin
+ * must supply their own OAuth app's credentials".
+ *
+ * hq-pro attaches `redirectUri` + `advancedClientSupported` to exactly these
+ * (`withAdvancedClientHint`), and the console turns that into its
+ * bring-your-own-credentials form. hq-cli has no flag for a client id or
+ * secret, so on its own it can only restate the refusal — which reads as a
+ * dead end even though the recovery exists one surface over. Route to the
+ * console instead.
+ */
+const BRING_YOUR_OWN_CLIENT_CODES = new Set([
+    "OAUTH_REGISTRATION_UNSUPPORTED",
+    "CLIENT_REGISTRATION_REFUSED",
+]);
 /**
  * Looks-like-a-domain test for the positional `<app>` argument. Deliberately
  * loose — hq-pro does the real resolution — but tight enough that `linear.app`
@@ -69,6 +84,27 @@ const CONSOLE_HANDOFF_CODES = new Set([
 function looksLikeDomain(value) {
     return /^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}$/i.test(value) && !value.includes(" ");
 }
+/**
+ * The host inside an endpoint URL, or the value unchanged when it is not one.
+ *
+ * `hq integrations inspect` is the "what does this expose before I connect it"
+ * command, so the natural thing to paste is the endpoint URL itself. Without
+ * this, `https://vyg.app/mcp` failed `looksLikeDomain` and went out as a free
+ * text SEARCH, which answered "No integrations.sh results found" for an app
+ * that is in the catalog under exactly that host. hq-pro accepts a URL-shaped
+ * domain, so the only thing missing was sending it as one.
+ */
+function hostFromEndpointUrl(value) {
+    const trimmed = value.trim();
+    if (!/^https?:\/\//i.test(trimmed))
+        return trimmed;
+    try {
+        return new URL(trimmed).hostname;
+    }
+    catch {
+        return trimmed;
+    }
+}
 /**
  * True when this shell is almost certainly on a different machine from the
  * person's browser. Not a security boundary — just the signal that a loopback
@@ -325,6 +361,26 @@ async function findCatalogEntryByName(token, companyUid, name) {
         return null;
     }
 }
+/**
+ * Confirm the backend recognises this target, without connecting anything.
+ *
+ * `pullBlueprint` is the read-only half of the install: it takes the same
+ * domain / query / catalogEntryId handles and 404s an unknown one. It has no
+ * shape for the two remaining refs, and neither needs it — a discovery receipt
+ * was minted by `discoverDocs` moments earlier in `resolveTarget`, and an
+ * `--mcp-url` is an endpoint the caller typed rather than a handle the backend
+ * could confirm (the handoff prints it back so they can see what they gave).
+ */
+async function assertTargetResolvable(token, companyUid, target) {
+    const { domain, query, catalogEntryId } = target.ref;
+    if (!domain && !query && !catalogEntryId)
+        return;
+    await pullBlueprint(token, companyUid, {
+        ...(domain ? { domain } : {}),
+        ...(query ? { query } : {}),
+        ...(catalogEntryId ? { catalogEntryId } : {}),
+    });
+}
 /**
  * Run the browser sign-in and finish the install.
  *
@@ -343,13 +399,26 @@ async function connectViaOAuth(token, companyUid, target, opts) {
         });
     }
     const startInput = { ...target.ref };
+    // A user-registered app pins the console callback and skips the loopback
+    // entirely — see `userClientSignIn` for why an ephemeral port cannot be the
+    // redirect URI here.
+    const userClient = await resolveUserOAuthClient(opts, target.label);
+    if (userClient)
+        return await userClientSignIn(token, companyUid, target, opts, userClient);
     // A loopback listener only works if the browser runs on THIS machine. Over
     // SSH the person opens the printed URL on their workstation, so the provider
     // redirects to the workstation's 127.0.0.1 while the listener sits on the
     // remote host — the callback can never arrive and the command just times
     // out. Go straight to the console handoff instead of failing slowly.
     if (opts.browser === false && isRemoteShell()) {
-        return await consoleHandoff(token, companyUid, startInput, target, opts);
+        // Every other route into the handoff has already put the target in front
+        // of the backend (`/oauth/start` rejects one it cannot resolve). This one
+        // returns before any request, so a target hq-pro would refuse — a stale
+        // `--entry-id`, an unmatched name that fell through to a raw query — would
+        // be answered with a confident "go finish it in the console" for an app
+        // that is not there. Ask the backend first.
+        await assertTargetResolvable(token, companyUid, target);
+        return await consoleHandoff(target, opts);
     }
     const listener = await startLoopbackListener(timeoutMs === undefined ? {} : { timeoutMs });
     try {
@@ -361,13 +430,16 @@ async function connectViaOAuth(token, companyUid, target, opts) {
             });
         }
         catch (err) {
-            if (!(err instanceof IntegrationsCliError) ||
-                !err.code ||
-                !CONSOLE_HANDOFF_CODES.has(err.code)) {
+            if (!(err instanceof IntegrationsCliError) || !err.code)
                 throw err;
+            if (BRING_YOUR_OWN_CLIENT_CODES.has(err.code)) {
+                listener.close();
+                return await bringYourOwnClientHandoff(target, opts, err.message, err.redirectUri);
             }
+            if (!CONSOLE_HANDOFF_CODES.has(err.code))
+                throw err;
             listener.close();
-            return await consoleHandoff(token, companyUid, startInput, target, opts);
+            return await consoleHandoff(target, opts);
         }
         // Arm the waiter BEFORE the browser opens. The listener buffers a redirect
         // that beats it, but ordering it this way means the happy path never
@@ -391,20 +463,260 @@ async function connectViaOAuth(token, companyUid, target, opts) {
         listener.close();
     }
 }
+const PRODUCTION_CONSOLE_ORIGIN = "https://hq.computer";
+const PRODUCTION_VAULT_API_HOST = "hqapi.hq.computer";
 /**
- * Fallback for a backend that will not accept a loopback callback: start the
- * sign-in against hq-pro's own console callback and hand the URL over. The
- * console route finishes the install, so this command cannot report the
- * result — it reports the handoff truthfully instead of pretending.
+ * The console that fronts the control plane this CLI is pointed at.
+ *
+ * A handoff must land on the console for the SAME backend, because that
+ * console starts its own OAuth flow against its own backend. Sending a staging
+ * session to the production console would connect the app in the wrong place —
+ * so when the control plane is overridden and its console cannot be derived,
+ * return undefined and say so rather than guess a host.
+ *
+ * `HQ_CONSOLE_URL` is the explicit override; otherwise the console is the
+ * control-plane host with its `hqapi.` prefix removed.
  */
-async function consoleHandoff(token, companyUid, startInput, target, opts) {
-    const started = await startOAuth(token, companyUid, startInput);
-    const name = started.displayName || target.label;
-    console.error(chalk.yellow(`${name} signs in through the browser, and this HQ backend finishes those sign-ins in the console.`));
-    console.error(`Open this URL to sign in:\n  ${started.authorizationUrl}`);
+export function consoleOrigin(vaultApiUrl = DEFAULT_VAULT_API_URL) {
+    const explicit = process.env.HQ_CONSOLE_URL?.trim();
+    if (explicit)
+        return explicit.replace(/\/+$/, "");
+    let api;
+    try {
+        api = new URL(vaultApiUrl);
+    }
+    catch {
+        return undefined;
+    }
+    if (api.host === PRODUCTION_VAULT_API_HOST)
+        return PRODUCTION_CONSOLE_ORIGIN;
+    if (!api.hostname.startsWith("hqapi."))
+        return undefined;
+    return `${api.protocol}//${api.host.slice("hqapi.".length)}`;
+}
+/**
+ * The console's Integrations page for a company, the console root when the
+ * caller never named one (a single-membership session resolves the company
+ * server-side, so hq-cli holds a uid here, not a slug — and the console routes
+ * by slug), or undefined when the console for this control plane is unknown.
+ */
+export function consoleIntegrationsUrl(
+// Required, deliberately: a default of `consoleOrigin()` would make an
+// explicit `undefined` — exactly what an unresolvable control plane yields —
+// silently fall back to the production console.
+companySlug, origin) {
+    if (!origin)
+        return undefined;
+    const slug = companySlug?.trim();
+    // A `cmp_…` uid is not a slug; the console has no route for it.
+    if (!slug || slug.startsWith("cmp_"))
+        return origin;
+    return `${origin}/companies/${encodeURIComponent(slug)}/integrations`;
+}
+/**
+ * What the caller named, phrased for someone about to retype it in the console.
+ *
+ * A `--mcp-url` or `--docs-url` target has no catalog row to search for over
+ * there — `resolveTarget` reduces a docs page to an opaque discovery receipt
+ * the console cannot take — so unless the handoff carries the address back,
+ * the only copy of it is in the caller's scrollback. A catalog target needs no
+ * hint: its label IS what they type into the console's search box.
+ */
+function targetSelectionHint(opts) {
+    if (opts.mcpUrl)
+        return `Server address to enter there: ${opts.mcpUrl}`;
+    if (opts.docsUrl)
+        return `Found from these docs: ${opts.docsUrl}`;
+    if (opts.entryId)
+        return `Catalog entry: ${opts.entryId}`;
+    return undefined;
+}
+/** Shared tail of every console handoff: the page, then what to connect there. */
+function printConsoleDestination(target, opts, url) {
+    if (url) {
+        console.error(`Open this page and connect ${target.label} from it:\n  ${url}`);
+    }
+    else {
+        console.error(`Open your HQ console's Integrations page and connect ${target.label} there. ` +
+            "(This session points at a control plane whose console address is not " +
+            "derivable — set HQ_CONSOLE_URL to name it.)");
+    }
+    const hint = targetSelectionHint(opts);
+    if (hint)
+        console.error(`  ${hint}`);
+}
+/**
+ * Fallback for a backend that will not accept a loopback callback: send the
+ * caller to the console and let it run the whole sign-in.
+ *
+ * This deliberately does NOT start an OAuth flow. It used to: it called
+ * `/oauth/start` against hq-pro's console callback and printed the vendor
+ * authorization URL. That URL could never complete. The console's callback
+ * route resolves which company to return to from a short-lived httpOnly cookie
+ * that only its own `startFactoryOAuthSignIn` server action sets, so a browser
+ * arriving from a CLI-minted URL carries no cookie, and the route — by design,
+ * rather than erroring — redirects to the console root. The user signed in
+ * successfully at the vendor every time and landed on the home page with no
+ * explanation, and the burned single-use state row made it look intermittent.
+ *
+ * Handing over the console page instead means the sign-in is started by the
+ * surface that can finish it. hq-cli still cannot report the outcome, so it
+ * says so rather than pretending.
+ */
+async function consoleHandoff(target, opts) {
+    const url = consoleIntegrationsUrl(opts.company, consoleOrigin());
+    console.error(chalk.yellow(`${target.label} signs in through the console, not the terminal — this HQ backend finishes these sign-ins there.`));
+    printConsoleDestination(target, opts, url);
+    if (url && opts.browser !== false)
+        await open(url).catch(() => { });
+    console.error(chalk.dim("When the browser says it connected, run `hq integrations list` to confirm."));
+    return null;
+}
+/**
+ * The provider refuses to register HQ automatically. That is recoverable — an
+ * admin registers their own OAuth app with the provider and pastes its
+ * credentials — but only the console can collect them, so say what is needed
+ * and hand the page over rather than restating the refusal and stopping.
+ */
+async function bringYourOwnClientHandoff(target, opts, reason, redirectUri) {
+    console.error(chalk.yellow(reason));
+    console.error(`${target.label} needs an OAuth app you register with the provider yourself.`);
+    // Prefer finishing here. The recovery needs two things the terminal can
+    // supply — the callback URL to register, and a client id + secret — and
+    // hq-pro sends the first one back on exactly these errors. Falling through
+    // to the console when either half is missing keeps the old behaviour rather
+    // than printing a half-command that cannot work.
+    const command = byoClientCommand(target, opts);
+    if (redirectUri && command) {
+        console.error("");
+        console.error(`In the provider's developer portal, register this callback URL:`);
+        console.error(`  ${redirectUri}`);
+        console.error(`Then run:`);
+        console.error(`  ${command}`);
+        console.error(chalk.dim("The secret is read from stdin, so it stays out of your shell history. " +
+            "Omit --client-secret-stdin for a public app that has no secret."));
+        return null;
+    }
+    const url = consoleIntegrationsUrl(opts.company, consoleOrigin());
+    console.error("The console shows the callback URL to register and takes the credentials.");
+    printConsoleDestination(target, opts, url);
+    if (url && opts.browser !== false)
+        await open(url).catch(() => { });
+    return null;
+}
+/**
+ * The copy-pasteable command that finishes a bring-your-own-app connect.
+ *
+ * Always `connect --mcp-url`, even when the caller reached here through
+ * `reconnect`: re-installing the same endpoint IS the reconnect, and the
+ * direct-endpoint path is the only one hq-pro reads user-supplied client
+ * credentials on. Null when the endpoint is unknown (a bare-name or domain
+ * connect that never resolved to a URL) — there is no honest command to print
+ * then, so the caller falls back to the console.
+ */
+function byoClientCommand(target, opts) {
+    const { mcpUrl, provider } = target.ref;
+    if (!mcpUrl)
+        return null;
+    const parts = ["hq integrations connect", `--mcp-url ${shellQuote(mcpUrl)}`];
+    if (opts.company)
+        parts.push(`--company ${shellQuote(opts.company)}`);
+    if (provider)
+        parts.push(`--provider ${shellQuote(provider)}`);
+    parts.push("--client-id <client-id-from-the-provider>", "--client-secret-stdin");
+    return parts.join(" ");
+}
+/**
+ * Refuse a `--client-id` that hq-pro would silently ignore, before anything is
+ * installed.
+ *
+ * hq-pro reads user-supplied client credentials only on the direct `mcpUrl`
+ * path — on a catalog, domain, or discovery-receipt connect it nulls them out
+ * and resolves its own client instead. Passing them there would not fail: the
+ * connect would attempt dynamic registration exactly as before and come back
+ * with the same refusal, leaving the caller certain they had supplied
+ * credentials that were never read. Say so instead.
+ */
+function assertUserClientApplicable(opts, target, authMode) {
+    if (!opts.clientId && !opts.clientSecretStdin)
+        return;
+    if (!opts.clientId) {
+        throw new IntegrationsCliError("--client-secret-stdin needs --client-id — a secret identifies no app on its own.", { expected: true });
+    }
+    if (opts.token || opts.tokenStdin) {
+        throw new IntegrationsCliError("--client-id is for a browser sign-in and --token is for an API key; pass one or the other, not both.", { expected: true });
+    }
+    // Only an mode the caller or the catalog stated. An UNKNOWN mode is left
+    // alone on purpose: the direct-endpoint path routinely discovers it is
+    // OAuth-protected only when hq-pro says so, and rejecting here would block
+    // the exact providers this flag exists for.
+    if (authMode === "key" || authMode === "none") {
+        throw new IntegrationsCliError(`${target.label} does not use a browser sign-in, so --client-id does not apply to it.`, { expected: true });
+    }
+    if (!target.ref.mcpUrl) {
+        throw new IntegrationsCliError("Your own OAuth app can only be used with a specific endpoint. " +
+            "Re-run with --mcp-url <endpoint> (find it with `hq integrations inspect`), " +
+            "or connect it from the console.", { expected: true });
+    }
+}
+/**
+ * Collect the user-registered OAuth app, if one was asked for.
+ *
+ * The secret has no argv flag by design. A client secret is a long-lived
+ * credential, and argv is visible in shell history and to `ps`; stdin covers
+ * the scripted case and a hidden prompt covers the interactive one, so there
+ * is no case left that an argv flag would serve.
+ */
+async function resolveUserOAuthClient(opts, appLabel) {
+    const clientId = opts.clientId?.trim();
+    if (!clientId)
+        return null;
+    if (opts.clientSecretStdin) {
+        const piped = (await readStdin()).trim();
+        if (!piped) {
+            throw new IntegrationsCliError("--client-secret-stdin was set but stdin was empty.", { expected: true });
+        }
+        return { clientId, clientSecret: piped };
+    }
+    if (process.stdin.isTTY) {
+        const value = (await promptForKey(`Client secret for ${appLabel} (leave blank if the app has none)`)).trim();
+        return value ? { clientId, clientSecret: value } : { clientId };
+    }
+    // Non-interactive and no secret piped: a public client is legitimate, so
+    // proceed with the id alone rather than inventing a blank secret.
+    return { clientId };
+}
+/**
+ * Sign in with an OAuth app the admin registered themselves.
+ *
+ * No loopback listener, deliberately. The whole premise is that the person
+ * registered ONE redirect URI with the provider ahead of time, and an
+ * ephemeral loopback port can never be one of them — so this pins hq-pro's
+ * console callback by omitting `redirectUri`, and the sign-in completes on the
+ * console. hq-cli cannot observe that completion, so it says what it knows and
+ * points at the check, rather than reporting an install it never saw.
+ *
+ * This requires the console callback to be able to finish a flow it did not
+ * start. It could not until hq-pro/#2823 + hq-console/#783: the return company
+ * came from a cookie only the console's own start action set, so a CLI-minted
+ * URL arrived cookie-less and the route dropped the user on the console root
+ * with nothing connected — see `consoleHandoff` below, which exists because of
+ * exactly that. hq-pro now resolves the company from the state row when
+ * `companyUid` is omitted, so the callback completes and the console names the
+ * app it connected. Ship this only against a backend carrying both.
+ */
+async function userClientSignIn(token, companyUid, target, opts, client) {
+    const started = await startOAuth(token, companyUid, {
+        ...target.ref,
+        clientId: client.clientId,
+        ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+    });
+    console.error(`Open this URL to sign in to ${started.displayName || target.label}:`);
+    console.error(`  ${started.authorizationUrl}`);
     if (opts.browser !== false)
         await open(started.authorizationUrl).catch(() => { });
-    console.error(chalk.dim("When the browser says it connected, run `hq integrations list` to confirm."));
+    console.error(chalk.dim("The browser finishes on the HQ console. When it says connected, " +
+        "run `hq integrations list` to confirm."));
     return null;
 }
 /**
@@ -459,6 +771,7 @@ function reportInstall(result, opts, expectedRevivedConnectionId) {
 async function connectApp(token, companyUid, app, opts, expectedRevivedConnectionId) {
     const target = await resolveTarget(token, companyUid, app, opts, expectedRevivedConnectionId !== undefined);
     const authMode = opts.auth ?? target.authClass;
+    assertUserClientApplicable(opts, target, authMode);
     if (authMode === "oauth") {
         const result = await connectViaOAuth(token, companyUid, target, opts);
         if (result)
@@ -536,6 +849,11 @@ export function registerConnectCommands(integrations) {
                 entry.source === "hq-recommended" ? "recommended" : null,
                 entry.source === "hq-discovered" ? "community" : null,
                 entry.mcpReady ? null : "not one-click",
+                // The listing is a claim about connectability, and for these apps HQ
+                // could not re-confirm it: the last probe was inconclusive and the
+                // previous verdict was carried forward. Say so on the row rather
+                // than let it read the same as an app checked this morning.
+                entry.verificationCarriedForward ? "not recently verified" : null,
             ]
                 .filter(Boolean)
                 .join(" · ");
@@ -553,7 +871,10 @@ export function registerConnectCommands(integrations) {
         .action(async (app, opts) => {
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
-        const blueprint = await pullBlueprint(token, companyUid, looksLikeDomain(app) ? { domain: app } : { query: app });
+        // A pasted endpoint URL names one host; look that host up rather than
+        // searching the catalog for the URL as free text.
+        const host = hostFromEndpointUrl(app);
+        const blueprint = await pullBlueprint(token, companyUid, looksLikeDomain(host) ? { domain: host } : { query: app });
         if (opts.json) {
             printJson(blueprint);
             return;
@@ -609,6 +930,8 @@ export function registerConnectCommands(integrations) {
         .option("--token <key>", "API key (prefer --token-stdin: --token lands in shell history)")
         .option("--token-stdin", "Read the API key from stdin")
         .option("--auth <mode>", "Force the auth mode: none, key, or oauth (default: detect)")
+        .option("--client-id <id>", "Client id of an OAuth app you registered with the provider yourself")
+        .option("--client-secret-stdin", "Read that app's client secret from stdin")
         .option("--no-browser", "Print the sign-in URL instead of opening a browser")
         .option("--timeout <seconds>", "How long to wait for a browser sign-in (default 300)")
         .option("--json", "Machine-readable output")
@@ -627,6 +950,8 @@ export function registerConnectCommands(integrations) {
         .option("--token <key>", "API key (prefer --token-stdin)")
         .option("--token-stdin", "Read the API key from stdin")
         .option("--auth <mode>", "Force the auth mode: none, key, or oauth (default: detect)")
+        .option("--client-id <id>", "Client id of an OAuth app you registered with the provider yourself")
+        .option("--client-secret-stdin", "Read that app's client secret from stdin")
         .option("--no-browser", "Print the sign-in URL instead of opening a browser")
         .option("--timeout <seconds>", "How long to wait for a browser sign-in (default 300)")
         .option("--connect", "For a revoked row, run `connect <domain>` to re-add and revive it")
@@ -673,6 +998,13 @@ export function registerConnectCommands(integrations) {
             ...(opts.auth ? { authClass: opts.auth } : {}),
             label: connection.installation?.displayName ?? bareProvider(connection.provider),
         };
+        // Same gate `connectApp` applies. This path does not go through it —
+        // it resolves the endpoint off the existing connection and branches
+        // itself — so without this, flags the CLI promises to reject are
+        // silently ignored instead: `--client-secret-stdin` with no id would
+        // start an ordinary sign-in, and `--client-id` beside `--token` would
+        // reinstall with the bearer token and drop the OAuth app.
+        assertUserClientApplicable(opts, target, target.authClass);
         if (target.authClass === "oauth") {
             const result = await connectViaOAuth(token, companyUid, target, opts);
             if (result)

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

@@ -150,12 +150,23 @@ export declare class IntegrationsCliError extends Error {
      * fingerprint as anything but the finite allowlist in sentry-fingerprint.ts.
      */
     readonly rpcCode?: number;
+    /**
+     * HQ's own OAuth callback URL, carried on the errors that say a provider
+     * refused to register HQ automatically. It is what the admin must register
+     * with the provider before their own OAuth app can be used, and it is NOT a
+     * secret — every authorization server already receives it in the authorize
+     * URL. Taken from the response rather than assembled locally so the CLI
+     * prints the callback this backend will actually redirect to, instead of a
+     * guess at its route that would send the admin to register the wrong URL.
+     */
+    readonly redirectUri?: string;
     constructor(message: string, opts?: {
         expected?: boolean;
         code?: string;
         status?: number;
         oauthProtected?: boolean;
         rpcCode?: number;
+        redirectUri?: string;
     });
 }
 /**

package/dist/commands/integrations-core.js

@@ -51,6 +51,16 @@ export class IntegrationsCliError extends Error {
      * fingerprint as anything but the finite allowlist in sentry-fingerprint.ts.
      */
     rpcCode;
+    /**
+     * HQ's own OAuth callback URL, carried on the errors that say a provider
+     * refused to register HQ automatically. It is what the admin must register
+     * with the provider before their own OAuth app can be used, and it is NOT a
+     * secret — every authorization server already receives it in the authorize
+     * URL. Taken from the response rather than assembled locally so the CLI
+     * prints the callback this backend will actually redirect to, instead of a
+     * guess at its route that would send the admin to register the wrong URL.
+     */
+    redirectUri;
     constructor(message, opts = {}) {
         super(message);
         this.name = "IntegrationsCliError";
@@ -63,6 +73,8 @@ export class IntegrationsCliError extends Error {
             this.oauthProtected = opts.oauthProtected;
         if (opts.rpcCode !== undefined)
             this.rpcCode = opts.rpcCode;
+        if (opts.redirectUri !== undefined)
+            this.redirectUri = opts.redirectUri;
     }
 }
 /**
@@ -184,13 +196,34 @@ export async function raiseForResponse(res, fallback) {
     // print verbatim — scrub credentials out before it can reach a terminal or a
     // Sentry crash report (same reasoning as the gateway path below).
     const detail = redactErrorText(body.error ?? "");
+    const redirectUri = httpsUrlOrNull(body.redirectUri);
     throw new IntegrationsCliError(detail || `${fallback} (HTTP ${res.status})`, {
         expected: isClientError(res.status),
         status: res.status,
         ...(body.code ? { code: body.code } : {}),
         ...(body.oauthProtected === true ? { oauthProtected: true } : {}),
+        ...(redirectUri ? { redirectUri } : {}),
     });
 }
+/**
+ * Accept a response field only if it really is an absolute https URL.
+ *
+ * This one is printed as an instruction — "register THIS with the provider" —
+ * so a malformed or non-https value must be dropped rather than echoed: the
+ * caller's fallback (send them to the console, which shows the same callback)
+ * is correct, while a bad URL would have them register a callback that can
+ * never complete a sign-in.
+ */
+function httpsUrlOrNull(value) {
+    if (typeof value !== "string" || !value.trim())
+        return null;
+    try {
+        return new URL(value).protocol === "https:" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
 export function toolPrefixForProvider(provider) {
     return provider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.105.1",
+  "version": "5.106.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.16.1",
+    "@indigoai-us/hq-cloud": "~6.16.3",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",