@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/utils/cli-telemetry.js

@@ -1,26 +1,256 @@
+import { randomUUID } 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 { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
+import { isExpiring, isMachineIdentity, loadCachedTokens, loadMachineCachedTokens, } from "./cognito-session.js";
+import { resolveProcessFlagCompanyContext, resolveProcessFlagGate, } from "../lib/flag-registry.js";
 import { vaultApiFetch } from "./vault-api.js";
-const TELEMETRY_TIMEOUT_MS = 1_200;
+import { firstSyncStepTelemetryProperties, isHumanInteractiveCliSession, } from "../lib/first-sync-next-step.js";
+export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, } from "../lib/first-sync-next-step.js";
+export const TELEMETRY_TIMEOUT_MS = 1_200;
+/**
+ * Exact stderr line printed once on the first signed-in TTY run that is not
+ * `--json`. Keep this notice and its marker stable for session telemetry;
+ * first-sync and feature-used fields have separate disclosures below; only
+ * feature-used telemetry remains opt-in.
+ */
+export const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export const FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; first-sync guidance shown or followed, with the identifier cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export const CLI_FEATURE_USED_TELEMETRY_FLAG = "cli.feature-used-telemetry-v1";
+export const CLI_FEATURE_USED_TELEMETRY_DISCLOSURE_LINE = "HQ sends a feature-use event when you run a supported CLI feature (feature kind and outcome, plus your company UID when available; never command names, file contents, or secrets). The hq-flags key cli.feature-used-telemetry-v1 controls these events. Set HQ_TELEMETRY=0 to turn this off.";
+const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "off"]);
+const DISCLOSURE_MARKER = "cli-telemetry-disclosed";
+const FIRST_SYNC_DISCLOSURE_MARKER = "cli-telemetry-disclosed-first-sync-v1";
+const FEATURE_USED_DISCLOSURE_MARKER = "cli-telemetry-disclosed-feature-used-v1";
 let cliSessionStartedPromise;
+const pendingPlanLimitInviteTeammateExposures = [];
+export const CLI_LIMIT_AT_ACTION_PROMPT_FLAG = "billing.limit-at-action-prompt";
+const pendingCliLimitNoticeExposures = [];
+const pendingCliLimitNoticeEngagements = [];
+/** Capture an exposure only after its notice has been written to the terminal. */
+export function queueCliLimitNoticeExposure(resourceKind, presentationKind, resolvedCompanyUid) {
+    try {
+        if (!resolveProcessFlagGate(CLI_LIMIT_AT_ACTION_PROMPT_FLAG, { fallback: false }, () => false)) {
+            return null;
+        }
+        const companyUid = resolvedCompanyUid ?? resolveProcessFlagCompanyContext().companyUid;
+        if (!companyUid || !COMPANY_UID_PATTERN.test(companyUid))
+            return null;
+        const exposure = { companyUid, resourceKind, presentationKind, exposureId: randomUUID() };
+        pendingCliLimitNoticeExposures.push(exposure);
+        return exposure;
+    }
+    catch {
+        return null;
+    }
+}
+/** Only an explicit, confirmed browser open is an upgrade engagement. */
+export function queueCliLimitNoticeEngagement(exposure) {
+    if (!exposure)
+        return;
+    pendingCliLimitNoticeEngagements.push({ ...exposure, action: "upgrade_clicked" });
+}
+export function takeCliLimitNoticeExposures() {
+    return pendingCliLimitNoticeExposures.splice(0, pendingCliLimitNoticeExposures.length);
+}
+export function takeCliLimitNoticeEngagements() {
+    return pendingCliLimitNoticeEngagements.splice(0, pendingCliLimitNoticeEngagements.length);
+}
+/** Queue one exposure after the CLI has printed the invite suggestion. */
+export function queuePlanLimitInviteTeammateExposure(companyUid) {
+    const normalizedCompanyUid = companyUid.trim();
+    if (normalizedCompanyUid.length === 0)
+        return;
+    pendingPlanLimitInviteTeammateExposures.push(normalizedCompanyUid);
+}
+/** Drain invite-suggestion exposures for the bounded command-finalization flush. */
+export function takePlanLimitInviteTeammateExposures() {
+    return pendingPlanLimitInviteTeammateExposures.splice(0, pendingPlanLimitInviteTeammateExposures.length);
+}
+const COMPANY_UID_PATTERN = /^cmp_[A-Za-z0-9_-]{1,128}$/;
+export function isCliLimitResourceKind(value) {
+    return ["users", "integrations", "secrets", "agents", "deployments", "storageBytes"].includes(value);
+}
+/**
+ * Emit one bounded, privacy-limited feature-use event with a cached identity.
+ * It never refreshes credentials or turns telemetry failure into command failure.
+ */
+export async function emitCliFeatureUsed(usage, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    try {
+        // Unit tests may run with a real cached user/agent token on the host. Never
+        // let their command fixtures write telemetry to a live account.
+        if (process.env.NODE_ENV === "test")
+            return;
+        if (isCliTelemetryDisabled() || !isCliFeatureUsedTelemetryEnabled())
+            return;
+        const machineIdentity = isMachineIdentity();
+        const cached = machineIdentity ? loadMachineCachedTokens() : loadCachedTokens();
+        if (!cached || isExpiring(cached, 120))
+            return;
+        const token = machineIdentity ? cached.idToken : cached.accessToken;
+        if (!token)
+            return;
+        const consentBasis = maybeDiscloseFeatureUsedTelemetry() ? "disclosed" : "no-consent";
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        const companyUid = usage.companyUid && COMPANY_UID_PATTERN.test(usage.companyUid)
+            ? usage.companyUid
+            : undefined;
+        try {
+            await vaultApiFetch({
+                token,
+                path: "/v1/telemetry/events",
+                method: "POST",
+                body: {
+                    events: [
+                        {
+                            eventName: "cli_feature_used",
+                            app: "hq-cli",
+                            source: "cli",
+                            occurredAt: new Date().toISOString(),
+                            consentBasis,
+                            schemaVersion: 1,
+                            ...(companyUid ? { companyUid } : {}),
+                            properties: { kind: usage.kind, outcome: usage.outcome },
+                        },
+                    ],
+                },
+                signal: controller.signal,
+            });
+        }
+        catch {
+            // Feature telemetry is best effort and must never affect the CLI action.
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // Cached-token reads are also best effort (for example, a malformed cache).
+    }
+}
+/** Run one action and emit exactly one success/failure event without masking errors. */
+export async function withCliFeatureUsed(kind, action, companyUid) {
+    let outcome = "success";
+    try {
+        return await action();
+    }
+    catch (err) {
+        outcome = "failure";
+        throw err;
+    }
+    finally {
+        await emitCliFeatureUsed({
+            kind,
+            outcome,
+            ...(companyUid ? { companyUid } : {}),
+        });
+    }
+}
+/**
+ * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
+ * CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is unchanged.
+ */
+export function isCliTelemetryDisabled(env = process.env) {
+    const raw = env.HQ_TELEMETRY?.trim().toLowerCase();
+    if (!raw)
+        return false;
+    return TELEMETRY_DISABLED_VALUES.has(raw);
+}
+/** Feature-use collection stays off until the HQ flag is explicitly enabled. */
+export function isCliFeatureUsedTelemetryEnabled() {
+    return resolveProcessFlagGate(CLI_FEATURE_USED_TELEMETRY_FLAG, { fallback: false }, () => false);
+}
+function hqConfigDir() {
+    const home = process.env.HOME?.trim() || os.homedir();
+    return path.join(home, ".hq");
+}
+export function telemetryDisclosureMarkerPath() {
+    return path.join(hqConfigDir(), DISCLOSURE_MARKER);
+}
+function firstSyncTelemetryDisclosureMarkerPath() {
+    return path.join(hqConfigDir(), FIRST_SYNC_DISCLOSURE_MARKER);
+}
+function featureUsedTelemetryDisclosureMarkerPath() {
+    return path.join(hqConfigDir(), FEATURE_USED_DISCLOSURE_MARKER);
+}
+function wantsJsonOutput(argv = process.argv) {
+    return argv.includes("--json");
+}
+function canPrintDisclosure(stdout = process.stdout, argv = process.argv) {
+    return Boolean(stdout.isTTY) && !wantsJsonOutput(argv);
+}
+function hasShownDisclosure(markerPath) {
+    try {
+        return fs.existsSync(markerPath);
+    }
+    catch {
+        return false;
+    }
+}
+function recordDisclosureShown(markerPath) {
+    try {
+        const dir = hqConfigDir();
+        // Do not create ~/.hq. Signed-in runs already have it (cached tokens).
+        if (!fs.existsSync(dir))
+            return;
+        fs.writeFileSync(markerPath, `${new Date().toISOString()}\n`);
+    }
+    catch {
+        // Marker write is best effort; a repeat print is better than crashing.
+    }
+}
+/**
+ * Print the one-line disclosure at most once per machine. Returns whether
+ * the notice has been shown (this run or a previous one). `--json` and
+ * non-TTY stdout skip the print and do not record the marker.
+ */
+export function maybeDiscloseCliTelemetry(stderr = process.stderr, stdout = process.stdout, argv = process.argv) {
+    return maybeDiscloseTelemetry(TELEMETRY_DISCLOSURE_LINE, telemetryDisclosureMarkerPath(), stderr, stdout, argv);
+}
+function maybeDiscloseFirstSyncTelemetry() {
+    return maybeDiscloseTelemetry(FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE, firstSyncTelemetryDisclosureMarkerPath());
+}
+function maybeDiscloseFeatureUsedTelemetry() {
+    return maybeDiscloseTelemetry(CLI_FEATURE_USED_TELEMETRY_DISCLOSURE_LINE, featureUsedTelemetryDisclosureMarkerPath());
+}
+function maybeDiscloseTelemetry(line, markerPath, stderr = process.stderr, stdout = process.stdout, argv = process.argv) {
+    if (hasShownDisclosure(markerPath))
+        return true;
+    if (!canPrintDisclosure(stdout, argv))
+        return false;
+    try {
+        stderr.write(`${line}\n`);
+    }
+    catch {
+        return false;
+    }
+    recordDisclosureShown(markerPath);
+    return true;
+}
 /**
  * Emit the authenticated CLI session signal using an already-cached token.
  * This deliberately never refreshes a session or opens a browser.
  */
-export function emitCliSessionStarted() {
-    cliSessionStartedPromise ??= emitCachedCliSessionStarted();
+export function emitCliSessionStarted(timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    cliSessionStartedPromise ??= emitCachedCliSessionStarted(timeoutMs);
     return cliSessionStartedPromise;
 }
-async function emitCachedCliSessionStarted() {
+async function emitCachedCliSessionStarted(timeoutMs) {
     try {
+        if (isCliTelemetryDisabled())
+            return;
         const cached = loadCachedTokens();
         if (!cached || isExpiring(cached, 120))
             return;
         const token = isMachineIdentity() ? cached.idToken : cached.accessToken;
         if (!token)
             return;
+        const disclosed = maybeDiscloseCliTelemetry();
+        const consentBasis = disclosed ? "disclosed" : "no-consent";
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
         try {
             const response = await vaultApiFetch({
                 token,
@@ -33,7 +263,7 @@ async function emitCachedCliSessionStarted() {
                             app: "hq-cli",
                             source: "cli",
                             occurredAt: new Date().toISOString(),
-                            consentBasis: "no-consent",
+                            consentBasis,
                             schemaVersion: 1,
                             properties: { version: CLI_VERSION },
                         },
@@ -55,4 +285,200 @@ async function emitCachedCliSessionStarted() {
         // Cached-token reads are also best effort (for example, a malformed cache).
     }
 }
+/** Emit one authenticated measurement for a first-sync prompt outcome. */
+export async function emitCliFirstSyncNextStepOutcome(outcome, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    try {
+        if (isCliTelemetryDisabled())
+            return;
+        const cached = loadCachedTokens();
+        const machineIdentity = isMachineIdentity();
+        if (!cached ||
+            isExpiring(cached, 120) ||
+            !isHumanInteractiveCliSession({
+                stdoutIsTTY: Boolean(process.stdout.isTTY),
+                argv: process.argv,
+                env: process.env,
+                machineIdentity,
+            }))
+            return;
+        const token = cached.accessToken;
+        if (!token)
+            return;
+        const consentBasis = maybeDiscloseFirstSyncTelemetry() ? "disclosed" : "no-consent";
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await vaultApiFetch({
+                token,
+                path: "/v1/telemetry/events",
+                method: "POST",
+                body: {
+                    events: [
+                        {
+                            eventName: "cli_session_started",
+                            app: "hq-cli",
+                            source: "cli",
+                            occurredAt: new Date().toISOString(),
+                            consentBasis,
+                            schemaVersion: 1,
+                            properties: {
+                                version: CLI_VERSION,
+                                ...firstSyncStepTelemetryProperties(outcome),
+                            },
+                        },
+                    ],
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                return;
+        }
+        catch {
+            // Telemetry is best effort and must never affect or follow as an error
+            // after the completed CLI command.
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // Cached-token reads are also best effort (for example, a malformed cache).
+    }
+}
+/** Emit one company-scoped event for a printed invite-teammate suggestion. */
+function logPlanLimitInviteTeammateExposureFailure(cause, status) {
+    const errorClass = cause instanceof Error ? cause.name : "unknown";
+    const result = status === undefined ? errorClass : `http_${status}`;
+    console.error(`hq: Could not send invite-teammate exposure telemetry (${result}).`);
+}
+export async function emitPlanLimitInviteTeammateExposure(companyUid, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    try {
+        if (isCliTelemetryDisabled())
+            return;
+        const cached = loadCachedTokens();
+        const machineIdentity = isMachineIdentity();
+        if (!cached ||
+            isExpiring(cached, 120) ||
+            !isHumanInteractiveCliSession({
+                stdoutIsTTY: Boolean(process.stdout.isTTY),
+                argv: process.argv,
+                env: process.env,
+                machineIdentity,
+            })) {
+            return;
+        }
+        const token = cached.accessToken;
+        if (!token)
+            return;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await vaultApiFetch({
+                token,
+                path: "/v1/telemetry/events",
+                method: "POST",
+                body: {
+                    events: [
+                        {
+                            eventName: "plan_limit_prompt_exposed",
+                            app: "hq-cli",
+                            source: "cli",
+                            occurredAt: new Date().toISOString(),
+                            consentBasis: "no-consent",
+                            schemaVersion: 2,
+                            companyUid,
+                            idempotencyKey: randomUUID(),
+                            properties: {
+                                surface: "cli_whoami_plan_limit",
+                                resourceKind: "users",
+                                presentationKind: "advisory",
+                                exposureId: randomUUID(),
+                            },
+                        },
+                    ],
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                logPlanLimitInviteTeammateExposureFailure(undefined, response.status);
+            }
+        }
+        catch (error) {
+            // This measurement is best-effort and must not affect the CLI command.
+            logPlanLimitInviteTeammateExposureFailure(error);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch (error) {
+        // Cached-token reads and identity checks are best-effort too.
+        logPlanLimitInviteTeammateExposureFailure(error);
+    }
+}
+/** Send one bounded plan-limit prompt event through authenticated CLI telemetry. */
+async function emitCliLimitNoticeEvent(exposure, eventName, action, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    try {
+        if (isCliTelemetryDisabled())
+            return;
+        const machineIdentity = isMachineIdentity();
+        const cached = machineIdentity ? loadMachineCachedTokens() : loadCachedTokens();
+        if (!cached ||
+            isExpiring(cached, 120) ||
+            !isHumanInteractiveCliSession({
+                stdoutIsTTY: Boolean(process.stdout.isTTY),
+                argv: process.argv,
+                env: process.env,
+                machineIdentity,
+            }))
+            return;
+        const token = machineIdentity ? cached.idToken : cached.accessToken;
+        if (!token)
+            return;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            await vaultApiFetch({
+                token,
+                path: "/v1/telemetry/events",
+                method: "POST",
+                body: {
+                    events: [{
+                            eventName,
+                            app: "hq-cli",
+                            source: "cli",
+                            occurredAt: new Date().toISOString(),
+                            consentBasis: "no-consent",
+                            schemaVersion: 2,
+                            companyUid: exposure.companyUid,
+                            idempotencyKey: randomUUID(),
+                            properties: {
+                                surface: "cli_limit_notice",
+                                resourceKind: exposure.resourceKind,
+                                presentationKind: exposure.presentationKind,
+                                exposureId: exposure.exposureId,
+                                ...(eventName === "plan_limit_prompt_engaged" && action ? { action } : {}),
+                            },
+                        }],
+                },
+                signal: controller.signal,
+            });
+        }
+        catch {
+            // Measurement must never change a command's output or exit status.
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // Identity, flag cache, and transport failures all remain best effort.
+    }
+}
+export function emitCliLimitNoticeExposure(exposure, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    return emitCliLimitNoticeEvent(exposure, "plan_limit_prompt_exposed", undefined, timeoutMs);
+}
+export function emitCliLimitNoticeEngagement(engagement, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    return emitCliLimitNoticeEvent(engagement, "plan_limit_prompt_engaged", engagement.action, timeoutMs);
+}
 //# sourceMappingURL=cli-telemetry.js.map

package/dist/utils/client-health.d.ts

@@ -33,8 +33,6 @@
 import { isExpiring, loadCachedTokens } from "./cognito-session.js";
 import { type VersionInfo } from "./feedback-versions.js";
 import { type ClientHealthArch, type ClientHealthHeartbeat, type ClientHealthLocalFilesOverview, type ClientHealthPlatform } from "./client-health-contract.js";
-/** Same bound as CLI telemetry: a heartbeat may never stall a command. */
-export declare const CLIENT_HEALTH_TIMEOUT_MS = 1200;
 export declare const CLIENT_HEALTH_STATE_FILE = "cli-client-health.json";
 /**
  * Single-flight marker for the journal observation below. Held only for the
@@ -66,8 +64,6 @@ export declare const CLIENT_HEALTH_OBSERVATION_FILE = "cli-client-health.observa
  * always re-observe — they have opened the store anyway, so it costs nothing.
  */
 export declare const JOURNAL_OBSERVATION_TTL_MS: number;
-/** An observation lock older than this is treated as abandoned. */
-export declare const JOURNAL_OBSERVATION_LOCK_STALE_MS: number;
 export interface CliClientHealthState {
     /** Stable random installation identity — regenerated only if invalid. */
     installationId: string;

package/dist/utils/client-health.js

@@ -40,7 +40,7 @@ import { collectVersions } from "./feedback-versions.js";
 import { CLIENT_HEALTH_CONTRACT_VERSION, parseClientHealthHeartbeat, } from "./client-health-contract.js";
 import { collectLocalFilesOverview } from "./local-files-overview.js";
 /** Same bound as CLI telemetry: a heartbeat may never stall a command. */
-export const CLIENT_HEALTH_TIMEOUT_MS = 1_200;
+const CLIENT_HEALTH_TIMEOUT_MS = 1_200;
 export const CLIENT_HEALTH_STATE_FILE = "cli-client-health.json";
 /**
  * Single-flight marker for the journal observation below. Held only for the
@@ -73,7 +73,7 @@ export const CLIENT_HEALTH_OBSERVATION_FILE = "cli-client-health.observation.jso
  */
 export const JOURNAL_OBSERVATION_TTL_MS = 15 * 60_000;
 /** An observation lock older than this is treated as abandoned. */
-export const JOURNAL_OBSERVATION_LOCK_STALE_MS = 5 * 60_000;
+const JOURNAL_OBSERVATION_LOCK_STALE_MS = 5 * 60_000;
 /**
  * Pre-filter mirror of the contract's SemVer shape (the contract keeps its
  * validators private). A version failing this is DROPPED individually so one

package/dist/utils/cognito-refresh-sentry.d.ts

@@ -0,0 +1,3 @@
+/** Capture only fixed, aggregatable auth diagnostics; never attach tokens or identity. */
+export declare function reportNoninteractivePersonRefreshRejection(error: unknown): Promise<void>;
+//# sourceMappingURL=cognito-refresh-sentry.d.ts.map

package/dist/utils/cognito-refresh-sentry.js

@@ -0,0 +1,49 @@
+import { CLI_VERSION } from "../cli-version.js";
+import { CognitoRefreshError } from "@indigoai-us/hq-cloud";
+/** Capture only fixed, aggregatable auth diagnostics; never attach tokens or identity. */
+export async function reportNoninteractivePersonRefreshRejection(error) {
+    try {
+        // Keep the Sentry SDK and its generated DSN out of ordinary session utility
+        // imports. The reporter is reached only after a definitive noninteractive
+        // refresh rejection, so load the Sentry boundary only on that path.
+        const { Sentry } = await import("../sentry.js");
+        const statusCode = error instanceof CognitoRefreshError ? error.statusCode : undefined;
+        const rejectionKind = error instanceof CognitoRefreshError
+            ? "cognito_refresh_rejection"
+            : "classified_auth_error";
+        Sentry.withScope((scope) => {
+            scope.setUser(null);
+            scope.clearBreadcrumbs();
+            scope.addBreadcrumb({
+                category: "hq.auth",
+                message: "Noninteractive person refresh was attempted for an expiring session",
+                level: "info",
+                data: { interactive: false },
+            });
+            scope.addBreadcrumb({
+                category: "hq.auth",
+                message: "Refresh rejection had no fresh same-principal cache generation",
+                level: "error",
+                data: {
+                    rejection_kind: rejectionKind,
+                    ...(Number.isInteger(statusCode) ? { status_code: statusCode } : {}),
+                },
+            });
+            scope.setLevel("error");
+            scope.setFingerprint(["hq-cli", "person-refresh-rejected"]);
+            scope.setTag("component", "person-session-refresh");
+            scope.setTag("auth.rejection_kind", rejectionKind);
+            scope.setTag("auth.fresh_cache_generation_found", "false");
+            scope.setTag("platform", process.platform);
+            scope.setTag("cli_version", CLI_VERSION);
+            if (Number.isInteger(statusCode) && statusCode >= 400 && statusCode <= 599) {
+                scope.setTag("auth.status_code", String(statusCode));
+            }
+            Sentry.captureMessage("Noninteractive HQ person session refresh rejected");
+        });
+    }
+    catch {
+        // Telemetry is best-effort: it must never prevent session invalidation or auth fallback.
+    }
+}
+//# sourceMappingURL=cognito-refresh-sentry.js.map

package/dist/utils/cognito-session.d.ts

@@ -81,6 +81,10 @@ export declare const DEFAULT_VAULT_API_URL: string;
  */
 export declare function resolveDefaultHqRoot(opts?: {
     onMissing?: "throw" | "fallback";
+    /** Defaults to process.env, process.cwd() and os.homedir(). */
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    home?: string;
 }): string;
 export declare const DEFAULT_HQ_ROOT: string;
 /**
@@ -110,6 +114,8 @@ export type EnsureCognitoTokenOptions = {
      * cached. Explicit `"person"` never uses machine creds.
      */
     tokenSource?: CognitoTokenSource;
+    /** Cancels bounded, non-interactive person-session refreshes. */
+    signal?: AbortSignal;
 };
 /**
  * On-disk person Cognito cache path for `env` (`HQ_STATE_DIR` or `~/.hq`).
@@ -153,6 +159,53 @@ export declare function wantsMachineCognitoTokens(options?: Pick<EnsureCognitoTo
  * not flip this to machine.
  */
 export declare function resolveCognitoTokenSource(env?: NodeJS.ProcessEnv): CognitoTokenSource;
+/**
+ * Refresh wrote a different Cognito subject than the active cache.
+ * Callers must not fall through to browser login or machine mint — that
+ * would replace the operator session the refusal is protecting.
+ */
+export declare class IdentitySwapRefusal extends Error {
+    constructor(message: string);
+}
+export declare function isIdentitySwapRefusal(err: unknown): err is IdentitySwapRefusal;
+/** `sub` plus `custom:entityUid` from an unverified JWT. Either may be absent. */
+export declare function cognitoSubjectFromToken(token: string | undefined): {
+    sub: string | null;
+    entityUid: string | null;
+};
+/** Stable local cache identity for a Cognito person or agent principal. */
+export declare function cognitoCachePrincipalUid(token: string | undefined): string | null;
+/** Stable subject key. Null when neither sub nor entity uid is present. */
+export declare function cognitoSubjectKey(tokens: {
+    idToken?: string;
+    accessToken?: string;
+} | null | undefined): string | null;
+/** Doctor/status line. Claims only — never token material. */
+export declare function formatCognitoSubject(tokens: {
+    idToken?: string;
+    accessToken?: string;
+} | null | undefined): string;
+/**
+ * Person cache as stored on disk for `env`. Does not consult hq-cloud's
+ * in-memory fallback, which can surface a different session when the file
+ * is missing or unreadable.
+ */
+export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessEnv): CognitoTokens | null;
+/**
+ * Refresh the active person session and refuse a subject change.
+ *
+ * hq-cloud's `refreshTokens` saves as soon as Cognito responds, and on a
+ * cache miss or unreadable file it can refresh an in-memory session for a
+ * different subject (same app client). Snapshot the active file first; if
+ * the response subject differs, put the bytes back and leave them there.
+ */
+export declare function refreshActivePersonTokens(cached: CognitoTokens, env?: NodeJS.ProcessEnv): Promise<CognitoTokens>;
+/**
+ * Client-health's short-lived flag read cannot use hq-cloud's unbounded refresh
+ * helper. Reuse its lockfile protocol, attach the caller signal to the refresh
+ * request, and persist only after the request has completed before the deadline.
+ */
+export declare function refreshActivePersonTokensForClientHealth(cached: CognitoTokens, signal: AbortSignal): Promise<CognitoTokens>;
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
 export declare function actorKindFromIdToken(idToken: string | undefined): CognitoActorKind;
 /**
@@ -184,6 +237,12 @@ export declare function withMachineTokenStateDir<T>(fn: () => Promise<T>, opts?:
     home?: string;
     env?: NodeJS.ProcessEnv;
 }): Promise<T>;
+/**
+ * Ensure the current machine identity has a valid session and return only the
+ * access/ID token pair needed by supported machine-session handoff scripts.
+ * The machine state directory is isolated from the person's session cache.
+ */
+export declare function ensureMachineSessionTokens(): Promise<Pick<CognitoTokens, "accessToken" | "idToken" | "expiresAt">>;
 /**
  * True when a person-token refresh failed with a definitive Cognito auth
  * rejection (refresh token invalid/revoked). Transient network/5xx/timeouts
@@ -239,4 +298,16 @@ export declare function refreshCachedSession(options?: Pick<EnsureCognitoTokenOp
     refreshed: boolean;
     reason?: string;
 }>;
+/**
+ * True on a Linux host with no terminal and no display — a container or
+ * server, where a browser sign-in can never be completed. macOS and Windows
+ * always have a way to open a browser, and a terminal means a person is there.
+ */
+export declare function isHeadlessHost(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: boolean): boolean;
+/**
+ * True when the environment explicitly names an HQ agent identity. Only the
+ * explicit variables count: guessing from the filesystem is unreliable, and a
+ * wrong guess would take an ordinary headless run off its sign-in path.
+ */
+export declare function hostRunsAnAgent(env?: NodeJS.ProcessEnv): boolean;
 //# sourceMappingURL=cognito-session.d.ts.map