@indigoai-us/hq-cli 5.345.170 → 5.345.172

package/dist/commands/dm.js

@@ -5,7 +5,9 @@ import { resolveDestinationCompanyUid, vaultApiFetch } from "../utils/vault-api.
 import { isMachineIdentity } from "@indigoai-us/hq-cloud";
 import { peekIdToken } from "../utils/id-token.js";
 import { redactAgentInboxItem as redactInboxCredentials } from "../lib/agent-kit/inbox-redact.js";
-import { EMAIL_PATTERN, RECIPIENT_UID_PATTERN, defaultAudienceFor, recipientKindOf, } from "../lib/notify-recipient.js";
+import { classifyAgentInboxBody } from "../lib/agent-kit/inbox-state.js";
+import { EMAIL_PATTERN, RECIPIENT_UID_PATTERN, PERSON_AGENT_AUDIENCE_MESSAGE, PERSON_CANNOT_SEND_AGENT_CODE, callerMayUseAudience, defaultAudienceFor, recipientKindOf, } from "../lib/notify-recipient.js";
+import { callerIsMachinePrincipal } from "../lib/caller-principal.js";
 export { defaultAudienceFor, recipientKindOf };
 import { dmForwardCliEnabled } from "./dm-forward-flag.js";
 import { attachmentScopeForChannel, formatUploadedAttachments, personalScopeForCaller, uploadDmAttachments, validateAttachmentPaths, } from "./dm-attach.js";
@@ -120,29 +122,45 @@ export function matchChannelsByName(channels, name) {
  * eba06f59). Returns null when nothing or more than one contact matches. Pure.
  */
 export function matchContactByName(contacts, name) {
-    const target = name.trim().toLowerCase();
-    const targetSlug = channelSlug(name);
+    const unique = matchContactsByName(contacts, name);
+    return unique.length === 1 ? unique[0] : null;
+}
+/**
+ * Every distinct contact (person or bot) whose display name matches `name`,
+ * using the same rule as matchContactByName. A leading '@' is the explicit
+ * person/bot selector and is ignored for matching. Pure.
+ */
+export function matchContactsByName(contacts, name) {
+    const bare = name.trim().replace(/^@/, "");
+    const target = bare.toLowerCase();
+    const targetSlug = channelSlug(bare);
     if (!target)
-        return null;
+        return [];
     const hits = contacts.filter((c) => {
         if (!c.personUid)
             return false;
         const dn = c.displayName?.trim().toLowerCase();
         return Boolean(dn && (dn === target || (targetSlug && channelSlug(dn) === targetSlug)));
     });
-    const unique = [...new Map(hits.map((c) => [c.personUid, c])).values()];
-    return unique.length === 1 ? unique[0] : null;
+    return [...new Map(hits.map((c) => [c.personUid, c])).values()];
+}
+/** One line per ambiguous contact match, for a refusal message. Pure. */
+export function formatContactMatches(matches) {
+    return matches
+        .map((c) => `  ${c.displayName || "(no name)"}${c.email ? ` <${c.email}>` : ""}  ${c.personUid}`)
+        .join("\n");
 }
+/** Contacts, or null when the lookup failed (so callers can say so). */
 async function fetchContacts(token) {
     try {
         const res = await vaultApiFetch({ token, path: "/v1/notify/contacts" });
         if (!res.ok)
-            return [];
+            return null;
         const data = (await res.json());
-        return Array.isArray(data.contacts) ? data.contacts : [];
+        return Array.isArray(data.contacts) ? data.contacts : null;
     }
     catch {
-        return [];
+        return null;
     }
 }
 /**
@@ -427,6 +445,8 @@ export async function resolveDmPeerUid(token, recipient) {
 function friendlyDmError(status, code, fallback) {
     if (status === 401)
         return "Not authenticated — run `hq login` and try again.";
+    if (code === PERSON_CANNOT_SEND_AGENT_CODE)
+        return fallback?.trim() || PERSON_AGENT_AUDIENCE_MESSAGE;
     if (status === 404 || code === "RECIPIENT_NOT_FOUND") {
         return "Recipient not found or not reachable — you can only DM someone you share an active company with.";
     }
@@ -818,29 +838,47 @@ function explicitAudience(opts) {
     }
     return explicit;
 }
+/** An explicit agent/both audience from a person login. */
+export class PersonAudienceError extends Error {
+    constructor() {
+        super(PERSON_AGENT_AUDIENCE_MESSAGE);
+        this.name = "PersonAudienceError";
+    }
+}
 /**
  * Resolve the audience for a send. The default comes from the recipient kind
- * (`defaultAudienceFor`); `--for-human` maps to `human`; an explicit
- * `--audience` wins over `--for-human` (with a warning) and is validated.
+ * and the caller (`defaultAudienceFor`: always `human` for a person login);
+ * `--for-human` maps to `human`; an explicit `--audience` wins over
+ * `--for-human` (with a warning) and is validated. A person login passing
+ * `--audience agent|both` throws PersonAudienceError.
  */
-export function resolveSendAudience(opts, recipientKind, warn = (m) => console.error(chalk.yellow(m))) {
+export function resolveSendAudience(opts, recipientKind, warn = (m) => console.error(chalk.yellow(m)), machineCaller = callerIsMachinePrincipal()) {
     const explicit = explicitAudience(opts);
+    if (!callerMayUseAudience(explicit, machineCaller))
+        throw new PersonAudienceError();
     if (explicit !== undefined) {
         if (opts.forHuman) {
             warn("Both --audience " + explicit + " and --for-human were passed; using --audience " + explicit + ".");
         }
         return explicit;
     }
-    return opts.forHuman ? "human" : defaultAudienceFor(recipientKind);
+    return opts.forHuman ? "human" : defaultAudienceFor(recipientKind, machineCaller);
 }
 async function runDmSend(recipient, message, rawOpts) {
     // Validate an explicit --audience before any network call; the default is
     // applied once the recipient kind is known.
     explicitAudience(rawOpts);
+    // People never send agent-tagged messages: refuse before any network call.
+    const machineCaller = callerIsMachinePrincipal();
+    if (!callerMayUseAudience(rawOpts.audience, machineCaller)) {
+        console.error(chalk.red(PERSON_AGENT_AUDIENCE_MESSAGE));
+        process.exit(1);
+        return;
+    }
     const opts = { ...rawOpts };
     const withAudience = (kind) => ({
         ...rawOpts,
-        audience: resolveSendAudience(rawOpts, kind),
+        audience: resolveSendAudience(rawOpts, kind, undefined, machineCaller),
     });
     // --channel <name> is an explicit channel target; the positional carries the
     // message (recipient slot), e.g. `hq dm --channel vyg-dev "hello"`.
@@ -874,16 +912,46 @@ async function runDmSend(recipient, message, rawOpts) {
     // A bare name or #hash addresses a named DM channel.
     const channelName = parseChannelName(recipient);
     if (channelName !== null) {
-        // A bare word (no '#') may name a person as well as a channel. Prefer the
-        // exact person and say so; '#name' or --channel always means the channel.
-        const person = recipient.trim().startsWith("#")
-            ? null
-            : matchContactByName(await fetchContacts(await ensureCognitoToken()), channelName);
+        // A bare word may name a person or bot as well as a channel. Prefer the
+        // exact person/bot and say so; '#name' or --channel always means the
+        // channel, '@name' always means a person/bot. Several same-named
+        // contacts are ambiguous: refuse with the list rather than fall through
+        // to a channel of that name (feedback eba06f59).
+        const typed = recipient.trim();
+        const explicitPerson = typed.startsWith("@");
+        const bare = channelName.replace(/^@/, "");
+        let person = null;
+        if (!typed.startsWith("#")) {
+            const contacts = await fetchContacts(await ensureCognitoToken());
+            if (contacts === null) {
+                // Without contacts we cannot tell a person/bot from a channel, so a
+                // bare name must not guess the channel either.
+                console.error(chalk.red(`Could not load your contacts to resolve '${typed}'; nothing was sent. ` +
+                    `Use their email or prs_/agt_ uid for a person or bot, or '#${bare}' or --channel ${bare} to post to the channel.`));
+                process.exit(1);
+                return;
+            }
+            else {
+                const matches = matchContactsByName(contacts, bare);
+                if (matches.length > 1) {
+                    console.error(chalk.red(`'${bare}' matches ${matches.length} people or bots; nothing was sent. Use an email or uid:\n${formatContactMatches(matches)}\n` +
+                        `Use '#${bare}' or --channel ${bare} for a channel.`));
+                    process.exit(1);
+                    return;
+                }
+                person = matches[0] ?? null;
+            }
+            if (!person && explicitPerson) {
+                console.error(chalk.red(`No person or bot named '${bare}' in your contacts; nothing was sent. Use '#${bare}' for a channel.`));
+                process.exit(1);
+                return;
+            }
+        }
         if (!person?.personUid) {
             await runChannelSend(channelName, message, withAudience("channel"));
             return;
         }
-        console.log(chalk.dim(`Resolved '${channelName}' to person ${person.displayName || person.email || person.personUid} (${person.personUid}). Use '#${channelName}' or --channel ${channelName} to post to a channel instead.`));
+        console.log(chalk.dim(`Resolved '${bare}' to person ${person.displayName || person.email || person.personUid} (${person.personUid}). Use '#${bare}' or --channel ${bare} to post to a channel instead.`));
         recipient = person.personUid;
     }
     Object.assign(opts, withAudience(recipientKindOf(recipient)));
@@ -1492,23 +1560,46 @@ async function runAgentInbox(token, agentUid, opts) {
         console.error(chalk.red(`GET ${route} → ${res.status}`));
         process.exit(1);
     }
-    const data = (await res.json().catch(() => ({})));
-    let items = (Array.isArray(data.messages) ? data.messages : []).map(redactAgentInboxItem);
+    // Same guard as `hq agent inbox` (hq-cli #2155): a 200 alone does not
+    // certify the read. A decode failure stays undefined for the classifier;
+    // parser errors and response bytes are never echoed.
+    const classified = classifyAgentInboxBody(await res.json().catch(() => undefined));
+    if (classified.status === "invalid") {
+        console.error(chalk.red(`GET ${route} returned an invalid response; the inbox could not be read, and nothing was acknowledged.`));
+        process.exit(1);
+        return;
+    }
+    const partial = classified.status === "partial";
+    if (partial) {
+        console.error(chalk.yellow("The server inbox contained invalid messages; showing the valid ones only, which may be incomplete."));
+    }
+    let items = classified.items.map(redactAgentInboxItem);
     if (opts.limit && Number(opts.limit) > 0)
         items = items.slice(0, Number(opts.limit));
     if (opts.json) {
         console.log(JSON.stringify(items, null, 2));
     }
     else if (items.length === 0) {
-        console.log(chalk.dim("No pending inbox items."));
+        console.log(chalk.dim(partial
+            ? "No pending inbox items can be confirmed; the server inbox could not be read completely."
+            : "No pending inbox items."));
     }
     else {
         console.log(chalk.green(`${items.length} pending inbox item${items.length === 1 ? "" : "s"}:`));
         for (const item of items)
             console.log(`\n${formatAgentInboxItem(item)}`);
     }
-    if (opts.markRead) {
+    if (opts.markRead && partial) {
+        // An incomplete read cannot show what --mark-read would hide, so ack nothing.
+        const n = items.length;
+        const ids = items.map((item) => item.id).join(", ");
+        console.error(chalk.yellow(`--mark-read skipped: the inbox read was incomplete, so ${n} ${n === 1 ? "item was" : "items were"} not acked` +
+            `${opts.limit ? " (count reflects --limit)" : ""}` +
+            `${n > 0 ? `: ${ids}. Ack individually with \`hq agent inbox done <id>\`.` : "."}`));
+    }
+    if (opts.markRead && !partial) {
         let acked = 0;
+        let failed = 0;
         for (const item of items) {
             const id = typeof item.messageId === "string" ? item.messageId : typeof item.id === "string" ? item.id : null;
             if (!id)
@@ -1516,9 +1607,13 @@ async function runAgentInbox(token, agentUid, opts) {
             const ack = await vaultApiFetch({ token, path: `${route}/${encodeURIComponent(id)}/ack`, method: "POST" });
             if (ack.ok)
                 acked += 1;
+            else
+                failed += 1;
         }
         if (!opts.json && acked > 0)
             console.log(chalk.dim(`\nAcked ${acked}.`));
+        if (failed > 0)
+            console.error(chalk.yellow(`${failed} item${failed === 1 ? "" : "s"} could not be acked.`));
     }
 }
 async function runDmInbox(opts) {
@@ -1729,7 +1824,7 @@ async function runDmChannel(target, opts) {
 export function registerDmCommand(program) {
     const dm = program
         .command("dm")
-        .description("Send and read direct messages, and manage connection requests. Messages to a person send to them; messages to an agent, a channel or a group are tagged for agents and folded away from people by default. Pass --for-human or --audience human|agent|both to override.");
+        .description("Send and read direct messages, and manage connection requests. Messages sent from a person login are always tagged for people. When an agent or bot sends, messages to an agent, a channel or a group are tagged for agents and folded away from people by default. Pass --for-human or --audience human to tag a message for people; --audience agent|both is for agents and bots only.");
     dm
         .command("send [recipient] [message]", { isDefault: true, hidden: true })
         .description('Send a direct message. RECIPIENT can be a person (email, personUid, or agentUid), a GROUP DM (comma-separated: "a@x.com,b@y.com"), or one of your DM CHANNELS by name — bare (hq dm vyg-dev "hi"), hash form (hq dm "#vyg-dev" "hi"), or via --channel (hq dm --channel vyg-dev "hi"). A person receives a DM as an HQ Sync notification; an agent receives it in its durable box inbox. If you aren\'t connected yet, it sends a connection request that holds your message. See your channels with `hq channels`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @"Jacob Posel") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare "@" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.\n\nCHANNEL THREADS: `hq dm <channel> --thread <eventId> "…"` replies under an existing root (the request carries rootEventId). `--thread last` replies to your most recent top-level message in that channel. Copy a root eventId from `hq dm channel <name>`, which prints each root\'s id and indents replies underneath.')
@@ -1742,7 +1837,7 @@ export function registerDmCommand(program) {
         .option("--details-file <path>", "Read the details from a file (1:1 DMs; channel sends also supported)")
         .option("--at <iso>", "Schedule delivery at an ISO8601 time (store-and-forward; delivered within ~60s of the time; 1:1 DMs only)")
         .option("--in <duration>", "Schedule delivery after a relative delay: 30s, 10m, 2h, 1d (1:1 DMs only)")
-        .option("--audience <human|agent|both>", "Tag who this message is for: human (a person must read it), agent (progress/status, hidden from humans by default), or both. Default: human for a person, agent for an agent, a channel or a group. Wins over --for-human.")
+        .option("--audience <human|agent|both>", "Tag who this message is for: human (a person must read it), agent (progress/status, hidden from humans by default), or both. agent and both are for agents and bots only; a person login always sends human. Default for agents and bots: human for a person, agent for an agent, a channel or a group. Wins over --for-human.")
         .option("--for-human", "Tag the message for people (alias for --audience human).")
         .option("--attach <path>", "Upload a local file and attach it to the message (repeatable, up to 5 files, 25 MB each). 1:1 DMs and named channels; the file lands in the conversation's vault scope and the recipient can open it. Not available for group DMs or scheduled sends.", (value, previous = []) => [...previous, value])
         .action(async (recipient, message, opts) => {

package/dist/commands/files.d.ts

@@ -78,6 +78,7 @@ export declare function registerFilesCommand(program: Command): Command;
  * whether it is a folder (`Makefile`, `bin/hq`); resolveBareSharePrefix asks
  * the vault.
  */
+export declare function isSingleSegmentWildcardPrefix(prefix: string): boolean;
 export declare function looksLikeBareFolderPrefix(prefix: string): boolean;
 /**
  * Refuse a bare prefix that would become a malformed grant if it were

package/dist/commands/files.js

@@ -164,7 +164,7 @@ export function formatShareSessionError(err) {
 export function registerFilesCommand(program) {
     const files = program
         .command("files")
-        .description("Manage file access controls in HQ vault. A trailing folder slash (foo/) is a private folder; the quoted glob 'foo/*' shares all children.")
+        .description("Manage file access controls in HQ vault. A trailing folder slash (foo/) is a private folder; the quoted glob 'foo/*' shares all children, and a quoted 'clients/*/reports' shares that folder under every client.")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
     // An exported HQ_API_KEY must never fall back to the caller's Cognito session
     // (that would ignore the key's scope entirely), so every subcommand is gated.
@@ -193,7 +193,7 @@ export function registerFilesCommand(program) {
     });
     files
         .command("share [paths...]")
-        .description("Share file paths. foo/ is a private folder (children stay creator-only); quote the shared-folder glob 'foo/*' so the shell passes it literally. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.")
+        .description("Share file paths. foo/ is a private folder (children stay creator-only); quote the shared-folder glob 'foo/*', or a one-folder wildcard such as 'clients/*/reports', so the shell passes it literally. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.")
         .option("--with <principal>", "Email address, group id, company Outpost id (out_...), or '@all' to share with every active company member")
         .option("--permission <level>", "Permission level (only with --with): read | write")
         .option("--exact", "With --with: grant exactly the object named by <prefix>, even when it looks like a folder (by default a bare folder name such as 'knowledge' is granted as the folder glob 'knowledge/*').")
@@ -763,6 +763,8 @@ export function registerFilesCommand(program) {
 async function warnIfEmptySharePrefix(params) {
     if (isPrivateFolderPattern(params.prefix))
         return;
+    if (isSingleSegmentWildcardPrefix(params.prefix))
+        return;
     let enabled;
     try {
         enabled = await resolveCompanyFlagGate(params.companyUid, params.token, FILES_SHARE_EMPTY_PREFIX_WARNING_FLAG, { fallback: false }, () => false);
@@ -879,9 +881,21 @@ async function resolveMentionPersonUid(mention, companySlug) {
  * whether it is a folder (`Makefile`, `bin/hq`); resolveBareSharePrefix asks
  * the vault.
  */
+export function isSingleSegmentWildcardPrefix(prefix) {
+    const body = prefix.endsWith("/*") ? prefix.slice(0, -2) : prefix;
+    const segments = body.split("/");
+    if (segments.some((segment) => segment.length === 0))
+        return false;
+    if (segments.some((segment) => segment !== "*" && segment.includes("*")))
+        return false;
+    const wildcards = segments.filter((segment) => segment === "*").length;
+    return wildcards === 1 && wildcards < segments.length;
+}
 export function looksLikeBareFolderPrefix(prefix) {
     if (prefix === "*" || prefix.endsWith("/") || prefix.endsWith("/*"))
         return false;
+    if (isSingleSegmentWildcardPrefix(prefix))
+        return false;
     const last = prefix.slice(prefix.lastIndexOf("/") + 1);
     return last.length > 0 && !last.includes(".");
 }
@@ -894,8 +908,12 @@ export function malformedBareSharePrefix(prefix) {
     if (!looksLikeBareFolderPrefix(prefix))
         return null;
     if (prefix.includes("*")) {
-        return (`'${prefix}' has a '*' inside a path segment. Only a whole trailing '/*' segment ` +
-            `(for example 'knowledge/*') or '*' alone (--full) is a glob.`);
+        const reason = prefix.split("/").some((segment) => segment !== "*" && segment.includes("*"))
+            ? "has a '*' inside a path segment"
+            : "has more than one '*' folder";
+        return (`'${prefix}' ${reason}. A '*' must be a whole folder name: once per path ` +
+            `(for example 'clients/*/reports'), as a trailing '/*' (for example 'knowledge/*'), ` +
+            `or '*' alone (--full).`);
     }
     if (prefix.split("/").some((segment) => segment.length === 0)) {
         return `'${prefix}' has an empty path segment. Pass a company-relative path such as 'knowledge'.`;

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

@@ -161,7 +161,10 @@ export interface InstallInput {
         placement: "header";
         header: string;
     };
+    scope?: ConnectScope;
 }
+export type ConnectScope = "personal" | "company";
+export declare function scopeUnavailableMessage(scope: ConnectScope): string;
 export declare function installIntegration(token: string, companyUid: string, input: InstallInput): Promise<InstallResult>;
 export declare function uninstallIntegration(token: string, companyUid: string, target: {
     installationId: string;
@@ -227,6 +230,7 @@ export interface OAuthStartInput {
      * direct `mcpUrl` path.
      */
     scopes?: string[];
+    scope?: ConnectScope;
 }
 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-api.js

@@ -53,6 +53,22 @@ export async function discoverDocs(token, companyUid, docsUrl) {
         await raiseForResponse(res, "Failed to read that documentation page");
     return (await res.json());
 }
+export function scopeUnavailableMessage(scope) {
+    const flag = scope === "personal" ? "--personal" : "--company-owned";
+    return ("Personal and company integrations aren't turned on for this company yet. " +
+        `Run the command again without ${flag} to connect the usual way.`);
+}
+async function raiseForConnectResponse(res, fallback, scope) {
+    try {
+        return await raiseForResponse(res, fallback);
+    }
+    catch (error) {
+        if (scope && error instanceof IntegrationsCliError && error.status === 404 && !error.code) {
+            throw new IntegrationsCliError(scopeUnavailableMessage(scope), { expected: true, status: 404 });
+        }
+        throw error;
+    }
+}
 export async function installIntegration(token, companyUid, input) {
     const res = await vaultApiFetch({
         token,
@@ -62,7 +78,7 @@ export async function installIntegration(token, companyUid, input) {
     });
     if (!res.ok) {
         try {
-            await raiseForResponse(res, "Failed to connect the app");
+            await raiseForConnectResponse(res, "Failed to connect the app", input.scope);
         }
         catch (error) {
             if (error instanceof IntegrationsCliError &&
@@ -106,7 +122,7 @@ export async function startOAuth(token, companyUid, input) {
         body: { companyUid, ...input },
     });
     if (!res.ok)
-        await raiseForResponse(res, "Failed to start sign-in");
+        await raiseForConnectResponse(res, "Failed to start sign-in", input.scope);
     return (await res.json());
 }
 export async function completeOAuth(token, companyUid, input) {

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

@@ -27,7 +27,7 @@ import { type ResidentCommandLeaseOptions } from "../utils/resident-package-prel
 import { consoleOrigin } from "../utils/console-origin.js";
 export { consoleOrigin };
 import type { AdminConnection } from "./integrations-core.js";
-import { type InstallInput } from "./integrations-api.js";
+import { type ConnectScope, type InstallInput } from "./integrations-api.js";
 interface ConnectOptions {
     company?: string;
     entryId?: string;
@@ -54,7 +54,10 @@ interface ConnectOptions {
      * to a person and check `hq integrations list` afterwards.
      */
     linkOnly?: boolean;
+    personal?: boolean;
+    companyOwned?: boolean;
 }
+export declare function connectScopeFromOptions(opts: Pick<ConnectOptions, "personal" | "companyOwned">): ConnectScope | undefined;
 /**
  * Validate `--auth` against the supported enum, rejecting an unknown value
  * before anything is installed. A finite provider/runtime option must never be
@@ -69,7 +72,7 @@ export declare function shellQuote(value: string): string;
 /** Everything the connect verbs need to name one app to hq-pro. */
 interface ConnectTarget {
     /** Install/OAuth identity fields, exactly as hq-pro expects them. */
-    ref: Pick<InstallInput, "domain" | "query" | "catalogEntryId" | "discoveryReceiptId" | "mcpUrl" | "provider" | "displayName" | "docsUrl">;
+    ref: Pick<InstallInput, "domain" | "query" | "catalogEntryId" | "discoveryReceiptId" | "mcpUrl" | "provider" | "displayName" | "docsUrl" | "scope">;
     /** Best-known auth mode before hq-pro is asked; `undefined` = unknown. */
     authClass?: "none" | "key" | "oauth";
     /** Human label for prompts and success lines. */
@@ -109,6 +112,10 @@ export declare function bringYourOwnClientHandoff(target: ConnectTarget, opts: C
  * built, so the hint always names the URL Google will actually be sent.
  */
 export declare function googleClientTypeHint(clientId: string, authorizationUrl: string): string | null;
-export declare function findAlreadyConnected(connections: readonly AdminConnection[], app: string): AdminConnection | undefined;
+export interface ConnectOwnership {
+    scope: ConnectScope;
+    viewerPersonUid?: string;
+}
+export declare function findAlreadyConnected(connections: readonly AdminConnection[], app: string, ownership?: ConnectOwnership): AdminConnection | undefined;
 export declare function registerConnectCommands(integrations: Command): void;
 //# sourceMappingURL=integrations-connect.d.ts.map

package/dist/commands/integrations-connect.js

@@ -31,7 +31,7 @@ import { consoleOrigin } from "../utils/console-origin.js";
 export { consoleOrigin };
 import { getCompanyUid } from "../utils/vault-api.js";
 import { redactSensitiveUrl, redactUrlsInText } from "../utils/redact-url.js";
-import { IntegrationsCliError, bareProvider, connectionDomain, fetchAdminSurface, printJson, revokedConnectionDetails, resolveConnection, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, connectionAccountLabel, connectionDomain, connectionOwnerLabel, fetchAdminSurface, printJson, revokedConnectionDetails, resolveConnection, } from "./integrations-core.js";
 import { completeOAuth, discoverDocs, installIntegration, listCatalog, pullBlueprint, startOAuth, } from "./integrations-api.js";
 import { OAUTH_LOOPBACK_TIMEOUT_CODE, startLoopbackListener, } from "./integrations-oauth.js";
 /** hq-pro's machine code for "this endpoint needs a browser sign-in". */
@@ -103,6 +103,19 @@ const BRING_YOUR_OWN_CLIENT_CODES = new Set([
     "OAUTH_REGISTRATION_UNSUPPORTED",
     "CLIENT_REGISTRATION_REFUSED",
 ]);
+export function connectScopeFromOptions(opts) {
+    if (opts.personal && opts.companyOwned) {
+        throw new IntegrationsCliError("--personal and --company-owned cannot be used together; pick one.", { expected: true });
+    }
+    if (opts.personal)
+        return "personal";
+    if (opts.companyOwned)
+        return "company";
+    return undefined;
+}
+function scopeFlag(scope) {
+    return scope === "personal" ? "--personal" : "--company-owned";
+}
 /**
  * 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
@@ -758,6 +771,10 @@ async function consoleHandoff(target, opts) {
     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.`));
     }
+    const scope = connectScopeFromOptions(opts);
+    if (scope) {
+        console.error(chalk.yellow(`Note: ${scopeFlag(scope)} cannot be carried into a console sign-in; choose who owns ${target.label} on the console page.`));
+    }
     if (url && opts.browser !== false)
         await open(url).catch((error) => warnBrowserOpenFailure(error));
     console.error(chalk.dim("When the browser says it connected, run `hq integrations list` to confirm."));
@@ -820,6 +837,9 @@ function byoClientCommand(target, opts) {
     // caller a line that reproduces the failure they are recovering from.
     if (opts.scopes)
         parts.push(`--scopes ${shellQuote(opts.scopes)}`);
+    const scope = connectScopeFromOptions(opts);
+    if (scope)
+        parts.push(scopeFlag(scope));
     return parts.join(" ");
 }
 /**
@@ -1035,6 +1055,7 @@ async function targetForAccessKeyConnect(token, companyUid, target, opts) {
     return {
         ref: {
             mcpUrl,
+            ...(target.ref.scope ? { scope: target.ref.scope } : {}),
             ...(opts.provider ? { provider: opts.provider } : blueprint.provider ? { provider: blueprint.provider } : {}),
             ...(opts.displayName
                 ? { displayName: opts.displayName }
@@ -1079,7 +1100,9 @@ function reportInstall(result, opts, expectedRevivedConnectionId) {
  * 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 resolved = await resolveTarget(token, companyUid, app, opts, expectedRevivedConnectionId !== undefined);
+    const scope = connectScopeFromOptions(opts);
+    const target = scope ? { ...resolved, ref: { ...resolved.ref, scope } } : resolved;
     const authMode = opts.authHeader
         ? "key"
         : opts.auth ?? target.authClass;
@@ -1205,7 +1228,16 @@ function isSettledInstallation(connection) {
     const status = connection.installation?.status?.trim().toLowerCase();
     return status === undefined || status === "" || status === "installed";
 }
-export function findAlreadyConnected(connections, app) {
+function hasRequestedOwnership(connection, ownership) {
+    const ownerType = connection.ownerType;
+    if (ownership.scope === "personal") {
+        return (ownerType === "person" &&
+            Boolean(ownership.viewerPersonUid) &&
+            connection.ownerId === ownership.viewerPersonUid);
+    }
+    return ownerType === undefined || ownerType === "company" || ownerType === "legacy";
+}
+export function findAlreadyConnected(connections, app, ownership) {
     const want = app.trim().toLowerCase();
     if (want === "")
         return undefined;
@@ -1215,6 +1247,8 @@ export function findAlreadyConnected(connections, app) {
             return false;
         if (!isSettledInstallation(connection))
             return false;
+        if (ownership && !hasRequestedOwnership(connection, ownership))
+            return false;
         const domain = (connectionDomain(connection) ?? "").toLowerCase();
         if (domain === want || domain.endsWith(`.${want}`))
             return true;
@@ -1254,22 +1288,31 @@ async function refuseIfAlreadyConnected(token, companyUid, app, opts) {
     // the deliberate "yes, add another one" escape hatch.
     if (!app || opts.force || opts.mcpUrl || opts.docsUrl || opts.entryId)
         return false;
+    const requestedScope = connectScopeFromOptions(opts);
     let connections;
     let viewer;
+    let personalConnect;
     try {
         const surface = await fetchAdminSurface(token, companyUid);
         connections = surface.connections ?? [];
         viewer = surface.viewer;
+        personalConnect = surface.capabilities?.personalConnect === true;
     }
     catch {
         // Never let this convenience check block a connect. If the list cannot be
         // read, fall through and let the real flow report whatever is wrong.
         return false;
     }
-    const existing = findAlreadyConnected(connections, app);
+    const scope = requestedScope ?? (personalConnect ? "personal" : undefined);
+    const ownership = scope
+        ? { scope, ...(viewer?.personUid ? { viewerPersonUid: viewer.personUid } : {}) }
+        : undefined;
+    const existing = findAlreadyConnected(connections, app, ownership);
     if (!existing)
         return false;
     const slug = bareProvider(existing.provider);
+    const owner = connectionOwnerLabel(existing);
+    const account = connectionAccountLabel(existing);
     if (opts.json) {
         printJson({
             ok: true,
@@ -1277,11 +1320,14 @@ async function refuseIfAlreadyConnected(token, companyUid, app, opts) {
             provider: slug,
             connection: existing.id,
             ...(connectionDomain(existing) ? { domain: connectionDomain(existing) } : {}),
+            ...(existing.ownerType ? { ownerType: existing.ownerType } : {}),
+            ...(existing.accountLabel ? { accountLabel: existing.accountLabel } : {}),
         });
         return true;
     }
     const label = redactUrlsInText(existing.installation?.displayName ?? slug);
-    console.log(chalk.green(`${label} is already connected.`));
+    const detail = [owner, account].filter(Boolean).join(", ");
+    console.log(chalk.green(`${label} is already connected${detail ? ` (${detail})` : ""}.`));
     if (connectedBySomeoneElse(existing, viewer)) {
         // Members may add apps and reconnect their own, but replacing a connection
         // someone else created stays with an owner or admin: the server refuses
@@ -1291,7 +1337,7 @@ async function refuseIfAlreadyConnected(token, companyUid, app, opts) {
         return true;
     }
     console.log(chalk.dim(`  Sign in again:  hq integrations reconnect --provider ${slug}\n` +
-        `  Add a second:   hq integrations connect ${shellQuote(app)} --force`));
+        `  Add a second:   hq integrations connect ${shellQuote(app)}${requestedScope ? ` ${scopeFlag(requestedScope)}` : ""} --force`));
     return true;
 }
 export function registerConnectCommands(integrations) {
@@ -1425,8 +1471,11 @@ export function registerConnectCommands(integrations) {
         .option("--timeout <seconds>", "How long to wait for a browser sign-in (default 300)")
         .option("--link-only", "Print the sign-in link and exit without waiting; the sign-in finishes on the HQ console")
         .option("--force", "Connect again even if this app is already connected")
+        .option("--personal", "Connect it as your own personal connection (not --company <slug>, which picks the company)")
+        .option("--company-owned", "Connect it as a connection the whole company owns (needs permission to add company apps)")
         .option("--json", "Machine-readable output")
         .action(async (app, opts) => {
+        connectScopeFromOptions(opts);
         assertAuthMode(opts.auth);
         assertAuthHeader(opts.authHeader);
         if (opts.authHeader && opts.auth !== undefined && opts.auth !== "key") {
@@ -1453,6 +1502,8 @@ export function registerConnectCommands(integrations) {
         .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("--personal", "With --connect: re-add it as your own personal connection")
+        .option("--company-owned", "With --connect: re-add it as a connection the whole company owns")
         .option("--json", "Machine-readable output")
         .action(async (app, opts) => {
         // Same validation as `connect`. Without it a typo like `--auth oauth2`
@@ -1460,11 +1511,19 @@ export function registerConnectCommands(integrations) {
         // silently reinstalls with auto-detection — the caller believes they
         // forced a mode that was never applied.
         assertAuthMode(opts.auth);
+        const scope = connectScopeFromOptions(opts);
+        if (scope && !opts.connect) {
+            throw new IntegrationsCliError(`${scopeFlag(scope)} only applies with --connect, when a revoked app is added again.`, { expected: true });
+        }
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
         const connection = await resolveConnection(token, companyUid, app, opts, {
             allowSingleRevoked: Boolean(opts.connect),
         });
+        if (scope && connection.status !== "revoked") {
+            throw new IntegrationsCliError(`${scopeFlag(scope)} only applies when --connect adds a revoked app again; this one is ${connection.status}. ` +
+                "A reconnect keeps the connection's current owner.", { expected: true });
+        }
         if (connection.status === "revoked") {
             const details = revokedConnectionDetails(connection, opts.company);
             if (!opts.connect) {
@@ -1492,6 +1551,11 @@ export function registerConnectCommands(integrations) {
                 ...(connection.installation?.displayName
                     ? { displayName: connection.installation.displayName }
                     : {}),
+                ...(connection.ownerType === "company"
+                    ? { scope: "company" }
+                    : connection.ownerType === "person"
+                        ? { scope: "personal" }
+                        : {}),
             },
             ...(opts.auth ? { authClass: opts.auth } : {}),
             label: connection.installation?.displayName ?? bareProvider(connection.provider),