DEV Community

Agent Island
Agent Island

Posted on • Originally published at agent-island.dev

Do Not Let One Provider Refresh Make Another Provider's Cache Look Fresh

#ai #opensource #softwareengineering #tooling

A desktop usage view needs a cache for cold starts and temporary network failures. The dangerous shortcut is giving the entire snapshot one freshness timestamp.

If Claude refreshes successfully while Codex fails, rewriting the shared cache with a new timestamp can silently extend the life of old Codex data. The values are still different, but their trust boundary has been collapsed.

The fix is to model freshness where failure happens: per provider.

Store the value and its age together

Agent Island v1.7.1 stores Claude data, Codex data, a compatibility timestamp, and separate provider timestamps:

snapshot = {
  claude,
  codex,
  updatedAt,
  claudeUpdatedAt,
  codexUpdatedAt
}
Enter fullscreen mode Exit fullscreen mode

The overall timestamp remains useful for decoding older records and rejecting obviously old snapshots. It does not authorize both provider values to restore.

This is an important distinction. A shared file is an implementation detail. It is not a shared freshness guarantee.

Empty and error responses are not fresh usage

A provider result should be cacheable only when the relevant windows have no error and at least one real signal exists: a positive percentage or a reset timestamp.

A plan label with two zero-percent windows is not enough. Authentication failures and empty responses often produce clean-looking shapes. Caching those shapes turns missing evidence into a confident 0%.

Error-bearing values are also unsafe even when they carry percentages from an earlier successful fetch. Those percentages may be useful for the current screen, but saving them with the new time launders stale data into a fresh cache entry.

Partial success may preserve, but never renew

Consider a refresh where Claude succeeds and Codex times out. The snapshot can save Claude's new value while carrying forward the last valid Codex value. The timestamps must tell the truth:

claude value: new          claudeUpdatedAt: now
codex value: preserved     codexUpdatedAt: old timestamp
Enter fullscreen mode Exit fullscreen mode

If neither provider produced fresh cacheable data, do not write a new snapshot. Repeated failures must not extend the cache indefinitely.

An unfetched provider follows the same rule. It may retain a previously valid value, but it never receives a fresh timestamp simply because its peer was fetched.

Restore providers independently

During restore, compare each provider timestamp with the maximum age. Claude may restore while Codex expires, or the other way around.

That behavior is more honest and more useful than rejecting the whole snapshot. A partial outage can still show one verified provider without presenting both with the same confidence.

Schema evolution needs the same care. A provider response may contain one meaningful usage window and explicitly omit another. It remains cacheable when the real window contains usage or reset evidence. Requiring two fully populated windows would turn a valid response into a permanent cache miss.

Tests that catch timestamp laundering

A useful policy test suite should prove that:

  • Error-bearing preserved usage cannot create or renew a snapshot.
  • Plan-only zero-percent data cannot restore as healthy usage.
  • Real usage keeps its percentage and reset time while cache errors are stripped.
  • Fresh Claude data can preserve old Codex data without changing the Codex timestamp.
  • An unfetched provider never gets a fresh timestamp.
  • Restore can keep one provider and expire the other.
  • A valid single-window response remains cacheable.

Keep the measurement boundary explicit

Cache correctness improves the honesty of a usage display. It does not change what the metric means.

Usage percentages and local API-value estimates are not subscription invoices, savings, revenue, user counts, or installs. A technically correct cache should not be used to make a stronger business claim than the underlying source supports.

The reusable rule is straightforward:

Scope freshness to the failing dependency, never renew data you did not fetch, and require evidence before turning an empty response into 0%.

The full policy, compatibility behavior, and product boundary are in the canonical engineering article. The Agent Island v1.7.1 source is public under MIT.

Top comments (0)