Skip to content

feat(terminal): keep recent sessions warm - #195

Draft
Lint111 wants to merge 2 commits into
Ark0N:masterfrom
Lint111:agent/split-warm-terminal-cache
Draft

feat(terminal): keep recent sessions warm#195
Lint111 wants to merge 2 commits into
Ark0N:masterfrom
Lint111:agent/split-warm-terminal-cache

Conversation

@Lint111

@Lint111 Lint111 commented Jul 29, 2026

Copy link
Copy Markdown

Summary

  • keep the active terminal and two recently viewed sessions in a bounded 30-second live range
  • restore eligible revisits from the in-memory xterm snapshot plus an ordered, capped live delta
  • skip the canonical terminal fetch only when stream coverage and the rendered snapshot were both confirmed before demotion
  • invalidate replay on clear, backpressure, transport recovery, overflow, expiry, deletion, and forced reload
  • serialize subscription updates and use the same per-tab transport identity as the terminal WebSocket

Why

Every session switch currently downloads and replays the terminal tail. On mobile, rapid switches can expose stale frames, repeat expensive xterm parsing, and make recently viewed sessions feel cold even though their rendered state is already in memory.

This change keeps a small recent range live. A quick switch-back becomes:

  1. restore the prior rendered snapshot;
  2. apply terminal bytes received while the session was inactive; and
  3. flush live bytes queued during the switch transaction.

Any uncertainty falls back to the existing canonical fetch.

Correctness Boundaries

  • A retained entry is not automatically replayable.
  • Replay eligibility is frozen when a canonical, subscription-confirmed active session is demoted.
  • A late subscription acknowledgement cannot retroactively validate a potentially gapped snapshot.
  • Clear and recovery events increment a replay generation, so an in-flight restore cannot commit stale state.
  • Async recovery handlers recheck active-session ownership after network and chunked-write awaits.
  • Shell sessions are removed when demoted because they do not use xterm snapshot restoration.
  • The cache is capped at three sessions and 256K JavaScript characters of delta per entry.

Dependencies

Merge order:

  1. feat(terminal): add bounded snapshot and history streaming #189 adds the backend per-tab transport ID, explicit empty subscription, bounded snapshot/history, and transport handoff contracts.
  2. fix(terminal): preserve replay and history ownership #193 adds caller-owned terminal replay transactions.
  3. This PR adds the bounded recent-session client cache.

This branch temporarily includes 92dbe64 from #193 and should be rebased after #193 merges. It does not duplicate #189. Before #189 is present, the extended subscription ID is rejected and entries remain ineligible, so the client safely uses canonical loads.

Commit Structure

Out Of Scope

Validation

  • npx vitest run --config config/vitest.config.ts test/warm-terminal-cache.test.ts test/terminal-flush-budget.test.ts test/codex-snapshot-replay.test.ts test/terminal-buffer-flush.test.ts - 26 passed
  • npm run check:lockfile
  • npm run typecheck
  • npm run lint
  • npm run check:frontend-syntax
  • npm run check:public-assets
  • npm run format:check
  • npm run build
  • git diff --check

The unsafe bare full-suite path was not run; its destructive quick-start fixture is isolated separately in #175.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant