@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/cognito-auth.ts

@@ -1,1422 +0,0 @@
-/**
- * Cognito browser-OAuth helper (VLT-9).
- *
- * Drives the Cognito Hosted UI authorization-code + PKCE flow for the
- * vault-service User Pool. Used by the CLI (`hq login`, `create-hq`) to
- * obtain a JWT that is then passed to the vault-service API as
- * `Authorization: Bearer <accessToken>`.
- *
- * Why PKCE: the CLI is a public client (no secret), so we use PKCE per
- * RFC 7636 to prove that the same process that started the auth request
- * is the one exchanging the code for tokens.
- *
- * Why a localhost callback: Cognito allows `http://localhost:*` as a
- * redirect URI specifically for native/CLI apps (RFC 8252 §7). We spin
- * up a one-shot HTTP server on the chosen port, capture exactly one
- * callback, then close it.
- */
-
-import * as crypto from "crypto";
-import * as fs from "fs";
-import * as http from "http";
-import * as path from "path";
-import * as os from "os";
-import open from "open";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface CognitoAuthConfig {
-  /** AWS region the User Pool lives in (e.g. "us-east-1"). */
-  region: string;
-  /** Cognito User Pool Domain prefix (e.g. "vault-indigo-hq-dev"). */
-  userPoolDomain: string;
-  /** App Client ID (e.g. "7r7an9keh0u6hlsvepl74tvqb0"). */
-  clientId: string;
-  /** Loopback callback port. Defaults to 3000. */
-  port?: number;
-  /** OAuth scopes. Defaults to ["openid", "email", "profile"]. */
-  scopes?: string[];
-  /**
-   * Force a federated IdP (e.g. "Google"). When set, the Hosted UI IdP picker
-   * is bypassed and Cognito redirects straight to the provider. When omitted,
-   * Cognito shows its default picker.
-   */
-  identityProvider?: string;
-  /**
-   * OAuth `prompt` param (e.g. "select_account"). Only meaningful when the IdP
-   * honors it — Google uses it to force account re-selection.
-   */
-  prompt?: string;
-}
-
-export interface CognitoTokens {
-  accessToken: string;
-  idToken: string;
-  refreshToken: string;
-  /** Epoch milliseconds when the access token expires. Writers MUST emit a number. Readers accept ISO 8601 strings for backward compatibility with pre-migration token files. */
-  expiresAt: string | number;
-  tokenType: "Bearer";
-}
-
-/** Returned when an interactive login is needed but stdin/browser is unavailable. */
-export class CognitoAuthError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "CognitoAuthError";
-  }
-}
-
-/**
- * A failed refresh attempt with enough classification for callers to decide
- * whether the cached session is still worth preserving. Network/5xx/429
- * failures remain recoverable; an invalid/expired refresh token means the
- * stored session can no longer make progress and should be cleared.
- */
-export class CognitoRefreshError extends CognitoAuthError {
-  public readonly requiresReauth: boolean;
-  public readonly statusCode?: number;
-  public readonly sessionFingerprint?: string;
-
-  constructor(
-    message: string,
-    requiresReauth: boolean,
-    statusCode?: number,
-    sessionFingerprint?: string,
-  ) {
-    super(message);
-    this.name = "CognitoRefreshError";
-    this.requiresReauth = requiresReauth;
-    this.statusCode = statusCode;
-    this.sessionFingerprint = sessionFingerprint;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Token cache (~/.hq/cognito-tokens.json)
-// ---------------------------------------------------------------------------
-
-/**
- * Root for hq CLI state: the token cache and its refresh lock.
- *
- * `HQ_STATE_DIR` overrides it, mirroring the existing `HQ_MACHINE_CREDS_FILE`
- * override for the creds path. Before this existed the location was
- * `os.homedir()/.hq` with NO escape hatch, which made every auth path — machine
- * identity included — require a writable HOME. A child job running with a
- * read-only HQ state directory therefore died on a *cache write* before it ever
- * reached the network:
- *
- *     EACCES: permission denied, open '…/.hq/cognito-tokens.json.lock.candidate.…'
- *
- * Pointing HQ_STATE_DIR at a writable tmpfs lets such a job authenticate while
- * leaving the credentials themselves wherever they are.
- *
- * Resolved per call (not once at import) so a caller can set it during startup
- * and so tests can exercise both branches.
- */
-export function hqStateDir(): string {
-  const override = process.env.HQ_STATE_DIR?.trim();
-  return override !== undefined && override.length > 0
-    ? override
-    : path.join(os.homedir(), ".hq");
-}
-
-/** The Cognito token cache file inside {@link hqStateDir}. */
-export function tokenCacheFile(): string {
-  return path.join(hqStateDir(), "cognito-tokens.json");
-}
-
-function tokenInvalidationPrefix(): string {
-  return `${tokenCacheFile()}.invalid.`;
-}
-
-/** Stable, non-secret identity for one access-token generation. */
-export function accessTokenFingerprint(accessToken: string): string {
-  return crypto.createHash("sha256").update(accessToken).digest("hex");
-}
-
-function invalidationPathForFingerprint(fingerprint: string): string | null {
-  return /^[a-f0-9]{64}$/i.test(fingerprint)
-    ? `${tokenInvalidationPrefix()}${fingerprint.toLowerCase()}`
-    : null;
-}
-
-/**
- * Mark only the rejected token generation unusable. Automatic auth failures
- * must not unlink the shared cache: another process may have completed a
- * refresh or login after the failing request started.
- */
-export function invalidateCachedTokensByFingerprint(
-  fingerprint: string | undefined,
-): void {
-  if (!fingerprint) return;
-  const invalidationPath = invalidationPathForFingerprint(fingerprint);
-  if (!invalidationPath) return;
-  if (!fs.existsSync(hqStateDir())) {
-    fs.mkdirSync(hqStateDir(), { recursive: true, mode: 0o700 });
-  }
-  try {
-    fs.writeFileSync(invalidationPath, "", { mode: 0o600, flag: "wx" });
-  } catch (err) {
-    const code =
-      err && typeof err === "object" && "code" in err
-        ? (err as { code?: string }).code
-        : undefined;
-    if (code !== "EEXIST") throw err;
-  }
-}
-
-function tokenIsInvalidated(accessToken: string): boolean {
-  const marker = invalidationPathForFingerprint(
-    accessTokenFingerprint(accessToken),
-  );
-  return marker !== null && fs.existsSync(marker);
-}
-
-/**
- * True for the errno family a read-only / not-writable state directory raises.
- *
- * A job whose HQ state dir is mounted read-only (container, restricted
- * sandbox, root-owned dir entered as another user) must still be able to
- * AUTHENTICATE — persisting the session is an optimisation, not a requirement.
- */
-function isNotWritableError(err: unknown): boolean {
-  const code = (err as NodeJS.ErrnoException | undefined)?.code;
-  return code === "EROFS" || code === "EACCES" || code === "EPERM";
-}
-
-/**
- * Process-local fallback used when the state directory cannot be written.
- *
- * Keeps the cache semantics intact for the life of the process instead of
- * failing the call outright. It is deliberately NOT a substitute for the shared
- * on-disk cache: a fresh subprocess starts empty and re-mints.
- */
-let inMemoryCachedTokens: CognitoTokens | null = null;
-
-export function loadCachedTokens(): CognitoTokens | null {
-  if (!fs.existsSync(tokenCacheFile())) return inMemoryCachedTokens;
-  try {
-    const raw = fs.readFileSync(tokenCacheFile(), "utf-8");
-    const tokens = JSON.parse(raw) as CognitoTokens;
-    if (!tokens.accessToken || tokenIsInvalidated(tokens.accessToken)) return null;
-    return tokens;
-  } catch {
-    return inMemoryCachedTokens;
-  }
-}
-
-export function saveCachedTokens(tokens: CognitoTokens): void {
-  // Remember in-process FIRST: whatever happens to the disk write below, this
-  // process must not lose a session it already successfully minted.
-  inMemoryCachedTokens = tokens;
-  try {
-    if (!fs.existsSync(hqStateDir())) {
-      fs.mkdirSync(hqStateDir(), { recursive: true, mode: 0o700 });
-    }
-    const invalidationPath = invalidationPathForFingerprint(
-      accessTokenFingerprint(tokens.accessToken),
-    );
-    if (invalidationPath && fs.existsSync(invalidationPath)) {
-      fs.unlinkSync(invalidationPath);
-    }
-    const tmpPath = path.join(
-      hqStateDir(),
-      `.cognito-tokens.json.tmp.${process.pid}`,
-    );
-    fs.writeFileSync(tmpPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
-    fs.renameSync(tmpPath, tokenCacheFile());
-  } catch (err) {
-    // A read-only state dir degrades to the in-memory cache. Any other error
-    // (disk full, corrupt path) is still a real fault and propagates.
-    if (!isNotWritableError(err)) throw err;
-  }
-}
-
-export function clearCachedTokens(): void {
-  if (fs.existsSync(tokenCacheFile())) fs.unlinkSync(tokenCacheFile());
-  if (!fs.existsSync(hqStateDir())) return;
-  const markerPrefix = `${path.basename(tokenCacheFile())}.invalid.`;
-  for (const entry of fs.readdirSync(hqStateDir())) {
-    if (entry.startsWith(markerPrefix)) {
-      fs.unlinkSync(path.join(hqStateDir(), entry));
-    }
-  }
-}
-
-/** Advisory lockfile guarding the read→refresh→save cycle (see withRefreshLock). */
-function refreshLockFile(): string {
-  return `${tokenCacheFile()}.lock`;
-}
-
-/** Thrown when the refresh lock can't be acquired within the deadline. */
-export class RefreshLockTimeoutError extends Error {
-  constructor() {
-    super("timed out acquiring the token refresh lock");
-    this.name = "RefreshLockTimeoutError";
-  }
-}
-
-/** The pid recorded in the lockfile, or null if absent/empty/malformed. */
-function readLockOwnerPid(): number | null {
-  try {
-    const pid = Number.parseInt(fs.readFileSync(refreshLockFile(), "utf-8").trim(), 10);
-    return Number.isInteger(pid) && pid > 0 ? pid : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Whether `pid` is a live process. All contenders for this lock share one host
- * (the cache is `~/.hq`), so pid liveness is authoritative. `EPERM` means the
- * process exists but is owned by another user — still alive; any other error
- * (`ESRCH`, bad pid) means it's gone.
- */
-function processAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return (err as NodeJS.ErrnoException).code === "EPERM";
-  }
-}
-
-/**
- * Serialize the token refresh/mint cycle across every process sharing this
- * cache (~/.hq/cognito-tokens.json). Boxes run several hq processes (the
- * auth-refresh timer, the sync runner, replica-sync) that refresh or mint the
- * same session concurrently; without coordination they race on the shared
- * cache. And if the app client ever issues single-use tokens (refresh-token
- * rotation), two unsynchronized refreshers each send the same token — the first
- * consumes it, the second gets `invalid_grant`. An advisory lockfile (atomic
- * hard-link publication) makes them take turns; the caller MUST re-read the cache
- * inside `fn` so a waiter reuses the winner's fresh token, never a consumed one.
- * This is also the lock the per-box machine-identity mint path reuses (ADR-0009).
- *
- * Correctness over availability at the edges:
- *  - A held lock is reclaimed ONLY when its recorded holder pid is dead (a real
- *    crash) or the lockfile is malformed — NEVER because a live holder is merely
- *    slow (a slow Cognito response must not let a second refresher race in).
- *  - Release unlinks ONLY our own lock (pid re-checked), so we can't delete a
- *    successor's lock.
- *  - If we can't acquire within `timeoutMs` (a live holder never released — a
- *    hung network), we THROW rather than refresh unlocked; the caller prefers a
- *    still-valid cached token and otherwise retries next cycle. Proceeding
- *    unlocked would reintroduce the exact rotation race this guards.
- */
-async function withRefreshLock<T>(fn: () => Promise<T>): Promise<T> {
-  const timeoutMs = 20_000;
-  const pollMs = 50;
-  try {
-    if (!fs.existsSync(hqStateDir())) {
-      fs.mkdirSync(hqStateDir(), { recursive: true, mode: 0o700 });
-    }
-  } catch (err) {
-    if (!isNotWritableError(err)) throw err;
-    return await fn();
-  }
-  // Publish a fully-written inode with an atomic hard link. Creating the lock
-  // itself and then writing the pid leaves an observable empty-file window in
-  // which a contender can misclassify and unlink a live holder's lock.
-  const candidate = `${refreshLockFile()}.candidate.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
-  try {
-    fs.writeFileSync(candidate, String(process.pid), {
-      flag: "wx",
-      mode: 0o600,
-    });
-  } catch (err) {
-    if (!isNotWritableError(err)) throw err;
-    // The state dir is not writable, so NO process can be persisting to this
-    // cache — there is nothing to serialize against and the lock's only job is
-    // moot. Run unlocked rather than failing the caller's authentication on a
-    // lockfile we neither need nor can create. (Before this, a read-only state
-    // dir raised EACCES here, killing machine auth before any network call.)
-    return await fn();
-  }
-  const deadline = Date.now() + timeoutMs;
-  let held = false;
-  try {
-    for (;;) {
-      try {
-        fs.linkSync(candidate, refreshLockFile());
-        held = true;
-        break;
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
-        const owner = readLockOwnerPid();
-        if (owner === null || (owner !== process.pid && !processAlive(owner))) {
-          try {
-            fs.unlinkSync(refreshLockFile()); // crashed/malformed holder — reclaim
-          } catch {
-            /* raced with another reclaimer */
-          }
-          continue;
-        }
-        if (Date.now() >= deadline) throw new RefreshLockTimeoutError();
-        await sleep(pollMs);
-      }
-    }
-    return await fn();
-  } finally {
-    // Release ONLY our own lock — never clobber a successor's.
-    if (held && readLockOwnerPid() === process.pid) {
-      try {
-        fs.unlinkSync(refreshLockFile());
-      } catch {
-        /* already released */
-      }
-    }
-    // Remove the private proposal inode name on success or acquisition failure.
-    try {
-      fs.unlinkSync(candidate);
-    } catch {
-      /* already removed */
-    }
-  }
-}
-
-/**
- * Parse `expiresAt` to epoch-ms. Canonical on-disk shape is epoch milliseconds
- * (number). Older token files may contain ISO 8601 strings. Accept both for
- * migration safety. Returns null for anything unparseable — callers should
- * treat that as "expired" and force a refresh.
- */
-function parseExpiresAtMs(raw: unknown): number | null {
-  if (typeof raw === "number") return Number.isFinite(raw) ? raw : null;
-  if (typeof raw === "string") {
-    const ms = new Date(raw).getTime();
-    return Number.isFinite(ms) ? ms : null;
-  }
-  return null;
-}
-
-/** True when the token expires within the given buffer (default 60s). */
-export function isExpiring(tokens: CognitoTokens, bufferSeconds = 60): boolean {
-  const expiresAt = parseExpiresAtMs(tokens.expiresAt);
-  if (expiresAt === null) return true;
-  return expiresAt - Date.now() < bufferSeconds * 1000;
-}
-
-/**
- * Decode the `client_id` claim from a Cognito access token (no signature
- * verification — we only need to identify which App Client minted it).
- * Returns null when the token can't be parsed.
- *
- * Used by `getValidAccessToken` to detect stale cached sessions that target
- * a different Cognito App Client. The canonical case is a pre-2026-04-25
- * cache file holding a `hq-vault-dev` token after the user upgraded to a
- * post-cutover CLI: the access token stays "non-expiring" for an hour but
- * the prod vault API rejects it with 401, and the dev refresh token can't
- * be exchanged at the prod token endpoint. Detecting the mismatch and
- * forcing a re-login is the only safe self-heal.
- */
-export function decodeAccessTokenClientId(accessToken: string): string | null {
-  const claims = decodeJwtClaims(accessToken);
-  return typeof claims?.client_id === "string" ? claims.client_id : null;
-}
-
-function decodeJwtClaims(token: string): Record<string, unknown> | null {
-  try {
-    const parts = token.split(".");
-    if (parts.length < 2) return null;
-    const payloadB64 = parts[1];
-    const normalized = payloadB64.replace(/-/g, "+").replace(/_/g, "/");
-    const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
-    const json = Buffer.from(padded, "base64").toString("utf-8");
-    const claims = JSON.parse(json);
-    return claims && typeof claims === "object" && !Array.isArray(claims)
-      ? (claims as Record<string, unknown>)
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function machineTokenPairMatchesIdentity(
-  tokens: CognitoTokens,
-  creds: MachineCreds,
-  expectedClientId: string,
-): boolean {
-  const accessClaims = decodeJwtClaims(tokens.accessToken);
-  const idClaims = decodeJwtClaims(tokens.idToken);
-  if (!accessClaims || !idClaims) return false;
-
-  const stringClaim = (
-    claims: Record<string, unknown>,
-    key: string,
-  ): string | null => {
-    const value = claims[key];
-    return typeof value === "string" && value.length > 0 ? value : null;
-  };
-
-  const accessClientId = accessClaims.client_id;
-  const idAudience = idClaims.aud;
-  const accessUsername =
-    stringClaim(accessClaims, "username") ??
-    stringClaim(accessClaims, "cognito:username");
-  const accessSub = stringClaim(accessClaims, "sub");
-  const idUsername =
-    stringClaim(idClaims, "cognito:username") ?? stringClaim(idClaims, "username");
-  const idSub = stringClaim(idClaims, "sub");
-  const entityType = stringClaim(idClaims, "custom:entityType");
-  const entityUid = stringClaim(idClaims, "custom:entityUid");
-  const delegatedSub = stringClaim(idClaims, "custom:delegatedSub");
-  const delegatedEmail = stringClaim(idClaims, "custom:delegatedEmail");
-  const hasValidMachineClaimShape =
-    (entityType === "agent" &&
-      entityUid !== null &&
-      entityUid.startsWith("agt_")) ||
-    (entityType === "outpost" &&
-      entityUid !== null &&
-      entityUid.startsWith("out_") &&
-      delegatedSub !== null &&
-      delegatedEmail !== null);
-  // Legacy agent credentials did not persist entityType. If a newer creds
-  // file adds only its agt_* uid, infer the only valid type for that uid.
-  const expectedEntityType = creds.entityType ?? "agent";
-  const entityMatchesCreds =
-    entityType === expectedEntityType &&
-    (creds.entityUid === undefined || entityUid === creds.entityUid);
-  // Bind the ID token to the REQUESTED credentials. Username equality only
-  // holds in pools without email aliasing; the prod pool aliases email-format
-  // usernames, so Cognito's canonical username (`cognito:username`, access
-  // `username`, `sub`) is a generated UUID that NEVER equals the email-format
-  // creds.username — and the machine app client cannot read `email`, so no
-  // email claim rides the ID token either. For creds that persist their
-  // entityUid (every ADR-0009 outpost and modern agent), the unique
-  // custom:entityUid claim IS the identity binding: exactly one Cognito user
-  // carries that attribute value, stamped server-side at provisioning.
-  // Regression: 6.14.13 shipped username-only binding and rejected every
-  // valid machine mint in the alias pool ("Machine token mint returned tokens
-  // that do not match the requested machine identity"), logging out the
-  // outpost fleet. Legacy creds without entityUid keep the username binding.
-  const idTokenMatchesCreds =
-    idUsername === creds.username ||
-    idSub === creds.username ||
-    (creds.entityUid !== undefined && entityUid === creds.entityUid);
-  const subjectBindings: boolean[] = [];
-  if (accessUsername !== null && idUsername !== null) {
-    subjectBindings.push(accessUsername === idUsername);
-  }
-  if (accessSub !== null && idSub !== null) {
-    subjectBindings.push(accessSub === idSub);
-  }
-  const tokensShareSubject =
-    subjectBindings.length > 0 && subjectBindings.every(Boolean);
-
-  return (
-    accessClaims.token_use === "access" &&
-    accessClientId === expectedClientId &&
-    idClaims.token_use === "id" &&
-    idAudience === expectedClientId &&
-    hasValidMachineClaimShape &&
-    entityMatchesCreds &&
-    idTokenMatchesCreds &&
-    tokensShareSubject
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Machine identity (company agents and Outpost boxes)
-// ---------------------------------------------------------------------------
-//
-// HQ agents and Outposts run headless on their own boxes with long-lived Cognito
-// MACHINE credentials ({username: "machine-agt_<ulid>", secret}) provisioned
-// by hq-pro's agent bootstrap and stored at ~/.hq-agent/machine-creds.json.
-// There is no browser, no Hosted UI, and no refresh-token dance: the creds
-// never expire, so the CLI simply re-mints a session via USER_PASSWORD_AUTH
-// whenever the cached tokens are missing or expiring.
-//
-// Token semantics matter here. Machine identity claims ride the ID token only:
-// agents carry custom:entityType=agent/custom:entityUid=agt_*, while Outposts
-// carry outpost/out_* plus delegatedSub and delegatedEmail. APIs that verify
-// token_use=access (e.g. hq-deploy) need the real access token. Both are cached
-// with correct field semantics — callers pick the token type each API validates.
-
-export interface MachineCreds {
-  /** Cognito username for the machine user. */
-  username: string;
-  /** Long-lived machine secret (USER_PASSWORD_AUTH password). */
-  secret: string;
-  /** App client to mint against — provisioned creds carry their own
-   *  (USER_PASSWORD_AUTH must be enabled on it); falls back to config. */
-  clientId?: string;
-  /** Cognito region for the mint endpoint; falls back to config. */
-  region?: string;
-  /** Expected machine kind carried in the ID token's custom:entityType claim. */
-  entityType?: "agent" | "outpost";
-  /** Exact expected machine uid carried in custom:entityUid. */
-  entityUid?: string;
-}
-
-/** Resolve the machine-creds file path (HQ_MACHINE_CREDS_FILE overrides). */
-export function machineCredsFilePath(): string {
-  return (
-    process.env.HQ_MACHINE_CREDS_FILE ??
-    path.join(os.homedir(), ".hq-agent", "machine-creds.json")
-  );
-}
-
-/**
- * Load machine credentials, or null when this process is not running as a
- * machine identity (no creds file / unreadable / malformed).
- */
-export function loadMachineCreds(): MachineCreds | null {
-  const file = machineCredsFilePath();
-  try {
-    if (!fs.existsSync(file)) return null;
-    const raw = JSON.parse(fs.readFileSync(file, "utf-8")) as {
-      username?: unknown;
-      secret?: unknown;
-      clientId?: unknown;
-      region?: unknown;
-      entityType?: unknown;
-      entityUid?: unknown;
-    };
-    // The creds FILE is the machine-identity signal — no username-shape
-    // gate. (6.7.0 required a "machine-" prefix, but live boxes are
-    // provisioned with "agt-<ulid>@agents.getindigo.ai", so detection
-    // never engaged on the first real agent box, 2026-06-12.)
-    const validEntityIdentity =
-      (raw.entityType === undefined && raw.entityUid === undefined) ||
-      (raw.entityType === undefined &&
-        typeof raw.entityUid === "string" &&
-        raw.entityUid.startsWith("agt_") &&
-        raw.entityUid.length > "agt_".length) ||
-      (raw.entityType === "agent" &&
-        typeof raw.entityUid === "string" &&
-        raw.entityUid.startsWith("agt_") &&
-        raw.entityUid.length > "agt_".length) ||
-      (raw.entityType === "outpost" &&
-        typeof raw.entityUid === "string" &&
-        raw.entityUid.startsWith("out_") &&
-        raw.entityUid.length > "out_".length);
-    if (
-      typeof raw.username === "string" &&
-      raw.username.length > 0 &&
-      typeof raw.secret === "string" &&
-      raw.secret.length > 0 &&
-      validEntityIdentity
-    ) {
-      return {
-        username: raw.username,
-        secret: raw.secret,
-        clientId: typeof raw.clientId === "string" ? raw.clientId : undefined,
-        region: typeof raw.region === "string" ? raw.region : undefined,
-        ...(raw.entityType === "agent" || raw.entityType === "outpost"
-          ? { entityType: raw.entityType }
-          : {}),
-        ...(typeof raw.entityUid === "string"
-          ? { entityUid: raw.entityUid }
-          : {}),
-      };
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-/** True when machine credentials are present — the CLI is a machine identity. */
-export function isMachineIdentity(): boolean {
-  return loadMachineCreds() !== null;
-}
-
-/**
- * Whether the caller declared this process MUST run as a machine identity
- * (`HQ_REQUIRE_MACHINE_IDENTITY=1`).
- *
- * Set it on unattended runners — child jobs, workers, skill subprocesses. It
- * converts the worst failure mode in this module into a clear one.
- *
- * Without it, a machine context that cannot find its credentials does not
- * error: `isMachineIdentity()` returns false and the caller quietly proceeds to
- * the HUMAN Cognito path. On a headless box that means "launching browser
- * sign-in" and a hang until something times out — observed in production, and
- * reported by a client as child jobs "falling back to refreshing a human HQ
- * session". The cause (a different HOME, so a different creds path) is nowhere
- * in that message.
- */
-export function machineIdentityRequired(): boolean {
-  const raw = process.env.HQ_REQUIRE_MACHINE_IDENTITY?.trim().toLowerCase();
-  return raw === "1" || raw === "true" || raw === "yes";
-}
-
-/**
- * Throw a typed, diagnosable error when machine identity is REQUIRED but the
- * creds file is not readable. Names the exact path checked and how it was
- * derived, so the fix (set `HQ_MACHINE_CREDS_FILE`, or restore HOME) is
- * readable straight off the error. No-op when not required or already a
- * machine identity.
- */
-export function assertMachineIdentityWhenRequired(): void {
-  if (!machineIdentityRequired() || isMachineIdentity()) return;
-  const explicit = process.env.HQ_MACHINE_CREDS_FILE?.trim();
-  const source =
-    explicit !== undefined && explicit.length > 0
-      ? "HQ_MACHINE_CREDS_FILE"
-      : `os.homedir()=${os.homedir()}`;
-  throw new CognitoAuthError(
-    `HQ_REQUIRE_MACHINE_IDENTITY is set but no usable machine credentials were ` +
-      `found at ${machineCredsFilePath()} (path from ${source}). Refusing to ` +
-      `fall back to an interactive human session. Set HQ_MACHINE_CREDS_FILE to ` +
-      `the credentials file, or run with the HOME that owns it.`,
-  );
-}
-
-interface InitiateAuthResponse {
-  AuthenticationResult?: {
-    AccessToken?: string;
-    IdToken?: string;
-    RefreshToken?: string;
-    ExpiresIn?: number;
-  };
-  ChallengeName?: string;
-  __type?: string;
-  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.
- */
-async function mintMachineTokensUnlocked(
-  config: CognitoAuthConfig,
-  creds?: MachineCreds,
-  retry?: MintRetryOptions,
-): Promise<CognitoTokens> {
-  const machineCreds = creds ?? loadMachineCreds();
-  if (!machineCreds) {
-    throw new CognitoAuthError(
-      `No machine credentials found at ${machineCredsFilePath()}`,
-    );
-  }
-  // Prefer the creds file's own clientId/region: provisioning pairs the
-  // machine user with an app client that has USER_PASSWORD_AUTH enabled,
-  // which the CLI's default (browser) client may not.
-  const region = machineCreds.region ?? config.region;
-  const clientId = machineCreds.clientId ?? config.clientId;
-  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",
-        },
-        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 retained.
-      refreshToken: "",
-      expiresAt: Date.now() + (result.ExpiresIn ?? 3600) * 1000,
-      tokenType: "Bearer",
-    };
-    if (!machineTokenPairMatchesIdentity(tokens, machineCreds, clientId)) {
-      throw new CognitoAuthError(
-        "Machine token mint returned tokens that do not match the requested machine identity",
-      );
-    }
-    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");
-}
-
-/**
- * Mint and persist a fresh machine session while holding the process-shared
- * token lock. The unlocked implementation is private so public callers cannot
- * race another process's cache write.
- */
-export async function mintMachineTokens(
-  config: CognitoAuthConfig,
-  creds?: MachineCreds,
-  retry?: MintRetryOptions,
-): Promise<CognitoTokens> {
-  return withRefreshLock(() => mintMachineTokensUnlocked(config, creds, retry));
-}
-
-// 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.
-// The memo carries an exact credential/client key, and in-flight work is keyed,
-// so reprovisioning a long-running process cannot reuse the prior identity.
-interface MachineTokenMemo {
-  identityKey: string;
-  tokens: CognitoTokens;
-}
-
-let inProcessMachineTokens: MachineTokenMemo | null = null;
-const inFlightMachineMints = new Map<string, Promise<CognitoTokens>>();
-
-function machineIdentityKey(
-  config: CognitoAuthConfig,
-  creds: MachineCreds,
-): string {
-  // Include every credential value that can change the effective mint. Hashing
-  // keeps the long-lived secret out of diagnostic heap strings while retaining
-  // exact-key behavior when a creds file is reprovisioned in place.
-  return crypto
-    .createHash("sha256")
-    .update(
-      JSON.stringify({
-        username: creds.username,
-        secret: creds.secret,
-        clientId: creds.clientId ?? config.clientId,
-        region: creds.region ?? config.region,
-        entityType: creds.entityType ?? "agent",
-        entityUid: creds.entityUid ?? null,
-      }),
-    )
-    .digest("hex");
-}
-
-/**
- * Return a valid (non-expiring) machine session, re-minting on demand.
- * 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();
-  if (!machineCreds) {
-    throw new CognitoAuthError(
-      `No machine credentials found at ${machineCredsFilePath()}`,
-    );
-  }
-  const expectedClientId = machineCreds.clientId ?? config.clientId;
-  const identityKey = machineIdentityKey(config, machineCreds);
-  // Hot path: a live in-memory token serves every request after the first.
-  if (
-    inProcessMachineTokens?.identityKey === identityKey &&
-    !isExpiring(inProcessMachineTokens.tokens, 120) &&
-    machineTokenPairMatchesIdentity(
-      inProcessMachineTokens.tokens,
-      machineCreds,
-      expectedClientId,
-    )
-  ) {
-    return inProcessMachineTokens.tokens;
-  }
-  // 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.
-  const existingResolution = inFlightMachineMints.get(identityKey);
-  if (existingResolution) return existingResolution;
-
-  const resolution = (async () => {
-    const resolveUnderLock = async (): Promise<CognitoTokens> => {
-      // Re-read only after acquiring the process-shared lock. A different hq
-      // process may have minted and saved this machine's session while this
-      // caller was waiting.
-      const cached = loadCachedTokens();
-      if (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
-        // the exact machine identity. Opaque/missing/human-shaped claims are
-        // treated as stale.
-        if (
-          machineTokenPairMatchesIdentity(
-            cached,
-            machineCreds,
-            expectedClientId,
-          )
-        ) {
-          if (cached.refreshToken === "") return cached;
-          const normalized = { ...cached, refreshToken: "" };
-          saveCachedTokens(normalized);
-          return normalized;
-        }
-      }
-      // mintMachineTokens persists before returning, so the complete shared
-      // cache read -> USER_PASSWORD_AUTH mint -> save sequence is serialized.
-      return mintMachineTokensUnlocked(config, machineCreds);
-    };
-
-    try {
-      return await withRefreshLock(resolveUnderLock);
-    } catch (err) {
-      if (!(err instanceof RefreshLockTimeoutError)) throw err;
-      // Never mint unlocked. If the holder managed to persist a matching fresh
-      // session, reuse it; otherwise surface a retryable auth failure.
-      const cached = loadCachedTokens();
-      if (cached && !isExpiring(cached, 120)) {
-        if (
-          machineTokenPairMatchesIdentity(
-            cached,
-            machineCreds,
-            expectedClientId,
-          )
-        ) {
-          // The successful path always leaves a machine cache with no refresh
-          // token. If this is legacy state, only normalize it while holding the
-          // lock; after a timeout we must not race the live holder's write.
-          if (cached.refreshToken === "") return cached;
-        }
-      }
-      throw new CognitoAuthError(
-        "Machine token mint is held by another process and no fresh matching session is available; retry shortly.",
-      );
-    }
-  })();
-  inFlightMachineMints.set(identityKey, resolution);
-
-  try {
-    const tokens = await resolution;
-    inProcessMachineTokens = { identityKey, tokens };
-    return tokens;
-  } finally {
-    // Clear on both success and failure: a rejected mint must not wedge later
-    // calls onto a permanently-failed promise.
-    if (inFlightMachineMints.get(identityKey) === resolution) {
-      inFlightMachineMints.delete(identityKey);
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// PKCE
-// ---------------------------------------------------------------------------
-
-function base64UrlEncode(buf: Buffer): string {
-  return buf
-    .toString("base64")
-    .replace(/\+/g, "-")
-    .replace(/\//g, "_")
-    .replace(/=+$/, "");
-}
-
-function generatePkce(): { verifier: string; challenge: string } {
-  const verifier = base64UrlEncode(crypto.randomBytes(32));
-  const challenge = base64UrlEncode(
-    crypto.createHash("sha256").update(verifier).digest(),
-  );
-  return { verifier, challenge };
-}
-
-// ---------------------------------------------------------------------------
-// Endpoint helpers
-// ---------------------------------------------------------------------------
-
-function authBaseUrl(config: CognitoAuthConfig): string {
-  return `https://${config.userPoolDomain}.auth.${config.region}.amazoncognito.com`;
-}
-
-function redirectUri(port: number): string {
-  return `http://localhost:${port}/callback`;
-}
-
-// ---------------------------------------------------------------------------
-// Browser login
-// ---------------------------------------------------------------------------
-
-/**
- * Open the Cognito Hosted UI in the user's browser, wait for the redirect
- * back to localhost, and exchange the auth code for tokens.
- *
- * Times out after 5 minutes if the user doesn't complete the flow.
- */
-export async function browserLogin(
-  config: CognitoAuthConfig,
-): Promise<CognitoTokens> {
-  const port = config.port ?? 3000;
-  const scopes = (config.scopes ?? ["openid", "email", "profile"]).join(" ");
-  const { verifier, challenge } = generatePkce();
-  const state = base64UrlEncode(crypto.randomBytes(16));
-
-  // Use `/oauth2/authorize` (not `/login`) so `identity_provider` + `prompt`
-  // are honored. `/login` ignores those params and always shows the IdP picker.
-  const authUrl = new URL(`${authBaseUrl(config)}/oauth2/authorize`);
-  authUrl.searchParams.set("client_id", config.clientId);
-  authUrl.searchParams.set("response_type", "code");
-  authUrl.searchParams.set("scope", scopes);
-  authUrl.searchParams.set("redirect_uri", redirectUri(port));
-  authUrl.searchParams.set("code_challenge", challenge);
-  authUrl.searchParams.set("code_challenge_method", "S256");
-  authUrl.searchParams.set("state", state);
-  if (config.identityProvider) {
-    authUrl.searchParams.set("identity_provider", config.identityProvider);
-  }
-  if (config.prompt) {
-    authUrl.searchParams.set("prompt", config.prompt);
-  }
-
-  const code = await waitForAuthCode(port, state);
-  const tokens = await exchangeCodeForTokens(config, code, verifier, port);
-  saveCachedTokens(tokens);
-  return tokens;
-
-  // -- inner: spin up loopback server and open browser ---------------------
-  function waitForAuthCode(port: number, expectedState: string): Promise<string> {
-    return new Promise((resolve, reject) => {
-      // cleanup() is a function declaration so it can be referenced from the
-      // server callbacks and the timeout closure below before its source
-      // position. It clears the 15-min login timer + closes the loopback
-      // server — without this both keep Node's event loop alive after the
-      // calling script "completes", making it look hung.
-      const server = http.createServer((req, res) => {
-        const url = new URL(req.url ?? "/", `http://localhost:${port}`);
-        if (url.pathname !== "/callback") {
-          res.writeHead(404);
-          res.end("Not found");
-          return;
-        }
-        const code = url.searchParams.get("code");
-        const state = url.searchParams.get("state");
-        const error = url.searchParams.get("error");
-
-        if (error) {
-          res.writeHead(400, { "Content-Type": "text/html" });
-          res.end(`<h1>Authentication failed</h1><p>${escapeHtml(error)}</p>`);
-          cleanup();
-          reject(new CognitoAuthError(`Cognito returned error: ${error}`));
-          return;
-        }
-        if (state !== expectedState) {
-          res.writeHead(400, { "Content-Type": "text/html" });
-          res.end("<h1>State mismatch</h1><p>Possible CSRF — try again.</p>");
-          cleanup();
-          reject(new CognitoAuthError("Cognito state parameter mismatch"));
-          return;
-        }
-        if (!code) {
-          res.writeHead(400, { "Content-Type": "text/html" });
-          res.end("<h1>Missing code</h1>");
-          cleanup();
-          reject(new CognitoAuthError("Cognito callback missing code"));
-          return;
-        }
-
-        res.writeHead(200, { "Content-Type": "text/html" });
-        res.end(
-          `<!doctype html><html><body style="font-family:system-ui;text-align:center;padding:48px;">
-            <h1>Signed in to HQ by Indigo</h1>
-            <p>You can close this tab and return to your terminal.</p>
-            <script>setTimeout(()=>window.close(),1500)</script>
-          </body></html>`,
-        );
-        cleanup();
-        resolve(code);
-      });
-
-      server.on("error", (err) => {
-        cleanup();
-        reject(err);
-      });
-      server.listen(port, "127.0.0.1", () => {
-        console.log(`\n  Opening browser for HQ sign-in...`);
-        console.log(`  If your browser doesn't open, visit:\n  ${authUrl.toString()}\n`);
-        open(authUrl.toString()).catch(() => {
-          /* user can paste the URL manually */
-        });
-      });
-
-      const loginTimer = setTimeout(
-        () => {
-          cleanup();
-          reject(new CognitoAuthError("Login timed out after 15 minutes"));
-        },
-        15 * 60 * 1000,
-      );
-
-      function cleanup() {
-        clearTimeout(loginTimer);
-        server.close();
-      }
-    });
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Token exchange + refresh
-// ---------------------------------------------------------------------------
-
-interface CognitoTokenResponse {
-  access_token: string;
-  id_token: string;
-  refresh_token?: string;
-  expires_in: number;
-  token_type: string;
-}
-
-async function exchangeCodeForTokens(
-  config: CognitoAuthConfig,
-  code: string,
-  verifier: string,
-  port: number,
-): Promise<CognitoTokens> {
-  const body = new URLSearchParams({
-    grant_type: "authorization_code",
-    client_id: config.clientId,
-    code,
-    code_verifier: verifier,
-    redirect_uri: redirectUri(port),
-  });
-
-  const res = await fetch(`${authBaseUrl(config)}/oauth2/token`, {
-    method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body: body.toString(),
-  });
-  if (!res.ok) {
-    const text = await res.text();
-    throw new CognitoAuthError(
-      `Token exchange failed (${res.status}): ${text}`,
-    );
-  }
-  const data = (await res.json()) as CognitoTokenResponse;
-  if (!data.refresh_token) {
-    throw new CognitoAuthError(
-      "Cognito did not return a refresh token — check OAuth scopes include offline_access semantics",
-    );
-  }
-  return {
-    accessToken: data.access_token,
-    idToken: data.id_token,
-    refreshToken: data.refresh_token,
-    expiresAt: Date.now() + data.expires_in * 1000,
-    tokenType: "Bearer",
-  };
-}
-
-/** Whether the cached session was minted by `config`'s app client. */
-function cachedIsForClient(
-  cached: CognitoTokens,
-  config: CognitoAuthConfig,
-): boolean {
-  const clientId = decodeAccessTokenClientId(cached.accessToken);
-  return clientId !== null && clientId === config.clientId;
-}
-
-/**
- * Use the refresh token to obtain a fresh access token without user interaction.
- *
- * Concurrency-safe. Several hq processes on a box refresh the same cached
- * session at once, so the whole read→refresh→save cycle runs under a
- * cross-process lock, and inside the lock we (a) reuse a token another refresher
- * just produced if it's still fresh, and (b) otherwise refresh with the FRESHEST
- * token on disk rather than the caller's snapshot. This keeps the shared cache
- * consistent, and stays correct if the app client uses single-use (rotated)
- * tokens — a stale snapshot would otherwise be an already-consumed token
- * (`invalid_grant`). NOTE: rotation is NOT how boxes stay signed in — a rotated
- * token inherits the original's remaining lifetime, so it does not extend the
- * session (AWS). Durable never-log-out is per-box machine identity (ADR-0009).
- */
-export async function refreshTokens(
-  config: CognitoAuthConfig,
-  currentRefreshToken: string,
-  currentAccessToken?: string,
-): Promise<CognitoTokens> {
-  const doRefresh = async (): Promise<CognitoTokens> => {
-    const cached = loadCachedTokens();
-    // Reuse a token another refresher just produced — but ONLY when it belongs
-    // to THIS app client (a direct caller may target a different pool than the
-    // shared cache holds) and is still fresh (a fresh access token has ~1h, so
-    // >300s of life means "someone already refreshed", not the caller's own
-    // expiring token).
-    if (cached && cachedIsForClient(cached, config) && !isExpiring(cached, 300)) {
-      return cached;
-    }
-
-    // Prefer the freshest refresh token on disk over the caller's snapshot when
-    // it's for this client — a concurrent rotation may have consumed the
-    // snapshot. Otherwise (different client / no cache) use the supplied token.
-    const refreshToken =
-      cached && cachedIsForClient(cached, config)
-        ? cached.refreshToken
-        : currentRefreshToken;
-    const sessionFingerprint = cached && cachedIsForClient(cached, config)
-      ? accessTokenFingerprint(cached.accessToken)
-      : currentAccessToken
-        ? accessTokenFingerprint(currentAccessToken)
-        : undefined;
-
-    const body = new URLSearchParams({
-      grant_type: "refresh_token",
-      client_id: config.clientId,
-      refresh_token: refreshToken,
-    });
-
-    let lastFailure: CognitoRefreshError | undefined;
-    for (let attempt = 0; attempt < 2; attempt++) {
-      let res: Response;
-      try {
-        res = await fetch(`${authBaseUrl(config)}/oauth2/token`, {
-          method: "POST",
-          headers: { "Content-Type": "application/x-www-form-urlencoded" },
-          body: body.toString(),
-        });
-      } catch (err) {
-        lastFailure = new CognitoRefreshError(
-          `Cognito refresh request failed: ${err instanceof Error ? err.message : String(err)}`,
-          false,
-          undefined,
-          sessionFingerprint,
-        );
-        if (attempt === 0) continue;
-        throw lastFailure;
-      }
-
-      if (!res.ok) {
-        const text = await res.text();
-        const retryable =
-          res.status === 401 ||
-          res.status === 408 ||
-          res.status === 429 ||
-          res.status >= 500;
-        const requiresReauth =
-          res.status === 401 ||
-          (res.status >= 400 &&
-            res.status < 500 &&
-            ![408, 429].includes(res.status));
-        lastFailure = new CognitoRefreshError(
-          requiresReauth
-            ? "Your HQ session needs a quick refresh. Sign in again to keep sync moving."
-            : `Cognito refresh failed (${res.status}): ${text}`,
-          requiresReauth,
-          res.status,
-          sessionFingerprint,
-        );
-        if (retryable && attempt === 0) continue;
-        throw lastFailure;
-      }
-
-      const data = (await res.json()) as CognitoTokenResponse;
-      const tokens: CognitoTokens = {
-        accessToken: data.access_token,
-        idToken: data.id_token,
-        // Persist a rotated refresh token if the endpoint returns one (single-use
-        // clients); otherwise keep the freshest token we sent. This is for cache
-        // correctness, not longevity; rotation does not extend session lifetime.
-        refreshToken: data.refresh_token ?? refreshToken,
-        expiresAt: Date.now() + data.expires_in * 1000,
-        tokenType: "Bearer",
-      };
-      saveCachedTokens(tokens);
-      return tokens;
-    }
-
-    throw (
-      lastFailure ??
-      new CognitoRefreshError("Cognito refresh failed after retry", false)
-    );
-  };
-
-  try {
-    return await withRefreshLock(doRefresh);
-  } catch (err) {
-    if (!(err instanceof RefreshLockTimeoutError)) throw err;
-    // A live holder never released within the window (pathological — e.g. a
-    // hung network). Prefer whatever it may have persisted for this client; do
-    // NOT refresh unlocked (that reintroduces the rotation race). If nothing
-    // usable is cached, surface the failure so the caller retries next cycle.
-    const cached = loadCachedTokens();
-    if (cached && cachedIsForClient(cached, config) && !isExpiring(cached)) {
-      return cached;
-    }
-    throw new CognitoRefreshError(
-      "Token refresh is held by another process and no fresh cached session is available; retry shortly.",
-      false,
-    );
-  }
-}
-
-/**
- * High-level helper: return a non-expired access token, refreshing or
- * launching browser login as needed.
- *
- * Pass `interactive: false` from automated contexts where you would rather
- * fail fast than open a browser.
- */
-export async function getValidAccessToken(
-  config: CognitoAuthConfig,
-  options: { interactive?: boolean } = {},
-): Promise<string> {
-  const interactive = options.interactive ?? true;
-
-  // Machine identities (company agents) never refresh or open a browser —
-  // they re-mint via USER_PASSWORD_AUTH on demand.
-  // Machine identities return the ID token: every hq-cloud caller of this
-  // getter talks to the VAULT API, whose authorizer accepts ID tokens — and
-  // the agent's identity claims (custom:entityType/entityUid) ride the ID
-  // token ONLY. Returning the access token made the first post-cutover
-  // agent box (Petyr, 2026-06-12) resolve as NOBODY: /membership/me -> []
-  // -> 'setup-needed' forever, while the identical call with the ID token
-  // returned its membership. (Consumers needing token_use=access — e.g.
-  // the deploy API — pick tokens per call in hq-cli, not here.)
-  if (isMachineIdentity()) {
-    const machine = await getValidMachineTokens(config);
-    return machine.idToken;
-  }
-
-  // Past this point we are on the HUMAN path (cache -> refresh -> browser).
-  // An unattended runner that declared itself a machine must fail here with a
-  // diagnosable error rather than silently trying to sign a person in.
-  assertMachineIdentityWhenRequired();
-
-  let cached = loadCachedTokens();
-
-  // Stale-pool detection: if the cached access token was issued by a
-  // different Cognito App Client than the one we're talking to now, drop the
-  // cache and re-authenticate. Without this, a user holding a pre-cutover
-  // dev-pool token would either keep using a token the prod API rejects
-  // with 401, or attempt a refresh against the prod token endpoint with a
-  // dev refresh token (InvalidGrant). See `decodeAccessTokenClientId` for
-  // the full rationale.
-  if (cached) {
-    const cachedClientId = decodeAccessTokenClientId(cached.accessToken);
-    if (cachedClientId !== null && cachedClientId !== config.clientId) {
-      invalidateCachedTokensByFingerprint(
-        accessTokenFingerprint(cached.accessToken),
-      );
-      cached = null;
-    }
-  }
-
-  if (cached && !isExpiring(cached)) return cached.accessToken;
-
-  if (cached) {
-    try {
-      const refreshed = await refreshTokens(
-        config,
-        cached.refreshToken,
-        cached.accessToken,
-      );
-      return refreshed.accessToken;
-    } catch (err) {
-      if (err instanceof CognitoRefreshError && err.requiresReauth) {
-        invalidateCachedTokensByFingerprint(
-          err.sessionFingerprint ?? accessTokenFingerprint(cached.accessToken),
-        );
-      }
-      if (!interactive) throw err;
-      // fall through to interactive login
-    }
-  }
-
-  if (!interactive) {
-    throw new CognitoAuthError(
-      "No valid HQ session and interactive login is disabled. Run `hq login` first.",
-    );
-  }
-
-  const fresh = await browserLogin(config);
-  return fresh.accessToken;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function escapeHtml(s: string): string {
-  return s
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#39;");
-}