Code FlowRun storage
Archive completed work to reduce retained detail in memory. Open an archived run to load its full evidence; archival caches do not replace the durable event log or delete worktrees by themselves.
Understand archived history
The append-only run event log and execution journal remain the source of truth. Startup recovers at most four runs concurrently, consuming fallback logs one record at a time. Recovery retains the latest run snapshot and latest state of each step; provider transcripts are read only when that run’s history is requested. It no longer builds an array containing every historical event log. A recovery record has a 64 MiB bound; exceeding it fails recovery visibly instead of silently dropping an ID.
Only archived, completed runs with no pending notes, follow-ups, approval, watch or unresolved remote execution can use cold storage. Running, interrupted, failed, stopped and unarchived runs remain in the normal live/resumable map. No worktrees or execution journals are removed by this optimization.
Each eligible run has optional runs/<id>.cold-index.json and runs/<id>.cold-detail.json projections. The compact index is at most 128 KiB; the full detail projection is at most 16 MiB. Oversized runs stay in the normal map. The projections carry checksums and exact source-file identities. A missing, damaged, changed or stale projection is rebuilt from the authoritative event log. They are caches, not a second source of truth.
Cold list/history entries explicitly return cold: true and detailAvailable: true. They preserve IDs, timestamps, repository/worktree ownership, parent/source/project provenance, source trust, pinned filesystem policies, permissions, usage, statistical counters and review attribution. Large task/summary previews are shortened, and heavy team graphs, context evidence, conventions and review prose are omitted. Open the run to read its complete metadata, transcript and evidence. Full-text history searches use indexed complete task and source/title text, including text beyond the preview. Legacy indexes obtain this text once during asynchronous startup; normal searches do not hydrate archived details.
Full metadata is read on demand through an eight-entry, 32 MiB least-recently-used cache. Individual reads are bounded to 16 MiB. A cold read returns a detached copy; mutation and Resume promote the complete run before changing it. Weak references preserve any still-held original live run handle during promotion without retaining archived full state. Updated data stays live until its queued event snapshot has been flushed and a matching cold projection has been saved. Source changes invalidate cached detail. Cold metadata is never used to reconstruct execution claims or substitute for journal replay.
History keeps every run ID and count. Cursor ordering uses creation time and run ID so runs created in the same millisecond are not skipped. Attention pagination includes every running run, plus at most 100 older attention items per page. Authorization filtering happens before totals and cursors. The response reports total attention, truncation and a continuation cursor; history remains available for older entries.
Reviewed retention manifests include both cold projection files when deleting their owner run. Their recent cache-generation time does not reset the original run’s retention age. Offline log compaction removes the derived cold projections so the next start rebuilds them. The normal backup and filesystem-policy boundaries continue to apply to these files.
This bounds retained full archived metadata and recovery batches. The compact index still grows with the number of recorded runs, and active/resumable runs remain in memory deliberately. The current UI reads bounded transcript pages directly by byte offset. Legacy stream clients and full exports can still request complete event history. Search uses an in-memory index, not a database. See Performance and resource boundaries for limits, diagnostics and benchmarks.