@indigoai-us/hq-cli 5.103.20 → 5.103.22

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [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
+
+- `hq agents jobs list|pause|cancel` now fails closed on an agent box instead of
+  provoking a cross-agent rejection on the server. These off-box operator
+  commands are reachable on agent boxes, where the CLI authenticates with the
+  box's own agent machine identity; forwarding another agent's identifier into
+  `GET /v1/agents/{uid}/jobs` was refused server-side by hq-pro's self-only jobs
+  guard and logged as an unexpected warning, while the CLI mislabeled the 403 as
+  "You need owner/admin on this company." — a role problem a box can never
+  satisfy. The commands now resolve the agent reference through the company
+  roster (a slug or name becomes an `agt_` uid, or fails locally), and refuse a
+  cross-agent target before any request leaves the box, naming the on-box
+  `hq-agent-jobs` tool and the person session required to manage another agent's
+  jobs. A server-side `CROSS_AGENT_JOB` denial is now rendered as identity-scoped
+  guidance rather than the owner/admin copy. Separately, every authenticated
+  vault-API request now carries an `x-hq-client-name` header so its origin is
+  attributable in telemetry and error reports. (Sentry 7617401436)
+
 ## [5.103.20] — 2026-08-24
 
 ### Changed

package/dist/commands/agents.d.ts

@@ -267,6 +267,29 @@ export interface DmThreadMessage {
  * membership).
  */
 export declare function resolveAgentUid(token: string, ref: string, companySlug: string | undefined): Promise<string>;
+/**
+ * Fail-closed local guard for the off-box `hq agents jobs` operator commands.
+ *
+ * hq-pro's jobs endpoints are self-only for an agent machine identity: an
+ * agent-authenticated list/pause/cancel against `/v1/agents/{uid}/jobs` whose
+ * `{uid}` is not the caller's OWN agt_ uid is refused server-side as 403
+ * `CROSS_AGENT_JOB` and logged loud (`caller_uid_mismatch`, Sentry hq-pro
+ * 7617401436). That happens when these commands are run ON an agent box, where
+ * {@link resolveVaultCredential} silently returns the box's own agent ID token —
+ * the operator meant to act as a person with owner/admin, not as the box.
+ *
+ * Catch it locally so the call never leaves the box: decode the (already
+ * locally trusted, signature-unverified) bearer token and, ONLY when it proves
+ * an agent identity acting on a DIFFERENT agent, return a refusal string for the
+ * command to print before any HTTP request. Every other shape fails OPEN
+ * (returns `null`) and proceeds to the server exactly as today: a person session
+ * (no `custom:entityType` claim), an opaque / non-JWT credential (an `hqk_` API
+ * key), a token with a missing or malformed uid claim, or an agent acting on its
+ * OWN jobs.
+ *
+ * Pure: no network, no logging; never prints or returns the token itself.
+ */
+export declare function crossAgentJobsRefusal(token: string, resolvedAgentUid: string): string | null;
 /** Send a DM to an agent. Returns nothing meaningful beyond success. */
 export declare function sendAgentDm(token: string, agentUid: string, message: string): Promise<void>;
 /** Read the two-way DM conversation with an agent (most recent `limit`). */

package/dist/commands/agents.js

@@ -30,6 +30,7 @@ import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { peekIdToken } from "../utils/id-token.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { confirmChargeOrExit, formatUsd, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
@@ -345,6 +346,17 @@ export async function cancelAgentJob(token, agentUid, jobId) {
 export function formatJobsHttpError(err, jobId) {
     if (err.status === 401)
         return "Not authenticated — run `hq login`.";
+    // A 403 CROSS_AGENT_JOB is hq-pro's self-only jobs guard, not a role problem:
+    // the caller authenticated as one agent and asked about another. Naming it as
+    // "owner/admin required" (below) is misleading copy an agent box can never
+    // satisfy, so distinguish it here (defence in depth — the CLI now also fails
+    // closed locally before the request, see crossAgentJobsRefusal).
+    if (err.status === 403 && err.code === "CROSS_AGENT_JOB") {
+        return ("Jobs are scoped to the calling agent's own identity — an agent may only " +
+            "list, pause, or cancel its OWN jobs (use the on-box `hq-agent-jobs` tool). " +
+            "Managing another agent's jobs needs a person session with owner/admin on " +
+            "the company.");
+    }
     if (err.status === 403)
         return "You need owner/admin on this company.";
     if (err.status === 404 && err.code === "JOB_NOT_FOUND") {
@@ -420,6 +432,77 @@ export async function resolveAgentUid(token, ref, companySlug) {
     }
     return match.uid;
 }
+/**
+ * Fail-closed local guard for the off-box `hq agents jobs` operator commands.
+ *
+ * hq-pro's jobs endpoints are self-only for an agent machine identity: an
+ * agent-authenticated list/pause/cancel against `/v1/agents/{uid}/jobs` whose
+ * `{uid}` is not the caller's OWN agt_ uid is refused server-side as 403
+ * `CROSS_AGENT_JOB` and logged loud (`caller_uid_mismatch`, Sentry hq-pro
+ * 7617401436). That happens when these commands are run ON an agent box, where
+ * {@link resolveVaultCredential} silently returns the box's own agent ID token —
+ * the operator meant to act as a person with owner/admin, not as the box.
+ *
+ * Catch it locally so the call never leaves the box: decode the (already
+ * locally trusted, signature-unverified) bearer token and, ONLY when it proves
+ * an agent identity acting on a DIFFERENT agent, return a refusal string for the
+ * command to print before any HTTP request. Every other shape fails OPEN
+ * (returns `null`) and proceeds to the server exactly as today: a person session
+ * (no `custom:entityType` claim), an opaque / non-JWT credential (an `hqk_` API
+ * key), a token with a missing or malformed uid claim, or an agent acting on its
+ * OWN jobs.
+ *
+ * Pure: no network, no logging; never prints or returns the token itself.
+ */
+export function crossAgentJobsRefusal(token, resolvedAgentUid) {
+    const claims = peekIdToken(token);
+    const entityType = typeof claims["custom:entityType"] === "string"
+        ? claims["custom:entityType"]
+        : undefined;
+    const entityUid = typeof claims["custom:entityUid"] === "string"
+        ? claims["custom:entityUid"].trim()
+        : "";
+    // Positive proof required before refusing: an agent identity, a well-formed
+    // agt_ own-uid, and a target that differs from it. Anything else proceeds.
+    if (entityType !== "agent")
+        return null;
+    if (!AGENT_UID_PATTERN.test(entityUid))
+        return null;
+    if (entityUid === resolvedAgentUid.trim())
+        return null;
+    return (`Refusing to manage ${resolvedAgentUid}'s scheduled jobs using this agent's ` +
+        `own identity (${entityUid}). On an agent box, \`hq agents jobs\` authenticates ` +
+        `as the box itself, and hq-pro scopes an agent to its OWN jobs only — inspect ` +
+        `those with the on-box \`hq-agent-jobs\` tool. To manage another agent's jobs, ` +
+        `run this from a person session with owner/admin on the company (\`hq login\`), ` +
+        `not on the agent box.`);
+}
+/**
+ * Shared preamble for the three `hq agents jobs` actions: resolve the caller's
+ * credential, turn the (possibly slug/name) reference into an `agt_` uid via the
+ * roster, and fail closed BEFORE any jobs request when an agent identity targets
+ * another agent ({@link crossAgentJobsRefusal}). Returns the token + resolved
+ * uid for the caller's single jobs request. Never returns on a refusal or a
+ * resolution error — it prints and exits non-zero. The refusal exit lives
+ * OUTSIDE the resolution try so it is not re-wrapped as a generic failure.
+ */
+async function resolveJobsTargetOrExit(ref, company) {
+    let token;
+    let targetUid;
+    try {
+        token = (await resolveVaultCredential()).token;
+        targetUid = await resolveAgentUid(token, ref, company);
+    }
+    catch (err) {
+        return failJobs(err);
+    }
+    const refusal = crossAgentJobsRefusal(token, targetUid);
+    if (refusal) {
+        console.error(chalk.red(refusal));
+        process.exit(1);
+    }
+    return { token, targetUid };
+}
 /** Send a DM to an agent. Returns nothing meaningful beyond success. */
 export async function sendAgentDm(token, agentUid, message) {
     await agentsRequest({
@@ -934,11 +1017,12 @@ export function registerAgentsCommand(program) {
     jobs
         .command("list <agentUid>")
         .description("List an agent's scheduled jobs")
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
         .option("--json", "Emit raw JSON")
-        .action(async (agentUid, opts) => {
+        .action(async function (agentUid, opts) {
+        const { token, targetUid } = await resolveJobsTargetOrExit(agentUid, companyOf(this));
         try {
-            const token = (await resolveVaultCredential()).token;
-            const roster = await listAgentJobs(token, agentUid);
+            const roster = await listAgentJobs(token, targetUid);
             if (opts.json) {
                 process.stdout.write(JSON.stringify(roster, null, 2) + "\n");
                 return;
@@ -956,10 +1040,11 @@ export function registerAgentsCommand(program) {
     jobs
         .command("pause <agentUid> <jobId>")
         .description("Pause a job's schedule (reversible)")
-        .action(async (agentUid, jobId) => {
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+        .action(async function (agentUid, jobId) {
+        const { token, targetUid } = await resolveJobsTargetOrExit(agentUid, companyOf(this));
         try {
-            const token = (await resolveVaultCredential()).token;
-            const result = await pauseAgentJob(token, agentUid, jobId);
+            const result = await pauseAgentJob(token, targetUid, jobId);
             console.log(chalk.green(formatPauseResult(result)));
         }
         catch (err) {
@@ -969,10 +1054,11 @@ export function registerAgentsCommand(program) {
     jobs
         .command("cancel <agentUid> <jobId>")
         .description("Cancel a job and delete its schedule")
-        .action(async (agentUid, jobId) => {
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+        .action(async function (agentUid, jobId) {
+        const { token, targetUid } = await resolveJobsTargetOrExit(agentUid, companyOf(this));
         try {
-            const token = (await resolveVaultCredential()).token;
-            const result = await cancelAgentJob(token, agentUid, jobId);
+            const result = await cancelAgentJob(token, targetUid, jobId);
             console.log(chalk.green(`Cancelled ${result.jobId}.`));
         }
         catch (err) {

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

@@ -134,12 +134,36 @@ export interface InstallInput {
     docsUrl?: string;
     authMode?: "none" | "bearer";
     bearerToken?: string;
+    /** Preserve a non-default placement for a pasted key (for example X-API-Key). */
+    authScheme?: {
+        placement: "authorization";
+        format: "bearer";
+    } | {
+        placement: "authorization";
+        format: "prefix";
+        prefix: string;
+    } | {
+        placement: "authorization";
+        format: "basic";
+        username?: string;
+    } | {
+        placement: "header";
+        header: string;
+    };
 }
 export declare function installIntegration(token: string, companyUid: string, input: InstallInput): Promise<InstallResult>;
 export declare function uninstallIntegration(token: string, companyUid: string, installationId: string): Promise<{
     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;
@@ -181,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 —
@@ -278,6 +289,14 @@ async function findCatalogEntry(token, companyUid, domain) {
 function domainLabel(domain) {
     return domain.trim().toLowerCase().split(".")[0] ?? "";
 }
+/** A catalog display name's copy-pasteable command-line slug. */
+function displayNameSlug(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
 /**
  * Best-effort resolution of a bare name to a single catalog entry. Matches the
  * entry's registrable domain label (`notion` → `notion.com`) or an exact
@@ -293,7 +312,8 @@ async function findCatalogEntryByName(token, companyUid, name) {
             return null;
         const entries = await listCatalog(token, companyUid, { query: name, limit: 20 });
         const matches = entries.filter((entry) => domainLabel(entry.domain) === want ||
-            entry.name?.trim().toLowerCase() === want);
+            entry.name?.trim().toLowerCase() === want ||
+            (entry.name !== undefined && displayNameSlug(entry.name) === displayNameSlug(want)));
         if (matches.length === 0)
             return null;
         // Collapse rows that point at the same app (same domain) before deciding
@@ -415,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") {
@@ -430,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]")
@@ -552,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_…)")
@@ -600,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`
@@ -609,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;
@@ -201,13 +211,23 @@ export declare function fetchAdminSurface(token: string, companyUid: string): Pr
 export declare function fetchConnections(token: string, companyUid: string): Promise<AdminConnection[]>;
 /**
  * Resolve one connection by `--connection acct_…` or `--provider linear`
- * (matches `factory:<slug>` and bare provider ids, case-insensitive). Errors
- * list what IS connected so the fix is one command away.
+ * (matches `factory:<slug>`, bare provider ids, and an installation's human
+ * display-name slug, case-insensitive). The legacy provider id remains a
+ * first-class match, so scripts that saved opaque historical slugs keep
+ * working. Errors list what IS connected so the fix is one command away.
  */
 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
@@ -217,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>;
 /**