@indigoai-us/hq-cli 5.205.0 → 5.207.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [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
+
+- Startup recovery no longer waits the full install deadline when an unchanged retired hq-cli package remains beside the install. Node 24 ESM loader file-read `ENOENT` errors also enter the existing recovery path and receive a report tag.
+
 ## [5.205.0] — 2026-09-26
 
 ### Added

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/dist/startup-registration.js

@@ -158,6 +158,7 @@ export async function registerCommandsWithRecovery(args) {
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                retiredSiblingPresent: result.retiredSiblingPresent,
                 sawTreeChange: result.sawTreeChange,
                 lockHeldAtEnd: result.lockHeldAtEnd,
                 lockedMs: result.lockedMs,
@@ -188,6 +189,7 @@ export async function registerCommandsWithRecovery(args) {
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                retiredSiblingPresent: result.retiredSiblingPresent,
                 sawTreeChange: result.sawTreeChange,
                 lockTool: result.lockTool,
             });

package/dist/utils/install-tree-torn.d.ts

@@ -39,8 +39,9 @@
  */
 export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT" | "EVAL_THROW";
 /**
- * The closed set of resolution-failure dialects, verified on Node v22.23.1 (the
- * @sentry/node import-in-the-middle hook does not change the shapes):
+ * The closed set of resolution-failure dialects, verified on Node v22.23.1 and
+ * the observed Node 24 synchronous ESM loader shape (the @sentry/node
+ * import-in-the-middle hook does not change the stack transfer):
  *   - `esm-path`:    ESM importer, an absolute file (or legacyMainResolve dir)
  *                    target — `err.url` set, or `Cannot find package '<abs>'…`.
  *   - `esm-package`: ESM importer, a bare specifier — `Cannot find package
@@ -62,7 +63,7 @@ export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "
  *                    held in Module._pathCache) and gone at READ, so the CJS
  *                    loader's source read (defaultLoadImpl/loadSource, or the older
  *                    Module._extensions..js handler) raises ENOENT with syscall
- *                    'open' and a cjs/loader frame but NO esm/load frame. `err.path`
+ *                    'open' and a cjs/loader frame but NO ESM source-read frame. `err.path`
  *                    is the vanished file.
  *   - `resolve-enoent`: ESM/CJS RESOLVE-time ENOENT (HQ-CLI-1S) — a path component
  *                    stat'ed OK, then vanished before realpathSync's lstat, so the
@@ -179,6 +180,13 @@ export interface InstallTreeFs {
     existsSync(p: string): boolean;
     statSync(p: string): {
         isDirectory(): boolean;
+        isSymbolicLink?(): boolean;
+        size?: number;
+        mtimeMs?: number;
+    };
+    lstatSync?(p: string): {
+        isDirectory(): boolean;
+        isSymbolicLink?(): boolean;
         size?: number;
         mtimeMs?: number;
     };
@@ -264,6 +272,8 @@ export interface WaitForInstallTreeSettledResult {
     sawTreeChange?: boolean;
     /** True when the lock-free tree stayed unchanged for `staleProbeMs`. */
     staleTree?: boolean;
+    /** Presence on the final poll; null means the sibling directory was unreadable. */
+    retiredSiblingPresent?: boolean | null;
 }
 export declare const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1500;
 /**
@@ -278,10 +288,11 @@ export declare const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1500;
  * app, the box's update timer, another `hq`) cannot make a legitimately-in-progress
  * reinstall look stale:
  *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
- *     by `deadlineMs`. If the target is still missing, no lock or retired sibling
- *     is present, and the observed tree stays unchanged for `staleProbeMs`, the
- *     wait returns `staleTree` early. Any observed tree change keeps the ordinary
- *     settle deadline in force. `deadlineMs === 0` evaluates readiness once.
+ *     by `deadlineMs`. If the target is still missing and the observed tree,
+ *     including retired sibling names and mtimes, stays unchanged for
+ *     `staleProbeMs`, the wait returns `staleTree` early. Any observed tree
+ *     change keeps the ordinary settle deadline in force. `deadlineMs === 0`
+ *     evaluates readiness once.
  *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
  *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
  *     10-minute staleness window) and does NOT consume the settle budget. When
@@ -342,6 +353,8 @@ export type InstallTreeTornDiagnostics = {
     /** The bounded `tool` of the last fresh foreign lock seen, or "". */
     lockTool: string;
     node: string;
+    /** Presence on the final poll when the scope directory could be observed. */
+    retiredSiblingPresent?: boolean;
     /** The thrown error's `name` for the eval-throw dialect (HQ-CLI-1T), else "". */
     errorName: string;
 };
@@ -363,6 +376,8 @@ export interface InstallTreeTornInit {
     lockedMs?: number;
     /** The last fresh foreign lock's `tool`, bounded on construction (default ""). */
     lockTool?: string;
+    /** Final retired sibling presence, or null when the scope directory was unreadable. */
+    retiredSiblingPresent?: boolean | null;
 }
 /**
  * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived

package/dist/utils/install-tree-torn.js

@@ -48,15 +48,33 @@ const ESM_PACKAGE_RE = /^Cannot find package '([^']+)' imported from (.+)$/s;
 const CJS_MODULE_RE = /^Cannot find module '([^']+)'/s;
 const ESM_MODULE_IMPORTED_RE = /^Cannot find module '([^']+)' imported from (.+)$/s;
 /**
- * The Node ESM loader's SOURCE-READ frame — `getSourceSync`/`defaultLoad` in
- * `node:internal/modules/esm/load`. Requiring the `esm/load` module frame (not
- * merely any frame under `modules/esm/`) is what proves the loader was READING
- * the module's source, so an ordinary `fs.openSync`/`readFileSync` ENOENT that
- * merely ESCAPES a module's EVALUATION — which runs under `esm/module_job`,
- * never `esm/load` — is NOT misclassified as a torn install and does not trigger
- * the settle wait. `load\b` also excludes the sibling `esm/loader` module.
+ * The Node ESM loader's SOURCE-READ helper in `node:internal/modules/esm/load`
+ * (Node 22) or `node:internal/modules/esm/loader` (Node 24's sync loader).
+ * `getSourceSync` must be the first non-`node:fs` caller after the source read;
+ * an ordinary fs ENOENT that escapes module evaluation therefore stays outside
+ * recovery even when an outer ModuleLoader frame exists.
  */
-const ESM_LOADER_FRAME = /node:internal[\\/]modules[\\/]esm[\\/]load\b/;
+const ESM_SOURCE_READ_FRAME = /^at getSourceSync \(node:internal[\\/]modules[\\/]esm[\\/](?:load|loader)\b/;
+const NODE_FS_FRAME = /^at .* \(node:fs\b/;
+/** True only when Node's ESM source-read helper called the failing fs read. */
+function hasEsmLoaderSourceReadFrame(stack) {
+    const frames = stack
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("at "));
+    let sawFsRead = false;
+    for (const frame of frames) {
+        if (!sawFsRead) {
+            if (NODE_FS_READ_FRAME.test(frame))
+                sawFsRead = true;
+            continue;
+        }
+        if (NODE_FS_FRAME.test(frame))
+            continue;
+        return ESM_SOURCE_READ_FRAME.test(frame);
+    }
+    return false;
+}
 /**
  * The Node module RESOLVER frame — `finalizeResolution` in
  * `node:internal/modules/esm/resolve` (the observed HQ-CLI-1S route, where
@@ -85,12 +103,12 @@ function hasModuleEvalFrame(stack) {
 }
 /**
  * The Node CJS loader's SOURCE-READ position (HQ-CLI-20) — the CJS twin of
- * {@link ESM_LOADER_FRAME}. A CJS require whose target was present at RESOLVE (its
+ * {@link hasEsmLoaderSourceReadFrame}. A CJS require whose target was present at RESOLVE (its
  * filename cached in Module._pathCache) and gone at READ fails inside the loader's
  * source read: `readFileSync (node:fs)` called by `defaultLoadImpl`/`loadSource`
  * (Node ≥22) or, on older Node, the `Module._extensions..js` extension handler —
  * all frames in `node:internal/modules/cjs/loader`, and (unlike HQ-CLI-1M) with NO
- * `esm/load` frame.
+ * ESM source-read frame.
  *
  * The discriminator is POSITIONAL: the innermost `node:fs` read frame's
  * IMMEDIATELY-following (caller) frame must be a cjs/loader frame that is NOT a
@@ -251,7 +269,7 @@ export function classifyModuleNotFound(err) {
         if (record.syscall === "open" &&
             typeof record.path === "string" &&
             typeof record.stack === "string" &&
-            ESM_LOADER_FRAME.test(record.stack)) {
+            hasEsmLoaderSourceReadFrame(record.stack)) {
             return {
                 code,
                 dialect: "esm-enoent",
@@ -263,7 +281,7 @@ export function classifyModuleNotFound(err) {
         // cjs-loader source-read ENOENT (HQ-CLI-20): the CJS twin of esm-enoent — a
         // require() whose target was present at RESOLVE (its filename held in
         // Module._pathCache) and gone at READ, so the CJS loader's source read raises
-        // ENOENT with syscall 'open' and a cjs/loader frame but NO esm/load frame
+        // ENOENT with syscall 'open' and a cjs/loader frame but NO ESM source-read frame
         // (which is why arm (0) missed it and classifyModuleNotFound returned null,
         // filing the bare HQ-CLI-20 capture). Gated on the FULL conjunction — code
         // ENOENT AND syscall 'open' AND a string path AND the POSITIONAL CJS
@@ -449,6 +467,7 @@ export function classifyEvalThrow(err, packageRoot) {
 const nodeInstallTreeFs = {
     existsSync: (p) => nodeFs.existsSync(p),
     statSync: (p) => nodeFs.statSync(p),
+    lstatSync: (p) => nodeFs.lstatSync(p),
     readFileSync: (p, encoding) => nodeFs.readFileSync(p, encoding),
     readdirSync: (p) => nodeFs.readdirSync(p),
 };
@@ -633,6 +652,56 @@ function retiredSiblingPresent(packageRoot, fs) {
     const entries = fs.readdirSync(parent); // caller treats a throw as "not ready"
     return entries.some((entry) => entry.startsWith(stagingPrefix));
 }
+/** Snapshot retired sibling trees so changes below their root stay observable. */
+function retiredSiblingActivitySignature(packageRoot, fs) {
+    const { leaf } = cliNameParts();
+    const stagingPrefix = `.${leaf}-`;
+    const parent = path.dirname(packageRoot);
+    const siblings = fs.readdirSync(parent).filter((entry) => entry.startsWith(stagingPrefix)).sort();
+    const snapshots = [["names", siblings]];
+    let observed = true;
+    let visited = 0;
+    const maxEntries = 20_000;
+    const maxDepth = 64;
+    const visit = (absolutePath, relativePath, depth) => {
+        visited += 1;
+        if (visited > maxEntries) {
+            observed = false;
+            return;
+        }
+        try {
+            const stat = fs.lstatSync ? fs.lstatSync(absolutePath) : fs.statSync(absolutePath);
+            const symbolicLink = stat.isSymbolicLink?.() ?? false;
+            const directory = !symbolicLink && stat.isDirectory();
+            const mtimeMs = stat.mtimeMs;
+            if (typeof mtimeMs !== "number" || !Number.isFinite(mtimeMs))
+                observed = false;
+            snapshots.push([
+                relativePath,
+                symbolicLink ? "symlink" : directory ? "directory" : "file",
+                stat.size ?? null,
+                typeof mtimeMs === "number" && Number.isFinite(mtimeMs) ? mtimeMs : null,
+            ]);
+            if (!directory)
+                return;
+            if (depth >= maxDepth) {
+                observed = false;
+                return;
+            }
+            for (const child of fs.readdirSync(absolutePath).sort()) {
+                visit(path.join(absolutePath, child), path.join(relativePath, child), depth + 1);
+            }
+        }
+        catch {
+            observed = false;
+            snapshots.push([relativePath, "unreadable"]);
+        }
+    };
+    for (const sibling of siblings) {
+        visit(path.join(parent, sibling), sibling, 0);
+    }
+    return { value: JSON.stringify(snapshots), observed };
+}
 /** Whether packageRoot's own manifest is healthy (`name === CLI_NAME`). */
 function packageRootHealthy(packageRoot, fs) {
     const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"));
@@ -754,6 +823,18 @@ function installTreeActivitySignature(target, packageRoot, fs) {
             snapshots.push([directory, `entries-unreadable:${errorCode(err)}`]);
         }
     }
+    if (packageRoot) {
+        try {
+            const retired = retiredSiblingActivitySignature(packageRoot, fs);
+            snapshots.push(["retired-siblings", retired.value]);
+            if (!retired.observed)
+                observed = false;
+        }
+        catch (err) {
+            observed = false;
+            snapshots.push(["retired-siblings-unreadable", errorCode(err)]);
+        }
+    }
     return { value: JSON.stringify(snapshots), observed };
 }
 export const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
@@ -769,10 +850,11 @@ export const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
  * app, the box's update timer, another `hq`) cannot make a legitimately-in-progress
  * reinstall look stale:
  *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
- *     by `deadlineMs`. If the target is still missing, no lock or retired sibling
- *     is present, and the observed tree stays unchanged for `staleProbeMs`, the
- *     wait returns `staleTree` early. Any observed tree change keeps the ordinary
- *     settle deadline in force. `deadlineMs === 0` evaluates readiness once.
+ *     by `deadlineMs`. If the target is still missing and the observed tree,
+ *     including retired sibling names and mtimes, stays unchanged for
+ *     `staleProbeMs`, the wait returns `staleTree` early. Any observed tree
+ *     change keeps the ordinary settle deadline in force. `deadlineMs === 0`
+ *     evaluates readiness once.
  *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
  *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
  *     10-minute staleness window) and does NOT consume the settle budget. When
@@ -839,7 +921,7 @@ export async function waitForInstallTreeSettled(args) {
             }
             lastActivitySnapshot = activitySnapshot;
         }
-        let retiredPresent = false;
+        let retiredPresent = null;
         let retiredCheckFailed = false;
         if (args.packageRoot) {
             try {
@@ -848,6 +930,7 @@ export async function waitForInstallTreeSettled(args) {
                     sawRetired = true;
             }
             catch {
+                retiredPresent = null;
                 retiredCheckFailed = true;
             }
         }
@@ -883,14 +966,13 @@ export async function waitForInstallTreeSettled(args) {
                 lockTool,
                 sawTreeChange,
                 staleTree: false,
+                retiredSiblingPresent: retiredPresent,
             };
         }
         if (!ready &&
             !foreignLockHeld &&
-            !retiredPresent &&
             !retiredCheckFailed &&
             !sawLock &&
-            !sawRetired &&
             !sawTreeChange &&
             staleObservationStartedAt !== null &&
             t - staleObservationStartedAt >= staleProbeMs) {
@@ -904,6 +986,7 @@ export async function waitForInstallTreeSettled(args) {
                 lockTool,
                 sawTreeChange,
                 staleTree: true,
+                retiredSiblingPresent: retiredPresent,
             };
         }
         // Give up when the TREE has had a full unlocked budget with no writer visible,
@@ -925,6 +1008,7 @@ export async function waitForInstallTreeSettled(args) {
                 lockTool,
                 sawTreeChange,
                 staleTree: false,
+                retiredSiblingPresent: retiredPresent,
             };
         }
         // The first poll at which the wait has reached `deadlineMs` while a lock is
@@ -1007,7 +1091,7 @@ export class InstallTreeTornError extends Error {
         this.cause = init.cause;
         const sawTreeChange = init.sawTreeChange ?? false;
         const treeState = init.treeState ?? (init.outcome === "stale_tree" ? "stale" : "in_flight");
-        this.diagnostics = {
+        const diagnostics = {
             dialect: init.classified.dialect,
             code: init.classified.code,
             specifier: boundedDiagnosticValue(init.classified.specifier, SPECIFIER_BYTES),
@@ -1026,6 +1110,10 @@ export class InstallTreeTornError extends Error {
             node: process.version,
             errorName: boundedDiagnosticValue(init.classified.errorName ?? "", ERRORNAME_BYTES),
         };
+        if (typeof init.retiredSiblingPresent === "boolean") {
+            diagnostics.retiredSiblingPresent = init.retiredSiblingPresent;
+        }
+        this.diagnostics = diagnostics;
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }

package/dist/utils/sentry-fingerprint.js

@@ -240,6 +240,15 @@ export function installTreeTornSentryTagsFor(err) {
         tree_state: installTreeStateTag(diagnostics.treeState),
         os: installTreeOsTag(process.platform),
     };
+    if (diagnostics.code === "ERR_MODULE_NOT_FOUND" || diagnostics.code === "MODULE_NOT_FOUND") {
+        tags.error_shape = "module_not_found";
+    }
+    else if (diagnostics.code === "ENOENT") {
+        tags.error_shape = "loader_enoent";
+    }
+    if (typeof diagnostics.retiredSiblingPresent === "boolean") {
+        tags.retired_sibling = diagnostics.retiredSiblingPresent ? "present" : "absent";
+    }
     if (recoveryOutcome)
         tags.recovery_outcome = recoveryOutcome;
     const lockTool = diagnostics.lockTool;

package/package.json

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