@indigoai-us/hq-cli 5.287.0 → 5.288.0

package/dist/lib/lanes/message-replay.js

@@ -1,3 +1,122 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { probeProviderCompactionsSince, providerTranscriptSize, } from "./compaction.js";
+import { LanesError } from "./errors.js";
 export const MESSAGE_REPLAY_STATE_NAME = "message-compaction-replay.json";
 export const MESSAGE_COMPACTION_REPLAY_NOTE = "These messages were delivered before a context compaction and still apply.";
+export function readMessageReplayState(filePath, turnId, onLegacyFlag) {
+    const text = fs.readFileSync(filePath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} is not an object`);
+    }
+    const state = parsed;
+    if (state.schema_version !== 1 ||
+        state.turn_id !== turnId ||
+        (state.last_compaction_marker !== null &&
+            (!Number.isSafeInteger(state.last_compaction_marker) || Number(state.last_compaction_marker) < 0)) ||
+        (state.transcript_offset !== undefined &&
+            (!Number.isSafeInteger(state.transcript_offset) || Number(state.transcript_offset) < 0)) ||
+        (state.transcript_path !== undefined && typeof state.transcript_path !== "string") ||
+        (state.provider !== undefined && !isLaneProvider(state.provider)) ||
+        (state.flag_enabled !== undefined && typeof state.flag_enabled !== "boolean")) {
+        throw new LanesError("message_replay_state_invalid", `Replay state ${filePath} does not match the current provider turn`);
+    }
+    // Older state files persisted the removed per-turn flag. Accept it, but
+    // remove it before the next write so the stale cache does not live on.
+    if (state.flag_enabled !== undefined) {
+        delete state.flag_enabled;
+        onLegacyFlag?.();
+    }
+    return state;
+}
+function isLaneProvider(value) {
+    return value === "claude" || value === "codex" || value === "grok";
+}
+export function writeMessageReplayState(filePath, state) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    fs.writeFileSync(tempPath, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+    try {
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        fs.rmSync(tempPath, { force: true });
+        throw err;
+    }
+}
+function safeProviderTranscriptPath(transcriptPath, provider, env) {
+    if (provider === "grok")
+        return transcriptPath;
+    const home = provider === "claude" ? env.CLAUDE_CONFIG_DIR : env.CODEX_HOME;
+    if (!home) {
+        throw new LanesError("message_replay_provider_home_missing", `Cannot validate ${provider} transcript without its provider home`);
+    }
+    if (!path.isAbsolute(transcriptPath) || path.extname(transcriptPath) !== ".jsonl") {
+        throw new LanesError("message_replay_transcript_path_invalid", `The ${provider} hook transcript path must be an absolute JSONL path`);
+    }
+    const configuredHomePath = path.resolve(home);
+    const homePath = fs.realpathSync(home);
+    const candidate = path.resolve(transcriptPath);
+    const expectedRoot = provider === "claude" ? "projects" : "sessions";
+    const assertWithinProviderHome = (root, resolvedTranscript, message) => {
+        const relative = path.relative(root, resolvedTranscript);
+        if (relative === "" ||
+            relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative) ||
+            relative.split(path.sep)[0] !== expectedRoot) {
+            throw new LanesError("message_replay_transcript_outside_provider_home", message);
+        }
+    };
+    try {
+        const realTranscript = fs.realpathSync(candidate);
+        assertWithinProviderHome(homePath, realTranscript, `The ${provider} hook transcript resolves outside its ${expectedRoot} directory`);
+        return realTranscript;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            assertWithinProviderHome(configuredHomePath, candidate, `The ${provider} hook transcript is outside its configured ${expectedRoot} directory`);
+            return candidate;
+        }
+        throw err;
+    }
+}
+export function updateMessageReplayTranscript(state, transcriptPath, provider, env, probe = probeProviderCompactionsSince) {
+    if (provider === "grok") {
+        state.provider = provider;
+        state.last_compaction_marker = 0;
+        return "unchanged";
+    }
+    const canonicalPath = safeProviderTranscriptPath(transcriptPath, provider, env);
+    const providerChanged = state.provider !== undefined && state.provider !== provider;
+    state.provider = provider;
+    if (providerChanged ||
+        state.last_compaction_marker === null ||
+        state.transcript_path !== canonicalPath ||
+        state.transcript_offset === undefined) {
+        state.last_compaction_marker = 0;
+        state.transcript_path = canonicalPath;
+        state.transcript_offset = providerTranscriptSize(canonicalPath);
+        return "baseline";
+    }
+    const delta = probe(canonicalPath, provider, state.transcript_offset);
+    state.transcript_offset = delta.next_offset;
+    if (delta.replaced) {
+        state.last_compaction_marker = 0;
+        return "replaced";
+    }
+    if (delta.count > 0) {
+        state.last_compaction_marker += delta.count;
+        return "compacted";
+    }
+    return "unchanged";
+}
 //# sourceMappingURL=message-replay.js.map

package/dist/lib/plan-limit-nag.js

@@ -37,6 +37,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { resolveProcessFlagCompanyContext } from "./flag-registry.js";
+import { isCliLimitResourceKind, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { planLimitUpgradeFallbackUrl, selectPlanLimitUpgradeUrl, } from "./billing/plan-limit-upgrade-url.js";
 export const PLAN_LIMIT_UPGRADE_URL = "https://hq.computer/billing/upgrade";
 /**
@@ -445,6 +446,9 @@ export function emitPlanLimitThresholdNotice(crossings, upgradeUrl, opts = {}) {
             thresholdsShownThisSession.set(key, crossing.firstSeenAt);
             printed[key] = crossing.firstSeenAt;
             write(chalk.yellow(renderThresholdNotice(crossing, resolvedUpgradeUrl)) + "\n");
+            if (isCliLimitResourceKind(crossing.resource)) {
+                queueCliLimitNoticeExposure(crossing.resource, "advisory");
+            }
         }
         if (Object.keys(printed).length > 0) {
             updateNagState(statePath, { notifiedThresholds: printed });
@@ -486,6 +490,10 @@ export function emitPlanLimitNag(opts = {}) {
             const overEntries = entries.filter(([, e]) => e.over);
             const line = buildOverLine(overEntries, resolvedUpgradeUrl);
             write(chalk.yellow(line) + "\n");
+            const resourceKind = overEntries[0]?.[0];
+            if (resourceKind && isCliLimitResourceKind(resourceKind)) {
+                queueCliLimitNoticeExposure(resourceKind, "advisory");
+            }
             writeShownAt(statePath, nowMs);
             return;
         }
@@ -498,6 +506,9 @@ export function emitPlanLimitNag(opts = {}) {
         warningShownThisSession = true;
         const line = `⚠ HQ Starter: ${formatEntryLine(worst.key, worst.entry)}. Add headroom before you hit the cap: ${resolvedUpgradeUrl}`;
         write(chalk.yellow(line) + "\n");
+        if (isCliLimitResourceKind(worst.key)) {
+            queueCliLimitNoticeExposure(worst.key, "advisory");
+        }
     }
     catch {
         // Never throw from emit path.

package/dist/main.js

@@ -43,7 +43,7 @@ import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
-import { emitCliFirstSyncNextStepOutcome, emitCliSessionStarted, emitPlanLimitInviteTeammateExposure, takeFirstSyncStepOutcomes, takePlanLimitInviteTeammateExposures, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
+import { emitCliFirstSyncNextStepOutcome, emitCliLimitNoticeEngagement, emitCliLimitNoticeExposure, emitCliSessionStarted, emitPlanLimitInviteTeammateExposure, isCliLimitResourceKind, queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, takeFirstSyncStepOutcomes, takeCliLimitNoticeEngagements, takeCliLimitNoticeExposures, takePlanLimitInviteTeammateExposures, maybeShowFirstSyncNextStep, } 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";
@@ -295,11 +295,15 @@ export async function runCli() {
             const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
             const firstSyncOutcomeFlushes = takeFirstSyncStepOutcomes().map((outcome) => emitCliFirstSyncNextStepOutcome(outcome, releaseHealthTimeoutMs));
             const inviteTeammateExposureFlushes = takePlanLimitInviteTeammateExposures().map((companyUid) => emitPlanLimitInviteTeammateExposure(companyUid, releaseHealthTimeoutMs));
+            const limitNoticeExposureFlushes = takeCliLimitNoticeExposures().map((exposure) => emitCliLimitNoticeExposure(exposure, releaseHealthTimeoutMs));
+            const limitNoticeEngagementFlushes = takeCliLimitNoticeEngagements().map((engagement) => emitCliLimitNoticeEngagement(engagement, releaseHealthTimeoutMs));
             await settleWithin([
                 refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
                 Sentry.flush(releaseHealthTimeoutMs),
                 ...firstSyncOutcomeFlushes,
                 ...inviteTeammateExposureFlushes,
+                ...limitNoticeExposureFlushes,
+                ...limitNoticeEngagementFlushes,
             ], releaseHealthTimeoutMs);
         });
         // Last, so it wins over anything the (skipped) command path would have
@@ -419,6 +423,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         const interactive = deps.interactive ?? canOfferTeamUpgrade(deps.argv);
         const message = formatPlanGateError(err, { urlOnly: !interactive });
         deps.stderr.write(interactive ? `hq: ${message}\n` : `${message}\n`);
+        const promptExposure = isCliLimitResourceKind(err.details.resource ?? "")
+            ? queueCliLimitNoticeExposure(err.details.resource, "refusal", err.details.companyUid)
+            : null;
         deps.setExitCode(1);
         if (interactive && err.details.upgradeUrl) {
             const companyUid = err.details.companyUid;
@@ -429,24 +436,28 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
                     err.code === "BILLING_REQUIRED");
             if (isCompanyWorkforceCheckout && companyUid) {
                 try {
-                    await offerTeamUpgrade(async () => {
+                    const upgraded = await offerTeamUpgrade(async () => {
                         await (deps.upgradeToTeam ?? upgradeToTeam)({ companyUid });
                     }, {
                         interactive: true,
                         argv: deps.argv,
                         ask: deps.ask,
                     });
+                    if (upgraded)
+                        queueCliLimitNoticeEngagement(promptExposure);
                 }
                 catch (upgradeErr) {
                     const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
                     deps.stderr.write(`hq: ${message}\n`);
                     try {
-                        await offerUpgradeLink(err.details.upgradeUrl, {
+                        const opened = await offerUpgradeLink(err.details.upgradeUrl, {
                             interactive: true,
                             argv: deps.argv,
                             ask: deps.ask,
                             openUrl: deps.openUrl,
                         });
+                        if (opened)
+                            queueCliLimitNoticeEngagement(promptExposure);
                     }
                     catch (linkErr) {
                         const linkMessage = linkErr instanceof Error ? linkErr.message : String(linkErr);
@@ -456,12 +467,14 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             }
             else {
                 try {
-                    await offerUpgradeLink(err.details.upgradeUrl, {
+                    const opened = await offerUpgradeLink(err.details.upgradeUrl, {
                         interactive: true,
                         argv: deps.argv,
                         ask: deps.ask,
                         openUrl: deps.openUrl,
                     });
+                    if (opened)
+                        queueCliLimitNoticeEngagement(promptExposure);
                 }
                 catch (upgradeErr) {
                     const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);

package/dist/utils/cli-telemetry.d.ts

@@ -10,6 +10,24 @@ export declare const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when yo
 export declare 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 declare const CLI_FEATURE_USED_TELEMETRY_FLAG = "cli.feature-used-telemetry-v1";
 export declare 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.";
+export declare const CLI_LIMIT_AT_ACTION_PROMPT_FLAG = "billing.limit-at-action-prompt";
+export type CliLimitResourceKind = "users" | "integrations" | "secrets" | "agents" | "deployments" | "storageBytes";
+export type CliLimitPresentationKind = "advisory" | "refusal";
+export interface CliLimitNoticeExposure {
+    companyUid: string;
+    resourceKind: CliLimitResourceKind;
+    presentationKind: CliLimitPresentationKind;
+    exposureId: string;
+}
+export interface CliLimitNoticeEngagement extends CliLimitNoticeExposure {
+    action: "upgrade_clicked";
+}
+/** Capture an exposure only after its notice has been written to the terminal. */
+export declare function queueCliLimitNoticeExposure(resourceKind: CliLimitResourceKind, presentationKind: CliLimitPresentationKind, resolvedCompanyUid?: string): CliLimitNoticeExposure | null;
+/** Only an explicit, confirmed browser open is an upgrade engagement. */
+export declare function queueCliLimitNoticeEngagement(exposure: CliLimitNoticeExposure | null): void;
+export declare function takeCliLimitNoticeExposures(): CliLimitNoticeExposure[];
+export declare function takeCliLimitNoticeEngagements(): CliLimitNoticeEngagement[];
 /** Queue one exposure after the CLI has printed the invite suggestion. */
 export declare function queuePlanLimitInviteTeammateExposure(companyUid: string): void;
 /** Drain invite-suggestion exposures for the bounded command-finalization flush. */
@@ -22,6 +40,7 @@ export interface CliFeatureUsage {
     /** Only company UIDs are accepted; names and slugs are never telemetry fields. */
     companyUid?: string;
 }
+export declare function isCliLimitResourceKind(value: string): value is CliLimitResourceKind;
 /**
  * Emit one bounded, privacy-limited feature-use event with a cached identity.
  * It never refreshes credentials or turns telemetry failure into command failure.
@@ -55,4 +74,6 @@ export declare function emitCliSessionStarted(timeoutMs?: number): Promise<void>
 /** Emit one authenticated measurement for a first-sync prompt outcome. */
 export declare function emitCliFirstSyncNextStepOutcome(outcome: FirstSyncStepOutcome, timeoutMs?: number): Promise<void>;
 export declare function emitPlanLimitInviteTeammateExposure(companyUid: string, timeoutMs?: number): Promise<void>;
+export declare function emitCliLimitNoticeExposure(exposure: CliLimitNoticeExposure, timeoutMs?: number): Promise<void>;
+export declare function emitCliLimitNoticeEngagement(engagement: CliLimitNoticeEngagement, timeoutMs?: number): Promise<void>;
 //# sourceMappingURL=cli-telemetry.d.ts.map

package/dist/utils/cli-telemetry.js

@@ -4,7 +4,7 @@ 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 { resolveProcessFlagGate } from "../lib/flag-registry.js";
+import { resolveProcessFlagCompanyContext, resolveProcessFlagGate, } from "../lib/flag-registry.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";
@@ -24,6 +24,38 @@ 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();
@@ -36,6 +68,9 @@ 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.
@@ -382,4 +417,69 @@ export async function emitPlanLimitInviteTeammateExposure(companyUid, timeoutMs
         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/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.js

@@ -30,6 +30,7 @@ import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { daemonDir } from "../lib/mesh/live/daemon/paths.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
 import { acquireLockFileExclusively } from "./exclusive-lock.js";
+import { reportNoninteractivePersonRefreshRejection } from "./cognito-refresh-sentry.js";
 // Re-export the cached-session primitives for callers that must deliberately
 // avoid the refresh/login behavior in the higher-level helpers below.
 export { isExpiring, isMachineIdentity, loadCachedTokens };
@@ -879,6 +880,37 @@ export function isDefinitivePersonAuthRejection(err) {
 function markPersonSessionRejected(accessToken) {
     invalidateCachedTokensByFingerprint(accessTokenFingerprint(accessToken));
 }
+async function reportPersonRefreshRejectionBestEffort(error) {
+    try {
+        await reportNoninteractivePersonRefreshRejection(error);
+    }
+    catch {
+        // Reporting is deliberately non-blocking for auth recovery and invalidation.
+    }
+}
+/**
+ * A refresh rejection applies to the snapshot sent to Cognito. Reread the
+ * shared person cache before rejecting the session because another process
+ * may have atomically installed a fresh generation while the request ran.
+ */
+function resolvePersonSessionAfterRefreshRejection(cached) {
+    const current = readPersonTokenFile();
+    const cachedKey = cognitoSubjectKey(cached);
+    const currentKey = cognitoSubjectKey(current);
+    if (!current || current.accessToken === cached.accessToken)
+        return { kind: "none" };
+    if (cachedKey && currentKey && cachedKey !== currentKey) {
+        return {
+            kind: "identity-swap",
+            error: new IdentitySwapRefusal("refusing rejected refresh for " + formatCognitoSubject(cached) +
+                ": the active token file now belongs to " + formatCognitoSubject(current)),
+        };
+    }
+    if (cachedKey && currentKey === cachedKey && !isExpiring(current, 120)) {
+        return { kind: "fresh", tokens: current };
+    }
+    return { kind: "none" };
+}
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in
  * as needed. Person cache lives at ~/.hq/cognito-tokens.json. Machine minting
@@ -931,6 +963,15 @@ async function ensureCognitoTokenUnserialized(options) {
             if (!isDefinitivePersonAuthRejection(err)) {
                 throw err;
             }
+            const resolution = resolvePersonSessionAfterRefreshRejection(cached);
+            if (resolution.kind === "identity-swap")
+                throw resolution.error;
+            if (resolution.kind === "fresh") {
+                return resolution.tokens.accessToken;
+            }
+            if (!interactive) {
+                await reportPersonRefreshRejectionBestEffort(err);
+            }
             markPersonSessionRejected(cached.accessToken);
             const fallback = await tryDefaultMachineCredsFallback(options);
             if (fallback)
@@ -1007,6 +1048,13 @@ async function ensureCognitoIdTokenUnserialized(options) {
             if (!isDefinitivePersonAuthRejection(err)) {
                 throw err;
             }
+            const resolution = resolvePersonSessionAfterRefreshRejection(cached);
+            if (resolution.kind === "identity-swap")
+                throw resolution.error;
+            if (resolution.kind === "fresh")
+                return resolution.tokens.idToken;
+            if (!interactive)
+                await reportPersonRefreshRejectionBestEffort(err);
             markPersonSessionRejected(cached.accessToken);
             const fallback = await tryDefaultMachineCredsFallback(options);
             if (fallback)
@@ -1123,6 +1171,13 @@ async function refreshCachedSessionUnserialized(options) {
                 reason: err instanceof Error ? err.message : String(err),
             };
         }
+        const resolution = resolvePersonSessionAfterRefreshRejection(cached);
+        if (resolution.kind === "identity-swap") {
+            return { refreshed: false, reason: resolution.error.message };
+        }
+        if (resolution.kind === "fresh")
+            return { refreshed: true };
+        await reportPersonRefreshRejectionBestEffort(err);
         // Definitive rejection — person session is dead; mark it and fall back.
         markPersonSessionRejected(cached.accessToken);
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.287.0",
+  "version": "5.288.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {