@indigoai-us/hq-cli 5.345.155 → 5.345.159

package/dist/commands/feedback.js

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import chalk from "chalk";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { ensureCognitoToken, loadCachedTokens } from "../utils/cognito-session.js";
 import { assertVaultApiRequestSupported, vaultApiFetch, } from "../utils/vault-api.js";
 import { collectDiagnostics } from "../utils/feedback-diagnostics.js";
 import { MAX_SCREENSHOTS, uploadScreenshots } from "../utils/feedback-screenshots.js";
@@ -8,6 +8,7 @@ import { FEEDBACK_LOGS_MAX_TOTAL_BYTES, FEEDBACK_LOGS_MIN_USEFUL_BYTES, collectF
 import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
 import { cachedLatestVersion } from "../utils/version-check.js";
+import { registerFeedbackShowCommand } from "./feedback-show.js";
 export const FEEDBACK_LATEST_VERSION_FLAG = "feedback.latest-version";
 export const FEEDBACK_LATEST_VERSION_FLAG_FALLBACK = false;
 export const FEEDBACK_REPORTER_KIND_FLAG = "feedback.reporter-kind";
@@ -199,7 +200,151 @@ export async function submitFeedback(opts) {
         throw new Error(`Failed to submit feedback: ${errMsg}`);
     }
     const data = (await res.json());
-    return { id: data.id };
+    return {
+        id: data.id,
+        ...(typeof data.publicUrl === "string" && data.publicUrl.length > 0
+            ? { publicUrl: data.publicUrl }
+            : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Public ticket pages: `hq feedback link <id>` and `hq feedback update <id>`
+// ---------------------------------------------------------------------------
+/** Customer-visible states accepted by `hq feedback update --state`. */
+export const PUBLIC_TICKET_STATES = [
+    "triaged",
+    "in-progress",
+    "shipped",
+    "verified",
+    "resolved",
+];
+const FEEDBACK_ID_RE = /^feedback_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export function assertFeedbackId(id) {
+    if (!FEEDBACK_ID_RE.test(id)) {
+        throw new Error(`Invalid feedback id '${id}': expected the full feedback_<uuid> id printed by hq feedback.`);
+    }
+}
+/**
+ * The staff feedback routes gate on the id token's email claim, so send the
+ * cached id token when a person session has one. Machine identities already
+ * get their id token back from ensureCognitoToken.
+ */
+async function resolveStaffToken() {
+    const token = await ensureCognitoToken({ interactive: false });
+    const cached = loadCachedTokens();
+    return typeof cached?.idToken === "string" && cached.idToken.length > 0
+        ? cached.idToken
+        : token;
+}
+async function readFeedbackError(res) {
+    const data = await res.json().catch(() => ({}));
+    return data &&
+        typeof data === "object" &&
+        !Array.isArray(data) &&
+        typeof data.error === "string"
+        ? data.error
+        : res.statusText;
+}
+function publicUrlFrom(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return null;
+    const url = data.publicUrl;
+    return typeof url === "string" && url.length > 0 ? url : null;
+}
+/** Resolve (and lazily mint) the public tracking link for a ticket. */
+export async function fetchFeedbackLink(opts) {
+    const res = await vaultApiFetch({
+        token: opts.token,
+        path: `/v1/feedback/${opts.id}`,
+        method: "PATCH",
+        body: { ensurePublicToken: true },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to get the public link for ${opts.id}: ${await readFeedbackError(res)}`);
+    }
+    const url = publicUrlFrom(await res.json());
+    if (!url) {
+        throw new Error(`The server did not return a public link for ${opts.id}. Public ticket pages may not be deployed yet.`);
+    }
+    return url;
+}
+/** Post a customer-visible update; the server also mirrors it into #hq-feedback. */
+export async function postFeedbackUpdate(opts) {
+    const res = await vaultApiFetch({
+        token: opts.token,
+        path: `/v1/feedback/${opts.id}`,
+        method: "PATCH",
+        body: { publicUpdate: { state: opts.state, note: opts.note } },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to update ${opts.id}: ${await readFeedbackError(res)}`);
+    }
+    const data = (await res.json());
+    return {
+        publicUrl: publicUrlFrom(data),
+        slack: typeof data.publicUpdateSlack === "string" ? data.publicUpdateSlack : null,
+    };
+}
+function registerLinkSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("link")
+        .description("Print the public tracking link for a ticket (status.hqforwork.com)")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .action(async (id) => {
+        try {
+            assertFeedbackId(id);
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            const url = await fetchFeedbackLink({ id, token });
+            console.log(`Track: ${url}`);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+function registerUpdateSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("update")
+        .description("Post a customer-visible status update on a ticket's public page and its #hq-feedback thread")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .requiredOption("--state <state>", `One of: ${PUBLIC_TICKET_STATES.join(", ")}`)
+        .requiredOption("--note <text>", "What the customer should read (plain text, up to 2000 characters)")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            if (!PUBLIC_TICKET_STATES.includes(opts.state)) {
+                throw new Error(`Invalid --state '${opts.state}': expected one of ${PUBLIC_TICKET_STATES.join(", ")}.`);
+            }
+            const note = opts.note.trim();
+            if (note.length === 0)
+                throw new Error("--note must not be empty.");
+            if (note.length > 2000)
+                throw new Error("--note must be at most 2000 characters.");
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            const result = await postFeedbackUpdate({
+                id,
+                token,
+                state: opts.state,
+                note,
+            });
+            console.log(`Updated: ${id} -> ${opts.state}`);
+            if (result.publicUrl)
+                console.log(`Track: ${result.publicUrl}`);
+            if (result.slack === "failed") {
+                console.error(chalk.yellow("Warning:"), "the update was saved but the #hq-feedback thread post failed.");
+            }
+            else if (result.slack === "skipped") {
+                console.error(chalk.yellow("Note:"), "the ticket has no #hq-feedback thread, so nothing was posted to Slack.");
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
 }
 function registerSubcommand(feedbackCmd, type) {
     feedbackCmd
@@ -284,6 +429,8 @@ function registerSubcommand(feedbackCmd, type) {
                 logsEnabled,
             });
             console.log(`Submitted: ${result.id}`);
+            if (result.publicUrl)
+                console.log(`Track: ${result.publicUrl}`);
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -297,5 +444,8 @@ export function registerFeedbackCommand(program) {
         .description("Submit a bug report or feature request to HQ");
     registerSubcommand(feedbackCmd, "bug");
     registerSubcommand(feedbackCmd, "feature");
+    registerLinkSubcommand(feedbackCmd);
+    registerUpdateSubcommand(feedbackCmd);
+    registerFeedbackShowCommand(feedbackCmd);
 }
 //# sourceMappingURL=feedback.js.map

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

@@ -443,6 +443,22 @@ export declare const PRESIGN_BUFFER_MAX_BYTES: number;
  * access token + companyUid are captured here; the orchestrator just calls
  * `send(...)` as if it held an S3 client.
  */
+/** Error code for a presigned storage download that failed after the API authorized it. */
+export declare const STORAGE_DOWNLOAD_FAILED_CODE = "FILES_STORAGE_DOWNLOAD_FAILED";
+/**
+ * Build the error for a failed presigned download. The API already checked the
+ * caller's ACL before it signed the URL, so a failure here is a storage or
+ * network outcome, not a missing grant. The error carries no `status: 403` and
+ * a code that `isAccessDeniedError` treats as not an access denial, so the CLI
+ * does not send the caller to `hq access` (which only re-checks the ACL that
+ * already passed).
+ *
+ * A response that really came from S3 carries `x-amz-request-id`; we report
+ * S3's error code from the XML body. A response without it came from something
+ * between this machine and the storage host, usually a sandbox egress proxy or
+ * firewall that does not allow the bucket host, and we say so.
+ */
+export declare function presignedDownloadError(key: string, url: string, dl: Response): Promise<Error>;
 export declare function createCompanyPresignClient(input: {
     token: string;
     companyUid: string;

package/dist/commands/files-browse.js

@@ -709,6 +709,57 @@ export const PRESIGN_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
  * access token + companyUid are captured here; the orchestrator just calls
  * `send(...)` as if it held an S3 client.
  */
+/** Error code for a presigned storage download that failed after the API authorized it. */
+export const STORAGE_DOWNLOAD_FAILED_CODE = "FILES_STORAGE_DOWNLOAD_FAILED";
+/**
+ * Build the error for a failed presigned download. The API already checked the
+ * caller's ACL before it signed the URL, so a failure here is a storage or
+ * network outcome, not a missing grant. The error carries no `status: 403` and
+ * a code that `isAccessDeniedError` treats as not an access denial, so the CLI
+ * does not send the caller to `hq access` (which only re-checks the ACL that
+ * already passed).
+ *
+ * A response that really came from S3 carries `x-amz-request-id`; we report
+ * S3's error code from the XML body. A response without it came from something
+ * between this machine and the storage host, usually a sandbox egress proxy or
+ * firewall that does not allow the bucket host, and we say so.
+ */
+export async function presignedDownloadError(key, url, dl) {
+    let host = "the storage host";
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        // keep the generic label
+    }
+    const requestId = dl.headers.get("x-amz-request-id");
+    const bodyText = (await dl.text().catch(() => "")).slice(0, 4096);
+    const fromStorage = requestId !== null && requestId.length > 0;
+    let message;
+    let storageCode;
+    if (fromStorage) {
+        storageCode = /<Code>([^<]{1,100})<\/Code>/.exec(bodyText)?.[1];
+        message =
+            `Failed to download '${key}' (HTTP ${dl.status}` +
+                (storageCode ? `, storage error ${storageCode}` : "") +
+                `, request id ${requestId}). Your file access was granted; the storage ` +
+                `service refused the signed download. Report this with: hq feedback bug`;
+    }
+    else {
+        message =
+            `Failed to download '${key}' (HTTP ${dl.status}). Your file access was ` +
+                `granted, but the response did not come from ${host}. A proxy or network ` +
+                `egress rule on this machine likely blocked it. Allow outbound HTTPS to ` +
+                `${host} (HQ vault files are served from *.s3.us-east-1.amazonaws.com).`;
+    }
+    return Object.assign(new Error(message), {
+        code: STORAGE_DOWNLOAD_FAILED_CODE,
+        key,
+        httpStatus: dl.status,
+        fromStorage,
+        ...(storageCode ? { storageCode } : {}),
+    });
+}
 export function createCompanyPresignClient(input) {
     const { token, companyUid, companySlug, baseUrl } = input;
     const denied = (message, key, extra) => Object.assign(new Error(message), {
@@ -780,7 +831,7 @@ export function createCompanyPresignClient(input) {
         }
         const dl = await fetch(first.url, { signal: AbortSignal.timeout(120_000) });
         if (!dl.ok) {
-            throw new Error(`Failed to download '${key}' (HTTP ${dl.status})`);
+            throw await presignedDownloadError(key, first.url, dl);
         }
         // 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

package/dist/commands/files.d.ts

@@ -9,6 +9,30 @@ export declare const FILES_SHARE_EMPTY_PREFIX_WARNING_FLAG = "files.share-empty-
 export declare function parseDuration(input: string): number | null;
 /** PRD upper bound on browser-launch share-session expiry. */
 export declare const MAX_SHARE_SESSION_EXPIRY_MS: number;
+/**
+ * A more specific ACL row under a prefix, as hq-pro reports it. File ACL
+ * resolution picks the single most specific row that covers a key, so each of
+ * these rows replaces the broader prefix's grants for the keys it covers
+ * (feedback_466fe8b8).
+ */
+export interface AclMaskingRow {
+    path: string;
+    open: boolean;
+    creatorUid: string;
+    grantees: Array<{
+        granteeType: string;
+        granteeId: string;
+        permission: string;
+    }>;
+}
+/** The warning `hq files share` prints when a grant is shadowed by more specific rows. */
+export declare function formatShadowedGrantWarning(input: {
+    prefix: string;
+    principal: string;
+    permission: string;
+    companySlug?: string;
+    maskedBy: AclMaskingRow[];
+}): string;
 export interface ShareSessionResponse {
     url: string;
     token?: string;

package/dist/commands/files.js

@@ -9,6 +9,7 @@ import { looksLikeCompanyUid } from "../utils/vault-api.js";
 import { AuthError } from "../utils/auth-error.js";
 import { formatAccessDenied, offerAccessLadder, } from "../utils/access-denied-hint.js";
 import { fetchChannels, matchChannelsByName } from "./dm.js";
+import { suggestChannels, withChannelSuggestions } from "./channel-suggest.js";
 import { resolveCompanySlug, resolvePersonWithRosterFallback, } from "./people.js";
 import { findHqRoot } from "../utils/manifest.js";
 import { maxLength } from "../utils/table-width.js";
@@ -55,6 +56,39 @@ function privateFolderExplanation(prefix) {
     return (`Private folder '${prefix}' — write can create only a new direct child. ` +
         "Children are creator-only; this grant does not read, list, overwrite, or delete them.");
 }
+function describeMaskingGrantees(row) {
+    if (row.open)
+        return "open (all members read)";
+    if (row.grantees.length === 0)
+        return "none (creator only)";
+    return row.grantees
+        .map((g) => g.granteeType === "company-wide"
+        ? `everyone:${g.permission}`
+        : `${g.granteeId}:${g.permission}`)
+        .join(", ");
+}
+function printMaskingTable(rows) {
+    const PATH_W = Math.max(4, ...rows.map((r) => displayAclPattern(r.path).length));
+    const CREATOR_W = Math.max(7, ...rows.map((r) => r.creatorUid.length));
+    console.log(chalk.bold(["PATH".padEnd(PATH_W), "CREATOR".padEnd(CREATOR_W), "GRANTS"].join("  ")));
+    for (const row of rows) {
+        console.log([
+            displayAclPattern(row.path).padEnd(PATH_W),
+            row.creatorUid.padEnd(CREATOR_W),
+            describeMaskingGrantees(row),
+        ].join("  "));
+    }
+}
+/** The warning `hq files share` prints when a grant is shadowed by more specific rows. */
+export function formatShadowedGrantWarning(input) {
+    const paths = input.maskedBy.map((row) => `'${row.path}'`).join(", ");
+    const company = input.companySlug ? ` --company ${input.companySlug}` : "";
+    return (`Warning: this grant takes no effect under ${input.maskedBy.length} more specific rule(s) ` +
+        `that do not include ${input.principal}: ${paths}. ` +
+        "Access under those paths is unchanged (the most specific rule wins). " +
+        `Share them too, for example: hq files share '${input.maskedBy[0]?.path ?? "<path>"}' --with ${input.principal} --permission ${input.permission}${company}` +
+        " — or remove the rule with hq files unshare.");
+}
 function formatAclPatternConflict(prefix, serverMessage) {
     const privatePattern = prefix.endsWith("/*")
         ? prefix.slice(0, -1)
@@ -544,6 +578,14 @@ export function registerFilesCommand(program) {
                 console.log("\nGranted on descendant prefixes (do not affect this prefix's access):");
                 printEntryTable(tree.children, true);
             }
+            if (Array.isArray(tree.masking) && tree.masking.length > 0) {
+                console.log(`\nMore specific rules under ${displayAclPattern(tree.prefix)} (each replaces this prefix's grants for its own paths):`);
+                printMaskingTable(tree.masking);
+                if (tree.maskingTruncated) {
+                    console.log(chalk.gray("  ...list truncated; use --json for the first page."));
+                }
+                console.log(chalk.gray(`A grant on ${displayAclPattern(tree.prefix)} does not reach these paths unless they grant the same principal. Share each path too, or remove its rule with hq files unshare.`));
+            }
             const allEntries = [...tree.direct, ...tree.inherited, ...tree.children];
             if (allEntries.some((entry) => entry.granteeType === "company-wide")) {
                 console.log(chalk.gray("\nCompany-wide grants apply to every active member, including guests. Demoting someone to guest does not exclude them. Use hq members remove to end membership, or hq access <path> --as <email> to see effective access."));
@@ -704,7 +746,7 @@ async function resolveShareChannelTarget(params) {
     const channels = await fetchChannels(token);
     const matches = matchChannelsByName(channels, params.channelName);
     if (matches.length === 0) {
-        console.error(chalk.red(`No channel named '${params.channelName}' — run \`hq channels\` to see your channels.`));
+        console.error(chalk.red(withChannelSuggestions(`No channel named '${params.channelName}' — run \`hq channels\` to see your channels.`, suggestChannels(channels, params.channelName))));
         process.exit(1);
     }
     if (matches.length > 1) {
@@ -894,6 +936,15 @@ async function runDirectGrant(params) {
     if (isPrivateFolderPattern(printedPrefix)) {
         console.log(chalk.gray(privateFolderExplanation(printedPrefix)));
     }
+    if (Array.isArray(data.maskedBy) && data.maskedBy.length > 0) {
+        console.warn(chalk.yellow(formatShadowedGrantWarning({
+            prefix: printedPrefix,
+            principal: isAll ? "@all" : principal,
+            permission: params.permission,
+            ...(params.companySlug ? { companySlug: params.companySlug } : {}),
+            maskedBy: data.maskedBy,
+        })));
+    }
     if (typeof data.record?.error === "string" &&
         typeof data.record.status === "number" &&
         data.record.status >= 400) {

package/dist/commands/integrations-connect.js

@@ -548,12 +548,16 @@ async function connectViaOAuth(token, companyUid, target, opts) {
         ...target.ref,
         ...(requestedScopes ? { scopes: requestedScopes } : {}),
     };
-    if (opts.linkOnly)
-        return await linkOnlySignIn(token, companyUid, target, opts, startInput);
+    const userClient = await resolveUserOAuthClient(opts, target.label);
+    if (opts.linkOnly) {
+        return await linkOnlySignIn(token, companyUid, target, opts, {
+            ...startInput,
+            ...(userClient ?? {}),
+        });
+    }
     // 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, requestedScopes);
     // A loopback listener only works if the browser runs on THIS machine. Over

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

@@ -120,6 +120,16 @@ interface GatewayMessage {
 }
 export type GatewayErrorShape = "string_error" | "object_no_code" | "object_code" | "string_code" | "nested_code" | "empty" | "redacted_empty";
 export type GatewayFailureCode = "invalid_envelope";
+/** Default client wait for a background (202) integration job. */
+export declare const ASYNC_GATEWAY_DEADLINE_MS: number;
+/** Upper bound for `hq integrations call --timeout`, in seconds. */
+export declare const MAX_CALL_TIMEOUT_SECONDS: number;
+/**
+ * Parse `--timeout <seconds>` for `hq integrations call` into milliseconds.
+ * Bounds how long the CLI waits for a background job; it never shortens the
+ * gateway's own limits.
+ */
+export declare function parseCallTimeoutMs(raw: string | undefined): number;
 export declare class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -338,7 +348,9 @@ export declare function resolveConnection(token: string, companyUid: string, app
 }, recoveryOpts?: {
     allowSingleRevoked?: boolean;
 }): Promise<AdminConnection>;
-export declare function callGateway(token: string, params: Record<string, unknown>, idempotencyKey?: string, method?: "tools/call" | "tools/list"): Promise<GatewayMessage>;
+export declare function callGateway(token: string, params: Record<string, unknown>, idempotencyKey?: string, method?: "tools/call" | "tools/list", opts?: {
+    waitMs?: number;
+}): 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

@@ -19,7 +19,43 @@ 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;
+/** Default client wait for a background (202) integration job. */
+export const ASYNC_GATEWAY_DEADLINE_MS = 4 * 60_000 + 30_000;
+/** Upper bound for `hq integrations call --timeout`, in seconds. */
+export const MAX_CALL_TIMEOUT_SECONDS = 30 * 60;
+/**
+ * Parse `--timeout <seconds>` for `hq integrations call` into milliseconds.
+ * Bounds how long the CLI waits for a background job; it never shortens the
+ * gateway's own limits.
+ */
+export function parseCallTimeoutMs(raw) {
+    if (raw === undefined)
+        return ASYNC_GATEWAY_DEADLINE_MS;
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new IntegrationsCliError(`--timeout must be a whole number of seconds (got "${raw}").`, { expected: true });
+    }
+    const seconds = Number(trimmed);
+    if (seconds < 1 || seconds > MAX_CALL_TIMEOUT_SECONDS) {
+        throw new IntegrationsCliError(`--timeout must be between 1 and ${MAX_CALL_TIMEOUT_SECONDS} seconds (got ${seconds}).`, { expected: true });
+    }
+    return seconds * 1_000;
+}
+/**
+ * Statuses the gateway returns when an inline (non-background) tools/call ran
+ * into the IntegrationMcpFunction 30s wall or its provider budget.
+ */
+function isInlineTimeoutStatus(status) {
+    return status === 500 || status === 502 || status === 504;
+}
+function inlineTimeoutHint(status) {
+    return (`${upstreamUnavailableMessage(status)} ` +
+        "If this was a long-running call (for example a large analytical read), it may have hit the " +
+        "gateway's 30-second limit: the gateway ran it inline, not as a background job. Long calls " +
+        "run as background jobs only when async integration jobs are enabled for your company; ask " +
+        "HQ support to enable them. Once enabled, hq integrations call waits for the result " +
+        "automatically (see --timeout).");
+}
 export class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -627,9 +663,9 @@ function gatewaySubcommandFor(params, method) {
         return "tools_call";
     return "other";
 }
-export async function callGateway(token, params, idempotencyKey, method = "tools/call") {
+export async function callGateway(token, params, idempotencyKey, method = "tools/call", opts = {}) {
     const gatewaySubcommand = gatewaySubcommandFor(params, method);
-    const deadline = Date.now() + ASYNC_GATEWAY_DEADLINE_MS;
+    const deadline = Date.now() + (opts.waitMs ?? ASYNC_GATEWAY_DEADLINE_MS);
     const res = await vaultApiFetch({
         token,
         path: "/v1/integrations/mcp",
@@ -663,6 +699,15 @@ export async function callGateway(token, params, idempotencyKey, method = "tools
     }
     if (res.status !== 202 && (!res.ok || !terminalMessage)) {
         raiseIfUnauthorized(res);
+        if (method === "tools/call" &&
+            params.acceptAsync === true &&
+            isInlineTimeoutStatus(res.status)) {
+            throw new IntegrationsCliError(inlineTimeoutHint(res.status), {
+                expected: true,
+                status: res.status,
+                gatewaySubcommand,
+            });
+        }
         raiseIfUpstreamUnavailable(res);
         // Carry the HTTP status so a reportable transport failure (e.g. a 501 that
         // is neither 401 nor an upstream-availability status, so it is captured)
@@ -773,7 +818,7 @@ async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, dea
             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 });
+    throw new IntegrationsCliError(`Timed out waiting for integration job ${jobId}; the server job may still finish. To safely retry, rerun with --idempotency-key ${idempotencyKey} (add --timeout <seconds> to wait longer).`, { expected: true });
 }
 /**
  * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`

package/dist/commands/integrations.js

@@ -56,7 +56,7 @@ import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { redactSensitiveUrl, redactSensitiveUrls, redactUrlsInText } from "../utils/redact-url.js";
-import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, fetchUsableApps, isBuiltInGatewayProvider, isClientError, printHealthNotice, printJson, printIntegrationCallResultJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, callGateway, parseCallTimeoutMs, fetchConnections, fetchUsableApps, isBuiltInGatewayProvider, isClientError, printHealthNotice, printJson, printIntegrationCallResultJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
 import { registerConnectCommands } from "./integrations-connect.js";
 import { registerImportCommands } from "./integrations-import.js";
 import { registerManageCommands } from "./integrations-manage.js";
@@ -483,8 +483,10 @@ export function registerIntegrationsCommand(program) {
         .option("--args <json>", "Tool arguments as a JSON object (default {}); use - to read the JSON from stdin")
         .option("--args-file <path>", "Read tool arguments from a JSON file (use - for stdin); avoids shell quoting of apostrophes and parentheses")
         .option("--idempotency-key <key>", "Stable key so retries execute at most once (default: generated)")
+        .option("--timeout <seconds>", "How long to wait for a long call that runs as a background job (default 270, max 1800)")
         .option("--json", "Machine-readable output")
         .action(async (tool, opts) => {
+        const waitMs = parseCallTimeoutMs(opts.timeout);
         const parsedArgs = await resolveCallArgs(opts);
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
@@ -522,7 +524,7 @@ export function registerIntegrationsCommand(program) {
                 },
             };
         }
-        const message = await callGateway(token, gatewayParams, idempotencyKey);
+        const message = await callGateway(token, gatewayParams, idempotencyKey, "tools/call", { waitMs });
         const payload = unwrapGatewayResult(message.result);
         const queued = queuedOutcome(payload);
         if (queued) {

package/dist/commands/lanes-accounts.js

@@ -9,9 +9,11 @@ import { assertUniqueAccountHomes, providerCompactAfterMs } from "../lib/lanes/c
 import { resolveLaneEffort } from "../lib/lanes/effort.js";
 import { LanesError } from "../lib/lanes/errors.js";
 import { CAPACITY_ONLY_REASON } from "../lib/capacity/accounts.js";
+import { claudeOpenCommand } from "../lib/capacity/ledger.js";
 import { accountQuotaView, clearAccountQuota, loadQuotaState } from "../lib/lanes/quota.js";
 import { resolveLaneModel } from "../lib/lanes/spawn.js";
 import { leadLaneIds } from "../lib/lanes/admission.js";
+import { resolveLaneCompany } from "../lib/lanes/lane-company.js";
 export function createLaneAccountsHandlers(deps) {
     const { admitQueuedFromCtx, automaticBalanceMoveHistoryReason, ensureDir, laneWithRecoveredProviderSession, loadClaudeBalanceHostSnapshots, parseRemoteJson, prepareAccountMove, printJson, reconcileHostFromCtx, resolveCallerPath } = deps;
     const VENDOR_LOGIN = {
@@ -124,6 +126,7 @@ export function createLaneAccountsHandlers(deps) {
             hostname: ctx.hostname(),
             homedir: ctx.homedir,
             probe: ctx.probeProvider,
+            readClaudeCredential: ctx.readClaudeCredential,
             env: ctx.env,
         }).map((status) => {
             const accountCfg = config.providers[provider].accounts[status.id];
@@ -146,6 +149,10 @@ export function createLaneAccountsHandlers(deps) {
                     error: "home_missing",
                     fix_command: `hq lanes accounts set-home ${provider} ${status.id} <host-home>`,
                 } : {}),
+                ...(provider === "claude" && status.sign_in_state === "expired" ? {
+                    error: "sign_in_expired",
+                    fix_command: `${claudeOpenCommand(status.home, ctx.homedir())} then run /login`,
+                } : {}),
                 ...(provider === "claude" ? {
                     identity: status.identity ?? null,
                     credential_matches_interactive: differs === null ? null : !differs,
@@ -192,7 +199,11 @@ export function createLaneAccountsHandlers(deps) {
         const balanceGateEnabled = true;
         const recentUsageEnabled = await deps.readClaudeAccountBalanceSignalsEnabled(ctx);
         const loads = accountLoadsForReport({ hosts: loaded.snapshots, config, quotaState });
-        const suggestions = planClaudeBalanceMoves({ hosts: loaded.snapshots, config });
+        const suggestions = planClaudeBalanceMoves({
+            hosts: loaded.snapshots,
+            config,
+            laneCompany: (lane) => resolveLaneCompany(hqRoot, lane).company,
+        });
         const selections = loaded.snapshots.map((host) => {
             try {
                 const selection = selectClaudeAccount({
@@ -428,6 +439,7 @@ export function createLaneAccountsHandlers(deps) {
             existsSync: ctx.existsSync,
             hostname,
             probe: ctx.probeProvider,
+            readClaudeCredential: ctx.readClaudeCredential,
             env: ctx.env,
         });
         if (status.logged_in !== true) {
@@ -567,6 +579,7 @@ export function createLaneAccountsHandlers(deps) {
             existsSync: ctx.existsSync,
             hostname: ctx.hostname(),
             probe: ctx.probeProvider,
+            readClaudeCredential: ctx.readClaudeCredential,
             env: ctx.env,
         });
         if (status.logged_in !== true) {
@@ -584,6 +597,7 @@ export function createLaneAccountsHandlers(deps) {
                 existsSync: ctx.existsSync,
                 hostname: ctx.hostname(),
                 probe: ctx.probeProvider,
+                readClaudeCredential: ctx.readClaudeCredential,
                 env: ctx.env,
             }),
         });
@@ -613,6 +627,7 @@ export function createLaneAccountsHandlers(deps) {
                 existsSync: ctx.existsSync,
                 hostname: ctx.hostname(),
                 probe: ctx.probeProvider,
+                readClaudeCredential: ctx.readClaudeCredential,
                 env: ctx.env,
             }),
         });