@indigoai-us/hq-cli 5.47.11 → 5.47.13

package/dist/bin/hq-auth-refresh.d.ts

@@ -6,8 +6,9 @@
  * shell out to a plain binary instead of a subcommand. Equivalent to
  * `hq auth refresh`.
  *
- * Exit 0 on refresh, exit 1 if no cached session or refresh failed.
- * Writes the refreshed tokens to ~/.hq/cognito-tokens.json.
+ * Exit 0 if a valid session is ensured now (healthy cache hit, refresh, or
+ * machine-token mint). Exit 1 if no valid session could be ensured
+ * non-interactively.
  */
 export {};
 //# sourceMappingURL=hq-auth-refresh.d.ts.map

package/dist/bin/hq-auth-refresh.js

@@ -6,11 +6,12 @@
  * shell out to a plain binary instead of a subcommand. Equivalent to
  * `hq auth refresh`.
  *
- * Exit 0 on refresh, exit 1 if no cached session or refresh failed.
- * Writes the refreshed tokens to ~/.hq/cognito-tokens.json.
+ * Exit 0 if a valid session is ensured now (healthy cache hit, refresh, or
+ * machine-token mint). Exit 1 if no valid session could be ensured
+ * non-interactively.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="28774b80-becb-5fb9-b676-dee74c26d73d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="03d2c531-f620-5d93-a87b-9a87264ad77b")}catch(e){}}();
 import { initSentry, Sentry } from "../sentry.js";
 import { refreshCachedSession } from "../utils/cognito-session.js";
 initSentry();
@@ -37,4 +38,4 @@ initSentry();
     }
 })();
 //# sourceMappingURL=hq-auth-refresh.js.map
-//# debugId=28774b80-becb-5fb9-b676-dee74c26d73d
+//# debugId=03d2c531-f620-5d93-a87b-9a87264ad77b

package/dist/commands/auth.d.ts

@@ -4,13 +4,13 @@
  * Subcommands:
  *   hq auth login     — open the Cognito Hosted UI in the browser and cache tokens
  *   hq auth logout    — clear the cached HQ session
- *   hq auth refresh   — refresh the cached Cognito session (non-interactive)
+ *   hq auth refresh   — ensure a valid cached Cognito session (non-interactive)
  *   hq auth status    — show whether a valid session is cached + expiry
  *
  * Sign-up is owned by the onboarding web app at
  * https://onboarding.indigo-hq.com. `hq auth login` signs an existing account
  * into this machine by writing ~/.hq/cognito-tokens.json; once cached, the
- * session is kept fresh by `hq auth refresh` / `hq-auth-refresh` and consumed
+ * session is kept valid by `hq auth refresh` / `hq-auth-refresh` and consumed
  * by the deploy + sync skills.
  */
 import { Command } from "commander";

package/dist/commands/auth.js

@@ -4,17 +4,17 @@
  * Subcommands:
  *   hq auth login     — open the Cognito Hosted UI in the browser and cache tokens
  *   hq auth logout    — clear the cached HQ session
- *   hq auth refresh   — refresh the cached Cognito session (non-interactive)
+ *   hq auth refresh   — ensure a valid cached Cognito session (non-interactive)
  *   hq auth status    — show whether a valid session is cached + expiry
  *
  * Sign-up is owned by the onboarding web app at
  * https://onboarding.indigo-hq.com. `hq auth login` signs an existing account
  * into this machine by writing ~/.hq/cognito-tokens.json; once cached, the
- * session is kept fresh by `hq auth refresh` / `hq-auth-refresh` and consumed
+ * session is kept valid by `hq auth refresh` / `hq-auth-refresh` and consumed
  * by the deploy + sync skills.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b9690c95-1d23-5c58-8cb3-0e3bdc8b35e8")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="66a74720-f5d1-58ed-93fd-ead15fc18146")}catch(e){}}();
 import chalk from "chalk";
 import { browserLogin, clearCachedTokens, loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
 import { refreshCachedSession, } from "../utils/cognito-session.js";
@@ -98,14 +98,14 @@ export function registerAuthCommands(program) {
     });
     authCmd
         .command("refresh")
-        .description("Refresh the cached Cognito session using the stored refresh token")
+        .description("Ensure a valid cached Cognito session (refresh only if expiring; no-op if already valid)")
         .action(async () => {
         const result = await refreshCachedSession();
         if (result.refreshed) {
-            console.log(chalk.green("HQ session refreshed"));
+            console.log(chalk.green("HQ session ensured"));
             return;
         }
-        console.error(chalk.yellow(`No refresh: ${result.reason ?? "unknown"}`));
+        console.error(chalk.yellow(`No valid session: ${result.reason ?? "unknown"}`));
         process.exit(1);
     });
     authCmd
@@ -136,4 +136,4 @@ export function registerAuthCommands(program) {
     });
 }
 //# sourceMappingURL=auth.js.map
-//# debugId=b9690c95-1d23-5c58-8cb3-0e3bdc8b35e8
+//# debugId=66a74720-f5d1-58ed-93fd-ead15fc18146

package/dist/commands/pkg-install.js

@@ -13,7 +13,7 @@
  * 9. Print next-step message
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c6ab4668-f147-5612-bbfc-e1e80b2f018a")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ac6f26b7-5678-5b4e-b0d8-2f5901adf9fe")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -25,7 +25,7 @@ import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { getRegistryUrl, RegistryClient, } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { addToRegistry } from '../utils/registry.js';
-import { installPack, sourceMatchesPackPattern } from './pack-install.js';
+import { MARKETPLACE_PREFIX, installPack, sourceMatchesPackPattern, } from './pack-install.js';
 export function registerPackageInstallCommand(parent) {
     parent
         .command('install <source>')
@@ -43,7 +43,14 @@ export function registerPackageInstallCommand(parent) {
                 });
             }
             else {
-                await installPackage(source, opts.company);
+                // Bare slugs: the legacy Cognito-gated registry backend
+                // (/packages, /entitlements) was never deployed, so a bare slug
+                // would fail at registry setup. Resolve it through the marketplace
+                // listings transport — the live install path — instead.
+                await installPack(`${MARKETPLACE_PREFIX}${source}`, {
+                    allowHooks: opts.allowHooks,
+                    followBranch: opts.branch,
+                });
             }
         }
         catch (error) {
@@ -156,4 +163,4 @@ async function installPackage(slug, company) {
     }
 }
 //# sourceMappingURL=pkg-install.js.map
-//# debugId=c6ab4668-f147-5612-bbfc-e1e80b2f018a
+//# debugId=ac6f26b7-5678-5b4e-b0d8-2f5901adf9fe

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

@@ -109,10 +109,12 @@ export declare const CLI_CLIENT_INFO: ClientInfo;
 /** Build a VaultServiceConfig with the given access token. */
 export declare function buildVaultConfig(authToken: string): VaultServiceConfig;
 /**
- * Refresh the cached Cognito session once and return the result. Used by
- * `hq auth refresh` and the `hq-auth-refresh` bin. Never opens a browser —
- * if no cached tokens exist or the refresh fails, returns `refreshed: false`
- * with a reason string so the caller can decide what to do.
+ * Ensure a valid cached Cognito session exists right now, non-interactively,
+ * and return the result. Used by `hq auth refresh` and the `hq-auth-refresh`
+ * bin. `refreshed: true` means a valid session is ensured now from a healthy
+ * cache hit, a token refresh, or a machine-token mint. `refreshed: false`
+ * means no valid session could be ensured non-interactively; the caller gets a
+ * reason string and can decide what to do next. Never opens a browser.
  */
 export declare function refreshCachedSession(): Promise<{
     refreshed: boolean;

package/dist/utils/cognito-session.js

@@ -19,13 +19,13 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="21e260f0-50fd-54c7-944a-c15630c42f3e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ab9733a5-3984-553b-8fcc-91b86d112c79")}catch(e){}}();
 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, mintMachineTokens, } from "@indigoai-us/hq-cloud";
+import { loadCachedTokens, isExpiring, refreshTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 export const DEFAULT_COGNITO = {
     region: process.env.AWS_REGION ?? "us-east-1",
@@ -334,17 +334,19 @@ export function buildVaultConfig(authToken) {
     };
 }
 /**
- * Refresh the cached Cognito session once and return the result. Used by
- * `hq auth refresh` and the `hq-auth-refresh` bin. Never opens a browser —
- * if no cached tokens exist or the refresh fails, returns `refreshed: false`
- * with a reason string so the caller can decide what to do.
+ * Ensure a valid cached Cognito session exists right now, non-interactively,
+ * and return the result. Used by `hq auth refresh` and the `hq-auth-refresh`
+ * bin. `refreshed: true` means a valid session is ensured now from a healthy
+ * cache hit, a token refresh, or a machine-token mint. `refreshed: false`
+ * means no valid session could be ensured non-interactively; the caller gets a
+ * reason string and can decide what to do next. Never opens a browser.
  */
 export async function refreshCachedSession() {
-    // Machine identities have no refresh token — a "refresh" is a fresh mint
-    // from the long-lived machine creds.
+    // Machine identities have no refresh token; ensure a valid cached machine
+    // session without forcing a re-mint when the cache is already healthy.
     if (isMachineIdentity()) {
         try {
-            await mintMachineTokens(DEFAULT_COGNITO);
+            await getValidMachineTokens(DEFAULT_COGNITO);
             return { refreshed: true };
         }
         catch (err) {
@@ -358,6 +360,9 @@ export async function refreshCachedSession() {
     if (!cached) {
         return { refreshed: false, reason: "no cached session" };
     }
+    if (!isExpiring(cached, 120)) {
+        return { refreshed: true };
+    }
     try {
         await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
         return { refreshed: true };
@@ -370,4 +375,4 @@ export async function refreshCachedSession() {
     }
 }
 //# sourceMappingURL=cognito-session.js.map
-//# debugId=21e260f0-50fd-54c7-944a-c15630c42f3e
+//# debugId=ab9733a5-3984-553b-8fcc-91b86d112c79

package/package.json

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

package/src/bin/hq-auth-refresh.ts

@@ -7,8 +7,9 @@
  * shell out to a plain binary instead of a subcommand. Equivalent to
  * `hq auth refresh`.
  *
- * Exit 0 on refresh, exit 1 if no cached session or refresh failed.
- * Writes the refreshed tokens to ~/.hq/cognito-tokens.json.
+ * Exit 0 if a valid session is ensured now (healthy cache hit, refresh, or
+ * machine-token mint). Exit 1 if no valid session could be ensured
+ * non-interactively.
  */
 
 import { initSentry, Sentry } from "../sentry.js";

package/src/commands/auth.ts

@@ -4,13 +4,13 @@
  * Subcommands:
  *   hq auth login     — open the Cognito Hosted UI in the browser and cache tokens
  *   hq auth logout    — clear the cached HQ session
- *   hq auth refresh   — refresh the cached Cognito session (non-interactive)
+ *   hq auth refresh   — ensure a valid cached Cognito session (non-interactive)
  *   hq auth status    — show whether a valid session is cached + expiry
  *
  * Sign-up is owned by the onboarding web app at
  * https://onboarding.indigo-hq.com. `hq auth login` signs an existing account
  * into this machine by writing ~/.hq/cognito-tokens.json; once cached, the
- * session is kept fresh by `hq auth refresh` / `hq-auth-refresh` and consumed
+ * session is kept valid by `hq auth refresh` / `hq-auth-refresh` and consumed
  * by the deploy + sync skills.
  */
 
@@ -137,16 +137,16 @@ export function registerAuthCommands(program: Command): void {
   authCmd
     .command("refresh")
     .description(
-      "Refresh the cached Cognito session using the stored refresh token",
+      "Ensure a valid cached Cognito session (refresh only if expiring; no-op if already valid)",
     )
     .action(async () => {
       const result = await refreshCachedSession();
       if (result.refreshed) {
-        console.log(chalk.green("HQ session refreshed"));
+        console.log(chalk.green("HQ session ensured"));
         return;
       }
       console.error(
-        chalk.yellow(`No refresh: ${result.reason ?? "unknown"}`),
+        chalk.yellow(`No valid session: ${result.reason ?? "unknown"}`),
       );
       process.exit(1);
     });

package/src/commands/pkg-install.dispatch.test.ts

@@ -0,0 +1,71 @@
+// @vitest-environment node
+/**
+ * Regression: `hq install <bare-slug>` must resolve through the marketplace
+ * listings transport (the live install path), not the legacy Cognito-gated
+ * registry flow whose backend (/packages, /entitlements) was never deployed.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Command } from 'commander';
+
+// vi.mock is hoisted above imports/consts, so build the mocks via vi.hoisted()
+// to avoid a temporal-dead-zone reference inside the factory.
+const { installPack, sourceMatchesPackPattern } = vi.hoisted(() => ({
+  installPack: vi.fn(async () => {}),
+  // Mirror the real classifier: pack-pattern sources (marketplace:/@scope/git/
+  // path) match; bare slugs do not.
+  sourceMatchesPackPattern: vi.fn(
+    (s: string) =>
+      s.startsWith('marketplace:') ||
+      s.startsWith('@') ||
+      s.startsWith('./') ||
+      s.startsWith('../') ||
+      s.startsWith('/') ||
+      s.endsWith('.git') ||
+      s.startsWith('git@') ||
+      s.startsWith('http://') ||
+      s.startsWith('https://'),
+  ),
+}));
+
+vi.mock('./pack-install.js', () => ({
+  MARKETPLACE_PREFIX: 'marketplace:',
+  installPack,
+  sourceMatchesPackPattern,
+}));
+
+import { registerPackageInstallCommand } from './pkg-install.js';
+
+async function runInstall(...args: string[]): Promise<void> {
+  const program = new Command();
+  program.exitOverride();
+  registerPackageInstallCommand(program);
+  await program.parseAsync(['install', ...args], { from: 'user' });
+}
+
+describe('hq install dispatch — bare slug routes to marketplace', () => {
+  beforeEach(() => {
+    installPack.mockClear();
+    sourceMatchesPackPattern.mockClear();
+  });
+
+  it('routes a bare slug through the marketplace transport', async () => {
+    await runInstall('email-assistant');
+    expect(installPack).toHaveBeenCalledTimes(1);
+    expect(installPack.mock.calls[0][0]).toBe('marketplace:email-assistant');
+  });
+
+  it('preserves a pinned version on a bare slug', async () => {
+    await runInstall('email-assistant@0.1.0');
+    expect(installPack.mock.calls[0][0]).toBe('marketplace:email-assistant@0.1.0');
+  });
+
+  it('passes an explicit marketplace: source through unchanged', async () => {
+    await runInstall('marketplace:tdd');
+    expect(installPack.mock.calls[0][0]).toBe('marketplace:tdd');
+  });
+
+  it('passes a pack-pattern source (npm scope) through unchanged', async () => {
+    await runInstall('@indigoai-us/hq-pack-demo');
+    expect(installPack.mock.calls[0][0]).toBe('@indigoai-us/hq-pack-demo');
+  });
+});

package/src/commands/pkg-install.ts

@@ -28,7 +28,11 @@ import {
 } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { addToRegistry } from '../utils/registry.js';
-import { installPack, sourceMatchesPackPattern } from './pack-install.js';
+import {
+  MARKETPLACE_PREFIX,
+  installPack,
+  sourceMatchesPackPattern,
+} from './pack-install.js';
 
 export function registerPackageInstallCommand(parent: Command): void {
   parent
@@ -52,7 +56,14 @@ export function registerPackageInstallCommand(parent: Command): void {
               followBranch: opts.branch,
             });
           } else {
-            await installPackage(source, opts.company);
+            // Bare slugs: the legacy Cognito-gated registry backend
+            // (/packages, /entitlements) was never deployed, so a bare slug
+            // would fail at registry setup. Resolve it through the marketplace
+            // listings transport — the live install path — instead.
+            await installPack(`${MARKETPLACE_PREFIX}${source}`, {
+              allowHooks: opts.allowHooks,
+              followBranch: opts.branch,
+            });
           }
         } catch (error) {
           console.error(

package/src/utils/cognito-session.machine.test.ts

@@ -6,7 +6,7 @@
  *     authorizer accepts ID tokens and the agent claims
  *     (custom:entityType/custom:entityUid) ride the ID token only
  *   - never refresh or open a browser — sessions re-mint on demand
- *   - treat `hq auth refresh` as a fresh mint instead of "no cached session"
+ *   - treat `hq auth refresh` as a non-interactive ensure-valid-session call
  */
 
 import { describe, it, expect, beforeEach, vi } from "vitest";
@@ -81,34 +81,29 @@ describe("ensureCognitoToken in machine mode", () => {
 });
 
 describe("refreshCachedSession in machine mode", () => {
-  it("re-mints instead of answering 'no cached session'", async () => {
+  it("ensures a healthy machine session via getValidMachineTokens", async () => {
     mocks.isMachineIdentity.mockReturnValue(true);
-    mocks.mintMachineTokens.mockResolvedValue(MACHINE_TOKENS);
-    mocks.loadCachedTokens.mockReturnValue(null);
+    mocks.getValidMachineTokens.mockResolvedValue(MACHINE_TOKENS);
 
     const result = await refreshCachedSession();
 
     expect(result).toEqual({ refreshed: true });
-    expect(mocks.mintMachineTokens).toHaveBeenCalledTimes(1);
+    expect(mocks.getValidMachineTokens).toHaveBeenCalledTimes(1);
+    expect(mocks.mintMachineTokens).not.toHaveBeenCalled();
     expect(mocks.refreshTokens).not.toHaveBeenCalled();
+    expect(mocks.browserLogin).not.toHaveBeenCalled();
+    expect(mocks.loadCachedTokens).not.toHaveBeenCalled();
   });
 
-  it("surfaces the mint error as the reason on failure", async () => {
+  it("surfaces the machine-session error as the reason on failure", async () => {
     mocks.isMachineIdentity.mockReturnValue(true);
-    mocks.mintMachineTokens.mockRejectedValue(new Error("NotAuthorized"));
+    mocks.getValidMachineTokens.mockRejectedValue(new Error("NotAuthorized"));
 
     const result = await refreshCachedSession();
 
     expect(result.refreshed).toBe(false);
     expect(result.reason).toContain("NotAuthorized");
-  });
-
-  it("keeps the human refresh path unchanged", async () => {
-    mocks.isMachineIdentity.mockReturnValue(false);
-    mocks.loadCachedTokens.mockReturnValue(null);
-
-    const result = await refreshCachedSession();
-
-    expect(result).toEqual({ refreshed: false, reason: "no cached session" });
+    expect(mocks.refreshTokens).not.toHaveBeenCalled();
+    expect(mocks.browserLogin).not.toHaveBeenCalled();
   });
 });

package/src/utils/cognito-session.refresh.test.ts

@@ -0,0 +1,84 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  isMachineIdentity: vi.fn(),
+  getValidMachineTokens: vi.fn(),
+  mintMachineTokens: vi.fn(),
+  loadCachedTokens: vi.fn(),
+  refreshTokens: vi.fn(),
+  browserLogin: vi.fn(),
+  isExpiring: vi.fn(),
+}));
+
+vi.mock("@indigoai-us/hq-cloud", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@indigoai-us/hq-cloud")>();
+  return { ...actual, ...mocks };
+});
+
+import { refreshCachedSession } from "./cognito-session.js";
+
+const HUMAN_TOKENS = {
+  accessToken: "human-access-token",
+  idToken: "human-id-token",
+  refreshToken: "human-refresh-token",
+  expiresAt: Date.now() + 3600_000,
+  tokenType: "Bearer" as const,
+};
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+describe("refreshCachedSession in human mode", () => {
+  it("returns no cached session without attempting a refresh", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue(null);
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: false, reason: "no cached session" });
+    expect(mocks.refreshTokens).not.toHaveBeenCalled();
+  });
+
+  it("returns success on a healthy cached session without refreshing", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.isExpiring.mockReturnValue(false);
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: true });
+    expect(mocks.isExpiring).toHaveBeenCalledWith(HUMAN_TOKENS, 120);
+    expect(mocks.refreshTokens).not.toHaveBeenCalled();
+  });
+
+  it("refreshes once when the cached session is expiring", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.isExpiring.mockReturnValue(true);
+    mocks.refreshTokens.mockResolvedValue({
+      ...HUMAN_TOKENS,
+      accessToken: "refreshed-access-token",
+    });
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: true });
+    expect(mocks.refreshTokens).toHaveBeenCalledTimes(1);
+    expect(mocks.refreshTokens).toHaveBeenCalledWith(
+      expect.any(Object),
+      HUMAN_TOKENS.refreshToken,
+    );
+  });
+
+  it("surfaces refresh failures as a non-throwing result", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.isExpiring.mockReturnValue(true);
+    mocks.refreshTokens.mockRejectedValue(new Error("token expired"));
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: false, reason: "token expired" });
+  });
+});

package/src/utils/cognito-session.ts

@@ -32,7 +32,6 @@ import {
   detectHqCoreVersion,
   isMachineIdentity,
   getValidMachineTokens,
-  mintMachineTokens,
   type CognitoAuthConfig,
   type ClientInfo,
   type VaultServiceConfig,
@@ -399,20 +398,22 @@ export function buildVaultConfig(authToken: string): VaultServiceConfig {
 }
 
 /**
- * Refresh the cached Cognito session once and return the result. Used by
- * `hq auth refresh` and the `hq-auth-refresh` bin. Never opens a browser —
- * if no cached tokens exist or the refresh fails, returns `refreshed: false`
- * with a reason string so the caller can decide what to do.
+ * Ensure a valid cached Cognito session exists right now, non-interactively,
+ * and return the result. Used by `hq auth refresh` and the `hq-auth-refresh`
+ * bin. `refreshed: true` means a valid session is ensured now from a healthy
+ * cache hit, a token refresh, or a machine-token mint. `refreshed: false`
+ * means no valid session could be ensured non-interactively; the caller gets a
+ * reason string and can decide what to do next. Never opens a browser.
  */
 export async function refreshCachedSession(): Promise<{
   refreshed: boolean;
   reason?: string;
 }> {
-  // Machine identities have no refresh token — a "refresh" is a fresh mint
-  // from the long-lived machine creds.
+  // Machine identities have no refresh token; ensure a valid cached machine
+  // session without forcing a re-mint when the cache is already healthy.
   if (isMachineIdentity()) {
     try {
-      await mintMachineTokens(DEFAULT_COGNITO);
+      await getValidMachineTokens(DEFAULT_COGNITO);
       return { refreshed: true };
     } catch (err) {
       return {
@@ -426,6 +427,11 @@ export async function refreshCachedSession(): Promise<{
   if (!cached) {
     return { refreshed: false, reason: "no cached session" };
   }
+
+  if (!isExpiring(cached, 120)) {
+    return { refreshed: true };
+  }
+
   try {
     await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
     return { refreshed: true };