@indigoai-us/hq-cli 5.103.26 → 5.103.28

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.103.28] — 2026-08-28
+
+## [5.103.27] — 2026-08-28
+
 ## [5.103.26] — 2026-08-27
 
 ### Changed

package/dist/commands/dm.js

@@ -272,15 +272,11 @@ async function runGroupSend(recipients, message) {
         for (const r of recipients) {
             const rc = detectRecipient(r);
             if (!rc) {
-                console.error(chalk.red(`Invalid recipient '${r}': each must be an email address or a personUid (prs_…).`));
-                process.exit(1);
-            }
-            // Group DMs are channels — agents don't participate in channels (their
-            // DM surface is 1:1 via the durable box inbox). DM an agent directly.
-            if (rc.toPersonUid?.startsWith("agt_")) {
-                console.error(chalk.red(`Agents can't join group DMs yet — DM '${r}' directly: hq dm ${r} "<message>".`));
+                console.error(chalk.red(`Invalid recipient '${r}': each must be an email address, a personUid (prs_…), or an agentUid (agt_…).`));
                 process.exit(1);
             }
+            // People (prs_) and agents (agt_) are both valid group participants —
+            // the server (handleCreateGroupDm) accepts agt_* uids like any other.
             participants.push(rc.toEmail ?? rc.toPersonUid);
         }
         if (participants.length < 2) {

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

@@ -8,6 +8,7 @@
  * Sentry live in exactly one place. `integrations.ts` re-exports this module's
  * public surface, so existing importers keep working unchanged.
  */
+export { bareProvider } from "../lib/integrations/provider-slug.js";
 /** Write policy on a connection — mirrors hq-pro's `WritePolicy`. */
 export type WritePolicy = "auto-allow" | "confirm" | "deny";
 /** Who a grant points at — mirrors hq-pro's `AclGranteeType`. */
@@ -199,8 +200,6 @@ export declare function raiseIfUnauthorized(res: Response): void;
 export declare function raiseForResponse(res: Response, fallback: string): Promise<never>;
 /** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
 export declare function toolPrefixForProvider(provider: string): string;
-/** "factory:linear" → "linear", for display and for `--provider` echoes. */
-export declare function bareProvider(provider: string): string;
 /**
  * Read the whole admin surface: connections with their governance state, the
  * viewer's role, and the recent audit feed. Several verbs need more than the
@@ -264,5 +263,18 @@ interface QueuedOutcome {
 }
 export declare function queuedOutcome(payload: unknown): QueuedOutcome | null;
 export declare function printJson(value: unknown): void;
-export {};
+/**
+ * Print why a connection is unusable and how to repair it, directly beneath its
+ * status line.
+ *
+ * `list` and `show` used to print a bare `error`, leaving the diagnosis the
+ * control plane had already sent reachable only through a separate `hq doctor`
+ * run. Classification is shared with that check rather than duplicated, so the
+ * two surfaces cannot drift into disagreeing about the same row.
+ *
+ * Healthy and revoked rows print nothing: revoked tombstones carry their own
+ * re-add wording, and a repair path printed against a working connection sends
+ * a user to fix something that is not broken.
+ */
+export declare function printHealthNotice(connection: AdminConnection): void;
 //# sourceMappingURL=integrations-core.d.ts.map

package/dist/commands/integrations-core.js

@@ -9,9 +9,13 @@
  * public surface, so existing importers keep working unchanged.
  */
 import { randomUUID } from "node:crypto";
+import chalk from "chalk";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { AuthError } from "../utils/auth-error.js";
 import { redactErrorText } from "../utils/redact-error-text.js";
+import { connectionHealthNotice } from "../lib/integrations/health.js";
+import { bareProvider } from "../lib/integrations/provider-slug.js";
+export { bareProvider } from "../lib/integrations/provider-slug.js";
 export class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -196,9 +200,6 @@ export function toolPrefixForProvider(provider) {
         .replace(/[^a-z0-9]+/g, ".");
 }
 /** "factory:linear" → "linear", for display and for `--provider` echoes. */
-export function bareProvider(provider) {
-    return provider.replace(/^factory:/, "");
-}
 /** Turn a factory display name into the human-friendly slug people type. */
 function humanSlug(value) {
     return value
@@ -441,4 +442,25 @@ export function queuedOutcome(payload) {
 export function printJson(value) {
     console.log(JSON.stringify(value, null, 2));
 }
+/**
+ * Print why a connection is unusable and how to repair it, directly beneath its
+ * status line.
+ *
+ * `list` and `show` used to print a bare `error`, leaving the diagnosis the
+ * control plane had already sent reachable only through a separate `hq doctor`
+ * run. Classification is shared with that check rather than duplicated, so the
+ * two surfaces cannot drift into disagreeing about the same row.
+ *
+ * Healthy and revoked rows print nothing: revoked tombstones carry their own
+ * re-add wording, and a repair path printed against a working connection sends
+ * a user to fix something that is not broken.
+ */
+export function printHealthNotice(connection) {
+    const notice = connectionHealthNotice(connection);
+    if (!notice)
+        return;
+    console.log(chalk.yellow(`  ${notice.headline}`));
+    if (notice.remediation)
+        console.log(chalk.yellow(`  ${notice.remediation}`));
+}
 //# sourceMappingURL=integrations-core.js.map

package/dist/commands/integrations-manage.js

@@ -16,7 +16,7 @@ import readline from "node:readline";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
-import { IntegrationsCliError, bareProvider, fetchConnections, fetchAdminSurface, printJson, revokedConnectionDetails, resolveConnection, selectConnection, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, printHealthNotice, fetchConnections, fetchAdminSurface, printJson, revokedConnectionDetails, resolveConnection, selectConnection, } from "./integrations-core.js";
 import { fetchPendingApprovals, getConnectionAccess, mutateConnectionAccess, purgeConnection, setReadSafe, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
 const WRITE_POLICIES = ["auto-allow", "confirm", "deny"];
 const PERMISSIONS = ["read", "write", "admin"];
@@ -238,6 +238,9 @@ export function registerManageCommands(integrations) {
         if (install?.status === "needs_credentials") {
             console.log(chalk.yellow("  Needs sign-in — run `hq integrations reconnect` to fix it."));
         }
+        // Last, so the diagnosis and its fix path are the final thing on screen
+        // rather than buried above the sharing and ownership lines.
+        printHealthNotice(connection);
     });
     integrations
         .command("policy [app]")

package/dist/commands/integrations.js

@@ -52,7 +52,7 @@ import { randomUUID } from "node:crypto";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, revokedConnectionDetails, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printHealthNotice, printJson, 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";
@@ -190,6 +190,7 @@ export function registerIntegrationsCommand(program) {
                 .join(" · ");
             console.log(`${chalk.bold(connectionLabel(c))}  ${chalk.dim(flags)}`);
             console.log(chalk.dim(`  connection: ${c.id}`));
+            printHealthNotice(c);
         }
     });
     registerImportCommands(integrations);

package/dist/lib/doctor/checks/integrations.d.ts

@@ -7,41 +7,26 @@
  * stored health signals only: a recorded rejection overrides a misleading
  * `connected` status, but a clean connected row is not live-provider proof.
  */
-import { type AdminConnection } from "../../../commands/integrations-core.js";
+import { type IntegrationConnection } from "../../integrations/health.js";
 import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+/**
+ * Health classification is shared with `hq integrations list`/`show` and lives
+ * in `lib/integrations/health.ts`. Re-exported here so the doctor family stays
+ * the single import surface for callers that already depend on it.
+ */
+export { classifyConnection } from "../../integrations/health.js";
+export type { IntegrationConnection } from "../../integrations/health.js";
 export declare const INTEGRATIONS_FAMILY_ID = "integrations";
 export declare const INTEGRATIONS_PREFIX = "integrations";
-/** Additive health fields returned by newer control planes. */
-export interface IntegrationConnection extends AdminConnection {
-    errorReason?: string;
-    degradedReason?: string;
-    needsReauthReason?: string;
-    /** Server-derived remediation flow; optional for older control planes. */
-    fix_path?: string;
-    /** Server-derived remediation class; optional for older control planes. */
-    fix_kind?: string;
-}
 export interface IntegrationsDoctorDeps {
     ensureToken?: () => Promise<string>;
     resolveCompany?: (token: string, company: string | undefined) => Promise<string>;
     listConnections?: (token: string, companyUid: string) => Promise<IntegrationConnection[]>;
 }
-type FindingKind = "reconnect" | "re-add" | "contact-admin" | "provider-blocked" | "retryable" | "hq-configuration";
-interface Finding {
-    provider: string;
-    connectionId: string;
-    kind: FindingKind;
-    message: string;
-    /** Optional HQ-authored remediation returned by the control plane. */
-    remediation?: string;
-}
 /**
  * Expected session/company prerequisites degrade to NA instead of crashing or
  * becoming a false connection failure. An unreadable inventory remains UNKNOWN.
  */
 export declare function checkIntegrations(context: CheckContext, deps?: IntegrationsDoctorDeps): Promise<CheckResult[]>;
-/** Classify without echoing untrusted provider text, which may contain secrets. */
-export declare function classifyConnection(connection: IntegrationConnection): Finding[];
 export declare const integrationsFamily: CheckFamily;
-export {};
 //# sourceMappingURL=integrations.d.ts.map

package/dist/lib/doctor/checks/integrations.js

@@ -11,20 +11,16 @@ import { ensureCognitoIdToken } from "../../../utils/cognito-session.js";
 import { isAuthError } from "../../../utils/auth-error.js";
 import { isCompanySelectionError } from "../../../utils/company-selection-error.js";
 import { getCompanyUid } from "../../../utils/vault-api.js";
-import { bareProvider, fetchConnections, IntegrationsCliError, } from "../../../commands/integrations-core.js";
+import { fetchConnections, IntegrationsCliError } from "../../../commands/integrations-core.js";
+import { classifyConnection } from "../../integrations/health.js";
+/**
+ * Health classification is shared with `hq integrations list`/`show` and lives
+ * in `lib/integrations/health.ts`. Re-exported here so the doctor family stays
+ * the single import surface for callers that already depend on it.
+ */
+export { classifyConnection } from "../../integrations/health.js";
 export const INTEGRATIONS_FAMILY_ID = "integrations";
 export const INTEGRATIONS_PREFIX = "integrations";
-const RECONNECT_REASON_CODES = new Set([
-    "oauth_refresh_invalid_grant",
-    "oauth_refresh_unavailable",
-    "token_refresh_failed",
-    "credentials_rejected",
-]);
-const RETRYABLE_REASON_CODES = new Set([
-    "oauth_refresh_transient",
-    "oauth_refresh_write_conflict",
-]);
-const HQ_CONFIGURATION_REASON_CODE = "oauth_client_secret_unavailable";
 /**
  * Expected session/company prerequisites degrade to NA instead of crashing or
  * becoming a false connection failure. An unreadable inventory remains UNKNOWN.
@@ -93,144 +89,6 @@ export async function checkIntegrations(context, deps = {}) {
     }
     return groupFindings(findings, context.company);
 }
-/** Classify without echoing untrusted provider text, which may contain secrets. */
-export function classifyConnection(connection) {
-    if (connection.status === "revoked")
-        return [];
-    const provider = bareProvider(connection.provider);
-    const reason = recordedReason(connection);
-    const connectedWithRecordedFailure = connection.status === "connected" && reason !== "";
-    const knownReasonCode = knownReasonCodeFor(connection);
-    if (knownReasonCode) {
-        const finding = findingForKnownReasonCode(connection, provider, knownReasonCode);
-        // Retryable and HQ-configuration reason codes diagnose conditions that a
-        // caller-specific remediation cannot change. Reconnect-class codes defer
-        // to the server's credential/role-aware remediation classification.
-        return [withServerRemediation(connection, RECONNECT_REASON_CODES.has(knownReasonCode)
-                ? findingForServerFixKind(finding, connection.fix_kind)
-                : finding)];
-    }
-    // A stale remediation value does not make a clean connected row unhealthy.
-    if (!connectedWithRecordedFailure && connection.status === "connected")
-        return [];
-    if (isProviderBlocked(reason) || connection.status === "degraded") {
-        return [withServerRemediation(connection, {
-                provider,
-                connectionId: connection.id,
-                kind: "provider-blocked",
-                message: connectedWithRecordedFailure
-                    ? "reports connected, but recorded provider health says access is blocked upstream"
-                    : "provider-side access is blocked or unavailable",
-            })];
-    }
-    const fallback = genericReconnectFinding(connection, provider);
-    const serverClassified = findingForServerFixKind(fallback, connection.fix_kind);
-    if (serverClassified.kind !== "reconnect") {
-        return [withServerRemediation(connection, serverClassified)];
-    }
-    if (isTokenRefreshFailure(reason) || isCredentialFailure(reason)) {
-        const problem = isTokenRefreshFailure(reason)
-            ? "token refresh failed"
-            : connectedWithRecordedFailure
-                ? "reports connected, but the provider rejected the stored credentials"
-                : "the provider rejected the stored credentials";
-        return [withServerRemediation(connection, {
-                provider,
-                connectionId: connection.id,
-                kind: "reconnect",
-                message: problem,
-            })];
-    }
-    if (connection.status === "needs-reauth" || connection.status === "error") {
-        return [withServerRemediation(connection, fallback)];
-    }
-    if (connection.status !== "connected") {
-        return [withServerRemediation(connection, {
-                provider,
-                connectionId: connection.id,
-                kind: "reconnect",
-                message: `reports an unrecognized non-healthy status (${connection.status})`,
-            })];
-    }
-    return [];
-}
-function genericReconnectFinding(connection, provider) {
-    return {
-        provider,
-        connectionId: connection.id,
-        kind: "reconnect",
-        message: connection.status === "needs-reauth"
-            ? "needs re-authentication"
-            : "is in an error state",
-    };
-}
-/** Only values emitted by hq-pro affect the classification; future values fall back. */
-function findingForServerFixKind(fallback, fixKind) {
-    switch (fixKind) {
-        case "re-add":
-            return {
-                ...fallback,
-                kind: "re-add",
-                message: "requires its API key to be re-entered",
-            };
-        case "contact-admin":
-            return {
-                ...fallback,
-                kind: "contact-admin",
-                message: "must be repaired by a company owner or admin",
-            };
-        case "reconnect":
-        default:
-            return fallback;
-    }
-}
-/**
- * A fix path is server-authored, role- and credential-aware wording. It cannot
- * make a connection unhealthy: the caller must first have classified a health
- * signal, so a stale fix path on an otherwise clean connected row is ignored.
- */
-function withServerRemediation(connection, finding) {
-    return connection.fix_path
-        ? { ...finding, remediation: connection.fix_path }
-        : finding;
-}
-/**
- * These are a closed hq-pro contract. Exact matching deliberately comes before
- * the legacy text heuristics, which remain below for old and unknown rows.
- */
-function knownReasonCodeFor(connection) {
-    return [connection.errorReason, connection.needsReauthReason, connection.degradedReason]
-        .find((value) => (typeof value === "string" &&
-        (RECONNECT_REASON_CODES.has(value) ||
-            RETRYABLE_REASON_CODES.has(value) ||
-            value === HQ_CONFIGURATION_REASON_CODE)));
-}
-function findingForKnownReasonCode(connection, provider, code) {
-    if (RECONNECT_REASON_CODES.has(code)) {
-        return {
-            provider,
-            connectionId: connection.id,
-            kind: "reconnect",
-            message: "stored credentials need re-authentication",
-        };
-    }
-    if (RETRYABLE_REASON_CODES.has(code)) {
-        return {
-            provider,
-            connectionId: connection.id,
-            kind: "retryable",
-            message: code === "oauth_refresh_write_conflict"
-                ? "token refresh lost a concurrent write race; the stored credential remains intact"
-                : "token refresh is temporarily unavailable; the stored credential remains intact",
-        };
-    }
-    return {
-        provider,
-        connectionId: connection.id,
-        kind: "hq-configuration",
-        message: "the HQ OAuth client secret is unavailable",
-    };
-}
 function groupFindings(findings, company) {
     const groups = new Map();
     for (const finding of findings) {
@@ -288,6 +146,15 @@ function resultForGroup(entries, company) {
             ...(serverRemediation ? { remediation: serverRemediation } : {}),
         };
     }
+    if (first.kind === "wait") {
+        return {
+            status: "WARN",
+            checkId: `${INTEGRATIONS_PREFIX}.wait.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}. Wait for it to complete, then retry the operation.`,
+            remediation: serverRemediation ?? "Wait for the Factory installation to complete, then retry the operation.",
+        };
+    }
     if (first.kind === "hq-configuration") {
         return {
             status: "FAIL",
@@ -298,6 +165,36 @@ function resultForGroup(entries, company) {
         };
     }
     const companyArg = company ? ` --company ${company}` : "";
+    if (first.kind === "undiagnosed") {
+        // The control plane reported a fault and explained none of it. Printing the
+        // reconnect command here would be the same guess `classifyConnection`
+        // refuses to make: it may cost the reader a working credential and, when it
+        // does not help, leaves them with nothing else to try. Name what HQ knows,
+        // point at the one command that can show more, and let a human decide.
+        //
+        // One `show` per listed connection, not just the first. Grouping keys on
+        // the message, and every undiagnosed row carries the same HQ-authored
+        // message whatever its unrecognized reason code was — so a single command
+        // would leave the rest of the group uninspected with their differing
+        // hidden reasons unread. `show` resolves exactly one connection.
+        const inspect = preview
+            .map((id) => `hq integrations show --connection ${id}${companyArg}`)
+            .join("; ");
+        return {
+            status: "FAIL",
+            checkId: `${INTEGRATIONS_PREFIX}.undiagnosed.${first.provider}`,
+            target: namedConnections,
+            // The caution belongs only where nothing supplied a fix. With a
+            // server-authored remediation printed below, warning that reconnecting
+            // may not help would contradict the very instruction being given.
+            message: serverRemediation
+                ? `${first.provider}: ${count} ${plural} ${first.message}.`
+                : `${first.provider}: ${count} ${plural} ${first.message}. HQ has no diagnosis for this, so reconnecting may not be the fix.`,
+            remediation: serverRemediation ?? (overflow > 0
+                ? `Inspect the listed connections, then repeat for the remaining ${overflow}: ${inspect}`
+                : inspect),
+        };
+    }
     const remediation = preview
         .map((id) => `hq integrations reconnect --connection ${id}${companyArg}`)
         .join("; ");

package/dist/lib/integrations/health.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Connection health classification, shared by every surface that has to explain
+ * why an integration is not usable.
+ *
+ * This lived inside the `hq doctor` integrations check until `list`/`show` had
+ * to answer the same question. It is deliberately presentation-free and makes
+ * no network calls: it classifies stored health signals only, so a caller can
+ * render a finding without deciding what the underlying codes mean. Keeping one
+ * copy is the point — `hq doctor` and `hq integrations show` disagreeing about
+ * whether a row needs a reconnect is exactly the confusion this family exists
+ * to remove.
+ *
+ * It never echoes untrusted provider text: upstream messages can carry tokens or
+ * secret-bearing URLs, so every user-visible string here is HQ-authored, and the
+ * only externally-sourced string that reaches a user is the server's own
+ * `fix_path`.
+ */
+import type { AdminConnection } from "../../commands/integrations-core.js";
+/** Additive health fields returned by newer control planes. */
+export interface IntegrationConnection extends AdminConnection {
+    errorReason?: string;
+    degradedReason?: string;
+    needsReauthReason?: string;
+    /** Server-derived remediation flow; optional for older control planes. */
+    fix_path?: string;
+    /** Server-derived remediation class; optional for older control planes. */
+    fix_kind?: string;
+}
+/**
+ * Remediation class — WHO has to act and WHAT they have to do.
+ *
+ * `undiagnosed` is the console's twin member (`_connection-health.ts` `FixKind`)
+ * and lands here to close that divergence. Before it, an unhealthy row the
+ * server described with neither a recognised reason code NOR a `fix_kind` fell
+ * back to `reconnect`, so `hq doctor` told a person to sign in again on the
+ * strength of no diagnosis at all — advice that can make them discard a
+ * credential that was never the problem, and that leaves them no better off
+ * when it does not help. An admission is more useful than a guess.
+ *
+ * A server that DID say `fix_kind: "reconnect"` still classifies as
+ * `reconnect`: that is a diagnosis, not an absence of one.
+ */
+export type FindingKind = "reconnect" | "re-add" | "contact-admin" | "wait" | "provider-blocked" | "retryable" | "hq-configuration" | "undiagnosed";
+export interface Finding {
+    provider: string;
+    connectionId: string;
+    kind: FindingKind;
+    message: string;
+    /** Optional HQ-authored remediation returned by the control plane. */
+    remediation?: string;
+}
+/** Classify without echoing untrusted provider text, which may contain secrets. */
+export declare function classifyConnection(connection: IntegrationConnection): Finding[];
+/**
+ * What a human should be told about one unhealthy connection.
+ *
+ * `null` means there is nothing to say: the row is healthy, or it is a revoked
+ * tombstone, which every surface already explains through its own re-add path.
+ */
+export interface ConnectionHealthNotice {
+    kind: FindingKind;
+    /** HQ-authored, provider-prefixed sentence — safe to print verbatim. */
+    headline: string;
+    /** The server's role- and credential-aware fix path, when it sent one. */
+    remediation?: string;
+}
+/**
+ * A status alone ("error") tells a user nothing they can act on. The control
+ * plane already sends the diagnosis and the fix path on every non-healthy row;
+ * this turns those into the two lines a surface should print next to the status.
+ *
+ * Revoked rows return `null` on purpose. They are tombstones rather than broken
+ * connections, and `revokedConnectionDetails` already produces the correct
+ * re-add wording for them — classifying them here would print two competing
+ * recovery paths for the same row.
+ */
+export declare function connectionHealthNotice(connection: IntegrationConnection): ConnectionHealthNotice | null;
+//# sourceMappingURL=health.d.ts.map