@indigoai-us/hq-cli 5.182.0 → 5.184.0

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

@@ -23,6 +23,7 @@ import * as Sentry from "@sentry/node";
 import { CLI_VERSION } from "../../cli-version.js";
 import { beforeSend } from "../../sentry-before-send.js";
 import { resolveLiveRoot } from "../../utils/hq-roots.js";
+import { hookTimeoutDebugContextEnabled } from "./hook-timeout-debug-context-flag.js";
 export const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
 export const MAX_SENTRY_REPORT_TIMEOUT_MS = 5_000;
 export const MAX_SENTRY_REPORT_PAYLOAD_BYTES = 2_048;
@@ -47,6 +48,8 @@ const HOOK_TIMEOUT_EXCEEDED_FINGERPRINT = "hook-timeout-exceeded";
 const HOOK_TIMEOUT_WARNING_FINGERPRINT = "hook-timeout";
 const HOOK_TIMEOUT_MACHINE_WIDE_FINGERPRINT = "hq-hook-slow";
 const MAX_HOOK_SEQUENCE_ENTRIES = 20;
+const MAX_HOOK_TIMEOUT_DEBUG_PHASES = 24;
+const MAX_HOOK_TIMEOUT_DEBUG_MS = 86_400_000;
 const HOOK_TIMEOUT_RATE_LIMIT_WINDOW_MS = 10 * 60 * 1_000;
 const RATE_LIMIT_LOCK_WAIT_MS = 500;
 const RATE_LIMIT_LOCK_POLL_MS = 5;
@@ -65,6 +68,72 @@ const KNOWN_HOOK_SCRIPTS = new Set([
     "45-lanes-senior-monitor.sh",
     "lanes-senior-monitor-stop-gate.sh",
 ]);
+const DEBUG_CONTEXT_HOOK_NAMES = new Set([
+    ...KNOWN_HOOK_SCRIPTS,
+    "reindex.sh",
+]);
+const DEBUG_CONTEXT_CHILD_NAMES = new Set([
+    ...DEBUG_CONTEXT_HOOK_NAMES,
+    "bash",
+    "bash.exe",
+    "sh",
+    "cmd",
+    "cmd.exe",
+    "powershell",
+    "powershell.exe",
+    "wmic.exe",
+    "jq",
+    "jq.exe",
+    "node",
+    "node.exe",
+    "git",
+    "git.exe",
+    "python",
+    "python.exe",
+    "python3",
+    "python3.exe",
+    "true",
+    "sleep",
+    "cat",
+    "grep",
+    "sed",
+    "awk",
+    "find",
+    "timeout",
+    "curl",
+    "gh",
+    "hq",
+    "npm",
+    "pnpm",
+    "npx",
+]);
+const DEBUG_CONTEXT_HOOK_EVENTS = new Set([
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "SessionStart",
+    "SessionEnd",
+    "Stop",
+    "PreCompact",
+    "Notification",
+    "PermissionRequest",
+    "SubagentStart",
+    "SubagentStop",
+    "TaskCompleted",
+    "TeammateIdle",
+]);
+const DEBUG_CONTEXT_PHASES = new Set([
+    "startup",
+    "source",
+    "config_load",
+    "policy_load",
+    "external_command",
+    "output_write",
+    "wait",
+    "child_wait",
+    "probe",
+    "parse",
+]);
 /**
  * The only hook diagnostics that can be attached as metadata. The list omits
  * command text, prompts, payloads, company names, and repositories. `hook_path`
@@ -96,6 +165,7 @@ export const ALLOWED_SENTRY_REPORT_METADATA_KEYS = [
     "shell",
     "nproc",
     "hook_sequence",
+    "hook_timeout_debug_context",
 ];
 const ALLOWED_METADATA_KEYS = new Set(ALLOWED_SENTRY_REPORT_METADATA_KEYS);
 const SENTRY_REPORT_METADATA_KEY_HEADROOM = 2;
@@ -107,6 +177,7 @@ const defaultDependencies = {
     sentry: Sentry,
     stdout: process.stdout,
     stderr: process.stderr,
+    timeoutDebugContextEnabled: (signal) => hookTimeoutDebugContextEnabled({}, signal),
 };
 /**
  * Read no more than the accepted event size. Returning early keeps a malformed
@@ -153,6 +224,90 @@ function isHookSequenceEntry(value) {
         Number.isFinite(value.ms) &&
         value.ms >= 0);
 }
+function boundedDebugName(value, known) {
+    if (typeof value !== "string" || value.length === 0)
+        return "other";
+    return known.has(basenameFromPath(value)) ? basenameFromPath(value) : "other";
+}
+function boundedDebugPhase(value) {
+    return typeof value === "string" && DEBUG_CONTEXT_PHASES.has(value) ? value : "other";
+}
+function boundedDebugHookEvent(value) {
+    return typeof value === "string" && DEBUG_CONTEXT_HOOK_EVENTS.has(value) ? value : "other";
+}
+function boundedDebugMilliseconds(value, allowNegative = false) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    const bounded = allowNegative
+        ? Math.abs(value) <= MAX_HOOK_TIMEOUT_DEBUG_MS
+        : value >= 0 && value <= MAX_HOOK_TIMEOUT_DEBUG_MS;
+    return bounded ? value : null;
+}
+function boundedDebugProbe(value) {
+    if (value === "unavailable")
+        return value;
+    return boundedDebugMilliseconds(value) ?? undefined;
+}
+function boundedDebugPhaseTimings(value) {
+    if (!Array.isArray(value) || value.length > MAX_HOOK_TIMEOUT_DEBUG_PHASES)
+        return null;
+    const timings = [];
+    for (const entry of value) {
+        if (!isRecord(entry))
+            return null;
+        const elapsed = boundedDebugMilliseconds(entry.elapsed_ms);
+        if (elapsed === null)
+            return null;
+        const timing = {
+            phase: boundedDebugPhase(entry.phase),
+            elapsed_ms: elapsed,
+        };
+        timings.push(timing);
+    }
+    return timings;
+}
+/** Return only the closed, bounded shell-to-CLI context shape. */
+function boundedHookTimeoutDebugContext(value) {
+    if (!isRecord(value))
+        return null;
+    const budget = boundedDebugMilliseconds(value.budget_ms);
+    const elapsed = boundedDebugMilliseconds(value.elapsed_ms);
+    const remaining = boundedDebugMilliseconds(value.remaining_ms, true);
+    const childElapsed = boundedDebugMilliseconds(value.waiting_child_elapsed_ms);
+    const phaseTimings = boundedDebugPhaseTimings(value.phase_timings);
+    if (budget === null ||
+        elapsed === null ||
+        remaining === null ||
+        childElapsed === null ||
+        phaseTimings === null) {
+        return null;
+    }
+    const loadAverage = boundedDebugProbe(value.load_average);
+    const spawnMs = boundedDebugProbe(value.spawn_ms);
+    const processCount = boundedDebugProbe(value.process_count);
+    const hasLoadAverage = typeof loadAverage === "number";
+    const hasWindowsProbe = spawnMs !== undefined && processCount !== undefined;
+    if (!hasLoadAverage && !hasWindowsProbe)
+        return null;
+    if (typeof processCount === "number" &&
+        (!Number.isInteger(processCount) || processCount > 1_000_000)) {
+        return null;
+    }
+    return {
+        hook_name: boundedDebugName(value.hook_name, DEBUG_CONTEXT_HOOK_NAMES),
+        hook_event: boundedDebugHookEvent(value.hook_event),
+        budget_ms: budget,
+        elapsed_ms: elapsed,
+        remaining_ms: remaining,
+        phase_timings: phaseTimings,
+        wait_point: boundedDebugPhase(value.wait_point),
+        waiting_child_basename: boundedDebugName(value.waiting_child_basename, DEBUG_CONTEXT_CHILD_NAMES),
+        waiting_child_elapsed_ms: childElapsed,
+        ...(loadAverage !== undefined ? { load_average: loadAverage } : {}),
+        ...(spawnMs !== undefined ? { spawn_ms: spawnMs } : {}),
+        ...(processCount !== undefined ? { process_count: processCount } : {}),
+    };
+}
 function boundedHookSequence(value) {
     if (!Array.isArray(value))
         return null;
@@ -168,6 +323,8 @@ function boundedHookSequence(value) {
 function isAllowedMetadataValue(key, value) {
     if (key === "hook_sequence")
         return boundedHookSequence(value) !== null;
+    if (key === "hook_timeout_debug_context")
+        return boundedHookTimeoutDebugContext(value) !== null;
     if (!isScalarMetadataValue(value))
         return false;
     if (key === "tool_name" || key === "session_id" || key === "hook_path") {
@@ -236,9 +393,10 @@ export function parseSentryReportEvent(stdin) {
         }
         if (!isAllowedMetadataValue(key, rawMetadata[key]))
             return invalidInput();
-        metadata[key] =
-            key === "hook_sequence"
-                ? boundedHookSequence(rawMetadata[key])
+        metadata[key] = key === "hook_sequence"
+            ? boundedHookSequence(rawMetadata[key])
+            : key === "hook_timeout_debug_context"
+                ? boundedHookTimeoutDebugContext(rawMetadata[key])
                 : rawMetadata[key];
     }
     if (typeof metadata.slow_child === "string") {
@@ -319,6 +477,11 @@ function elapsedBucket(elapsedMs) {
         return "20-60s";
     return ">=60s";
 }
+function remainingBucket(remainingMs) {
+    return remainingMs < 0
+        ? `overdue-${elapsedBucket(Math.abs(remainingMs))}`
+        : elapsedBucket(remainingMs);
+}
 function loadBucket(loadAverage) {
     if (loadAverage === undefined)
         return "unknown";
@@ -368,6 +531,53 @@ function spawnMsBucket(metadata) {
         return "500-999ms";
     return ">=1000ms";
 }
+function debugSpawnMsBucket(value) {
+    if (typeof value !== "number")
+        return "unavailable";
+    if (value < 100)
+        return "<100ms";
+    if (value < 500)
+        return "100-499ms";
+    if (value < 1_000)
+        return "500-999ms";
+    return ">=1000ms";
+}
+function processCountBucket(value) {
+    if (typeof value !== "number")
+        return "unavailable";
+    if (value < 5)
+        return "0-4";
+    if (value < 17)
+        return "5-16";
+    if (value < 65)
+        return "17-64";
+    return "65+";
+}
+function hookTimeoutDebugContextTags(context) {
+    const tags = {
+        timeout_debug_hook_name: context.hook_name,
+        timeout_debug_hook_event: context.hook_event,
+        timeout_debug_budget_bucket: elapsedBucket(context.budget_ms),
+        timeout_debug_elapsed_bucket: elapsedBucket(context.elapsed_ms),
+        timeout_debug_remaining_bucket: remainingBucket(context.remaining_ms),
+        timeout_debug_wait_point: context.wait_point,
+        timeout_debug_waiting_child: context.waiting_child_basename,
+        timeout_debug_waiting_child_elapsed_bucket: elapsedBucket(context.waiting_child_elapsed_ms),
+        timeout_debug_load_bucket: context.load_average === "unavailable"
+            ? "unavailable"
+            : loadBucket(context.load_average),
+        timeout_debug_spawn_ms_bucket: debugSpawnMsBucket(context.spawn_ms),
+        timeout_debug_process_count_bucket: processCountBucket(context.process_count),
+    };
+    const phaseElapsed = new Map();
+    for (const timing of context.phase_timings) {
+        phaseElapsed.set(timing.phase, Math.max(phaseElapsed.get(timing.phase) ?? 0, timing.elapsed_ms));
+    }
+    for (const [phase, elapsedMs] of phaseElapsed) {
+        tags[`timeout_debug_phase_${phase}_bucket`] = elapsedBucket(elapsedMs);
+    }
+    return tags;
+}
 function safeSlowChild(metadata) {
     const value = metadata.slow_child;
     if (typeof value !== "string" || value.length === 0)
@@ -464,10 +674,10 @@ function sentryEnvelope(event, overrides, additionalTags = {}) {
     };
 }
 /** Build the same scrubbed event projection that the live SDK path uses. */
-function scrubbedSentryEnvelope(event, overrides) {
+function scrubbedSentryEnvelope(event, overrides, additionalTags = {}) {
     return beforeSend({
         message: event.message,
-        ...sentryEnvelope(event, overrides),
+        ...sentryEnvelope(event, overrides, additionalTags),
     }, {});
 }
 /**
@@ -740,19 +950,47 @@ export async function reportSentryEvent(stdin, options = {}, dependencies = defa
         const noun = result.droppedMetadataKeys === 1 ? "key" : "keys";
         dependencies.stderr.write(`Dropped ${result.droppedMetadataKeys} unsupported Sentry report metadata ${noun}.\n`);
     }
-    const overrides = hookTimeoutExceededOverrides(result.event);
+    let event = result.event;
+    let debugContextTags = {};
+    const debugContext = event.metadata.hook_timeout_debug_context;
+    if (debugContext && isHookTimeoutEvent(event)) {
+        let enabled;
+        try {
+            enabled =
+                (await dependencies.timeoutDebugContextEnabled?.(options.signal)) ?? false;
+        }
+        catch {
+            // An optional diagnostic flag read must never suppress the base report.
+            enabled = false;
+        }
+        if (enabled) {
+            debugContextTags = hookTimeoutDebugContextTags(debugContext);
+        }
+        else {
+            const metadata = { ...event.metadata };
+            delete metadata.hook_timeout_debug_context;
+            event = { ...event, metadata };
+        }
+    }
+    else if (debugContext) {
+        const metadata = { ...event.metadata };
+        delete metadata.hook_timeout_debug_context;
+        event = { ...event, metadata };
+    }
+    result.event = event;
+    const overrides = hookTimeoutExceededOverrides(event);
     if (options.dryRun) {
-        const scrubbed = scrubbedSentryEnvelope(result.event, overrides);
+        const scrubbed = scrubbedSentryEnvelope(event, overrides, debugContextTags);
         if (scrubbed)
             dependencies.stdout.write(`${JSON.stringify(scrubbed)}\n`);
         return result;
     }
-    if (isHookTimeoutEvent(result.event)) {
-        addHookSequenceBreadcrumbs(result.event, dependencies);
-        const kind = hookTimeoutKind(result.event);
+    if (isHookTimeoutEvent(event)) {
+        addHookSequenceBreadcrumbs(event, dependencies);
+        const kind = hookTimeoutKind(event);
         let rateLimit;
         try {
-            rateLimit = timeoutRateLimitLease(result.event, kind, options, dependencies);
+            rateLimit = timeoutRateLimitLease(event, kind, options, dependencies);
         }
         catch {
             dependencies.stderr.write("Sentry timeout rate limit state unavailable; sending without rate limiting.\n");
@@ -764,14 +1002,14 @@ export async function reportSentryEvent(stdin, options = {}, dependencies = defa
             };
         }
         if (!rateLimit.capture) {
-            return reportSuppressedTimeout(result, result.event, timeoutMs, dependencies, kind);
+            return reportSuppressedTimeout(result, event, timeoutMs, dependencies, kind);
         }
         const tags = rateLimit.suppressedSinceLast > 0
             ? { suppressed_since_last: String(rateLimit.suppressedSinceLast) }
             : {};
-        const envelope = sentryEnvelope(result.event, overrides, tags);
+        const envelope = sentryEnvelope(event, overrides, { ...debugContextTags, ...tags });
         try {
-            dependencies.sentry.captureMessage(result.event.message, envelope);
+            dependencies.sentry.captureMessage(event.message, envelope);
             rateLimit.commitCapture();
             if (await flushWithin(dependencies.sentry, timeoutMs))
                 return result;
@@ -783,9 +1021,9 @@ export async function reportSentryEvent(stdin, options = {}, dependencies = defa
         dependencies.stderr.write("Sentry report failed.\n");
         return invalidInput();
     }
-    const envelope = sentryEnvelope(result.event, overrides);
+    const envelope = sentryEnvelope(event, overrides, debugContextTags);
     try {
-        dependencies.sentry.captureMessage(result.event.message, envelope);
+        dependencies.sentry.captureMessage(event.message, envelope);
         if (await flushWithin(dependencies.sentry, timeoutMs))
             return result;
     }

package/dist/lib/doctor/checks/sync-health.js

@@ -223,6 +223,7 @@ function versionResults(context, deps) {
         results.push({
             status: "WARN",
             checkId: "sync.versions.core",
+            reasonCode: "core-version-unavailable",
             target: path.join(context.hqRoot, "core", "core.yaml"),
             message: "hq-core version could not be read from core/core.yaml — the scaffold may be missing or pre-v12.",
             remediation: "Run /update-hq to (re)install the hq-core scaffold.",
@@ -282,6 +283,7 @@ function updateAvailabilityResult(context, deps) {
             {
                 status: "WARN",
                 checkId: "sync.update.core",
+                reasonCode: "core-update-available",
                 message: `hq-core update available: local v${core}, latest v${latest}.`,
                 remediation: "Run /update-hq in a fresh session to upgrade.",
             },
@@ -373,6 +375,7 @@ function journalResults(deps, journals) {
                 return {
                     status: "NA",
                     checkId,
+                    reasonCode: "no-local-tree",
                     target: entry.path,
                     message: `Sync journal '${entry.slug}' is unused on this machine — there is no companies/${entry.slug} directory, so this journal is not a live sync target.`,
                 };
@@ -382,6 +385,7 @@ function journalResults(deps, journals) {
             return {
                 status: "WARN",
                 checkId,
+                reasonCode: "never-synced",
                 target: entry.path,
                 message: `Sync journal '${entry.slug}' exists but has never recorded a successful sync.`,
                 remediation: "Run /hq-sync (or `hq sync`) to complete a first sync.",
@@ -392,6 +396,7 @@ function journalResults(deps, journals) {
             return {
                 status: "UNKNOWN",
                 checkId,
+                reasonCode: "invalid-last-sync",
                 target: entry.path,
                 message: `Sync journal '${entry.slug}' has an unparseable lastSync (${lastSync}).`,
             };
@@ -402,6 +407,7 @@ function journalResults(deps, journals) {
             return {
                 status: "WARN",
                 checkId,
+                reasonCode: "stale-threshold",
                 target: entry.path,
                 message: `Sync journal '${entry.slug}' is stale: last successful sync ${days} day${days === 1 ? "" : "s"} ago (${lastSync}).`,
                 remediation: "Run /hq-sync (or `hq sync`) and check the sync runner.",
@@ -443,6 +449,7 @@ function manifestResults(deps, journals) {
             {
                 status: "NA",
                 checkId: "sync.manifest",
+                reasonCode: "manifest-unavailable",
                 message: `${MANIFEST_UNAVAILABLE_REASON} — upgrade hq-cloud to audit manifest uploads.`,
             },
         ];
@@ -456,6 +463,7 @@ function manifestResults(deps, journals) {
             {
                 status: "UNKNOWN",
                 checkId: "sync.manifest",
+                reasonCode: "manifest-state-unavailable",
                 message: `Manifest upload state could not be read: ${error instanceof Error ? error.message : String(error)}`,
                 remediation: "Check that the HQ state directory is readable, then re-run `hq doctor`.",
             },
@@ -469,6 +477,7 @@ function manifestResults(deps, journals) {
             {
                 status: "NA",
                 checkId: "sync.manifest",
+                reasonCode: "no-manifest-scopes",
                 message: "No manifest-auditable sync scopes on this machine — nothing to reconcile.",
             },
         ];
@@ -480,6 +489,7 @@ function manifestResults(deps, journals) {
             return {
                 status: "UNTESTED",
                 checkId,
+                reasonCode: "never-uploaded",
                 message: `Scope '${entry.scopeKey}' has never uploaded a sync manifest — expected until the first pass runs.`,
                 remediation: "Run `hq sync manifest` to upload one now.",
             };
@@ -489,6 +499,7 @@ function manifestResults(deps, journals) {
             return {
                 status: "UNKNOWN",
                 checkId,
+                reasonCode: "invalid-upload-time",
                 message: `Scope '${entry.scopeKey}' has an unparseable last manifest upload time (${entry.lastUploadAt}).`,
             };
         }
@@ -501,6 +512,7 @@ function manifestResults(deps, journals) {
             return {
                 status: "WARN",
                 checkId,
+                reasonCode: "stale-threshold",
                 message: `Scope '${entry.scopeKey}' last uploaded a sync manifest ${days} day${days === 1 ? "" : "s"} ago (${entry.lastUploadAt}) — the daily audit pass is not running.`,
                 remediation: "Run `hq sync manifest` and check HQ_SYNC_MANIFEST_DISABLED and the sync runner.",
             };
@@ -532,6 +544,7 @@ function unresolvedResults(deps, journals) {
     return slugs.map((slug) => ({
         status: "UNTESTED",
         checkId: `sync.manifest.unresolved.${slug}`,
+        reasonCode: "unresolved-company-uid",
         message: `Company scope '${slug}' has a sync journal but its companyUid could not be resolved locally — its manifest uploads were not checked.`,
         remediation: `Run \`hq sync manifest --scope ${slug}\` to audit it explicitly.`,
     }));

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

@@ -0,0 +1,26 @@
+import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-client";
+export declare const CLIENT_HEALTH_REASON_CODES_FLAG = "client-health-sync-reason-codes";
+export declare const CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK = false;
+export declare const CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS = 150;
+type ClientHealthFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface ClientHealthReasonCodesFlagDependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => ClientHealthFlagClient;
+    getToken?: FlagClientOptions["getToken"];
+    fetch?: typeof fetch;
+    reportFailure?: (error: unknown) => void;
+}
+export interface ClientHealthReasonCodesCompany {
+    companyUid: string;
+    companySlug?: string;
+}
+/**
+ * Resolve the privacy gate from hq-flags with a bounded request. Missing
+ * identity, service configuration, and every lookup failure keep diagnostics
+ * off so a flag outage cannot delay the doctor's health result.
+ */
+export declare function clientHealthReasonCodesEnabled(dependencies?: ClientHealthReasonCodesFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+/** Resolve the same default-off gate for one explicitly identified company. */
+export declare function clientHealthReasonCodesEnabledForCompany(company: ClientHealthReasonCodesCompany, dependencies?: ClientHealthReasonCodesFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+export {};
+//# sourceMappingURL=client-health-reason-codes-flag.d.ts.map

package/dist/lib/doctor/client-health-reason-codes-flag.js

@@ -0,0 +1,94 @@
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { createFlagClient, } from "@indigoai-us/hq-flags-client";
+export const CLIENT_HEALTH_REASON_CODES_FLAG = "client-health-sync-reason-codes";
+export const CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK = false;
+export const CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS = 150;
+function safeErrorClass(error) {
+    const name = error instanceof Error ? error.name : "UnknownError";
+    return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : "UnknownError";
+}
+function reportFlagFailure(error) {
+    process.stderr.write(`HQ client-health reason-code flag lookup failed (${safeErrorClass(error)}); using default off.\n`);
+}
+function combineSignals(first, second) {
+    return first ? AbortSignal.any([first, second]) : second;
+}
+/**
+ * Resolve the privacy gate from hq-flags with a bounded request. Missing
+ * identity, service configuration, and every lookup failure keep diagnostics
+ * off so a flag outage cannot delay the doctor's health result.
+ */
+export async function clientHealthReasonCodesEnabled(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_REASON_CODES_FLAG_FALLBACK;
+    }
+    return clientHealthReasonCodesEnabledForCompany({
+        companyUid,
+        companySlug: env.HQ_COMPANY_SLUG?.trim() || undefined,
+    }, dependencies, callerSignal);
+}
+/** Resolve the same default-off gate for one explicitly identified company. */
+export async function clientHealthReasonCodesEnabledForCompany(company, dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const endpoint = env.HQ_FLAGS_API_URL?.trim() || "";
+    const companyUid = company.companyUid.trim();
+    if (!endpoint || !/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    }
+    const companySlug = company.companySlug?.trim() || "";
+    const deadline = AbortSignal.timeout(CLIENT_HEALTH_REASON_CODES_FLAG_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_REASON_CODES_FLAG_FALLBACK;
+    const reportFailureOnce = (error) => {
+        failed = true;
+        if (failureReported)
+            return;
+        failureReported = true;
+        (dependencies.reportFailure ?? reportFlagFailure)(error);
+    };
+    try {
+        client = (dependencies.createClient ?? createFlagClient)({
+            endpoint,
+            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_REASON_CODES_FLAG_TIMEOUT_MS,
+            onError: reportFailureOnce,
+        });
+        await client.ready();
+        if (!failed && !signal.aborted) {
+            enabled = client.isEnabled(CLIENT_HEALTH_REASON_CODES_FLAG, {
+                fallback: CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK,
+            });
+        }
+    }
+    catch (error) {
+        reportFailureOnce(error);
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch (error) {
+            reportFailureOnce(error);
+        }
+    }
+    return failed || signal.aborted
+        ? CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK
+        : enabled;
+}
+//# sourceMappingURL=client-health-reason-codes-flag.js.map

package/dist/lib/doctor/fix/apply.d.ts

@@ -31,6 +31,7 @@
 import type { CheckResult, DoctorStatus } from "../types.js";
 import { type GateProfile } from "../hook-gate-profiles.js";
 import { type FixClass } from "./remediation.js";
+import { type RefreshSyncOutcome } from "./refresh-sync-outcome.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export declare const HOOK_CONFIG_DIRS: readonly [".claude", ".codex", ".grok"];
 /** Options for {@link applyFixes}. Everything is injectable for hermetic tests. */
@@ -91,6 +92,8 @@ export interface RefreshSyncTarget {
 export interface RefreshSyncResult {
     /** Whether the pull exited 0. */
     ok: boolean;
+    /** Closed enum for machine-readable client-health diagnostics. */
+    outcome: RefreshSyncOutcome;
     /** One-line summary for the post-fix report. */
     message: string;
 }
@@ -108,6 +111,8 @@ export interface AppliedFix {
     summary: string;
     /** The status of the re-run check for this target, or null if not found. */
     postStatus: DoctorStatus | null;
+    /** Present for refresh-sync plans; contains no command output or path data. */
+    refreshSyncOutcome?: RefreshSyncOutcome;
 }
 /** The outcome of an {@link applyFixes} run. */
 export interface ApplyFixesResult {