@indigoai-us/hq-cli 5.108.6 → 5.108.7

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.108.7] — 2026-09-05
+
+### Fixed
+
+- Fresh agent boxes and Outposts no longer fail `hq auth refresh` with "No
+  valid session: no cached session" when `HQ_MACHINE_CREDS_FILE` is unset.
+  Regression since 5.108.2: machine-token minting required that env (or an
+  explicit `{ tokenSource: "machine" }`), but hq-pro cloud-init never exports
+  it, so bootstrap aborted after sixty refresh failures. When the env is
+  unset, there is no usable person session at `~/.hq/cognito-tokens.json`, and
+  the default `~/.hq-agent/machine-creds.json` is readable, the CLI now mints
+  from that file (same daemon-state-dir cache as the env opt-in) and logs
+  `machine identity from default creds file`. A present person session still
+  wins so a human login is never flipped onto machine tokens; explicit
+  `tokenSource: "person"` never uses machine creds. `hq auth status` and
+  `hq whoami` report the resolved token source.
+
 ## [5.108.6] — 2026-09-05
 
 ### Added

package/dist/commands/auth.js

@@ -14,8 +14,8 @@
  * by the deploy + sync skills.
  */
 import chalk from "chalk";
-import { browserLogin, clearCachedTokens, loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
-import { DEFAULT_COGNITO, refreshCachedSession, } from "../utils/cognito-session.js";
+import { browserLogin, clearCachedTokens, loadCachedTokens, isExpiring, loadMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
+import { DEFAULT_COGNITO, refreshCachedSession, resolveCognitoTokenSource, } from "../utils/cognito-session.js";
 import { cognitoConfigForLoginProvider } from "../utils/login-provider.js";
 import { callbackPortBusyGuidance, DEFAULT_CALLBACK_PORT, isCallbackPortBusy, } from "../utils/callback-port-busy.js";
 /**
@@ -56,7 +56,7 @@ export function registerAuthCommands(program) {
         .description("Sign in to HQ — opens the Cognito Hosted UI and caches tokens locally")
         .option("--provider <provider>", "OAuth provider to use: google, microsoft, or picker")
         .action(async (options) => {
-        if (isMachineIdentity()) {
+        if (resolveCognitoTokenSource() === "machine") {
             console.log(chalk.green(`Running as ${machineIdentityLabel()} — sessions mint automatically; no browser login needed.`));
             return;
         }
@@ -119,16 +119,22 @@ export function registerAuthCommands(program) {
         .command("status")
         .description("Show whether a valid HQ session is cached")
         .action(() => {
-        const machine = isMachineIdentity();
+        // Effective source: env opt-in, fresh-box default-creds when no usable
+        // person session, or after a definitive person-refresh rejection marked
+        // the person cache rejected (transient refresh errors still report person).
+        const tokenSource = resolveCognitoTokenSource();
+        const machine = tokenSource === "machine";
         const cached = loadCachedTokens();
         if (!cached) {
             if (machine) {
                 // No cached session yet, but machine creds mint one on demand —
                 // report ready, not signed-out.
                 console.log(chalk.green(`${machineIdentityLabel()} — no cached session yet (mints automatically on first use)`));
+                console.log(chalk.dim(`token source: ${tokenSource}`));
                 return;
             }
             console.log(chalk.yellow("No cached HQ session — run `hq auth login`"));
+            console.log(chalk.dim(`token source: ${tokenSource}`));
             process.exit(1);
         }
         const claims = peekIdToken(cached.idToken);
@@ -140,6 +146,7 @@ export function registerAuthCommands(program) {
         console.log(expiring
             ? chalk.yellow(`${label}HQ session cached but expiring (expiresAt=${cached.expiresAt})`)
             : chalk.green(`${label}HQ session valid (expiresAt=${cached.expiresAt})`));
+        console.log(chalk.dim(`token source: ${tokenSource}`));
     });
 }
 //# sourceMappingURL=auth.js.map

package/dist/commands/whoami.js

@@ -2,8 +2,9 @@
  * hq whoami — displays current user or 'not logged in'
  */
 import chalk from 'chalk';
-import { loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, } from '@indigoai-us/hq-cloud';
+import { loadCachedTokens, isExpiring, loadMachineCreds, } from '@indigoai-us/hq-cloud';
 import { peekIdToken as decodeIdToken } from "../utils/id-token.js";
+import { resolveCognitoTokenSource } from "../utils/cognito-session.js";
 function peekIdToken(idToken) {
     const decoded = decodeIdToken(idToken);
     return {
@@ -23,7 +24,10 @@ export function registerWhoamiCommand(program) {
         .description('Show the currently authenticated user')
         .action(async () => {
         try {
-            const machine = isMachineIdentity();
+            // Effective source (same as auth status / ensureCognitoToken): env
+            // opt-in, fresh-box default-creds when no usable person session, or
+            // after a definitive person-refresh rejection marked the session rejected.
+            const machine = resolveCognitoTokenSource() === "machine";
             const cached = loadCachedTokens();
             if (machine) {
                 // Machine identities (company agents) mint sessions on demand from
@@ -34,6 +38,7 @@ export function registerWhoamiCommand(program) {
                     ? peekIdToken(cached.idToken).entityUid
                     : undefined;
                 console.log(`Machine identity ${username}${entityUid ? ` (agent ${entityUid})` : ''} — sessions mint automatically`);
+                console.log(`token source: machine`);
                 return;
             }
             if (!cached) {

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

@@ -93,31 +93,64 @@ export declare function machineTokenStateDir(home?: string, env?: NodeJS.Process
 export declare function machineTokenCacheFile(home?: string, env?: NodeJS.ProcessEnv): string;
 /**
  * True when `HQ_MACHINE_CREDS_FILE` is explicitly set (non-empty) in `env`.
- * The mere presence of `~/.hq-agent/machine-creds.json` is NOT enough — minting
- * and doctor "machine" reporting are opt-in via this env (systemd unit) or an
- * explicit `{ tokenSource: "machine" }` caller option.
+ * Explicit env remains the primary opt-in for daemon units. Fresh agent boxes
+ * without the env still mint via {@link wantsMachineCognitoTokens}'s
+ * default-file fallback when no usable person session exists.
  */
 export declare function isMachineCredsFileEnvSet(env?: NodeJS.ProcessEnv): boolean;
+/** Default machine-creds path hq-cloud also checks when the env is unset. */
+export declare function defaultMachineCredsFile(home?: string): string;
 export type EnsureCognitoTokenOptions = {
     interactive?: boolean;
     /**
      * Force machine-credential minting (`"machine"`) or the person login cache
-     * (`"person"`). When omitted, machine minting is used only if
-     * `HQ_MACHINE_CREDS_FILE` is explicitly set and readable.
+     * (`"person"`). When omitted, machine minting is used if
+     * `HQ_MACHINE_CREDS_FILE` is set, or (fresh-box fallback) the default
+     * `~/.hq-agent/machine-creds.json` is readable and no person session is
+     * cached. Explicit `"person"` never uses machine creds.
      */
     tokenSource?: CognitoTokenSource;
 };
+/**
+ * On-disk person Cognito cache path for `env` (`HQ_STATE_DIR` or `~/.hq`).
+ * Deliberately does not use hq-cloud's `loadCachedTokens()`: after a machine
+ * mint in this process, that helper returns in-memory machine tokens when the
+ * person file is absent, which would falsely block the fresh-box fallback.
+ */
+export declare function personTokenCacheFile(home?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * True when a usable person Cognito cache file exists under the effective
+ * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the
+ * person path even when the default machine-creds file is also on disk
+ * (no-flip guarantee).
+ */
+export declare function hasPersonCachedSession(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Fresh-box / Outpost bootstrap: env unset, not forced to person, no person
+ * cache, and the default machine-creds file is readable. Distinct from
+ * explicit `HQ_MACHINE_CREDS_FILE` / `{ tokenSource: "machine" }` opt-in.
+ */
+export declare function isDefaultMachineCredsFallback(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">, env?: NodeJS.ProcessEnv): boolean;
 /**
  * Whether this call should mint/cache via machine creds (USER_PASSWORD_AUTH).
- * Opt-in only: explicit `{ tokenSource: "machine" }`, or `HQ_MACHINE_CREDS_FILE`
- * set in the environment. Default-path `~/.hq-agent/machine-creds.json` alone
- * never flips other CLI commands onto the machine path.
+ *
+ * Machine path when:
+ *   - explicit `{ tokenSource: "machine" }` and creds are readable, or
+ *   - `HQ_MACHINE_CREDS_FILE` is set and readable, or
+ *   - fresh-box fallback: env unset, no person cache, default
+ *     `~/.hq-agent/machine-creds.json` readable.
+ *
+ * Explicit `{ tokenSource: "person" }` never uses machine creds. A present
+ * person cache keeps the person path even when the default creds file exists
+ * (do not flip a human's commands onto machine tokens).
  */
 export declare function wantsMachineCognitoTokens(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">, env?: NodeJS.ProcessEnv): boolean;
 /**
- * Which Cognito token source this process will use for doctor / reporting:
- * machine only when `HQ_MACHINE_CREDS_FILE` is explicitly set and readable;
- * otherwise the person login cache. Default-path machine-creds alone → person.
+ * Which Cognito token source this process will use for doctor / status / whoami.
+ * Matches {@link wantsMachineCognitoTokens}: env opt-in, or default-file
+ * fallback when no usable person session is cached (absent, or marked rejected
+ * after a definitive Cognito refresh refusal). Transient refresh failures do
+ * not flip this to machine.
  */
 export declare function resolveCognitoTokenSource(env?: NodeJS.ProcessEnv): CognitoTokenSource;
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
@@ -143,19 +176,28 @@ export declare function describeCognitoTokenSource(opts?: {
  * Run `fn` with `HQ_STATE_DIR` pointed at the machine/daemon token cache so
  * hq-cloud's mint writes never touch the person login file.
  *
- * When `HQ_STATE_DIR` is already set (tests / explicit callers), leave it alone
- * so a pre-seeded machine session is still found — only redirect when unset.
+ * Always redirects — even when the caller already set `HQ_STATE_DIR` (person
+ * cache / tests). Override the machine cache location with
+ * `HQ_MACHINE_TOKEN_STATE_DIR` instead. Restores the prior env afterwards.
  */
 export declare function withMachineTokenStateDir<T>(fn: () => Promise<T>, opts?: {
     home?: string;
     env?: NodeJS.ProcessEnv;
 }): Promise<T>;
+/**
+ * True when a person-token refresh failed with a definitive Cognito auth
+ * rejection (refresh token invalid/revoked). Transient network/5xx/timeouts
+ * must NOT trigger machine-identity fallback.
+ */
+export declare function isDefinitivePersonAuthRejection(err: unknown): boolean;
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in
  * as needed. Person cache lives at ~/.hq/cognito-tokens.json. Machine minting
- * is opt-in: `HQ_MACHINE_CREDS_FILE` explicitly set, or
- * `{ tokenSource: "machine" }` — then USER_PASSWORD_AUTH and (when
- * `HQ_STATE_DIR` is unset) a cache under the daemon state dir.
+ * uses `HQ_MACHINE_CREDS_FILE` / `{ tokenSource: "machine" }`, or the fresh-box
+ * fallback when the default creds file is readable and no person session
+ * exists (or person refresh fails with a definitive auth rejection).
+ * Machine tokens always cache under the dedicated machine/daemon state dir
+ * (never the caller's `HQ_STATE_DIR` person cache).
  *
  * Pass `interactive: false` from automated contexts (e.g. the `hq-auth-refresh`
  * bin invoked by the deploy skill) where failing fast is better than opening

package/dist/utils/cognito-session.js

@@ -23,7 +23,7 @@ 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, } from "@indigoai-us/hq-cloud";
+import { loadCachedTokens, isExpiring, refreshTokens, 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";
@@ -248,40 +248,36 @@ export function machineTokenCacheFile(home = os.homedir(), env = process.env) {
 }
 /**
  * True when `HQ_MACHINE_CREDS_FILE` is explicitly set (non-empty) in `env`.
- * The mere presence of `~/.hq-agent/machine-creds.json` is NOT enough — minting
- * and doctor "machine" reporting are opt-in via this env (systemd unit) or an
- * explicit `{ tokenSource: "machine" }` caller option.
+ * Explicit env remains the primary opt-in for daemon units. Fresh agent boxes
+ * without the env still mint via {@link wantsMachineCognitoTokens}'s
+ * default-file fallback when no usable person session exists.
  */
 export function isMachineCredsFileEnvSet(env = process.env) {
     const raw = env.HQ_MACHINE_CREDS_FILE;
     return typeof raw === "string" && raw.trim().length > 0;
 }
+/** Default machine-creds path hq-cloud also checks when the env is unset. */
+export function defaultMachineCredsFile(home = os.homedir()) {
+    return path.join(home, ".hq-agent", "machine-creds.json");
+}
 /**
- * Whether this call should mint/cache via machine creds (USER_PASSWORD_AUTH).
- * Opt-in only: explicit `{ tokenSource: "machine" }`, or `HQ_MACHINE_CREDS_FILE`
- * set in the environment. Default-path `~/.hq-agent/machine-creds.json` alone
- * never flips other CLI commands onto the machine path.
+ * Align `process.env.HQ_MACHINE_CREDS_FILE` with a (possibly synthetic) `env`
+ * for the duration of `fn`, so hq-cloud's `isMachineIdentity()` sees the same
+ * value doctor / tests intended.
  */
-export function wantsMachineCognitoTokens(options = {}, env = process.env) {
-    if (options.tokenSource === "person")
-        return false;
-    if (options.tokenSource === "machine") {
-        return isMachineIdentity();
-    }
-    if (!isMachineCredsFileEnvSet(env))
-        return false;
-    // Align process.env for hq-cloud's isMachineIdentity() when a synthetic env
-    // is supplied (doctor / tests).
+function withAlignedMachineCredsEnv(env, fn) {
     const prevCreds = process.env.HQ_MACHINE_CREDS_FILE;
     const nextCreds = env.HQ_MACHINE_CREDS_FILE;
     if (nextCreds !== prevCreds) {
-        if (nextCreds === undefined)
+        if (nextCreds === undefined || String(nextCreds).trim() === "") {
             delete process.env.HQ_MACHINE_CREDS_FILE;
-        else
+        }
+        else {
             process.env.HQ_MACHINE_CREDS_FILE = nextCreds;
+        }
     }
     try {
-        return isMachineIdentity();
+        return fn();
     }
     finally {
         if (nextCreds !== prevCreds) {
@@ -293,9 +289,104 @@ export function wantsMachineCognitoTokens(options = {}, env = process.env) {
     }
 }
 /**
- * Which Cognito token source this process will use for doctor / reporting:
- * machine only when `HQ_MACHINE_CREDS_FILE` is explicitly set and readable;
- * otherwise the person login cache. Default-path machine-creds alone → person.
+ * On-disk person Cognito cache path for `env` (`HQ_STATE_DIR` or `~/.hq`).
+ * Deliberately does not use hq-cloud's `loadCachedTokens()`: after a machine
+ * mint in this process, that helper returns in-memory machine tokens when the
+ * person file is absent, which would falsely block the fresh-box fallback.
+ */
+export function personTokenCacheFile(home = os.homedir(), env = process.env) {
+    const override = env.HQ_STATE_DIR?.trim();
+    const stateDir = override && override.length > 0 ? override : path.join(home, ".hq");
+    return path.join(stateDir, "cognito-tokens.json");
+}
+/**
+ * True when a usable person Cognito cache file exists under the effective
+ * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the
+ * person path even when the default machine-creds file is also on disk
+ * (no-flip guarantee).
+ */
+export function hasPersonCachedSession(env = process.env) {
+    try {
+        const file = personTokenCacheFile(os.homedir(), env);
+        if (!fs.existsSync(file))
+            return false;
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof raw.accessToken !== "string" ||
+            raw.accessToken.length === 0 ||
+            typeof raw.idToken !== "string" ||
+            raw.idToken.length === 0) {
+            return false;
+        }
+        // Definitive refresh rejection writes `${file}.invalid.<fingerprint>`;
+        // treat that as no usable person session so status/whoami report machine.
+        const marker = `${file}.invalid.${accessTokenFingerprint(raw.accessToken)}`;
+        if (fs.existsSync(marker))
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether hq-cloud currently sees readable machine creds (env override or
+ * default `~/.hq-agent/machine-creds.json`), honoring a synthetic `env`.
+ */
+function probeMachineIdentity(env) {
+    return withAlignedMachineCredsEnv(env, () => isMachineIdentity());
+}
+/**
+ * Fresh-box / Outpost bootstrap: env unset, not forced to person, no person
+ * cache, and the default machine-creds file is readable. Distinct from
+ * explicit `HQ_MACHINE_CREDS_FILE` / `{ tokenSource: "machine" }` opt-in.
+ */
+export function isDefaultMachineCredsFallback(options = {}, env = process.env) {
+    if (options.tokenSource === "person")
+        return false;
+    if (options.tokenSource === "machine")
+        return false;
+    if (isMachineCredsFileEnvSet(env))
+        return false;
+    if (hasPersonCachedSession(env))
+        return false;
+    return probeMachineIdentity(env);
+}
+function logDefaultMachineCredsFallback() {
+    console.error(chalk.dim("machine identity from default creds file"));
+}
+/**
+ * Whether this call should mint/cache via machine creds (USER_PASSWORD_AUTH).
+ *
+ * Machine path when:
+ *   - explicit `{ tokenSource: "machine" }` and creds are readable, or
+ *   - `HQ_MACHINE_CREDS_FILE` is set and readable, or
+ *   - fresh-box fallback: env unset, no person cache, default
+ *     `~/.hq-agent/machine-creds.json` readable.
+ *
+ * Explicit `{ tokenSource: "person" }` never uses machine creds. A present
+ * person cache keeps the person path even when the default creds file exists
+ * (do not flip a human's commands onto machine tokens).
+ */
+export function wantsMachineCognitoTokens(options = {}, env = process.env) {
+    if (options.tokenSource === "person")
+        return false;
+    if (options.tokenSource === "machine") {
+        return probeMachineIdentity(env);
+    }
+    if (isMachineCredsFileEnvSet(env)) {
+        return probeMachineIdentity(env);
+    }
+    // Fresh-box fallback — default creds file only when no person session.
+    if (hasPersonCachedSession(env))
+        return false;
+    return probeMachineIdentity(env);
+}
+/**
+ * Which Cognito token source this process will use for doctor / status / whoami.
+ * Matches {@link wantsMachineCognitoTokens}: env opt-in, or default-file
+ * fallback when no usable person session is cached (absent, or marked rejected
+ * after a definitive Cognito refresh refusal). Transient refresh failures do
+ * not flip this to machine.
  */
 export function resolveCognitoTokenSource(env = process.env) {
     return wantsMachineCognitoTokens({}, env) ? "machine" : "person";
@@ -400,16 +491,13 @@ export function describeCognitoTokenSource(opts = {}) {
  * Run `fn` with `HQ_STATE_DIR` pointed at the machine/daemon token cache so
  * hq-cloud's mint writes never touch the person login file.
  *
- * When `HQ_STATE_DIR` is already set (tests / explicit callers), leave it alone
- * so a pre-seeded machine session is still found — only redirect when unset.
+ * Always redirects — even when the caller already set `HQ_STATE_DIR` (person
+ * cache / tests). Override the machine cache location with
+ * `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 existing = env.HQ_STATE_DIR?.trim() || process.env.HQ_STATE_DIR?.trim() || "";
-    if (existing) {
-        return fn();
-    }
     const prev = process.env.HQ_STATE_DIR;
     process.env.HQ_STATE_DIR = machineTokenStateDir(home, env);
     try {
@@ -425,12 +513,54 @@ export async function withMachineTokenStateDir(fn, opts = {}) {
 async function ensureMachineTokens() {
     return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO));
 }
+/**
+ * Mint machine tokens (daemon state dir cache). Logs once when the fresh-box
+ * default-creds fallback is what selected the machine path.
+ */
+async function ensureMachineTokensMaybeFallback(options = {}) {
+    if (isDefaultMachineCredsFallback(options)) {
+        logDefaultMachineCredsFallback();
+    }
+    return ensureMachineTokens();
+}
+/**
+ * After a person-cache miss or refresh failure: if the default machine-creds
+ * file is readable and the caller did not force person mode, mint from it.
+ * Returns null when the fallback does not apply.
+ */
+async function tryDefaultMachineCredsFallback(options = {}) {
+    if (options.tokenSource === "person")
+        return null;
+    if (isMachineCredsFileEnvSet())
+        return null;
+    if (!isMachineIdentity())
+        return null;
+    logDefaultMachineCredsFallback();
+    return ensureMachineTokens();
+}
+/**
+ * True when a person-token refresh failed with a definitive Cognito auth
+ * rejection (refresh token invalid/revoked). Transient network/5xx/timeouts
+ * must NOT trigger machine-identity fallback.
+ */
+export function isDefinitivePersonAuthRejection(err) {
+    if (err instanceof CognitoRefreshError) {
+        return err.requiresReauth === true;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return /NotAuthorizedException|invalid_grant|invalid refresh token/i.test(msg);
+}
+function markPersonSessionRejected(accessToken) {
+    invalidateCachedTokensByFingerprint(accessTokenFingerprint(accessToken));
+}
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in
  * as needed. Person cache lives at ~/.hq/cognito-tokens.json. Machine minting
- * is opt-in: `HQ_MACHINE_CREDS_FILE` explicitly set, or
- * `{ tokenSource: "machine" }` — then USER_PASSWORD_AUTH and (when
- * `HQ_STATE_DIR` is unset) a cache under the daemon state dir.
+ * uses `HQ_MACHINE_CREDS_FILE` / `{ tokenSource: "machine" }`, or the fresh-box
+ * fallback when the default creds file is readable and no person session
+ * exists (or person refresh fails with a definitive auth rejection).
+ * Machine tokens always cache under the dedicated machine/daemon state dir
+ * (never the caller's `HQ_STATE_DIR` person cache).
  *
  * Pass `interactive: false` from automated contexts (e.g. the `hq-auth-refresh`
  * bin invoked by the deploy skill) where failing fast is better than opening
@@ -445,10 +575,10 @@ export async function ensureCognitoToken(options = {}) {
     // so vault-API calls from a machine identity send the ID token. The cached
     // token file keeps correct field semantics (real access token in
     // accessToken) for consumers that need token_use=access, e.g. the deploy
-    // API via the deploy skill. Cache path: daemon state dir when HQ_STATE_DIR
-    // is unset, never a silent overwrite of a person's ~/.hq.
+    // API via the deploy skill. Cache path: dedicated machine/daemon state dir
+    // (isolated even when HQ_STATE_DIR points at a person cache).
     if (wantsMachineCognitoTokens(options)) {
-        const machine = await ensureMachineTokens();
+        const machine = await ensureMachineTokensMaybeFallback(options);
         return machine.idToken;
     }
     const cached = loadCachedTokens();
@@ -464,11 +594,24 @@ export async function ensureCognitoToken(options = {}) {
             return refreshed.accessToken;
         }
         catch (err) {
+            // Transient/network/server errors stay person errors — never mint machine.
+            if (!isDefinitivePersonAuthRejection(err)) {
+                throw err;
+            }
+            markPersonSessionRejected(cached.accessToken);
+            const fallback = await tryDefaultMachineCredsFallback(options);
+            if (fallback)
+                return fallback.idToken;
             if (interactive) {
                 console.error(chalk.dim(`  Refresh failed (${err instanceof Error ? err.message : err}), falling back to browser login`));
             }
         }
     }
+    else {
+        const fallback = await tryDefaultMachineCredsFallback(options);
+        if (fallback)
+            return fallback.idToken;
+    }
     if (!interactive) {
         throw new Error("No valid HQ session and interactive login is disabled. Run `hq login` first.");
     }
@@ -490,7 +633,7 @@ export async function ensureCognitoToken(options = {}) {
 export async function ensureCognitoIdToken(options = {}) {
     const interactive = options.interactive ?? true;
     if (wantsMachineCognitoTokens(options)) {
-        const machine = await ensureMachineTokens();
+        const machine = await ensureMachineTokensMaybeFallback(options);
         return machine.idToken;
     }
     const cached = loadCachedTokens();
@@ -506,11 +649,23 @@ export async function ensureCognitoIdToken(options = {}) {
             return refreshed.idToken;
         }
         catch (err) {
+            if (!isDefinitivePersonAuthRejection(err)) {
+                throw err;
+            }
+            markPersonSessionRejected(cached.accessToken);
+            const fallback = await tryDefaultMachineCredsFallback(options);
+            if (fallback)
+                return fallback.idToken;
             if (interactive) {
                 console.error(chalk.dim(`  Refresh failed (${err instanceof Error ? err.message : err}), falling back to browser login`));
             }
         }
     }
+    else {
+        const fallback = await tryDefaultMachineCredsFallback(options);
+        if (fallback)
+            return fallback.idToken;
+    }
     if (!interactive) {
         throw new Error("No valid HQ session and interactive login is disabled. Run `hq login` first.");
     }
@@ -551,10 +706,11 @@ export function buildVaultConfig(authToken) {
 export async function refreshCachedSession(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 daemon state dir when HQ_STATE_DIR is unset.
+    // Tokens land under the dedicated machine/daemon state dir.
+    // Includes the fresh-box default-creds fallback when no person session.
     if (wantsMachineCognitoTokens(options)) {
         try {
-            await ensureMachineTokens();
+            await ensureMachineTokensMaybeFallback(options);
             return { refreshed: true };
         }
         catch (err) {
@@ -566,6 +722,20 @@ export async function refreshCachedSession(options = {}) {
     }
     const cached = loadCachedTokens();
     if (!cached) {
+        // Person path had nothing; last chance is default machine creds (e.g. the
+        // cache was cleared between the wantsMachine check and now, or identity
+        // became readable). Prefer machine mint over "no cached session" on boxes.
+        try {
+            const fallback = await tryDefaultMachineCredsFallback(options);
+            if (fallback)
+                return { refreshed: true };
+        }
+        catch (err) {
+            return {
+                refreshed: false,
+                reason: err instanceof Error ? err.message : String(err),
+            };
+        }
         return { refreshed: false, reason: "no cached session" };
     }
     if (!isExpiring(cached, 120)) {
@@ -576,6 +746,26 @@ export async function refreshCachedSession(options = {}) {
         return { refreshed: true };
     }
     catch (err) {
+        // Transient/network/server refresh errors stay person failures.
+        if (!isDefinitivePersonAuthRejection(err)) {
+            return {
+                refreshed: false,
+                reason: err instanceof Error ? err.message : String(err),
+            };
+        }
+        // Definitive rejection — person session is dead; mark it and fall back.
+        markPersonSessionRejected(cached.accessToken);
+        try {
+            const fallback = await tryDefaultMachineCredsFallback(options);
+            if (fallback)
+                return { refreshed: true };
+        }
+        catch (mintErr) {
+            return {
+                refreshed: false,
+                reason: mintErr instanceof Error ? mintErr.message : String(mintErr),
+            };
+        }
         return {
             refreshed: false,
             reason: err instanceof Error ? err.message : String(err),

package/package.json

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