@indigoai-us/hq-cli 5.103.26 → 5.103.27

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.103.27] — 2026-08-28
+
 ## [5.103.26] — 2026-08-27
 
 ### Changed

package/dist/commands/dm.js

@@ -272,15 +272,11 @@ async function runGroupSend(recipients, message) {
         for (const r of recipients) {
             const rc = detectRecipient(r);
             if (!rc) {
-                console.error(chalk.red(`Invalid recipient '${r}': each must be an email address or a personUid (prs_…).`));
-                process.exit(1);
-            }
-            // Group DMs are channels — agents don't participate in channels (their
-            // DM surface is 1:1 via the durable box inbox). DM an agent directly.
-            if (rc.toPersonUid?.startsWith("agt_")) {
-                console.error(chalk.red(`Agents can't join group DMs yet — DM '${r}' directly: hq dm ${r} "<message>".`));
+                console.error(chalk.red(`Invalid recipient '${r}': each must be an email address, a personUid (prs_…), or an agentUid (agt_…).`));
                 process.exit(1);
             }
+            // People (prs_) and agents (agt_) are both valid group participants —
+            // the server (handleCreateGroupDm) accepts agt_* uids like any other.
             participants.push(rc.toEmail ?? rc.toPersonUid);
         }
         if (participants.length < 2) {

package/dist/lib/doctor/checks/integrations.d.ts

@@ -26,7 +26,7 @@ export interface IntegrationsDoctorDeps {
     resolveCompany?: (token: string, company: string | undefined) => Promise<string>;
     listConnections?: (token: string, companyUid: string) => Promise<IntegrationConnection[]>;
 }
-type FindingKind = "reconnect" | "re-add" | "contact-admin" | "provider-blocked" | "retryable" | "hq-configuration";
+type FindingKind = "reconnect" | "re-add" | "contact-admin" | "wait" | "provider-blocked" | "retryable" | "hq-configuration";
 interface Finding {
     provider: string;
     connectionId: string;

package/dist/lib/doctor/checks/integrations.js

@@ -25,6 +25,7 @@ const RETRYABLE_REASON_CODES = new Set([
     "oauth_refresh_write_conflict",
 ]);
 const HQ_CONFIGURATION_REASON_CODE = "oauth_client_secret_unavailable";
+const UNSPECIFIED_REASON_CODE = "unspecified";
 /**
  * Expected session/company prerequisites degrade to NA instead of crashing or
  * becoming a false connection failure. An unreadable inventory remains UNKNOWN.
@@ -101,11 +102,18 @@ export function classifyConnection(connection) {
     const reason = recordedReason(connection);
     const connectedWithRecordedFailure = connection.status === "connected" && reason !== "";
     const knownReasonCode = knownReasonCodeFor(connection);
-    if (knownReasonCode) {
+    // `unspecified` is a recognised member of the server vocabulary, but it is an
+    // absence of diagnosis rather than one. Short-circuiting on it here would skip
+    // the status-aware branches below and report a degraded connection as an error
+    // needing a reconnect. It is deliberately allowed to fall through, where the
+    // server's role- and credential-aware remediation is applied like any other
+    // undiagnosed row.
+    if (knownReasonCode && knownReasonCode !== UNSPECIFIED_REASON_CODE) {
         const finding = findingForKnownReasonCode(connection, provider, knownReasonCode);
         // Retryable and HQ-configuration reason codes diagnose conditions that a
         // caller-specific remediation cannot change. Reconnect-class codes defer
-        // to the server's credential/role-aware remediation classification.
+        // to the server's credential/role-aware remediation classification, so an
+        // install in progress is never interrupted by a reconnect.
         return [withServerRemediation(connection, RECONNECT_REASON_CODES.has(knownReasonCode)
                 ? findingForServerFixKind(finding, connection.fix_kind)
                 : finding)];
@@ -179,6 +187,12 @@ function findingForServerFixKind(fallback, fixKind) {
                 kind: "contact-admin",
                 message: "must be repaired by a company owner or admin",
             };
+        case "wait":
+            return {
+                ...fallback,
+                kind: "wait",
+                message: "is waiting for the Factory installation to complete",
+            };
         case "reconnect":
         default:
             return fallback;
@@ -199,11 +213,13 @@ function withServerRemediation(connection, finding) {
  * the legacy text heuristics, which remain below for old and unknown rows.
  */
 function knownReasonCodeFor(connection) {
-    return [connection.errorReason, connection.needsReauthReason, connection.degradedReason]
-        .find((value) => (typeof value === "string" &&
+    const values = [connection.errorReason, connection.needsReauthReason, connection.degradedReason];
+    if (values.includes(HQ_CONFIGURATION_REASON_CODE))
+        return HQ_CONFIGURATION_REASON_CODE;
+    return values.find((value) => (typeof value === "string" &&
         (RECONNECT_REASON_CODES.has(value) ||
             RETRYABLE_REASON_CODES.has(value) ||
-            value === HQ_CONFIGURATION_REASON_CODE)));
+            value === UNSPECIFIED_REASON_CODE)));
 }
 function findingForKnownReasonCode(connection, provider, code) {
     if (RECONNECT_REASON_CODES.has(code)) {
@@ -288,6 +304,15 @@ function resultForGroup(entries, company) {
             ...(serverRemediation ? { remediation: serverRemediation } : {}),
         };
     }
+    if (first.kind === "wait") {
+        return {
+            status: "WARN",
+            checkId: `${INTEGRATIONS_PREFIX}.wait.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}. Wait for it to complete, then retry the operation.`,
+            remediation: serverRemediation ?? "Wait for the Factory installation to complete, then retry the operation.",
+        };
+    }
     if (first.kind === "hq-configuration") {
         return {
             status: "FAIL",

package/dist/lib/search-index/index.d.ts

@@ -108,6 +108,28 @@ export declare class QmdTerminatedError extends QmdExitError {
     name: string;
     constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string, signal: string);
 }
+/**
+ * qmd refused an LLM-backed operation because its local LLM is DISABLED IN CI:
+ * qmd hard-disables every LLM operation whenever `CI` is truthy in the
+ * environment and throws `Error: LLM operations are disabled in CI (set
+ * CI=true)`. Its semantic/hybrid reads (`vsearch`/`query`) expand the query
+ * through that gate, and the index build (`embed`) generates vectors through it,
+ * so any of them dies immediately when CI is set. hq-cli forwards the caller's
+ * environment — including CI — to the qmd child, so this is the caller's
+ * ENVIRONMENT, not an hq-cli defect.
+ *
+ * Before this class the refusal rendered as `qmd <full argv> exited with 1:
+ * <qmd's stderr>` and, because that message interpolated the caller's whole
+ * argv, every distinct search query minted a brand-new permanent Sentry issue —
+ * the same unbounded-fingerprint failure fixed for HQ-CLI-S and HQ-CLI
+ * 7677702704. This typed subclass lets the boundary classify the condition as
+ * the caller's environment and stop fingerprinting on the query text: it is
+ * raised only from qmd's OWN captured streams and its message names the
+ * SUBCOMMAND only. Sentry HQ-CLI 7688850003.
+ */
+export declare class QmdLlmDisabledError extends QmdExitError {
+    name: string;
+}
 export type ResolveQmdBinOptions = {
     env?: Record<string, string | undefined>;
     isExecutable?: (candidate: string) => boolean;

package/dist/lib/search-index/index.js

@@ -86,6 +86,28 @@ export class QmdTerminatedError extends QmdExitError {
         this.signal = signal;
     }
 }
+/**
+ * qmd refused an LLM-backed operation because its local LLM is DISABLED IN CI:
+ * qmd hard-disables every LLM operation whenever `CI` is truthy in the
+ * environment and throws `Error: LLM operations are disabled in CI (set
+ * CI=true)`. Its semantic/hybrid reads (`vsearch`/`query`) expand the query
+ * through that gate, and the index build (`embed`) generates vectors through it,
+ * so any of them dies immediately when CI is set. hq-cli forwards the caller's
+ * environment — including CI — to the qmd child, so this is the caller's
+ * ENVIRONMENT, not an hq-cli defect.
+ *
+ * Before this class the refusal rendered as `qmd <full argv> exited with 1:
+ * <qmd's stderr>` and, because that message interpolated the caller's whole
+ * argv, every distinct search query minted a brand-new permanent Sentry issue —
+ * the same unbounded-fingerprint failure fixed for HQ-CLI-S and HQ-CLI
+ * 7677702704. This typed subclass lets the boundary classify the condition as
+ * the caller's environment and stop fingerprinting on the query text: it is
+ * raised only from qmd's OWN captured streams and its message names the
+ * SUBCOMMAND only. Sentry HQ-CLI 7688850003.
+ */
+export class QmdLlmDisabledError extends QmdExitError {
+    name = 'QmdLlmDisabledError';
+}
 function isExecutable(candidate) {
     try {
         fs.accessSync(candidate, fs.constants.X_OK);
@@ -730,6 +752,21 @@ function finishRunQmd(result, bin, args) {
     }
     const detail = normalized.stderr || normalized.stdout || 'qmd returned no diagnostic output';
     const message = `qmd ${args.join(' ')} exited with ${normalized.status ?? 'an unknown status'}: ${detail}`;
+    // qmd refused because its local LLM is disabled: whenever CI is set in the
+    // environment, qmd hard-disables every LLM operation, so `vsearch`/`query`
+    // (query expansion) and `embed` (vector build) throw `Error: LLM operations
+    // are disabled in CI (set CI=true)` before doing any work. hq-cli inherits the
+    // caller's CI into the qmd child (runQmd forwards process.env), so this is the
+    // caller's ENVIRONMENT, not an hq-cli defect. Match qmd's OWN captured streams
+    // (stderr AND stdout) — never the synthesized `message`, which embeds the
+    // caller's whole argv — and name the SUBCOMMAND only, so the Sentry group can
+    // no longer fingerprint per search query (HQ-CLI 7688850003). Checked ahead of
+    // the collection wordings: the refusal text matches none of them, so order is
+    // safe, and the narrower typed signature stays first.
+    if (/LLM operations are disabled/i.test(`${normalized.stderr}\n${normalized.stdout}`)) {
+        const subcommand = typeof args[0] === 'string' && args[0].length > 0 ? redactErrorText(args[0]) || 'qmd' : 'qmd';
+        throw new QmdLlmDisabledError(`qmd ${subcommand} could not run: its local LLM is disabled because CI is set in the environment`, args, normalized.status, normalized.stdout, normalized.stderr);
+    }
     if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(detail)) {
         throw new QmdCollectionMissingError(message, args, normalized.status, normalized.stdout, normalized.stderr);
     }

package/dist/main.js

@@ -68,6 +68,7 @@ import { networkTransportErrorMessage } from "./utils/network-transport-error.js
 import { qmdNativeBindingErrorMessage } from "./utils/qmd-native-binding-error.js";
 import { qmdMissingCollectionMessage } from "./utils/qmd-collection-missing-error.js";
 import { qmdTerminatedMessage } from "./utils/qmd-terminated-error.js";
+import { qmdLlmDisabledMessage } from "./utils/qmd-llm-disabled-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
@@ -486,7 +487,23 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // collection-missing checks (both narrower typed signatures) and BEFORE the
         // environmental / transport / generic branches.
         const terminatedMsg = qmdMsg || collectionMsg ? null : qmdTerminatedMessage(err);
-        const envMsg = qmdMsg || collectionMsg || terminatedMsg ? null : environmentalFsErrorMessage(err);
+        // A qmd LLM-backed operation refused because qmd's local LLM is DISABLED
+        // whenever CI is set in the environment (`vsearch`/`query` expand the
+        // query through it; `embed` builds vectors through it). hq-cli forwards the
+        // caller's CI to the qmd child, so this is the caller's ENVIRONMENT, not an
+        // hq-cli defect. Before this branch the refusal reached the final else and,
+        // because the synthesized message embedded the caller's whole argv, minted
+        // a brand-new permanent issue per query (HQ-CLI 7688850003). finishRunQmd
+        // now types it QmdLlmDisabledError; print the query-free remedy and skip
+        // capture. Evaluated AFTER the native-binding / collection-missing /
+        // terminated checks (narrower typed signatures) and BEFORE the
+        // environmental / transport / generic branches. Scoped to the subcommands
+        // that legitimately need the LLM (vsearch/query/embed); an LLM-disabled
+        // failure from hq's OWN reconciliation stays a captured internal error.
+        const llmDisabledMsg = qmdMsg || collectionMsg || terminatedMsg ? null : qmdLlmDisabledMessage(err);
+        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg
+            ? null
+            : environmentalFsErrorMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
         // with a ConnectTimeoutError / ECONNREFUSED / ENOTFOUND cause) is the
         // caller's connectivity, not an hq-cli defect. Before this branch it fell
@@ -497,7 +514,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // message that names the unreachable host, exit 1, and skip Sentry.
         // Ordered after the environmental check so a full disk keeps its exact
         // existing message.
-        const transportMsg = qmdMsg || collectionMsg || terminatedMsg || envMsg ? null : networkTransportErrorMessage(err);
+        const transportMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || envMsg
+            ? null
+            : networkTransportErrorMessage(err);
         if (qmdMsg) {
             deps.stderr.write(`hq: ${qmdMsg}\n`);
         }
@@ -507,6 +526,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (terminatedMsg) {
             deps.stderr.write(`hq: ${terminatedMsg}\n`);
         }
+        else if (llmDisabledMsg) {
+            deps.stderr.write(`hq: ${llmDisabledMsg}\n`);
+        }
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }

package/dist/utils/qmd-llm-disabled-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * If `err` is a qmd LLM-disabled-in-CI failure on a subcommand that legitimately
+ * needs the LLM, return an actionable, query-free remedy; otherwise return
+ * `null`. Mirrors qmdTerminatedMessage / qmdMissingCollectionMessage /
+ * qmdNativeBindingErrorMessage so the top-level handler branches the same way: a
+ * non-null result means print-and-skip-Sentry, null means "handle as usual
+ * (capture to Sentry)".
+ */
+export declare function qmdLlmDisabledMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-llm-disabled-error.d.ts.map

package/dist/utils/qmd-llm-disabled-error.js

@@ -0,0 +1,87 @@
+// src/utils/qmd-llm-disabled-error.ts
+//
+// Classify a qmd failure caused by qmd's local LLM being DISABLED IN CI — not an
+// hq-cli code defect. qmd hard-disables every LLM operation whenever `CI` is
+// truthy in the environment (`Error: LLM operations are disabled in CI (set
+// CI=true)`); its semantic/hybrid reads (`vsearch`/`query`) expand the query
+// through that gate and the index build (`embed`) generates embeddings through
+// it, so each dies immediately when CI is set. hq-cli forwards the caller's
+// environment — including CI — to the qmd child, so this is the caller's
+// ENVIRONMENT, not a bug HQ can fix in code: surface an actionable remedy and
+// SKIP Sentry capture. Sibling of qmd-terminated-error.ts (HQ-CLI 7677702704),
+// qmd-collection-missing-error.ts (HQ-CLI-S), qmd-native-binding-error.ts
+// (HQ-CLI-J), environmental-error.ts (HQ-CLI-2) and network-transport-error.ts
+// (HQ-CLI-G): a failure that is NOT an hq-cli defect is printed with an
+// actionable message and never filed as a crash.
+//
+// HQ-CLI 7688850003: `hq search <query> --mode semantic ...` spawned `qmd
+// vsearch`, which refused because CI was set on the host (an automation
+// harness). hq-cli had no classifier for that wording, so finishRunQmd raised a
+// plain QmdExitError whose synthesized message interpolates the caller's whole
+// argv; nothing caught it, so it reached the top-level handler's final else and
+// was captured — and because the message embeds the query, every distinct query
+// minted a brand-new permanent Sentry issue. finishRunQmd now types the
+// condition QmdLlmDisabledError (raised only from qmd's OWN captured streams,
+// message naming the subcommand only); this classifier closes the boundary.
+//
+// The gate is deliberately narrow on TWO axes so it can neither be tripped by
+// user input nor silence a real bug:
+//   1. CLASS: only a QmdLlmDisabledError (the typed subclass finishRunQmd raises
+//      for the LLM-disabled wording) qualifies — never a plain QmdExitError, a
+//      native-binding failure, or any other error, even one carrying the same
+//      wording in a user-controlled field.
+//   2. INVOCATION: only the qmd subcommands that legitimately need the LLM — the
+//      caller-supplied semantic/hybrid reads `vsearch`/`query`, plus the index
+//      build `embed`. Any other subcommand (e.g. an LLM-disabled failure surfaced
+//      by hq's OWN `collection list` reconciliation) returns null and stays on
+//      the captured-error path, so a condition hq did not expect is still
+//      reported — now grouped per subcommand rather than per query.
+//
+// The remedy is entirely query-free: only the SUBCOMMAND — drawn from a closed
+// allow-list — selects the wording, and NOTHING is interpolated from user input,
+// so there is no injection surface at all. This preserves the bounded-
+// fingerprint doctrine established by HQ-CLI-S and HQ-CLI 7677702704.
+/** Semantic/hybrid reads whose query is EXPANDED through qmd's LLM gate. */
+const LLM_SEARCH_READS = new Set(["vsearch", "query"]);
+/** The index build that generates embeddings through the same LLM gate. */
+const LLM_INDEX_BUILD = "embed";
+/**
+ * Remedy for a semantic/hybrid SEARCH read. Leads with `--mode keyword`, which
+ * needs no LLM and is correct in EVERY environment (including a genuine CI
+ * pipeline where clearing CI is not an option), and offers clearing CI only as
+ * the secondary option for a non-CI host that merely has the variable set.
+ */
+const SEARCH_REMEDY = "Semantic and hybrid search need qmd's local LLM, which is switched off " +
+    "because CI is set in this environment. Re-run with '--mode keyword' (it needs " +
+    "no LLM and works everywhere), or clear CI for the command and try again.";
+/**
+ * Remedy for the `embed` index build, which cannot run at all without the LLM —
+ * so `--mode keyword` does not apply and the only fix is to clear CI.
+ */
+const EMBED_REMEDY = "Embeddings can't be built while CI is set in this environment, because qmd " +
+    "disables its local LLM there. Clear CI for the command and run it again.";
+/**
+ * If `err` is a qmd LLM-disabled-in-CI failure on a subcommand that legitimately
+ * needs the LLM, return an actionable, query-free remedy; otherwise return
+ * `null`. Mirrors qmdTerminatedMessage / qmdMissingCollectionMessage /
+ * qmdNativeBindingErrorMessage so the top-level handler branches the same way: a
+ * non-null result means print-and-skip-Sentry, null means "handle as usual
+ * (capture to Sentry)".
+ */
+export function qmdLlmDisabledMessage(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "QmdLlmDisabledError")
+        return null;
+    const args = Array.isArray(record.args) ? record.args : [];
+    const subcommand = args[0];
+    if (typeof subcommand !== "string")
+        return null;
+    if (LLM_SEARCH_READS.has(subcommand))
+        return SEARCH_REMEDY;
+    if (subcommand === LLM_INDEX_BUILD)
+        return EMBED_REMEDY;
+    return null;
+}
+//# sourceMappingURL=qmd-llm-disabled-error.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.103.26",
+  "version": "5.103.27",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {