@indigoai-us/hq-cli 5.103.21 → 5.103.22

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.103.22] — 2026-08-25
+
+### Fixed
+
+- `hq auth login` now points account signup guidance at the canonical `onboarding.hq.computer` host instead of the retired Indigo onboarding domain.
+
 ## [5.103.21] — 2026-08-24
 
 ### Fixed

package/dist/commands/auth.d.ts

@@ -8,7 +8,7 @@
  *   hq auth status    — show whether a valid session is cached + expiry
  *
  * Sign-up is owned by the onboarding web app at
- * https://onboarding.indigo-hq.com. `hq auth login` signs an existing account
+ * https://onboarding.hq.computer. `hq auth login` signs an existing account
  * into this machine by writing ~/.hq/cognito-tokens.json; once cached, the
  * session is kept valid by `hq auth refresh` / `hq-auth-refresh` and consumed
  * by the deploy + sync skills.

package/dist/commands/auth.js

@@ -8,7 +8,7 @@
  *   hq auth status    — show whether a valid session is cached + expiry
  *
  * Sign-up is owned by the onboarding web app at
- * https://onboarding.indigo-hq.com. `hq auth login` signs an existing account
+ * https://onboarding.hq.computer. `hq auth login` signs an existing account
  * into this machine by writing ~/.hq/cognito-tokens.json; once cached, the
  * session is kept valid by `hq auth refresh` / `hq-auth-refresh` and consumed
  * by the deploy + sync skills.
@@ -96,7 +96,7 @@ export function registerAuthCommands(program) {
                 console.error(chalk.dim(callbackPortCollisionGuidance(DEFAULT_COGNITO.port ?? 8765)));
             }
             else {
-                console.error(chalk.dim("  If you do not have an account, sign up at https://onboarding.indigo-hq.com"));
+                console.error(chalk.dim("  If you do not have an account, sign up at https://onboarding.hq.computer"));
             }
             process.exit(1);
         }

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

@@ -156,6 +156,14 @@ export declare function uninstallIntegration(token: string, companyUid: string,
     installationId: string;
     connectionId: string;
 }>;
+/**
+ * Permanently remove a revoked connection tombstone. The admin purge endpoint
+ * deliberately accepts only the connection id: it derives the company and
+ * enforces owner authorization from the authenticated connection record.
+ */
+export declare function purgeConnection(token: string, companyUid: string, connectionId: string): Promise<{
+    connectionId: string;
+}>;
 export interface OAuthStartResult {
     provider: string;
     displayName: string;
@@ -197,6 +205,11 @@ export declare function updateGovernance(token: string, companyUid: string, inpu
     writePolicy?: WritePolicy;
     writeAllowlist: WriteAllowlistGrant[];
 }>;
+/**
+ * Mark or unmark one tool as read-safe. The service owns tool classification:
+ * it refuses attempts to mark write/destructive tools read-safe.
+ */
+export declare function setReadSafe(token: string, companyUid: string, connectionId: string, toolName: string, readSafe: boolean): Promise<void>;
 export interface ConnectionAccess {
     connectionId: string;
     provider: string;

package/dist/commands/integrations-api.js

@@ -74,6 +74,27 @@ export async function uninstallIntegration(token, companyUid, installationId) {
         await raiseForResponse(res, "Failed to disconnect the app");
     return (await res.json());
 }
+/**
+ * Permanently remove a revoked connection tombstone. The admin purge endpoint
+ * deliberately accepts only the connection id: it derives the company and
+ * enforces owner authorization from the authenticated connection record.
+ */
+export async function purgeConnection(token, companyUid, connectionId) {
+    // Keep the company in this client's call signature with the other
+    // connection mutations. It is resolved before the target connection so a
+    // caller cannot use a slug from a different company, but the server's purge
+    // contract intentionally takes only connectionId in its body.
+    void companyUid;
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/admin/purge",
+        method: "POST",
+        body: { connectionId },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to purge the revoked connection");
+    return (await res.json());
+}
 export async function startOAuth(token, companyUid, input) {
     const res = await vaultApiFetch({
         token,
@@ -110,6 +131,20 @@ export async function updateGovernance(token, companyUid, input) {
         await raiseForResponse(res, "Failed to update the app's settings");
     return (await res.json());
 }
+/**
+ * Mark or unmark one tool as read-safe. The service owns tool classification:
+ * it refuses attempts to mark write/destructive tools read-safe.
+ */
+export async function setReadSafe(token, companyUid, connectionId, toolName, readSafe) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/admin/read-safe",
+        method: "POST",
+        body: { companyUid, connectionId, toolName, readSafe },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to update the tool's read-safe setting");
+}
 /**
  * Live open-approval list, read from hq-pro's confirm-queue state (not the
  * audit feed). Unlike the audit-derived reconstruction this replaces, a call

package/dist/commands/integrations-connect.js

@@ -20,7 +20,7 @@ import chalk from "chalk";
 import open from "open";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
-import { IntegrationsCliError, bareProvider, printJson, resolveConnection, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, connectionDomain, printJson, revokedConnectionDetails, resolveConnection, } from "./integrations-core.js";
 import { completeOAuth, discoverDocs, installIntegration, listCatalog, pullBlueprint, startOAuth, } from "./integrations-api.js";
 import { startLoopbackListener } from "./integrations-oauth.js";
 /** hq-pro's machine code for "this endpoint needs a browser sign-in". */
@@ -183,7 +183,7 @@ async function resolveKey(opts, appLabel) {
  * most-specific-first so an explicit flag always wins over the positional
  * argument's heuristics.
  */
-async function resolveTarget(token, companyUid, app, opts) {
+async function resolveTarget(token, companyUid, app, opts, preserveDomain = false) {
     if (opts.docsUrl) {
         const found = await discoverDocs(token, companyUid, opts.docsUrl);
         if (!found.discovery || !found.discoveryReceiptId) {
@@ -222,6 +222,17 @@ async function resolveTarget(token, companyUid, app, opts) {
         // authClass, both of which make the connect cleaner than a raw domain
         // lookup. Missing it is fine — the domain path still works.
         const match = await findCatalogEntry(token, companyUid, app);
+        if (preserveDomain) {
+            // Reviving a revoked connection is keyed by its canonical domain in
+            // hq-pro. A catalog entry id is useful auth metadata, but replacing the
+            // domain with it can create a distinct connection instead of reviving
+            // the original acct_ row.
+            return {
+                ref: { domain: app },
+                ...(match?.authClass ? { authClass: match.authClass } : {}),
+                label: match?.name || app,
+            };
+        }
         return catalogEntryToTarget(match, { ref: { domain: app }, label: app });
     }
     // A bare name (`notion`, `atlassian`) is how the catalog reads to a person —
@@ -424,14 +435,15 @@ async function completeCredentialIfNeeded(token, companyUid, target, opts, resul
     });
 }
 /** Print the outcome of a successful connect. */
-function reportInstall(result, opts) {
+function reportInstall(result, opts, expectedRevivedConnectionId) {
     if (opts.json) {
         printJson(result);
         return;
     }
     const { installation, connection } = result;
     const toolCount = result.mcp?.tools?.length;
-    console.log(chalk.green(`Connected ${chalk.bold(installation.displayName)}`) +
+    const revived = connection.id === expectedRevivedConnectionId;
+    console.log(chalk.green(`${revived ? "Revived" : "Connected"} ${chalk.bold(installation.displayName)}`) +
         (typeof toolCount === "number" ? chalk.dim(` — ${toolCount} tools available`) : ""));
     console.log(chalk.dim(`  connection: ${connection.id}`));
     if (installation.status === "needs_credentials") {
@@ -439,6 +451,49 @@ function reportInstall(result, opts) {
     }
     console.log(chalk.dim(`  Try it: hq integrations tools --provider ${bareProvider(connection.provider)}`));
 }
+/**
+ * The shared `connect <domain>` execution path. Reconnect's revoked fallback
+ * intentionally comes through here rather than re-installing its saved MCP
+ * URL: hq-pro recognizes the domain and revives the revoked row in place.
+ */
+async function connectApp(token, companyUid, app, opts, expectedRevivedConnectionId) {
+    const target = await resolveTarget(token, companyUid, app, opts, expectedRevivedConnectionId !== undefined);
+    const authMode = opts.auth ?? target.authClass;
+    if (authMode === "oauth") {
+        const result = await connectViaOAuth(token, companyUid, target, opts);
+        if (result)
+            reportInstall(result, opts, expectedRevivedConnectionId);
+        return;
+    }
+    // A key is only collected when something already says one is needed, or
+    // the caller supplied one — otherwise a no-auth app would pointlessly
+    // prompt.
+    const wantsKey = authMode === "key" || Boolean(opts.token || opts.tokenStdin);
+    const bearerToken = wantsKey ? await resolveKey(opts, target.label) : undefined;
+    try {
+        const result = await installIntegration(token, companyUid, {
+            ...target.ref,
+            ...(bearerToken
+                ? { authMode: "bearer", bearerToken }
+                : authMode === "none"
+                    ? { authMode: "none" }
+                    : {}),
+        });
+        reportInstall(await completeCredentialIfNeeded(token, companyUid, target, opts, result), opts, expectedRevivedConnectionId);
+    }
+    catch (err) {
+        // Server-authoritative detection: the endpoint turned out to be
+        // OAuth-protected, so run the browser flow instead of making the
+        // caller re-issue the command with --auth oauth.
+        if (isOAuthRequiredError(err)) {
+            const result = await connectViaOAuth(token, companyUid, target, opts);
+            if (result)
+                reportInstall(result, opts, expectedRevivedConnectionId);
+            return;
+        }
+        throw err;
+    }
+}
 export function registerConnectCommands(integrations) {
     integrations
         .command("catalog [query]")
@@ -561,46 +616,11 @@ export function registerConnectCommands(integrations) {
         assertAuthMode(opts.auth);
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
-        const target = await resolveTarget(token, companyUid, app, opts);
-        const authMode = opts.auth ?? target.authClass;
-        if (authMode === "oauth") {
-            const result = await connectViaOAuth(token, companyUid, target, opts);
-            if (result)
-                reportInstall(result, opts);
-            return;
-        }
-        // A key is only collected when something already says one is needed, or
-        // the caller supplied one — otherwise a no-auth app would pointlessly
-        // prompt.
-        const wantsKey = authMode === "key" || Boolean(opts.token || opts.tokenStdin);
-        const bearerToken = wantsKey ? await resolveKey(opts, target.label) : undefined;
-        try {
-            const result = await installIntegration(token, companyUid, {
-                ...target.ref,
-                ...(bearerToken
-                    ? { authMode: "bearer", bearerToken }
-                    : authMode === "none"
-                        ? { authMode: "none" }
-                        : {}),
-            });
-            reportInstall(await completeCredentialIfNeeded(token, companyUid, target, opts, result), opts);
-        }
-        catch (err) {
-            // Server-authoritative detection: the endpoint turned out to be
-            // OAuth-protected, so run the browser flow instead of making the
-            // caller re-issue the command with --auth oauth.
-            if (isOAuthRequiredError(err)) {
-                const result = await connectViaOAuth(token, companyUid, target, opts);
-                if (result)
-                    reportInstall(result, opts);
-                return;
-            }
-            throw err;
-        }
+        await connectApp(token, companyUid, app, opts);
     });
     integrations
         .command("reconnect [app]")
-        .description("Re-authenticate a connected app whose credentials stopped working")
+        .description("Re-authenticate a connected app; use --connect to re-add a revoked app")
         .option("--company <slug>", "Company slug, e.g. indigo")
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
@@ -609,6 +629,7 @@ export function registerConnectCommands(integrations) {
         .option("--auth <mode>", "Force the auth mode: none, key, or oauth (default: detect)")
         .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")
         .option("--json", "Machine-readable output")
         .action(async (app, opts) => {
         // Same validation as `connect`. Without it a typo like `--auth oauth2`
@@ -618,7 +639,23 @@ export function registerConnectCommands(integrations) {
         assertAuthMode(opts.auth);
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
-        const connection = await resolveConnection(token, companyUid, app, opts);
+        const connection = await resolveConnection(token, companyUid, app, opts, {
+            allowSingleRevoked: Boolean(opts.connect),
+        });
+        if (connection.status === "revoked") {
+            const details = revokedConnectionDetails(connection, opts.company);
+            if (!opts.connect) {
+                if (opts.json)
+                    printJson(details);
+                else {
+                    console.log(chalk.yellow(details.reason));
+                    console.log(chalk.yellow(`Re-add it with: ${details.fixPath}`));
+                }
+                return;
+            }
+            await connectApp(token, companyUid, connectionDomain(connection), opts, connection.id);
+            return;
+        }
         const url = connection.installation?.surface?.url;
         if (!url) {
             throw new IntegrationsCliError(`${bareProvider(connection.provider)} was not installed through the app catalog, so it cannot be reconnected from here.`, { expected: true });

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

@@ -74,6 +74,16 @@ export interface AdminConnection {
     };
     installation?: FactoryInstallation | null;
 }
+/**
+ * The actionable state returned instead of attempting to use a revoked
+ * connection. Keep this machine-readable so commands and scripts get the same
+ * recovery path instead of treating a listed row as absent.
+ */
+export interface RevokedConnectionDetails {
+    status: "revoked";
+    reason: string;
+    fixPath: string;
+}
 export interface AdminAuditEvent {
     timestamp: string;
     memberOrAgent: string;
@@ -210,6 +220,14 @@ export declare function selectConnection(connections: AdminConnection[], opts: {
     connection?: string;
     provider?: string;
 }): AdminConnection;
+/**
+ * The hostname re-add needs. Prefer the server's canonical installation domain;
+ * an older row may only retain its MCP URL, and provider is the last-resort
+ * human-safe query when neither was stored.
+ */
+export declare function connectionDomain(connection: AdminConnection): string;
+/** A revoked row is still addressable, but it cannot make a live MCP call. */
+export declare function revokedConnectionDetails(connection: AdminConnection, companySlug?: string): RevokedConnectionDetails;
 /**
  * Resolve a connection the caller named positionally OR through the
  * `--provider` / `--connection` flags. Every management verb takes an optional
@@ -219,6 +237,8 @@ export declare function selectConnection(connections: AdminConnection[], opts: {
 export declare function resolveConnection(token: string, companyUid: string, app: string | undefined, opts: {
     provider?: string;
     connection?: string;
+}, recoveryOpts?: {
+    allowSingleRevoked?: boolean;
 }): Promise<AdminConnection>;
 export declare function callGateway(token: string, params: Record<string, unknown>): Promise<GatewayMessage>;
 /**

package/dist/commands/integrations-core.js

@@ -256,14 +256,26 @@ export function selectConnection(connections, opts) {
     if (opts.provider) {
         const want = opts.provider.trim().toLowerCase();
         const wantHumanSlug = humanSlug(opts.provider);
-        const providerMatch = active.find((c) => bareProvider(c.provider).toLowerCase() === want || c.provider.toLowerCase() === want);
+        // A reconnect normally leaves a revoked historical row alongside its new
+        // active connection. Prefer the active inventory before applying the
+        // provider/name/alias precedence below; fall back to history only when no
+        // active row matches this selector at all. `--connection` above remains
+        // the explicit way to inspect or act on a particular historical row.
+        const activeMatches = connections.filter((c) => c.status !== "revoked" &&
+            (bareProvider(c.provider).toLowerCase() === want ||
+                c.provider.toLowerCase() === want ||
+                c.installation?.displayName?.trim().toLowerCase() === want ||
+                (wantHumanSlug !== "" &&
+                    humanSlug(c.installation?.displayName ?? "") === wantHumanSlug)));
+        const candidates = activeMatches.length > 0 ? activeMatches : connections;
+        const providerMatch = candidates.find((c) => bareProvider(c.provider).toLowerCase() === want || c.provider.toLowerCase() === want);
         if (providerMatch)
             return providerMatch;
-        const displayNameMatch = active.find((c) => c.installation?.displayName?.trim().toLowerCase() === want);
+        const displayNameMatch = candidates.find((c) => c.installation?.displayName?.trim().toLowerCase() === want);
         if (displayNameMatch)
             return displayNameMatch;
         const aliasMatches = wantHumanSlug
-            ? active.filter((c) => {
+            ? candidates.filter((c) => {
                 const displayName = c.installation?.displayName;
                 const displayNameSlug = displayName ? humanSlug(displayName) : "";
                 return displayNameSlug !== "" && displayNameSlug === wantHumanSlug;
@@ -274,7 +286,7 @@ export function selectConnection(connections, opts) {
         if (aliasMatches.length > 1) {
             throw new IntegrationsCliError(`Display-name alias '${opts.provider}' matches multiple connected apps. Use --connection to choose one.`, { expected: true });
         }
-        const available = active.map((c) => bareProvider(c.provider)).join(", ");
+        const available = connections.map((c) => bareProvider(c.provider)).join(", ");
         throw new IntegrationsCliError(`No connected app matches '${opts.provider}'.` +
             (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps with `hq integrations connect <app>`."), { expected: true });
     }
@@ -286,17 +298,59 @@ export function selectConnection(connections, opts) {
     throw new IntegrationsCliError(`Multiple apps are connected — pick one with --provider:\n` +
         active.map((c) => `  --provider ${bareProvider(c.provider)}`).join("\n"), { expected: true });
 }
+/**
+ * The hostname re-add needs. Prefer the server's canonical installation domain;
+ * an older row may only retain its MCP URL, and provider is the last-resort
+ * human-safe query when neither was stored.
+ */
+export function connectionDomain(connection) {
+    const domain = connection.installation?.domain?.trim();
+    if (domain)
+        return domain;
+    const url = connection.installation?.surface?.url;
+    if (url) {
+        try {
+            const host = new URL(url).hostname;
+            if (host)
+                return host;
+        }
+        catch {
+            // The saved endpoint is advisory here. A malformed legacy URL must not
+            // prevent recovery when the provider slug can still be re-added.
+        }
+    }
+    return bareProvider(connection.provider);
+}
+/** A revoked row is still addressable, but it cannot make a live MCP call. */
+export function revokedConnectionDetails(connection, companySlug) {
+    const domain = connectionDomain(connection);
+    return {
+        status: "revoked",
+        reason: "This connection was revoked and cannot be used until it is re-added.",
+        fixPath: `hq integrations connect ${domain}` +
+            (companySlug ? ` --company ${companySlug}` : ""),
+    };
+}
 /**
  * Resolve a connection the caller named positionally OR through the
  * `--provider` / `--connection` flags. Every management verb takes an optional
  * `<app>` argument for ergonomics (`hq integrations policy linear …`), which is
  * matched exactly like `--provider` unless it looks like a connection id.
  */
-export async function resolveConnection(token, companyUid, app, opts) {
+export async function resolveConnection(token, companyUid, app, opts, recoveryOpts = {}) {
     const connections = await fetchConnections(token, companyUid);
     if (app && !opts.provider && !opts.connection) {
         return selectConnection(connections, app.startsWith("acct_") ? { connection: app } : { provider: app });
     }
+    // Normal management verbs deliberately ignore revoked rows for implicit
+    // selection. Reconnect's explicit --connect recovery is the one exception:
+    // a sole revoked row is unambiguous and needs its saved domain to revive.
+    if (recoveryOpts.allowSingleRevoked &&
+        !opts.provider &&
+        !opts.connection &&
+        connections.length === 1) {
+        return connections[0];
+    }
     return selectConnection(connections, opts);
 }
 export async function callGateway(token, params) {

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

@@ -1,6 +1,6 @@
 /**
  * `hq integrations show | policy | grants | grant | ungrant | access | share |
- * unshare | audit | pending | disconnect`.
+ * unshare | audit | pending | disconnect | purge`.
  *
  * The govern-and-remove half of the lifecycle. Two different permission
  * surfaces live here and are easy to confuse, so they get separate verbs:

package/dist/commands/integrations-manage.js

@@ -1,6 +1,6 @@
 /**
  * `hq integrations show | policy | grants | grant | ungrant | access | share |
- * unshare | audit | pending | disconnect`.
+ * unshare | audit | pending | disconnect | purge`.
  *
  * The govern-and-remove half of the lifecycle. Two different permission
  * surfaces live here and are easy to confuse, so they get separate verbs:
@@ -16,8 +16,8 @@ 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, fetchAdminSurface, printJson, resolveConnection, selectConnection, } from "./integrations-core.js";
-import { fetchPendingApprovals, getConnectionAccess, mutateConnectionAccess, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
+import { IntegrationsCliError, bareProvider, 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"];
 /** Plain-English gloss for each write policy, used in every policy readout. */
@@ -97,6 +97,67 @@ function confirm(message) {
 function connectionLabel(connection) {
     return connection.installation?.displayName ?? bareProvider(connection.provider);
 }
+/**
+ * The category of match must mirror `selectConnection`: an exact provider id
+ * takes precedence over a display name, which takes precedence over its human
+ * slug. Unlike ordinary verbs, purge deliberately operates on historical
+ * revoked rows, so it must not inherit selectConnection's active-first policy.
+ */
+function purgeSelectorMatches(connections, selector) {
+    if (selector.connection) {
+        return connections.filter((connection) => connection.id === selector.connection);
+    }
+    if (selector.provider) {
+        const want = selector.provider.trim().toLowerCase();
+        const wantHumanSlug = humanSlug(selector.provider);
+        const providerMatches = connections.filter((connection) => bareProvider(connection.provider).toLowerCase() === want ||
+            connection.provider.toLowerCase() === want);
+        if (providerMatches.length > 0)
+            return providerMatches;
+        const displayNameMatches = connections.filter((connection) => connection.installation?.displayName?.trim().toLowerCase() === want);
+        if (displayNameMatches.length > 0)
+            return displayNameMatches;
+        if (wantHumanSlug) {
+            return connections.filter((connection) => {
+                const displayName = connection.installation?.displayName;
+                return displayName !== undefined && humanSlug(displayName) === wantHumanSlug;
+            });
+        }
+        return [];
+    }
+    return connections;
+}
+function humanSlug(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function purgeSelector(app, opts) {
+    if (app && !opts.provider && !opts.connection) {
+        return app.startsWith("acct_") ? { connection: app } : { provider: app };
+    }
+    return opts;
+}
+async function resolveRevokedPurgeConnection(token, companyUid, app, opts) {
+    const selector = purgeSelector(app, opts);
+    const connections = await fetchConnections(token, companyUid);
+    const matches = purgeSelectorMatches(connections, selector);
+    const revoked = matches.filter((connection) => connection.status === "revoked");
+    if (revoked.length === 1)
+        return revoked[0];
+    if (revoked.length > 1) {
+        const selected = selector.connection ?? selector.provider ?? "the supplied selector";
+        throw new IntegrationsCliError(`Multiple revoked connections match '${selected}'. Use --connection <acct_id> to choose one:\n` +
+            revoked.map((connection) => `  --connection ${connection.id} (${connectionLabel(connection)})`).join("\n"), { expected: true });
+    }
+    if (matches.length > 0) {
+        throw new IntegrationsCliError(`${connectionLabel(matches[0])} is still connected. Disconnect it first, then purge it.`, { expected: true });
+    }
+    // Keep the existing command group's not-found wording and error taxonomy.
+    return selectConnection(connections, selector);
+}
 /**
  * Governance writes are owner-only on hq-pro AND the allowlist PATCH is a
  * whole-list REPLACE. A non-owner reads an identity-redacted grant list, so
@@ -144,7 +205,9 @@ export function registerManageCommands(integrations) {
             ? selectConnection(surface.connections, app.startsWith("acct_") ? { connection: app } : { provider: app })
             : selectConnection(surface.connections, opts);
         if (opts.json) {
-            printJson(connection);
+            printJson(connection.status === "revoked"
+                ? { ...connection, ...revokedConnectionDetails(connection, opts.company) }
+                : connection);
             return;
         }
         const install = connection.installation;
@@ -153,6 +216,11 @@ export function registerManageCommands(integrations) {
         if (install?.id)
             console.log(chalk.dim(`  installation: ${install.id}`));
         console.log(chalk.dim(`  status:      ${connection.status}`));
+        if (connection.status === "revoked") {
+            const details = revokedConnectionDetails(connection, opts.company);
+            console.log(chalk.yellow(`  Revoked — ${details.reason}`));
+            console.log(chalk.yellow(`  Re-add: ${details.fixPath}`));
+        }
         if (install?.domain)
             console.log(chalk.dim(`  domain:      ${install.domain}`));
         if (install?.surface?.url)
@@ -218,6 +286,47 @@ export function registerManageCommands(integrations) {
         }
         console.log(chalk.green(`${connectionLabel(connection)}: ${writePolicy} — ${POLICY_BLURB[writePolicy]}`));
     });
+    integrations
+        .command("read-safe <tool>")
+        .description("Mark a read-only tool as safe to run without approval (owner only)")
+        .option("--company <slug>", "Company slug, e.g. indigo")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .option("--unset", "Remove the read-safe override")
+        .option("--off", "Alias for --unset")
+        .option("--json", "Machine-readable output")
+        .action(async (tool, opts) => {
+        const toolName = tool.trim();
+        if (!toolName) {
+            throw new IntegrationsCliError("Tool name cannot be empty.", { expected: true });
+        }
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = await resolveConnection(token, companyUid, undefined, opts);
+        const readSafe = !(opts.unset || opts.off);
+        try {
+            await setReadSafe(token, companyUid, connection.id, toolName, readSafe);
+        }
+        catch (error) {
+            if (error instanceof IntegrationsCliError) {
+                if (error.status === 403) {
+                    throw new IntegrationsCliError("This command is owner only. Ask a company owner to manage read-safe tools.", { expected: true });
+                }
+                if (readSafe && (error.status === 409 || error.status === 422)) {
+                    throw new IntegrationsCliError(`${toolName} is a write tool and can't be marked read-safe (its changes always need approval).`, { expected: true });
+                }
+            }
+            throw error;
+        }
+        const outcome = { connectionId: connection.id, toolName, readSafe };
+        if (opts.json) {
+            printJson(outcome);
+            return;
+        }
+        console.log(chalk.green(readSafe
+            ? `${toolName} on ${connectionLabel(connection)} is now read-safe and skips approval.`
+            : `${toolName} on ${connectionLabel(connection)} is no longer read-safe; its override was removed.`));
+    });
     integrations
         .command("grants [app]")
         .description("Show who is authorized to run an app's change-making tools")
@@ -518,6 +627,52 @@ export function registerManageCommands(integrations) {
         }
         console.log(chalk.green(`Disconnected ${connectionLabel(connection)}.`));
     });
+    integrations
+        .command("purge [app]")
+        .description("Permanently remove a revoked connection from the list (owner only)")
+        .option("--company <slug>", "Company slug, e.g. indigo")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .option("--yes", "Skip the permanent-removal confirmation prompt")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = await resolveRevokedPurgeConnection(token, companyUid, app, opts);
+        const label = connectionLabel(connection);
+        if (!opts.yes) {
+            // Warning + prompt go to stderr: with --json, stdout must stay parseable.
+            console.error(`Purging ${chalk.bold(label)} permanently removes its revoked connection record. It cannot be restored.`);
+            const ok = await confirm(`Permanently purge ${label}?`);
+            if (!ok) {
+                // A non-TTY run lands here too: refusing is the only safe default
+                // when nobody can confirm a permanent deletion.
+                throw new IntegrationsCliError("Not purged. Re-run with --yes if you are sure.", { expected: true });
+            }
+        }
+        try {
+            await purgeConnection(token, companyUid, connection.id);
+        }
+        catch (error) {
+            if (error instanceof IntegrationsCliError && error.status === 409) {
+                throw new IntegrationsCliError(`${label} is still connected. Disconnect it first, then purge it.`, { expected: true, status: 409, code: error.code });
+            }
+            if (error instanceof IntegrationsCliError && error.status === 403) {
+                throw new IntegrationsCliError("Purging a connection is owner only. Ask a company owner to run this.", { expected: true, status: 403, code: error.code });
+            }
+            throw error;
+        }
+        const outcome = {
+            connectionId: connection.id,
+            provider: bareProvider(connection.provider),
+            status: "purged",
+        };
+        if (opts.json) {
+            printJson(outcome);
+            return;
+        }
+        console.log(chalk.green(`Purged ${label}. It will no longer appear in \`hq integrations list\`.`));
+    });
 }
 /** Order-insensitive identity of an allowlist, for change detection. */
 export function allowlistFingerprint(grants) {

package/dist/commands/integrations.d.ts

@@ -26,10 +26,12 @@
  *
  * Govern and remove:
  *   hq integrations policy [app] --set <m>   Approval setting for changes.
+ *   hq integrations read-safe <tool>          Mark/unmark a trusted read-only tool.
  *   hq integrations grants|grant|ungrant     Per-tool authorization to run change-making tools.
  *   hq integrations access|share|unshare     Who may use the app.
  *   hq integrations audit                    Recent activity.
  *   hq integrations disconnect [app]         Remove it and its credentials.
+ *   hq integrations purge [app]              Permanently remove a revoked connection row.
  *
  * Governance: reads flow freely; calls that can change the app are subject to
  * the connection's write policy (default: a person approves first). A queued

package/dist/commands/integrations.js

@@ -26,10 +26,12 @@
  *
  * Govern and remove:
  *   hq integrations policy [app] --set <m>   Approval setting for changes.
+ *   hq integrations read-safe <tool>          Mark/unmark a trusted read-only tool.
  *   hq integrations grants|grant|ungrant     Per-tool authorization to run change-making tools.
  *   hq integrations access|share|unshare     Who may use the app.
  *   hq integrations audit                    Recent activity.
  *   hq integrations disconnect [app]         Remove it and its credentials.
+ *   hq integrations purge [app]              Permanently remove a revoked connection row.
  *
  * Governance: reads flow freely; calls that can change the app are subject to
  * the connection's write policy (default: a person approves first). A queued
@@ -50,11 +52,65 @@ 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, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, 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";
 export { IntegrationsCliError, callGateway, fetchConnections, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
+/**
+ * Gateway metadata is additive and may be absent when talking to an older
+ * gateway. Parse it defensively so an unknown or malformed value never breaks
+ * tool discovery.
+ */
+function effectiveToolMode(tool) {
+    const raw = tool._meta?.["hq/effective-mode"];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const mode = raw.mode;
+    const approvalRequired = raw.approvalRequired;
+    if ((mode !== "read" && mode !== "write") || typeof approvalRequired !== "boolean") {
+        return null;
+    }
+    const denied = raw.denied;
+    const policy = raw.policy;
+    return {
+        mode,
+        approvalRequired,
+        ...(denied === true ? { denied: true } : {}),
+        ...(policy === "deny" ? { policy: "deny" } : {}),
+    };
+}
+function toolBadge(tool) {
+    const effectiveMode = effectiveToolMode(tool);
+    if (!effectiveMode)
+        return null;
+    if (effectiveMode.mode === "read")
+        return "read";
+    if (effectiveMode.denied)
+        return "denied";
+    return effectiveMode.approvalRequired ? "approval-required" : "write";
+}
+function formatToolBadge(tool) {
+    const badge = toolBadge(tool);
+    if (!badge)
+        return "";
+    const label = `[${badge}]`;
+    switch (badge) {
+        case "read":
+            return chalk.green(label);
+        case "approval-required":
+            return chalk.yellow(label);
+        case "denied":
+            return chalk.red(label);
+        case "write":
+            return chalk.blue(label);
+    }
+}
+/** Add gateway policy metadata where scripts can consume it directly. */
+function toolJsonView(tool) {
+    const effectiveMode = effectiveToolMode(tool);
+    return effectiveMode ? { ...tool, effectiveMode } : tool;
+}
 /**
  * The gateway relays MCP tool schemas verbatim. Keep the default listing
  * compact, but make required inputs visible before a caller has to discover
@@ -86,6 +142,23 @@ function printToolSchema(tool) {
     console.log(chalk.dim("  Input schema:"));
     console.log(chalk.dim(schema.split("\n").map((line) => `  ${line}`).join("\n")));
 }
+function reportRevokedConnection(connection, opts) {
+    if (connection.status !== "revoked")
+        return false;
+    const details = revokedConnectionDetails(connection, opts.company);
+    if (opts.json) {
+        printJson(details);
+    }
+    else {
+        console.log(chalk.yellow(`${connectionLabel(connection)}: status=revoked`));
+        console.log(chalk.yellow(`  ${details.reason}`));
+        console.log(`  Re-add: ${details.fixPath}`);
+    }
+    if (opts.fail) {
+        throw new IntegrationsCliError(`status=revoked. ${details.reason} Re-add with: ${details.fixPath}`, { expected: true });
+    }
+    return true;
+}
 export function registerIntegrationsCommand(program) {
     const integrations = program
         .command("integrations")
@@ -132,6 +205,8 @@ export function registerIntegrationsCommand(program) {
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
         const connection = selectConnection(await fetchConnections(token, companyUid), opts);
+        if (reportRevokedConnection(connection, opts))
+            return;
         const prefix = toolPrefixForProvider(connection.provider);
         const message = await callGateway(token, {
             companyUid,
@@ -154,24 +229,26 @@ export function registerIntegrationsCommand(program) {
                 throw new IntegrationsCliError(`No tool named '${opts.describe}' on ${connectionLabel(connection)}.`, { expected: true });
             }
             if (opts.json) {
-                printJson(tool);
+                printJson(toolJsonView(tool));
                 return;
             }
-            console.log(`${chalk.bold(tool.name)}  ${chalk.dim(`on ${connectionLabel(connection)}`)}`);
+            const badge = formatToolBadge(tool);
+            console.log(`${chalk.bold(tool.name)}${badge ? `  ${badge}` : ""}  ${chalk.dim(`on ${connectionLabel(connection)}`)}`);
             if (tool.description)
                 console.log(chalk.dim(`  ${tool.description}`));
             printToolSchema(tool);
             return;
         }
         if (opts.json) {
-            printJson(payload);
+            printJson({ ...payload, tools: tools.map(toolJsonView) });
             return;
         }
         console.log(chalk.dim(`App: ${connectionLabel(connection)}`));
         for (const tool of tools) {
             const label = tool.title && tool.title !== tool.name ? `  ${chalk.dim(tool.title)}` : "";
             const required = requiredInputHint(tool.inputSchema);
-            console.log(`${chalk.bold(tool.name)}${label}${required ? `  ${chalk.dim(required)}` : ""}`);
+            const badge = formatToolBadge(tool);
+            console.log(`${chalk.bold(tool.name)}${badge ? `  ${badge}` : ""}${label}${required ? `  ${chalk.dim(required)}` : ""}`);
         }
         console.log(chalk.dim(`\n${tools.length} tools. Describe inputs: hq integrations tools --provider ${bareProvider(connection.provider)} --describe <tool>\nCall one with: hq integrations call <tool> --provider ${bareProvider(connection.provider)} --args '<json>'`));
     });
@@ -199,6 +276,8 @@ export function registerIntegrationsCommand(program) {
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
         const connection = selectConnection(await fetchConnections(token, companyUid), opts);
+        if (reportRevokedConnection(connection, { ...opts, fail: true }))
+            return;
         const prefix = toolPrefixForProvider(connection.provider);
         const idempotencyKey = opts.idempotencyKey ?? `hq-cli-${randomUUID()}`;
         const message = await callGateway(token, {

package/package.json

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