Frozen-panel retention (instant switch-back to recent sessions)

What it is

Normally, when you switch away from a session its chat panel is torn down to a lightweight shell to save memory. When you switch back, Omniscio has to rebuild the heavy view — re-parse the markdown, re-highlight the code, rebuild the DOM — which on a long conversation can show a brief "loading" shell before the chat appears.

Frozen-panel retention keeps the sessions you've looked at most recently fully built in memory while they're hidden — the way a web browser keeps a handful of background tabs ready — so switching back to one is instant. There is no rebuild and no loading shell; the already-built panel is simply shown again. The name is the model: a hidden retained panel is "frozen" (mounted but not updating), and revealing it is just a visibility flip.

On top of keeping the panel built, Omniscio re-applies its scroll position before the panel is painted (the pre-paint reveal), so a retained session reappears already scrolled to where it belongs — with no momentary jump or flash on the way in. This is on by default and also smooths switching into inbox / Needs-You panels; its own field kill switch is AMC_DISABLE_PREPAINT_REVEAL. The engineering detail lives in the session-switch-prepaint contract.

This is a performance setting, not a workflow change. With it on, recent sessions just feel snappier to return to. Nothing about how you use sessions changes.

It is off by default (opt-in, since 2026-08-25) — it trades memory for speed, so Omniscio does not turn it on for you, and nothing turns it on for existing installs. It is a fully reversible layer on top of the existing renderer: with the setting off (or the kill switch set) Omniscio behaves exactly as it did before the feature existed — the off path is unchanged.

Where to find it

Turning it on or off

It is off until you turn it on. To get instant switch-back to recent sessions, go to Settings → Performance → "Keep recent sessions instant" and turn it on. To go back to the rebuild-on-switch behaviour, turn it off again in the same place.

The toggle's own description reads: "Keep the sessions you've looked at recently fully built in memory (the way a browser keeps background tabs ready) so switching back to one is instant instead of rebuilding it. Only applies to sessions that aren't actively streaming, and a small limit caps how many are held so memory stays bounded. Off by default — it trades memory for speed."

There is no restart required — flipping it on starts retaining panels from your next session visit; flipping it off immediately reverts hidden panels to shells and lets memory reclaim them.

How it behaves

When it applies

• The session is not actively streaming (it's idle / ended / paused / waiting on you / errored — anything except a running or starting session).
• You have viewed it recently — retention follows the visit. A session only becomes retainable after it has been the on-screen session at least once this app run (that visit is what loads its conversation into memory in the first place).
• It is among the most recently viewed sessions, within the cap (see Limits below). Ping-pong between two or three sessions and they all stay instant.

When it does NOT apply

• Streaming sessions (green — running / starting). A live session's view is changing token-by-token, so "instant return to the same view" is meaningless for it; those are already kept responsive by the separate keep-alive pool.
• Sessions you haven't visited this run. Retention never pre-builds a panel you haven't opened — it only keeps already-built recent ones around.
• Sessions popped out into their own window (detached) — they already have their own live panel; retention won't mount a second copy.
• When the cap is exceeded. Only the most-recent N are retained; older ones fall off and rebuild normally on next click (graceful — never a blank, just the same rebuild you get today).
• When the feature is off — every session switch behaves exactly as it did before this feature shipped.

A retained panel will never show stale or blank content: if a hidden session's conversation has been dropped from memory, it is removed from the retained set and falls back to the normal fetch-on-click path with its loading shell — i.e. it degrades to today's behaviour, never to a wrong empty chat.

Limits and memory

Each retained panel is a full heavy chat view (markdown + syntax highlighting + DOM), so the feature is deliberately bounded:

• At most 12 panels are retained at once (MAX_RETAINED_PANELS), most-recently viewed first; the rest rebuild on click.
• Omniscio remembers the last 32 session ids you viewed (VISITED_ORDER_CAP) as the input to that selection — a cheap list of strings, not panels.
• Runtime-only. The retained set lives in memory for the life of the app process and is not saved to disk — every launch starts empty and only fills as you navigate. So there is no boot-time memory cost.

These caps are conservative on purpose. They stack on top of the keep-alive pool's own budget rather than replacing it, so the two never fight over the same panels.

The kill switch

There are two independent off-switches, and the kill switch always wins:

1. The Settings toggle above (frozenPanelRetentionEnabled, default off).
2. An environment kill switch: launch Omniscio with AMC_DISABLE_FROZEN_PANELS=1 and the feature is forced off even if the setting is on. This is the field escape hatch — if retention ever misbehaved, this disables it without touching your settings. A missing or malformed switch is treated as "not killed," so the setting alone governs in the normal case.

How it relates to the other "instant session" features

Three separate layers make sessions feel fast; this is the third:

• Lazy content load makes the first time you open any session paint quickly, regardless of length.
• Scroll position memory returns you to where you were scrolled when you come back to a session.
• Frozen-panel retention (this page) keeps the whole built panel of recent, non-streaming sessions in memory so the return itself is instant — no rebuild.

It is an additive layer on top of the keep-alive pool (which keeps the active session and live/attention sessions mounted). The two sets never overlap: a session kept alive by the pool is never separately retained, so there's no double-mounting and no double memory cost.

For agents

Where it lives in code

• src/renderer/src/features/dashboard/frozen-panel-retention.ts — the pure LRU selector selectRetentionIds(...), the isRetainableStatus non-streaming gate, and the MAX_RETAINED_PANELS / VISITED_ORDER_CAP bounds.
• src/renderer/src/lib/frozen-panel-flag.ts — isFrozenPanelRetentionEnabled(setting): setting first, then the AMC_DISABLE_FROZEN_PANELS kill switch wins.
• src/renderer/src/features/dashboard/Dashboard.tsx — tracks the recently-viewed order, computes the retained set, unions it into the conversation-cache eviction guard, and mounts pool ∪ retained as one panel set.
• src/renderer/src/features/sessions/SessionPanel.tsx — shouldRenderHeavy folds in a retained term so a retained hidden panel renders heavy instead of as a shell.
• src/preload/index.ts — bridges the AMC_DISABLE_FROZEN_PANELS env var to the renderer before first paint.

The full engineering contract (test-locked invariants + safe-change checklist) is the "frozen-panel retention" section of .claude/memory/contracts/keep-alive-pool-contract.md.

Related

• lazy-content-load.md — instant first cold-mount of a long session.
• scroll-position-memory.md — restores scroll position on return.
• real-conversation-layout.md — the default chat render that retention keeps built.