@indigoai-us/hq-cli 5.313.0 → 5.314.0

package/dist/utils/cli-telemetry.js

@@ -1,255 +1,26 @@
-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, loadMachineCachedTokens, } from "./cognito-session.js";
-import { resolveProcessFlagCompanyContext, resolveProcessFlagGate, } from "../lib/flag-registry.js";
+import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
 import { vaultApiFetch } from "./vault-api.js";
-import { firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, 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, isFirstSyncNextStepEnabled, 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 opt-in disclosures below.
- */
-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; when enabled, first-sync guidance shown or followed and the flag key 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";
+const TELEMETRY_TIMEOUT_MS = 1_200;
 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(timeoutMs = TELEMETRY_TIMEOUT_MS) {
-    cliSessionStartedPromise ??= emitCachedCliSessionStarted(timeoutMs);
+export function emitCliSessionStarted() {
+    cliSessionStartedPromise ??= emitCachedCliSessionStarted();
     return cliSessionStartedPromise;
 }
-async function emitCachedCliSessionStarted(timeoutMs) {
+async function emitCachedCliSessionStarted() {
     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(), timeoutMs);
+        const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
         try {
             const response = await vaultApiFetch({
                 token,
@@ -262,7 +33,7 @@ async function emitCachedCliSessionStarted(timeoutMs) {
                             app: "hq-cli",
                             source: "cli",
                             occurredAt: new Date().toISOString(),
-                            consentBasis,
+                            consentBasis: "no-consent",
                             schemaVersion: 1,
                             properties: { version: CLI_VERSION },
                         },
@@ -284,202 +55,4 @@ async function emitCachedCliSessionStarted(timeoutMs) {
         // 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;
-        if (!isFirstSyncNextStepEnabled())
-            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,6 +33,8 @@
 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
@@ -64,6 +66,8 @@ 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. */
-const CLIENT_HEALTH_TIMEOUT_MS = 1_200;
+export 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. */
-const JOURNAL_OBSERVATION_LOCK_STALE_MS = 5 * 60_000;
+export 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-session.d.ts

@@ -81,10 +81,6 @@ 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;
 /**
@@ -114,8 +110,6 @@ 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`).
@@ -159,53 +153,6 @@ 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;
 /**
@@ -237,12 +184,6 @@ 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
@@ -298,16 +239,4 @@ 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