@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -23,6 +23,7 @@
  * Every dependency is injectable so the family is unit-testable without an HQ
  * tree, a state dir, or the wall clock.
  */
+import { defaultSyncRuntimeResults } from "./sync-runtime.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 // Namespace import, deliberately: hq-cloud is an ESM package, so a static
@@ -47,14 +48,36 @@ export const STALE_JOURNAL_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
 /** The offline update cache written by the check-hq-update SessionStart hook. */
 export const UPDATE_CACHE_RELPATH = path.join("workspace", ".hq-update-check", "last-check.json");
 /** Fill in the optional dependencies so call sites never branch on undefined. */
-function withDefaults(deps) {
+function withDefaults(deps, hqRoot) {
     return {
         ...deps,
+        runtime: deps.runtime ?? (() => []),
         manifestStatuses: deps.manifestStatuses ?? defaultManifestStatuses,
         manifestAvailable: deps.manifestAvailable ?? (() => loadManifestExports() !== null),
         unresolvedScopes: deps.unresolvedScopes ?? defaultUnresolvedScopes,
+        localCompanyExists: deps.localCompanyExists ??
+            ((slug) => defaultLocalCompanyExists(hqRoot, slug)),
     };
 }
+/**
+ * True when `slug` is a filesystem-safe company folder name. Rejects empty
+ * values, path separators, and `..` so a journal slug cannot be used to probe
+ * outside `companies/`.
+ */
+export function isSafeCompanySlug(slug) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug);
+}
+/** True when `hqRoot/companies/<slug>` exists as a directory. Never throws. */
+export function defaultLocalCompanyExists(hqRoot, slug) {
+    if (!isSafeCompanySlug(slug))
+        return false;
+    try {
+        return fs.statSync(path.join(hqRoot, "companies", slug)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Company journal shards are unresolvable by the default collector: the
  * snapshot store keys company scopes by `companyUid`, which `listJournals()`
@@ -97,6 +120,7 @@ const DEFAULT_DEPS = {
     journals: () => hqCloud.listJournals(),
     now: () => new Date(),
     manifestStatuses: defaultManifestStatuses,
+    runtime: defaultSyncRuntimeResults,
 };
 /**
  * Map the machine's journal shards onto the manifest scopes hq-cloud keys its
@@ -146,6 +170,15 @@ const NON_COMPANY_JOURNAL_SLUGS = new Set([
     PERSONAL_SCOPE_SLUG,
     PERSONAL_VAULT_SCOPE_SLUG,
 ]);
+/** True when this journal slug names a company rather than the personal tree. */
+export function isCompanyJournalSlug(slug) {
+    return !NON_COMPANY_JOURNAL_SLUGS.has(slug);
+}
+/** Company slug from a `sync.journal.<slug>` check id, or null if not one. */
+export function journalSlugFromCheckId(checkId) {
+    const match = /^sync\.journal\.(.+)$/.exec(checkId);
+    return match ? match[1] : null;
+}
 /** The versions/sync check family. Registered in `createDefaultRegistry`. */
 export const syncHealthFamily = {
     id: SYNC_FAMILY_ID,
@@ -154,12 +187,13 @@ export const syncHealthFamily = {
 };
 /** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
 export function checkSyncHealth(context, rawDeps = DEFAULT_DEPS) {
-    const deps = withDefaults(rawDeps);
+    const deps = withDefaults(rawDeps, context.hqRoot);
     try {
         return [
             ...versionResults(context, deps),
             ...updateAvailabilityResult(context, deps),
             ...journalAndManifestResults(deps),
+            ...deps.runtime(deps.now()),
         ];
     }
     catch (error) {
@@ -193,6 +227,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.",
@@ -252,6 +287,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.",
             },
@@ -325,10 +361,35 @@ function journalResults(deps, journals) {
     return journals.map((entry) => {
         const lastSync = entry.journal?.lastSync;
         const checkId = `sync.journal.${entry.slug}`;
+        // A company journal without a local tree is leftover membership state,
+        // not a live sync target. WARN would make `hq doctor --fix` look like it
+        // failed to repair something it was never going to touch (US-015 health
+        // hook files remaining FAIL/WARN after the safe repair pass).
+        if (isCompanyJournalSlug(entry.slug)) {
+            let local;
+            try {
+                local = deps.localCompanyExists(entry.slug);
+            }
+            catch {
+                // Existence probe failed: fall through to the staleness check rather
+                // than hiding a possibly-live company behind NA.
+                local = true;
+            }
+            if (!local) {
+                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.`,
+                };
+            }
+        }
         if (typeof lastSync !== "string" || lastSync.length === 0) {
             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.",
@@ -339,6 +400,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}).`,
             };
@@ -349,6 +411,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.",
@@ -390,6 +453,7 @@ function manifestResults(deps, journals) {
             {
                 status: "NA",
                 checkId: "sync.manifest",
+                reasonCode: "manifest-unavailable",
                 message: `${MANIFEST_UNAVAILABLE_REASON} — upgrade hq-cloud to audit manifest uploads.`,
             },
         ];
@@ -403,6 +467,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`.",
             },
@@ -416,6 +481,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.",
             },
         ];
@@ -427,6 +493,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.",
             };
@@ -436,6 +503,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}).`,
             };
         }
@@ -448,6 +516,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.",
             };
@@ -479,6 +548,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/checks/sync-runtime.d.ts

@@ -0,0 +1,11 @@
+import type { CheckResult } from "../types.js";
+export declare const SYNC_RUNTIME_WINDOW_MS: number;
+export interface SyncRuntimeOptions {
+    now: number;
+    conflictCount?: number;
+}
+/** Classify the last hour of sync log lines into privacy-safe results. */
+export declare function analyzeSyncRuntimeLog(lines: readonly string[], options: SyncRuntimeOptions): CheckResult[];
+/** Read the machine's sync logs and client health file. */
+export declare function defaultSyncRuntimeResults(now: Date, hqHome?: string, env?: NodeJS.ProcessEnv): CheckResult[];
+//# sourceMappingURL=sync-runtime.d.ts.map

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

@@ -0,0 +1,216 @@
+/**
+ * Sync runtime checks: problems visible only in the running sync runner's log
+ * (realtime lag, receiver permission errors, restart loops, device-limit
+ * backoff) plus the conflict counter the desktop app keeps in client health.
+ *
+ * Results carry only a closed reason code and counts. Log content (paths,
+ * tenant ids, AWS error prose) never leaves this module.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { currentSyncLogFamily, SYNC_LOG_GENERATIONS, syncLogBasePaths, syncLogGenerationPath, } from "../../../utils/sync-log-sources.js";
+export const SYNC_RUNTIME_WINDOW_MS = 60 * 60_000;
+const LAG_SECONDS = 15 * 60;
+const LAG_MIN_RECEIPTS = 3;
+const RESTART_MIN_STARTS = 4;
+const CONFLICT_MIN_COUNT = 5;
+const LOG_TAIL_BYTES = 8 * 1024 * 1024;
+const TIMESTAMP = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)\s/;
+const PERMISSION = /AccessDenied|not authorized to perform|\b403\b/;
+const DEVICE_LIMIT = /sync device limit exceeded|"sync_device_limit"/;
+function parseRecord(rest) {
+    const start = rest.indexOf("{");
+    if (start < 0)
+        return null;
+    try {
+        const value = JSON.parse(rest.slice(start));
+        return value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function timestampFromRecord(record) {
+    if (!record)
+        return null;
+    for (const key of ["time", "timestamp", "ts"]) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            const millis = value < 100_000_000_000 ? value * 1000 : value;
+            if (Number.isFinite(millis))
+                return millis;
+        }
+        if (typeof value === "string") {
+            const parsed = Date.parse(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+    }
+    return null;
+}
+function lineTimestamp(line) {
+    const stamp = TIMESTAMP.exec(line);
+    if (stamp) {
+        const parsed = Date.parse(stamp[1]);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return timestampFromRecord(parseRecord(line));
+}
+/** Classify the last hour of sync log lines into privacy-safe results. */
+export function analyzeSyncRuntimeLog(lines, options) {
+    const since = options.now - SYNC_RUNTIME_WINDOW_MS;
+    let slowReceipts = 0;
+    let denied = 0;
+    let starts = 0;
+    let deviceLimited = 0;
+    for (const line of lines) {
+        const time = lineTimestamp(line);
+        if (time === null)
+            continue;
+        if (!Number.isFinite(time) || time < since || time > options.now)
+            continue;
+        const stamp = TIMESTAMP.exec(line);
+        const rest = stamp ? line.slice(stamp[0].length) : line;
+        if (DEVICE_LIMIT.test(rest))
+            deviceLimited += 1;
+        const record = parseRecord(rest);
+        if (!record)
+            continue;
+        const event = record.event;
+        if (event === "fanout.receive") {
+            const latency = record.latencySeconds;
+            if (typeof latency === "number" && latency > LAG_SECONDS)
+                slowReceipts += 1;
+        }
+        else if (event === "receiver.start") {
+            starts += 1;
+        }
+        if ((record.type === "receiver" || record.type === "error" ||
+            (typeof event === "string" && event.startsWith("receiver."))) &&
+            PERMISSION.test(JSON.stringify(record.err ?? record.message ?? ""))) {
+            denied += 1;
+        }
+    }
+    const conflicts = options.conflictCount ?? 0;
+    const checks = [
+        { id: "realtime-lag", reasonCode: "realtime-lag-stuck", failing: slowReceipts >= LAG_MIN_RECEIPTS, count: slowReceipts, label: "incoming changes delayed over 15 minutes" },
+        { id: "receiver-permission", reasonCode: "receiver-permission-denied", failing: denied > 0, count: denied, label: "cloud permission refusals" },
+        { id: "runner-restarts", reasonCode: "runner-restart-loop", failing: starts >= RESTART_MIN_STARTS, count: starts, label: "sync runner starts" },
+        { id: "device-limit", reasonCode: "device-limit-backoff", failing: deviceLimited > 0, count: deviceLimited, label: "device-limit backoffs" },
+        { id: "conflicts", reasonCode: "repeated-conflicts", failing: conflicts >= CONFLICT_MIN_COUNT, count: conflicts, label: "unresolved conflicts" },
+    ];
+    return checks.map((check) => check.failing
+        ? {
+            status: "WARN",
+            checkId: `sync.runtime.${check.id}`,
+            reasonCode: check.reasonCode,
+            message: `${check.count} ${check.label} in the last hour.`,
+            remediation: "Run `hq sync status` and inspect the selected sync log under ~/.hq/logs/, ~/.hq/daemon/logs/, or the configured HQ_DAEMON_DIR/logs/.",
+        }
+        : {
+            status: "PASS",
+            checkId: `sync.runtime.${check.id}`,
+            message: `${check.count} ${check.label} in the last hour.`,
+        });
+}
+function readLogTail(file) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const size = fs.fstatSync(fd).size;
+        const length = Math.min(size, LOG_TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        fs.readSync(fd, buffer, 0, length, size - length);
+        return buffer.toString("utf8").split("\n");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function firstTimestamp(lines) {
+    for (const line of lines) {
+        const timestamp = lineTimestamp(line);
+        if (timestamp !== null)
+            return timestamp;
+    }
+    return null;
+}
+/**
+ * Lines from the active log and as many rotated generations as needed to
+ * cover the window. Throws when a present log cannot be read.
+ */
+function readWindowLines(logFile, since, daemonLog) {
+    const generations = [];
+    for (let n = 0; n < SYNC_LOG_GENERATIONS; n += 1) {
+        const file = syncLogGenerationPath(logFile, n);
+        if (!fs.existsSync(file))
+            continue;
+        const lines = readLogTail(file);
+        const fallbackTime = daemonLog ? fs.statSync(file).mtimeMs : null;
+        const timestampedLines = fallbackTime === null
+            ? lines
+            : lines.map((line) => lineTimestamp(line) === null
+                ? `${new Date(fallbackTime).toISOString()} ${line}`
+                : line);
+        generations.unshift(timestampedLines);
+        const first = firstTimestamp(timestampedLines);
+        if (first !== null && first <= since)
+            break;
+    }
+    return generations.length > 0 ? generations.flat() : null;
+}
+function readConflictCount(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        const count = value?.conflictCount;
+        return typeof count === "number" && Number.isFinite(count) ? count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Read the machine's sync logs and client health file. */
+export function defaultSyncRuntimeResults(now, hqHome = path.join(os.homedir(), ".hq"), env = process.env) {
+    const options = {
+        now: now.getTime(),
+        conflictCount: readConflictCount(path.join(hqHome, "client-health.json")),
+    };
+    const paths = syncLogBasePaths(hqHome, env);
+    const familyModifiedMs = (family) => {
+        let newest = null;
+        for (let generation = 0; generation < SYNC_LOG_GENERATIONS; generation += 1) {
+            try {
+                const stat = fs.lstatSync(syncLogGenerationPath(paths[family], generation));
+                if (!stat.isFile() && !stat.isDirectory())
+                    continue;
+                newest = newest === null ? stat.mtimeMs : Math.max(newest, stat.mtimeMs);
+            }
+            catch {
+                // Missing or inaccessible generations do not make a source family newer.
+            }
+        }
+        return newest;
+    };
+    const family = currentSyncLogFamily(familyModifiedMs("desktop"), familyModifiedMs("daemon"));
+    const logFile = family === null ? paths.desktop : paths[family];
+    let lines;
+    try {
+        lines = readWindowLines(logFile, options.now - SYNC_RUNTIME_WINDOW_MS, family === "daemon");
+    }
+    catch {
+        return [
+            { status: "UNKNOWN", checkId: "sync.runtime.log", message: "The sync runner log could not be read." },
+            ...analyzeSyncRuntimeLog([], options).filter((r) => r.checkId === "sync.runtime.conflicts"),
+        ];
+    }
+    if (lines === null) {
+        return [
+            { status: "NA", checkId: "sync.runtime.log", message: "No sync runner log on this machine." },
+            ...analyzeSyncRuntimeLog([], options).filter((r) => r.checkId === "sync.runtime.conflicts"),
+        ];
+    }
+    return analyzeSyncRuntimeLog(lines, options);
+}
+//# sourceMappingURL=sync-runtime.js.map

package/dist/lib/doctor/checks/work-context.js

@@ -6,10 +6,11 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { readDeviceConfig, getDefaultCompany, } from "../../work-context/config.js";
+import { readDeviceConfig, } from "../../work-context/config.js";
 import { outboxStats, listOutboxOperations } from "../../work-context/outbox.js";
+import { outboxQuarantineStatusEnabled } from "../../work-context/outbox-quarantine-status-flag.js";
 import { workContextRoot, workContextSessionsDir } from "../../work-context/paths.js";
-import { countJsonlLines, deadLetterNonEmpty, } from "../../mesh/live/spool.js";
+import { countDistinctHeldEvents, countJsonlLines, deadLetterNonEmpty, } from "../../mesh/live/spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../../mesh/live/paths.js";
 import { collectDaemonDoctor, formatDaemonDoctor, } from "../../mesh/live/daemon/doctor.js";
 export const WORK_CONTEXT_FAMILY_ID = "work-context";
@@ -87,16 +88,29 @@ function runChecks(deps) {
         target: path.join(root, "outbox"),
         message: `Outbox queued depth=${stats.depth} (acked=${stats.acked}).`,
     });
+    const showQuarantineReason = stats.quarantined > 0 && outboxQuarantineStatusEnabled();
+    const quarantineDetails = [
+        stats.lastQuarantineHttpStatus !== null
+            ? `HTTP ${stats.lastQuarantineHttpStatus}`
+            : "",
+        stats.lastQuarantineServerCode ?? "",
+    ]
+        .filter(Boolean)
+        .join(" ");
     results.push({
         status: stats.quarantined > 0 ? "WARN" : "PASS",
         checkId: "work-context.outbox-quarantined",
         target: path.join(root, "outbox"),
-        message: `Outbox quarantined count=${stats.quarantined}.`,
+        message: `Outbox quarantined count=${stats.quarantined}${showQuarantineReason
+            ? ` (last reason=${stats.lastQuarantineReason ?? "unknown"}${quarantineDetails ? `; ${quarantineDetails}` : ""})`
+            : ""}.`,
     });
     // Default-company mode + migration capability (US-017B)
     try {
         const cfg = readDeviceConfig({ root });
-        const def = getDefaultCompany({ root });
+        const def = cfg.defaultCompany?.enabled && cfg.defaultCompany.slug
+            ? cfg.defaultCompany
+            : null;
         const mode = def?.enabled
             ? `enabled slug=${def.slug}`
             : "disabled (dark / unset)";
@@ -133,7 +147,7 @@ function runChecks(deps) {
     const heldPath = workMeshHeldPath(meshRoot);
     const deadLetterPath = workMeshDeadLetterPath(meshRoot);
     const spoolDepth = countJsonlLines(spoolPath);
-    const heldDepth = countJsonlLines(heldPath);
+    const heldDepth = countDistinctHeldEvents(heldPath);
     results.push({
         status: "PASS",
         checkId: "work-context.spool-depth",
@@ -178,7 +192,7 @@ function formatMigrationCapabilityCheck(cap, root) {
             status: "WARN",
             checkId: "work-context.migration-capability",
             target,
-            message: `Migration capability: offline at ${cap.checkedAt}; default-company stays locked.`,
+            message: `Migration capability: offline at ${cap.checkedAt}; selected-company membership is still verified when setting a default.`,
         };
     }
     const falseCount = cap.companies.filter((c) => !c.migration).length;

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

@@ -0,0 +1,15 @@
+export declare const CLIENT_HEALTH_FLAG_TOKEN_TIMEOUT_MS = 1000;
+export declare class MissingFlagTokenError extends Error {
+    constructor();
+}
+export declare class ClientHealthFlagTokenTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+export type ClientHealthFlagTokenProvider = (signal: AbortSignal) => string | Promise<string>;
+/**
+ * Obtain a non-interactive ID token, separately bounded from the flag read.
+ * ensureCognitoIdToken refreshes expired person sessions and selects machine
+ * identity credentials when the current installation is a machine.
+ */
+export declare function getClientHealthFlagToken(provider?: ClientHealthFlagTokenProvider, timeoutMs?: number, callerSignal?: AbortSignal): Promise<string>;
+//# sourceMappingURL=client-health-flag-token.d.ts.map

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

@@ -0,0 +1,66 @@
+import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+export const CLIENT_HEALTH_FLAG_TOKEN_TIMEOUT_MS = 1_000;
+export class MissingFlagTokenError extends Error {
+    constructor() {
+        super("No cached HQ identity token is available");
+        this.name = "MissingFlagTokenError";
+    }
+}
+export class ClientHealthFlagTokenTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Client-health flag token acquisition exceeded its ${timeoutMs} ms bound`);
+        this.name = "ClientHealthFlagTokenTimeoutError";
+    }
+}
+/**
+ * Obtain a non-interactive ID token, separately bounded from the flag read.
+ * ensureCognitoIdToken refreshes expired person sessions and selects machine
+ * identity credentials when the current installation is a machine.
+ */
+export async function getClientHealthFlagToken(provider, timeoutMs = CLIENT_HEALTH_FLAG_TOKEN_TIMEOUT_MS, callerSignal) {
+    if (callerSignal?.aborted) {
+        throw callerSignal.reason ?? new Error("Token acquisition was aborted");
+    }
+    const controller = new AbortController();
+    const signal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
+    const timeout = new ClientHealthFlagTokenTimeoutError(timeoutMs);
+    const timer = setTimeout(() => controller.abort(timeout), timeoutMs);
+    let onAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        onAbort = () => reject(signal.reason ?? new Error("Token acquisition was aborted"));
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        const acquire = provider ?? ((requestSignal) => ensureCognitoIdToken({ interactive: false, signal: requestSignal }));
+        const acquisition = Promise.resolve().then(() => {
+            if (signal.aborted) {
+                throw signal.reason ?? new Error("Token acquisition was aborted");
+            }
+            return acquire(signal);
+        });
+        const token = await Promise.race([acquisition, aborted]);
+        if (signal.aborted) {
+            throw signal.reason ?? new Error("Token acquisition was aborted");
+        }
+        if (typeof token !== "string" || token.trim().length === 0) {
+            throw new MissingFlagTokenError();
+        }
+        return token;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.startsWith("No valid HQ session and interactive login is disabled")) {
+            throw new MissingFlagTokenError();
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+//# sourceMappingURL=client-health-flag-token.js.map

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

@@ -0,0 +1,27 @@
+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"];
+    tokenTimeoutMs?: number;
+    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