@cad0p/pi-usage 0.11.5 → 0.11.6

package/src/local/worker.js

@@ -0,0 +1,157 @@
+/**
+ * Run the potentially large local session scan away from Pi's TUI event loop.
+ * The worker runs the plain Node ESM entry point; the extension itself may be
+ * loaded through jiti, but this worker never needs that loader.
+ *
+ * The scan can outlive the surface that asked for it. A cold scan of a
+ * multi-gigabyte session store takes seconds, and the user may `/quit` or
+ * `/reload` a second later: a thread left behind keeps reading session files
+ * after the session is gone and holds `local-sessions.json.lock` until the
+ * 120 s stale timeout, so every later scan is read-only with a warning. The
+ * handle owns that lifecycle — the host stops it, and the stop always ends with
+ * the lock released and no half-written state.
+ */
+
+import { Worker } from "node:worker_threads";
+
+import { releaseHistoryLock } from "./history.js";
+
+/**
+ * How long a stopping scan gets to notice the flag and release its own lock
+ * before the thread is terminated and the parent releases the lock instead.
+ */
+export const DEFAULT_STOP_GRACE_MS = 2_000;
+
+/** A scan the host stopped, told apart from a failure by its name. */
+function scanStoppedError() {
+  const error = new Error("local token stats scan stopped");
+  error.name = "AbortError";
+  return error;
+}
+
+/**
+ * Start the scan in a worker thread.
+ *
+ * The stop request is a shared flag the scan polls rather than a message it has
+ * to be idle to receive: a cold scan spends its time inside synchronous reads
+ * and hashing, where a queued message would only be seen after the work it is
+ * meant to interrupt.
+ *
+ * @param {import("./pi-sessions.js").LocalStatsOptions} [options]
+ * @param {{
+ *   graceMs?: number,
+ *   spawn?: () => { on: Function, once: Function, postMessage: Function, terminate: () => Promise<number> },
+ *   releaseLock?: (lock: { path: string, token: string | null }) => boolean,
+ * }} [lifecycle] Test seams: a fake worker and a zero grace period.
+ * @returns {{
+ *   result: Promise<Awaited<ReturnType<typeof import("./pi-sessions.js").collectLocalStats>>>,
+ *   stop: () => Promise<void>,
+ * }}
+ */
+export function startLocalStatsWorker(options = {}, lifecycle = {}) {
+  const graceMs = Number.isFinite(lifecycle.graceMs)
+    ? Math.max(0, /** @type {number} */ (lifecycle.graceMs))
+    : DEFAULT_STOP_GRACE_MS;
+  const stopFlag = new Int32Array(new SharedArrayBuffer(4));
+  const releaseLock = lifecycle.releaseLock ?? releaseHistoryLock;
+  const worker = lifecycle.spawn
+    ? lifecycle.spawn()
+    : new Worker(new URL("./stats-worker.js", import.meta.url), { workerData: { options, stopFlag } });
+
+  /** The lock the scan told us it holds; only its own token may remove it. */
+  /** @type {{ path: string, token: string | null } | null} */
+  let lock = null;
+  /** @type {{ ok: true, result: any } | { ok: false, aborted: boolean, error: string } | null} */
+  let outcome = null;
+  let stopping = false;
+  let settled = false;
+  /** @type {(value: any) => void} */
+  let resolveResult = () => {};
+  /** @type {(error: Error) => void} */
+  let rejectResult = () => {};
+  const result = new Promise((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+
+  const finish = () => {
+    if (settled) return;
+    settled = true;
+    const owned = lock;
+    lock = null;
+    // A scan that ended on its own already released this in its own `finally`;
+    // a thread that had to be killed did not, and its token is the only proof
+    // the file is still ours.
+    if (owned) releaseLock(owned);
+    if (outcome?.ok) resolveResult(outcome.result);
+    else rejectResult(outcome?.aborted ? scanStoppedError() : new Error(outcome?.error ?? "the worker thread failed"));
+  };
+
+  worker.on("message", (message) => {
+    if (!message || typeof message !== "object") return;
+    if (message.type === "lock") {
+      if (typeof message.path === "string") {
+        lock = { path: message.path, token: typeof message.token === "string" ? message.token : null };
+      }
+      return;
+    }
+    if (message.type !== "result") return;
+    outcome = message.ok
+      ? { ok: true, result: message.result }
+      : {
+          ok: false,
+          aborted: message.aborted === true,
+          error: typeof message.error === "string" ? message.error : "the scan failed",
+        };
+  });
+  worker.once("error", () => {
+    // A thread that died (OOM, a broken entry point) never posts a result.
+    if (!outcome) outcome = { ok: false, aborted: stopping, error: "the worker thread failed" };
+  });
+  const exited = new Promise((resolve) => {
+    worker.once("exit", (code) => {
+      if (!outcome) {
+        outcome = stopping
+          ? { ok: false, aborted: true, error: "local token stats scan stopped" }
+          : { ok: false, aborted: false, error: "the worker thread exited without a result" };
+      }
+      finish();
+      resolve(code);
+    });
+  });
+
+  /**
+   * End the scan: ask it to stop, terminate the thread if it does not, and
+   * leave the report cache and the history exactly as they were found.
+   */
+  const stop = async () => {
+    if (stopping) return;
+    stopping = true;
+    Atomics.store(stopFlag, 0, 1);
+    if (!settled) {
+      const stopped = await Promise.race([
+        exited.then(() => true),
+        new Promise((resolve) => {
+          const timer = setTimeout(() => resolve(false), graceMs);
+          timer.unref?.();
+        }),
+      ]);
+      if (!stopped) await worker.terminate().catch(() => 0);
+    }
+    await exited;
+    finish();
+  };
+
+  return { result, stop };
+}
+
+/**
+ * Await one scan to completion. The caller that wants the lifecycle uses
+ * {@link startLocalStatsWorker} instead.
+ *
+ * @param {import("./pi-sessions.js").LocalStatsOptions} [options]
+ * @returns {Promise<Awaited<ReturnType<typeof import("./pi-sessions.js").collectLocalStats>>>}
+ */
+export function collectLocalStatsInWorker(options = {}) {
+  return startLocalStatsWorker(options).result;
+}

package/src/model.js

@@ -33,6 +33,10 @@
  * @property {string} source               Credential source description.
  * @property {"pi" | "claude-code"} [sourceKind]  Which kind of store produced it.
  * @property {string | null} expiresInMin  Credential freshness, when known.
+ * @property {true} [tokenRenewedInMemory]  Present only when the provider renewed
+ *                                          this token in memory for this run: the
+ *                                          stored credential's freshness then no
+ *                                          longer describes the request made.
  */
 
 /**
@@ -247,6 +251,7 @@ export function humanReset(seconds) {
  *   source: string,
  *   now?: number,
  *   expiresInMin?: number | null,
+ *   tokenRenewedInMemory?: boolean,
  *   windows?: QuotaWindow[],
  * }} input
  * @returns {QuotaResult}
@@ -256,7 +261,7 @@ export function degradedResult(input) {
     input.notConfigured ??
       (typeof input.error === "string" && input.error.startsWith("no ") && input.error.includes("credential in the Pi store")),
   );
-  return {
+  const result = {
     family: input.family,
     label: input.label,
     account: input.account ?? "unknown",
@@ -270,6 +275,27 @@ export function degradedResult(input) {
     sourceKind: input.sourceKind,
     expiresInMin: input.expiresInMin ?? null,
   };
+  // Only ever present when a provider renewed the token in memory: a field on
+  // every result would be one more thing the JSON feed promises to keep.
+  if (input.tokenRenewedInMemory === true) result.tokenRenewedInMemory = true;
+  return result;
+}
+
+/**
+ * Which field `displayIdentity` would print for this credential.
+ *
+ * A provider that adds a second identifier of its own (Antigravity's Cloud Code
+ * project) needs to know whether the identity already *is* that identifier, or
+ * it prints the same value twice.
+ *
+ * @param {{ email?: string | null, accountId?: string | null, projectId?: string | null, identity?: string }} credential
+ * @returns {"email" | "accountId" | "projectId" | "identity" | "none"}
+ */
+export function identityKind(credential) {
+  if (credential.email) return "email";
+  if (credential.accountId) return "accountId";
+  if (credential.projectId) return "projectId";
+  return credential.identity ? "identity" : "none";
 }
 
 /**
@@ -279,10 +305,18 @@ export function degradedResult(input) {
  * @returns {string}
  */
 export function displayIdentity(credential) {
-  if (credential.email) return credential.email;
-  if (credential.accountId) return `${credential.accountId.slice(0, 8)}…`;
-  if (credential.projectId) return `project ${credential.projectId.slice(0, 8)}…`;
-  return credential.identity ? `id ${credential.identity.slice(0, 8)}…` : "unknown";
+  switch (identityKind(credential)) {
+    case "email":
+      return /** @type {string} */ (credential.email);
+    case "accountId":
+      return `${/** @type {string} */ (credential.accountId).slice(0, 8)}…`;
+    case "projectId":
+      return `project ${/** @type {string} */ (credential.projectId).slice(0, 8)}…`;
+    case "identity":
+      return `id ${/** @type {string} */ (credential.identity).slice(0, 8)}…`;
+    default:
+      return "unknown";
+  }
 }
 
 /**

package/src/omarchy/publish.js

@@ -61,7 +61,7 @@ function writeRecord(dir, id, record) {
  * no longer present.
  *
  * @param {Array<{ id: string, record: Record<string, unknown> }>} records
- * @param {{ dir?: string, env?: Record<string, string | undefined>, home?: string }} [options]
+ * @param {{ dir?: string, env?: Record<string, string | undefined>, home?: string, prune?: boolean }} [options]
  * @returns {{ dir: string, written: string[], removed: string[] }}
  */
 export function publishRecords(records, options = {}) {
@@ -74,15 +74,16 @@ export function publishRecords(records, options = {}) {
     written.push(writeRecord(dir, id, record));
   }
 
-  const keep = new Set(records.map(({ id }) => `${id}.json`));
   const removed = [];
-  for (const name of readdirSync(dir)) {
-    if (!name.startsWith(RECORD_PREFIX) || !name.endsWith(".json")) continue;
-    if (!isPiRecordId(name.slice(0, -".json".length)) || keep.has(name)) continue;
-    rmSync(join(dir, name), { force: true });
-    removed.push(join(dir, name));
+  if (options.prune !== false) {
+    const keep = new Set(records.map(({ id }) => `${id}.json`));
+    for (const name of readdirSync(dir)) {
+      if (!name.startsWith(RECORD_PREFIX) || !name.endsWith(".json")) continue;
+      if (!isPiRecordId(name.slice(0, -".json".length)) || keep.has(name)) continue;
+      rmSync(join(dir, name), { force: true });
+      removed.push(join(dir, name));
+    }
   }
 
-
   return { dir, written, removed };
 }

package/src/overlay-keys.js

@@ -0,0 +1,257 @@
+/**
+ * Raw key decoding for the /usage overlay.
+ *
+ * Terminals speak two encodings for the keys the overlay answers. Legacy
+ * terminals send the familiar escape sequences (`\x1b[A` for Up, `\x1b[5~` for
+ * PgUp), and terminals that negotiate the kitty keyboard protocol — Ghostty
+ * among them, because Pi asks for flags 1|2|4 — send CSI sequences carrying a
+ * 1-based modifier mask and an event type (`\x1b[1;1:1A` for a press,
+ * `\x1b[1;1:2A` for a repeat, `\x1b[1;1:3A` for a release), and may report a
+ * printable key as its codepoint (`\x1b[106u` for `j`).
+ *
+ * This mirrors the subset of pi-tui's `matchesKey`, `isKeyRelease`,
+ * `isKeyRepeat` and `decodeKittyPrintable` the overlay needs. It is local on
+ * purpose. Pi maps `@earendil-works/pi-tui` for an extension at load time
+ * through jiti's virtual modules, so a static import would work inside Pi — but
+ * the test suite loads the extension with Node's type stripping, where a bare
+ * specifier resolves only from a `node_modules` this package does not have and
+ * never installs: it ships zero runtime and dev dependencies, and CI runs
+ * `npm test` with no install step. Declaring pi-tui a peer/dev dependency would
+ * only move that install into CI and every contributor's checkout, and injecting
+ * the matcher would still need a real implementation for the tests. One local
+ * decoder is a single code path that the unit table, the overlay tests and the
+ * live tmux proof all exercise.
+ *
+ * A release is never a press: the overlay drops it before acting. A repeat is a
+ * press. A held arrow must keep moving, and in a legacy terminal the OS repeat
+ * is byte-identical to the first press, so ignoring kitty repeats would make a
+ * held key behave differently in Ghostty than in tmux.
+ */
+
+const LOCK_MASK = 64 + 128; // Caps Lock and Num Lock ride along in the modifier field
+const MODIFIER_SHIFT = 1;
+
+/** Kitty reserves this Private Use Area range for functional keys. */
+const KITTY_FUNCTIONAL_START = 57344;
+const KITTY_FUNCTIONAL_END = 63743;
+
+/** Internal codepoints: negative so a reported codepoint can never collide. */
+const ARROW = { up: -1, down: -2, right: -3, left: -4 };
+const FUNCTIONAL = { delete: -10, insert: -11, pageUp: -12, pageDown: -13, home: -14, end: -15 };
+
+/** The final letter of a `CSI A/B/C/D` arrow sequence. */
+const ARROW_BY_LETTER = { A: ARROW.up, B: ARROW.down, C: ARROW.right, D: ARROW.left };
+
+/** Codepoints of the keys the overlay names. */
+const KEY_CODEPOINTS = {
+  escape: 27,
+  enter: 13,
+  tab: 9,
+  space: 32,
+  ...ARROW,
+  ...FUNCTIONAL,
+};
+
+/**
+ * Kitty's Private Use Area spellings of the same keys, including the keypad
+ * aliases (57417 left … 57424 end, 57414 keypad enter).
+ *
+ * @type {Map<number, number>}
+ */
+const KITTY_EQUIVALENTS = new Map([
+  [57350, ARROW.left],
+  [57351, ARROW.right],
+  [57352, ARROW.up],
+  [57353, ARROW.down],
+  [57354, FUNCTIONAL.pageUp],
+  [57355, FUNCTIONAL.pageDown],
+  [57356, FUNCTIONAL.home],
+  [57357, FUNCTIONAL.end],
+  [57414, KEY_CODEPOINTS.enter],
+  [57417, ARROW.left],
+  [57418, ARROW.right],
+  [57419, ARROW.up],
+  [57420, ARROW.down],
+  [57421, FUNCTIONAL.pageUp],
+  [57422, FUNCTIONAL.pageDown],
+  [57423, FUNCTIONAL.home],
+  [57424, FUNCTIONAL.end],
+]);
+
+/** What a legacy terminal (or tmux, in either cursor mode) sends for each key. */
+const LEGACY = {
+  escape: ["\u001b"],
+  // SS3 M is how xterm family terminals send the numpad Enter.
+  enter: ["\r", "\n", "\u001bOM"],
+  tab: ["\t"],
+  space: [" "],
+  up: ["\u001b[A", "\u001bOA"],
+  down: ["\u001b[B", "\u001bOB"],
+  left: ["\u001b[D", "\u001bOD"],
+  right: ["\u001b[C", "\u001bOC"],
+  pageUp: ["\u001b[5~", "\u001b[[5~"],
+  pageDown: ["\u001b[6~", "\u001b[[6~"],
+  home: ["\u001b[H", "\u001bOH", "\u001b[1~", "\u001b[7~"],
+  end: ["\u001b[F", "\u001bOF", "\u001b[4~", "\u001b[8~"],
+};
+
+/** The number in a `CSI <n> ~` functional sequence. */
+const FUNCTIONAL_BY_NUMBER = { 1: FUNCTIONAL.home, 2: FUNCTIONAL.insert, 3: FUNCTIONAL.delete, 4: FUNCTIONAL.end, 5: FUNCTIONAL.pageUp, 6: FUNCTIONAL.pageDown, 7: FUNCTIONAL.home, 8: FUNCTIONAL.end };
+
+const CSI_U = /^\x1b\[(\d+)(?::(\d*))?(?::(\d+))?(?:;(\d+))?(?::(\d+))?u$/;
+// A modifier field only ever follows "1;" — the bare forms (\x1b[1A, \x1b[1H)
+// are not sequences pi-tui accepts as arrows, so neither do we.
+const CSI_ARROW = /^\x1b\[1;(\d+)(?::(\d+))?([ABCD])$/;
+const CSI_HOME_END = /^\x1b\[1;(\d+)(?::(\d+))?([HF])$/;
+const CSI_FUNCTIONAL = /^\x1b\[(\d+)(?:;(\d+))?(?::(\d+))?~$/;
+const CSI_MODIFY_OTHER_KEYS = /^\x1b\[27;(\d+);(\d+)~$/;
+
+/**
+ * Event type from the trailing field: 1 press, 2 repeat, 3 release.
+ *
+ * @param {string | undefined} value
+ * @returns {"press" | "repeat" | "release"}
+ */
+function eventType(value) {
+  if (value === "2") return "repeat";
+  if (value === "3") return "release";
+  return "press";
+}
+
+/**
+ * Normalize a kitty functional codepoint to the internal one.
+ *
+ * @param {number} codepoint
+ * @returns {number}
+ */
+function normalize(codepoint) {
+  return KITTY_EQUIVALENTS.get(codepoint) ?? codepoint;
+}
+
+/**
+ * One parsed key event, or null when the bytes are neither a key the overlay
+ * knows nor a sequence it can read.
+ *
+ * @param {string} data
+ * @returns {{ codepoint: number, shifted?: number, modifier: number, event: "press" | "repeat" | "release" } | null}
+ */
+function parseKey(data) {
+  let match = data.match(CSI_MODIFY_OTHER_KEYS);
+  if (match) return { codepoint: Number(match[2]), modifier: Number(match[1]) - 1, event: "press" };
+
+  match = data.match(CSI_U);
+  if (match) {
+    return {
+      codepoint: Number(match[1]),
+      shifted: match[2] ? Number(match[2]) : undefined,
+      modifier: match[4] ? Number(match[4]) - 1 : 0,
+      event: eventType(match[5]),
+    };
+  }
+
+  match = data.match(CSI_ARROW);
+  if (match) return { codepoint: ARROW_BY_LETTER[match[3]], modifier: Number(match[1]) - 1, event: eventType(match[2]) };
+
+  match = data.match(CSI_HOME_END);
+  if (match) {
+    return {
+      codepoint: match[3] === "H" ? FUNCTIONAL.home : FUNCTIONAL.end,
+      modifier: Number(match[1]) - 1,
+      event: eventType(match[2]),
+    };
+  }
+
+  match = data.match(CSI_FUNCTIONAL);
+  if (match) {
+    const codepoint = FUNCTIONAL_BY_NUMBER[Number(match[1])];
+    if (codepoint !== undefined) return { codepoint, modifier: match[2] ? Number(match[2]) - 1 : 0, event: eventType(match[3]) };
+  }
+  return null;
+}
+
+/**
+ * Whether raw input is a kitty key release. Only a kitty-protocol terminal
+ * reports releases, so legacy input is always a press.
+ *
+ * @param {string} data
+ * @returns {boolean}
+ */
+export function isKeyRelease(data) {
+  return parseKey(data)?.event === "release";
+}
+
+/**
+ * Whether raw input is a kitty key repeat (the terminal auto-repeating a held
+ * key). The overlay treats it as a press; see the module comment.
+ *
+ * @param {string} data
+ * @returns {boolean}
+ */
+export function isKeyRepeat(data) {
+  return parseKey(data)?.event === "repeat";
+}
+
+/**
+ * Whether raw input is the named key, unmodified.
+ *
+ * Shift is allowed on enter, space and escape, whose shifted form is the same
+ * key in a legacy terminal; Shift+Tab is backtab (`\x1b[Z`), a different key, so
+ * it is not tab in either encoding, and any other modifier is a different key
+ * (shift+up, ctrl+page-up, …).
+ *
+ * @param {string} data raw bytes from the terminal
+ * @param {"escape" | "enter" | "tab" | "space" | "up" | "down" | "left" | "right" | "pageUp" | "pageDown" | "home" | "end"} name
+ * @returns {boolean}
+ */
+export function matchesKey(data, name) {
+  if ((LEGACY[name] ?? []).includes(data)) return true;
+  const expected = KEY_CODEPOINTS[name];
+  if (expected === undefined) return false;
+  const parsed = parseKey(data);
+  if (!parsed) return false;
+  const modifier = parsed.modifier & ~LOCK_MASK;
+  const allowed = name === "enter" || name === "space" || name === "escape" ? MODIFIER_SHIFT : 0;
+  if ((modifier & ~allowed) !== 0) return false;
+  return normalize(parsed.codepoint) === expected;
+}
+
+/**
+ * The printable character a kitty CSI-u or xterm modifyOtherKeys sequence
+ * carries, if it is one. Plain and Shift-modified text only: ctrl/alt/super
+ * combinations are key bindings, not text.
+ *
+ * @param {string} data
+ * @returns {string | undefined}
+ */
+function decodePrintable(data) {
+  const parsed = parseKey(data);
+  if (!parsed) return undefined;
+  const modifier = parsed.modifier & ~LOCK_MASK;
+  if ((modifier & ~MODIFIER_SHIFT) !== 0) return undefined;
+  let codepoint = parsed.codepoint;
+  if (modifier & MODIFIER_SHIFT) {
+    if (parsed.shifted !== undefined) codepoint = parsed.shifted;
+    else if (codepoint >= 97 && codepoint <= 122) codepoint -= 32;
+  }
+  codepoint = normalize(codepoint);
+  if (!Number.isFinite(codepoint) || codepoint < 32) return undefined;
+  if (codepoint >= KITTY_FUNCTIONAL_START && codepoint <= KITTY_FUNCTIONAL_END) return undefined;
+  try {
+    return String.fromCodePoint(codepoint);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether raw input is the printable character, in any encoding: the byte
+ * itself (legacy), or a codepoint sequence with no modifier or Shift.
+ *
+ * @param {string} data raw bytes from the terminal
+ * @param {string} char one printable character
+ * @returns {boolean}
+ */
+export function matchesPrintable(data, char) {
+  if (data === char) return true;
+  return decodePrintable(data) === char;
+}

package/src/providers/antigravity-oauth.js

@@ -41,6 +41,9 @@ const ANTIGRAVITY_OAUTH_SOURCES = [
   join(homedir(), ".pi", "agent", "npm", "node_modules", "pi-antigravity", "dist", "auth", "oauth.js"),
 ];
 
+/** Renewed Google access tokens live only in this process, until shortly before expiry. */
+const renewedAccessTokens = new Map();
+
 /**
  * Recover the two `atob("..." + "...")` literals from the installed package.
  *
@@ -89,11 +92,15 @@ export function resolveOAuthClient(options = {}) {
 }
 
 /**
- * @param {{ client?: { clientId: string, clientSecret: string }, fetchFn?: typeof fetch, timeoutMs?: number }} [options]
+ * Describe the OAuth client a refresh used, resolved the same way the refresh
+ * resolved it: a description of the environment's client while the request went
+ * out with the installed package's would name the wrong credential source.
+ *
+ * @param {{ client?: { clientId: string, clientSecret: string }, env?: Record<string, string | undefined>, sourcePath?: string }} [options]
  * @returns {string}
  */
 export function describeOAuthClient(options = {}) {
-  const client = options.client ?? resolveOAuthClient();
+  const client = options.client ?? resolveOAuthClient({ env: options.env, sourcePath: options.sourcePath });
   return client.source === "env"
     ? "client from ANTIGRAVITY_CLIENT_ID/SECRET"
     : client.source === "pi-antigravity"
@@ -108,12 +115,16 @@ export function describeOAuthClient(options = {}) {
  *   fetchFn?: typeof fetch,
  *   timeoutMs?: number,
  *   now?: number,
+ *   env?: Record<string, string | undefined>,
+ *   sourcePath?: string,
  * }} [options]
  * @returns {Promise<{ access: string, refresh: string, expires: number } | { error: string }>}
  */
 export async function refreshAccessToken(refreshToken, options = {}) {
   if (!refreshToken) return { error: "no refresh token available" };
-  const client = options.client ?? resolveOAuthClient();
+  // The caller's environment and package source decide the client. Keep these
+  // resolution inputs aligned with describeOAuthClient for an accurate failure.
+  const client = options.client ?? resolveOAuthClient({ env: options.env, sourcePath: options.sourcePath });
 
   const response = await requestJson(GOOGLE_TOKEN_URL, {
     method: "POST",
@@ -152,12 +163,30 @@ export async function refreshAccessToken(refreshToken, options = {}) {
  *   now?: number,
  *   bufferMs?: number,
  *   enabled?: boolean,
+ *   env?: Record<string, string | undefined>,
+ *   sourcePath?: string,
+ *   cacheKey?: string,
  * }} [options]
  * @returns {Promise<{ ok: boolean, refreshed: boolean, error?: string }>}
  */
 export async function ensureFreshAccessToken(account, options = {}) {
   const now = options.now ?? Date.now();
   const bufferMs = options.bufferMs ?? 5 * 60 * 1000;
+  const cacheKey = options.cacheKey;
+  if (cacheKey) {
+    const cached = renewedAccessTokens.get(cacheKey);
+    if (cached && cached.expiresAtMs - bufferMs > now) {
+      account.access = cached.access;
+      account.expiresAtMs = cached.expiresAtMs;
+      return { ok: true, refreshed: true };
+    }
+    if (cached) {
+      clearTimeout(cached.timer);
+      cached.access = "";
+      renewedAccessTokens.delete(cacheKey);
+    }
+  }
+
   const expiring = !account.expiresAtMs || account.expiresAtMs - bufferMs <= now;
   if (!expiring) return { ok: true, refreshed: false };
   if (options.enabled === false) return { ok: Boolean(account.access), refreshed: false, error: "refresh disabled" };
@@ -169,5 +198,16 @@ export async function ensureFreshAccessToken(account, options = {}) {
   account.access = result.access;
   account.refresh = result.refresh;
   account.expiresAtMs = result.expires;
+  if (cacheKey) {
+    const entry = { access: result.access, expiresAtMs: result.expires, timer: null };
+    const clearAfterMs = Math.max(1, result.expires - bufferMs - now);
+    entry.timer = setTimeout(() => {
+      if (renewedAccessTokens.get(cacheKey) !== entry) return;
+      entry.access = "";
+      renewedAccessTokens.delete(cacheKey);
+    }, clearAfterMs);
+    entry.timer.unref?.();
+    renewedAccessTokens.set(cacheKey, entry);
+  }
   return { ok: true, refreshed: true };
 }