@indigoai-us/hq-cli 5.345.165 → 5.345.168

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [5.345.168] — 2026-10-24
+- `hq dm` now picks the default audience from the recipient when no audience flag is passed. A 1:1 DM to a person (email, `prs_` uid, or a bare name that resolves to a person) sends `audience: "human"`. A 1:1 DM to an agent (`agt_` uid), a group DM and a channel post send `audience: "agent"`, so script and lane messages stay out of people's conversations. Scheduled sends (`--at`, `--in`) follow the same rule. Pass `--for-human` (alias for `--audience human`) to tag any message for people; an explicit `--audience human|agent|both` wins over `--for-human`, with a warning on stderr, and is validated on every path. `hq core delegate send` tags the pickup DM `audience: "both"`, `hq dm-bind post` keeps the channel default (`audience: "agent"`) for its automated status posts, and the agent MCP `hq_dm_send` tool, `hq agents message` and the `hq access` grant request apply the recipient rule. Reading commands (inbox, thread, channel) are unchanged, and `hq dm forward` does not set an audience.
+- `hq scan secrets` no longer exits 2 when a repo's `.gitleaks.toml` allowlist is rejected. In staged and file scans it now prints a fixed warning that quotes no part of the file and scans with no repo allowlist, so a real key is still reported (exit 1) and a commit that replaces a bad allowlist is not blocked. An unknown `--allowlist-rev` still exits 2.
+
+## [5.345.166] — 2026-10-24
+- `hq integrations approve` now says why an approved call did not run. When an app refuses it, the CLI prints the app's own reason, such as Slack's refusal to send into a Slack Connect channel. Before this it printed only "failed (rejected)". With an older server it prints the rejection code instead. `hq integrations pending --history` adds a `Why:` line for decided calls that did not run. The approve command printed after a queued call keeps `--company` when you passed it. Before printing, the reason is cleaned of terminal escape codes, credentials and credential-bearing links, and it is capped at 500 characters. Feedback 15e7593c-50e5-4e6a-ae3a-342d618363c0.
+- The bundled sync engine now uses hq-cloud 6.18.101, the current npm `latest`.
+  A 403 from the flags endpoint (for example a stale company in the local
+  manifest) is now held as `false` for an hour instead of being re-read and
+  logged on every telemetry pass (hq-cloud #1046).
+- `hq doctor` no longer counts runner telemetry errors as sync receiver permission refusals. A failed outcome-flag read ("hq-flags: resolve returned 403") for a company you are not a member of used to inflate `sync.runtime.receiver-permission`; only the receiver's own events are counted now.
+- The bundled shell fallbacks for `rebuild-index` all, orchestrator, public-knowledge, reports, social-drafts, threads, and workers now print the same usage as the native command for `--help`/`-h` and exit without writing. Before, they ignored the flag and rebuilt the index, which failed the published core command parity check.
+
 ## [5.345.165] — 2026-10-23
 - `hq billing sponsor grant <email|prs_id> --company <slug>` lets a company owner or admin put a member's personal plan on the company bill without a request first; `--all-members` does it for every active member and reports each person as covered, already covered, or skipped. `hq billing sponsor ungrant <email|prs_id>` takes it off again. hq-pro checks the owner/admin role and active membership.
 - `hq scan secrets <files...>` takes `--repo <dir>`, which applies that repo's committed `.gitleaks.toml` allowlists to a file scan, matching each file by its path relative to the repo, as a staged scan does. `--snapshot-root <dir>` (with `--repo`) matches files laid out as `<dir>/<commit>/<repo path>`, the history copies `commit-secret-scan.sh pr-check` writes, as `<repo path>`. Findings still name the files as given. Before this, a file scan ignored the repo's allowlists, so pr-check failed on false positives the commit gate already allowed. Without `--repo` a file scan is unchanged.

package/assets/scaffold/core/scripts/hq-delegate-send.sh

@@ -283,7 +283,7 @@ if ! jq '.status = "sending"' "$MANIFEST" > "$TMP_MANIFEST" || ! mv "$TMP_MANIFE
   rm -f "$TMP_MANIFEST"
   die "could not persist sending state; no DM attempted"
 fi
-DM_OUT="$(hq dm "$PRINCIPAL" "$HEADLINE" --prompt-file "$PROMPT" --details-file "$BRIEF")" \
+DM_OUT="$(hq dm "$PRINCIPAL" "$HEADLINE" --audience both --prompt-file "$PROMPT" --details-file "$BRIEF")" \
   || die "hq dm delivery outcome is uncertain; status is sending, inspect DM history before retrying"
 
 EVENT_ID="$(printf '%s' "$DM_OUT" | grep -oE 'eventId[: ]+[A-Za-z0-9_-]+' | head -1 | sed -E 's/eventId[: ]+//' || true)"

package/assets/scaffold/core/scripts/rebuild-all-indexes.sh

@@ -11,6 +11,17 @@
 
 set -uo pipefail
 
+# Help must never write: print the same usage as `hq core rebuild-index all --help`.
+for arg in "$@"; do
+  if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
+    printf '%s\n' \
+      'Usage: hq core rebuild-index all [--accept]' \
+      '' \
+      'Regenerate every INDEX.md across the HQ tree. Help performs no writes.'
+    exit 0
+  fi
+done
+
 HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 cd "$HQ_ROOT"
 

package/assets/scaffold/core/scripts/rebuild-orchestrator-index.sh

@@ -12,6 +12,17 @@
 
 set -euo pipefail
 
+# Help must never write: print the same usage as `hq core rebuild-index orchestrator --help`.
+for arg in "$@"; do
+  if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
+    printf '%s\n' \
+      'Usage: hq core rebuild-index orchestrator [--accept]' \
+      '' \
+      'Regenerate the orchestrator workspace INDEX.md. Help performs no writes.'
+    exit 0
+  fi
+done
+
 HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 cd "$HQ_ROOT"
 

package/assets/scaffold/core/scripts/rebuild-public-knowledge-index.sh

@@ -7,6 +7,17 @@
 
 set -euo pipefail
 
+# Help must never write: print the same usage as `hq core rebuild-index public-knowledge --help`.
+for arg in "$@"; do
+  if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
+    printf '%s\n' \
+      'Usage: hq core rebuild-index public-knowledge [--accept]' \
+      '' \
+      'Regenerate core/knowledge/public/INDEX.md. Help performs no writes.'
+    exit 0
+  fi
+done
+
 HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 cd "$HQ_ROOT"
 

package/assets/scaffold/core/scripts/rebuild-reports-index.sh

@@ -8,6 +8,17 @@
 
 set -euo pipefail
 
+# Help must never write: print the same usage as `hq core rebuild-index reports --help`.
+for arg in "$@"; do
+  if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
+    printf '%s\n' \
+      'Usage: hq core rebuild-index reports [--accept]' \
+      '' \
+      'Regenerate the reports INDEX.md. Help performs no writes.'
+    exit 0
+  fi
+done
+
 HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 cd "$HQ_ROOT"
 

package/assets/scaffold/core/scripts/rebuild-social-drafts-index.sh

@@ -8,6 +8,17 @@
 
 set -euo pipefail
 
+# Help must never write: print the same usage as `hq core rebuild-index social-drafts --help`.
+for arg in "$@"; do
+  if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
+    printf '%s\n' \
+      'Usage: hq core rebuild-index social-drafts [--accept]' \
+      '' \
+      'Regenerate workspace/social-drafts/INDEX.md. Help performs no writes.'
+    exit 0
+  fi
+done
+
 HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 # shellcheck source=core/scripts/lib/portable.sh
 . "$HQ_ROOT/core/scripts/lib/portable.sh"

package/assets/scaffold/core/scripts/rebuild-threads-index.sh

@@ -11,6 +11,17 @@
 
 set -euo pipefail
 
+# Help must never write: print the same usage as `hq core rebuild-index threads --help`.
+for arg in "$@"; do
+  if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
+    printf '%s\n' \
+      'Usage: hq core rebuild-index threads [--accept]' \
+      '' \
+      'Regenerate the session-threads INDEX.md. Help performs no writes.'
+    exit 0
+  fi
+done
+
 HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 cd "$HQ_ROOT"
 

package/assets/scaffold/core/scripts/rebuild-workers-index.sh

@@ -7,6 +7,17 @@
 
 set -euo pipefail
 
+# Help must never write: print the same usage as `hq core rebuild-index workers --help`.
+for arg in "$@"; do
+  if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
+    printf '%s\n' \
+      'Usage: hq core rebuild-index workers [--accept]' \
+      '' \
+      'Regenerate the workers INDEX.md. Help performs no writes.'
+    exit 0
+  fi
+done
+
 HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 cd "$HQ_ROOT"
 

package/dist/command-catalog.generated.d.ts

@@ -3987,7 +3987,7 @@ export declare const COMMAND_CATALOG: readonly [{
     }];
 }, {
     readonly name: "dm";
-    readonly description: "Send and read direct messages, and manage connection requests.";
+    readonly 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.";
     readonly aliases: readonly [];
     readonly hidden: false;
     readonly helpOption: true;
@@ -4054,7 +4054,11 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly hidden: false;
         }, {
             readonly flags: "--audience <human|agent|both>";
-            readonly description: "Tag who this message is for: human (a person must read it), agent (progress/status, hidden from humans by default), or both";
+            readonly description: "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.";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--for-human";
+            readonly description: "Tag the message for people (alias for --audience human).";
             readonly hidden: false;
         }, {
             readonly flags: "--attach <path>";

package/dist/command-catalog.generated.js

@@ -4827,7 +4827,7 @@ export const COMMAND_CATALOG = [
     },
     {
         "name": "dm",
-        "description": "Send and read direct messages, and manage connection requests.",
+        "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.",
         "aliases": [],
         "hidden": false,
         "helpOption": true,
@@ -4908,7 +4908,12 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--audience <human|agent|both>",
-                        "description": "Tag who this message is for: human (a person must read it), agent (progress/status, hidden from humans by default), or both",
+                        "description": "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.",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--for-human",
+                        "description": "Tag the message for people (alias for --audience human).",
                         "hidden": false
                     },
                     {

package/dist/commands/access.js

@@ -25,6 +25,7 @@ import { listJournals, syncDoctor, } from "@indigoai-us/hq-cloud";
 import { listActiveMembers } from "./members.js";
 import { aclLockedBy } from "./acl-lock.js";
 import { buildDmBody } from "./dm.js";
+import { defaultAudienceFor, recipientKindOf } from "../lib/notify-recipient.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { findRecentAccessRequest, formatTimeAgo, recordAccessRequest, } from "../utils/access-requests.js";
 import { recordAccessOutcome } from "../utils/access-outcomes.js";
@@ -1155,6 +1156,7 @@ async function buildLiveAccessDeps(slug, hqRoot) {
                 prompt: msg.prompt,
                 details: msg.details,
                 now: Date.now(),
+                audience: defaultAudienceFor(recipientKindOf(msg.recipient)),
             });
             const res = await vaultApiFetch({
                 token,

package/dist/commands/agents.js

@@ -42,7 +42,7 @@ import { consoleOrigin } from "./integrations-connect.js";
 import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSessionTimeoutError, } from "@indigoai-us/hq-cloud/outposts/node";
 import { peekIdToken } from "../utils/id-token.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, } from "../utils/plan-gate-error.js";
-import { AGENT_UID_PATTERN, isAgentUid } from "../lib/notify-recipient.js";
+import { AGENT_UID_PATTERN, defaultAudienceFor, isAgentUid } from "../lib/notify-recipient.js";
 import { AGENT_MODEL_PROVIDERS, modelSelectionErrorMessage, readAgentModelCatalog, validateAgentModelSelection, } from "../lib/agents/model-catalog.js";
 import { fetchCompanyPricingPlan, isUsageOnly, usageOnlyBoxSentence, usageOnlyCardRequiredLines, } from "../lib/billing/usage-only.js";
 import { BUNDLED_USAGE_CARD, fetchUsageCard, } from "../lib/billing/usage-card.js";
@@ -1139,7 +1139,7 @@ export async function sendAgentDm(token, agentUid, message) {
         token,
         path: "/v1/notify/dm",
         method: "POST",
-        body: { toPersonUid: agentUid, body: message },
+        body: { toPersonUid: agentUid, body: message, audience: defaultAudienceFor("agent") },
     });
 }
 /** Read the two-way DM conversation with an agent (most recent `limit`). */

package/dist/commands/core-delegate-w1b.js

@@ -1079,7 +1079,8 @@ function runSend(args, context) {
         catch {
             return fail("send", "could not persist sending state; no DM attempted");
         }
-        const dm = runHq(["dm", principal, headline, "--prompt-file", prompt, "--details-file", brief], context);
+        // The pickup DM is read by the person and acted on by their agent.
+        const dm = runHq(["dm", principal, headline, "--audience", "both", "--prompt-file", prompt, "--details-file", brief], context);
         if (dm.code !== 0)
             return fail("send", "hq dm delivery outcome is uncertain; status is sending, inspect DM history before retrying");
         const event = /eventId[: ]+([A-Za-z0-9_-]+)/.exec(dm.stdout ?? "")?.[1] ?? "";

package/dist/commands/core-dm-bind-native.js

@@ -579,6 +579,8 @@ async function post(d, args) {
         const versionError = requireCliVersion(d);
         if (versionError)
             return versionError;
+        // An automated status post keeps the channel default (agent audience); only a
+        // reply to a message a person wrote is for humans.
         const call = ["dm", ch, ...(root ? ["--thread", root] : []), cliMessage];
         const sent = d.runHq(call, { ...d.env, HQ_ROOT: d.root });
         if (sent.code !== 0)
@@ -594,7 +596,7 @@ async function post(d, args) {
         const mentions = mentionsJson(d, sid, names);
         if (!mentions.length)
             return fail("no mention resolved to a channel member id — not posting an update that notifies nobody");
-        const payload = { body: postedMessage, mentions };
+        const payload = { body: postedMessage, mentions, audience: "agent" };
         if (root)
             payload.rootEventId = root;
         try {

package/dist/commands/dm.d.ts

@@ -1,4 +1,6 @@
 import { Command } from "commander";
+import { defaultAudienceFor, recipientKindOf, type DmRecipientKind } from "../lib/notify-recipient.js";
+export { defaultAudienceFor, recipientKindOf, type DmRecipientKind };
 import { type DmAttachmentWire } from "./dm-attach.js";
 export interface DmRecipient {
     toEmail?: string;
@@ -158,7 +160,8 @@ export declare function resolveMentions(tokens: string[], members: ChannelMember
  * Returns null on anything that doesn't match. Pure → unit-testable.
  */
 export declare function parseDuration(input: string): number | null;
-type DmAudience = "human" | "agent" | "both";
+import type { DmAudience } from "../lib/notify-recipient.js";
+export type { DmAudience };
 export interface DmSendBody {
     toEmail?: string;
     toPersonUid?: string;
@@ -233,6 +236,15 @@ export declare function fetchChannels(token: string): Promise<ChannelSummary[]>;
  * post itself passes. Used to resolve `@name` mentions into participant uids.
  */
 export declare function fetchChannelMembers(token: string, channelId: string): Promise<ChannelMember[]>;
+/**
+ * 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.
+ */
+export declare function resolveSendAudience(opts: {
+    audience?: string;
+    forHuman?: boolean;
+}, recipientKind: DmRecipientKind, warn?: (msg: string) => void): string;
 /** One incoming DM as returned by GET /v1/notify/inbox. */
 export interface DmInboxEvent {
     eventId: string;
@@ -411,5 +423,4 @@ export declare function formatChannelTranscript(messages: ChannelMessageItem[],
 export declare function agentCallerUid(token: string, machine?: () => boolean): string | null;
 export declare const AGENT_THREAD_UNAVAILABLE: string;
 export declare function registerDmCommand(program: Command): void;
-export {};
 //# sourceMappingURL=dm.d.ts.map

package/dist/commands/dm.js

@@ -5,7 +5,8 @@ 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 } from "../lib/notify-recipient.js";
+import { EMAIL_PATTERN, RECIPIENT_UID_PATTERN, defaultAudienceFor, recipientKindOf, } from "../lib/notify-recipient.js";
+export { defaultAudienceFor, recipientKindOf };
 import { dmForwardCliEnabled } from "./dm-forward-flag.js";
 import { attachmentScopeForChannel, formatUploadedAttachments, personalScopeForCaller, uploadDmAttachments, validateAttachmentPaths, } from "./dm-attach.js";
 import { ChannelNotFoundError, suggestChannels, withChannelSuggestions, } from "./channel-suggest.js";
@@ -555,7 +556,7 @@ async function runConnectionAction(action, identifier) {
  * the server's idempotent participant-key dedupe) a group channel, then posts
  * the message into it. Reuses the same vault API client + auth as the 1:1 path.
  */
-async function runGroupSend(recipients, message) {
+async function runGroupSend(recipients, message, audience) {
     try {
         const participants = [];
         for (const r of recipients) {
@@ -601,7 +602,7 @@ async function runGroupSend(recipients, message) {
             token,
             path: `/v1/notify/channels/${encodeURIComponent(channelId)}/messages`,
             method: "POST",
-            body: { body },
+            body: { body, ...(audience ? { audience } : {}) },
         });
         if (!sendRes.ok) {
             const err = (await sendRes.json().catch(() => ({})));
@@ -810,11 +811,41 @@ async function runChannelSend(channelName, message, opts) {
         process.exit(1);
     }
 }
-async function runDmSend(recipient, message, opts) {
+function explicitAudience(opts) {
+    const explicit = opts.audience !== undefined && opts.audience !== "" ? opts.audience : undefined;
+    if (explicit !== undefined && !DM_AUDIENCE_VALUES.includes(explicit)) {
+        throw new Error("Invalid --audience '" + explicit + "': must be human, agent, or both.");
+    }
+    return explicit;
+}
+/**
+ * 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.
+ */
+export function resolveSendAudience(opts, recipientKind, warn = (m) => console.error(chalk.yellow(m))) {
+    const explicit = explicitAudience(opts);
+    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);
+}
+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);
+    const opts = { ...rawOpts };
+    const withAudience = (kind) => ({
+        ...rawOpts,
+        audience: resolveSendAudience(rawOpts, kind),
+    });
     // --channel <name> is an explicit channel target; the positional carries the
     // message (recipient slot), e.g. `hq dm --channel vyg-dev "hello"`.
     if (opts.channel !== undefined) {
-        await runChannelSend(opts.channel, message ?? recipient, opts);
+        await runChannelSend(opts.channel, message ?? recipient, withAudience("channel"));
         return;
     }
     if (recipient === undefined) {
@@ -837,7 +868,7 @@ async function runDmSend(recipient, message, opts) {
             process.exit(1);
             return;
         }
-        await runGroupSend(group, message);
+        await runGroupSend(group, message, withAudience("group").audience);
         return;
     }
     // A bare name or #hash addresses a named DM channel.
@@ -849,12 +880,13 @@ async function runDmSend(recipient, message, opts) {
             ? null
             : matchContactByName(await fetchContacts(await ensureCognitoToken()), channelName);
         if (!person?.personUid) {
-            await runChannelSend(channelName, message, opts);
+            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.`));
         recipient = person.personUid;
     }
+    Object.assign(opts, withAudience(recipientKindOf(recipient)));
     if (opts.thread !== undefined) {
         console.error(chalk.red("--thread is only supported for channel messages (hq dm <channel> --thread <eventId|last> \"…\")."));
         process.exit(1);
@@ -1697,7 +1729,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.");
+        .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.");
     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.')
@@ -1710,7 +1742,8 @@ 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")
+        .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("--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) => {
         await runDmSend(recipient, message, opts);

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

@@ -292,6 +292,10 @@ export interface PendingApproval {
     status?: string;
     /** Owner-facing outcome projected by hq-pro for decided rows. */
     outcome?: string;
+    /** Closed rejection code for a rejected row (e.g. provider_tool_error); older servers omit it. */
+    rejectionReason?: string | null;
+    /** Plain reason a decided row did not run, such as the app's own refusal text; older servers omit it. */
+    failureMessage?: string | null;
 }
 /**
  * Read open approvals from hq-pro's confirm-queue state (not the audit feed).
@@ -307,4 +311,15 @@ export declare function mutateConnectionAccess(token: string, companyUid: string
     granteeId?: string;
     permission?: Permission;
 }): Promise<ConnectionAccess>;
+/** Same cap the server applies to a failure reason; the CLI enforces it for older or malformed responses. */
+export declare const TERMINAL_REASON_MAX_CHARS = 500;
+/**
+ * Server-supplied text that reaches the terminal (a failure reason quoting an
+ * app's error). ANSI escapes, control and invisible formatting characters are
+ * removed, then the same credential-redaction chain the gateway diagnostics use
+ * (`redactErrorText`: credential URLs, bearer values, token assignments, known
+ * token shapes) is applied, and the result is capped. The server redacts too;
+ * this keeps an older or misbehaving server from printing a secret.
+ */
+export declare function terminalSafeText(text: string): string;
 //# sourceMappingURL=integrations-api.d.ts.map

package/dist/commands/integrations-api.js

@@ -8,6 +8,7 @@
  * is optional and read defensively.
  */
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { redactErrorText } from "../utils/redact-error-text.js";
 import { IntegrationsCliError, raiseForResponse, } from "./integrations-core.js";
 export async function listCatalog(token, companyUid, opts = {}) {
     const query = {
@@ -188,4 +189,30 @@ export async function mutateConnectionAccess(token, companyUid, action, input) {
     }
     return (await res.json());
 }
+// eslint-disable-next-line no-control-regex
+const TERMINAL_ESCAPES = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?|\u001b[@-_]/g;
+// eslint-disable-next-line no-control-regex
+const TERMINAL_CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+/** Bidirectional overrides, isolates, marks and zero-width characters, which can reorder or hide text. */
+const TERMINAL_INVISIBLE_FORMAT_CHARS = /[\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/g;
+/** Same cap the server applies to a failure reason; the CLI enforces it for older or malformed responses. */
+export const TERMINAL_REASON_MAX_CHARS = 500;
+/**
+ * Server-supplied text that reaches the terminal (a failure reason quoting an
+ * app's error). ANSI escapes, control and invisible formatting characters are
+ * removed, then the same credential-redaction chain the gateway diagnostics use
+ * (`redactErrorText`: credential URLs, bearer values, token assignments, known
+ * token shapes) is applied, and the result is capped. The server redacts too;
+ * this keeps an older or misbehaving server from printing a secret.
+ */
+export function terminalSafeText(text) {
+    const visible = text
+        .replace(TERMINAL_ESCAPES, "")
+        .replace(TERMINAL_CONTROL_CHARS, "")
+        .replace(TERMINAL_INVISIBLE_FORMAT_CHARS, "");
+    const redacted = redactErrorText(visible);
+    return redacted.length > TERMINAL_REASON_MAX_CHARS
+        ? `${redacted.slice(0, TERMINAL_REASON_MAX_CHARS - 1)}…`
+        : redacted;
+}
 //# sourceMappingURL=integrations-api.js.map

package/dist/commands/integrations-manage.js

@@ -18,7 +18,7 @@ import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
 import { redactSensitiveUrl, redactUrlsInText } from "../utils/redact-url.js";
 import { IntegrationsCliError, bareProvider, printHealthNotice, fetchConnections, fetchAdminSurface, fetchAuditPage, AUDIT_PAGE_MAX, printJson, revokedConnectionDetails, resolveConnection, selectConnection, } from "./integrations-core.js";
-import { fetchPendingApprovals, getConnectionAccess, mutateConnectionAccess, purgeConnection, setReadSafe, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
+import { fetchPendingApprovals, getConnectionAccess, mutateConnectionAccess, purgeConnection, setReadSafe, terminalSafeText, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
 const WRITE_POLICIES = ["auto-allow", "confirm", "deny"];
 const PERMISSIONS = ["read", "write", "admin"];
 /** Plain-English gloss for each write policy, used in every policy readout. */
@@ -617,9 +617,11 @@ export function registerManageCommands(integrations) {
             console.log(`${chalk.bold(label)}  ${chalk.dim(`${who} · ${row.createdAt}`)}`);
             if (opts.history) {
                 console.log(chalk.dim(`  ${row.queueId} · ${row.status ?? row.outcome ?? "status unavailable"}`));
+                if (row.failureMessage)
+                    console.log(chalk.dim(`  Why: ${terminalSafeText(row.failureMessage)}`));
             }
             else {
-                console.log(chalk.dim(`  hq integrations approve ${row.queueId}${row.provider ? ` --provider ${bareProvider(row.provider)}` : ""}`));
+                console.log(chalk.dim(`  hq integrations approve ${row.queueId}${row.provider ? ` --provider ${bareProvider(row.provider)}` : ""}${opts.company ? ` --company ${opts.company}` : ""}`));
             }
         }
     });

package/dist/commands/integrations.js

@@ -61,7 +61,7 @@ import { registerConnectCommands } from "./integrations-connect.js";
 import { registerImportCommands } from "./integrations-import.js";
 import { registerManageCommands } from "./integrations-manage.js";
 import { registerSlackCommands } from "./integrations-slack.js";
-import { fetchPendingApprovals } from "./integrations-api.js";
+import { fetchPendingApprovals, terminalSafeText } from "./integrations-api.js";
 const CALL_ARGS_EXAMPLE = `--args '{"assignee":"me"}' or --args-file args.json`;
 function readStream(stream) {
     return new Promise((resolve, reject) => {
@@ -533,7 +533,7 @@ export function registerIntegrationsCommand(program) {
                 return;
             }
             console.log(chalk.yellow("Queued for approval — this call can change the app, so a company owner decides first."));
-            console.log(`Approve with:\n  hq integrations approve ${queued.queueId} --provider ${bareProvider(connection.provider)}`);
+            console.log(`Approve with:\n  hq integrations approve ${queued.queueId} --provider ${bareProvider(connection.provider)}${opts.company ? ` --company ${opts.company}` : ""}`);
             if (queued.expiresAt) {
                 console.log(chalk.dim(`Expires ${queued.expiresAt}`));
             }
@@ -606,7 +606,9 @@ export function registerIntegrationsCommand(program) {
                     const unknown = terminal.status === "write_unknown" || terminal.outcome === "unknown";
                     console.log(chalk.red(unknown
                         ? `The provider outcome is unknown for ${queueId}. Check the provider before taking any action; ${historyCommand} shows the latest queue state.`
-                        : `The approved call failed (${terminal.status ?? terminal.outcome}). See ${historyCommand} for its status.`));
+                        : terminal.failureMessage
+                            ? `The approved call did not run: ${terminalSafeText(terminal.failureMessage)}`
+                            : `The approved call failed (${terminal.rejectionReason ?? terminal.status ?? terminal.outcome}). See ${historyCommand} for its status.`));
                 }
                 else if (terminal.status === "resumed" || terminal.status === "completed" || terminal.outcome === "ran") {
                     console.log(chalk.green("Approved — the call completed."));
@@ -614,7 +616,7 @@ export function registerIntegrationsCommand(program) {
                         printJson(unwrapGatewayResult(stored.result));
                     }
                     else if (ran) {
-                        console.log(chalk.yellow(`The call's result could not be read back. Run \`hq integrations approve ${queueId}\` again to fetch it; the call will not run twice.`));
+                        console.log(chalk.yellow(`The call's result could not be read back. Run \`hq integrations approve ${queueId} --provider ${bareProvider(connection.provider)}${opts.company ? ` --company ${opts.company}` : ""}\` again to fetch it; the call will not run twice.`));
                     }
                 }
                 else {
@@ -649,7 +651,9 @@ export function registerIntegrationsCommand(program) {
             if (failed) {
                 const reason = body.rejectionReason ??
                     (toolError ? "provider_tool_error" : body.outcome ?? body.status ?? "failed");
-                console.log(chalk.red(`The approved call failed at the provider (${reason}).`));
+                console.log(chalk.red(body.failureMessage
+                    ? `The approved call did not run: ${terminalSafeText(body.failureMessage)}`
+                    : `The approved call failed at the provider (${reason}).`));
             }
             else if (body.status === "resumed" || body.status === "completed" || body.outcome === "ran") {
                 console.log(chalk.green(`Approved — the call ran (status: ${body.status ?? body.outcome}).`));