@indigoai-us/hq-cli 5.108.25 → 5.109.0

package/dist/commands/cloud.js

@@ -12,6 +12,7 @@
  *   hq sync pull              — pull all permitted files from the vault
  *   hq sync status            — show local journal summary
  */
+import { isAccessDeniedError, accessDeniedKeyOf, formatAccessDenied, } from "../utils/access-denied-hint.js";
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
@@ -44,6 +45,14 @@ export class SyncExitError extends Error {
  * CLI are released independently.
  */
 export function formatSyncFailure(err) {
+    if (isAccessDeniedError(err)) {
+        const key = accessDeniedKeyOf(err);
+        const base = err instanceof Error ? err.message : String(err);
+        if (key) {
+            return formatAccessDenied(`Access denied for '${key}': ${base}`, key);
+        }
+        return formatAccessDenied(base);
+    }
     if (typeof err === "object" && err !== null) {
         const diagnostic = err;
         if (diagnostic.code === "POLICY_WRITE_SCOPE_TRUNCATED") {
@@ -978,7 +987,8 @@ export function registerCloudCommands(program) {
         catch (err) {
             if (syncHealth)
                 await syncHealth.failed();
-            console.error(chalk.red("\n✗ Pull failed:"), err instanceof Error ? err.message : String(err));
+            const message = formatSyncFailure(err);
+            console.error(chalk.red("\n✗ Pull failed:"), message);
             process.exit(1);
         }
     });

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

@@ -35,7 +35,7 @@
  */
 import { Command } from "commander";
 import { ListObjectsV2Command, GetObjectCommand, type ListObjectsV2CommandOutput, type GetObjectCommandOutput } from "@aws-sdk/client-s3";
-import { type ExplicitGrant } from "@indigoai-us/hq-cloud";
+import { VaultClient, type ExplicitGrant } from "@indigoai-us/hq-cloud";
 /** STS-vended credential set the browse/cat path consumes. */
 export interface BrowseCredentials {
     accessKeyId: string;
@@ -433,7 +433,18 @@ export declare const PRESIGN_BUFFER_MAX_BYTES: number;
 export declare function createCompanyPresignClient(input: {
     token: string;
     companyUid: string;
+    /**
+     * Company slug the client is scoped to. Attached as `company` on every 403
+     * so the access ladder targets THIS tenant rather than the active company
+     * (keys on these errors are bucket-relative and carry no slug).
+     */
+    companySlug?: string;
 }): FilesBrowseS3Client;
+/**
+ * Production company-mode client factory — closes over the caller's token and
+ * (when known) the company slug, so 403s are tenant-anchored.
+ */
+export declare function makeCompanyPresignFactory(token: string, companySlug?: string): CompanyBrowseClientFactory;
 /**
  * `FilesBrowseVaultClient` for a Bearer `hqk_` key.
  *
@@ -455,6 +466,19 @@ export declare function createCompanyPresignClient(input: {
  * roll-up) throw a fail-closed error naming the Cognito requirement.
  */
 export declare function createApiKeyBrowseVaultClient(token: string): FilesBrowseVaultClient & FilesSharedWithMeVaultClient;
+/**
+ * The caller's credential plus the vault client that can carry it.
+ *
+ * `cognito` is undefined under HQ_API_KEY: `VaultClient` speaks only the JWT
+ * routes, so the keyed adapter stands in for the company path — and the
+ * personal path, which needs `VaultClient.entity.listByType` plus an STS vend,
+ * has nothing to run on and must fail closed at its branch.
+ */
+export declare function resolveBrowseSession(): Promise<{
+    token: string;
+    client: FilesBrowseVaultClient & FilesSharedWithMeVaultClient;
+    cognito?: VaultClient;
+}>;
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group

package/dist/commands/files-browse.js

@@ -33,6 +33,7 @@
  * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
  * methods and `grantPathToPrefix` from hq-cloud.
  */
+import { isAccessDeniedError, accessDeniedKeyOf, reportAccessDenied, accessDeniedCompanyOf, } from "../utils/access-denied-hint.js";
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -595,7 +596,13 @@ export const PRESIGN_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
  * `send(...)` as if it held an S3 client.
  */
 export function createCompanyPresignClient(input) {
-    const { token, companyUid } = input;
+    const { token, companyUid, companySlug } = input;
+    const denied = (message, key, extra) => Object.assign(new Error(message), {
+        status: 403,
+        key,
+        ...(companySlug ? { company: companySlug } : {}),
+        ...(extra ?? {}),
+    });
     async function listObjects(cmd) {
         const prefix = cmd.input.Prefix ?? "";
         const query = { company: companyUid };
@@ -606,7 +613,11 @@ export function createCompanyPresignClient(input) {
         const res = await vaultApiFetch({ token, path: "/v1/files/list", query });
         if (!res.ok) {
             const body = (await res.json().catch(() => ({})));
-            throw new Error(body.message ?? body.error ?? `files list failed (${res.status})`);
+            const message = body.message ?? body.error ?? `files list failed (${res.status})`;
+            if (res.status === 403) {
+                throw denied(message, prefix);
+            }
+            throw new Error(message);
         }
         const body = (await res.json());
         return {
@@ -636,13 +647,21 @@ export function createCompanyPresignClient(input) {
         });
         if (!res.ok) {
             const body = (await res.json().catch(() => ({})));
-            throw new Error(body.message ?? body.error ?? `presign failed (${res.status})`);
+            const message = body.message ?? body.error ?? `presign failed (${res.status})`;
+            if (res.status === 403) {
+                throw denied(message, key);
+            }
+            throw new Error(message);
         }
         const body = (await res.json());
         const first = body.results?.[0];
         if (!first || !first.url) {
             // Per-key denial/validation surfaces here (e.g. FILES_PRESIGN_FORBIDDEN).
-            throw new Error(first?.error ?? `No presigned URL returned for '${key}'`);
+            const message = first?.error ?? `No presigned URL returned for '${key}'`;
+            if (first?.code === "FILES_PRESIGN_FORBIDDEN") {
+                throw denied(message, key, { code: "FILES_PRESIGN_FORBIDDEN" });
+            }
+            throw new Error(message);
         }
         const dl = await fetch(first.url);
         if (!dl.ok) {
@@ -687,9 +706,21 @@ export function createCompanyPresignClient(input) {
     }
     return { send };
 }
-/** Production company-mode client factory — closes over the caller's token. */
-function makeCompanyPresignFactory(token) {
-    return ({ companyUid }) => createCompanyPresignClient({ token, companyUid });
+/**
+ * Production company-mode client factory — closes over the caller's token and
+ * (when known) the company slug, so 403s are tenant-anchored.
+ */
+export function makeCompanyPresignFactory(token, companySlug) {
+    return ({ companyUid }) => createCompanyPresignClient({ token, companyUid, companySlug });
+}
+/**
+ * Tenant anchor for the access ladder in a CLI catch block: prefer the slug
+ * the failing client stamped on the 403, else the `--company` flag. `hqRoot`
+ * rides along so `hq access` reads the same tree the command was run against.
+ */
+function accessLadderContextFor(err, command, hqRoot) {
+    const flag = command.optsWithGlobals().company;
+    return { company: accessDeniedCompanyOf(err) ?? flag, hqRoot };
 }
 // ── HQ_API_KEY vault client (keyed routes only) ──────────────────────────────
 /** Fail-closed error the top-level handler prints without a Sentry report. */
@@ -793,7 +824,7 @@ function personalVaultNeedsCognito() {
  * personal path, which needs `VaultClient.entity.listByType` plus an STS vend,
  * has nothing to run on and must fail closed at its branch.
  */
-async function resolveBrowseSession() {
+export async function resolveBrowseSession() {
     const cred = await resolveVaultCredential();
     if (cred.kind === "api-key") {
         return {
@@ -882,7 +913,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 pathPrefix: pathArg,
                 companySlug: slug,
                 vaultClient: client,
-                companyClient: makeCompanyPresignFactory(accessToken),
+                companyClient: makeCompanyPresignFactory(accessToken, slug),
                 region: DEFAULT_COGNITO.region,
             });
             console.log(formatBrowseTable(result.rows));
@@ -895,7 +926,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             }
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err) ?? pathArg, accessLadderContextFor(err, command, options.hqRoot));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });
@@ -959,7 +996,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 hqRoot: options.hqRoot,
                 companySlug: slug,
                 vaultClient: client,
-                companyClient: makeCompanyPresignFactory(accessToken),
+                companyClient: makeCompanyPresignFactory(accessToken, slug),
                 region: DEFAULT_COGNITO.region,
             });
             if (result.destination.kind === "file") {
@@ -967,7 +1004,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             }
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err) ?? keyArg, accessLadderContextFor(err, command, options.hqRoot));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });
@@ -1003,7 +1046,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             console.log(formatSharedWithMeTable(rows));
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err), accessLadderContextFor(err, command));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });
@@ -1049,13 +1098,22 @@ export function registerFilesBrowseCommands(filesCmd) {
                 query,
                 companySlug: company,
                 vaultClient: client,
-                companyClient: makeCompanyPresignFactory(accessToken),
+                companyClient: makeCompanyPresignFactory(accessToken, company),
                 region: DEFAULT_COGNITO.region,
             });
             console.log(formatBrowseTable(rows));
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err) ??
+                    (command.optsWithGlobals().company
+                        ? `companies/${command.optsWithGlobals().company}`
+                        : undefined), accessLadderContextFor(err, command));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });
@@ -1091,7 +1149,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 hqRoot: options.hqRoot,
                 companySlug: slug,
                 vaultClient: client,
-                companyClient: makeCompanyPresignFactory(accessToken),
+                companyClient: makeCompanyPresignFactory(accessToken, slug),
                 region: DEFAULT_COGNITO.region,
             });
             console.error(chalk.green("✓"), `Materialized ${result.filesWritten} file(s), ${result.bytesWritten} bytes.`);
@@ -1100,7 +1158,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             }
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err) ?? pathArg, accessLadderContextFor(err, command, options.hqRoot));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });

package/dist/commands/files.js

@@ -7,6 +7,7 @@ import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
 import { looksLikeCompanyUid } from "../utils/vault-api.js";
 import { AuthError } from "../utils/auth-error.js";
+import { formatAccessDenied, offerAccessLadder, } from "../utils/access-denied-hint.js";
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for unit tests)
 // ---------------------------------------------------------------------------
@@ -75,9 +76,9 @@ export function formatShareSessionError(err) {
     }
     if (err.status === 403) {
         if (err.path) {
-            return `Not authorized to share '${err.path}' — you need read access on every path`;
+            return formatAccessDenied(`Not authorized to share '${err.path}' — you need read access on every path`, err.path);
         }
-        return "Not authorized — you need to be a company member with read access on every path";
+        return formatAccessDenied("Not authorized — you need to be a company member with read access on every path");
     }
     if (err.status === 400) {
         return `Invalid request: ${err.message}`;
@@ -236,6 +237,9 @@ export function registerFilesCommand(program) {
                 }
                 else if (res.status === 403) {
                     console.error(chalk.red("Not authorized to modify this file prefix's ACL"));
+                    await offerAccessLadder(canonicalPrefix, {
+                        company: files.opts().company,
+                    });
                 }
                 else if (res.status === 404) {
                     // A 404 means ZERO rows were removed — never report a green success
@@ -304,6 +308,9 @@ export function registerFilesCommand(program) {
                 }
                 else if (treeRes.status === 403) {
                     console.error(chalk.red("Not authorized to view this file prefix's ACL"));
+                    await offerAccessLadder(canonicalPrefix, {
+                        company: files.opts().company,
+                    });
                 }
                 else if (treeRes.status >= 500) {
                     console.error(chalk.red(`Server error: ${body.error ?? treeRes.statusText}`));
@@ -566,6 +573,9 @@ async function runDirectGrant(params) {
         }
         else if (res.status === 403) {
             console.error(chalk.red("Not authorized to share this file prefix"));
+            await offerAccessLadder(canonicalPrefix, {
+                company: params.companySlug,
+            });
         }
         else if (res.status === 404) {
             console.error(chalk.red("ACL record not found — the prefix may not have an ACL yet"));
@@ -666,7 +676,7 @@ export function formatFilesDeleteError(err, prefix) {
         return "Not authenticated — please run `hq login`";
     }
     if (err.status === 403) {
-        return `Not authorized to delete '${prefix}' — you need write access on it`;
+        return formatAccessDenied(`Not authorized to delete '${prefix}' — you need write access on it`, prefix);
     }
     if (err.status === 400) {
         return `Invalid request: ${err.message}`;
@@ -1084,9 +1094,9 @@ function formatFilesRecoveryError(err, key) {
         return "Not authenticated — please run hq login";
     }
     if (err.status === 403) {
-        return key
+        return formatAccessDenied(key
             ? "Not authorized to modify '" + key + "' — you need write access on it"
-            : "Not authorized to view this vault path";
+            : "Not authorized to view this vault path", key);
     }
     if (err.code === "FILES_RESTORE_VERSION_NOT_FOUND") {
         return "That version is unavailable or is a delete marker.";

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

@@ -212,6 +212,21 @@ export interface OAuthStartInput {
      * state row and attaches it at code exchange; it is never logged.
      */
     clientSecret?: string;
+    /**
+     * The exact permissions to request at the authorize step.
+     *
+     * Normally leave this alone: hq-pro sends whatever a vendor needs, either
+     * the scopes a pre-registered client was granted or, for the vendors that
+     * reject a scope-less request outright, a server-side list. This exists for
+     * the case that list does not cover — an app that wants narrower access
+     * than the default, or a vendor whose requirement HQ does not yet know.
+     *
+     * hq-pro honours it on EVERY connect path (catalog, domain, discovery
+     * receipt, direct `mcpUrl`) and it beats both the static-client and
+     * registry-derived scopes, unlike `clientId`, which is read only on the
+     * direct `mcpUrl` path.
+     */
+    scopes?: string[];
 }
 export declare function startOAuth(token: string, companyUid: string, input: OAuthStartInput): Promise<OAuthStartResult>;
 export declare function completeOAuth(token: string, companyUid: string, input: {

package/dist/commands/integrations-connect.js

@@ -76,6 +76,64 @@ const BRING_YOUR_OWN_CLIENT_CODES = new Set([
     "OAUTH_REGISTRATION_UNSUPPORTED",
     "CLIENT_REGISTRATION_REFUSED",
 ]);
+/**
+ * Server-side limits, restated here so a typo fails in the terminal with a
+ * sentence rather than as an opaque 400 three network hops away. Kept in step
+ * with hq-pro's own `parseRequestedScopes`; if that changes, change this.
+ */
+const MAX_SCOPES = 32;
+const MAX_SCOPE_LENGTH = 256;
+/**
+ * Parses `--scopes`, accepting either separator a person would reach for:
+ * `--scopes "mcp:read mcp:write"` and `--scopes mcp:read,mcp:write` are the
+ * same request. Order is preserved and duplicates are dropped, so a repeated
+ * scope is not sent twice.
+ *
+ * Rejects rather than silently repairing. A scope list is a permissions
+ * request; quietly dropping a malformed entry would ask a vendor for something
+ * other than what the caller typed, and the caller would not find out until an
+ * agent hit a missing permission later.
+ */
+function parseRequestedScopes(raw) {
+    if (raw === undefined)
+        return undefined;
+    const entries = raw.split(/[\s,]+/).filter((entry) => entry.length > 0);
+    if (entries.length === 0) {
+        throw new IntegrationsCliError("--scopes was empty — pass at least one permission.", {
+            expected: true,
+        });
+    }
+    if (entries.length > MAX_SCOPES) {
+        throw new IntegrationsCliError(`--scopes takes at most ${MAX_SCOPES} permissions; ${entries.length} were given.`, { expected: true });
+    }
+    const scopes = [];
+    for (const entry of entries) {
+        if (entry.length > MAX_SCOPE_LENGTH) {
+            throw new IntegrationsCliError(`--scopes entries must be at most ${MAX_SCOPE_LENGTH} characters.`, { expected: true });
+        }
+        if (!scopes.includes(entry))
+            scopes.push(entry);
+    }
+    return scopes;
+}
+/**
+ * Refuse a `--scopes` that could not possibly be honoured, before anything is
+ * sent. Permissions are an OAuth concept: an API-key app has none to ask for,
+ * and an app that needs no auth has nothing to ask.
+ */
+function assertScopesApplicable(opts, target, authMode) {
+    if (opts.scopes === undefined)
+        return;
+    if (opts.token || opts.tokenStdin) {
+        throw new IntegrationsCliError("--scopes is for a browser sign-in and --token is for an API key; pass one or the other, not both.", { expected: true });
+    }
+    // An UNKNOWN mode is left alone for the same reason --client-id leaves it
+    // alone: the direct-endpoint path often learns it is OAuth only once hq-pro
+    // says so, and refusing here would block the very case this flag is for.
+    if (authMode === "key" || authMode === "none") {
+        throw new IntegrationsCliError(`${target.label} does not use a browser sign-in, so --scopes does not apply to it.`, { expected: true });
+    }
+}
 /**
  * Looks-like-a-domain test for the positional `<app>` argument. Deliberately
  * loose — hq-pro does the real resolution — but tight enough that `linear.app`
@@ -398,13 +456,17 @@ async function connectViaOAuth(token, companyUid, target, opts) {
             expected: true,
         });
     }
-    const startInput = { ...target.ref };
+    const requestedScopes = parseRequestedScopes(opts.scopes);
+    const startInput = {
+        ...target.ref,
+        ...(requestedScopes ? { scopes: requestedScopes } : {}),
+    };
     // A user-registered app pins the console callback and skips the loopback
     // entirely — see `userClientSignIn` for why an ephemeral port cannot be the
     // redirect URI here.
     const userClient = await resolveUserOAuthClient(opts, target.label);
     if (userClient)
-        return await userClientSignIn(token, companyUid, target, opts, userClient);
+        return await userClientSignIn(token, companyUid, target, opts, userClient, requestedScopes);
     // A loopback listener only works if the browser runs on THIS machine. Over
     // SSH the person opens the printed URL on their workstation, so the provider
     // redirects to the workstation's 127.0.0.1 while the listener sits on the
@@ -567,6 +629,13 @@ async function consoleHandoff(target, opts) {
     const url = consoleIntegrationsUrl(opts.company, consoleOrigin());
     console.error(chalk.yellow(`${target.label} signs in through the console, not the terminal — this HQ backend finishes these sign-ins there.`));
     printConsoleDestination(target, opts, url);
+    // A console sign-in is started by the console, so there is nowhere to put a
+    // --scopes list. Saying nothing would let the connect finish with default
+    // permissions while the caller believes theirs were requested -- the exact
+    // silent-wrong-permissions failure --scopes exists to prevent.
+    if (opts.scopes) {
+        console.error(chalk.yellow(`Note: --scopes cannot be carried into a console sign-in, so this connect will use ${target.label}'s default permissions.`));
+    }
     if (url && opts.browser !== false)
         await open(url).catch(() => { });
     console.error(chalk.dim("When the browser says it connected, run `hq integrations list` to confirm."));
@@ -624,6 +693,11 @@ function byoClientCommand(target, opts) {
     if (provider)
         parts.push(`--provider ${shellQuote(provider)}`);
     parts.push("--client-id <client-id-from-the-provider>", "--client-secret-stdin");
+    // The whole point of --scopes is that this vendor needs permissions HQ would
+    // not otherwise send. Dropping them from the recovery command would hand the
+    // caller a line that reproduces the failure they are recovering from.
+    if (opts.scopes)
+        parts.push(`--scopes ${shellQuote(opts.scopes)}`);
     return parts.join(" ");
 }
 /**
@@ -705,11 +779,15 @@ async function resolveUserOAuthClient(opts, appLabel) {
  * `companyUid` is omitted, so the callback completes and the console names the
  * app it connected. Ship this only against a backend carrying both.
  */
-async function userClientSignIn(token, companyUid, target, opts, client) {
+async function userClientSignIn(token, companyUid, target, opts, client, requestedScopes) {
     const started = await startOAuth(token, companyUid, {
         ...target.ref,
         clientId: client.clientId,
         ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+        // A caller who registered the app themselves is the one who knows which
+        // permissions that registration was granted, so their list must reach the
+        // authorize step on this path too.
+        ...(requestedScopes ? { scopes: requestedScopes } : {}),
     });
     console.error(`Open this URL to sign in to ${started.displayName || target.label}:`);
     console.error(`  ${started.authorizationUrl}`);
@@ -772,6 +850,7 @@ async function connectApp(token, companyUid, app, opts, expectedRevivedConnectio
     const target = await resolveTarget(token, companyUid, app, opts, expectedRevivedConnectionId !== undefined);
     const authMode = opts.auth ?? target.authClass;
     assertUserClientApplicable(opts, target, authMode);
+    assertScopesApplicable(opts, target, authMode);
     if (authMode === "oauth") {
         const result = await connectViaOAuth(token, companyUid, target, opts);
         if (result)
@@ -932,6 +1011,7 @@ export function registerConnectCommands(integrations) {
         .option("--auth <mode>", "Force the auth mode: none, key, or oauth (default: detect)")
         .option("--client-id <id>", "Client id of an OAuth app you registered with the provider yourself")
         .option("--client-secret-stdin", "Read that app's client secret from stdin")
+        .option("--scopes <list>", "Permissions to request, space- or comma-separated (default: what the app needs)")
         .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("--json", "Machine-readable output")
@@ -1005,6 +1085,7 @@ export function registerConnectCommands(integrations) {
         // start an ordinary sign-in, and `--client-id` beside `--token` would
         // reinstall with the bearer token and drop the OAuth app.
         assertUserClientApplicable(opts, target, target.authClass);
+        assertScopesApplicable(opts, target, target.authClass);
         if (target.authClass === "oauth") {
             const result = await connectViaOAuth(token, companyUid, target, opts);
             if (result)

package/dist/commands/integrations-oauth.js

@@ -23,10 +23,69 @@ import { IntegrationsCliError } from "./integrations-core.js";
 export const LOOPBACK_CALLBACK_PATH = "/hq/integrations/oauth/callback";
 /** How long to wait for the browser round trip before giving the port back. */
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Escapes text destined for the callback page.
+ *
+ * Every caller passes a literal today, so nothing here is attacker-controlled.
+ * It is escaped anyway because this function builds HTML: the next person to
+ * pass a provider-supplied string through it should not have to notice that
+ * the escaping was missing.
+ */
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * The hq-console visual language, inlined.
+ *
+ * Deliberately NOT the console's webfont: this page is served by a local port
+ * and is often the browser's first paint after a redirect, so a blocking
+ * request to fonts.googleapis.com would either delay it or fail outright on a
+ * plane. Geist is named first so it is used when the machine has it, with the
+ * system stack behind. Token values track src/app/globals.css in hq-console —
+ * near-black ground, hairline border, one 13px size, weight 400 only, grey
+ * heading over bright body.
+ */
+const CALLBACK_PAGE_STYLE = `
+  :root { color-scheme: dark }
+  * { box-sizing: border-box }
+  body {
+    margin: 0; min-height: 100vh; display: flex;
+    align-items: center; justify-content: center;
+    background: #17161a; color: #f2efe9;
+    font-family: Geist, ui-sans-serif, system-ui, -apple-system, sans-serif;
+    font-size: 13px; font-weight: 400; letter-spacing: -0.013em; line-height: 1.6;
+  }
+  main {
+    width: 100%; max-width: 26rem; margin: 2rem; padding: 1.75rem;
+    border: 1px solid rgba(255,255,255,0.1); border-radius: 10px;
+    background: #121116;
+  }
+  .mark { color: #6f6a62; margin-bottom: 1.5rem }
+  h1 { font-size: 13px; font-weight: 400; color: #a8a29a; margin: 0 0 0.5rem }
+  p  { margin: 0; color: #f2efe9 }
+  .dot {
+    display: inline-block; width: 6px; height: 6px; border-radius: 50%;
+    margin-right: 0.5rem; vertical-align: 1px; background: var(--dot);
+  }
+`;
 function respond(res, status, title, detail) {
-    const body = `<!doctype html><meta charset="utf-8"><title>${title}</title>
-<body style="font:15px system-ui;margin:4rem auto;max-width:32rem;color:#111">
-<h1 style="font-size:1.1rem;font-weight:600">${title}</h1><p>${detail}</p></body>`;
+    // Green only when the browser leg genuinely succeeded. A cancelled or
+    // incomplete sign-in gets amber, because the page must not read as success
+    // when the terminal is about to report a failure.
+    const dot = status === 200 ? "#34d399" : "#fbbf24";
+    const body = `<!doctype html><html lang="en"><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(title)} · HQ</title>
+<style>${CALLBACK_PAGE_STYLE}</style>
+<body><main>
+<div class="mark">HQ</div>
+<h1><span class="dot" style="--dot:${dot}"></span>${escapeHtml(title)}</h1>
+<p>${escapeHtml(detail)}</p>
+</main></body></html>`;
     res.writeHead(status, {
         "content-type": "text/html; charset=utf-8",
         // The page is a terminal handoff, never something to keep or re-fetch.

package/dist/commands/mcp-registration.d.ts

@@ -52,7 +52,6 @@
  * first-class skip), and {@link registerMcpServers} is the pack-install routing
  * seam over it.
  */
-import { type FlagReader } from '../lib/flag-registry.js';
 /** Base for every MCP-registration error; carries a stable machine-checkable `code`. */
 export declare abstract class McpRegistrationError extends Error {
     abstract readonly code: string;
@@ -596,10 +595,17 @@ export declare function registerServer(opts: RegisterServerOptions): RegisterSer
  * when neither a url nor a command is present.
  */
 export declare function manifestTarget(manifest: McpManifest): string;
-/** Resolve the gate once at the start of an MCP registration operation. */
-export declare function isMcpRegistrationEnabled(flagReader?: FlagReader): boolean;
-/** Freeze a registration decision so multi-server work cannot split on refresh. */
-export declare function captureMcpRegistrationDecision(flagReader?: FlagReader): FlagReader;
+/**
+ * Resolve the MCP registration kill switch from its env var alone.
+ *
+ * `HQ_DISABLE_MCP_REGISTRATION` is an operator's own machine-local opt-out, not
+ * a rollout flag, so it is read straight from the environment — no registry
+ * lookup. The polarity is inverted and the value match is asymmetric on
+ * purpose: ONLY the exact value "1" disables registration; unset and every
+ * other value (including "0" and "false") leave it enabled. Do not "tidy" this
+ * into a boolean parse — that would silently disable anyone who wrote "false".
+ */
+export declare function isMcpRegistrationEnabled(env?: Readonly<Record<string, string | undefined>>): boolean;
 /**
  * Register one pack's MCP servers into the shared agent configs (the public seam
  * `pack-install` routes `wire:'merge'` keys to). For each declared server name it
@@ -627,8 +633,12 @@ export declare function registerMcpServers(pkg: string, names: string[], options
     /** Lock tuning + backup stamp passthrough (tests). */
     lock?: AcquireLockOptions;
     stamp?: string;
-    /** Test seam: held registry snapshot reader. */
-    flagReader?: FlagReader;
+    /**
+     * Pre-resolved kill-switch decision, frozen once before a multi-server loop
+     * so an install writes either all of a pack's servers or none of them.
+     * Omitted → read `HQ_DISABLE_MCP_REGISTRATION` directly.
+     */
+    registrationEnabled?: boolean;
 }): RegisterServerResult[];
 /** smol-toml's value-table type (its `parse` return + `stringify` input). */
 type TomlTable = Record<string, unknown>;