tokentracker-cli 1.5.2 → 1.5.3

package/src/lib/workbuddy-limits.js

@@ -19,10 +19,18 @@
 // Display names are English regardless of the backend's localized names.
 
 const fs = require("node:fs");
+const os = require("node:os");
 const path = require("node:path");
 const { resolveWorkbuddyHome } = require("./rollout");
 const { UNAVAILABLE, readWorkbuddyIpcDiscovery, openWorkbuddyIpc } = require("./workbuddy-ipc");
 
+const WORKBUDDY_LIMITS_CACHE_FILE = "workbuddy-usage-limits-cache.json";
+// Windows without a usable reset_at — the pooled resource window by design,
+// plus a plan row whose cycle end never parsed — cannot be checked against a
+// quota rollover, so they are only served while the snapshot is young enough
+// to trust.
+const WORKBUDDY_LIMITS_CACHE_UNKNOWN_RESET_TTL_MS = 12 * 60 * 60 * 1000;
+
 const PLAN_PRIORITY = Object.freeze({
   TCACA_code_027_0FCGVA6vSa: 4, // flagship
   TCACA_code_026_BaESVICNoi: 3, // advanced
@@ -451,12 +459,16 @@ function readAuthFile(filePath) {
   const auth = parsed?.auth;
   if (!auth || typeof auth !== "object") return null;
   const domain = isNonEmptyString(auth.domain) ? auth.domain.trim() : "";
+  // The app records the signed-in account next to its (often encrypted)
+  // session. The uid stays readable while the app is closed, so it is the
+  // one account signal that survives into the UNAVAILABLE state.
+  const uid = isNonEmptyString(parsed.account?.uid) ? parsed.account.uid.trim() : "";
   const token = auth.accessToken;
-  if (isNonEmptyString(token)) return { token: token.trim(), domain, encrypted: false };
+  if (isNonEmptyString(token)) return { token: token.trim(), domain, encrypted: false, uid };
   if (token && typeof token === "object" && token.$wbEncrypted === 1) {
-    return { token: null, domain, encrypted: true };
+    return { token: null, domain, encrypted: true, uid };
   }
-  return { token: null, domain, encrypted: false };
+  return { token: null, domain, encrypted: false, uid };
 }
 
 function resolveSession(variant, { env, authFiles, workbuddyHome }) {
@@ -464,15 +476,120 @@ function resolveSession(variant, { env, authFiles, workbuddyHome }) {
     ? authFiles
     : authSearchDirs(env, workbuddyHome).flatMap((dir) => variant.authFileNames.map((name) => path.join(dir, name)));
   let encryptedForVariant = false;
+  let encryptedUid = "";
   for (const filePath of files) {
     if (!filePath) continue;
     const session = readAuthFile(filePath);
     if (!session) continue;
     if (!hostAllowed(hostOf(session.domain), variant.allowedHostSuffixes)) continue;
-    if (session.token) return { token: session.token, encrypted: false, matched: true };
-    if (session.encrypted) encryptedForVariant = true;
+    if (session.token) return { token: session.token, encrypted: false, matched: true, uid: session.uid };
+    if (session.encrypted) {
+      encryptedForVariant = true;
+      // First encrypted candidate wins: when the app is closed this record is
+      // what a live read would authenticate with, so its account is the one
+      // the cached windows must match.
+      encryptedUid = encryptedUid || session.uid;
+    }
   }
-  return { token: null, encrypted: encryptedForVariant, matched: encryptedForVariant };
+  return { token: null, encrypted: encryptedForVariant, matched: encryptedForVariant, uid: encryptedUid };
+}
+
+// ---------------------------------------------------------------------------
+// Last-good disk cache for WorkBuddy quota windows (house pattern: codex /
+// ark / qoder / zcode, issue #952). A live read — IPC or API — persists the
+// windows per edition; when the live chain later fails, the stale windows are
+// served with data-age markers instead of a bare "Start WorkBuddy and sign
+// in". The steady state this covers is the app being closed: wbipc discovery
+// is gone and the encrypted session cannot be read.
+//
+// Editions never borrow each other's data: workbuddy CN and workbuddyAi are
+// separate partitions of one file, matching the edition-local socket
+// discipline. Partitions are also scoped to the login that produced the
+// windows, so an account switch followed by a live failure cannot serve the
+// previous account's bars.
+//
+// The cache identity comes from the session selection itself (resolveSession):
+// the record whose token supplies — or, while the app is closed, would supply
+// — the live read. It is the app's own account uid, readable after the app
+// closes when the encrypted session token is not, and it is an account id,
+// not a credential: nothing secret is persisted or hashed. An account the
+// records do not name ("unknown") matches only its own entries.
+
+function workbuddyLimitsCachePath({ home } = {}) {
+  return path.join(home || os.homedir(), ".tokentracker", "tracker", WORKBUDDY_LIMITS_CACHE_FILE);
+}
+
+// A window whose reset_at has already passed is stale data, not a usable
+// fallback — the quota has rolled over, so drop it. Undated windows (the
+// resource pool, or a plan row without a readable cycle end) cannot be
+// checked against a reset and are bounded by the snapshot-age TTL instead.
+function workbuddyCachedWindow(window, { cachedAtMs, nowMs } = {}) {
+  if (!window || typeof window !== "object") return null;
+  const resetAtMs = Date.parse(window.reset_at || "");
+  if (Number.isFinite(resetAtMs)) return resetAtMs > nowMs ? window : null;
+  return nowMs - cachedAtMs <= WORKBUDDY_LIMITS_CACHE_UNKNOWN_RESET_TTL_MS ? window : null;
+}
+
+/** Read the last-good windows for one edition, scoped to the login that wrote them. */
+function readWorkbuddyLimitsCache({ home, nowMs = Date.now(), variantId, identity } = {}) {
+  // An explicit home keeps the cache hermetic: callers that never said where
+  // the user's tracker state lives (tests, odd embedders) must not touch the
+  // developer's real cache file.
+  if (!home || !variantId || !identity) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(workbuddyLimitsCachePath({ home }), "utf8"));
+  } catch (_error) {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const raw = parsed[variantId];
+  if (!raw || typeof raw !== "object") return null;
+  if (raw.identity !== identity) return null;
+  const cachedAtMs = Date.parse(raw.cached_at || "");
+  if (!Number.isFinite(cachedAtMs) || cachedAtMs > nowMs + 60_000) return null;
+  const context = { cachedAtMs, nowMs };
+  const primaryWindow = workbuddyCachedWindow(raw.primary_window, context);
+  const secondaryWindow = workbuddyCachedWindow(raw.secondary_window, context);
+  // A partition whose windows all rolled or expired no longer describes the
+  // account's quota — withholding it lets the live error stay visible.
+  if (!primaryWindow && !secondaryWindow) return null;
+  return {
+    configured: true,
+    error: null,
+    plan_label: typeof raw.plan_label === "string" ? raw.plan_label : null,
+    primary_window: primaryWindow,
+    secondary_window: secondaryWindow,
+    cached: true,
+    stale: true,
+    cached_at: raw.cached_at,
+    source: "disk-cache",
+  };
+}
+
+/** Merge one edition's partition into the disk cache; best-effort, never throws. */
+function writeWorkbuddyLimitsCache(limits, { home, nowMs = Date.now(), variantId, identity } = {}) {
+  if (!home || !variantId || !identity || !limits?.configured || limits.error) return;
+  if (!limits.primary_window && !limits.secondary_window) return;
+  const cachePath = workbuddyLimitsCachePath({ home });
+  let payload = {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+    if (parsed && typeof parsed === "object") payload = parsed;
+  } catch (_error) {}
+  payload[variantId] = {
+    identity,
+    plan_label: typeof limits.plan_label === "string" ? limits.plan_label : null,
+    primary_window: limits.primary_window || null,
+    secondary_window: limits.secondary_window || null,
+    cached_at: new Date(nowMs).toISOString(),
+  };
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    const tmpPath = `${cachePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), { encoding: "utf8", mode: 0o600 });
+    fs.renameSync(tmpPath, cachePath);
+  } catch (_error) {}
 }
 
 function readProductEndpoint(workbuddyHome) {
@@ -584,19 +701,24 @@ function scopedEnv(env, home) {
   return next;
 }
 
-async function fetchVariant(variantId, opts = {}) {
-  const variant = variantById(variantId);
-  if (!variant) return { configured: false };
-  const env = scopedEnv(opts.env || process.env, opts.home);
-  const workbuddyHome = opts.workbuddyHome || resolveWorkbuddyHome(env, variant.source);
-  const installed = directoryExists(workbuddyHome);
+// Live chain for one edition, unchanged by the cache layer: the IPC proxy
+// while the app publishes it, then the API source with a resolvable session.
+// The session is selected by the caller (fetchVariant) so the cache identity
+// and the live read cannot disagree about the account. Throws propagate to
+// the cache wrapper below; the { configured: true, error: UNAVAILABLE }
+// result comes back when the app is closed and no session can be read.
+async function fetchVariantLive(variant, variantId, { env, workbuddyHome, installed, opts, session }) {
   const discovery = readWorkbuddyIpcDiscovery(workbuddyHome);
   if (discovery) {
     // Discovery is edition-local. Never fall back to the other edition's
     // socket or allow an explicitly redirected product to be mislabelled.
     const productEndpoint = readProductEndpoint(workbuddyHome);
     if (productEndpoint && !originAllowed(productEndpoint, variant)) {
-      throw new Error("WorkBuddy quota host does not match this edition.");
+      const error = new Error("WorkBuddy quota host does not match this edition.");
+      // Tagged so the cache wrapper surfaces the mislabelled host instead of
+      // stale bars from whichever login wrote them.
+      error.code = "EDITION_MISMATCH";
+      throw error;
     }
     const client = await openWorkbuddyIpc({
       discovery, signal: opts.signal, timeoutMs: opts.timeoutMs, connectImpl: opts.connectImpl,
@@ -607,10 +729,6 @@ async function fetchVariant(variantId, opts = {}) {
       client.close();
     }
   }
-  const explicitToken = resolveToken(variant, env);
-  const session = explicitToken
-    ? { token: explicitToken, encrypted: false, matched: true }
-    : resolveSession(variant, { env, authFiles: opts.authFiles, workbuddyHome });
   if (!session.token) {
     if (session.encrypted || installed) return { configured: true, error: UNAVAILABLE };
     if (!installed) return { configured: false };
@@ -625,12 +743,64 @@ async function fetchVariant(variantId, opts = {}) {
     workbuddyHome: opts.origin ? null : workbuddyHome,
   });
   if (!originAllowed(origin, variant)) {
-    throw new Error("WorkBuddy quota host does not match this edition.");
+    const error = new Error("WorkBuddy quota host does not match this edition.");
+    error.code = "EDITION_MISMATCH";
+    throw error;
   }
   return { ...await fetchPlanQuota((apiPath, body) => postBilling(fetchImpl,
     `${origin}${apiPath}`, session.token, body, opts.signal), variantId), source: "api" };
 }
 
+async function fetchVariant(variantId, opts = {}) {
+  const variant = variantById(variantId);
+  if (!variant) return { configured: false };
+  const env = scopedEnv(opts.env || process.env, opts.home);
+  const workbuddyHome = opts.workbuddyHome || resolveWorkbuddyHome(env, variant.source);
+  const installed = directoryExists(workbuddyHome);
+  // Sampled when used, not when the fetch starts: the live attempt can spend
+  // the whole provider budget before a cache read or write happens, and a
+  // window whose reset rolled in that span must not be served. An injected
+  // clock (tests) keeps every use on the same instant.
+  const nowMs = () => (Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now());
+  // One session selection feeds both the live attempt and the cache identity:
+  // cached windows are stamped with (and served only to) the account whose
+  // record supplies — or, while the app is closed, would supply — the session
+  // token. An env-token session names no record; "unknown" matches only its
+  // own entries.
+  const explicitToken = resolveToken(variant, env);
+  const session = explicitToken
+    ? { token: explicitToken, encrypted: false, matched: true, uid: "" }
+    : resolveSession(variant, { env, authFiles: opts.authFiles, workbuddyHome });
+  const identity = (explicitToken ? "" : session.uid) || "unknown";
+  let live;
+  try {
+    live = await fetchVariantLive(variant, variantId, { env, workbuddyHome, installed, opts, session });
+  } catch (error) {
+    // Re-login stays actionable (opencode-go auth_error / codex reauth
+    // precedent) and a mislabelled host is a configuration fault, not
+    // transient data loss: neither may be masked by stale bars.
+    if (error?.code === "AUTH_EXPIRED" || error?.code === "EDITION_MISMATCH") throw error;
+    const cached = readWorkbuddyLimitsCache({ home: opts.home, nowMs: nowMs(), variantId, identity });
+    if (cached) return cached;
+    throw error;
+  }
+  if (live.configured === true && !live.error) {
+    // Live read is current as of now: persist it so a later failure serves
+    // stale bars instead of a vanished card.
+    writeWorkbuddyLimitsCache(live, { home: opts.home, nowMs: nowMs(), variantId, identity });
+    return live;
+  }
+  if (live.configured === true && live.error) {
+    // The steady state the cache exists for (UNAVAILABLE: app closed, session
+    // unreadable) and transient API/IPC failures. A never-signed-in install
+    // ({ configured: false }) stays untouched — an edition that produced no
+    // windows here has nothing to fall back to.
+    const cached = readWorkbuddyLimitsCache({ home: opts.home, nowMs: nowMs(), variantId, identity });
+    if (cached) return cached;
+  }
+  return live;
+}
+
 function fetchWorkbuddyLimits(opts) {
   return fetchVariant("workbuddy", opts);
 }
@@ -651,6 +821,9 @@ module.exports = {
   readSubscriptionIdentity,
   originAllowed,
   hostAllowed,
+  readWorkbuddyLimitsCache,
+  writeWorkbuddyLimitsCache,
+  workbuddyLimitsCachePath,
   fetchWorkbuddyLimits,
   fetchWorkbuddyAiLimits,
 };

package/src/lib/zcode-limits.js

@@ -1156,6 +1156,10 @@ function readZcodeLimitsCache({ home, nowMs = Date.now(), providerKeys = [], ide
       configured: true,
       error: null,
       provider_key: providerKey,
+      // Live results carry their provider's region for the other_region
+      // attach; the cached shape mirrors them so a cache-served card keeps
+      // that section too (issue #959).
+      region: zcodeRegionFromProviderId(providerKey),
       plan_kind: typeof raw.plan_kind === "string" ? raw.plan_kind : null,
       plan_id: typeof raw.plan_id === "string" ? raw.plan_id : null,
       plan_label: typeof raw.plan_label === "string" ? raw.plan_label : null,
@@ -1172,27 +1176,23 @@ function readZcodeLimitsCache({ home, nowMs = Date.now(), providerKeys = [], ide
   return null;
 }
 
-/** Merge one provider partition into the disk cache; best-effort, never throws. */
-function writeZcodeLimitsCache(limits, { home, nowMs = Date.now(), providerKey, identity } = {}) {
-  if (!providerKey || !identity || !limits?.configured || limits.error) return;
-  if (!limits.primary_window && !limits.secondary_window && !limits.tertiary_window) return;
+/**
+ * Merge partitions into the disk cache atomically; best-effort, never throws.
+ * Cross-process semantics are last-writer-wins on purpose, matching the house
+ * pattern (ark / qoder / codex caches): a concurrent writer can discard a
+ * partition added between its read and rename, which costs one refresh cycle
+ * — the next fetch rewrites it. Snapshots in particular keep getting
+ * re-persisted on every fetch while their region's rows are inside the scan
+ * window, so a lost write self-heals long before the window expires.
+ */
+function mergeZcodeLimitsCacheEntries(entries, { home } = {}) {
   const cachePath = zcodeLimitsCachePath({ home });
   let payload = {};
   try {
     const parsed = JSON.parse(fs.readFileSync(cachePath, "utf8"));
     if (parsed && typeof parsed === "object") payload = parsed;
   } catch (_error) {}
-  payload[providerKey] = {
-    identity,
-    plan_kind: typeof limits.plan_kind === "string" ? limits.plan_kind : null,
-    plan_id: typeof limits.plan_id === "string" ? limits.plan_id : null,
-    plan_label: typeof limits.plan_label === "string" ? limits.plan_label : null,
-    buckets: Array.isArray(limits.buckets) ? limits.buckets : [],
-    primary_window: limits.primary_window || null,
-    secondary_window: limits.secondary_window || null,
-    tertiary_window: limits.tertiary_window || null,
-    cached_at: new Date(nowMs).toISOString(),
-  };
+  Object.assign(payload, entries);
   try {
     fs.mkdirSync(path.dirname(cachePath), { recursive: true });
     const tmpPath = `${cachePath}.${process.pid}.tmp`;
@@ -1201,28 +1201,129 @@ function writeZcodeLimitsCache(limits, { home, nowMs = Date.now(), providerKey,
   } catch (_error) {}
 }
 
+/** Merge one provider partition into the disk cache; best-effort, never throws. */
+function writeZcodeLimitsCache(limits, { home, nowMs = Date.now(), providerKey, identity } = {}) {
+  if (!providerKey || !identity || !limits?.configured || limits.error) return;
+  if (!limits.primary_window && !limits.secondary_window && !limits.tertiary_window) return;
+  mergeZcodeLimitsCacheEntries({
+    [providerKey]: {
+      identity,
+      plan_kind: typeof limits.plan_kind === "string" ? limits.plan_kind : null,
+      plan_id: typeof limits.plan_id === "string" ? limits.plan_id : null,
+      plan_label: typeof limits.plan_label === "string" ? limits.plan_label : null,
+      buckets: Array.isArray(limits.buckets) ? limits.buckets : [],
+      primary_window: limits.primary_window || null,
+      secondary_window: limits.secondary_window || null,
+      tertiary_window: limits.tertiary_window || null,
+      cached_at: new Date(nowMs).toISOString(),
+    },
+  }, { home });
+}
+
+// Issue #959: ZCode only queries the balance of the region currently in use,
+// so the other region's log rows stop appearing the moment it goes idle and
+// then age out of the 6h scan window — the other_region section would vanish.
+// While a region's rows are still fresh, snapshot its latest record into a
+// per-region cache partition; withZcodeOtherRegion falls back to it after the
+// window expires. The snapshot shape comes straight from
+// normalizeZcodeBalanceResponse, so the no-reset_credits / no-start_plan red
+// line holds structurally. Log records carry no login id, so unlike the
+// windows partitions there is no identity guard here: staleness is
+// self-attested by the snapshot's log_timestamp (rendered as the section's
+// time row), and the section stays collapsed and informational.
+function zcodeLogSnapshotCacheKey(region) {
+  return `log-snapshot:${region}`;
+}
+
+function writeZcodeLogSnapshotCache(byRegion, { home, nowMs = Date.now() } = {}) {
+  if (!(byRegion instanceof Map) || byRegion.size === 0) return;
+  const entries = {};
+  for (const [region, record] of byRegion) {
+    if (region !== "bigmodel" && region !== "zai") continue;
+    let normalized;
+    try {
+      normalized = normalizeZcodeBalanceResponse(record.body);
+    } catch (_error) {
+      continue;
+    }
+    entries[zcodeLogSnapshotCacheKey(region)] = {
+      source: "zcode-log",
+      region,
+      provider_key: record.providerKey,
+      log_timestamp: record.log_timestamp,
+      ...normalized,
+      cached_at: new Date(nowMs).toISOString(),
+    };
+  }
+  if (Object.keys(entries).length > 0) mergeZcodeLimitsCacheEntries(entries, { home });
+}
+
+/**
+ * Read one region's persisted log snapshot, shaped exactly like the fresh
+ * withZcodeOtherRegion attach (issue #938). Deliberately no per-window
+ * expiry: clipping aged windows would make the cached section render
+ * differently from the same record served fresh inside the scan window.
+ */
+function readZcodeLogSnapshotCache(region, { home, nowMs = Date.now() } = {}) {
+  if (region !== "bigmodel" && region !== "zai") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(zcodeLimitsCachePath({ home }), "utf8"));
+  } catch (_error) {
+    return null;
+  }
+  const raw = parsed?.[zcodeLogSnapshotCacheKey(region)];
+  if (!raw || typeof raw !== "object" || raw.source !== "zcode-log" || raw.region !== region) return null;
+  if (!Number.isFinite(Date.parse(typeof raw.log_timestamp === "string" ? raw.log_timestamp : ""))) return null;
+  const cachedAtMs = Date.parse(typeof raw.cached_at === "string" ? raw.cached_at : "");
+  if (!Number.isFinite(cachedAtMs) || cachedAtMs > nowMs + 60_000) return null;
+  return {
+    source: "zcode-log",
+    region,
+    provider_key: typeof raw.provider_key === "string" ? raw.provider_key : null,
+    log_timestamp: raw.log_timestamp,
+    plan_kind: typeof raw.plan_kind === "string" ? raw.plan_kind : null,
+    plan_id: typeof raw.plan_id === "string" ? raw.plan_id : null,
+    plan_label: typeof raw.plan_label === "string" ? raw.plan_label : null,
+    buckets: Array.isArray(raw.buckets) ? raw.buckets : [],
+    primary_window: raw.primary_window || null,
+    secondary_window: raw.secondary_window || null,
+    tertiary_window: raw.tertiary_window || null,
+  };
+}
+
 /**
  * Attach the freshest logged balance snapshot from the user's other region
  * (issue #938): ZCode's own usage logs carry both regions' billing data even
- * when only the active region's credentials are on disk. The snapshot is
+ * when only the active region's credentials are on disk. Once those rows age
+ * out of the 6h scan window (ZCode only queries the active region's balance,
+ * issue #959), fall back to the snapshot persisted by
+ * writeZcodeLogSnapshotCache while they were fresh. Either way the section is
  * read-only and deliberately carries no reset_credits / start_plan extras —
  * those are login-scoped and must never ride along across regions.
  */
-function withZcodeOtherRegion(result, byRegion) {
+function withZcodeOtherRegion(result, byRegion, { home, env = process.env, nowMs = Date.now() } = {}) {
   if (!result || result.error || !result.region) return result;
   const otherRegion = result.region === "bigmodel" ? "zai" : "bigmodel";
   const record = byRegion instanceof Map ? byRegion.get(otherRegion) : null;
-  if (!record) return result;
-  return {
-    ...result,
-    other_region: {
-      source: "zcode-log",
-      region: otherRegion,
-      provider_key: record.providerKey,
-      log_timestamp: record.log_timestamp,
-      ...normalizeZcodeBalanceResponse(record.body),
-    },
-  };
+  if (record) {
+    return {
+      ...result,
+      other_region: {
+        source: "zcode-log",
+        region: otherRegion,
+        provider_key: record.providerKey,
+        log_timestamp: record.log_timestamp,
+        ...normalizeZcodeBalanceResponse(record.body),
+      },
+    };
+  }
+  // Saved snapshots are log-derived data, so the log-fallback kill switch
+  // silences them along with the scan that feeds them.
+  if (env?.TOKENTRACKER_ZCODE_DISABLE_LOG_FALLBACK === "1") return result;
+  const snapshot = readZcodeLogSnapshotCache(otherRegion, { home, nowMs });
+  if (!snapshot) return result;
+  return { ...result, other_region: snapshot };
 }
 
 /**
@@ -1264,8 +1365,9 @@ function loadZcodeLoginScopedTokens(family, auth, { home, env } = {}) {
  * logs, and finally the last-good disk cache. The result carries the winning
  * provider's `region` ("bigmodel" | "zai") and, when ZCode's own logs hold one,
  * an `other_region` snapshot of the second region's plan (issue #938) — read-only
- * log data, never extended with login-scoped extras. Credentials and internal
- * team routing identifiers are omitted from the result.
+ * log data, never extended with login-scoped extras, served from the logs while
+ * fresh and from the disk cache once the scan window expires (issue #959).
+ * Credentials and internal team routing identifiers are omitted from the result.
  */
 async function fetchZcodeLimits({ home, env, fetchImpl = fetch, nowMs = Date.now(), providerTimeoutMs } = {}) {
   const startedAt = Date.now();
@@ -1283,11 +1385,15 @@ async function fetchZcodeLimits({ home, env, fetchImpl = fetch, nowMs = Date.now
     providerKeys: authCandidates.map((auth) => auth.providerKey),
     nowMs,
   });
+  // Issue #959: capture each region's freshest log record while it is still
+  // inside the scan window, so the other_region section survives the window
+  // expiring (ZCode stops writing rows for a region the moment it goes idle).
+  writeZcodeLogSnapshotCache(logScan.byRegion, { home, nowMs });
   const requireProviderMatch = authCandidates.some((auth) => auth.planKind === "coding-plan");
   const selectLogFallback = (errors) => {
     const record = logScan.preferred
       || (requireProviderMatch && authCandidates.length > 0 ? null : logScan.fallback);
-    return withZcodeOtherRegion(zcodeLogFallbackResult(record, errors), logScan.byRegion);
+    return withZcodeOtherRegion(zcodeLogFallbackResult(record, errors), logScan.byRegion, { home, env, nowMs });
   };
   if (!authCandidates.length) {
     return selectLogFallback([]) || { configured: false };
@@ -1403,13 +1509,13 @@ async function fetchZcodeLimits({ home, env, fetchImpl = fetch, nowMs = Date.now
           }
         }
       }
-      return withZcodeOtherRegion(result, logScan.byRegion);
+      return withZcodeOtherRegion(result, logScan.byRegion, { home, env, nowMs });
     } catch (error) {
       errors.push(`${auth.providerKey}: ${error?.message || "Unknown error"}`);
       partitionFailures.push({ providerKey: auth.providerKey, authError: error?.authError === true });
     }
   }
-  if (emptySuccess) return withZcodeOtherRegion(emptySuccess, logScan.byRegion);
+  if (emptySuccess) return withZcodeOtherRegion(emptySuccess, logScan.byRegion, { home, env, nowMs });
   // Rank fallback partitions in live candidate priority order, and withhold
   // any partition whose attempts all ended in auth errors: re-login is
   // actionable, so neither a stale log record nor stale cache bars may mask
@@ -1428,7 +1534,7 @@ async function fetchZcodeLimits({ home, env, fetchImpl = fetch, nowMs = Date.now
   // A log record for a provider with no live candidate is untouched by this
   // gate: nothing was attempted for it, so no error is being masked.
   if (logRecord && !authErrorOnlyProviders.has(logRecord.providerKey)) {
-    return withZcodeOtherRegion(zcodeLogFallbackResult(logRecord, errors), logScan.byRegion);
+    return withZcodeOtherRegion(zcodeLogFallbackResult(logRecord, errors), logScan.byRegion, { home, env, nowMs });
   }
   // Last stop before the error result: serve the disk cache in live candidate
   // priority order, scoped to the login that produced the windows so an
@@ -1440,7 +1546,7 @@ async function fetchZcodeLimits({ home, env, fetchImpl = fetch, nowMs = Date.now
     identityByKey.get(auth.providerKey).add(zcodeCacheIdentity(loginIdFor(zcodeProviderFamily(auth.providerKey)), auth.teamContext));
   }
   const cached = readZcodeLimitsCache({ home, nowMs, providerKeys: cacheEligible, identityByKey });
-  if (cached) return withZcodeOtherRegion(cached, logScan.byRegion);
+  if (cached) return withZcodeOtherRegion(cached, logScan.byRegion, { home, env, nowMs });
   return {
     configured: true,
     error: errors[0] || "Unknown error",
@@ -1474,6 +1580,8 @@ module.exports = {
   fetchZcodeStartPlanGrants,
   readZcodeLimitsCache,
   writeZcodeLimitsCache,
+  writeZcodeLogSnapshotCache,
+  readZcodeLogSnapshotCache,
   zcodeCacheIdentity,
   fetchZcodeLimits,
 };