@indigoai-us/hq-cli 5.103.24 → 5.103.26

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [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
+
+- Codex Stop hooks now record their automatic checkpoint out of band after a
+  user-facing reply has already been delivered, avoiding the visible
+  `Hook re-prompted Codex` filler message while preserving the missing-reply
+  safety gate.
+
 ## [5.103.24] — 2026-08-27
 
 ## [5.103.23] — 2026-08-26

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -490,6 +490,32 @@ set -uo pipefail
     exit 0
   fi
 
+  # A turn whose user-facing reply is ALREADY delivered cannot be blocked into
+  # silence. Hosts re-prompt an assistant turn that produces no visible text
+  # ("your previous response had no visible output"), so blocking here forces a
+  # trailing filler message — the very double-messaging this gate exists to
+  # prevent. Every wording tried so far only shrank that filler (full
+  # restatement, then a meta-note, then a bare <br>); none removed it, because
+  # the instruction asks for a turn shape the host will not accept.
+  #
+  # So do not ask. Let the turn end and record the checkpoint out-of-band. The
+  # payload carries the transcript, which is what the sibling already reads to
+  # derive files, decisions and learnings, so the record keeps its substance
+  # without an agent-authored summary. Turns that checkpoint BEFORE replying
+  # never reach this branch and keep the full hand-written payload; the
+  # reply-required gate above still runs first, so a turn with no reply at all
+  # is unaffected.
+  if [ "$replied" = 1 ]; then
+    (nohup hq core checkpoint \
+       --session-id "$session_id" \
+       --trigger stop-gate-auto \
+       --transcript "$transcript_path" \
+       --summary "turn ended with its user-facing reply already delivered" \
+       >/dev/null 2>&1 &)
+    rm -f "$block_count_file" 2>/dev/null || true
+    exit 0
+  fi
+
   # Loop guard for the missing-checkpoint demand below: cap consecutive blocks
   # per session, then fail open (see the counter's comment above).
   if [ "$block_count" -ge 3 ]; then
@@ -500,18 +526,12 @@ set -uo pipefail
   # Built with printf rather than concatenation so the session id can appear in
   # both commands without re-splitting the message into fragments.
   #
-  # Two variants, chosen from the transcript rather than left to the agent's
-  # judgment: a single instruction either demanded a full restatement
-  # (double-messaging hosts that render pre-tool text) or forbade
-  # post-checkpoint text (hiding the reply when the agent had not yet written
-  # one). The transcript already tells us which case we are in, so say exactly
-  # one thing.
+  # Only the not-yet-replied case reaches here — a delivered reply took the
+  # out-of-band branch above — so this instruction never has to forbid a
+  # restatement, and the agent's reply lands in final position where every host
+  # renders it in full.
   flags_spec='  hq core checkpoint --session-id %s --trigger stop-gate --summary "<what changed, in one line>" [--file <path>] [--decision "<choice and why>"] [--learning "<reusable rule>"] [--next "<outstanding step>"]\n\nOnly --summary is required, and the repeatable flags are what the sibling uses to enrich the record, distil policies and update the indexes — a bare summary gives it almost nothing to work with. Write them as machine record, not prose for the user, and pass each one that genuinely applies:\n  --file      every path you created or modified this turn\n  --decision  a choice you made that a reader would otherwise have to reverse-engineer\n  --learning  a rule that changes how someone acts next time, not a restatement of what just happened\n  --next      work that is genuinely still outstanding\nOmit a flag rather than padding it: an empty or invented learning is worse than none.\n\nIf this turn only read or inspected things and changed no state, the correct call instead is:\n\n  hq core checkpoint --session-id %s --idle'
-  if [ "$replied" = 1 ]; then
-    reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint before it can end.\n\nYour user-facing reply is ALREADY delivered — the message you just wrote is visible to the user. Do NOT send it again, in full or summarized: repeating it double-messages the user, which is exactly the bug this gate guards against.\n\nTHE SIBLING (a background maintenance agent) reads only the checkpoint payload, never your chat reply — anything it needs must go into the flags.\n\nRun the checkpoint now as the FINAL action of the turn and end the turn immediately after it, adding no further text:\n\n'"$flags_spec" "$session_id" "$session_id")"
-  else
-    reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. You have not sent one yet this turn — everything you owe them (results, links, answers, status, decisions) must go into it. The checkpoint is invisible to them and does NOT count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nORDER: run the checkpoint FIRST, then deliver your complete user-facing reply as the FINAL text of the turn — final-position text is the one placement every host renders in full. Every link, URL, instruction, command, and decision the user needs must appear in that final message. The gate enforces this: a turn that ends without a user-facing reply is blocked until the reply is delivered.\n\n'"$flags_spec" "$session_id" "$session_id")"
-  fi
+  reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. You have not sent one yet this turn — everything you owe them (results, links, answers, status, decisions) must go into it. The checkpoint is invisible to them and does NOT count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nORDER: run the checkpoint FIRST, then deliver your complete user-facing reply as the FINAL text of the turn — final-position text is the one placement every host renders in full. Every link, URL, instruction, command, and decision the user needs must appear in that final message. The gate enforces this: a turn that ends without a user-facing reply is blocked until the reply is delivered.\n\n'"$flags_spec" "$session_id" "$session_id")"
 
   # Codex surfaces a blocked Stop reason as a synthetic user prompt. Preserve
   # the actionable instruction out-of-band, then use the stable marker covered

package/dist/commands/doctor.d.ts

@@ -7,10 +7,9 @@
  *     to every check.
  *   - Running outside any HQ tree exits non-zero with a message naming exactly
  *     what it looked for — never a throw, never a false PASS.
- *   - The command performs no network calls and needs no authentication; it is
- *     purely a function of the on-disk shape of the tree. `--live-runtimes` is
- *     the one opt-in exception: it probes the installed AI CLIs (claude, codex,
- *     grok) with a version read and a one-line prompt.
+ *   - Most families inspect the local tree. The integrations family makes one
+ *     control-plane inventory read for the active company, without invoking a
+ *     provider tool. `--live-runtimes` is the opt-in AI CLI probe.
  *
  * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
  * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
@@ -86,6 +85,10 @@ export interface RunDoctorOptions {
      * family reports UNTESTED rather than spawning anything.
      */
     liveRuntimes?: boolean;
+    /** Company slug for the integrations family; omitted uses active membership. */
+    company?: string;
+    /** Internal test seam; production CLI always runs integrations checks. */
+    integrations?: boolean;
 }
 /** The outcome of a doctor run, returned rather than thrown so it is testable. */
 export interface RunDoctorResult {
@@ -98,7 +101,8 @@ export interface RunDoctorResult {
 }
 /**
  * Resolve the HQ root, run every registered check family against it, and render
- * a plain-text summary. Makes no network calls and needs no authentication.
+ * a plain-text summary. The integrations family makes one bounded inventory
+ * read; all other default tiers remain local unless explicitly opted in.
  */
 export declare function runDoctor(options?: RunDoctorOptions): Promise<RunDoctorResult>;
 /** Register the top-level `hq doctor` command so it appears in `hq --help`. */

package/dist/commands/doctor.js

@@ -7,10 +7,9 @@
  *     to every check.
  *   - Running outside any HQ tree exits non-zero with a message naming exactly
  *     what it looked for — never a throw, never a false PASS.
- *   - The command performs no network calls and needs no authentication; it is
- *     purely a function of the on-disk shape of the tree. `--live-runtimes` is
- *     the one opt-in exception: it probes the installed AI CLIs (claude, codex,
- *     grok) with a version read and a one-line prompt.
+ *   - Most families inspect the local tree. The integrations family makes one
+ *     control-plane inventory read for the active company, without invoking a
+ *     provider tool. `--live-runtimes` is the opt-in AI CLI probe.
  *
  * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
  * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
@@ -79,7 +78,8 @@ function isHqRoot(dir) {
 }
 /**
  * Resolve the HQ root, run every registered check family against it, and render
- * a plain-text summary. Makes no network calls and needs no authentication.
+ * a plain-text summary. The integrations family makes one bounded inventory
+ * read; all other default tiers remain local unless explicitly opted in.
  */
 export async function runDoctor(options = {}) {
     const write = options.stdout ?? ((chunk) => void process.stdout.write(chunk));
@@ -102,6 +102,8 @@ export async function runDoctor(options = {}) {
         platform: { id: platform.id, evidence: platform.evidence },
         sessionId: options.sessionId,
         liveRuntimes: options.liveRuntimes === true,
+        company: options.company,
+        integrations: options.integrations !== false,
     };
     const families = await registry.run(context);
     // `--deep-test` (US-008): after the read-only tiers, actually fire pure-guard
@@ -150,13 +152,14 @@ export async function runDoctor(options = {}) {
 export function registerDoctorCommand(program) {
     program
         .command("doctor")
-        .description("Verify HQ hook guardrails are wired and firing (read-only, offline; --live-runtimes adds networked AI CLI probes).")
+        .description("Verify HQ hook wiring, runtimes, and connection health (read-only; integrations uses one control-plane inventory read).")
         .option("--json", "Emit the machine-readable JSON document (no colour).")
         .option("--verbose", "Also print every PASS result in text output.")
         .option("--no-color", "Disable ANSI colour even on a TTY.")
         .option("--session-id <id>", "Scope the runtime probe's ledger check to this exact session.")
         .option("--deep-test", "Also fire pure-guard hooks through the real gate under all three profiles (sandboxed).")
         .option("--live-runtimes", "Also probe each installed AI CLI (claude, codex, grok) with a one-line prompt to verify login and subscription (networked; uses your subscriptions).")
+        .option("--company <slug>", "Company slug for integrations checks (otherwise resolves your single active company).")
         .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
         .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
         .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
@@ -204,6 +207,7 @@ export function registerDoctorCommand(program) {
             sessionId: opts.sessionId,
             deepTest: opts.deepTest === true,
             liveRuntimes: opts.liveRuntimes === true,
+            company: opts.company,
         });
         // Set the exit code rather than calling process.exit, so the CLI's
         // normal shutdown (telemetry flush) still runs. Non-zero means either an

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

@@ -0,0 +1,47 @@
+/**
+ * Company integration health for `hq doctor`.
+ *
+ * This family makes one authenticated read of HQ's connection inventory. It
+ * never calls an integration gateway or provider tool, so it cannot mutate
+ * data, spend provider quota, or trigger provider rate limits. It classifies
+ * stored health signals only: a recorded rejection overrides a misleading
+ * `connected` status, but a clean connected row is not live-provider proof.
+ */
+import { type AdminConnection } from "../../../commands/integrations-core.js";
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+export declare const INTEGRATIONS_FAMILY_ID = "integrations";
+export declare const INTEGRATIONS_PREFIX = "integrations";
+/** Additive health fields returned by newer control planes. */
+export interface IntegrationConnection extends AdminConnection {
+    errorReason?: string;
+    degradedReason?: string;
+    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" | "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
+ * becoming a false connection failure. An unreadable inventory remains UNKNOWN.
+ */
+export declare function checkIntegrations(context: CheckContext, deps?: IntegrationsDoctorDeps): Promise<CheckResult[]>;
+/** Classify without echoing untrusted provider text, which may contain secrets. */
+export declare function classifyConnection(connection: IntegrationConnection): Finding[];
+export declare const integrationsFamily: CheckFamily;
+export {};
+//# sourceMappingURL=integrations.d.ts.map

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

@@ -0,0 +1,353 @@
+/**
+ * Company integration health for `hq doctor`.
+ *
+ * This family makes one authenticated read of HQ's connection inventory. It
+ * never calls an integration gateway or provider tool, so it cannot mutate
+ * data, spend provider quota, or trigger provider rate limits. It classifies
+ * stored health signals only: a recorded rejection overrides a misleading
+ * `connected` status, but a clean connected row is not live-provider proof.
+ */
+import { ensureCognitoIdToken } from "../../../utils/cognito-session.js";
+import { isAuthError } from "../../../utils/auth-error.js";
+import { isCompanySelectionError } from "../../../utils/company-selection-error.js";
+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.
+ */
+export async function checkIntegrations(context, deps = {}) {
+    if (context.integrations === false) {
+        return [{
+                status: "NA",
+                checkId: `${INTEGRATIONS_PREFIX}.skipped`,
+                message: "Integration checks were not requested for this run.",
+            }];
+    }
+    const ensureToken = deps.ensureToken ?? (() => ensureCognitoIdToken({ interactive: false }));
+    const resolveCompany = deps.resolveCompany ?? getCompanyUid;
+    const listConnections = deps.listConnections ?? ((token, companyUid) => fetchConnections(token, companyUid));
+    let token;
+    try {
+        token = await ensureToken();
+    }
+    catch {
+        return skippedForSession();
+    }
+    let companyUid;
+    try {
+        companyUid = await resolveCompany(token, context.company);
+    }
+    catch (error) {
+        if (isAuthError(error))
+            return skippedForSession();
+        if (isCompanySelectionError(error)) {
+            return skippedForCompany(error instanceof Error ? error : new Error("Company selection failed."));
+        }
+        return unknown("The active company could not be resolved; retry after checking HQ connectivity.");
+    }
+    let connections;
+    try {
+        connections = await listConnections(token, companyUid);
+    }
+    catch (error) {
+        if (isAuthError(error))
+            return skippedForSession();
+        if (error instanceof IntegrationsCliError && error.expected) {
+            return [{
+                    status: "NA",
+                    checkId: `${INTEGRATIONS_PREFIX}.unavailable`,
+                    message: "Integration inventory is unavailable to this account, so no connection health was assessed.",
+                }];
+        }
+        return unknown("The integration connection inventory could not be read; retry after checking HQ connectivity.");
+    }
+    const active = connections.filter((connection) => connection.status !== "revoked");
+    if (active.length === 0) {
+        return [{
+                status: "NA",
+                checkId: `${INTEGRATIONS_PREFIX}.connections`,
+                message: "No active integration connections to assess. Revoked connection tombstones are ignored.",
+            }];
+    }
+    const findings = active.flatMap(classifyConnection);
+    if (findings.length === 0) {
+        return [{
+                status: "PASS",
+                checkId: `${INTEGRATIONS_PREFIX}.connections`,
+                message: `${active.length} active integration connection${active.length === 1 ? "" : "s"} reported healthy; only the control-plane inventory was read (no provider calls).`,
+            }];
+    }
+    return groupFindings(findings, context.company);
+}
+/** Classify without echoing untrusted provider text, which may contain secrets. */
+export function classifyConnection(connection) {
+    if (connection.status === "revoked")
+        return [];
+    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 [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)
+            ? "token refresh failed"
+            : connectedWithRecordedFailure
+                ? "reports connected, but the provider rejected the stored credentials"
+                : "the provider rejected the stored credentials";
+        return [withServerRemediation(connection, {
+                provider,
+                connectionId: connection.id,
+                kind: "reconnect",
+                message: problem,
+            })];
+    }
+    if (connection.status === "needs-reauth" || connection.status === "error") {
+        return [withServerRemediation(connection, fallback)];
+    }
+    if (connection.status !== "connected") {
+        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}\u0000${finding.remediation ?? ""}`;
+        const entries = groups.get(key) ?? [];
+        entries.push(finding);
+        groups.set(key, entries);
+    }
+    return [...groups.values()]
+        .sort((a, b) => a[0].provider.localeCompare(b[0].provider))
+        .map((entries) => resultForGroup(entries, company));
+}
+function resultForGroup(entries, company) {
+    const first = entries[0];
+    const count = entries.length;
+    const ids = entries.map((entry) => entry.connectionId);
+    const preview = ids.slice(0, 6);
+    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") {
+        return {
+            status: "FAIL",
+            checkId: `${INTEGRATIONS_PREFIX}.re-add.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}.`,
+            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}` : "";
+    const remediation = preview
+        .map((id) => `hq integrations reconnect --connection ${id}${companyArg}`)
+        .join("; ");
+    return {
+        status: "FAIL",
+        checkId: `${INTEGRATIONS_PREFIX}.reconnect.${first.provider}`,
+        target: namedConnections,
+        message: `${first.provider}: ${count} ${plural} ${first.message}.`,
+        remediation: serverRemediation ?? (overflow > 0
+            ? `Reconnect the listed connections, then repeat for the remaining ${overflow}: ${remediation}`
+            : remediation),
+    };
+}
+function recordedReason(connection) {
+    return [connection.errorReason, connection.needsReauthReason, connection.degradedReason]
+        .filter((value) => typeof value === "string")
+        .join(" ")
+        .toLowerCase();
+}
+function isTokenRefreshFailure(reason) {
+    return /token[\s_-]*refresh|refresh[\s_-]*token|invalid_grant/.test(reason);
+}
+function isCredentialFailure(reason) {
+    return /rejected[\s_-]*(the[\s_-]*)?stored[\s_-]*credentials|credentials[\s_-]*rejected|unauthori[sz]ed|invalid[\s_-]*(token|credentials)/.test(reason);
+}
+function isProviderBlocked(reason) {
+    return /\b403\b|access[\s_-]*denied|upstream[\s_-]*(block|blocked)|provider[\s_-]*(block|blocked|unavailable)|service[\s_-]*unavailable/.test(reason);
+}
+function skippedForSession() {
+    return [{
+            status: "NA",
+            checkId: `${INTEGRATIONS_PREFIX}.session`,
+            message: "Integration checks skipped: no usable HQ session is available.",
+            remediation: "Run `hq login`, then rerun `hq doctor`.",
+        }];
+}
+function skippedForCompany(error) {
+    return [{
+            status: "NA",
+            checkId: `${INTEGRATIONS_PREFIX}.company`,
+            message: "Integration checks skipped: no single active company could be selected.",
+            remediation: `Rerun \`hq doctor --company <slug>\`. (${error.message})`,
+        }];
+}
+function unknown(message) {
+    return [{ status: "UNKNOWN", checkId: `${INTEGRATIONS_PREFIX}.inventory`, message }];
+}
+export const integrationsFamily = {
+    id: INTEGRATIONS_FAMILY_ID,
+    title: "Integration connection health",
+    run: (context) => checkIntegrations(context),
+};
+//# sourceMappingURL=integrations.js.map

package/dist/lib/doctor/registry.js

@@ -19,6 +19,7 @@ import { checkCodexWiring } from "./checks/codex-wiring.js";
 import { checkGrokWiring } from "./checks/grok-wiring.js";
 import { checkRuntimeProbe } from "./checks/runtime-probe.js";
 import { runtimeHealthFamily } from "./checks/runtime-health.js";
+import { integrationsFamily } from "./checks/integrations.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -177,6 +178,9 @@ export function createDefaultRegistry() {
     // runtime is logged out or broken; this family closes that blind spot. Its
     // default tier is a pure PATH scan, preserving the offline contract.
     registry.register(runtimeHealthFamily);
+    // The engine remains family-agnostic: integrations is one bounded,
+    // read-only inventory family, registered alongside all other checks.
+    registry.register(integrationsFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

package/dist/lib/doctor/types.d.ts

@@ -66,6 +66,10 @@ export interface CheckContext {
      * executing anything.
      */
     liveRuntimes?: boolean;
+    /** Company slug for company-scoped families; absent uses active membership. */
+    company?: string;
+    /** Internal test seam; production `hq doctor` always enables integrations. */
+    integrations?: boolean;
 }
 /**
  * A check family: an id, a human title, and an async `run` returning per-item

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.103.24",
+  "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.71",
+    "@indigoai-us/hq-cloud": "~6.15.80",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",