Skip idle disk-state scans until expiration

[Alek99]

The disk-state write worker lists and stats every state file on every idle tick, even when no file can expire. Remember the earliest possible expiration and skip disk cleanup until that deadline. Persisted writes and lifetime changes invalidate the cached scan; a generation check preserves invalidation during concurrent writes, and the worker reports the lifetime actually used so configuration changes cannot mislabel a deadline.

With 10,000 unexpired files, the idle disk-cleanup portion of a tick measured 32.60 ms before versus 0.0014 ms for the deadline guard (nine alternating pairs on Python 3.14.5 / Apple M5 Pro). This excludes the rest of the write worker and its queue delay. Startup and due scans still inspect the directory; this targets idle I/O.

Validation:

• Full unit suite: 8,304 passed, 18 skipped, 75.98% coverage.
• Worker regression verifies that idle ticks skip scans and expired files are removed. Additional tests cover newly discovered files, lifetime changes, clock rollback, and write/configuration races.
• Both disk benchmark cases, repository-wide Ruff and Pyright passed.

Independent of the other performance drafts; based directly on main.

[greptile-apps]

Greptile Summary

This PR caches the next possible disk-state expiration deadline so idle write-worker ticks can avoid unnecessary directory scans.

• Invalidates the cached deadline after persisted writes and token-lifetime changes.
• Uses a write generation to avoid publishing scan results invalidated by concurrent writes.
• Adds unit coverage for expiration deadlines, configuration changes, clock changes, and scan/write interleavings.
• Adds benchmarks for idle checks with 100 and 10,000 state files.

Confidence Score: 4/5

The implementation appears behaviorally sound, but the repository's explicit documentation requirement for time calculations must be satisfied before merging.

No correctness or security failure remains supported; the only accepted finding is the missing human-readable duration explanation required for the new deadline arithmetic.

Files Needing Attention: reflex/istate/manager/disk.py

Important Files Changed

Filename	Overview
reflex/istate/manager/disk.py	Adds deadline-based scan suppression and generation-aware cache invalidation; the new time calculations need the human-readable duration comment required by repository rules.
tests/units/istate/manager/test_disk.py	Adds focused regression coverage for idle scans, new files, lifetime changes, clock movement, and concurrent invalidation.
tests/benchmarks/test_disk_expiration.py	Benchmarks the guarded idle expiration path across small and large state directories.
news/+idle-disk-state-cleanup.performance.md	Documents the user-visible disk-cleanup performance improvement.

_{Reviews (1): Last reviewed commit: "Skip idle disk-state scans until expirat..." | Re-trigger Greptile}

[greptile-apps]

Duration Comments Missing

The new deadline calculations here and on line 122 add token_expiration directly to timestamps without a comment explaining the duration or unit in human-readable terms. This violates the repository requirement for documenting time-based calculations and must be addressed before merging.

Rule Used: When using time-based calculations in code, includ... (source)

Learned From
reflex-dev/flexgen#2190

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[codspeed-hq]

Merging this PR will not alter performance

✅ 32 untouched benchmarks
🆕 2 new benchmarks
⏩ 8 skipped benchmarks¹

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
🆕	test_idle_disk_expiration_check[100]	N/A	138.7 µs	N/A
🆕	test_idle_disk_expiration_check[10000]	N/A	114.6 µs	N/A

---

_{Comparing codex/perf-disk-expiration-scheduling (77194ca) with main (c49a85d)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩