@indigoai-us/hq-cli 5.206.0 → 5.207.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.207.0] — 2026-09-26
+
+### Added
+
+- The SessionStart hook can send client health reports straight to Sentry when
+  the company enables `client-health.sentry-direct`. Reports exclude doctor
+  text and company names. With the flag off, the hook keeps using the existing
+  feedback route.
+
 ## [5.206.0] — 2026-09-26
 
 ### Fixed

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

@@ -5552,6 +5552,15 @@ export declare const COMMAND_CATALOG: readonly [{
     }, {
         readonly flags: "--client-health-report";
         readonly description: "Resolve the opt-in hq-flags gate used by the client-health report hook.";
+    }, {
+        readonly flags: "--client-health-sentry";
+        readonly description: "Send the opt-in client-health Sentry report from a doctor JSON document.";
+    }, {
+        readonly flags: "--json-input <file>";
+        readonly description: "Doctor JSON input for the client-health report.";
+    }, {
+        readonly flags: "--client-health-fix-outcome <outcome>";
+        readonly description: "Safe fix outcome label for the client-health report.";
     }, {
         readonly flags: "--yes";
         readonly description: "Skip the interactive --fix confirmation (non-interactive use).";

package/dist/command-catalog.generated.js

@@ -7163,6 +7163,18 @@ export const COMMAND_CATALOG = [
                 "flags": "--client-health-report",
                 "description": "Resolve the opt-in hq-flags gate used by the client-health report hook."
             },
+            {
+                "flags": "--client-health-sentry",
+                "description": "Send the opt-in client-health Sentry report from a doctor JSON document."
+            },
+            {
+                "flags": "--json-input <file>",
+                "description": "Doctor JSON input for the client-health report."
+            },
+            {
+                "flags": "--client-health-fix-outcome <outcome>",
+                "description": "Safe fix outcome label for the client-health report."
+            },
             {
                 "flags": "--yes",
                 "description": "Skip the interactive --fix confirmation (non-interactive use)."

package/dist/commands/doctor.js

@@ -33,6 +33,9 @@ import { PARITY_FAMILY_ID, PARITY_FAMILY_TITLE, runParityReplay, } from "../lib/
 import { applyFixes } from "../lib/doctor/fix/apply.js";
 import { renderDoctorFixJson } from "../lib/doctor/fix/json-output.js";
 import { clientHealthReasonCodesEnabled as isActiveCompanyClientHealthReasonCodesEnabled, clientHealthReasonCodesEnabledForCompany, } from "../lib/doctor/client-health-reason-codes-flag.js";
+import { CLIENT_HEALTH_SENTRY_MAX_INPUT_BYTES, CLIENT_HEALTH_SENTRY_NOT_HANDLED_EXIT_CODE, handleClientHealthSentryReport, } from "../lib/doctor/client-health-sentry.js";
+import { clientHealthSentryDirectEnabled, clientHealthSentryDirectEnabledForCompany, } from "../lib/doctor/client-health-sentry-flag.js";
+import { reportClientHealthEvents } from "../lib/core-utils/sentry-report.js";
 import { isCompanyJournalSlug } from "../lib/doctor/checks/sync-health.js";
 import { readCompaniesManifestMap } from "../lib/work-context/repo-remote.js";
 import * as readline from "node:readline";
@@ -241,6 +244,26 @@ function createClientHealthReasonCodeCompanyResolver(hqRoot) {
         });
     };
 }
+function createClientHealthSentryCompanyResolver(hqRoot) {
+    const companies = readCompaniesManifestMap(hqRoot);
+    return async (companySlug) => {
+        if (companySlug === null)
+            return clientHealthSentryDirectEnabled();
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(companySlug))
+            return false;
+        const manifestUid = companies?.[companySlug]?.cloud_uid;
+        const activeSlug = process.env.HQ_COMPANY_SLUG?.trim() || "";
+        const activeUid = process.env.HQ_COMPANY_UID?.trim() || "";
+        const companyUid = typeof manifestUid === "string" && manifestUid.trim()
+            ? manifestUid.trim()
+            : companySlug === activeSlug
+                ? activeUid
+                : "";
+        if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid))
+            return false;
+        return clientHealthSentryDirectEnabledForCompany({ companyUid, companySlug });
+    };
+}
 /** Register the top-level `hq doctor` command so it appears in `hq --help`. */
 export function registerDoctorCommand(program) {
     program
@@ -256,6 +279,9 @@ export function registerDoctorCommand(program) {
         .option("--only <families>", "Run only these comma-separated check families (e.g. hooks). Unknown names are rejected; --json then records the scope.")
         .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
         .addOption(new Option("--client-health-report", "Resolve the opt-in hq-flags gate used by the client-health report hook.").hideHelp())
+        .addOption(new Option("--client-health-sentry", "Send the opt-in client-health Sentry report from a doctor JSON document.").hideHelp())
+        .addOption(new Option("--json-input <file>", "Doctor JSON input for the client-health report.").hideHelp())
+        .addOption(new Option("--client-health-fix-outcome <outcome>", "Safe fix outcome label for the client-health report.").hideHelp())
         .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
         .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
         .action(async (opts) => {
@@ -272,6 +298,54 @@ export function registerDoctorCommand(program) {
             process.exitCode = 1;
             return;
         }
+        if (opts.clientHealthSentry === true) {
+            const hqRoot = resolveHqRoot();
+            if (!hqRoot || !opts.jsonInput) {
+                process.stderr.write("hq doctor --client-health-sentry requires an HQ root and --json-input.\n");
+                process.exitCode = 1;
+                return;
+            }
+            try {
+                const workspacePath = path.join(hqRoot, "workspace");
+                const workspaceStat = fs.lstatSync(workspacePath);
+                if (!workspaceStat.isDirectory() || workspaceStat.isSymbolicLink()) {
+                    throw new Error("workspace is not a local directory");
+                }
+                const statePath = path.join(hqRoot, "workspace", ".hq-client-health");
+                const stateStat = fs.lstatSync(statePath);
+                if (!stateStat.isDirectory() || stateStat.isSymbolicLink()) {
+                    throw new Error("client-health state is not a local directory");
+                }
+                const stateRoot = fs.realpathSync(statePath);
+                const inputPath = fs.realpathSync(opts.jsonInput);
+                const relativeInput = path.relative(stateRoot, inputPath);
+                if (relativeInput === ".." || relativeInput.startsWith(`..${path.sep}`) || path.isAbsolute(relativeInput)) {
+                    throw new Error("input path is outside client-health state");
+                }
+                if (fs.statSync(inputPath).size > CLIENT_HEALTH_SENTRY_MAX_INPUT_BYTES) {
+                    throw new Error("input exceeds client-health size limit");
+                }
+                const result = await handleClientHealthSentryReport({
+                    hqRoot,
+                    doctorJson: fs.readFileSync(inputPath, "utf8"),
+                    fixOutcome: opts.clientHealthFixOutcome ?? "not_auto_fixable",
+                }, {
+                    resolveFlagForCompany: createClientHealthSentryCompanyResolver(hqRoot),
+                    sendEvents: async (events) => (await reportClientHealthEvents(events)).code === 0,
+                });
+                process.exitCode =
+                    result === "not_handled"
+                        ? CLIENT_HEALTH_SENTRY_NOT_HANDLED_EXIT_CODE
+                        : result === "send_failed"
+                            ? 1
+                            : 0;
+            }
+            catch {
+                process.stderr.write("hq doctor --client-health-sentry could not handle the report.\n");
+                process.exitCode = 1;
+            }
+            return;
+        }
         // `--fix` is the only write path. It resolves the tree, applies the
         // allowlisted repairs behind a backup + confirmation, and returns its own
         // exit code; the read-only report below never runs in this branch.

package/dist/lib/core-utils/sentry-report.d.ts

@@ -17,6 +17,7 @@
  */
 import * as Sentry from "@sentry/node";
 import type { CaptureContext, SeverityLevel } from "@sentry/node";
+import type { ClientHealthSentryEvent } from "../doctor/client-health-sentry.js";
 export declare const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
 export declare const MAX_SENTRY_REPORT_TIMEOUT_MS = 5000;
 export declare const MAX_SENTRY_REPORT_PAYLOAD_BYTES = 2048;
@@ -95,6 +96,17 @@ export type SentryReportResult = {
     event?: SentryReportEvent;
     droppedMetadataKeys?: number;
 };
+export interface ClientHealthSentryScope {
+    clear(): void;
+    setLevel(level: SeverityLevel): void;
+    setFingerprint(fingerprint: string[]): void;
+    setTags(tags: Record<string, string>): void;
+    setUser(user: {
+        id: string;
+        ip_address: null;
+    }): void;
+}
+export type ClientHealthSentryScopeRunner = (callback: (scope: ClientHealthSentryScope) => void) => void;
 /**
  * Read no more than the accepted event size. Returning early keeps a malformed
  * pipe from making a watchdog retain an unbounded hook payload in memory.
@@ -117,4 +129,11 @@ export declare function parseSentryReportEvent(stdin: string): SentryReportResul
  * transport errors cannot echo event data back to a hook.
  */
 export declare function reportSentryEvent(stdin: string, options?: SentryReportOptions, dependencies?: SentryReportDependencies): Promise<SentryReportResult>;
+/** Send the client-health projection with a clean Sentry scope and no metadata payload. */
+export declare function reportClientHealthEvents(events: readonly ClientHealthSentryEvent[], options?: {
+    timeoutMs?: number;
+    scopeRunner?: ClientHealthSentryScopeRunner;
+}, dependencies?: SentryReportDependencies): Promise<{
+    code: 0 | 1;
+}>;
 //# sourceMappingURL=sentry-report.d.ts.map

package/dist/lib/core-utils/sentry-report.js

@@ -1033,4 +1033,65 @@ export async function reportSentryEvent(stdin, options = {}, dependencies = defa
     dependencies.stderr.write("Sentry report failed.\n");
     return invalidInput();
 }
+function isSafeClientHealthEvent(event) {
+    const tags = event.tags;
+    const checkClass = tags.check_class;
+    const reasonCode = tags.reason_code;
+    const classPattern = /^sync\.(?:update\.core|journal\.(?:personal|personal_vault|company)|manifest\.(?:personal|personal_vault|company))$|^other$/;
+    const reasonPattern = /^(?:none|core-version-unavailable|core-update-available|no-local-tree|never-synced|invalid-last-sync|stale-threshold|manifest-unavailable|manifest-state-unavailable|no-manifest-scopes|never-uploaded|invalid-upload-time|unresolved-company-uid)$/;
+    const versionPattern = /^(?:unknown|\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?(?:\+[A-Za-z0-9.-]+)?)$/;
+    const safeTagKeys = [
+        "check_class", "reason_code", "fix_outcome", "status", "failing_check_count",
+        "cli_version", "core_version", "sync_version", "platform", "arch",
+    ];
+    return (event.level === "warning" &&
+        classPattern.test(checkClass) &&
+        reasonPattern.test(reasonCode) &&
+        event.message === `Client health: ${checkClass} unresolved after hq doctor --fix` &&
+        event.fingerprint.length === 3 &&
+        event.fingerprint[0] === "client-health" &&
+        event.fingerprint[1] === checkClass &&
+        event.fingerprint[2] === reasonCode &&
+        (tags.fix_outcome === "not_auto_fixable" || tags.fix_outcome === "fix_failed" || tags.fix_outcome === "fix_timed_out") &&
+        (tags.status === "FAIL" || tags.status === "WARN") &&
+        /^\d{1,3}$/.test(tags.failing_check_count) &&
+        safeTagKeys.every((key) => Object.hasOwn(tags, key)) &&
+        Object.keys(tags).length === safeTagKeys.length &&
+        [tags.cli_version, tags.core_version, tags.sync_version].every((value) => versionPattern.test(value)) &&
+        /^[a-z0-9]+$/.test(tags.platform) &&
+        /^[a-z0-9]+$/.test(tags.arch) &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(event.user.id) &&
+        event.user.ip_address === null);
+}
+/** Send the client-health projection with a clean Sentry scope and no metadata payload. */
+export async function reportClientHealthEvents(events, options = {}, dependencies = defaultDependencies) {
+    const timeoutMs = resolveTimeout(options.timeoutMs);
+    if (timeoutMs === null ||
+        events.length === 0 ||
+        events.length > 250 ||
+        events.some((event) => !isSafeClientHealthEvent(event))) {
+        dependencies.stderr.write("Invalid client health Sentry event.\n");
+        return { code: 1 };
+    }
+    const withScope = options.scopeRunner ?? ((callback) => Sentry.withScope((scope) => callback(scope)));
+    try {
+        for (const event of events) {
+            withScope((scope) => {
+                scope.clear();
+                scope.setLevel(event.level);
+                scope.setFingerprint([...event.fingerprint]);
+                scope.setTags({ sentry_event_type: "client_health", ...event.tags });
+                scope.setUser({ id: event.user.id, ip_address: null });
+                dependencies.sentry.captureMessage(event.message);
+            });
+        }
+        if (await flushWithin(dependencies.sentry, timeoutMs))
+            return { code: 0 };
+    }
+    catch {
+        // Keep the event and transport details out of hook stderr.
+    }
+    dependencies.stderr.write("Client health Sentry report failed.\n");
+    return { code: 1 };
+}
 //# sourceMappingURL=sentry-report.js.map

package/dist/lib/doctor/client-health-sentry-flag.d.ts

@@ -0,0 +1,22 @@
+import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-client";
+export declare const CLIENT_HEALTH_SENTRY_DIRECT_FLAG = "client-health.sentry-direct";
+export declare const CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK = false;
+export declare const CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS = 150;
+type ClientHealthFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface ClientHealthSentryFlagDependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => ClientHealthFlagClient;
+    getToken?: FlagClientOptions["getToken"];
+    fetch?: typeof fetch;
+    reportFailure?: (error: unknown) => void;
+}
+export interface ClientHealthSentryCompany {
+    companyUid: string;
+    companySlug?: string;
+}
+/** Resolve the active company gate with a bounded hq-flags read. */
+export declare function clientHealthSentryDirectEnabled(dependencies?: ClientHealthSentryFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+/** Resolve the default-off gate for one explicitly identified company. */
+export declare function clientHealthSentryDirectEnabledForCompany(company: ClientHealthSentryCompany, dependencies?: ClientHealthSentryFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+export {};
+//# sourceMappingURL=client-health-sentry-flag.d.ts.map

package/dist/lib/doctor/client-health-sentry-flag.js

@@ -0,0 +1,88 @@
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { createFlagClient, } from "@indigoai-us/hq-flags-client";
+import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+export const CLIENT_HEALTH_SENTRY_DIRECT_FLAG = "client-health.sentry-direct";
+export const CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK = false;
+export const CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS = 150;
+function reportFlagFailure(error) {
+    const name = error instanceof Error ? error.name : "UnknownError";
+    const safeName = /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : "UnknownError";
+    process.stderr.write(`HQ client-health Sentry flag lookup failed (${safeName}); using default off.\n`);
+}
+function combineSignals(first, second) {
+    return first ? AbortSignal.any([first, second]) : second;
+}
+/** Resolve the active company gate with a bounded hq-flags read. */
+export async function clientHealthSentryDirectEnabled(dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const companyUid = env.HQ_COMPANY_UID?.trim() || "";
+    if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK;
+    }
+    return clientHealthSentryDirectEnabledForCompany({
+        companyUid,
+        companySlug: env.HQ_COMPANY_SLUG?.trim() || undefined,
+    }, dependencies, callerSignal);
+}
+/** Resolve the default-off gate for one explicitly identified company. */
+export async function clientHealthSentryDirectEnabledForCompany(company, dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const companyUid = company.companyUid.trim();
+    if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK;
+    }
+    const companySlug = company.companySlug?.trim() || "";
+    const deadline = AbortSignal.timeout(CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    let client;
+    let failed = false;
+    let failureReported = false;
+    let enabled = CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK;
+    const reportFailureOnce = (error) => {
+        failed = true;
+        if (failureReported)
+            return;
+        failureReported = true;
+        (dependencies.reportFailure ?? reportFlagFailure)(error);
+    };
+    try {
+        client = (dependencies.createClient ?? createFlagClient)({
+            endpoint: resolveFlagRegistryEndpoint(undefined, env),
+            companyUid,
+            ...(companySlug && /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/.test(companySlug)
+                ? { companyIdentifiers: [companySlug] }
+                : {}),
+            env: {},
+            getToken: dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? ""),
+            fetch: (input, init) => doFetch(input, {
+                ...init,
+                signal: combineSignals(init?.signal ?? undefined, signal),
+            }),
+            refreshIntervalMs: 0,
+            requestTimeoutMs: CLIENT_HEALTH_SENTRY_DIRECT_TIMEOUT_MS,
+            onError: reportFailureOnce,
+        });
+        await client.ready();
+        if (!failed && !signal.aborted) {
+            enabled = client.isEnabled(CLIENT_HEALTH_SENTRY_DIRECT_FLAG, {
+                fallback: CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK,
+            });
+        }
+    }
+    catch (error) {
+        reportFailureOnce(error);
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch (error) {
+            reportFailureOnce(error);
+        }
+    }
+    return failed || signal.aborted
+        ? CLIENT_HEALTH_SENTRY_DIRECT_FALLBACK
+        : enabled;
+}
+//# sourceMappingURL=client-health-sentry-flag.js.map

package/dist/lib/doctor/client-health-sentry.d.ts

@@ -0,0 +1,71 @@
+export declare const CLIENT_HEALTH_SENTRY_NOT_HANDLED_EXIT_CODE = 10;
+export declare const CLIENT_HEALTH_SENTRY_MAX_INPUT_BYTES: number;
+export declare const CLIENT_HEALTH_SENTRY_MAX_FINDINGS = 250;
+export declare const CLIENT_HEALTH_INSTALL_ID_FILENAME = "install-id";
+export declare const CLIENT_HEALTH_LAST_RESULT_FILENAME = "last-result.json";
+export type ClientHealthFixOutcome = "not_auto_fixable" | "fix_failed" | "fix_timed_out";
+export type ClientHealthStatus = "FAIL" | "WARN";
+export type ClientHealthCheckClass = "sync.update.core" | "sync.journal.personal" | "sync.journal.personal_vault" | "sync.journal.company" | "sync.manifest.personal" | "sync.manifest.personal_vault" | "sync.manifest.company" | "other";
+export interface ClientHealthSentryEvent {
+    message: string;
+    level: "warning";
+    fingerprint: ["client-health", ClientHealthCheckClass, string];
+    tags: {
+        check_class: ClientHealthCheckClass;
+        reason_code: string;
+        fix_outcome: ClientHealthFixOutcome;
+        status: ClientHealthStatus;
+        failing_check_count: string;
+        cli_version: string;
+        core_version: string;
+        sync_version: string;
+        platform: string;
+        arch: string;
+    };
+    user: {
+        id: string;
+        ip_address: null;
+    };
+}
+interface ClientHealthFinding {
+    checkClass: ClientHealthCheckClass;
+    companySlug: string | null;
+    reasonCode: string;
+    status: ClientHealthStatus;
+}
+export interface ClientHealthLastResult {
+    check_class: ClientHealthCheckClass;
+    outcome: ClientHealthFixOutcome;
+    next_step: string;
+    result_id: string;
+}
+export interface ClientHealthReportVersions {
+    cli: string | null;
+    core: string | null;
+    sync: string | null;
+}
+export interface ClientHealthSentryReportDependencies {
+    resolveFlagForCompany: (companySlug: string | null) => Promise<boolean>;
+    sendEvents: (events: readonly ClientHealthSentryEvent[]) => Promise<boolean>;
+    randomUUID?: () => string;
+    versions?: (hqRoot: string) => ClientHealthReportVersions;
+    platform?: () => string;
+    arch?: () => string;
+}
+/** Collapse company-specific doctor ids before any value can enter a Sentry event. */
+export declare function normalizeClientHealthCheckId(checkId: string): ClientHealthCheckClass;
+/** Keep only the doctor fields needed for safe health reporting. */
+export declare function parseClientHealthDoctorFindings(input: string): ClientHealthFinding[];
+/** Store a random UUID once per local HQ install, without using host identity. */
+export declare function getOrCreateClientHealthInstallId(hqRoot: string, randomUUID?: () => string): string;
+/**
+ * Report only after every finding's company has opted in. A mixed rollout
+ * falls back as one batch so the old path cannot duplicate partially sent rows.
+ */
+export declare function handleClientHealthSentryReport(input: {
+    hqRoot: string;
+    doctorJson: string;
+    fixOutcome: string;
+}, dependencies: ClientHealthSentryReportDependencies): Promise<"handled" | "not_handled" | "send_failed">;
+export {};
+//# sourceMappingURL=client-health-sentry.d.ts.map

package/dist/lib/doctor/client-health-sentry.js

@@ -0,0 +1,279 @@
+import { randomUUID as cryptoRandomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CLI_VERSION } from "../../cli-version.js";
+import { readSyncVersion } from "../../utils/feedback-versions.js";
+import { readHqVersion } from "../../utils/pack-contributions.js";
+export const CLIENT_HEALTH_SENTRY_NOT_HANDLED_EXIT_CODE = 10;
+export const CLIENT_HEALTH_SENTRY_MAX_INPUT_BYTES = 2 * 1024 * 1024;
+export const CLIENT_HEALTH_SENTRY_MAX_FINDINGS = 250;
+export const CLIENT_HEALTH_INSTALL_ID_FILENAME = "install-id";
+export const CLIENT_HEALTH_LAST_RESULT_FILENAME = "last-result.json";
+const STATE_DIRECTORY = path.join("workspace", ".hq-client-health");
+const REASON_CODES = new Set([
+    "core-version-unavailable",
+    "core-update-available",
+    "no-local-tree",
+    "never-synced",
+    "invalid-last-sync",
+    "stale-threshold",
+    "manifest-unavailable",
+    "manifest-state-unavailable",
+    "no-manifest-scopes",
+    "never-uploaded",
+    "invalid-upload-time",
+    "unresolved-company-uid",
+]);
+const FIX_OUTCOMES = new Set(["not_auto_fixable", "fix_failed", "fix_timed_out"]);
+const INSTALL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const VERSION = /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?(?:\+[A-Za-z0-9.-]+)?$/;
+const PLATFORMS = new Set([
+    "aix", "android", "darwin", "freebsd", "haiku", "linux", "openbsd",
+    "sunos", "win32", "cygwin",
+]);
+const ARCHITECTURES = new Set([
+    "arm", "arm64", "ia32", "loong64", "mips", "mipsel", "ppc", "ppc64",
+    "riscv64", "s390x", "x64",
+]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function cleanVersion(value) {
+    return value && VERSION.test(value) ? value : "unknown";
+}
+function cleanPlatform(value) {
+    return PLATFORMS.has(value) ? value : "unknown";
+}
+function cleanArchitecture(value) {
+    return ARCHITECTURES.has(value) ? value : "unknown";
+}
+/** Collapse company-specific doctor ids before any value can enter a Sentry event. */
+export function normalizeClientHealthCheckId(checkId) {
+    if (checkId === "sync.update.core")
+        return checkId;
+    if (checkId === "sync.journal.__hq_personal_vault__")
+        return "sync.journal.personal_vault";
+    if (checkId === "sync.manifest.__hq_personal_vault__")
+        return "sync.manifest.personal_vault";
+    const match = /^sync\.(journal|manifest)\.([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/.exec(checkId);
+    if (!match)
+        return "other";
+    const family = match[1];
+    const scope = match[2];
+    if (scope === "personal")
+        return `sync.${family}.personal`;
+    if (family === "manifest" && scope.startsWith("unresolved."))
+        return "other";
+    return `sync.${family}.company`;
+}
+function companySlugForCheck(checkId, checkClass) {
+    if (checkClass !== "sync.journal.company" && checkClass !== "sync.manifest.company") {
+        return null;
+    }
+    const match = /^sync\.(?:journal|manifest)\.([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/.exec(checkId);
+    return match?.[1] ?? null;
+}
+function safeReasonCode(value) {
+    return typeof value === "string" && REASON_CODES.has(value) ? value : "none";
+}
+function safeFixOutcome(value) {
+    return FIX_OUTCOMES.has(value) ? value : "not_auto_fixable";
+}
+/** Keep only the doctor fields needed for safe health reporting. */
+export function parseClientHealthDoctorFindings(input) {
+    if (Buffer.byteLength(input, "utf8") > CLIENT_HEALTH_SENTRY_MAX_INPUT_BYTES) {
+        throw new Error("Client health doctor input exceeds its size limit");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch {
+        throw new Error("Client health doctor input is invalid JSON");
+    }
+    if (!isRecord(parsed) || !Array.isArray(parsed.results)) {
+        throw new Error("Client health doctor input has no results array");
+    }
+    const findings = [];
+    for (const value of parsed.results) {
+        if (!isRecord(value) || value.family !== "sync")
+            continue;
+        if (value.status !== "FAIL" && value.status !== "WARN")
+            continue;
+        if (value.checkId === "sync.update.core" && value.status === "WARN")
+            continue;
+        const checkId = typeof value.checkId === "string" &&
+            /^sync\.[A-Za-z0-9._-]{1,160}$/.test(value.checkId)
+            ? value.checkId
+            : "unknown";
+        const checkClass = normalizeClientHealthCheckId(checkId);
+        findings.push({
+            checkClass,
+            companySlug: companySlugForCheck(checkId, checkClass),
+            reasonCode: safeReasonCode(value.reasonCode),
+            status: value.status,
+        });
+        if (findings.length > CLIENT_HEALTH_SENTRY_MAX_FINDINGS) {
+            throw new Error("Client health doctor input has too many sync findings");
+        }
+    }
+    return findings;
+}
+function defaultVersions(hqRoot) {
+    let core;
+    try {
+        core = readHqVersion(hqRoot);
+    }
+    catch {
+        core = null;
+    }
+    let sync;
+    try {
+        sync = readSyncVersion();
+    }
+    catch {
+        sync = null;
+    }
+    return { cli: CLI_VERSION, core, sync };
+}
+function stateDirectory(hqRoot) {
+    const root = fs.realpathSync(hqRoot);
+    const workspacePath = path.join(root, "workspace");
+    fs.mkdirSync(workspacePath, { recursive: true, mode: 0o700 });
+    const workspaceStat = fs.lstatSync(workspacePath);
+    if (!workspaceStat.isDirectory() || workspaceStat.isSymbolicLink()) {
+        throw new Error("Client health state workspace is not a local directory");
+    }
+    const directory = path.join(root, STATE_DIRECTORY);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const directoryStat = fs.lstatSync(directory);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
+        throw new Error("Client health state directory is not a local directory");
+    }
+    fs.chmodSync(directory, 0o700);
+    return directory;
+}
+function readInstallId(filePath) {
+    try {
+        const fileStat = fs.lstatSync(filePath);
+        if (!fileStat.isFile() || fileStat.isSymbolicLink()) {
+            throw new Error("Client health install id is not a regular local file");
+        }
+        const value = fs.readFileSync(filePath, "utf8").trim();
+        if (!INSTALL_ID.test(value))
+            throw new Error("Client health install id is invalid");
+        fs.chmodSync(filePath, 0o600);
+        return value;
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+/** Store a random UUID once per local HQ install, without using host identity. */
+export function getOrCreateClientHealthInstallId(hqRoot, randomUUID = cryptoRandomUUID) {
+    const directory = stateDirectory(hqRoot);
+    const filePath = path.join(directory, CLIENT_HEALTH_INSTALL_ID_FILENAME);
+    const current = readInstallId(filePath);
+    if (current)
+        return current;
+    const candidate = randomUUID();
+    if (!INSTALL_ID.test(candidate))
+        throw new Error("Client health random id source returned an invalid id");
+    try {
+        fs.writeFileSync(filePath, `${candidate}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        return candidate;
+    }
+    catch (error) {
+        if (!isRecord(error) || error.code !== "EEXIST")
+            throw error;
+        const raced = readInstallId(filePath);
+        if (!raced)
+            throw new Error("Client health install id was not created");
+        return raced;
+    }
+}
+function nextStep(checkClass) {
+    switch (checkClass) {
+        case "sync.update.core":
+            return "HQ couldn't update itself automatically. Run `hq update` or `/update-hq`, then restart this session.";
+        case "sync.journal.personal":
+        case "sync.journal.personal_vault":
+            return "HQ hasn't synced your personal files in over 7 days and the automatic fix did not work. Run `hq sync` and check the result. If it fails, run `hq doctor` and send the output to support.";
+        case "sync.journal.company":
+            return "HQ hasn't synced this company's files in over 7 days and the automatic fix did not work. Run `hq sync` and check the result. If it fails, run `hq doctor` and send the output to support.";
+        case "sync.manifest.personal":
+        case "sync.manifest.personal_vault":
+            return "HQ couldn't read your personal sync list. Run `hq doctor --fix`. If it still fails, run `hq login` again.";
+        case "sync.manifest.company":
+            return "HQ couldn't read a company sync manifest. Run `hq doctor --fix`. If it still fails, run `hq login` again.";
+        default:
+            return "HQ still reports a sync health issue after its automatic fix. Run `hq doctor` and send the output to support.";
+    }
+}
+function writeLastResult(hqRoot, finding, outcome, randomUUID) {
+    const directory = stateDirectory(hqRoot);
+    const result = {
+        check_class: finding.checkClass,
+        outcome,
+        next_step: nextStep(finding.checkClass),
+        result_id: randomUUID(),
+    };
+    if (!INSTALL_ID.test(result.result_id))
+        throw new Error("Client health result id source returned an invalid id");
+    const filePath = path.join(directory, CLIENT_HEALTH_LAST_RESULT_FILENAME);
+    const tempPath = path.join(directory, `${CLIENT_HEALTH_LAST_RESULT_FILENAME}.${result.result_id}.tmp`);
+    fs.writeFileSync(tempPath, `${JSON.stringify(result, null, 2)}\n`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o600,
+    });
+    fs.renameSync(tempPath, filePath);
+    return result;
+}
+function buildEvent(finding, installId, outcome, failingCount, versions, platform, arch) {
+    const reasonCode = finding.reasonCode;
+    return {
+        message: `Client health: ${finding.checkClass} unresolved after hq doctor --fix`,
+        level: "warning",
+        fingerprint: ["client-health", finding.checkClass, reasonCode],
+        tags: {
+            check_class: finding.checkClass,
+            reason_code: reasonCode,
+            fix_outcome: outcome,
+            status: finding.status,
+            failing_check_count: String(failingCount),
+            cli_version: cleanVersion(versions.cli),
+            core_version: cleanVersion(versions.core),
+            sync_version: cleanVersion(versions.sync),
+            platform: cleanPlatform(platform),
+            arch: cleanArchitecture(arch),
+        },
+        user: { id: installId, ip_address: null },
+    };
+}
+/**
+ * Report only after every finding's company has opted in. A mixed rollout
+ * falls back as one batch so the old path cannot duplicate partially sent rows.
+ */
+export async function handleClientHealthSentryReport(input, dependencies) {
+    const findings = parseClientHealthDoctorFindings(input.doctorJson);
+    if (findings.length === 0)
+        return "handled";
+    const outcome = safeFixOutcome(input.fixOutcome);
+    const companySlugs = [...new Set(findings.map((finding) => finding.companySlug))];
+    const enabled = await Promise.all(companySlugs.map((companySlug) => dependencies.resolveFlagForCompany(companySlug)));
+    if (enabled.some((value) => value !== true))
+        return "not_handled";
+    const randomUUID = dependencies.randomUUID ?? cryptoRandomUUID;
+    const installId = getOrCreateClientHealthInstallId(input.hqRoot, randomUUID);
+    const versions = (dependencies.versions ?? defaultVersions)(input.hqRoot);
+    const events = findings.map((finding) => buildEvent(finding, installId, outcome, findings.length, versions, cleanPlatform((dependencies.platform ?? (() => process.platform))()), cleanArchitecture((dependencies.arch ?? os.arch)())));
+    writeLastResult(input.hqRoot, findings[0], outcome, randomUUID);
+    if (!(await dependencies.sendEvents(events)))
+        return "send_failed";
+    return "handled";
+}
+//# sourceMappingURL=client-health-sentry.js.map

package/dist/sentry-before-send.js

@@ -175,6 +175,86 @@ function scrubFields(value, memo = new Map()) {
     return out;
 }
 export function beforeSend(event, _hint) {
+    if (event.tags?.sentry_event_type === "client_health") {
+        const sourceTags = (event.tags ?? {});
+        const checkClasses = new Set([
+            "sync.update.core",
+            "sync.journal.personal",
+            "sync.journal.personal_vault",
+            "sync.journal.company",
+            "sync.manifest.personal",
+            "sync.manifest.personal_vault",
+            "sync.manifest.company",
+            "other",
+        ]);
+        const reasonCodes = new Set([
+            "none",
+            "core-version-unavailable",
+            "core-update-available",
+            "no-local-tree",
+            "never-synced",
+            "invalid-last-sync",
+            "stale-threshold",
+            "manifest-unavailable",
+            "manifest-state-unavailable",
+            "no-manifest-scopes",
+            "never-uploaded",
+            "invalid-upload-time",
+            "unresolved-company-uid",
+        ]);
+        const platforms = new Set([
+            "aix", "android", "darwin", "freebsd", "haiku", "linux", "openbsd",
+            "sunos", "win32", "cygwin",
+        ]);
+        const architectures = new Set([
+            "arm", "arm64", "ia32", "loong64", "mips", "mipsel", "ppc", "ppc64",
+            "riscv64", "s390x", "x64",
+        ]);
+        const versionPattern = /^(?:unknown|\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?(?:\+[A-Za-z0-9.-]+)?)$/;
+        const id = typeof event.user?.id === "string" &&
+            /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(event.user.id)
+            ? event.user.id
+            : undefined;
+        const checkClass = typeof sourceTags.check_class === "string" && checkClasses.has(sourceTags.check_class)
+            ? sourceTags.check_class
+            : "other";
+        const reasonCode = typeof sourceTags.reason_code === "string" && reasonCodes.has(sourceTags.reason_code)
+            ? sourceTags.reason_code
+            : "none";
+        const fixOutcome = ["not_auto_fixable", "fix_failed", "fix_timed_out"].includes(String(sourceTags.fix_outcome)) ? String(sourceTags.fix_outcome) : "not_auto_fixable";
+        const status = sourceTags.status === "WARN" ? "WARN" : "FAIL";
+        const count = typeof sourceTags.failing_check_count === "string" &&
+            /^[1-9]\d{0,2}$/.test(sourceTags.failing_check_count) &&
+            Number(sourceTags.failing_check_count) <= 250
+            ? sourceTags.failing_check_count
+            : "1";
+        const safeVersion = (value) => typeof value === "string" && versionPattern.test(value) ? value : "unknown";
+        const safePlatform = (value) => typeof value === "string" && platforms.has(value) ? value : "unknown";
+        const safeArchitecture = (value) => typeof value === "string" && architectures.has(value) ? value : "unknown";
+        return {
+            type: undefined,
+            ...(typeof event.event_id === "string" ? { event_id: event.event_id } : {}),
+            ...(typeof event.timestamp === "number" ? { timestamp: event.timestamp } : {}),
+            platform: "node",
+            level: "warning",
+            message: `Client health: ${checkClass} unresolved after hq doctor --fix`,
+            fingerprint: ["client-health", checkClass, reasonCode],
+            tags: {
+                sentry_event_type: "client_health",
+                check_class: checkClass,
+                reason_code: reasonCode,
+                fix_outcome: fixOutcome,
+                status,
+                failing_check_count: count,
+                cli_version: safeVersion(sourceTags.cli_version),
+                core_version: safeVersion(sourceTags.core_version),
+                sync_version: safeVersion(sourceTags.sync_version),
+                platform: safePlatform(sourceTags.platform),
+                arch: safeArchitecture(sourceTags.arch),
+            },
+            user: { ...(id ? { id } : {}), ip_address: null },
+        };
+    }
     if (event.request) {
         const req = event.request;
         event.request = {

package/package.json

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