Bug Hermes Agent 0.21.0: Chat Desktop Bisa Gagal Dibuka saat SQLite WAL Sibuk

Hermes Agent 0.21.0 punya bug operasional baru di jalur pembacaan database session. Saat beberapa profile atau proses aktif menulis ke state.db dalam mode WAL, pembacaan read-only dapat sesaat menerima sqlite3.OperationalError: disk I/O error. Desktop lalu gagal membuka chat atau membuat daftar session tampak hilang sampai refresh berikutnya.

Ini bukan kelanjutan otomatis dari risiko korupsi SQLite yang pernah dibahas pada 0.19.0. Issue yang memicu patch terbaru justru lolos PRAGMA integrity_check, dan percobaan membuka chat lagi berhasil. Masalahnya ada pada cara Hermes memperlakukan error pembacaan yang transient sebagai kegagalan permanen.

Fix sudah masuk branch main pada 2 September 2026 melalui commit 3a0e7df, disusul hardening UI pada 3d81650. Namun stable terbaru masih Hermes Agent 0.21.0 dengan tag v2026.8.31. Jadi instalasi stable belum boleh diasumsikan membawa perbaikan tersebut.

Gejala yang perlu dicari

Laporan resmi issue #100436 datang dari Desktop dengan sepuluh bot profile aktif. Pengguna sesekali melihat pesan "Couldn't open 's chat - try again". Klik kedua biasanya berhasil.

Pada log, kegagalannya berada di jalur GET /api/sessions. Hermes membuka database profile secara read-only, lalu memeriksa tabel FTS. Pemeriksaan itu berhenti dengan disk I/O error dan endpoint mengembalikan HTTP 500.

Issue tersebut diberi label bug P2 dan risiko session state. Pelapor menjalankan integrity check pada database utama dan profile yang gagal; hasilnya tetap ok. FTS scan dan query juga berjalan normal. Artinya, gejala ini tidak boleh langsung diterjemahkan sebagai database rusak.

Laporan lain, issue #100871, menemukan error sekelas pada WSL2 dengan state.db di ext4 yang ditopang VHDX. Kasus itu terjadi pada multi-process deployment setelah upgrade ke 0.21.0 dan menyentuh jalur SessionDB.get_session. Reproduksinya belum deterministik, jadi issue tersebut masih perlu diperlakukan sebagai field report, bukan bukti bahwa semua instalasi WSL2 pasti terdampak.

Kenapa WAL yang sehat bisa memunculkan disk I/O error

SQLite WAL memungkinkan reader dan writer bekerja bersamaan. Namun reader yang dibuka dengan mode=ro tidak dapat melakukan recovery tertentu karena proses itu perlu menulis index -shm.

Menurut penjelasan commit fix resmi, window singkat dapat muncul ketika writer sedang melakukan checkpoint, reset atau truncate WAL, atau menyelesaikan frame flush. Reader yang masuk tepat pada window itu bisa menerima SQLITE_IOERR, meskipun database dan storage sehat. Window-nya hanya hitungan milidetik.

Bug Hermes ada pada respons terhadap kondisi tersebut:

1. read-only open atau FTS probe gagal satu kali;
2. tidak ada bounded retry untuk SQLITE_IOERR;
3. error langsung naik ke endpoint session;
4. Desktop membaca respons gagal atau daftar kosong sebagai state terbaru;
5. chat tidak terbuka, atau row session idle menghilang sementara dari sidebar.

timeout=1.0 tidak menyelesaikan kasus ini. Busy timeout membantu lock contention, sedangkan SQLITE_IOERR langsung gagal dan membutuhkan klasifikasi serta retry tersendiri.

Fix yang sudah masuk main

Commit resmi 3a0e7df mengubah perilaku di beberapa lapisan.

Pertama, read-only opener mendapat retry terbatas dengan backoff pendek. Commit menetapkan tiga attempt dengan jeda 50 milidetik untuk error disk I/O error. Jika masalahnya transient, pembacaan berikutnya dapat berhasil. Jika error terus muncul, Hermes tetap menghentikan retry dan meneruskannya sebagai kegagalan storage.

Kedua, error database yang diklasifikasikan sementara dipetakan menjadi HTTP 503, bukan 500. Maknanya berbeda: session store sedang sibuk dan client harus mempertahankan daftar lama, bukan menganggap data sudah kosong.

Ketiga, jalur write hanya mengulang BEGIN IMMEDIATE bila error terjadi sebelum callback mutasi berjalan. Setelah callback dimulai, status transaksi bisa tidak pasti sehingga operasi tidak diulang sembarangan. Ini penting agar perbaikan reliability tidak menciptakan duplikasi write.

Commit lanjutan 3d81650 memperkuat Desktop. Jika scan profile gagal, row session sebelumnya untuk profile tersebut tetap dipertahankan. Profile yang berhasil dibaca masih menjadi sumber kebenaran. Daftar benar-benar dikosongkan hanya ketika backend mengembalikan page kosong tanpa error.

Ada pull request komunitas #100474 yang mencoba memperbaiki gejala serupa dan mencatat 190 test lulus. PR itu ditutup tanpa merge. Operator sebaiknya mengacu ke commit yang benar-benar ada di branch resmi main, bukan menambal production dengan patch PR yang ditutup.

Jangan salah membedakan transient error dan korupsi

Teks disk I/O error tetap bisa menandakan masalah storage nyata. Fix di main tidak menelan semua error. Retry dibatasi; kegagalan yang persisten tetap muncul.

Gunakan pola berikut untuk triage:

• Jika retry manual segera berhasil, integrity check ok, dan error hanya muncul ketika banyak writer aktif, transient WAL read window masuk akal.
• Jika error terus terjadi saat fleet idle, periksa filesystem, permission, fd, kernel log, free space, serta kondisi -wal dan -shm.
• Jika PRAGMA quick_check atau integrity_check gagal, perlakukan database sebagai suspect. Hentikan writer secara terkontrol sebelum mengambil backup atau melakukan recovery.
• Jika session benar-benar hilang dari database, jangan menyimpulkan ini hanya masalah sidebar. Bug UI yang dibahas di sini mempertahankan row lama saat scan gagal; ia tidak memulihkan data yang sudah terhapus.

Artikel sebelumnya tentang risiko korupsi SQLite WAL pada Hermes Agent 0.19.0 membahas bug SQLite upstream yang berbeda dan dapat menyebabkan kerusakan data. Kasus 0.21.0 ini berfokus pada pembacaan transient dan penanganan UI, dengan integrity check yang tetap sehat pada laporan utama.

Mitigasi aman untuk pengguna stable 0.21.0

Belum ada tag stable baru setelah v2026.8.31. Sampai fix dirilis, langkah paling aman adalah mengurangi dampak tanpa membuat perubahan storage spekulatif.

1. Retry satu kali sebelum melakukan recovery

Jika chat gagal dibuka sekali, refresh atau buka ulang. Jangan langsung menjalankan repair database hanya karena satu disk I/O error. Simpan timestamp dan cocokkan dengan log agar pola concurrent writer dapat dilihat.

2. Periksa kesehatan database secara read-only

Jalankan PRAGMA quick_check; atau PRAGMA integrity_check; melalui interpreter dan environment yang benar-benar dipakai Hermes. Lakukan saat beban terkendali dan jangan mencetak konfigurasi atau credential ke log.

3. Kurangi writer yang tidak perlu

Issue WSL2 melibatkan gateway, dashboard, dan CLI yang berbagi satu state.db. Pastikan tidak ada gateway atau agent duplikat yang hidup tanpa sengaja. Untuk Bot Mode, kurangi jumlah backend aktif bila error muncul berulang selama aktivitas profile.

4. Jangan pindah ke journal mode DELETE sebagai reaksi pertama

Reporter issue #100871 menguji WAL dan DELETE pada salinan database yang sama. Benchmark sintetisnya tidak mereproduksi IOERR, tetapi mode DELETE membuat read throughput turun dari sekitar 5,1 juta menjadi 174 operasi selama fase uji dan menghasilkan ratusan lock contention. Angka itu hanya berlaku pada harness reporter, bukan benchmark universal. Pesannya tetap jelas: DELETE dapat mengubah error sesekali menjadi bottleneck permanen pada deployment multi-process.

5. Jangan menyalin commit main langsung ke production tanpa canary

Branch main sudah ratusan commit di depan stable saat audit dilakukan. Mengambil dua commit secara manual dapat berbenturan dengan perubahan state, Desktop, dan test matrix lain. Jalur yang lebih aman adalah menunggu release bertag, lalu menguji pada satu canary dengan salinan data dan backup yang dapat dipulihkan.

Checklist verifikasi setelah patch stable tersedia

Saat release berikutnya membawa fix ini, uji skenario yang benar-benar memicu risiko:

• buka Desktop dengan beberapa profile aktif;
• jalankan turn bersamaan agar masing-masing profile menulis session;
• refresh sidebar dan pindah chat berulang kali;
• pastikan satu scan gagal tidak mengosongkan row session lain;
• periksa respons transient menjadi 503, bukan 500 atau page kosong yang dianggap final;
• verifikasi persistent storage error tetap muncul setelah retry budget habis;
• jalankan quick check sebelum dan setelah canary;
• restart Desktop dan gateway, lalu pastikan session lama tetap muncul;
• cocokkan versi runtime dengan tag dan commit yang benar-benar aktif.

Jangan berhenti pada "chat bisa dibuka". Periksa juga recents, cron session, messaging session, usage per profile, dan row idle dari hari sebelumnya. Commit UI terbaru secara khusus memperbaiki metadata serta row yang dapat ikut terhapus sementara saat satu profile gagal discan.

Keputusan operasional

Bug ini material untuk operator Hermes Agent 0.21.0 yang memakai Desktop, Bot Mode, banyak profile, atau beberapa proses pada database session yang sama. Dampaknya terutama availability dan konsistensi tampilan session. Laporan utama tidak menemukan korupsi, tetapi error persisten tetap harus diperlakukan sebagai masalah storage sampai terbukti sebaliknya.

Fix di branch main sudah punya arah yang tepat: retry hanya pada window yang aman, bedakan busy dari damaged, pertahankan sidebar lama saat scan gagal, dan jangan mengulang write setelah status transaksi menjadi tidak pasti.

Untuk production, tahan diri dari hot-patch dan perubahan journal mode yang terburu-buru. Pantau log, verifikasi database, kurangi process churn, dan tunggu release bertag yang memuat commit 3a0e7df serta hardening Desktop 3d81650.

Sumber primer

• Hermes Agent issue #100436: transient read-only FTS probe
• Hermes Agent issue #100871: field report WSL2 multi-process
• Commit 3a0e7df: bounded SQLite retry dan HTTP 503
• Commit 3d81650: Desktop mempertahankan row saat scan gagal
• Hermes Agent 0.21.0 / v2026.8.31