@indigoai-us/hq-cloud 6.12.3 → 6.12.5

package/src/cli/share.ts

@@ -64,6 +64,7 @@ import {
   readShortMachineId,
 } from "../lib/conflict-file.js";
 import { appendConflictEntry } from "../lib/conflict-index.js";
+import { isCloudAuthoritative } from "../lib/cloud-authoritative.js";
 
 /**
  * Push-side fresh-collision convergence probe.
@@ -1260,6 +1261,16 @@ async function executeUploads(
       }
 
       if ((localChanged && remoteChanged) || isFreshCollision) {
+        // Cloud-authoritative paths (server-regenerated: company-brief.md,
+        // board.json, ontology/ signals/ sources/) are PULL-WINS. Never push the
+        // local copy over the server-owned version and never mint a `.conflict-`
+        // mirror — the pull leg overwrites local from cloud. Declining here is
+        // what stops the per-sync conflict-mirror loop on these files.
+        if (isCloudAuthoritative(relativePath)) {
+          run.emit({ type: "reconciled", path: relativePath, direction: "push" });
+          counters.filesSkipped++;
+          return;
+        }
         conflictPaths.push(relativePath);
 
         const resolution = await resolveConflictSerialized({

package/src/cli/sync.test.ts

@@ -451,6 +451,58 @@ describe("sync", () => {
     expect(litter).toHaveLength(1);
   });
 
+  it("cloud-authoritative file is PULL-WINS on conflict: overwrites local, no mirror, no false-stamp", async () => {
+    // company-brief.md is server-regenerated (gardener), so a divergence is not
+    // a real conflict — the cloud copy wins. Even under --on-conflict keep, the
+    // conflict path must short-circuit to a plain overwrite: NO `.conflict-`
+    // mirror (the loop) and NO journal stamp of the remote etag over divergent
+    // local content (Finding B). Contrast the docs/handoff.md test above, which
+    // (correctly) keeps local + mirrors for a client-owned file.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, "company-brief.md"), "local richer brief");
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "company-brief.md", size: 17, lastModified: new Date(), etag: '"newbrief"' },
+    ]);
+    // Default downloadFile mock writes "mock file content" — the cloud copy.
+
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "company-brief.md": {
+            hash: "stale-hash",
+            size: 18,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    const result = await sync({
+      company: "acme",
+      onConflict: "keep",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // Cloud wins: not counted as a conflict; local overwritten with the cloud copy.
+    expect(result.conflicts).toBe(0);
+    expect(result.conflictPaths).toEqual([]);
+    expect(
+      fs.readFileSync(path.join(companyRoot, "company-brief.md"), "utf-8"),
+    ).toBe("mock file content");
+    // No conflict mirror littered.
+    const litter = fs
+      .readdirSync(companyRoot)
+      .filter((f) => f.includes(".conflict-"));
+    expect(litter).toHaveLength(0);
+  });
+
   it("pre-primes new-file GET presigns before per-file created-by HEADs (avoids the presign-burst breaker trip)", async () => {
     vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
       { key: "alpha.md", size: 10, lastModified: new Date(), etag: '"a1"' },

package/src/cli/sync.ts

@@ -69,6 +69,7 @@ import {
   readShortMachineId,
 } from "../lib/conflict-file.js";
 import { appendConflictEntry } from "../lib/conflict-index.js";
+import { isCloudAuthoritative } from "../lib/cloud-authoritative.js";
 import { reindex } from "./reindex.js";
 import { withOperationLock } from "../operation-lock.js";
 import {
@@ -1048,6 +1049,19 @@ async function executeConflictItem(
 ): Promise<SyncResult | null> {
   const { remoteFile, localPath } = item;
 
+  // Cloud-authoritative paths (server-regenerated: company-brief.md, board.json,
+  // ontology/ signals/ sources/) are PULL-WINS: the cloud copy is the source of
+  // truth, so a divergence here is not a real conflict. Resolve it as a normal
+  // overwrite-from-cloud — queue a plain download (which stamps the journal with
+  // the REMOTE hash/etag) and skip the conflict path entirely. This removes both
+  // the `.conflict-` mirror loop AND the journal false-stamp (remote etag over
+  // divergent local content) that the keep path produced for these files.
+  if (isCloudAuthoritative(path.relative(run.hqRoot, localPath))) {
+    downloadItems.push({ action: "download", remoteFile, localPath, isNew: false });
+    run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
+    return null;
+  }
+
   await refreshRunContextIfExpiring(run);
 
   const detectedAt = new Date().toISOString();

package/src/cognito-auth.ts

@@ -299,15 +299,63 @@ interface InitiateAuthResponse {
   message?: string;
 }
 
+/** Tunables for the machine-mint retry-on-throttle loop. Defaults are the
+ *  production values; tests pass `baseDelayMs: 0` to retry without waiting. */
+export interface MintRetryOptions {
+  /** Retries AFTER the first attempt (so total attempts = maxRetries + 1). */
+  maxRetries?: number;
+  /** Backoff for the first retry in ms; doubles each subsequent attempt. */
+  baseDelayMs?: number;
+  /** Ceiling for any single backoff sleep. */
+  maxDelayMs?: number;
+}
+
+const DEFAULT_MINT_RETRY: Required<MintRetryOptions> = {
+  maxRetries: 5,
+  baseDelayMs: 250,
+  maxDelayMs: 5000,
+};
+
+/**
+ * Cognito signals a per-user mint throttle as `TooManyRequestsException` — and
+ * (observed in prod on the Infraredi agent box, 2026-06-26) returns it under
+ * HTTP 400, not 429. Match the typed error first and the status second so both
+ * shapes are treated as transient throttles to retry, not hard auth failures.
+ */
+function isCognitoThrottle(status: number, type: string | undefined): boolean {
+  if (typeof type === "string" && type.includes("TooManyRequests")) return true;
+  return status === 429;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Full-jitter exponential backoff: a random delay in
+ *  [0, min(maxDelayMs, baseDelayMs * 2^attempt)]. Jitter de-syncs a concurrent
+ *  burst of retries so they don't re-collide on the same per-user limit. */
+function backoffDelayMs(
+  attempt: number,
+  opts: Required<MintRetryOptions>,
+): number {
+  const ceiling = Math.min(opts.maxDelayMs, opts.baseDelayMs * 2 ** attempt);
+  return Math.floor(Math.random() * (ceiling + 1));
+}
+
 /**
  * Mint a fresh session for the machine identity via USER_PASSWORD_AUTH
  * against the Cognito IDP endpoint (plain unsigned HTTP — no AWS SDK
  * dependency). Caches BOTH tokens with correct field semantics and returns
  * them.
+ *
+ * Retries on a `TooManyRequestsException` throttle with exponential backoff +
+ * full jitter (transient, per-user rate limit); every other non-OK response
+ * (bad creds, disabled flow) is a hard error surfaced immediately.
  */
 export async function mintMachineTokens(
   config: CognitoAuthConfig,
   creds?: MachineCreds,
+  retry?: MintRetryOptions,
 ): Promise<CognitoTokens> {
   const machineCreds = creds ?? loadMachineCreds();
   if (!machineCreds) {
@@ -320,68 +368,131 @@ export async function mintMachineTokens(
   // which the CLI's default (browser) client may not.
   const region = machineCreds.region ?? config.region;
   const clientId = machineCreds.clientId ?? config.clientId;
-  const res = await fetch(
-    `https://cognito-idp.${region}.amazonaws.com/`,
-    {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/x-amz-json-1.1",
-        "X-Amz-Target": "AWSCognitoIdentityProviderService.InitiateAuth",
-      },
-      body: JSON.stringify({
-        AuthFlow: "USER_PASSWORD_AUTH",
-        ClientId: clientId,
-        AuthParameters: {
-          USERNAME: machineCreds.username,
-          PASSWORD: machineCreds.secret,
+  const retryOpts: Required<MintRetryOptions> = { ...DEFAULT_MINT_RETRY, ...retry };
+
+  let lastError: CognitoAuthError | null = null;
+  for (let attempt = 0; attempt <= retryOpts.maxRetries; attempt++) {
+    const res = await fetch(
+      `https://cognito-idp.${region}.amazonaws.com/`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-amz-json-1.1",
+          "X-Amz-Target": "AWSCognitoIdentityProviderService.InitiateAuth",
         },
-      }),
-    },
-  );
-  const data = (await res.json().catch(() => ({}))) as InitiateAuthResponse;
-  if (!res.ok) {
-    throw new CognitoAuthError(
-      `Machine token mint failed (${res.status}): ${data.__type ?? ""} ${data.message ?? ""}`.trim(),
-    );
-  }
-  const result = data.AuthenticationResult;
-  if (!result?.AccessToken || !result?.IdToken) {
-    throw new CognitoAuthError(
-      `Machine token mint returned no tokens${data.ChallengeName ? ` (challenge: ${data.ChallengeName})` : ""}`,
+        body: JSON.stringify({
+          AuthFlow: "USER_PASSWORD_AUTH",
+          ClientId: clientId,
+          AuthParameters: {
+            USERNAME: machineCreds.username,
+            PASSWORD: machineCreds.secret,
+          },
+        }),
+      },
     );
+    const data = (await res.json().catch(() => ({}))) as InitiateAuthResponse;
+    if (!res.ok) {
+      const err = new CognitoAuthError(
+        `Machine token mint failed (${res.status}): ${data.__type ?? ""} ${data.message ?? ""}`.trim(),
+      );
+      // Back off and retry a transient per-user throttle rather than failing
+      // the whole sync run; surface every other auth error immediately.
+      if (
+        isCognitoThrottle(res.status, data.__type) &&
+        attempt < retryOpts.maxRetries
+      ) {
+        lastError = err;
+        await sleep(backoffDelayMs(attempt, retryOpts));
+        continue;
+      }
+      throw err;
+    }
+    const result = data.AuthenticationResult;
+    if (!result?.AccessToken || !result?.IdToken) {
+      throw new CognitoAuthError(
+        `Machine token mint returned no tokens${data.ChallengeName ? ` (challenge: ${data.ChallengeName})` : ""}`,
+      );
+    }
+    const tokens: CognitoTokens = {
+      accessToken: result.AccessToken,
+      idToken: result.IdToken,
+      // Machine creds never expire — expiry is handled by re-minting, so the
+      // refresh token (when Cognito returns one at all) is never exercised.
+      refreshToken: result.RefreshToken ?? "",
+      expiresAt: Date.now() + (result.ExpiresIn ?? 3600) * 1000,
+      tokenType: "Bearer",
+    };
+    saveCachedTokens(tokens);
+    return tokens;
   }
-  const tokens: CognitoTokens = {
-    accessToken: result.AccessToken,
-    idToken: result.IdToken,
-    // Machine creds never expire — expiry is handled by re-minting, so the
-    // refresh token (when Cognito returns one at all) is never exercised.
-    refreshToken: result.RefreshToken ?? "",
-    expiresAt: Date.now() + (result.ExpiresIn ?? 3600) * 1000,
-    tokenType: "Bearer",
-  };
-  saveCachedTokens(tokens);
-  return tokens;
+  // Unreachable in practice — the final throttled attempt throws inside the
+  // loop — but keeps the function total for the type checker.
+  throw lastError ?? new CognitoAuthError("Machine token mint failed: throttled");
 }
 
+// In-process machine-token memo (sync-runner mint-storm fix).
+//
+// `getValidAccessToken` runs on EVERY vault request, and a busy sync fans out
+// many requests concurrently (presign primes, STS vend, the per-file tombstone
+// HEAD verifies). The on-disk cache alone does NOT bound mints: at run start
+// the disk token is often within its expiry buffer, so N concurrent callers
+// each independently observe "expiring" and each fire USER_PASSWORD_AUTH —
+// bursting Cognito's per-user limit (TooManyRequestsException) on large vaults
+// (observed: 56 throttled mints over 314 files on the Infraredi box, 2026-06-26).
+//
+// This module-level memo makes mints O(1) per process:
+//   - hot path: a live in-memory token serves every later request with no disk
+//     read and no network — a 300-file sync does ONE mint, not one-per-request;
+//   - single-flight: a concurrent burst of cache-misses (the run-start fan-out)
+//     collapses onto a single in-flight mint instead of one mint per caller.
+// One machine identity per process is assumed (true for agent boxes), so a
+// single slot suffices.
+let inProcessMachineTokens: CognitoTokens | null = null;
+let inFlightMachineMint: Promise<CognitoTokens> | null = null;
+
 /**
  * Return a valid (non-expiring) machine session, re-minting on demand.
- * Cache-hit path never touches the network.
+ * Cache-hit path never touches the network — and after the first mint, the
+ * in-process memo serves every subsequent request for the life of the token.
  */
 export async function getValidMachineTokens(
   config: CognitoAuthConfig,
 ): Promise<CognitoTokens> {
-  const machineCreds = loadMachineCreds();
-  const cached = loadCachedTokens();
-  if (machineCreds && cached && !isExpiring(cached, 120)) {
-    // Compare against the client we'd actually mint with (creds-file clientId
-    // wins over config), and require the cached ID token to prove this exact
-    // agent identity. Opaque/missing/human-shaped claims are treated as stale.
-    const expectedClientId = machineCreds.clientId ?? config.clientId;
-    if (cachedTokensMatchMachineIdentity(cached, machineCreds, expectedClientId)) {
-      return cached;
+  // Hot path: a live in-memory token serves every request after the first.
+  if (inProcessMachineTokens && !isExpiring(inProcessMachineTokens, 120)) {
+    return inProcessMachineTokens;
+  }
+  // Single-flight: collapse a concurrent burst of misses onto one resolution.
+  // The assignment below completes before the first `await` yields, so sibling
+  // callers in the same tick see the in-flight promise and reuse it.
+  if (inFlightMachineMint) return inFlightMachineMint;
+
+  inFlightMachineMint = (async () => {
+    const machineCreds = loadMachineCreds();
+    const cached = loadCachedTokens();
+    if (machineCreds && cached && !isExpiring(cached, 120)) {
+      // Compare against the client we'd actually mint with (creds-file clientId
+      // wins over config), and require the cached ID token to prove this exact
+      // agent identity. Opaque/missing/human-shaped claims are treated as stale.
+      const expectedClientId = machineCreds.clientId ?? config.clientId;
+      if (
+        cachedTokensMatchMachineIdentity(cached, machineCreds, expectedClientId)
+      ) {
+        return cached;
+      }
     }
+    return mintMachineTokens(config, machineCreds ?? undefined);
+  })();
+
+  try {
+    const tokens = await inFlightMachineMint;
+    inProcessMachineTokens = tokens;
+    return tokens;
+  } finally {
+    // Clear on both success and failure: a rejected mint must not wedge later
+    // calls onto a permanently-failed promise.
+    inFlightMachineMint = null;
   }
-  return mintMachineTokens(config, machineCreds ?? undefined);
 }
 
 // ---------------------------------------------------------------------------

package/src/lib/cloud-authoritative.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { isCloudAuthoritative } from "./cloud-authoritative.js";
+
+describe("isCloudAuthoritative", () => {
+  it("matches server-regenerated root files (both path forms)", () => {
+    for (const p of [
+      "companies/indigo/company-brief.md",
+      "company-brief.md",
+      "companies/acme/board.json",
+      "board.json",
+    ]) {
+      expect(isCloudAuthoritative(p)).toBe(true);
+    }
+  });
+
+  it("matches the pipeline-authored dirs", () => {
+    for (const p of [
+      "companies/indigo/ontology/entities/concept/grok.md",
+      "ontology/entities/person/x.md",
+      "companies/indigo/signals/slack-dm/action_item/a.md",
+      "signals/decision/b.md",
+      "companies/indigo/sources/slack/T1-2.md",
+      "sources/meetings/m.md",
+    ]) {
+      expect(isCloudAuthoritative(p)).toBe(true);
+    }
+  });
+
+  it("does NOT match client-owned files", () => {
+    for (const p of [
+      "companies/indigo/skills/work-mesh/SKILL.md",
+      "companies/indigo/projects/company-agents/release/index.html",
+      "companies/indigo/workers/hq-notify/emails/notice.template.html",
+      "companies/indigo/knowledge/readme.md",
+      "company-brief.md.conflict-2026-06-18T00-00-00Z-501bc8.md", // a mirror, not the brief
+      "docs/handoff.md",
+    ]) {
+      expect(isCloudAuthoritative(p)).toBe(false);
+    }
+  });
+
+  it("normalizes windows separators", () => {
+    expect(isCloudAuthoritative("companies\\indigo\\ontology\\entities\\x.md")).toBe(true);
+  });
+});

package/src/lib/cloud-authoritative.ts

@@ -0,0 +1,59 @@
+/**
+ * Cloud-authoritative vault paths — files the SERVER regenerates and owns, so
+ * on a sync conflict the cloud version always wins (pull-wins) and NO
+ * `.conflict-` mirror is minted.
+ *
+ * Why this exists
+ * ---------------
+ * Some vault files are written/regenerated server-side on a schedule, not by
+ * the client:
+ *   - `company-brief.md`  — rewritten by the ontology gardener's brief-generator
+ *                           on every run.
+ *   - `board.json`        — rewritten by board automation.
+ *   - `ontology/**`, `signals/**`, `sources/**` — the gardener / sources+signals
+ *                           pipeline are the sole authors; clients only consume.
+ *
+ * A client that also holds these locally diverges from the server copy on
+ * essentially every sync. Under `--on-conflict keep` (what outposts run) that
+ * produced two compounding bugs:
+ *   1. CONFLICT LOOP — each sync minted a fresh `<file>.conflict-<ts>-<machine>`
+ *      mirror that was never cleaned up (e.g. ~50 `company-brief.md.conflict-*`
+ *      piled up on an outpost over a few days).
+ *   2. SILENT DRIFT — the keep path stamped the journal with the REMOTE etag
+ *      while leaving the divergent LOCAL content in place, so the journal
+ *      reported "in sync" forever and the file never reconciled.
+ *
+ * Treating these paths as cloud-authoritative resolves both: the conflict path
+ * short-circuits to a normal overwrite-from-cloud (correct journal stamp, no
+ * mirror), because for a server-owned file the cloud copy is the truth.
+ *
+ * Extending
+ * ---------
+ * Add a pattern to {@link CLOUD_AUTHORITATIVE_PATTERNS}. Patterns are matched
+ * against the VAULT-RELATIVE path (a leading `companies/<slug>/` is stripped
+ * first), so both call sites — the pull leg (hqRoot-relative
+ * `companies/<slug>/…`) and the push leg (company-relative `…`) — work.
+ */
+
+/** Vault-relative patterns for server-owned, cloud-wins files. */
+export const CLOUD_AUTHORITATIVE_PATTERNS: readonly RegExp[] = [
+  /^company-brief\.md$/,
+  /^board\.json$/,
+  /^ontology\//,
+  /^signals\//,
+  /^sources\//,
+];
+
+/**
+ * True iff `relPath` is a server-regenerated, cloud-authoritative vault file.
+ * Accepts either an hqRoot-relative path (`companies/<slug>/…`) or a
+ * vault-relative path (`…`); Windows separators are normalized.
+ */
+export function isCloudAuthoritative(relPath: string): boolean {
+  const vaultRel = relPath
+    .split("\\")
+    .join("/")
+    .replace(/^\.?\//, "")
+    .replace(/^companies\/[^/]+\//, "");
+  return CLOUD_AUTHORITATIVE_PATTERNS.some((re) => re.test(vaultRel));
+}

package/src/machine-auth.test.ts

@@ -355,6 +355,143 @@ describe("getValidMachineTokens", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Regression: constant token mints over N files (sync-runner mint storm)
+// ---------------------------------------------------------------------------
+//
+// `getValidAccessToken` (→ getValidMachineTokens) is invoked on EVERY vault
+// request a sync makes, including the per-file tombstone HEAD verifies. The
+// 2026-06-26 prod incident was 56 throttled USER_PASSWORD_AUTH mints over 314
+// files on one box: with no in-process memo + single-flight, mints scaled with
+// request count and tripped Cognito's per-user limit. These lock the invariant
+// that mints are O(1) per process, independent of N.
+
+describe("regression: constant mints regardless of file count", () => {
+  it.each([10, 300])(
+    "performs exactly ONE token mint across %i sequential file-verify requests",
+    async (n) => {
+      writeCreds();
+      const { fetchMock } = stubMintFetch();
+      const { getValidMachineTokens } = await importModule();
+
+      for (let i = 0; i < n; i++) {
+        await getValidMachineTokens(CONFIG);
+      }
+
+      // One mint for N requests — NOT proportional to N. The first call mints;
+      // every later call is served by the in-process memo (no network).
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    },
+  );
+
+  it.each([10, 300])(
+    "collapses a concurrent burst of %i requests onto a SINGLE mint (single-flight)",
+    async (n) => {
+      writeCreds();
+      const { fetchMock } = stubMintFetch();
+      const { getValidMachineTokens } = await importModule();
+
+      // Fire all N at once, as the run-start fan-out does. Without single-flight
+      // every concurrent miss would mint and burst the per-user limit.
+      const results = await Promise.all(
+        Array.from({ length: n }, () => getValidMachineTokens(CONFIG)),
+      );
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      // All callers observe the same token.
+      for (const r of results) expect(r).toEqual(results[0]);
+
+      // Follow-up sequential requests stay on the memo — still one mint total.
+      await getValidMachineTokens(CONFIG);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    },
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Throttle handling: retry TooManyRequestsException with backoff
+// ---------------------------------------------------------------------------
+
+describe("mintMachineTokens throttle retry", () => {
+  /** Fetch mock that throttles (HTTP 400 + TooManyRequestsException, the shape
+   *  Cognito actually returns) for the first `throttleCount` calls, then 200s. */
+  function stubThrottleThenSuccess(throttleCount: number) {
+    let call = 0;
+    const fetchMock = vi.fn(async () => {
+      call++;
+      if (call <= throttleCount) {
+        return new Response(
+          JSON.stringify({
+            __type: "TooManyRequestsException",
+            message: "Too many requests",
+          }),
+          { status: 400 },
+        );
+      }
+      return new Response(
+        JSON.stringify({
+          AuthenticationResult: {
+            AccessToken: fakeJwt({ token_use: "access", client_id: CONFIG.clientId }),
+            IdToken: fakeJwt({ token_use: "id" }),
+            ExpiresIn: 3600,
+          },
+        }),
+        { status: 200 },
+      );
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    return fetchMock;
+  }
+
+  it("retries a throttled mint with backoff and eventually succeeds", async () => {
+    writeCreds();
+    const fetchMock = stubThrottleThenSuccess(2);
+    const { mintMachineTokens } = await importModule();
+
+    // baseDelayMs: 0 keeps the test instant — jitter * 0 == 0.
+    const tokens = await mintMachineTokens(CONFIG, undefined, {
+      baseDelayMs: 0,
+      maxRetries: 5,
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(3); // 2 throttles + 1 success
+    const idClaims = JSON.parse(
+      Buffer.from(tokens.idToken.split(".")[1], "base64url").toString(),
+    );
+    expect(idClaims.token_use).toBe("id");
+  });
+
+  it("gives up after maxRetries and throws when throttling never clears", async () => {
+    writeCreds();
+    const fetchMock = stubThrottleThenSuccess(Number.POSITIVE_INFINITY);
+    const { mintMachineTokens, CognitoAuthError } = await importModule();
+
+    await expect(
+      mintMachineTokens(CONFIG, undefined, { baseDelayMs: 0, maxRetries: 2 }),
+    ).rejects.toBeInstanceOf(CognitoAuthError);
+
+    // maxRetries: 2 → 3 total attempts (initial + 2 retries).
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+
+  it("does NOT retry a non-throttle auth failure (bad creds fail fast)", async () => {
+    writeCreds();
+    const fetchMock = vi.fn(async () =>
+      new Response(
+        JSON.stringify({ __type: "NotAuthorizedException", message: "nope" }),
+        { status: 400 },
+      ),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const { mintMachineTokens, CognitoAuthError } = await importModule();
+
+    await expect(
+      mintMachineTokens(CONFIG, undefined, { baseDelayMs: 0, maxRetries: 5 }),
+    ).rejects.toBeInstanceOf(CognitoAuthError);
+    expect(fetchMock).toHaveBeenCalledTimes(1); // no retries
+  });
+});
+
 // ---------------------------------------------------------------------------
 // getValidAccessToken — machine-mode short circuit
 // ---------------------------------------------------------------------------