MC-4882

## RE-SCOPED 2026-06-09 (Lucienne): manifest approach — the warmer didn't work The in-process TTL cache (MC-4873) + background warmer (first MC-4882 attempt, commit 6e19e1a) does NOT reliably kill the cold scan: verified live `/reports` = 20.8s after 90s idle (warmer doesn't keep the gthread workers' caches warm; -w2, no --preload). DO NOT just retry the thread. Replace with a DURABLE SHARED MANIFEST so a full 340-file scan NEVER happens in the request path. ## Design - Manifest file: `PKA-Outputs/_state/reports-index.json` (Luci path `/home/lucienne/gdrive/PKA-Outputs/_state/reports-index.json`) listing every report: {rel, title, date, type, mtime, base}. - MC `/reports` LISTING reads the manifest (fast JSON) instead of scanning + reading ~340 files. It's a FILE shared by all workers → worker-count-proof (the thing that broke the in-proc cache). - A `rebuild_reports_manifest()` scans both bases (cloud + ~/workspace/reports), writes JSON ATOMICALLY (tmp + os.replace). Triggered OUT of the request path: a scheduled refresh (every ~5-10 min) and/or after a report is written. The expensive scan runs in the builder, never in a user request. - Listing falls back to the current live scan if the manifest is missing/unreadable (so it NEVER breaks). May keep the short TTL cache as a thin extra layer or remove it. ## Constraints - NON-BREAKING: manifest absent/corrupt → fall back to live scan (current behavior). Atomic manifest write (tmp+rename); tolerant read. - Don't change report SERVING. Preserve listing content + order (date desc) + full count. - Do NOT deploy live yourself — produce review-required evidence; Lucienne (controller) guarded-deploys. ## Verification (before review-required) - `/reports` cold (FRESH worker / after >TTL idle) < 2s — manifest read, NO 340-file scan (the actual goal that the warmer failed) - A newly-added report appears in the listing within the refresh window - Listing count + order unchanged vs live scan; a report serves 200; board / loads - app.py parses; tests pass ## Terminal-state report REQUIRED: STATUS, 1-line, commit SHA, literal /reports cold-timing(seconds) + counts, follow-ups. Don't deploy live.