PR #26487: fix(cli): speed up --resume / /resume session listing

• Repository: google-gemini/gemini-cli
• Author: dimssu
• State: open | merged: False
• Link: https://github.com/google-gemini/gemini-cli/pull/26487

Description (problem / solution / changelog)

Summary

gemini --resume and the interactive /resume command hang for ~10–15 s on Windows before any UI appears. Profile-guided fix: stop streaming and JSON.parse'ing every saved chat file just to extract listing metadata.

Details

Root cause (in loadConversationRecord at packages/core/src/services/chatRecordingService.ts:106 and getAllSessionFiles at packages/cli/src/utils/sessionUtils.ts:246):

1. getAllSessionFiles fans out via Promise.all over every *.jsonl in ~/.gemini/projects/<hash>/chats/, calling loadConversationRecord(file, { metadataOnly: true }) per file.
2. Per file, loadConversationRecord did:
   • A synchronous fs.existsSync(filePath) (line 118) — with N parallel calls all on one JS thread, the existsSync wave blocked the event loop. That's why even SessionBrowserLoading doesn't paint during the hang.
   • Streamed the entire JSONL through readline + JSON.parse per line, just to compute messageCount, firstUserMessage, hasUserOrAssistantMessage, and the latest $set.

On Windows, AppData is typically scanned by Defender / indexed, so each fs syscall costs 100–200 ms. With 10–30 saved sessions that easily lands at 10–15 s before first paint, exactly matching the report.

Fix:

1. Per-session metadata sidecar <base>.meta.json next to each chat file, containing only the listing-needed fields (sessionId, projectHash, startTime, lastUpdated, kind, summary, directories, messageCount, userMessageCount, hasUserOrAssistantMessage, firstUserMessage; version: 1 for future migrations). Written atomically (tmp + rename) by ChatRecordingService on init / pushMessage / updateMetadata / rewindTo, and removed alongside the .jsonl in deleteSessionAndArtifacts, deleteCurrentSessionAsync, and cleanupExpiredSessions. The retention cleanup pass uses a new lazyMigrate: false flag on getAllSessionFiles so it doesn't backfill sidecars for sessions it's about to delete.
2. Drop the fs.existsSync in loadConversationRecord. The for await over readline already errors via the existing try/catch; ENOENT is now silently swallowed in the catch to keep log parity.
3. Read path in getAllSessionFiles prefers the sidecar; on miss / malformed / version mismatch it falls back to the existing JSONL stream parse and opportunistically backfills the sidecar (lazy migration, no upgrade step needed). Search mode (includeFullContent: true) still streams full files — unchanged.

Net effect: listing goes from O(N × full-file-parse) to O(N × tiny-file-read). All three forms (latest, <uuid>, <index>) become sub-second; numeric-index ordering is unchanged because the sidecar still exposes startTime.

No public API or persisted-format changes for the .jsonl itself; .meta.json is a new but additive on-disk file the user can safely delete (it'll be regenerated).

Related Issues

Closes #26478

How to Validate

1. npm ci && npm run build
2. Populate session history: npm run start and hold a few short conversations to seed ~/.gemini/projects/<hash>/chats/ with 10+ sessions of varying sizes. Confirm *.meta.json files appear next to each .jsonl.
3. Time the resume forms (all should reach first paint sub-second on macOS, dramatically faster on Windows):
   • time node bundle/gemini.js --resume (latest)
   • time node bundle/gemini.js --resume <uuid>
   • time node bundle/gemini.js --resume 1 (numeric index)
4. From inside the CLI, run /resume — the dialog should render its Loading… state immediately and populate within a few hundred ms.
5. Lazy migration check: rm a *.meta.json, run /resume, confirm the listing still works and the sidecar is rewritten afterwards.
6. Delete check: from /resume, delete a session, confirm both the .jsonl and .meta.json are removed.
7. Retention check (optional): with general.sessionRetention.enabled: true, restart and verify expired sessions remove both .jsonl and .meta.json.

Targeted unit tests:

• npm test -w @google/gemini-cli-core -- chatRecordingService.test
• npm test -w @google/gemini-cli -- sessionUtils.test sessionCleanup.integration.test

Full suites:

• npm run test --workspace @google/gemini-cli-core → 7214 / 7214 pass
• npm run test --workspace @google/gemini-cli → 6750 / 6750 pass
• npm run typecheck ✅ — npm run lint:ci ✅

Pre-Merge Checklist

• Updated relevant documentation and README (no doc changes needed — sidecar is internal)
• Added/updated tests (sidecar lifecycle, lazy migration, version mismatch, kind=subagent skip, sessionCleanup orphan removal, and missing-file ENOENT path)
• Noted breaking changes — none
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows (the platform of original concern — would value a maintainer spot-check here)
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

Changed files

• packages/cli/src/utils/sessionCleanup.ts (modified, +20/-1)
• packages/cli/src/utils/sessionUtils.test.ts (modified, +198/-0)
• packages/cli/src/utils/sessionUtils.ts (modified, +123/-71)
• packages/core/src/services/chatRecordingService.test.ts (modified, +119/-0)
• packages/core/src/services/chatRecordingService.ts (modified, +207/-3)