@cad0p/pi-usage 0.11.5 → 0.11.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cad0p/pi-usage",
-  "version": "0.11.5",
+  "version": "0.11.6",
   "publishConfig": {
     "access": "public"
   },

package/src/cache.js

@@ -62,6 +62,59 @@ export function resolveCachePath(options = {}) {
   return join(cacheHome, "pi-quota", "usage.json");
 }
 
+/**
+ * Read the cache envelope, or null when there is not one this version understands.
+ *
+ * @param {string} path
+ * @returns {Record<string, any> | null}
+ */
+function readPayload(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? /** @type {Record<string, any>} */ (parsed) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The fetch time of every family a cached report carries.
+ *
+ * The report is written family by family — the Pi extension repaints and saves
+ * as each one lands — so `savedAt` says when the *last* family was written and
+ * nothing about the others. Judging the whole file by it served Claude's
+ * five-minute-old numbers to a reader a minute later, only because Codex had
+ * just been saved. Each family therefore keeps its own clock. A cache written
+ * before that field existed carries only `savedAt`, and every family falls
+ * back to it.
+ *
+ * @param {Record<string, any>} parsed
+ * @param {string[]} families
+ * @returns {Record<string, number>}
+ */
+function payloadClocks(parsed, families) {
+  const savedAt = typeof parsed.savedAt === "number" && Number.isFinite(parsed.savedAt) ? parsed.savedAt : null;
+  /** @type {Record<string, number>} */
+  const clocks = {};
+  const raw = parsed.fetchedAt;
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    for (const [family, value] of Object.entries(raw)) {
+      if (typeof value === "number" && Number.isFinite(value)) clocks[family] = value;
+    }
+  }
+  for (const family of families) {
+    if (typeof clocks[family] === "number") continue;
+    if (savedAt !== null) clocks[family] = savedAt;
+  }
+  return clocks;
+}
+
 /**
  * @param {{
  *   path?: string,
@@ -71,27 +124,20 @@ export function resolveCachePath(options = {}) {
  *   home?: string,
  *   key?: string,       Settings fingerprint; a cached report saved under another key is a miss.
  * }} [options]
- * @returns {{ report: import("./engine.js").PiQuotaReport, ageMs: number, path: string } | null}
+ * @returns {{
+ *   report: import("./engine.js").PiQuotaReport,
+ *   ageMs: number,
+ *   fetchedAt: Record<string, number>,
+ *   path: string,
+ * } | null}
  */
 export function readCache(options = {}) {
   const path = options.path ?? resolveCachePath(options);
   const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
   const now = options.now ?? Date.now();
 
-  let raw;
-  try {
-    raw = readFileSync(path, "utf-8");
-  } catch {
-    return null;
-  }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== "object") return null;
+  const parsed = readPayload(path);
+  if (!parsed) return null;
   const report = /** @type {{ report?: import("./engine.js").PiQuotaReport }} */ (parsed).report;
   if (!report || !Array.isArray(report.providers)) return null;
 
@@ -99,7 +145,13 @@ export function readCache(options = {}) {
     ? /** @type {number} */ (/** @type {{ savedAt?: number }} */ (parsed).savedAt)
     : null;
   if (savedAt === null) return null;
-  const ageMs = now - savedAt;
+  const families = Array.from(new Set(report.providers.map((provider) => provider.family)));
+  const fetchedAt = payloadClocks(parsed, families);
+  // The oldest family decides the hit: a report is only as fresh as its stalest
+  // part, which is what the single-`savedAt` rule meant before per-family clocks.
+  const ageMs = families.length > 0
+    ? Math.max(...families.map((family) => now - (fetchedAt[family] ?? savedAt)))
+    : now - savedAt;
   if (ageMs > ttlMs) return null;
   // A report collected under other settings (e.g. another Claude source) answers a
   // different question, so it is a miss rather than a stale hit.
@@ -116,7 +168,33 @@ export function readCache(options = {}) {
     }
   }
 
-  return { report, ageMs, path };
+  return { report, ageMs, fetchedAt, path };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+function finite(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/**
+ * The fetch time a family's own results carry: the oldest `updatedAt` among
+ * its accounts, or undefined when none parses.
+ *
+ * @param {import("./engine.js").PiQuotaReport} report
+ * @param {string} family
+ * @returns {number | undefined}
+ */
+function oldestUpdatedAt(report, family) {
+  let oldest;
+  for (const provider of report.providers ?? []) {
+    if (provider?.family !== family) continue;
+    const at = Date.parse(provider.updatedAt ?? "");
+    if (Number.isFinite(at) && (oldest === undefined || at < oldest)) oldest = at;
+  }
+  return oldest;
 }
 
 /**
@@ -128,24 +206,34 @@ export function readCache(options = {}) {
  *   home?: string,
  *   merge?: boolean,
  *   key?: string,
+ *   fetchedAtMs?: Record<string, number>,  Each family's own fetch time, when the caller knows it.
+ *   freshFamilies?: string[],  Families this write fetched just now; defaults to every family in `report`.
  * }} [options]
  * @returns {{ ok: boolean, path: string, error?: string }}
  */
 export function writeCache(report, options = {}) {
   const path = options.path ?? resolveCachePath(options);
   const now = options.now ?? Date.now();
+  const existing = readCache({ ...options, path, ttlMs: Number.POSITIVE_INFINITY });
   let finalReport = report;
-  if (options.merge) {
-    const existing = readCache({ ...options, path, ttlMs: Number.POSITIVE_INFINITY });
-    if (existing?.report) {
-      finalReport = mergeReportIntoCache(existing.report, report);
-    }
+  if (options.merge && existing?.report) {
+    finalReport = mergeReportIntoCache(existing.report, report);
+  }
+  const fresh = new Set(options.freshFamilies ?? (report.providers ?? []).map((provider) => provider.family));
+  const provided = options.fetchedAtMs ?? {};
+  /** @type {Record<string, number>} */
+  const fetchedAt = {};
+  for (const family of new Set((finalReport.providers ?? []).map((provider) => provider.family))) {
+    // A family this write fetched is "now" unless the caller knows a better
+    // time. Any other family keeps the clock it had; with no clock anywhere it
+    // is as old as its own results say, never restamped to now, which would
+    // let an hour-old copy pass as fresh merely because a neighbour was saved.
+    const own = provided[family];
+    const at = finite(own) ? own : fresh.has(family) ? now : finite(existing?.fetchedAt?.[family]) ? existing.fetchedAt[family] : oldestUpdatedAt(finalReport, family);
+    fetchedAt[family] = finite(at) ? at : now;
   }
-  const payload = JSON.stringify(
-    options.key === undefined ? { savedAt: now, report: finalReport } : { savedAt: now, key: options.key, report: finalReport },
-    null,
-    2,
-  );
+  const envelope = { savedAt: now, ...(options.key === undefined ? {} : { key: options.key }), fetchedAt, report: finalReport };
+  const payload = JSON.stringify(envelope, null, 2);
 
   try {
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
@@ -211,10 +299,16 @@ export function describeCache(options = {}) {
 export async function withCache(options, loader) {
   const requested = options.families;
   if (!options.force) {
-    const hit = readCache(options);
+    // Freshness is decided per family below, so the read must not apply one
+    // TTL to the whole file first.
+    const hit = readCache({ ...options, ttlMs: Number.POSITIVE_INFINITY });
     if (hit) {
-      const allPresent = !requested || requested.every((fam) => fam in hit.report.byFamily);
-      if (allPresent) {
+      const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+      const now = options.now ?? Date.now();
+      const present = new Set(hit.report.providers.map((provider) => provider.family));
+      const wanted = requested ?? Array.from(present);
+      const fresh = wanted.every((family) => present.has(family) && now - (hit.fetchedAt[family] ?? 0) <= ttlMs);
+      if (fresh) {
         const filteredReport = requested
           ? {
               ...hit.report,
@@ -224,7 +318,10 @@ export async function withCache(options, loader) {
               ),
             }
           : hit.report;
-        return { report: filteredReport, cached: true, ageMs: hit.ageMs };
+        const ageMs = wanted.length > 0
+          ? Math.max(...wanted.map((family) => now - (hit.fetchedAt[family] ?? now)))
+          : hit.ageMs;
+        return { report: filteredReport, cached: true, ageMs };
       }
     }
   }

package/src/cli/commands/omarchy.js

@@ -44,19 +44,37 @@ export function skippedFamilies(env, dir) {
 }
 
 /**
- * @param {{ load: () => Promise<import("../../engine.js").PiQuotaReport>, dir?: string, env?: Record<string, string | undefined>, quiet?: boolean }} options
+ * @param {{
+ *   load: (options?: { onFamily?: (family: string, report: import("../../engine.js").PiQuotaReport) => void | Promise<void> }) => Promise<import("../../engine.js").PiQuotaReport>,
+ *   dir?: string,
+ *   env?: Record<string, string | undefined>,
+ *   quiet?: boolean,
+ * }} options
  * @returns {Promise<number>}
  */
 export async function runOmarchyCommand(options) {
+  const skip = skippedFamilies(options.env ?? process.env, options.dir);
+  const onFamily = async (family, fragment) => {
+    if (skip.has(family)) return;
+    const providers = (fragment.providers ?? []).filter((provider) => provider?.family === family && !skip.has(provider.family));
+    if (providers.length === 0) return;
+    try {
+      const familyReport = { ...fragment, providers, byFamily: { [family]: providers } };
+      publishRecords(buildRecords(familyReport), { dir: options.dir, env: options.env, prune: false });
+    } catch {
+      // A per-family write must not prevent later providers from being collected.
+      // The final complete publish below reports any persistent write failure.
+    }
+  };
+
   let report;
   try {
-    report = await options.load();
+    report = await options.load({ onFamily });
   } catch (error) {
     err(`omarchy: could not collect quota: ${redact(/** @type {{ message?: string }} */ (error)?.message ?? error)}`);
     return 1;
   }
 
-  const skip = skippedFamilies(options.env ?? process.env, options.dir);
   const records = buildRecords(skip.size > 0 ? { ...report, providers: (report.providers ?? []).filter((p) => !skip.has(p?.family)) } : report);
   let result;
   try {

package/src/engine.js

@@ -6,7 +6,7 @@
  * degraded result with an actionable message.
  */
 
-import { checkFreshness, LABEL_BY_FAMILY, loadPiCredentials, resolveAuthPaths } from "./auth/pi-auth.js";
+import { checkFreshness, LABEL_BY_FAMILY, loadPiCredentials, normalizeCredential, resolveAuthPaths } from "./auth/pi-auth.js";
 import { loadClaudeCodeCredential } from "./auth/claude-code-auth.js";
 import { redact } from "./http.js";
 import { collectLocalStats } from "./local/pi-sessions.js";
@@ -239,6 +239,12 @@ const PROVIDERS = {
  *     tests and library callers never read a real home directory; the CLI turns
  *     it on with a time budget. Pass an object to inject session roots or a
  *     cache path, or false to disable it explicitly.
+ *   onFamily?: (family: string, report: PiQuotaReport) => void | Promise<void>,
+ *     Called once a family has settled, before the other families necessarily
+ *     finish. The report fragment contains only that family's results.
+ *   authOverrides?: Record<string, { access: string, expiresAtMs?: number | null, accountId?: string | null }>,
+ *     Optional in-memory OAuth access tokens supplied by the host runtime. Never
+ *     persisted or included in reports.
  * }} [options]
  * @returns {Promise<PiQuotaReport>}
  */
@@ -255,6 +261,37 @@ export async function collectQuota(options = {}) {
     paths: options.paths,
   });
 
+  // Pi's extension host may have resolved/renewed an OAuth token through Pi's
+  // own locked auth path. Apply only to the matching provider in memory; the
+  // underlying file reader remains read-only and the token never reaches output.
+  for (const [provider, auth] of Object.entries(options.authOverrides ?? {})) {
+    if (typeof auth?.access !== "string" || auth.access === "") continue;
+    let matched = false;
+    for (const credential of loaded.credentials) {
+      if (credential.provider !== provider) continue;
+      credential.access = auth.access;
+      credential.expiresAtMs = auth.expiresAtMs ?? null;
+      if (typeof auth.accountId === "string" && auth.accountId !== "") credential.accountId = auth.accountId;
+      matched = true;
+    }
+    // Pi may own auth from a non-default agent directory that the standalone
+    // read-only path discovery does not know about. A host-resolved OAuth token
+    // is sufficient to create the in-memory provider entry; never persist it.
+    if (!matched) {
+      const credential = normalizeCredential(
+        provider,
+        {
+          type: "oauth",
+          access: auth.access,
+          expires: auth.expiresAtMs,
+          accountId: auth.accountId,
+        },
+        "Pi runtime auth",
+      );
+      if (credential) loaded.credentials.push(credential);
+    }
+  }
+
   // Claude is the one family with a second, non-Pi source, so it is resolved
   // before the per-family loop and then treated exactly like any other credential.
   const claude = resolveClaudeCredentials({
@@ -290,6 +327,43 @@ export async function collectQuota(options = {}) {
   /** @type {Record<string, string[]>} */
   const familyWarnings = {};
 
+  /**
+   * Publish a family fragment as soon as its provider work is complete. A
+   * callback failure is isolated from provider collection and becomes a warning
+   * on the final report.
+   *
+   * @param {string} family
+   * @param {import("./model.js").QuotaResult[]} results
+   */
+  const emitFamily = async (family, results) => {
+    for (const provider of results) {
+      provider.primaryWindowId = selectPrimaryWindow(provider.windows ?? [])?.id ?? null;
+    }
+    byFamily[family] = results;
+    familyWarnings[family] ??= [];
+    if (!options.onFamily) return;
+    const fragment = {
+      engine: "pi-quota",
+      schemaVersion: 1,
+      readOnly: true,
+      generatedAt: new Date(now).toISOString(),
+      sources: loaded.paths,
+      claudeSource: { mode: claude.mode, paths: claude.claudeCodePaths, unavailable: claude.unavailable },
+      warnings: [...warnings, ...familyWarnings[family]],
+      providers: results,
+      byFamily: { [family]: results },
+      localStats: {},
+      localStatsMeta: null,
+    };
+    try {
+      await options.onFamily(family, fragment);
+    } catch (error) {
+      familyWarnings[family].push(
+        `${family}: family callback failed: ${redact(/** @type {{ message?: string }} */ (error)?.message ?? String(error))}`,
+      );
+    }
+  };
+
   const hasOpenAi = loaded.rawProviders?.includes("openai") || Boolean(env.OPENAI_API_KEY);
 
   // The local scan runs beside the network calls: a first full scan of the
@@ -310,7 +384,7 @@ export async function collectQuota(options = {}) {
         // `notConfigured` is stated rather than inferred: the message now names a
         // second source, and every renderer keys off this flag to avoid painting a
         // failure icon for a provider the user simply does not use.
-        byFamily[family] = [
+        await emitFamily(family, [
           degradedResult({
             family,
             label: LABEL_BY_FAMILY[family] ?? family,
@@ -319,7 +393,7 @@ export async function collectQuota(options = {}) {
             source: loaded.paths[0] ?? resolveAuthPaths({ env, home: options.home })[0] ?? "~/.pi/agent/auth.json",
             now,
           }),
-        ];
+        ]);
         return;
       }
 
@@ -340,7 +414,7 @@ export async function collectQuota(options = {}) {
 
       const throttle = backoffState(family, { now, env, home: options.home });
       if (throttle.active && !options.force) {
-        byFamily[family] = [
+        await emitFamily(family, [
           degradedResult({
             family,
             label: LABEL_BY_FAMILY[family] ?? family,
@@ -351,7 +425,7 @@ export async function collectQuota(options = {}) {
             source: credentials[0].source,
             now,
           }),
-        ];
+        ]);
         return;
       }
 
@@ -404,7 +478,11 @@ export async function collectQuota(options = {}) {
       const results = [];
       const familyWarnList = [];
       for (const { result, warning, crashed } of outcomes) {
-        if (warning) familyWarnList.push(warning);
+        // The stored-credential warning is a claim about this run, and a provider
+        // that renewed the token in memory for it knows better than the store:
+        // "the Pi token expired 271316m ago" next to two healthy Antigravity
+        // windows was reading Pi's stale copy, not the token that was used.
+        if (warning && result.tokenRenewedInMemory !== true) familyWarnList.push(warning);
         if (!crashed) {
           // Bookkeeping must degrade like the provider call it follows: a
           // failing backoff write is a warning, never a rejected family.
@@ -426,8 +504,8 @@ export async function collectQuota(options = {}) {
         }
         results.push(result);
       }
-      byFamily[family] = results;
       familyWarnings[family] = familyWarnList;
+      await emitFamily(family, results);
     }),
   );
 
@@ -526,3 +604,16 @@ function refreshHint(credential) {
 export function firstForFamily(report, family) {
   return report.byFamily[family]?.[0] ?? null;
 }
+
+/**
+ * Collect a single family using the same normalized engine and callback
+ * semantics as collectQuota. This is useful to independent refresh schedulers:
+ * an in-flight family does not serialize another family's request.
+ *
+ * @param {string} family
+ * @param {Parameters<typeof collectQuota>[0]} [options]
+ * @returns {Promise<PiQuotaReport>}
+ */
+export function collectFamily(family, options = {}) {
+  return collectQuota({ ...options, families: [family] });
+}

package/src/local/pi-sessions.js

@@ -145,8 +145,22 @@ const RECENT_DAYS = 7;
  * @property {number} [now]            Report time; decides which local day is "today".
  * @property {number} [budgetMs]       Wall-clock budget for this scan.
  * @property {() => number} [clock]    Time source; tests inject one to drive the budget.
+ * @property {() => boolean} [shouldStop] The host wants the scan to end now (session shutdown, /reload).
+ * @property {(lock: { path: string, token: string | null }) => void} [onLock] Receives the lock
+ *   this scan holds, so a host that has to kill the worker can still release it.
  */
 
+/**
+ * The host asked the scan to stop. Thrown out of the scan loop so the `finally`
+ * releases the history lock and nothing after the interruption is written.
+ */
+export class LocalScanAbortedError extends Error {
+  constructor() {
+    super("local token stats scan stopped");
+    this.name = "LocalScanAbortedError";
+  }
+}
+
 /**
  * One session file's cache entry.
  *
@@ -1135,6 +1149,10 @@ export function buildLocalStats(input = {}) {
  * }>}
  */export async function collectLocalStats(options = {}) {
   const clock = options.clock ?? Date.now;
+  const hostStopped = options.shouldStop;
+  const stopNow = () => {
+    if (hostStopped?.() === true) throw new LocalScanAbortedError();
+  };
   const startedAt = clock();
   const now = options.now ?? Date.now();
   const today = localDayKey(now);
@@ -1164,6 +1182,9 @@ export function buildLocalStats(input = {}) {
   // delta twice. A run that cannot take it still answers, from what is on disk.
   const lockPath = `${cachePath}.lock`;
   const lock = acquireHistoryLock({ lockPath, now: clock() });
+  // The host gets the token, not just the path: whoever releases this lock must
+  // prove it is this scan's, never another run's.
+  if (lock.acquired) options.onLock?.({ path: lock.path, token: lock.token });
   if (!lock.acquired) {
     // Read-only path: `canWrite: false` keeps it from rebuilding or repairing
     // anything the run that does hold the lock is writing right now.
@@ -1277,6 +1298,7 @@ export function buildLocalStats(input = {}) {
     };
 
     for (const path of listen) {
+      stopNow();
       if (!keepLock()) break;
       if (!partial && overBudget()) partial = true;
       if (partial) break;
@@ -1373,7 +1395,7 @@ export function buildLocalStats(input = {}) {
           startOffset,
           days,
           now,
-          shouldStop: overBudget,
+          shouldStop: () => overBudget() || hostStopped?.() === true,
           onUsage: (usage) => {
             if (lastFrozenDay && usage.day <= lastFrozenDay) {
               // Frozen days are never reconstructed on a rescan. Incremental
@@ -1465,6 +1487,11 @@ export function buildLocalStats(input = {}) {
       };
     }
 
+    // A stop that arrived while the last file was being read has to end the run
+    // here: freezing days and writing the cache are the writes a shutdown must
+    // not race. Everything before this point is undoable read-only work.
+    stopNow();
+
     const openRows = buildOpenRows(next);
     const pendingBeforeApply = pendingLate.size;
     const applied = applyDurable({

package/src/local/stats-worker.js

@@ -0,0 +1,27 @@
+import { parentPort, workerData } from "node:worker_threads";
+
+import { LocalScanAbortedError, collectLocalStats } from "./pi-sessions.js";
+
+const options = workerData?.options ?? {};
+// A stop request is a flag the scan polls, not a message it has to be idle to
+// receive: a cold scan spends its time inside synchronous reads and hashing.
+const stopFlag = workerData?.stopFlag instanceof Int32Array ? workerData.stopFlag : null;
+
+try {
+  const result = await collectLocalStats({
+    ...options,
+    shouldStop: () => stopFlag !== null && Atomics.load(stopFlag, 0) === 1,
+    // The host keeps this handle: if it has to kill this thread, it can release
+    // the lock, and only with the token this scan created.
+    onLock: (lock) => parentPort?.postMessage({ type: "lock", path: lock.path, token: lock.token }),
+  });
+  parentPort?.postMessage({ type: "result", ok: true, result });
+} catch (error) {
+  // Do not serialize arbitrary error objects from the scanner into the host.
+  parentPort?.postMessage({
+    type: "result",
+    ok: false,
+    aborted: error instanceof LocalScanAbortedError,
+    error: "the scan failed",
+  });
+}