@indigoai-us/hq-cli 5.341.5 → 5.342.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.342.0] — 2026-10-04
+
+- Keep `hq integrations call` alive through slow provider calls with bounded async-job polling, safe idempotent retry guidance on timeout, and validation of terminal responses.
+
+- Let `hq sync now` skip unchanged server-owned cloud placeholders while keeping their warnings visible, so the sync can complete.
+
 ## [5.341.5] — 2026-10-04
 - Reconcile can close an eligible done-story worker with a legacy missing `interrupted_at` when a matching watcher classification proves the interruption age.
 - `hq doctor --verbose` now shows passing checks, including hqd runtime health details.

package/dist/commands/cloud.js

@@ -1751,6 +1751,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             hqRoot,
             progressRecorder: trackingProgressRecorder(planLimitTracker, pushProgressCompany),
             skipUnchanged: true,
+            serverOwnedPathPolicy: "skip",
             propagateDeletes: true,
             propagateDeletePolicy: resolveDeletePolicy(),
             ...(onConflict ? { onConflict } : {}),

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

@@ -248,7 +248,7 @@ export declare function resolveConnection(token: string, companyUid: string, app
 }, recoveryOpts?: {
     allowSingleRevoked?: boolean;
 }): Promise<AdminConnection>;
-export declare function callGateway(token: string, params: Record<string, unknown>): Promise<GatewayMessage>;
+export declare function callGateway(token: string, params: Record<string, unknown>, idempotencyKey?: string): Promise<GatewayMessage>;
 /**
  * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`
  * where `text` is the provider's JSON. Unwrap to the inner payload; fall back

package/dist/commands/integrations-core.js

@@ -18,6 +18,8 @@ import { redactSensitiveUrls, redactUrlsInText } from "../utils/redact-url.js";
 import { connectionHealthNotice } from "../lib/integrations/health.js";
 import { bareProvider } from "../lib/integrations/provider-slug.js";
 export { bareProvider } from "../lib/integrations/provider-slug.js";
+const ASYNC_GATEWAY_POLL_INTERVAL_MS = 1_000;
+const ASYNC_GATEWAY_DEADLINE_MS = 4 * 60_000 + 30_000;
 export class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -397,7 +399,8 @@ export async function resolveConnection(token, companyUid, app, opts, recoveryOp
     }
     return selectConnection(connections, opts);
 }
-export async function callGateway(token, params) {
+export async function callGateway(token, params, idempotencyKey) {
+    const deadline = Date.now() + ASYNC_GATEWAY_DEADLINE_MS;
     const res = await vaultApiFetch({
         token,
         path: "/v1/integrations/mcp",
@@ -410,7 +413,23 @@ export async function callGateway(token, params) {
         },
     });
     const message = (await res.json().catch(() => null));
-    if (!res.ok || !message) {
+    let terminalMessage = message;
+    if (res.status === 202) {
+        const accepted = message;
+        const jobId = accepted && typeof accepted.jobId === "string" ? accepted.jobId : "";
+        if (accepted?.status !== "pending" || !/^imj_[A-Za-z0-9_-]+$/.test(jobId)) {
+            throw new IntegrationsCliError(`Integration gateway returned an invalid async job response (job id: ${jobId || "missing"}).`, { expected: false, status: 202 });
+        }
+        const companyUid = typeof params.companyUid === "string" ? params.companyUid : "";
+        if (!companyUid) {
+            throw new IntegrationsCliError(`Cannot poll integration job ${jobId}: the company id is missing.`, { expected: true });
+        }
+        if (!idempotencyKey) {
+            throw new IntegrationsCliError(`Integration gateway accepted async job ${jobId} without an idempotency key.`, { expected: false, status: 202 });
+        }
+        terminalMessage = await pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline);
+    }
+    if (res.status !== 202 && (!res.ok || !terminalMessage)) {
         raiseIfUnauthorized(res);
         raiseIfUpstreamUnavailable(res);
         // Carry the HTTP status so a reportable transport failure (e.g. a 501 that
@@ -420,7 +439,7 @@ export async function callGateway(token, params) {
         // `status`. This does not change the `expected` decision above.
         throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status });
     }
-    if (message.error) {
+    if (terminalMessage?.error) {
         // The gateway's error text is minted UPSTREAM (hq-pro, the integration
         // factory, and beyond it the third-party provider), so it is untrusted:
         // scrub credentials and bound the length here, at the throw site, because
@@ -429,16 +448,87 @@ export async function callGateway(token, params) {
         // The chain is idempotent, so the unexpected path scrubbing again is a
         // no-op. This preserves PR #298's user-visible diagnostic; it only makes
         // it safe on the newly-expected path.
-        throw new IntegrationsCliError(redactErrorText(message.error.message ?? "") ||
+        throw new IntegrationsCliError(redactErrorText(terminalMessage.error.message ?? "") ||
             "Integration gateway returned an error.", {
-            expected: isExpectedGatewayError(message.error.code),
+            expected: isExpectedGatewayError(terminalMessage.error.code),
             // Carry the protocol code to the capture site as a bounded grouping
             // discriminator (HQ-CLI collision, Sentry 7642756130). This does not
             // alter the `expected` decision above; it only labels the error.
-            ...(message.error.code !== undefined ? { rpcCode: message.error.code } : {}),
+            ...(terminalMessage.error.code !== undefined ? { rpcCode: terminalMessage.error.code } : {}),
         });
     }
-    return message;
+    return terminalMessage;
+}
+async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline) {
+    const jobPath = `/v1/integrations/mcp/jobs/${encodeURIComponent(jobId)}`;
+    while (Date.now() < deadline) {
+        const requestRemainingMs = deadline - Date.now();
+        if (requestRemainingMs <= 0)
+            break;
+        const controller = new AbortController();
+        const requestTimeout = setTimeout(() => controller.abort(), requestRemainingMs);
+        let res;
+        let poll;
+        try {
+            res = await vaultApiFetch({
+                token,
+                path: jobPath,
+                method: "GET",
+                query: { companyUid },
+                signal: controller.signal,
+            });
+            poll = (await res.json().catch(() => null));
+        }
+        catch (error) {
+            if (!controller.signal.aborted)
+                throw error;
+            break;
+        }
+        finally {
+            clearTimeout(requestTimeout);
+        }
+        if (!res.ok) {
+            raiseIfUnauthorized(res);
+            raiseIfUpstreamUnavailable(res);
+            if (res.status === 404) {
+                throw new IntegrationsCliError(`Integration job ${jobId} was not found or is no longer available.`, { expected: true, status: 404 });
+            }
+            throw new IntegrationsCliError(`Integration job ${jobId} polling failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status });
+        }
+        if (!poll || typeof poll !== "object") {
+            throw new IntegrationsCliError(`Integration job ${jobId} returned an invalid poll response.`, { expected: true });
+        }
+        if (poll.status === "result" || poll.status === "error") {
+            const response = poll.response;
+            const isPlainObject = response !== null &&
+                typeof response === "object" &&
+                !Array.isArray(response) &&
+                (Object.getPrototypeOf(response) === Object.prototype || Object.getPrototypeOf(response) === null);
+            const responseRecord = isPlainObject ? response : undefined;
+            const hasResult = responseRecord ? Object.hasOwn(responseRecord, "result") : false;
+            const hasError = responseRecord ? Object.hasOwn(responseRecord, "error") : false;
+            const error = responseRecord?.error;
+            const validError = error !== null &&
+                typeof error === "object" &&
+                !Array.isArray(error) &&
+                (Object.getPrototypeOf(error) === Object.prototype || Object.getPrototypeOf(error) === null);
+            const hasJsonRpcOutcome = responseRecord?.jsonrpc === "2.0" &&
+                hasResult !== hasError &&
+                (!hasError || validError);
+            if (!hasJsonRpcOutcome) {
+                throw new IntegrationsCliError(`Integration job ${jobId} returned an invalid JSON-RPC response.`, { expected: false });
+            }
+            return response;
+        }
+        if (poll.status !== "pending") {
+            throw new IntegrationsCliError(`Integration job ${jobId} returned unknown status '${String(poll.status)}'.`, { expected: true });
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(ASYNC_GATEWAY_POLL_INTERVAL_MS, remainingMs)));
+    }
+    throw new IntegrationsCliError(`Timed out waiting for integration job ${jobId}; the server job may still finish. To safely retry, rerun with --idempotency-key ${idempotencyKey}.`, { expected: true });
 }
 /**
  * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`

package/dist/commands/integrations.js

@@ -338,6 +338,7 @@ export function registerIntegrationsCommand(program) {
         const idempotencyKey = opts.idempotencyKey ?? `hq-cli-${randomUUID()}`;
         const message = await callGateway(token, {
             companyUid,
+            acceptAsync: true,
             name: `${prefix}.mcp.tools.call`,
             arguments: {
                 companyUid,
@@ -346,7 +347,7 @@ export function registerIntegrationsCommand(program) {
                 arguments: parsedArgs,
                 idempotencyKey,
             },
-        });
+        }, idempotencyKey);
         const payload = unwrapGatewayResult(message.result);
         const queued = queuedOutcome(payload);
         if (queued) {

package/package.json

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