agent's checksum cache was poisoned by a partial download and verification failed

TL;DR

A checksum cache is only trustworthy if entries are written after complete, verified downloads. A partial download that still writes its computed-so-far hash poisons every later check that trusts it. Write cache entries atomically only after size and hash verification passes, include the expected hash in the cache key, and evict and recompute any entry tied to an interrupted transfer.

agent's checksum cache was poisoned by a partial download and verification failed

Use this when

• Verification fails repeatedly for a file that verifies fine when downloaded fresh elsewhere.
• The first failure followed an interrupted or timed-out download.
• Clearing the agent cache makes the failure vanish once, then it can return after another interruption.

Not for this skill when

• The file in the repository is genuinely corrupt. Fresh downloads fail too, which exonerates the cache.
• The agent reads production cache instead of the restore. Provenance problem.

Steps

1. Reproduce by comparing the cached hash for the suspect file with a freshly computed hash of a complete download. Verify: cache and reality disagree, proving poisoning
2. Audit the cache write path for when entries are created relative to download completion. Verify: the premature write point is found
3. Change caching to write only after full size and hash checks pass, using a temporary entry promoted atomically. Verify: killing a download mid-way leaves no cache entry in tests
4. Key entries by object identifier plus expected hash or version so stale entries cannot masquerade as current. Verify: a changed object misses the old cache entry
5. Evict all entries created before the fix for affected repositories and run verification. Verify: checks pass on verified downloads

Variant phrasings

checksum cache poisoned partial download verification

The poisoning phrasing.

stale hash cache agent false corruption

The false-alarm variant.

cache only verified downloads atomic entry

The design wording.

Compatibility: Agents verifying restic, Borg, S3 and file-based backups with local checksum or metadata caches in Python and TypeScript.

Why it happens

Caches trade correctness risk for speed, and the risk concentrates exactly at failure boundaries: the interrupted download is both when wrong data appears and when bookkeeping is sloppiest. If the cache records the hash of whatever bytes arrived, later checks compare the repository against the accident, not against the truth, and report phantom corruption with total confidence.

Edge cases / pitfalls

• A cache that cannot be trusted is worse than no cache. Measure hit benefit before keeping the feature.
• Store the verification evidence with the cache entry so its provenance can be audited.
• After any poisoning incident, assume sibling entries from the same window are suspect. Evict by time range.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstj8IrpS2GK79QZOLCPAJUg