@indigoai-us/hq-cli 5.103.25 → 5.103.26

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [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/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" | "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,17 @@ 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";
 /**
  * Expected session/company prerequisites degrade to NA instead of crashing or
  * becoming a false connection failure. An unreadable inventory remains UNKNOWN.
@@ -89,15 +100,33 @@ export function classifyConnection(connection) {
     const provider = bareProvider(connection.provider);
     const reason = recordedReason(connection);
     const connectedWithRecordedFailure = connection.status === "connected" && reason !== "";
+    const knownReasonCode = knownReasonCodeFor(connection);
+    if (knownReasonCode) {
+        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.
+        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 +134,107 @@ 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 [{
+        return [withServerRemediation(connection, {
                 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 [{
-                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 "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) {
+    return [connection.errorReason, connection.needsReauthReason, connection.degradedReason]
+        .find((value) => (typeof value === "string" &&
+        (RECONNECT_REASON_CODES.has(value) ||
+            RETRYABLE_REASON_CODES.has(value) ||
+            value === HQ_CONFIGURATION_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 +251,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 +267,34 @@ 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 === "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 +306,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.103.25",
+  "version": "5.103.26",
   "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",