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.
Agent Island v1.7.1 stores Claude data, Codex data, a compatibility timestamp, and separate provider timestamps:
snapshot = {
claude,
codex,
updatedAt,
claudeUpdatedAt,
codexUpdatedAt
}
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.
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.
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
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.
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.
A useful policy test suite should prove that:
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.