@indigoai-us/hq-cli 5.206.0 → 5.208.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.208.0] — 2026-09-26
+
+### Fixed
+
+- `hq lanes accounts set-home` and `login` accept `--company <slug|uid>` and
+  scope the host-account-home flag read to that company.
+- The `hq daemon` updater now installs new hq-cloud patch releases. It looks up the newest release in the bundled major version and installs that exact version. Before, `npm install` with a version range kept an installed copy that already matched the range, so the updater stayed on 6.18.1 after 6.18.2 was published. A failed lookup is reported as a failed update and installs nothing.
+
+## [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).";
@@ -8163,6 +8172,9 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly options: readonly [{
                 readonly flags: "--host <hostname>";
                 readonly description: "Host key (defaults to this host's hostname)";
+            }, {
+                readonly flags: "--company <slug|uid>";
+                readonly description: "Company scope for the host-account-home flag";
             }, {
                 readonly flags: "--json";
                 readonly description: "JSON on stdout (always)";
@@ -8186,6 +8198,9 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly options: readonly [{
                 readonly flags: "--home <path>";
                 readonly description: "Account home directory";
+            }, {
+                readonly flags: "--company <slug|uid>";
+                readonly description: "Company scope for the host-account-home flag";
             }, {
                 readonly flags: "--device-auth";
                 readonly description: "Use Codex device authentication instead of localhost callback";

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)."
@@ -10559,6 +10571,10 @@ export const COMMAND_CATALOG = [
                                 "flags": "--host <hostname>",
                                 "description": "Host key (defaults to this host's hostname)"
                             },
+                            {
+                                "flags": "--company <slug|uid>",
+                                "description": "Company scope for the host-account-home flag"
+                            },
                             {
                                 "flags": "--json",
                                 "description": "JSON on stdout (always)"
@@ -10589,6 +10605,10 @@ export const COMMAND_CATALOG = [
                                 "flags": "--home <path>",
                                 "description": "Account home directory"
                             },
+                            {
+                                "flags": "--company <slug|uid>",
+                                "description": "Company scope for the host-account-home flag"
+                            },
                             {
                                 "flags": "--device-auth",
                                 "description": "Use Codex device authentication instead of localhost callback"

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

@@ -35,6 +35,8 @@ export interface LanesCommandDeps {
     now?: () => Date;
     hostname?: () => string;
     resolveCompany?: (company?: string) => Promise<LaneCompanyRef>;
+    /** Membership-backed explicit company selection for account-home writers. */
+    resolveActiveCompany?: (company: string) => Promise<LaneCompanyRef | null>;
     listOutpostIds?: () => Promise<string[]>;
     readOutpostIdentity?: () => OutpostIdentity;
     spawnLogin?: (opts: {

package/dist/commands/lanes.js

@@ -30,7 +30,9 @@ import { BALANCE_MOVABLE_STATES, CLAUDE_ACCOUNT_BALANCE_FLAG, accountLoadsForRep
 import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { backfillOutpostIdentityMarker as backfillOutpostIdentityMarkerImpl, createOutpostIdentityMarkerIfMissing, validateOutpostIdentityId, } from "../lib/lanes/outpost-identity.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
-import { openMeshTransport } from "../lib/mesh/client.js";
+import { resolveActiveMembershipCompany } from "../lib/mesh/api.js";
+import { openMeshTransport, requireToken } from "../lib/mesh/client.js";
+import { CompanySelectionError } from "../utils/company-selection-error.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshEventIdentity, } from "../lib/lanes/mesh-events.js";
 import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
 import { effectiveAccountHome } from "../lib/lanes/account-home.js";
@@ -88,11 +90,18 @@ function defaultLaneOutpostQuestionVisibilityEnabled(company, env) {
 function defaultLaneHostScopedAccountHomesEnabled(company, env) {
     return readLanesRegistryFlag(LANE_HOST_SCOPED_ACCOUNT_HOMES_FLAG, { company, env });
 }
-async function hostScopedAccountHomesEnabled(ctx) {
+async function hostScopedAccountHomesEnabled(ctx, company) {
     const localOverride = readLocalOverride(LANE_HOST_SCOPED_ACCOUNT_HOMES_FLAG, ctx.env);
     if (localOverride !== null)
         return localOverride;
-    return ctx.laneHostScopedAccountHomesEnabled(await ctx.resolveCompany());
+    return ctx.laneHostScopedAccountHomesEnabled(company ?? await ctx.resolveCompany());
+}
+async function resolveSelectedAccountHomeCompany(ctx, selector) {
+    const company = await ctx.resolveActiveCompany(selector);
+    if (!company) {
+        throw new CompanySelectionError(`No unique active company membership for ${selector}. Pass an active company UID with --company.`);
+    }
+    return company;
 }
 function withoutProviderHome(value) {
     if (Array.isArray(value))
@@ -158,6 +167,12 @@ async function defaultResolveCompany(company) {
     const { company: mesh } = await openMeshTransport({ company });
     return { slug: mesh.companySlug, uid: mesh.companyUid };
 }
+async function defaultResolveActiveCompany(company) {
+    const membership = await resolveActiveMembershipCompany(await requireToken(), company);
+    return membership
+        ? { slug: membership.companySlug, uid: membership.companyUid }
+        : null;
+}
 function defaultOutpostsClient() {
     return createOutpostsClient({
         transport: vaultApiFetch,
@@ -243,6 +258,7 @@ function resolveDeps(deps = {}) {
         now: deps.now ?? (() => new Date()),
         hostname: deps.hostname ?? (() => os.hostname()),
         resolveCompany: deps.resolveCompany ?? defaultResolveCompany,
+        resolveActiveCompany: deps.resolveActiveCompany ?? defaultResolveActiveCompany,
         listOutpostIds: deps.listOutpostIds ?? defaultListOutpostIds,
         readOutpostIdentity: deps.readOutpostIdentity ?? (() => readOutpostIdentity()),
         spawnLogin: deps.spawnLogin ?? defaultSpawnLogin,
@@ -7922,8 +7938,11 @@ async function runAccountsLogin(ctx, providerRaw, accountId, opts) {
     if (opts.home !== undefined && !requestedHome) {
         throw new LanesError("invalid_account_home", "--home must be a non-empty path", { provider, account: id });
     }
+    const company = opts.company !== undefined
+        ? await resolveSelectedAccountHomeCompany(ctx, opts.company)
+        : undefined;
     const hostScopedWriterEnabled = registeredAccount !== undefined && requestedHome !== undefined
-        ? await hostScopedAccountHomesEnabled(ctx)
+        ? await hostScopedAccountHomesEnabled(ctx, company)
         : false;
     const homeRaw = requestedHome ??
         (registeredAccount !== undefined
@@ -8017,7 +8036,10 @@ async function runAccountsLogin(ctx, providerRaw, accountId, opts) {
     printJson({ ok: true, action: "accounts.login", account: status });
 }
 async function runAccountsSetHome(ctx, providerRaw, accountIdRaw, homeRaw, opts) {
-    if (!(await hostScopedAccountHomesEnabled(ctx))) {
+    const company = opts.company !== undefined
+        ? await resolveSelectedAccountHomeCompany(ctx, opts.company)
+        : undefined;
+    if (!(await hostScopedAccountHomesEnabled(ctx, company))) {
         throw new LanesError("host_scoped_account_homes_disabled", "Setting a host-specific account home requires the lanes.host-scoped-account-homes flag", { flag: LANE_HOST_SCOPED_ACCOUNT_HOMES_FLAG });
     }
     const callerCwd = ctx.callerCwd();
@@ -8689,6 +8711,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .argument("<account-id>", "Existing account id")
         .argument("<path>", "Home directory for this host")
         .option("--host <hostname>", "Host key (defaults to this host's hostname)")
+        .option("--company <slug|uid>", "Company scope for the host-account-home flag")
         .option("--json", "JSON on stdout (always)")
         .action(wrap(async (provider, accountId, home, opts) => {
         await runAccountsSetHome(ctx, provider, accountId, home, opts);
@@ -8699,6 +8722,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .argument("<provider>", "claude | codex | grok")
         .argument("<account-id>", "Open-ended account id")
         .option("--home <path>", "Account home directory")
+        .option("--company <slug|uid>", "Company scope for the host-account-home flag")
         .option("--device-auth", "Use Codex device authentication instead of localhost callback")
         .action(wrap(async (provider, accountId, opts) => {
         await runAccountsLogin(ctx, provider, accountId, opts);

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/daemon/hq-cloud.d.ts

@@ -31,8 +31,21 @@ export interface HqCloudRunners {
     sessionHost: string | null;
 }
 export declare function hqCloudRunners(root: string, exists?: (p: string) => boolean): HqCloudRunners;
-/** Install the newest release of the bundled major version, never older than the bundled copy. */
-export declare function hqCloudInstallCommand(prefix: string, bundledVersion: string, platform?: NodeJS.Platform, pinnedVersion?: string): {
+/**
+ * Ask npm for every release of the bundled major version, no older than the
+ * bundled copy. The updater installs the newest one exactly: `npm install` with
+ * a range keeps an installed copy that already satisfies it, so a range alone
+ * never moves 6.18.1 to 6.18.2.
+ */
+export declare function hqCloudLatestCommand(bundledVersion: string, platform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+    shell: boolean;
+};
+/** The newest release in `npm view --json` output with the bundled major version, never older than it. */
+export declare function latestSameMajor(npmViewJson: string, bundledVersion: string): string | null;
+/** Install one exact hq-cloud version into the updater's folder. */
+export declare function hqCloudInstallCommand(prefix: string, version: string, platform?: NodeJS.Platform): {
     file: string;
     args: string[];
     shell: boolean;
@@ -48,6 +61,17 @@ export interface HqCloudUpdateOutcome {
     to: string | null;
     detail?: string;
 }
+export interface NpmRunResult {
+    status: number | null;
+    stdout?: string | null;
+    stderr?: string | null;
+    error?: Error;
+}
+export interface UpdateHqCloudDeps {
+    run?: (file: string, args: string[], shell: boolean, env: NodeJS.ProcessEnv) => NpmRunResult;
+    bundled?: HqCloudCopy | null;
+    platform?: NodeJS.Platform;
+}
 /** Install or update the updater's copy, as this (the login) user. */
-export declare function updateManagedHqCloud(daemonRoot: string, env: NodeJS.ProcessEnv): HqCloudUpdateOutcome;
+export declare function updateManagedHqCloud(daemonRoot: string, env: NodeJS.ProcessEnv, deps?: UpdateHqCloudDeps): HqCloudUpdateOutcome;
 //# sourceMappingURL=hq-cloud.d.ts.map

package/dist/lib/daemon/hq-cloud.js

@@ -61,18 +61,45 @@ export function hqCloudRunners(root, exists = fs.existsSync) {
         sessionHost: bin("outpost-session-host.js"),
     };
 }
-/** Install the newest release of the bundled major version, never older than the bundled copy. */
-export function hqCloudInstallCommand(prefix, bundledVersion, platform = process.platform, pinnedVersion) {
+/**
+ * Ask npm for every release of the bundled major version, no older than the
+ * bundled copy. The updater installs the newest one exactly: `npm install` with
+ * a range keeps an installed copy that already satisfies it, so a range alone
+ * never moves 6.18.1 to 6.18.2.
+ */
+export function hqCloudLatestCommand(bundledVersion, platform = process.platform) {
+    const plan = buildSpawnPlan("npm", ["view", `${HQ_CLOUD_PACKAGE}@^${bundledVersion}`, "version", "--json"], platform);
+    return { file: plan.cmd, args: plan.args, shell: plan.shell };
+}
+/** The newest release in `npm view --json` output with the bundled major version, never older than it. */
+export function latestSameMajor(npmViewJson, bundledVersion) {
+    const b = parseVersion(bundledVersion);
+    if (!b)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(npmViewJson);
+    }
+    catch {
+        return null;
+    }
+    const versions = typeof parsed === "string" ? [parsed] : Array.isArray(parsed) ? parsed : [];
+    let best = null;
+    for (const text of versions) {
+        if (typeof text !== "string" || !/^\d+\.\d+\.\d+$/.test(text))
+            continue;
+        const v = parseVersion(text);
+        if (v[0] !== b[0] || newer(b, v))
+            continue;
+        if (!best || newer(v, best.v))
+            best = { text, v };
+    }
+    return best?.text ?? null;
+}
+/** Install one exact hq-cloud version into the updater's folder. */
+export function hqCloudInstallCommand(prefix, version, platform = process.platform) {
     // npm is a .cmd on Windows and needs the shell, so every argument is quoted for it.
-    const plan = buildSpawnPlan("npm", [
-        "install",
-        "--prefix",
-        prefix,
-        "--no-audit",
-        "--no-fund",
-        "--omit=dev",
-        `${HQ_CLOUD_PACKAGE}@${pinnedVersion ?? `^${bundledVersion}`}`,
-    ], platform);
+    const plan = buildSpawnPlan("npm", ["install", "--prefix", prefix, "--no-audit", "--no-fund", "--omit=dev", `${HQ_CLOUD_PACKAGE}@${version}`], platform);
     return { file: plan.cmd, args: plan.args, shell: plan.shell };
 }
 export function readHqCloudCopy(root) {
@@ -99,10 +126,26 @@ export function currentHqCloud(daemonRoot) {
     const pinnedVersion = readDaemonConfig(path.join(daemonRoot, "config.json")).hqCloudVersion;
     return pickHqCloud(bundledHqCloud(), readHqCloudCopy(managedHqCloudRoot(daemonRoot)), (copy) => hqCloudRunners(copy.root).syncRunner !== null, pinnedVersion);
 }
+function runNpm(file, args, shell, env) {
+    return spawnSync(file, args, {
+        encoding: "utf8",
+        env,
+        timeout: 10 * 60_000,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        shell,
+    });
+}
+function npmFailure(r) {
+    const tail = `${r.stderr ?? ""}\n${r.stdout ?? ""}`.trim().split("\n").slice(-3).join(" ").slice(0, 400);
+    return tail || (r.error ? r.error.message : `npm exited ${r.status ?? "by signal"}`);
+}
 /** Install or update the updater's copy, as this (the login) user. */
-export function updateManagedHqCloud(daemonRoot, env) {
+export function updateManagedHqCloud(daemonRoot, env, deps = {}) {
+    const run = deps.run ?? runNpm;
+    const platform = deps.platform ?? process.platform;
     const pinnedVersion = readDaemonConfig(path.join(daemonRoot, "config.json")).hqCloudVersion;
-    const bundled = bundledHqCloud();
+    const bundled = deps.bundled !== undefined ? deps.bundled : bundledHqCloud();
     const from = currentHqCloud(daemonRoot)?.version ?? null;
     if (!bundled)
         return { ok: false, from, to: null, detail: "this CLI install has no bundled hq-cloud to match" };
@@ -113,19 +156,22 @@ export function updateManagedHqCloud(daemonRoot, env) {
     catch (err) {
         return { ok: false, from, to: null, detail: `could not create ${prefix}: ${err instanceof Error ? err.message : String(err)}` };
     }
-    const cmd = hqCloudInstallCommand(prefix, bundled.version, process.platform, pinnedVersion);
-    const r = spawnSync(cmd.file, cmd.args, {
-        encoding: "utf8",
-        env,
-        timeout: 10 * 60_000,
-        stdio: ["ignore", "pipe", "pipe"],
-        windowsHide: true,
-        shell: cmd.shell,
-    });
-    if (r.status !== 0) {
-        const tail = `${r.stderr ?? ""}\n${r.stdout ?? ""}`.trim().split("\n").slice(-3).join(" ").slice(0, 400);
-        return { ok: false, from, to: null, detail: tail || (r.error ? r.error.message : `npm exited ${r.status ?? "by signal"}`) };
+    let version = pinnedVersion;
+    if (!version) {
+        const view = hqCloudLatestCommand(bundled.version, platform);
+        const r = run(view.file, view.args, view.shell, env);
+        if (r.status !== 0)
+            return { ok: false, from, to: null, detail: `could not look up the newest hq-cloud: ${npmFailure(r)}` };
+        const latest = latestSameMajor(r.stdout ?? "", bundled.version);
+        if (!latest) {
+            return { ok: false, from, to: null, detail: `npm listed no hq-cloud release at or above ${bundled.version} in the same major version` };
+        }
+        version = latest;
     }
+    const cmd = hqCloudInstallCommand(prefix, version, platform);
+    const r = run(cmd.file, cmd.args, cmd.shell, env);
+    if (r.status !== 0)
+        return { ok: false, from, to: null, detail: npmFailure(r) };
     return { ok: true, from, to: currentHqCloud(daemonRoot)?.version ?? null };
 }
 //# sourceMappingURL=hq-cloud.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.208.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {