@indigoai-us/hq-cli 5.108.24 → 5.108.26

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 ## [Unreleased]
 
+## [5.108.26] — 2026-09-08
+
+### Added
+
+- **Daemon receive-only mode** (owner decision 2026-09-08; contract
+  direct-emit-v1 §6.3). `hq mesh mode <get|legacy|direct|check>` selects the
+  daemon's emit mode, resolved from `HQ_MESH_MODE` then `~/.hq/work-mesh/config.json`
+  (`emitMode`), defaulting to **legacy**. In `legacy` the daemon runs the spool
+  watch + flush + held + outbox replay + transcript-watch emit path (unchanged).
+  In `direct` it runs **receive-only** — the presence subscriber keeps the cache
+  the desktop app reads warm on `hq/{personUid}/mesh`, with no spool/held/outbox/
+  flush/transcript-watch — because sessions POST events directly. `hq mesh mode
+  check` probes whether `/v1/mesh/events` is live so the flag can flip after the
+  server route lands. `hq mesh daemon doctor` reports `mode` + `subscription`
+  state and omits the spool/held/outbox lines in direct mode.
+- **Direct-emit path** (owner decision 2026-09-08 "retire the client daemon";
+  contract `direct-emit-v1`). `hq mesh session <kind>` now POSTs each Work Mesh
+  event straight to `POST /v1/mesh/events` with the caller's normal HQ bearer
+  token instead of appending to the local spool; the server attributes the event
+  to a company server-side and fans it out over MQTT. Evidence for attribution
+  travels in an `evidence` object gathered client-side: `companySlug` (from the
+  session meta), `cwd`, `hqRoot`, `touchedPaths` (`--touched-path`, repeatable),
+  `repoPath` (derived from the enclosing git work-tree), `project`, `task`. On a
+  network/5xx/429 failure the batch is written to a tiny local retry file that the
+  next invocation drains — no long-lived process. `--enqueue` is retained as a
+  no-op for hook back-compat (it now emits directly).
+- `hq mesh emit` — drains the retry file; `--replay-legacy` also replays the
+  legacy `spool.jsonl` + `held.jsonl` backlog through the new endpoint, lifting
+  each event's local-only fields into `evidence` and reusing its `eventId` so the
+  server dedupes.
+- `hq mesh daemon doctor` now reports the direct-emit path: `emit last post`
+  (lastPostAt), per-status counts from the last attempt, and `emit retry depth`.
+- `hq integrations connect --scopes "<list>"` sends an explicit permissions list
+  on the OAuth start request, for a vendor whose requirements HQ does not yet
+  know. Space- or comma-separated; order preserved, duplicates dropped. Omitting
+  the flag is unchanged — the request carries no `scopes` field at all and
+  hq-pro keeps choosing, because an empty list would ask a vendor for no access
+  rather than for its default. Refused up front where it could never be honoured
+  (alongside `--token`, or against an app whose auth mode is known to be `key`
+  or `none`), and carried through the printed bring-your-own-client command. A
+  console hand-off cannot carry it, and now says so.
+
+### Changed
+
+- The loopback sign-in callback page — the one HQ surface a person sees in a
+  browser during `hq integrations connect` — now carries the hq-console visual
+  language instead of an unstyled white page: near-black ground, hairline-bordered
+  card, one 13px size, grey heading over bright body, and a dim `HQ` mark.
+  Deliberately ships no webfont: the page is served by a local port and is often
+  the browser's first paint after a redirect, where a blocking font request would
+  delay it and would fail outright offline — exactly when a loopback callback
+  still works.
+
+### Fixed
+
+- `hq secrets set` now attributes its writes to a `cli_secrets_set` telemetry
+  surface, so CLI-created secrets are no longer recorded as generic `api` traffic.
+- `hq mesh context backfill-held` now forwards the company evidence each held
+  event recorded at enqueue time (`cwd`, `hqRoot`, the session's bound
+  `companySlug`, and any `project`/`task`) into the synthesized reconcile
+  observation, so an ended session attributes to the company it was actually
+  bound to (or its `companies/{slug}/` cwd) instead of resolving to
+  `needs_company` and staying held forever. `--dry-run` now predicts with the
+  same evidence + shared resolver the write path uses, so its `reconciled`/
+  `unresolved` counts match a real run — previously `--dry-run` reported every
+  unattributed session as would-reconcile while the write run, given no
+  evidence in its observation, resolved none.
+
+## [5.108.25] — 2026-09-08
+
 ## [5.108.24] — 2026-09-08
 
 ### Added

package/dist/commands/files.d.ts

@@ -89,6 +89,17 @@ export declare function stripRedundantCompanyScope(prefix: string): {
     prefix: string;
     strippedSlug: string;
 } | null;
+/**
+ * The company an anchored path names, or `undefined` for a relative/personal
+ * path.
+ *
+ * Discarding this slug is what makes retargeting possible: strip the anchor,
+ * then resolve the company from somewhere else, and the operation lands on a
+ * DIFFERENT company than the operator pasted. Callers pair this with
+ * `normalizeCompanyFilePrefix` so the anchor either MATCHES the explicit
+ * `--company` (or is refused), or BECOMES the company when none was given.
+ */
+export declare function companySlugFromAnchor(prefix: string, personal?: boolean): string | undefined;
 export declare function runFilesDelete(params: RunFilesDeleteParams, deps?: {
     confirm?: ConfirmFn;
 }): Promise<void>;

package/dist/commands/files.js

@@ -5,6 +5,8 @@ import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 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";
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for unit tests)
 // ---------------------------------------------------------------------------
@@ -157,8 +159,8 @@ export function registerFilesCommand(program) {
                 process.exit(1);
             }
             // Fork: --with present → existing direct-grant path. No --with →
-            // browser-launch share-session path. Per PRD, the direct-grant
-            // path is unchanged from US-001 and operates on a single prefix.
+            // browser-launch share-session path. The direct-grant path
+            // operates on a single prefix.
             if (opts.with !== undefined) {
                 if (paths.length !== 1) {
                     console.error(chalk.red("Direct grant (--with) takes exactly one prefix. Pass multiple paths only when minting a share-session URL."));
@@ -190,7 +192,15 @@ export function registerFilesCommand(program) {
         .requiredOption("--with <principal>", "Email address, group id, or '@all' to remove the company-wide grant")
         .action(async (prefix, opts) => {
         try {
-            const canonicalPrefix = normalizeFilePrefix(prefix);
+            // Unshare MUTATES access with no preview, and it resolves the target
+            // company from --company (not from the pasted anchor), so a mismatched
+            // anchor would revoke a real grant in the wrong company.
+            const canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
+                mutating: true,
+                ...(files.opts().company !== undefined
+                    ? { companySlug: files.opts().company }
+                    : {}),
+            });
             const principal = opts.with;
             const isAll = principal === "@all";
             const isEmail = !isAll && EMAIL_PATTERN.test(principal);
@@ -264,10 +274,21 @@ export function registerFilesCommand(program) {
         .description("Show the ACL (access control list) for a file prefix")
         .action(async (prefix) => {
         try {
-            const canonicalPrefix = normalizeFilePrefix(prefix);
+            // Read-only, so stripping is safe — but a mismatched anchor would show
+            // a DIFFERENT company's ACL than the one the operator pasted.
+            const explicitCompany = files.opts().company;
+            const canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
+                ...(explicitCompany !== undefined
+                    ? { companySlug: explicitCompany }
+                    : {}),
+            });
             const token = (await resolveVaultCredential()).token;
-            const companySlug = files.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            // Resolve through the anchor so the answer describes the company the
+            // operator actually pasted, and never a different one.
+            const companyUid = await resolveCompanyUidForAnchoredPath(token, {
+                explicit: explicitCompany,
+                anchorSlug: companySlugFromAnchor(prefix),
+            });
             // `/acl/tree` carries the prefix's own row metadata (directRow) and the
             // caller's effectivePermission alongside direct/inherited/children, so
             // a single request returns everything the "files acl" view needs.
@@ -474,7 +495,13 @@ export function registerFilesCommand(program) {
     return files;
 }
 async function runDirectGrant(params) {
-    const canonicalPrefix = normalizeFilePrefix(params.prefix);
+    const canonicalPrefix = normalizeCompanyFilePrefix(params.prefix, {
+        mutating: true,
+        rootAdvice: "Use --full --with <principal> to share the entire vault, or pass a bounded path.",
+        ...(params.companySlug !== undefined
+            ? { companySlug: params.companySlug }
+            : {}),
+    });
     if (!params.permission) {
         console.error(chalk.red("--permission is required when --with is set (read | write)"));
         process.exit(1);
@@ -565,9 +592,15 @@ async function runDirectGrant(params) {
     }
 }
 async function runShareSession(params) {
-    // Normalize every path through the shared prefix helper so a trailing
-    // `/` becomes `/*` consistently with the direct-grant path.
-    const normalizedPaths = params.paths.map(normalizeFilePrefix);
+    // Validate every path before minting a session; an anchored path must never
+    // silently become a share of the corresponding company-relative objects.
+    const normalizedPaths = params.paths.map((prefix) => normalizeCompanyFilePrefix(prefix, {
+        mutating: true,
+        rootAdvice: "Use --full --with <principal> to share the entire vault, or pass a bounded path.",
+        ...(params.companySlug !== undefined
+            ? { companySlug: params.companySlug }
+            : {}),
+    }));
     let expiresInMs;
     if (params.expires !== undefined) {
         const parsed = parseDuration(params.expires);
@@ -723,36 +756,179 @@ export function stripRedundantCompanyScope(prefix) {
         return null;
     return { prefix: m[2] ?? "", strippedSlug: m[1] };
 }
+/**
+ * Resolve the company for a possibly-anchored path, refusing any retarget.
+ *
+ * The pure normalizer can only compare slug against slug. That left a hole: a
+ * UID-form `--company` was skipped by the string check, so
+ * `--company cmp_beta delete <alpha-anchored-path>` stripped the anchor,
+ * resolved beta, and previewed/deleted from beta. Comparing IDENTITIES rather
+ * than strings is the only way to close it, and that needs resolution.
+ *
+ * - no anchor            -> unchanged behaviour
+ * - anchor, no --company -> the anchor IS the company
+ * - UID anchor           -> compare with the selected company UID
+ * - slug + explicit UID  -> validate the selected entity's slug directly
+ * - slug + slug          -> resolve BOTH and require the same uid
+ *
+ * API keys can verify UID anchors through their company selector or keyed
+ * membership. Slug anchors still fail closed because keys cannot read entities.
+ */
+async function resolveCompanyUidForAnchoredPath(token, opts) {
+    if (opts.anchorSlug === undefined) {
+        return getCompanyUid(token, opts.explicit);
+    }
+    if (looksLikeCompanyUid(opts.anchorSlug)) {
+        const selectedUid = await getCompanyUid(token, opts.explicit ?? (token.startsWith("hqk_") ? undefined : opts.anchorSlug));
+        if (selectedUid !== opts.anchorSlug) {
+            throw new Error(`Refusing anchored path: it names company '${opts.anchorSlug}' ` +
+                `but this command targets '${selectedUid}'. Pass a matching company or path.`);
+        }
+        return selectedUid;
+    }
+    if (token.startsWith("hqk_")) {
+        throw new Error(`Refusing anchored path under an API key: the anchor names ` +
+            `'${opts.anchorSlug}', and an API key cannot resolve a slug to verify ` +
+            `that is the company it is bound to. Pass the bucket-relative path.`);
+    }
+    if (opts.explicit !== undefined && looksLikeCompanyUid(opts.explicit)) {
+        // An explicit UID disambiguates duplicate slugs. Resolving the slug first
+        // would fail before the caller's unambiguous selector could be considered.
+        const response = await vaultApiFetch({
+            token,
+            path: `/entity/${encodeURIComponent(opts.explicit)}`,
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (response.status === 401)
+            throw new AuthError();
+        if (!response.ok) {
+            throw new Error(`Failed to resolve company '${opts.explicit}' (HTTP ${response.status})`);
+        }
+        const data = (await response.json());
+        if (data.entity?.uid !== opts.explicit ||
+            data.entity.type !== "company" ||
+            data.entity.slug !== opts.anchorSlug) {
+            throw new Error(`Refusing anchored path: cannot verify that company '${opts.explicit}' ` +
+                `has the anchored slug '${opts.anchorSlug}'. Pass a matching company or path.`);
+        }
+        return opts.explicit;
+    }
+    const anchorUid = await getCompanyUid(token, opts.anchorSlug);
+    if (opts.explicit === undefined)
+        return anchorUid;
+    const explicitUid = await getCompanyUid(token, opts.explicit);
+    if (explicitUid !== anchorUid) {
+        throw new Error(`Refusing anchored path: it names company '${opts.anchorSlug}' ` +
+            `(${anchorUid}) but this command targets '${opts.explicit}' ` +
+            `(${explicitUid}). Re-run with --company ${opts.anchorSlug}, or pass ` +
+            `the bucket-relative path.`);
+    }
+    return anchorUid;
+}
+/**
+ * The company an anchored path names, or `undefined` for a relative/personal
+ * path.
+ *
+ * Discarding this slug is what makes retargeting possible: strip the anchor,
+ * then resolve the company from somewhere else, and the operation lands on a
+ * DIFFERENT company than the operator pasted. Callers pair this with
+ * `normalizeCompanyFilePrefix` so the anchor either MATCHES the explicit
+ * `--company` (or is refused), or BECOMES the company when none was given.
+ */
+export function companySlugFromAnchor(prefix, personal) {
+    if (personal)
+        return undefined;
+    return stripRedundantCompanyScope(prefix)?.strippedSlug;
+}
+/**
+ * Normalize company paths at the CLI boundary, preserving personal keys.
+ *
+ * `mutating` marks a route that CHANGES access and has no preview or
+ * confirmation step (grant, share, unshare). Those refuse an anchored path
+ * outright rather than guessing, because stripping the anchor changes which
+ * objects the operation reaches and there is nothing downstream to catch it.
+ *
+ * `companySlug` is the company the command is actually targeting. When the
+ * anchor names a DIFFERENT company we refuse in every mode: stripping would
+ * silently retarget the operation at the active company, so
+ * `--company beta unshare <alpha-anchored-path>` would revoke a real grant in
+ * beta while leaving alpha untouched.
+ */
+function normalizeCompanyFilePrefix(prefix, options = {}) {
+    const scope = options.personal ? null : stripRedundantCompanyScope(prefix);
+    if (!scope)
+        return normalizeFilePrefix(prefix);
+    // A `cmp_…` reference is a UID, not a slug, so it can only be compared to the
+    // anchor by RESOLVING it — which this pure helper cannot do. Comparing the
+    // strings would refuse `--company cmp_acme` against an `acme` anchor even
+    // though both name the same company, and `getCompanyUid`'s ambiguity error
+    // explicitly tells callers to retry with `--company <uid>`. Skip the check
+    // rather than break that recovery path; the UID is authoritative either way.
+    if (options.companySlug !== undefined &&
+        !looksLikeCompanyUid(options.companySlug) &&
+        !looksLikeCompanyUid(scope.strippedSlug) &&
+        options.companySlug !== scope.strippedSlug) {
+        throw new Error(`Refusing anchored path '${prefix}': it names company ` +
+            `'${scope.strippedSlug}' but this command targets ` +
+            `'${options.companySlug}'. Stripping the anchor would apply the ` +
+            `operation to '${options.companySlug}' instead. Re-run with ` +
+            `--company ${scope.strippedSlug}, or pass the bucket-relative path.`);
+    }
+    // A bare anchor strips to nothing. The ACL routes would ship that empty
+    // prefix to a server that answers 400, so fail here with a message that says
+    // what to do instead. `deferRootReject` is for callers that already have a
+    // root guard with better copy — `runFilesDelete` says "Refusing to delete the
+    // vault root", which beats anything this generic helper could write.
+    if (!scope.prefix && !options.deferRootReject) {
+        // Route-specific: `--full` exists ONLY on `files share`. Suggesting it for
+        // `unshare` fails with an unknown option and names the opposite operation.
+        const advice = options.rootAdvice ??
+            "Pass a bounded bucket-relative path (e.g. 'projects/foo').";
+        throw new Error(`Refusing anchored path '${prefix}': it resolves to the vault root. ` +
+            advice);
+    }
+    if (options.mutating) {
+        throw new Error(`Refusing anchored path '${prefix}': the vault is already ` +
+            `company-scoped, so removing 'companies/${scope.strippedSlug}/' would ` +
+            `change which objects this affects. Retry with the bucket-relative ` +
+            `path '${normalizeFilePrefix(scope.prefix)}' if that is what you intend.`);
+    }
+    console.error(chalk.yellow(`Note: stripped redundant 'companies/${scope.strippedSlug}/' — the vault ` +
+        `is already company-scoped; using bucket-relative '${scope.prefix}'.`));
+    return normalizeFilePrefix(scope.prefix);
+}
 export async function runFilesDelete(params, deps = {}) {
     const confirm = deps.confirm ?? realConfirm;
-    // The vault is already company-scoped — a `companies/<slug>/` prefix is the HQ
-    // LOCAL tree layout, not a vault key, and the server 400s it (HQ-8F). Strip it
-    // here so a pasted local path is gracefully normalized to bucket-relative
-    // BEFORE the dry-run/preview (so the operator still sees the exact keys and
-    // confirms the right target). If stripping empties the prefix, the root-reject
-    // below catches it with a clear message.
-    const scope = stripRedundantCompanyScope(params.prefix);
-    if (scope) {
-        console.error(chalk.yellow(`Note: stripped redundant 'companies/${scope.strippedSlug}/' — the vault ` +
-            `is already company-scoped; using bucket-relative ` +
-            `'${scope.prefix || "(root)"}'.`));
-    }
-    const rawPrefix = scope ? scope.prefix : params.prefix;
-    // Normalize exactly as the share/unshare/acl paths do (trailing `/` → `/*`),
-    // then reject the root/empty prefix CLIENT-side so a typo never reaches the
-    // server as a vault-wide delete. The server enforces this too (defense in
-    // depth), but failing fast here is clearer and avoids a wasted round-trip.
-    const normalized = normalizeFilePrefix(rawPrefix);
+    // Strip the local company anchor before preview/confirmation (HQ-8F/HQ-CA).
+    // Personal keys are already bucket-relative and must keep any such anchor.
+    // Normalize trailing `/` to `/*`, then reject the root/empty prefix before
+    // any network call, including when stripping a bare company anchor empties it.
+    // The anchor names a company. Compare it with --company (refusing a
+    // mismatch), and when --company was omitted ADOPT it rather than letting the
+    // membership fallback pick a different company to delete from.
+    const anchorSlug = companySlugFromAnchor(params.prefix, params.personal);
+    const normalized = normalizeCompanyFilePrefix(params.prefix, {
+        personal: params.personal,
+        deferRootReject: true,
+        ...(params.companySlug !== undefined
+            ? { companySlug: params.companySlug }
+            : {}),
+    });
     if (normalized === "" || normalized === "*" || normalized === "/*") {
         console.error(chalk.red("Refusing to delete the vault root. Pass a bounded prefix (e.g. 'projects/foo/' or 'projects/foo/*') or an exact key."));
         process.exit(1);
     }
     const token = (await resolveVaultCredential()).token;
     // Personal scope resolves the vault server-side from the caller's identity —
-    // no company to look up. Company scope resolves the companyUid as before.
+    // no company to look up. Company scope resolves the companyUid through the
+    // anchor-aware resolver so an anchored path can never delete from a company
+    // other than the one it names.
     const companyUid = params.personal
         ? undefined
-        : await getCompanyUid(token, params.companySlug);
+        : await resolveCompanyUidForAnchoredPath(token, {
+            explicit: params.companySlug,
+            anchorSlug,
+        });
     const scopeArgs = params.personal
         ? { personal: true }
         : { companyUid };

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.