@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/utils/cognito-session.js

@@ -18,15 +18,19 @@
  *   HQ_COGNITO_CALLBACK_PORT   — Loopback OAuth callback port
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import * as yaml from "js-yaml";
 import chalk from "chalk";
-import { loadCachedTokens, isExpiring, refreshTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
+import { loadCachedTokens, isExpiring, refreshTokens, saveCachedTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
 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 };
@@ -101,22 +105,24 @@ export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hq
  * Re-importable as a function for command-time resolution and tests.
  */
 export function resolveDefaultHqRoot(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? os.homedir();
     // Tier 1: explicit override.
-    if (process.env.HQ_ROOT)
-        return path.resolve(process.env.HQ_ROOT);
+    if (env.HQ_ROOT)
+        return path.resolve(env.HQ_ROOT);
     // Tier 2: working-tree walk-up — operate on the HQ tree you're inside.
-    let cur = path.resolve(process.cwd());
+    let cur = path.resolve(opts.cwd ?? process.cwd());
     while (cur !== path.dirname(cur)) {
         if (isHqRoot(cur))
             return cur;
         cur = path.dirname(cur);
     }
     // Tiers 3–4: the installer/menubar's canonical "where is HQ" records.
-    const fromConfig = readHqRootFromHqConfig(path.join(os.homedir(), ".hq"));
+    const fromConfig = readHqRootFromHqConfig(path.join(home, ".hq"));
     if (fromConfig)
         return path.resolve(fromConfig);
     // Tier 5: discover a valid HQ root in the well-known locations.
-    const discovered = discoverHqRootViaCoreYaml();
+    const discovered = discoverHqRootViaCoreYaml(home);
     if (discovered)
         return discovered;
     // Tier 6: nothing resolved.
@@ -126,7 +132,7 @@ export function resolveDefaultHqRoot(opts = {}) {
             "or install HQ via the installer/menubar so ~/.hq/menubar.json records " +
             "its location.");
     }
-    return path.join(os.homedir(), "hq");
+    return path.join(home, "hq");
 }
 /**
  * Read the configured HQ root from the installer/menubar records under
@@ -155,8 +161,7 @@ function readJsonStringField(file, field) {
     }
 }
 /** Well-known parent locations an HQ tree commonly lives in (mirrors hq-sync). */
-function hqDiscoveryCandidates() {
-    const home = os.homedir();
+function hqDiscoveryCandidates(home = os.homedir()) {
     return [
         path.join(home, "HQ"),
         path.join(home, "hq"),
@@ -171,8 +176,8 @@ function hqDiscoveryCandidates() {
  * signature. First match wins; returns undefined if none qualify. Cheap — a
  * few stats plus one small YAML parse on a hit.
  */
-function discoverHqRootViaCoreYaml() {
-    return hqDiscoveryCandidates().find(isValidHqRootSignature);
+function discoverHqRootViaCoreYaml(home) {
+    return hqDiscoveryCandidates(home).find(isValidHqRootSignature);
 }
 /**
  * True iff `dir` carries a valid hq-core `core.yaml` — canonical
@@ -408,6 +413,308 @@ function decodeJwtPayload(token) {
         return null;
     }
 }
+/**
+ * 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 class IdentitySwapRefusal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IdentitySwapRefusal";
+    }
+}
+export function isIdentitySwapRefusal(err) {
+    return err instanceof IdentitySwapRefusal;
+}
+/** `sub` plus `custom:entityUid` from an unverified JWT. Either may be absent. */
+export function cognitoSubjectFromToken(token) {
+    const claims = decodeJwtPayload(token);
+    const sub = typeof claims?.sub === "string" && claims.sub.length > 0 ? claims.sub : null;
+    const entity = claims?.["custom:entityUid"];
+    const entityUid = typeof entity === "string" && entity.length > 0 ? entity : null;
+    return { sub, entityUid };
+}
+/** Stable local cache identity for a Cognito person or agent principal. */
+export function cognitoCachePrincipalUid(token) {
+    const claims = cognitoSubjectFromToken(token);
+    return claims.entityUid ?? claims.sub;
+}
+/** Stable subject key. Null when neither sub nor entity uid is present. */
+export function cognitoSubjectKey(tokens) {
+    if (!tokens)
+        return null;
+    const fromId = cognitoSubjectFromToken(tokens.idToken);
+    const fromAccess = cognitoSubjectFromToken(tokens.accessToken);
+    const sub = fromId.sub ?? fromAccess.sub;
+    const entityUid = fromId.entityUid ?? fromAccess.entityUid;
+    if (!sub && !entityUid)
+        return null;
+    return `${sub ?? ""}|${entityUid ?? ""}`;
+}
+/** Doctor/status line. Claims only — never token material. */
+export function formatCognitoSubject(tokens) {
+    if (!tokens)
+        return "sub=- entityUid=-";
+    const fromId = cognitoSubjectFromToken(tokens.idToken);
+    const fromAccess = cognitoSubjectFromToken(tokens.accessToken);
+    return `sub=${fromId.sub ?? fromAccess.sub ?? "-"} entityUid=${fromId.entityUid ?? fromAccess.entityUid ?? "-"}`;
+}
+function readTokenFile(file) {
+    try {
+        if (!fs.existsSync(file))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof raw.accessToken !== "string" || typeof raw.idToken !== "string")
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 function readPersonTokenFile(home = os.homedir(), env = process.env) {
+    return readTokenFile(personTokenCacheFile(home, env));
+}
+function restoreTokenFile(file, before) {
+    if (before) {
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = path.join(dir, `.cognito-tokens.json.restore.${process.pid}`);
+        fs.writeFileSync(tmp, before, { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        return;
+    }
+    if (fs.existsSync(file))
+        fs.unlinkSync(file);
+}
+/**
+ * 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 async function refreshActivePersonTokens(cached, env = process.env) {
+    const file = personTokenCacheFile(os.homedir(), env);
+    const onDisk = readTokenFile(file);
+    const diskKey = cognitoSubjectKey(onDisk);
+    const cachedKey = cognitoSubjectKey(cached);
+    if (diskKey && cachedKey && diskKey !== cachedKey) {
+        const message = `refusing token refresh: cached subject ${formatCognitoSubject(cached)} ` +
+            `does not match active subject ${formatCognitoSubject(onDisk)}; token file left unchanged`;
+        console.error(message);
+        throw new IdentitySwapRefusal(message);
+    }
+    const activeTokens = diskKey && cachedKey && diskKey === cachedKey ? onDisk : cached;
+    const activeKey = cognitoSubjectKey(activeTokens);
+    const before = fs.existsSync(file) ? fs.readFileSync(file) : null;
+    const refreshed = await refreshTokens(DEFAULT_COGNITO, activeTokens.refreshToken, activeTokens.accessToken);
+    const nextKey = cognitoSubjectKey(refreshed);
+    if (activeKey && nextKey && nextKey !== activeKey) {
+        restoreTokenFile(file, before);
+        const message = `refusing token refresh: refreshed subject ${formatCognitoSubject(refreshed)} ` +
+            `does not match active subject ${formatCognitoSubject(activeTokens)}; token file left unchanged`;
+        console.error(message);
+        throw new IdentitySwapRefusal(message);
+    }
+    return refreshed;
+}
+function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw signal.reason ?? new Error("Token acquisition was aborted");
+}
+function waitForRefreshLock(signal, delayMs) {
+    return new Promise((resolve, reject) => {
+        const finish = (error) => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const timer = setTimeout(() => finish(), delayMs);
+        const onAbort = () => finish(signal.reason ?? new Error("Token acquisition was aborted"));
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Refresh-lock protocol shared with hq-cloud, with caller cancellation while
+ * waiting. The flag lookup is best-effort, so it never refreshes unlocked.
+ */
+async function withAbortablePersonRefreshLock(signal, fn) {
+    const lockFile = `${personTokenCacheFile()}.lock`;
+    const stateDir = path.dirname(lockFile);
+    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const candidate = `${lockFile}.candidate.${process.pid}.${randomBytes(8).toString("hex")}`;
+    fs.writeFileSync(candidate, String(process.pid), { flag: "wx", mode: 0o600 });
+    let held = false;
+    try {
+        for (;;) {
+            throwIfAborted(signal);
+            try {
+                acquireLockFileExclusively(candidate, lockFile, stateDir);
+                held = true;
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                let ownerPid = null;
+                try {
+                    const parsed = Number.parseInt(fs.readFileSync(lockFile, "utf8").trim(), 10);
+                    if (Number.isInteger(parsed) && parsed > 0)
+                        ownerPid = parsed;
+                }
+                catch {
+                    // An absent or malformed lock may be reclaimed below.
+                }
+                let ownerAlive = false;
+                if (ownerPid !== null) {
+                    try {
+                        process.kill(ownerPid, 0);
+                        ownerAlive = true;
+                    }
+                    catch (probeError) {
+                        ownerAlive = probeError.code === "EPERM";
+                    }
+                }
+                if (!ownerAlive) {
+                    try {
+                        fs.unlinkSync(lockFile);
+                    }
+                    catch {
+                        // Another contender may have reclaimed it first.
+                    }
+                    continue;
+                }
+                await waitForRefreshLock(signal, 50);
+            }
+        }
+        throwIfAborted(signal);
+        return await fn();
+    }
+    finally {
+        if (held) {
+            try {
+                const owner = Number.parseInt(fs.readFileSync(lockFile, "utf8").trim(), 10);
+                if (owner === process.pid)
+                    fs.unlinkSync(lockFile);
+            }
+            catch {
+                // A failed request must not mask its original error.
+            }
+        }
+        try {
+            fs.unlinkSync(candidate);
+        }
+        catch {
+            // The candidate may already have been removed.
+        }
+    }
+}
+/**
+ * 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 async function refreshActivePersonTokensForClientHealth(cached, signal) {
+    // Cognito refresh rotation is off for this client (#2603; ALLOW_REFRESH_TOKEN_AUTH stays), so aborting loses no rotated token; keep this lock protocol identical to hq-cloud withRefreshLock.
+    return withAbortablePersonRefreshLock(signal, async () => {
+        throwIfAborted(signal);
+        const onDisk = readPersonTokenFile();
+        const diskKey = cognitoSubjectKey(onDisk);
+        const cachedKey = cognitoSubjectKey(cached);
+        if (diskKey && cachedKey && diskKey !== cachedKey) {
+            throw new IdentitySwapRefusal(`refusing token refresh: cached subject ${formatCognitoSubject(cached)} ` +
+                `does not match active subject ${formatCognitoSubject(onDisk)}`);
+        }
+        const activeTokens = onDisk ?? cached;
+        if (!isExpiring(activeTokens, 120))
+            return activeTokens;
+        if (!activeTokens.refreshToken) {
+            throw new CognitoRefreshError("No refresh token is available for the cached HQ session", true);
+        }
+        const body = new URLSearchParams({
+            grant_type: "refresh_token",
+            client_id: DEFAULT_COGNITO.clientId,
+            refresh_token: activeTokens.refreshToken,
+        });
+        const endpoint = `https://${DEFAULT_COGNITO.userPoolDomain}.auth.${DEFAULT_COGNITO.region}.amazoncognito.com/oauth2/token`;
+        const fingerprint = accessTokenFingerprint(activeTokens.accessToken);
+        let response;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            throwIfAborted(signal);
+            try {
+                response = await fetch(endpoint, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    body: body.toString(),
+                    signal,
+                });
+            }
+            catch (err) {
+                throwIfAborted(signal);
+                if (attempt === 0)
+                    continue;
+                throw new CognitoRefreshError(`Cognito refresh request failed: ${err instanceof Error ? err.message : String(err)}`, false, undefined, fingerprint);
+            }
+            throwIfAborted(signal);
+            if (response.ok)
+                break;
+            const retryable = response.status === 401 ||
+                response.status === 408 ||
+                response.status === 429 ||
+                response.status >= 500;
+            if (retryable && attempt === 0)
+                continue;
+            const reauth = response.status === 401 ||
+                (response.status >= 400 && response.status < 500 && ![408, 429].includes(response.status));
+            throw new CognitoRefreshError(`Cognito refresh failed (${response.status})`, reauth, response.status, fingerprint);
+        }
+        if (!response?.ok) {
+            throw new CognitoRefreshError("Cognito refresh failed after retry", false, undefined, fingerprint);
+        }
+        const data = (await response.json());
+        throwIfAborted(signal);
+        if (typeof data.access_token !== "string" ||
+            typeof data.id_token !== "string" ||
+            typeof data.expires_in !== "number" ||
+            !Number.isFinite(data.expires_in) ||
+            data.expires_in <= 0) {
+            throw new CognitoRefreshError("Cognito refresh returned an invalid token response", false);
+        }
+        const refreshed = {
+            accessToken: data.access_token,
+            idToken: data.id_token,
+            refreshToken: typeof data.refresh_token === "string" && data.refresh_token.length > 0
+                ? data.refresh_token
+                : activeTokens.refreshToken,
+            expiresAt: Date.now() + data.expires_in * 1_000,
+            tokenType: "Bearer",
+        };
+        const activeKey = cognitoSubjectKey(activeTokens);
+        const nextKey = cognitoSubjectKey(refreshed);
+        if (activeKey && nextKey && nextKey !== activeKey) {
+            throw new IdentitySwapRefusal(`refusing token refresh: refreshed subject ${formatCognitoSubject(refreshed)} ` +
+                `does not match active subject ${formatCognitoSubject(activeTokens)}`);
+        }
+        throwIfAborted(signal);
+        saveCachedTokens(refreshed);
+        return refreshed;
+    });
+}
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
 export function actorKindFromIdToken(idToken) {
     const claims = decodeJwtPayload(idToken);
@@ -496,23 +803,52 @@ export function describeCognitoTokenSource(opts = {}) {
  * `HQ_MACHINE_TOKEN_STATE_DIR` instead. Restores the prior env afterwards.
  */
 export async function withMachineTokenStateDir(fn, opts = {}) {
-    const home = opts.home ?? os.homedir();
-    const env = opts.env ?? process.env;
-    const prev = process.env.HQ_STATE_DIR;
-    process.env.HQ_STATE_DIR = machineTokenStateDir(home, env);
-    try {
-        return await fn();
-    }
-    finally {
-        if (prev === undefined)
-            delete process.env.HQ_STATE_DIR;
-        else
-            process.env.HQ_STATE_DIR = prev;
-    }
+    return withTokenStateDirSection(async () => {
+        const home = opts.home ?? os.homedir();
+        const env = opts.env ?? process.env;
+        const prev = process.env.HQ_STATE_DIR;
+        process.env.HQ_STATE_DIR = machineTokenStateDir(home, env);
+        try {
+            return await fn();
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.HQ_STATE_DIR;
+            else
+                process.env.HQ_STATE_DIR = prev;
+        }
+    });
+}
+/**
+ * The token cache location (`HQ_STATE_DIR`) is process-wide, and a machine mint
+ * points it at the machine cache across an await. A person-session read in the
+ * same process while that mint is in flight would load the MACHINE tokens: a
+ * local bot's resident (machine identity for its own calls) checking its
+ * owner's sign-in at startup got the bot's token and "No person entity found".
+ * Every section that swaps or reads the cache location runs one at a time;
+ * nested sections (a person read falling back to a machine mint) run inline.
+ */
+const tokenStateDirSection = new AsyncLocalStorage();
+let tokenStateDirTail = Promise.resolve();
+function withTokenStateDirSection(fn) {
+    if (tokenStateDirSection.getStore())
+        return fn();
+    const run = tokenStateDirTail.then(() => tokenStateDirSection.run(true, fn));
+    tokenStateDirTail = run.catch(() => undefined);
+    return run;
 }
 async function ensureMachineTokens() {
     return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO));
 }
+/**
+ * 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 async function ensureMachineSessionTokens() {
+    const tokens = await ensureMachineTokensMaybeFallback({ tokenSource: "machine" });
+    return { accessToken: tokens.accessToken, idToken: tokens.idToken, expiresAt: tokens.expiresAt };
+}
 /**
  * Mint machine tokens (daemon state dir cache). Logs once when the fresh-box
  * default-creds fallback is what selected the machine path.
@@ -553,6 +889,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
@@ -567,6 +934,11 @@ function markPersonSessionRejected(accessToken) {
  * a browser.
  */
 export async function ensureCognitoToken(options = {}) {
+    if (wantsMachineCognitoTokens(options))
+        return ensureCognitoTokenUnserialized(options);
+    return withTokenStateDirSection(() => ensureCognitoTokenUnserialized(options));
+}
+async function ensureCognitoTokenUnserialized(options) {
     const interactive = options.interactive ?? true;
     // Machine identities (company agents) mint sessions on demand via
     // USER_PASSWORD_AUTH — no refresh-token dance, no browser. The vault API's
@@ -590,14 +962,25 @@ export async function ensureCognitoToken(options = {}) {
             if (interactive) {
                 console.error(chalk.dim("  Refreshing expiring HQ session..."));
             }
-            const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+            const refreshed = await refreshActivePersonTokens(cached);
             return refreshed.accessToken;
         }
         catch (err) {
+            if (isIdentitySwapRefusal(err))
+                throw err;
             // Transient/network/server errors stay person errors — never mint machine.
             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)
@@ -615,6 +998,15 @@ export async function ensureCognitoToken(options = {}) {
     if (!interactive) {
         throw new Error("No valid HQ session and interactive login is disabled. Run `hq login` first.");
     }
+    if (isHeadlessHost() && hostRunsAnAgent()) {
+        // An agent host with no display has no one to complete a browser sign-in,
+        // which then blocks until something kills the process. Fail with the fix
+        // instead. Scoped to agent hosts so an ordinary headless run keeps the
+        // existing sign-in and its remedies.
+        throw new Error("No valid HQ session, and this host has no display for a browser sign-in. " +
+            "If this is an enrolled agent, set HQ_AGENT_DIR to its agent directory " +
+            "(or HQ_MACHINE_CREDS_FILE to its machine-creds.json). Otherwise run `hq login` on a computer with a browser.");
+    }
     console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
     const tokens = await browserLogin(DEFAULT_COGNITO);
     return tokens.accessToken;
@@ -631,7 +1023,16 @@ export async function ensureCognitoToken(options = {}) {
  * identical to `ensureCognitoToken` there.
  */
 export async function ensureCognitoIdToken(options = {}) {
+    if (options.signal?.aborted)
+        throw options.signal.reason ?? new Error("Token acquisition was aborted");
+    if (wantsMachineCognitoTokens(options))
+        return ensureCognitoIdTokenUnserialized(options);
+    return withTokenStateDirSection(() => ensureCognitoIdTokenUnserialized(options));
+}
+async function ensureCognitoIdTokenUnserialized(options) {
     const interactive = options.interactive ?? true;
+    if (options.signal?.aborted)
+        throw options.signal.reason ?? new Error("Token acquisition was aborted");
     if (wantsMachineCognitoTokens(options)) {
         const machine = await ensureMachineTokensMaybeFallback(options);
         return machine.idToken;
@@ -645,13 +1046,24 @@ export async function ensureCognitoIdToken(options = {}) {
             if (interactive) {
                 console.error(chalk.dim("  Refreshing expiring HQ session..."));
             }
-            const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+            const refreshed = options.signal
+                ? await refreshActivePersonTokensForClientHealth(cached, options.signal)
+                : await refreshActivePersonTokens(cached);
             return refreshed.idToken;
         }
         catch (err) {
+            if (options.signal?.aborted || isIdentitySwapRefusal(err))
+                throw err;
             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)
@@ -669,6 +1081,13 @@ export async function ensureCognitoIdToken(options = {}) {
     if (!interactive) {
         throw new Error("No valid HQ session and interactive login is disabled. Run `hq login` first.");
     }
+    if (isHeadlessHost() && hostRunsAnAgent()) {
+        // A browser sign-in on a server has no one to complete it and blocks
+        // until something kills the process. Fail with the fix instead.
+        throw new Error("No valid HQ session, and this host has no display for a browser sign-in. " +
+            "If this is an enrolled agent, set HQ_AGENT_DIR to its agent directory " +
+            "(or HQ_MACHINE_CREDS_FILE to its machine-creds.json). Otherwise run `hq login` on a computer with a browser.");
+    }
     console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
     const tokens = await browserLogin(DEFAULT_COGNITO);
     return tokens.idToken;
@@ -704,6 +1123,11 @@ export function buildVaultConfig(authToken) {
  * reason string and can decide what to do next. Never opens a browser.
  */
 export async function refreshCachedSession(options = {}) {
+    if (wantsMachineCognitoTokens(options))
+        return refreshCachedSessionUnserialized(options);
+    return withTokenStateDirSection(() => refreshCachedSessionUnserialized(options));
+}
+async function refreshCachedSessionUnserialized(options) {
     // Machine identities have no refresh token; ensure a valid cached machine
     // session without forcing a re-mint when the cache is already healthy.
     // Tokens land under the dedicated machine/daemon state dir.
@@ -742,10 +1166,13 @@ export async function refreshCachedSession(options = {}) {
         return { refreshed: true };
     }
     try {
-        await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+        await refreshActivePersonTokens(cached);
         return { refreshed: true };
     }
     catch (err) {
+        if (isIdentitySwapRefusal(err)) {
+            return { refreshed: false, reason: err.message };
+        }
         // Transient/network/server refresh errors stay person failures.
         if (!isDefinitivePersonAuthRejection(err)) {
             return {
@@ -753,6 +1180,13 @@ export async function refreshCachedSession(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 {
@@ -772,4 +1206,24 @@ export async function refreshCachedSession(options = {}) {
         };
     }
 }
+/**
+ * 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 function isHeadlessHost(env = process.env, platform = process.platform, tty = Boolean(process.stdin.isTTY || process.stdout.isTTY || process.stderr.isTTY)) {
+    if (platform !== "linux")
+        return false;
+    if (tty)
+        return false;
+    return !env.DISPLAY?.trim() && !env.WAYLAND_DISPLAY?.trim();
+}
+/**
+ * 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 function hostRunsAnAgent(env = process.env) {
+    return Boolean(env.HQ_AGENT_DIR?.trim() || env.HQ_MACHINE_CREDS_FILE?.trim());
+}
 //# sourceMappingURL=cognito-session.js.map

package/dist/utils/console-origin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The console that fronts the control plane this CLI is pointed at.
+ *
+ * A handoff must land on the console for the same backend. When an override is
+ * active, derive its console from the control-plane host instead of assuming
+ * production. `HQ_CONSOLE_URL` remains an explicit override.
+ */
+export declare function consoleOrigin(vaultApiUrl?: string): string | undefined;
+//# sourceMappingURL=console-origin.d.ts.map