@indigoai-us/hq-cli 5.103.25 → 5.103.27

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.103.27] — 2026-08-28
+
+## [5.103.26] — 2026-08-27
+
+### Changed
+
+- Company skill creation and collaboration now use the shared `skills/`
+  directory end to end: new skills are discovered and registered with stable
+  IDs, `hq skill propose` posts comment-only improvements, and local Claude,
+  Cursor, and Codex skill links stay scoped to the active company.
+
 ## [5.103.25] — 2026-08-27
 
 ### Fixed

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/commands/skill.d.ts

@@ -2,7 +2,7 @@
  * Company skill creation and comment-only improvements.
  *
  * `hq skill create <slug>` registers a canonical company skill, stamps its
- * immutable UID, reindexes its generated runtime wrapper, and syncs it.
+ * immutable UID, surfaces its generated runtime wrapper, and syncs it.
  * `hq skill propose <uid|path> --message "…"` posts a whole-skill comment to
  * the same improvement thread shown in HQ Console. It never uploads a modified
  * SKILL.md and cannot overwrite live content. Structured suggest/list/review
@@ -11,6 +11,7 @@
 import { Command } from "commander";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { surfaceCompanySkill } from "../lib/company-skill-wrapper.js";
 export declare const SKILL_UID_PATTERN: RegExp;
 export declare const SKILL_SLUG_PATTERN: RegExp;
 interface SkillSyncInput {
@@ -27,6 +28,7 @@ interface SkillSyncResult {
 export declare function parseSkillUid(markdown: string): string | undefined;
 export declare function readActiveCompanySlug(hqRoot: string): string | undefined;
 export declare function resolveCompanySlug(flag: string | undefined, hqRoot?: string): string;
+export declare function readCompanyPrefix(hqRoot: string, companySlug: string): string | undefined;
 /** Resolve a UID directly, or read the immutable UID from a local SKILL.md. */
 export declare function resolveSkillUid(target: string, cwd: string): string;
 export declare function canonicalCompanySkillPath(hqRoot: string, companySlug: string, skillSlug: string): string;
@@ -44,11 +46,7 @@ interface SkillCommandDeps {
     cwd?: () => string;
     hqRoot?: string;
     syncFile?: (input: SkillSyncInput) => Promise<SkillSyncResult>;
-    reindexFn?: (input: {
-        repoRoot: string;
-    }) => {
-        status: number | null;
-    };
+    surfaceSkillFn?: typeof surfaceCompanySkill;
 }
 export declare function registerSkillCommand(program: Command, deps?: SkillCommandDeps): Command;
 export {};

package/dist/commands/skill.js

@@ -2,7 +2,7 @@
  * Company skill creation and comment-only improvements.
  *
  * `hq skill create <slug>` registers a canonical company skill, stamps its
- * immutable UID, reindexes its generated runtime wrapper, and syncs it.
+ * immutable UID, surfaces its generated runtime wrapper, and syncs it.
  * `hq skill propose <uid|path> --message "…"` posts a whole-skill comment to
  * the same improvement thread shown in HQ Console. It never uploads a modified
  * SKILL.md and cannot overwrite live content. Structured suggest/list/review
@@ -12,9 +12,10 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import chalk from "chalk";
 import yaml from "js-yaml";
-import { reindex, share } from "@indigoai-us/hq-cloud";
+import { share } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken, DEFAULT_HQ_ROOT, buildVaultConfig, } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { surfaceCompanySkill } from "../lib/company-skill-wrapper.js";
 export const SKILL_UID_PATTERN = /^skl_[A-Za-z0-9]+$/;
 export const SKILL_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const COMPANY_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
@@ -69,6 +70,31 @@ export function resolveCompanySlug(flag, hqRoot = DEFAULT_HQ_ROOT) {
     }
     return slug;
 }
+export function readCompanyPrefix(hqRoot, companySlug) {
+    const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+    if (!fs.existsSync(manifestPath))
+        return undefined;
+    try {
+        const parsed = yaml.load(fs.readFileSync(manifestPath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        const companies = parsed.companies;
+        if (!companies || typeof companies !== "object" || Array.isArray(companies)) {
+            return undefined;
+        }
+        const company = companies[companySlug];
+        if (!company || typeof company !== "object" || Array.isArray(company)) {
+            return undefined;
+        }
+        const prefix = company.prefix;
+        return typeof prefix === "string" && /^[a-z0-9][a-z0-9-]*$/.test(prefix)
+            ? prefix
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Resolve a UID directly, or read the immutable UID from a local SKILL.md. */
 export function resolveSkillUid(target, cwd) {
     if (SKILL_UID_PATTERN.test(target))
@@ -159,7 +185,7 @@ export function registerSkillCommand(program, deps = {}) {
     const cwd = deps.cwd ?? process.cwd;
     const hqRoot = deps.hqRoot ?? DEFAULT_HQ_ROOT;
     const syncFile = deps.syncFile ?? defaultSyncFile;
-    const reindexFn = deps.reindexFn ?? reindex;
+    const surfaceSkillFn = deps.surfaceSkillFn ?? surfaceCompanySkill;
     const skill = program
         .command("skill")
         .description("Create company skills and discuss improvements")
@@ -167,10 +193,11 @@ export function registerSkillCommand(program, deps = {}) {
         .option("--hq-root <path>", "Local HQ root", hqRoot);
     skill
         .command("create <slug>")
-        .description("Register, stamp, reindex, and sync a company skill")
+        .description("Register, stamp, surface, and sync a company skill")
         .option("--name <name>", "Display name when creating a new template")
         .option("--description <text>", "Description when creating a new template")
         .option("--no-sync", "Register locally without uploading the stamped file")
+        .option("--surface-only", "Refresh local skill discovery without registration or sync")
         .action(async (slug, opts) => {
         if (!SKILL_SLUG_PATTERN.test(slug)) {
             throw new Error("Skill slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
@@ -179,9 +206,24 @@ export function registerSkillCommand(program, deps = {}) {
         const resolvedRoot = path.resolve(parentOpts.hqRoot ?? hqRoot);
         const companySlug = resolveCompanySlug(parentOpts.company, resolvedRoot);
         const filePath = canonicalCompanySkillPath(resolvedRoot, companySlug, slug);
+        const legacyPrefix = readCompanyPrefix(resolvedRoot, companySlug);
         if (fs.existsSync(filePath) && !fs.statSync(filePath).isFile()) {
             throw new Error(`Expected a SKILL.md file at '${filePath}'.`);
         }
+        if (opts.surfaceOnly === true) {
+            // Discovery wrappers are execution surfaces. Never create one for an
+            // unregistered file, because that would bypass immutable identity and
+            // the FILE_ACL-backed registration flow.
+            resolveSkillUid(filePath, resolvedRoot);
+            const surfaced = surfaceSkillFn({
+                hqRoot: resolvedRoot,
+                companySlug,
+                skillSlug: slug,
+                ...(legacyPrefix ? { legacyPrefix } : {}),
+            });
+            console.log(chalk.green(`Local discovery ready: ${surfaced.wrapperPath}`));
+            return;
+        }
         const localContent = fs.existsSync(filePath)
             ? fs.readFileSync(filePath, "utf8")
             : makeSkillTemplate({
@@ -213,15 +255,20 @@ export function registerSkillCommand(program, deps = {}) {
             throw new Error("The server returned an invalid skill registration response; the local file was not changed.");
         }
         writeSkillFileAtomically(filePath, registered.content);
-        let reindexStatus = null;
+        let discoveryStatus = null;
         try {
-            reindexStatus = reindexFn({ repoRoot: resolvedRoot }).status;
+            discoveryStatus = surfaceSkillFn({
+                hqRoot: resolvedRoot,
+                companySlug,
+                skillSlug: slug,
+                ...(legacyPrefix ? { legacyPrefix } : {}),
+            }).status;
         }
         catch (err) {
-            console.warn(chalk.yellow(`⚠ Skill registered, but HQ reindex failed: ${err instanceof Error ? err.message : String(err)}`));
+            console.warn(chalk.yellow(`⚠ Skill registered, but local discovery failed: ${err instanceof Error ? err.message : String(err)}`));
         }
-        if (reindexStatus !== null && reindexStatus !== 0) {
-            console.warn(chalk.yellow(`⚠ Skill registered, but HQ reindex exited ${reindexStatus}. Run 'hq reindex --repo-root ${resolvedRoot}' to retry discovery.`));
+        if (discoveryStatus !== null && discoveryStatus !== 0) {
+            console.warn(chalk.yellow(`⚠ Skill registered, but local discovery exited ${discoveryStatus}. Run 'hq skill --company ${companySlug} create ${slug} --surface-only' to retry without another registration request.`));
         }
         if (opts.sync !== false) {
             let syncResult;
@@ -242,7 +289,7 @@ export function registerSkillCommand(program, deps = {}) {
         }
         console.log(chalk.green(`Skill ready: ${registered.skillUid}`));
         console.log(`  File:     ${filePath}`);
-        console.log(`  Discovery: ${reindexStatus === 0 ? "reindexed" : "reindex needs attention"}`);
+        console.log(`  Discovery: ${discoveryStatus === 0 ? "ready" : "needs attention"}`);
         console.log(registered.accessPolicy === "open"
             ? `  Access:   Open — every active ${companySlug} member can edit`
             : "  Access:   preserved existing policy");

package/dist/lib/company-skill-wrapper.d.ts

@@ -0,0 +1,24 @@
+import * as fs from "node:fs";
+export interface SurfaceCompanySkillInput {
+    hqRoot: string;
+    companySlug: string;
+    skillSlug: string;
+    /** Prefix used by pre-namespaced generated wrappers (for one-time cleanup). */
+    legacyPrefix?: string;
+    /** Test seam for the Win32 filename adapter. */
+    win32?: boolean;
+    /** Test seam for replacement rollback failures. */
+    renameEntry?: typeof fs.renameSync;
+    /** Test seam for environments that deny local symlink creation. */
+    symlinkEntry?: typeof fs.symlinkSync;
+}
+export interface SurfaceCompanySkillResult {
+    status: 0;
+    wrapperPath: string;
+}
+/**
+ * Surface one canonical company skill to Claude/Codex without running HQ's
+ * global reindex, migrations, worker generation, or unrelated cleanup.
+ */
+export declare function surfaceCompanySkill(input: SurfaceCompanySkillInput): SurfaceCompanySkillResult;
+//# sourceMappingURL=company-skill-wrapper.d.ts.map

package/dist/lib/company-skill-wrapper.js

@@ -0,0 +1,276 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+const WIN32_RESERVED_CHARS = /[<>:"/\\|?*]/;
+const WIN32_DEVICE_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+const LOCAL_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const WRAPPER_MARKER_DIR = ".hq-company-skill-wrappers";
+function encodeLocalSegment(segment, win32) {
+    if (!win32)
+        return segment;
+    let encoded = "";
+    for (let index = 0; index < segment.length; index += 1) {
+        const char = segment[index];
+        const trailingDotOrSpace = index === segment.length - 1 && (char === "." || char === " ");
+        const dotSegment = (segment === "." || segment === "..") && index === 0;
+        const deviceName = WIN32_DEVICE_NAME.test(segment) && index === 0;
+        if (char === "%" ||
+            char.charCodeAt(0) <= 0x1f ||
+            WIN32_RESERVED_CHARS.test(char) ||
+            trailingDotOrSpace ||
+            dotSegment ||
+            deviceName) {
+            encoded += `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`;
+        }
+        else {
+            encoded += char;
+        }
+    }
+    return encoded;
+}
+function lstat(pathname) {
+    try {
+        return fs.lstatSync(pathname);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isWithin(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function sameFile(left, right) {
+    try {
+        const a = fs.statSync(left);
+        const b = fs.statSync(right);
+        return a.dev === b.dev && a.ino === b.ino;
+    }
+    catch {
+        return false;
+    }
+}
+function symlinkTarget(linkPath) {
+    try {
+        if (!fs.lstatSync(linkPath).isSymbolicLink())
+            return undefined;
+        return path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath));
+    }
+    catch {
+        return undefined;
+    }
+}
+function generatedMarkerPath(wrapperPath) {
+    return path.join(path.dirname(wrapperPath), WRAPPER_MARKER_DIR, `${path.basename(wrapperPath)}.json`);
+}
+function hasBoundGeneratedMarker(wrapperPath, companySlug) {
+    try {
+        const marker = JSON.parse(fs.readFileSync(generatedMarkerPath(wrapperPath), "utf8"));
+        const wrapper = fs.lstatSync(wrapperPath);
+        return (marker.version === 2 &&
+            marker.companySlug === companySlug &&
+            marker.wrapperDev === wrapper.dev &&
+            marker.wrapperIno === wrapper.ino &&
+            marker.wrapperBirthtimeMs === wrapper.birthtimeMs);
+    }
+    catch {
+        return false;
+    }
+}
+function writeGeneratedMarker(wrapperPath, companySlug, skillSlug) {
+    const markerPath = generatedMarkerPath(wrapperPath);
+    try {
+        const wrapper = fs.lstatSync(wrapperPath);
+        fs.mkdirSync(path.dirname(markerPath), { recursive: true });
+        fs.writeFileSync(markerPath, `${JSON.stringify({
+            version: 2,
+            companySlug,
+            skillSlug,
+            wrapperDev: wrapper.dev,
+            wrapperIno: wrapper.ino,
+            wrapperBirthtimeMs: wrapper.birthtimeMs,
+        })}\n`, "utf8");
+    }
+    catch {
+        // Every generated entry is also a live symlink into the canonical company
+        // skill, so wrapper ownership remains recoverable if this hint cannot land.
+    }
+}
+function removeGeneratedMarker(wrapperPath) {
+    try {
+        fs.rmSync(generatedMarkerPath(wrapperPath), { force: true });
+    }
+    catch {
+        // The wrapper itself is already gone; an orphaned hint is harmless and is
+        // never sufficient to surface content on its own.
+    }
+}
+function isGeneratedNamespacedWrapper(wrapperPath, hqRoot, companySlug) {
+    const companySkillsRoot = path.join(hqRoot, "companies", companySlug, "skills");
+    const wrapperTarget = symlinkTarget(wrapperPath);
+    if (wrapperTarget)
+        return isWithin(companySkillsRoot, wrapperTarget);
+    const wrapper = lstat(wrapperPath);
+    if (!wrapper?.isDirectory())
+        return false;
+    const entries = fs.readdirSync(wrapperPath).filter((entry) => !entry.startsWith("."));
+    const containsOnlyLiveBridges = (entries.length > 0 &&
+        entries.every((entry) => {
+            const target = symlinkTarget(path.join(wrapperPath, entry));
+            return target !== undefined && isWithin(companySkillsRoot, target);
+        }));
+    return containsOnlyLiveBridges || hasBoundGeneratedMarker(wrapperPath, companySlug);
+}
+function isGeneratedLegacyEntry(legacyPath, sourceDir, skillFile) {
+    const target = symlinkTarget(legacyPath);
+    if (target)
+        return target === sourceDir || target === skillFile;
+    const entry = lstat(legacyPath);
+    if (!entry)
+        return false;
+    if (entry.isFile())
+        return sameFile(legacyPath, skillFile);
+    if (!entry.isDirectory())
+        return false;
+    const legacySkill = path.join(legacyPath, "SKILL.md");
+    const skillTarget = symlinkTarget(legacySkill);
+    return skillTarget === skillFile || sameFile(legacySkill, skillFile);
+}
+function pruneStaleNamespacedWrappers(runtimeRoot, currentWrapperName, hqRoot, companySlug, win32) {
+    const namespacePrefix = encodeLocalSegment(`${companySlug}:`, win32);
+    for (const name of fs.readdirSync(runtimeRoot)) {
+        if (name === currentWrapperName || !name.startsWith(namespacePrefix))
+            continue;
+        const candidate = path.join(runtimeRoot, name);
+        const skillSlug = name.slice(namespacePrefix.length);
+        const canonicalSkill = path.join(hqRoot, "companies", companySlug, "skills", skillSlug, "SKILL.md");
+        if (LOCAL_SLUG.test(skillSlug) &&
+            !fs.existsSync(canonicalSkill) &&
+            isGeneratedNamespacedWrapper(candidate, hqRoot, companySlug)) {
+            fs.rmSync(candidate, { recursive: true, force: false });
+            removeGeneratedMarker(candidate);
+        }
+    }
+}
+function bridgeEntry(sourcePath, wrapperPath, target, type, symlinkEntry) {
+    try {
+        symlinkEntry(target, wrapperPath, type);
+    }
+    catch (symlinkError) {
+        const reason = symlinkError instanceof Error
+            ? symlinkError.message
+            : (JSON.stringify(symlinkError) ?? "Unknown symlink error");
+        throw new Error(`Could not surface '${sourcePath}' as a live skill link: ${reason}. ` +
+            "Enable local symlink support (Windows Developer Mode or an elevated shell) and retry.");
+    }
+}
+/**
+ * Surface one canonical company skill to Claude/Codex without running HQ's
+ * global reindex, migrations, worker generation, or unrelated cleanup.
+ */
+export function surfaceCompanySkill(input) {
+    if (!LOCAL_SLUG.test(input.companySlug)) {
+        throw new Error("Company slug must contain only lowercase letters, numbers, and hyphens.");
+    }
+    if (!LOCAL_SLUG.test(input.skillSlug)) {
+        throw new Error("Skill slug must contain only lowercase letters, numbers, and hyphens.");
+    }
+    if (input.legacyPrefix !== undefined && !LOCAL_SLUG.test(input.legacyPrefix)) {
+        throw new Error("Legacy prefix must contain only lowercase letters, numbers, and hyphens.");
+    }
+    const sourceDir = path.join(input.hqRoot, "companies", input.companySlug, "skills", input.skillSlug);
+    const skillFile = path.join(sourceDir, "SKILL.md");
+    if (!fs.existsSync(skillFile) || !fs.statSync(skillFile).isFile()) {
+        throw new Error(`The canonical SKILL.md does not exist at '${skillFile}'.`);
+    }
+    const wrapperName = encodeLocalSegment(`${input.companySlug}:${input.skillSlug}`, input.win32 ?? process.platform === "win32");
+    const win32 = input.win32 ?? process.platform === "win32";
+    const wrapperPath = path.join(input.hqRoot, ".claude", "skills", wrapperName);
+    const existingWrapper = lstat(wrapperPath);
+    if (existingWrapper &&
+        !existingWrapper.isSymbolicLink() &&
+        !existingWrapper.isDirectory()) {
+        throw new Error(`Cannot surface the skill because '${wrapperPath}' is not a directory.`);
+    }
+    const sourceEntries = fs.readdirSync(sourceDir).sort();
+    const runtimeRoot = path.dirname(wrapperPath);
+    fs.mkdirSync(runtimeRoot, { recursive: true });
+    const stagingPath = fs.mkdtempSync(path.join(runtimeRoot, `.${wrapperName}.tmp-`));
+    try {
+        if (win32) {
+            // Directory junctions do not require Developer Mode or elevation and
+            // keep the runtime wrapper live against the canonical company skill.
+            // Replace the mkdtemp directory with the staged junction, then rename it
+            // into place through the same rollback-safe commit path below.
+            fs.rmSync(stagingPath, { recursive: true, force: false });
+            bridgeEntry(sourceDir, stagingPath, sourceDir, "junction", input.symlinkEntry ?? fs.symlinkSync);
+        }
+        else {
+            for (const entry of sourceEntries) {
+                const sourcePath = path.join(sourceDir, entry);
+                const entryWrapper = path.join(stagingPath, entry);
+                // Resolve relative to the FINAL wrapper location. The staging directory
+                // is renamed only after every entry has been bridged successfully.
+                const relativeTarget = path.relative(wrapperPath, sourcePath);
+                bridgeEntry(sourcePath, entryWrapper, relativeTarget, fs.statSync(sourcePath).isDirectory() ? "dir" : "file", input.symlinkEntry ?? fs.symlinkSync);
+            }
+        }
+        const currentWrapper = lstat(wrapperPath);
+        if (currentWrapper &&
+            !currentWrapper.isSymbolicLink() &&
+            !currentWrapper.isDirectory()) {
+            throw new Error(`Cannot surface the skill because '${wrapperPath}' is not a directory.`);
+        }
+        const renameEntry = input.renameEntry ?? fs.renameSync;
+        const backupPath = `${stagingPath}.previous`;
+        let previousMoved = false;
+        if (currentWrapper) {
+            if (!isGeneratedNamespacedWrapper(wrapperPath, input.hqRoot, input.companySlug)) {
+                throw new Error(`Cannot replace '${wrapperPath}' because it is not an HQ-generated skill wrapper.`);
+            }
+            renameEntry(wrapperPath, backupPath);
+            previousMoved = true;
+        }
+        try {
+            renameEntry(stagingPath, wrapperPath);
+        }
+        catch (replaceError) {
+            if (previousMoved && !lstat(wrapperPath)) {
+                try {
+                    renameEntry(backupPath, wrapperPath);
+                }
+                catch (restoreError) {
+                    throw new Error(`Could not replace '${wrapperPath}' and could not restore its previous wrapper ` +
+                        `(replace: ${replaceError instanceof Error ? replaceError.message : String(replaceError)}; ` +
+                        `restore: ${restoreError instanceof Error ? restoreError.message : String(restoreError)}).`);
+                }
+            }
+            throw replaceError;
+        }
+        if (previousMoved) {
+            try {
+                fs.rmSync(backupPath, { recursive: true, force: true });
+            }
+            catch {
+                // The new wrapper is already committed. A hidden generated backup is
+                // safer than rolling back a successful replacement.
+            }
+        }
+        writeGeneratedMarker(wrapperPath, input.companySlug, input.skillSlug);
+        pruneStaleNamespacedWrappers(runtimeRoot, wrapperName, input.hqRoot, input.companySlug, win32);
+        if (input.legacyPrefix) {
+            const legacyBase = path.join(runtimeRoot, `${input.legacyPrefix}-${input.skillSlug}`);
+            for (const legacyPath of [legacyBase, `${legacyBase}.md`]) {
+                if (legacyPath !== wrapperPath &&
+                    isGeneratedLegacyEntry(legacyPath, sourceDir, skillFile)) {
+                    fs.rmSync(legacyPath, { recursive: true, force: false });
+                }
+            }
+        }
+    }
+    catch (error) {
+        fs.rmSync(stagingPath, { recursive: true, force: true });
+        throw error;
+    }
+    return { status: 0, wrapperPath };
+}
+//# sourceMappingURL=company-skill-wrapper.js.map

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

@@ -18,18 +18,22 @@ export interface IntegrationConnection extends AdminConnection {
     needsReauthReason?: string;
     /** Server-derived remediation flow; optional for older control planes. */
     fix_path?: string;
+    /** Server-derived remediation class; optional for older control planes. */
+    fix_kind?: string;
 }
 export interface IntegrationsDoctorDeps {
     ensureToken?: () => Promise<string>;
     resolveCompany?: (token: string, company: string | undefined) => Promise<string>;
     listConnections?: (token: string, companyUid: string) => Promise<IntegrationConnection[]>;
 }
-type FindingKind = "reconnect" | "re-add" | "provider-blocked";
+type FindingKind = "reconnect" | "re-add" | "contact-admin" | "wait" | "provider-blocked" | "retryable" | "hq-configuration";
 interface Finding {
     provider: string;
     connectionId: string;
     kind: FindingKind;
     message: string;
+    /** Optional HQ-authored remediation returned by the control plane. */
+    remediation?: string;
 }
 /**
  * Expected session/company prerequisites degrade to NA instead of crashing or

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

@@ -14,6 +14,18 @@ import { getCompanyUid } from "../../../utils/vault-api.js";
 import { bareProvider, fetchConnections, IntegrationsCliError, } from "../../../commands/integrations-core.js";
 export const INTEGRATIONS_FAMILY_ID = "integrations";
 export const INTEGRATIONS_PREFIX = "integrations";
+const RECONNECT_REASON_CODES = new Set([
+    "oauth_refresh_invalid_grant",
+    "oauth_refresh_unavailable",
+    "token_refresh_failed",
+    "credentials_rejected",
+]);
+const RETRYABLE_REASON_CODES = new Set([
+    "oauth_refresh_transient",
+    "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.
@@ -89,15 +101,40 @@ export function classifyConnection(connection) {
     const provider = bareProvider(connection.provider);
     const reason = recordedReason(connection);
     const connectedWithRecordedFailure = connection.status === "connected" && reason !== "";
+    const knownReasonCode = knownReasonCodeFor(connection);
+    // `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, 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)];
+    }
+    // A stale remediation value does not make a clean connected row unhealthy.
+    if (!connectedWithRecordedFailure && connection.status === "connected")
+        return [];
     if (isProviderBlocked(reason) || connection.status === "degraded") {
-        return [{
+        return [withServerRemediation(connection, {
                 provider,
                 connectionId: connection.id,
                 kind: "provider-blocked",
                 message: connectedWithRecordedFailure
                     ? "reports connected, but recorded provider health says access is blocked upstream"
                     : "provider-side access is blocked or unavailable",
-            }];
+            })];
+    }
+    const fallback = genericReconnectFinding(connection, provider);
+    const serverClassified = findingForServerFixKind(fallback, connection.fix_kind);
+    if (serverClassified.kind !== "reconnect") {
+        return [withServerRemediation(connection, serverClassified)];
     }
     if (isTokenRefreshFailure(reason) || isCredentialFailure(reason)) {
         const problem = isTokenRefreshFailure(reason)
@@ -105,49 +142,115 @@ export function classifyConnection(connection) {
             : connectedWithRecordedFailure
                 ? "reports connected, but the provider rejected the stored credentials"
                 : "the provider rejected the stored credentials";
-        return [{ provider, connectionId: connection.id, kind: "reconnect", message: problem }];
-    }
-    if (connection.status !== "connected" && connection.fix_path === "blocked-upstream") {
-        return [{
-                provider,
-                connectionId: connection.id,
-                kind: "provider-blocked",
-                message: "provider-side access is blocked or unavailable",
-            }];
-    }
-    // The server is authoritative about an API-key credential that must be
-    // re-entered. Do not apply a stale fix path to a clean connected row, but do
-    // preserve this useful branch logic for a non-healthy row.
-    if (connection.status !== "connected" && connection.fix_path === "re-add") {
-        return [{
+        return [withServerRemediation(connection, {
                 provider,
                 connectionId: connection.id,
-                kind: "re-add",
-                message: "needs its API key re-entered",
-            }];
+                kind: "reconnect",
+                message: problem,
+            })];
     }
     if (connection.status === "needs-reauth" || connection.status === "error") {
-        return [{
-                provider,
-                connectionId: connection.id,
-                kind: "reconnect",
-                message: connection.status === "needs-reauth" ? "needs re-authentication" : "is in an error state",
-            }];
+        return [withServerRemediation(connection, fallback)];
     }
     if (connection.status !== "connected") {
-        return [{
+        return [withServerRemediation(connection, {
                 provider,
                 connectionId: connection.id,
                 kind: "reconnect",
                 message: `reports an unrecognized non-healthy status (${connection.status})`,
-            }];
+            })];
     }
     return [];
 }
+function genericReconnectFinding(connection, provider) {
+    return {
+        provider,
+        connectionId: connection.id,
+        kind: "reconnect",
+        message: connection.status === "needs-reauth"
+            ? "needs re-authentication"
+            : "is in an error state",
+    };
+}
+/** Only values emitted by hq-pro affect the classification; future values fall back. */
+function findingForServerFixKind(fallback, fixKind) {
+    switch (fixKind) {
+        case "re-add":
+            return {
+                ...fallback,
+                kind: "re-add",
+                message: "requires its API key to be re-entered",
+            };
+        case "contact-admin":
+            return {
+                ...fallback,
+                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;
+    }
+}
+/**
+ * A fix path is server-authored, role- and credential-aware wording. It cannot
+ * make a connection unhealthy: the caller must first have classified a health
+ * signal, so a stale fix path on an otherwise clean connected row is ignored.
+ */
+function withServerRemediation(connection, finding) {
+    return connection.fix_path
+        ? { ...finding, remediation: connection.fix_path }
+        : finding;
+}
+/**
+ * These are a closed hq-pro contract. Exact matching deliberately comes before
+ * the legacy text heuristics, which remain below for old and unknown rows.
+ */
+function knownReasonCodeFor(connection) {
+    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 === UNSPECIFIED_REASON_CODE)));
+}
+function findingForKnownReasonCode(connection, provider, code) {
+    if (RECONNECT_REASON_CODES.has(code)) {
+        return {
+            provider,
+            connectionId: connection.id,
+            kind: "reconnect",
+            message: "stored credentials need re-authentication",
+        };
+    }
+    if (RETRYABLE_REASON_CODES.has(code)) {
+        return {
+            provider,
+            connectionId: connection.id,
+            kind: "retryable",
+            message: code === "oauth_refresh_write_conflict"
+                ? "token refresh lost a concurrent write race; the stored credential remains intact"
+                : "token refresh is temporarily unavailable; the stored credential remains intact",
+        };
+    }
+    return {
+        provider,
+        connectionId: connection.id,
+        kind: "hq-configuration",
+        message: "the HQ OAuth client secret is unavailable",
+    };
+}
 function groupFindings(findings, company) {
     const groups = new Map();
     for (const finding of findings) {
-        const key = `${finding.kind}\u0000${finding.provider}\u0000${finding.message}`;
+        const key = `${finding.kind}\u0000${finding.provider}\u0000${finding.message}\u0000${finding.remediation ?? ""}`;
         const entries = groups.get(key) ?? [];
         entries.push(finding);
         groups.set(key, entries);
@@ -164,12 +267,14 @@ function resultForGroup(entries, company) {
     const overflow = ids.length - preview.length;
     const namedConnections = preview.join(", ") + (overflow > 0 ? ` (+${overflow} more)` : "");
     const plural = count === 1 ? "connection" : "connections";
+    const serverRemediation = first.remediation;
     if (first.kind === "provider-blocked") {
         return {
             status: "FAIL",
             checkId: `${INTEGRATIONS_PREFIX}.provider-blocked.${first.provider}`,
             target: namedConnections,
             message: `${first.provider}: ${count} ${plural} ${first.message}. This is not reported as a local credential repair.`,
+            ...(serverRemediation ? { remediation: serverRemediation } : {}),
         };
     }
     if (first.kind === "re-add") {
@@ -178,7 +283,43 @@ function resultForGroup(entries, company) {
             checkId: `${INTEGRATIONS_PREFIX}.re-add.${first.provider}`,
             target: namedConnections,
             message: `${first.provider}: ${count} ${plural} ${first.message}.`,
-            remediation: `hq integrations connect ${first.provider} --token-stdin${company ? ` --company ${company}` : ""}`,
+            remediation: serverRemediation ?? `hq integrations connect ${first.provider} --token-stdin${company ? ` --company ${company}` : ""}`,
+        };
+    }
+    if (first.kind === "contact-admin") {
+        return {
+            status: "FAIL",
+            checkId: `${INTEGRATIONS_PREFIX}.contact-admin.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}.`,
+            remediation: serverRemediation ?? "Ask a company owner or admin to repair this integration.",
+        };
+    }
+    if (first.kind === "retryable") {
+        return {
+            status: "WARN",
+            checkId: `${INTEGRATIONS_PREFIX}.retryable.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}. Reconnecting is not needed; retry the operation later.`,
+            ...(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",
+            checkId: `${INTEGRATIONS_PREFIX}.hq-configuration.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}. An HQ administrator must repair this configuration; reconnecting will not fix it.`,
+            ...(serverRemediation ? { remediation: serverRemediation } : {}),
         };
     }
     const companyArg = company ? ` --company ${company}` : "";
@@ -190,9 +331,9 @@ function resultForGroup(entries, company) {
         checkId: `${INTEGRATIONS_PREFIX}.reconnect.${first.provider}`,
         target: namedConnections,
         message: `${first.provider}: ${count} ${plural} ${first.message}.`,
-        remediation: overflow > 0
+        remediation: serverRemediation ?? (overflow > 0
             ? `Reconnect the listed connections, then repeat for the remaining ${overflow}: ${remediation}`
-            : remediation,
+            : remediation),
     };
 }
 function recordedReason(connection) {

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.25",
+  "version": "5.103.27",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.15.79",
+    "@indigoai-us/hq-cloud": "~6.15.80",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",