@indigoai-us/hq-cli 5.106.2 → 5.107.0

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

@@ -0,0 +1,279 @@
+/**
+ * Versions & sync health — the doctor family the registry docblock always
+ * anticipated (client-sync-health-control-plane US-015).
+ *
+ * Reports, per install:
+ *   - the CLI / Core / desktop (hq-sync menubar) component versions, from the
+ *     same collectors the feedback and client-health paths use (US-003), so
+ *     `hq doctor --json` shows exactly what a heartbeat would report;
+ *   - whether a newer hq-core release is known to be available — read OFFLINE
+ *     from the cache stamped by the `check-hq-update` SessionStart hook
+ *     (`workspace/.hq-update-check/last-check.json`), never from the network,
+ *     preserving the doctor's offline contract (no cache → UNTESTED, not PASS);
+ *   - per-company sync journal staleness via the engine's `listJournals()` —
+ *     the ONLY correct enumeration of per-scope journal shards
+ *     (single-path reconstruction regressed before: feedback_9fbf1f82 /
+ *     feedback_46288b7b).
+ *
+ * Caution paid for in blood (bridge-health false positives): a machine with no
+ * journals at all is NA, not WARN — CLI-only installs never sync locally and
+ * must not read as degraded. Staleness warns only on a corroborated signal: a
+ * journal that EXISTS and carries a parseable, old `lastSync`.
+ *
+ * Every dependency is injectable so the family is unit-testable without an HQ
+ * tree, a state dir, or the wall clock.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { listJournals } from "@indigoai-us/hq-cloud";
+import { CLI_VERSION } from "../../../cli-version.js";
+import { readSyncVersion } from "../../../utils/feedback-versions.js";
+import { readHqVersion } from "../../../utils/pack-contributions.js";
+/** The id of the versions/sync family. */
+export const SYNC_FAMILY_ID = "sync";
+/** Human title for grouped output. */
+export const SYNC_FAMILY_TITLE = "Versions & sync";
+/**
+ * A journal shard older than this is reported stale. Seven days: long enough
+ * that a laptop shut over a weekend never warns, short enough that a silently
+ * dead sync runner surfaces well before data divergence becomes painful.
+ */
+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");
+function defaultVersions(hqRoot) {
+    return {
+        cli: CLI_VERSION,
+        core: safeReadCore(hqRoot),
+        desktop: safeReadDesktop(),
+    };
+}
+function safeReadCore(hqRoot) {
+    try {
+        return readHqVersion(hqRoot);
+    }
+    catch {
+        return null;
+    }
+}
+function safeReadDesktop() {
+    try {
+        return readSyncVersion();
+    }
+    catch {
+        return null;
+    }
+}
+const DEFAULT_DEPS = {
+    versions: defaultVersions,
+    // Deliberately NOT wrapped in a try/catch: an enumeration failure must
+    // surface as UNKNOWN in `journalResults`, never be collapsed into the
+    // empty-list (NA, "cloud sync not in use") case. False healthy is worse
+    // than no check.
+    journals: () => listJournals(),
+    now: () => new Date(),
+};
+/** The versions/sync check family. Registered in `createDefaultRegistry`. */
+export const syncHealthFamily = {
+    id: SYNC_FAMILY_ID,
+    title: SYNC_FAMILY_TITLE,
+    run: (context) => Promise.resolve(checkSyncHealth(context)),
+};
+/** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
+export function checkSyncHealth(context, deps = DEFAULT_DEPS) {
+    try {
+        return [
+            ...versionResults(context, deps),
+            ...updateAvailabilityResult(context, deps),
+            ...journalResults(deps),
+        ];
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "sync.error",
+                message: `versions/sync checks could not run: ${error.message}`,
+            },
+        ];
+    }
+}
+// ─── Component versions ──────────────────────────────────────────────────────
+function versionResults(context, deps) {
+    const versions = deps.versions(context.hqRoot);
+    const results = [
+        {
+            status: "PASS",
+            checkId: "sync.versions.cli",
+            message: `hq-cli ${versions.cli}.`,
+        },
+    ];
+    if (versions.core) {
+        results.push({
+            status: "PASS",
+            checkId: "sync.versions.core",
+            message: `hq-core ${versions.core} (core/core.yaml hqVersion).`,
+        });
+    }
+    else {
+        results.push({
+            status: "WARN",
+            checkId: "sync.versions.core",
+            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.",
+        });
+    }
+    // Desktop absence is NA, never WARN: hq-sync is optional (CLI-only and CI
+    // machines legitimately run without it), so "not installed" is not degraded.
+    results.push(versions.desktop
+        ? {
+            status: "PASS",
+            checkId: "sync.versions.desktop",
+            message: `hq-sync desktop ${versions.desktop} (~/.hq/sync-version.json).`,
+        }
+        : {
+            status: "NA",
+            checkId: "sync.versions.desktop",
+            message: "hq-sync desktop app not detected (~/.hq/sync-version.json absent) — not required on CLI-only installs.",
+        });
+    return results;
+}
+// ─── Update availability (offline, from the SessionStart hook's cache) ───────
+function updateAvailabilityResult(context, deps) {
+    const cachePath = path.join(context.hqRoot, UPDATE_CACHE_RELPATH);
+    let latest = null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+        const value = parsed?.latest;
+        if (typeof value === "string" && /^\d+\.\d+\.\d+$/.test(value)) {
+            latest = value;
+        }
+    }
+    catch {
+        // Missing or malformed cache: fall through to UNTESTED.
+    }
+    if (!latest) {
+        return [
+            {
+                status: "UNTESTED",
+                checkId: "sync.update.core",
+                target: cachePath,
+                message: "Latest hq-core release unknown — no update-check cache yet (written by the check-hq-update SessionStart hook; the doctor never goes to the network for it).",
+            },
+        ];
+    }
+    const core = deps.versions(context.hqRoot).core;
+    if (!core) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "sync.update.core",
+                message: `Latest hq-core release is v${latest}, but the local core version could not be read to compare.`,
+            },
+        ];
+    }
+    if (semverGt(latest, core)) {
+        return [
+            {
+                status: "WARN",
+                checkId: "sync.update.core",
+                message: `hq-core update available: local v${core}, latest v${latest}.`,
+                remediation: "Run /update-hq in a fresh session to upgrade.",
+            },
+        ];
+    }
+    return [
+        {
+            status: "PASS",
+            checkId: "sync.update.core",
+            message: `hq-core is up to date (local v${core}, latest known v${latest}).`,
+        },
+    ];
+}
+/** True when `a` > `b` for plain X.Y.Z versions. Non-numeric parts compare 0. */
+export function semverGt(a, b) {
+    const pa = a.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da !== db)
+            return da > db;
+    }
+    return false;
+}
+// ─── Per-journal staleness ───────────────────────────────────────────────────
+function journalResults(deps) {
+    // Enumeration failure (throw / IO error) is UNKNOWN — which FAILS per the
+    // doctor's exit-code contract — never NA: a broken or unreadable journal
+    // store must not read as "cloud sync not in use" (a false healthy). Only a
+    // SUCCESSFUL enumeration that finds nothing is the benign CLI-only case.
+    let journals;
+    try {
+        journals = deps.journals();
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "sync.journals",
+                message: `Sync journal enumeration failed: ${error instanceof Error ? error.message : String(error)}`,
+                remediation: "Check that the HQ state directory is readable, then re-run `hq doctor`.",
+            },
+        ];
+    }
+    // No journals is NA, never WARN: a CLI-only install has nothing to sync
+    // locally and must not read as degraded (bridge-health false-positive
+    // lesson — warn only on corroborated signals).
+    if (journals.length === 0) {
+        return [
+            {
+                status: "NA",
+                checkId: "sync.journals",
+                message: "No local sync journals found — HQ cloud sync is not in use on this machine.",
+            },
+        ];
+    }
+    const nowMs = deps.now().getTime();
+    return journals.map((entry) => {
+        const lastSync = entry.journal?.lastSync;
+        const checkId = `sync.journal.${entry.slug}`;
+        if (typeof lastSync !== "string" || lastSync.length === 0) {
+            return {
+                status: "WARN",
+                checkId,
+                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.",
+            };
+        }
+        const parsed = Date.parse(lastSync);
+        if (!Number.isFinite(parsed)) {
+            return {
+                status: "UNKNOWN",
+                checkId,
+                target: entry.path,
+                message: `Sync journal '${entry.slug}' has an unparseable lastSync (${lastSync}).`,
+            };
+        }
+        const ageMs = nowMs - parsed;
+        if (ageMs > STALE_JOURNAL_THRESHOLD_MS) {
+            const days = Math.floor(ageMs / 86_400_000);
+            return {
+                status: "WARN",
+                checkId,
+                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.",
+            };
+        }
+        return {
+            status: "PASS",
+            checkId,
+            target: entry.path,
+            message: `Sync journal '${entry.slug}' is fresh (last sync ${lastSync}).`,
+        };
+    });
+}
+//# sourceMappingURL=sync-health.js.map

package/dist/lib/doctor/registry.js

@@ -20,6 +20,7 @@ import { checkGrokWiring } from "./checks/grok-wiring.js";
 import { checkRuntimeProbe } from "./checks/runtime-probe.js";
 import { runtimeHealthFamily } from "./checks/runtime-health.js";
 import { integrationsFamily } from "./checks/integrations.js";
+import { syncHealthFamily } from "./checks/sync-health.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -181,6 +182,11 @@ export function createDefaultRegistry() {
     // The engine remains family-agnostic: integrations is one bounded,
     // read-only inventory family, registered alongside all other checks.
     registry.register(integrationsFamily);
+    // Versions & sync (US-015): CLI/Core/desktop component versions, offline
+    // update availability, and per-company sync journal staleness — the family
+    // this registry's docblock always anticipated. Local-only reads, so the
+    // doctor's offline contract is preserved.
+    registry.register(syncHealthFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

package/dist/main.js

@@ -75,6 +75,7 @@ import { qmdStoreMissingMessage } from "./utils/qmd-store-missing-error.js";
 import { qmdStoreUnopenableMessage } from "./utils/qmd-store-unopenable-error.js";
 import { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
+import { isVarlockEnvError } from "./run/env-graph-guard.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import { isAuthError } from "./utils/auth-error.js";
@@ -89,6 +90,7 @@ import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
+import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
@@ -288,7 +290,12 @@ registerDoctorCommand(program);
 // from `hq doctor` (hook guardrails). Does not start MQTT listen.
 registerMeshCommand(program);
 program.hook("preAction", async () => {
-    await emitCliSessionStarted();
+    // Both are best-effort, bounded (1.2s), and fully swallowed: neither can
+    // delay past its bound or change the command's result or exit code.
+    await Promise.all([
+        emitCliSessionStarted(),
+        reportCliClientHealthInvocation(),
+    ]);
 });
 export async function runCli() {
     // Set when a self-update re-exec'd this command on a newer CLI: the child
@@ -463,6 +470,17 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         deps.stderr.write(`hq: ${err.message}\n`);
         deps.setExitCode(1);
     }
+    else if (isVarlockEnvError(err)) {
+        // HQ-CLI-W: `hq run` could not load or resolve a .env.schema/.env.local
+        // because the file itself is malformed. The typed carrier
+        // (EnvGraphLoadError / EnvResolutionError) already names the offending
+        // file and the pinned varlock version, so print that one actionable line
+        // and skip Sentry capture — a user's un-parseable env file is their file,
+        // not an hq-cli defect. A genuinely unclassified floated rejection is not
+        // one of these carriers, so it keeps falling through to the capture arm.
+        deps.stderr.write(`hq: ${err.message}\n`);
+        deps.setExitCode(1);
+    }
     else if (isPackageRootResolutionError(err)) {
         deps.stderr.write(`hq: ${err.message}\n`);
         deps.sentry.captureException(err, {

package/dist/run/env-graph-guard.d.ts

@@ -0,0 +1,83 @@
+/** The varlock version hq-cli is pinned to (package.json `dependencies`). */
+export declare const VARLOCK_PINNED_VERSION = "1.0.0";
+/** A schema/plugin source varlock could not finish loading. */
+interface GuardDataSource {
+    readonly isValid: boolean;
+    readonly loadingError?: {
+        readonly message?: string;
+    } | null;
+    readonly schemaErrors?: ReadonlyArray<{
+        readonly message?: string;
+        readonly isWarning?: boolean;
+    }>;
+    readonly resolutionErrors?: ReadonlyArray<{
+        readonly message?: string;
+    }>;
+    readonly label?: string;
+    /** Present on file-based sources (.env.schema / .env.local). */
+    readonly fullPath?: string;
+}
+interface GuardPlugin {
+    readonly loadingError?: {
+        readonly message?: string;
+    } | null;
+    readonly localPath?: string;
+}
+/**
+ * The structural subset of varlock's EnvGraph this module reads. varlock's
+ * concrete EnvGraph is assignable to it, so `hq run` passes its graph with no
+ * cast. Everything the guard reads is optional so a varlock shape change
+ * degrades to "no problems found" rather than a crash — the resolve-time layer
+ * and the varlock-shape smoke test (src/run/varlock-shape.test.ts) are what
+ * make such a degradation fail loudly.
+ */
+export interface LoadedEnvGraph {
+    readonly sortedDataSources?: ReadonlyArray<GuardDataSource>;
+    readonly plugins?: ReadonlyArray<GuardPlugin>;
+    resolveEnvValues(keys?: Array<string>): Promise<void>;
+}
+/**
+ * A schema/entry file could not be loaded, so the env graph never finished
+ * processing. Carries an actionable, file-naming message; classified by
+ * handleTopLevelError as a user-file error (printed, not reported to Sentry).
+ */
+export declare class EnvGraphLoadError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolving the env graph floated a rejection (varlock's un-awaited resolver).
+ * Converted from the process-level unhandled rejection by resolveEnvValuesOrThrow
+ * so the promise `hq run` awaits can never hang. Classified as a user-file error.
+ */
+export declare class EnvResolutionError extends Error {
+    readonly reason: unknown;
+    constructor(reason: unknown);
+}
+/** True for either typed carrier this module raises. */
+export declare function isVarlockEnvError(err: unknown): boolean;
+/**
+ * Throw a typed, actionable EnvGraphLoadError when varlock did not finish
+ * loading the graph — i.e. when it would have bailed out of finishLoad() before
+ * processing items, leaving them unresolvable. Mirrors finishLoad's two
+ * early-return conditions exactly: any data source with `isValid === false`, or
+ * any plugin with a `loadingError`. A fully-valid graph passes silently.
+ */
+export declare function assertEnvGraphLoaded(graph: LoadedEnvGraph): void;
+/**
+ * Await `graph.resolveEnvValues()`, but convert varlock's floated resolution
+ * rejection into a thrown EnvResolutionError instead of hanging on the promise
+ * that never settles.
+ *
+ * varlock@1.0.0's resolveEnvValues dispatches its per-item resolver un-awaited
+ * and with a dead `_reject`, so a throw inside it becomes a process-level
+ * unhandled rejection AND leaves the returned promise permanently pending. We
+ * race the resolve against a scoped `unhandledRejection` listener: whichever
+ * settles first wins. The listener is prepended (so the prior listeners still
+ * run — nothing is swallowed) and removed in `finally` (restoring the exact
+ * prior listener set, including the no-prior-listener case). If resolve settles
+ * normally the listener never fires; a stray unrelated rejection during the
+ * window is still delivered to the pre-existing listeners.
+ */
+export declare function resolveEnvValuesOrThrow(graph: LoadedEnvGraph): Promise<void>;
+export {};
+//# sourceMappingURL=env-graph-guard.d.ts.map

package/dist/run/env-graph-guard.js

@@ -0,0 +1,155 @@
+// src/run/env-graph-guard.ts
+//
+// Guards for `hq run`'s use of varlock's env graph. Two independent layers
+// close the same class of failure that produced Sentry HQ-CLI-W
+// ("expected dataType to be set", varlock ConfigItem.resolve):
+//
+//   1. assertEnvGraphLoaded(graph) — refuse to resolve a graph varlock never
+//      finished loading. When ANY discovered entry file (.env.schema /
+//      .env.local) fails to parse, varlock's EnvGraph.finishLoad() returns
+//      early — BEFORE it processes items — so every ConfigItem is left with
+//      `dataType === undefined` and NO error attached. Resolving such a graph
+//      reaches varlock's internal invariant `expected dataType to be set` for
+//      any item whose key also exists in process.env (varlock treats the whole
+//      process env as overrides), and — because varlock fires that resolution
+//      as an un-awaited, un-caught promise — the throw becomes a process-level
+//      unhandled rejection while the promise `hq run` awaits NEVER settles.
+//      finishLoad's two early-return conditions are: any data source with
+//      `isValid === false`, or any plugin with a `loadingError`. This guard
+//      mirrors exactly those conditions and throws a typed, actionable error
+//      first, so resolution is never reached with an unprocessed graph.
+//
+//   2. resolveEnvValuesOrThrow(graph) — defence in depth for the case the
+//      shape-dependent guard above cannot see (a future varlock could change
+//      the members it reads). It wraps `graph.resolveEnvValues()` in a
+//      narrowly-scoped `unhandledRejection` window: if varlock floats the
+//      resolution rejection, this converts it into a thrown EnvResolutionError
+//      instead of hanging forever on the never-settling promise. The window is
+//      restored to the exact prior listener set afterwards, and every rejection
+//      it observes is still forwarded to the pre-existing listeners, so it never
+//      swallows an unrelated rejection or permanently alters process semantics.
+//
+// Both failures are a user's malformed schema file, not an hq-cli defect, so
+// main.ts's handleTopLevelError classifies these typed carriers as an
+// actionable `hq: …` line WITHOUT a Sentry capture (see isVarlockEnvError).
+import { claimRejection, releaseRejection, } from "../unhandled-rejection-boundary.js";
+/** The varlock version hq-cli is pinned to (package.json `dependencies`). */
+export const VARLOCK_PINNED_VERSION = "1.0.0";
+/**
+ * A schema/entry file could not be loaded, so the env graph never finished
+ * processing. Carries an actionable, file-naming message; classified by
+ * handleTopLevelError as a user-file error (printed, not reported to Sentry).
+ */
+export class EnvGraphLoadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnvGraphLoadError";
+    }
+}
+/**
+ * Resolving the env graph floated a rejection (varlock's un-awaited resolver).
+ * Converted from the process-level unhandled rejection by resolveEnvValuesOrThrow
+ * so the promise `hq run` awaits can never hang. Classified as a user-file error.
+ */
+export class EnvResolutionError extends Error {
+    reason;
+    constructor(reason) {
+        const underlying = reason instanceof Error ? reason.message : String(reason);
+        super(`could not resolve your env schema (varlock ${VARLOCK_PINNED_VERSION}): ${underlying}. ` +
+            `This usually means a .env.schema or .env.local file could not be parsed — ` +
+            `check them for syntax errors and try again.`);
+        this.name = "EnvResolutionError";
+        this.reason = reason;
+    }
+}
+/** True for either typed carrier this module raises. */
+export function isVarlockEnvError(err) {
+    return err instanceof EnvGraphLoadError || err instanceof EnvResolutionError;
+}
+/** Collect the human-readable reason(s) a source is invalid, mirroring varlock. */
+function describeSourceFailure(source) {
+    const parts = [];
+    const loadingMessage = source.loadingError?.message;
+    if (loadingMessage)
+        parts.push(loadingMessage);
+    for (const err of source.schemaErrors ?? []) {
+        if (!err.isWarning && err.message)
+            parts.push(err.message);
+    }
+    for (const err of source.resolutionErrors ?? []) {
+        if (err.message)
+            parts.push(err.message);
+    }
+    return parts.length > 0 ? parts.join("; ") : "failed to load";
+}
+/**
+ * Throw a typed, actionable EnvGraphLoadError when varlock did not finish
+ * loading the graph — i.e. when it would have bailed out of finishLoad() before
+ * processing items, leaving them unresolvable. Mirrors finishLoad's two
+ * early-return conditions exactly: any data source with `isValid === false`, or
+ * any plugin with a `loadingError`. A fully-valid graph passes silently.
+ */
+export function assertEnvGraphLoaded(graph) {
+    const problems = [];
+    for (const source of graph.sortedDataSources ?? []) {
+        if (source.isValid === false) {
+            const where = source.fullPath ?? source.label ?? "unknown source";
+            problems.push(`${where}: ${describeSourceFailure(source)}`);
+        }
+    }
+    for (const plugin of graph.plugins ?? []) {
+        if (plugin.loadingError) {
+            const where = plugin.localPath ?? "plugin";
+            problems.push(`${where}: ${plugin.loadingError.message ?? String(plugin.loadingError)}`);
+        }
+    }
+    if (problems.length === 0)
+        return;
+    throw new EnvGraphLoadError(`hq run could not load your env schema (varlock ${VARLOCK_PINNED_VERSION}). ` +
+        `Fix the following and re-run:\n` +
+        problems.map((p) => `  - ${p}`).join("\n"));
+}
+/**
+ * Await `graph.resolveEnvValues()`, but convert varlock's floated resolution
+ * rejection into a thrown EnvResolutionError instead of hanging on the promise
+ * that never settles.
+ *
+ * varlock@1.0.0's resolveEnvValues dispatches its per-item resolver un-awaited
+ * and with a dead `_reject`, so a throw inside it becomes a process-level
+ * unhandled rejection AND leaves the returned promise permanently pending. We
+ * race the resolve against a scoped `unhandledRejection` listener: whichever
+ * settles first wins. The listener is prepended (so the prior listeners still
+ * run — nothing is swallowed) and removed in `finally` (restoring the exact
+ * prior listener set, including the no-prior-listener case). If resolve settles
+ * normally the listener never fires; a stray unrelated rejection during the
+ * window is still delivered to the pre-existing listeners.
+ */
+export async function resolveEnvValuesOrThrow(graph) {
+    let claimedReason;
+    let didClaim = false;
+    const onRejection = (reason) => {
+        // Claim this rejection so the process-wide boundary (index.ts) defers to us
+        // and does not ALSO report it — one failure, one diagnostic. The
+        // pre-existing listeners still fire (this is a prependOnceListener), so the
+        // rejection is never swallowed from the process's normal handling.
+        claimedReason = reason;
+        didClaim = true;
+        claimRejection(reason);
+        rejectRace(new EnvResolutionError(reason));
+    };
+    let rejectRace = () => { };
+    const rejection = new Promise((_resolve, reject) => {
+        rejectRace = reject;
+    });
+    process.prependOnceListener("unhandledRejection", onRejection);
+    try {
+        await Promise.race([graph.resolveEnvValues(), rejection]);
+    }
+    finally {
+        // No-op if the once-listener already fired; restores the prior set exactly.
+        process.removeListener("unhandledRejection", onRejection);
+        if (didClaim)
+            releaseRejection(claimedReason);
+    }
+}
+//# sourceMappingURL=env-graph-guard.js.map

package/dist/unhandled-rejection-boundary.d.ts

@@ -0,0 +1,30 @@
+export declare function hadFatalRejection(): boolean;
+export declare function claimRejection(reason: unknown): void;
+export declare function releaseRejection(reason: unknown): void;
+/** Reset the process-level rejection state. Test-only. */
+export declare function __resetRejectionStateForTests(): void;
+export interface RejectionBoundaryDependencies {
+    /** Reads the current process exit code (undefined when still unset). */
+    readonly getExitCode: () => number | undefined;
+    readonly setExitCode: (code: number) => void;
+    /** Best-effort actionable report; may be async and may not finish before exit. */
+    readonly report: (reason: unknown) => void;
+}
+/**
+ * Handle one floated rejection. Synchronously fixes the exit code — a broken
+ * pipe (EPIPE) is a clean close (0), anything else is a failure (1) — WITHOUT
+ * downgrading a non-zero code a command path already set, then kicks off a
+ * best-effort actionable report. Never calls process.exit, so the command's
+ * finally block (release-health session end + bounded Sentry flush) still runs.
+ */
+export declare function handleFatalRejection(reason: unknown, deps: RejectionBoundaryDependencies): void;
+/**
+ * Register the boundary on `process`, once, before index.ts dispatches into the
+ * command graph. Idempotent so repeated imports/installs add a single listener.
+ * The actionable report routes through main.ts's existing handleTopLevelError
+ * with a NO-OP capture: @sentry/node's integration has already captured the
+ * rejection, so this only adds the classified `hq:` line (and its EPIPE / typed
+ * carve-outs) without a second Sentry event.
+ */
+export declare function installProcessRejectionBoundary(): void;
+//# sourceMappingURL=unhandled-rejection-boundary.d.ts.map