OpenClaw Memperbaiki Bug Cleanup Worktree: Nested Repository Tidak Boleh Dihapus Sembarangan

Auto-cleanup memang dibuat untuk menghapus worktree yang sudah tidak dipakai. Masalahnya, satu folder bisa berisi repository lain yang lifecycle-nya tidak dimiliki oleh proses cleanup tersebut.

Itu yang terjadi di OpenClaw pada branch main: automatic cleanup dapat salah memperlakukan nested repository sebagai bagian dari state yang boleh dihapus. Pada skenario tertentu, linked worktree yang berisi file lokal belum di-commit ikut terhapus. Pada skenario lain, proses cleanup gagal membuat snapshot lalu mengulang warning yang sama setiap Gateway startup dan hourly maintenance sweep.

Issue resmi #129414 sudah ditutup pada 25 Agustus 2026. Fix upstream kemudian masuk melalui commit 4070461 dan merge commit 34067fc. Artikel ini membahas bug-nya, kenapa root cause-nya penting untuk sistem agentic, dan apa yang perlu diuji sebelum mengaktifkan cleanup otomatis di environment yang menyimpan kerja manusia atau agent.

Keputusan operasional: jangan menyamakan "berada di repository Git yang sama" dengan "boleh dihapus oleh lifecycle OpenClaw". Saat target cleanup berisi nested repository atau linked worktree, default yang aman adalah mempertahankannya kecuali ada record ownership yang jelas.

Bug-nya bukan sekadar salah hapus folder

OpenClaw punya managed worktree untuk session dan workboard. Setelah melewati retention window, worktree dapat masuk ke jalur garbage collection. Sebelum fix, classifier cleanup memakai informasi dari Git untuk menentukan apakah nested checkout masih dianggap disposable.

Ada dua bentuk masalah yang dilaporkan upstream:

1. Nested repository independen. Repository lain berada di dalam worktree OpenClaw. Snapshot lossless tidak bisa memasukkan seluruh state repository tersebut, sehingga removal seharusnya berhenti. Namun record yang tertahan terus dicoba lagi pada sweep berikutnya dan menghasilkan warning berulang.
2. Ignored linked worktree dari repository yang sama. Nested checkout terlihat sebagai linked worktree dari outer repository. Karena identitas Git-nya sama, cleanup menganggapnya boleh ikut dibersihkan. Padahal nested path itu tidak punya record managed-worktree OpenClaw yang membuktikan bahwa lifecycle-nya dimiliki oleh cleanup outer.

Skenario kedua yang paling berbahaya. Issue upstream membuat linked checkout yang di-ignore, menulis local.txt di dalamnya, lalu menjalankan garbage collection. Implementasi lama menghapus outer checkout dan nested checkout tersebut. File lokal yang belum di-commit hilang bersama path-nya.

Root cause: identitas Git dipakai sebagai otoritas lifecycle

Git bisa menjawab pertanyaan seperti:

• apakah path ini berada di bawah repository tertentu;
• apakah nested checkout terdaftar sebagai linked worktree;
• file apa yang tracked, ignored, atau untracked;
• apakah ada gitlink pada index.

Git tidak menjawab pertanyaan yang lebih penting untuk operasi destructive:

Proses mana yang memiliki otoritas untuk menghancurkan path ini?

Dalam bug ini, dua pertanyaan tersebut tercampur. Shared Git common directory dianggap cukup untuk menyimpulkan bahwa outer managed worktree boleh menghapus nested linked worktree. Padahal hubungan repository belum tentu sama dengan hubungan ownership aplikasi.

Ini pola yang sering muncul di sistem automation. Sebuah tool melihat path berada di bawah direktori yang ia kelola, lalu menganggap semua isi di dalamnya ikut menjadi miliknya. Asumsi itu aman untuk file temporary yang dibuat tool sendiri. Asumsi yang sama berbahaya untuk repository, database, secret, cache agent, atau checkout yang dibuat manusia.

Batas yang benar seharusnya berbasis lifecycle ownership. Jika nested worktree punya record OpenClaw sendiri, ia dapat dibersihkan melalui record tersebut. Jika tidak ada record, outer cleanup harus menganggapnya sebagai state terpisah dan mempertahankannya.

Mengapa warning berulang juga merupakan masalah produksi?

Nested repository independen biasanya ditolak saat snapshot karena OpenClaw tidak dapat menyimpan seluruh isinya secara lossless. Itu perilaku fail-closed yang benar. Yang tidak benar adalah membiarkan record yang sama masuk ke percobaan cleanup berikutnya tanpa hasil yang lebih informatif atau perubahan state.

Issue #129414 mencatat warning yang berulang pada startup dan sweep per jam. Pada satu Gateway, tiga worktree terdampak mencatat puluhan warning identik. Ini bukan hanya masalah log yang berisik. Ada tiga dampak operasional:

• alert penting bisa tertutup oleh error yang sama;
• operator mengira cleanup sedang berjalan, padahal state lama terus tertahan;
• investigasi menjadi lebih lambat karena gejala muncul pada scheduler, bukan saat repository nested pertama kali dibuat.

Gateway memang menjalankan managed-worktree cleanup segera setelah siap dan kemudian secara berkala. Karena itu, bug pada cleanup path dapat berubah menjadi noise permanen selama service hidup.

Apa yang diperbaiki upstream?

Commit fix 4070461 mengubah aturan automatic cleanup pada tiga jalur: idle cleanup, limit eviction, dan run-end cleanup.

Aturan barunya lebih sederhana:

• nested Git repository dan linked worktree diperlakukan sebagai ownership boundary terpisah;
• outer worktree dipertahankan jika nested repository terdeteksi;
• nested OpenClaw worktree dibersihkan melalui managed-worktree record miliknya sendiri;
• automatic cleanup tidak lagi memberi pengecualian hanya karena linked worktree berasal dari repository Git yang sama;
• test real-Git memastikan file lokal nested tetap ada dan warning cleanup tidak berulang.

Perbaikannya bukan sekadar mengganti satu kondisi if. Source dan test upstream memperluas guard yang sama ke beberapa jalur cleanup, termasuk batas count dan size. Test juga mencakup repository independen, linked worktree dari repository yang sama, repository yang hanya menyisakan metadata .git, serta cleanup saat run berakhir.

Ini detail penting. Guard yang hanya dipasang pada idle cleanup masih menyisakan jalur lain untuk menghapus state. Untuk operasi destructive, invariant keselamatan harus dipakai bersama oleh semua entry point, bukan ditambal satu per satu setelah ada laporan baru.

Status dampaknya untuk pengguna OpenClaw

Issue upstream menyebut reproduksi pada current main, bukan bukti bahwa semua instalasi OpenClaw terdampak. Review upstream juga mencatat bahwa perubahan yang memperkenalkan perilaku berisiko berada di current main dan belum ada pada stable tag v2026.7.1-2 yang diperiksa saat review.

Jadi framing yang tepat bukan "semua pengguna OpenClaw kehilangan repository". Framing-nya:

• branch atau build tertentu punya cleanup behavior yang berisiko;
• dampak muncul bila managed worktree berisi nested repository atau linked worktree;
• status fix harus diverifikasi terhadap commit atau release yang benar-benar dipakai;
• reinstall atau upgrade binary tanpa memeriksa jalur cleanup tidak cukup sebagai bukti aman.

Fix sudah masuk upstream dan issue ditutup. Namun downstream package, channel beta, atau build internal bisa memiliki posisi commit yang berbeda. Sebelum rollout, cek apakah target Anda sudah memuat commit perbaikan dan jalankan fixture test pada build yang sama.

Checklist pengujian untuk environment agentic

Kalau sistem Anda membuat dan menghapus checkout secara otomatis, pengujian minimalnya tidak boleh berhenti pada "worktree kosong berhasil dihapus".

1. Uji nested repository independen

Buat repository utama, letakkan repository lain di dalam path yang mungkin di-ignore, lalu isi file lokal di repository nested. Jalankan setiap mode cleanup yang tersedia. Outer worktree dan seluruh isi nested harus tetap ada.

2. Uji linked worktree dari repository yang sama

Buat linked worktree di dalam outer managed worktree. Jangan daftarkan nested path itu ke registry lifecycle tool. Tambahkan file lokal yang belum di-commit. Cleanup outer harus mempertahankan nested checkout tersebut.

3. Uji repository tanpa file kerja

Jangan hanya menguji nested repository yang punya banyak file. Repository yang terlihat kosong tetapi masih menyimpan .git tetap merupakan ownership boundary. Test upstream menambahkan skenario metadata-only karena detector yang hanya mencari file biasa bisa melewatkannya.

4. Uji semua entry point

Jalankan idle cleanup, limit eviction berbasis jumlah, limit eviction berbasis ukuran, dan run-end cleanup. Hasil aman pada satu entry point tidak membuktikan jalur lain aman.

5. Cek dua hal setelah cleanup

Jangan hanya memeriksa apakah outer folder hilang. Periksa juga:

• file lokal nested masih bisa dibaca;
• linked worktree masih terdaftar di Git jika memang belum dimiliki lifecycle tool;
• registry aplikasi tidak menandai nested path sebagai removed;
• log tidak mengulang warning yang sama pada sweep kedua.

Prinsip yang bisa dipakai di luar Git

Kasus ini relevan untuk lebih banyak hal daripada OpenClaw. Scheduler, CI runner, backup job, dan automation agent sering bekerja di bawah satu root directory. Di dalamnya bisa ada state dengan owner yang berbeda.

Rule praktisnya:

1. Path containment bukan bukti ownership. Direktori anak belum tentu boleh dihapus parent process.
2. Relationship bukan authority. Dua checkout bisa berbagi repository, storage, atau database tanpa berbagi lifecycle.
3. Fail closed untuk destructive action. Jika ownership tidak terbukti, pertahankan state dan catat alasan yang bisa ditindaklanjuti.
4. Gunakan guard yang sama di semua jalur. Idle, quota, shutdown, retry, dan manual cleanup harus memakai invariant keselamatan yang konsisten.
5. Test state lokal yang tidak terlihat oleh status utama. File ignored, metadata-only repository, lease, lock, dan uncommitted state sering menjadi bagian yang hilang dari happy-path test.

Cleanup otomatis memang mengurangi pekerjaan rutin. Tetapi begitu ia diberi hak menghapus state, ia harus diperlakukan seperti migrasi database atau deploy production: ownership, snapshot, rollback, dan evidence perlu dibuktikan sebelum action destructive dijalankan.

Kesimpulan operasional

Bug OpenClaw #129414 menunjukkan batas yang mudah dilupakan: repository Git yang sama tidak otomatis berarti lifecycle yang sama. Sebelum fix, asumsi itu membuat automatic cleanup menghapus linked worktree nested yang tidak pernah didaftarkan sebagai milik OpenClaw. Repository independen yang aman dipertahankan juga menghasilkan warning berulang karena jalur cleanup terus mencoba ulang.

Fix upstream mengembalikan aturan yang lebih sehat: nested repository dan linked worktree adalah batas ownership. Outer cleanup harus mempertahankannya, dan hanya record lifecycle yang jelas yang boleh menjadi dasar penghapusan.

Untuk tim yang mengoperasikan agent atau automation di production, keputusan praktisnya jelas: verifikasi commit fix pada build target, uji nested repository independen dan linked worktree, lalu pastikan semua jalur cleanup memakai guard fail-closed yang sama. Jangan menerima "path berada di bawah folder saya" sebagai bukti bahwa state itu aman untuk dihapus.

Referensi primer

• Issue OpenClaw #129414: Automatic worktree cleanup can delete nested user repositories
• Commit fix 4070461: preserve nested repositories during cleanup
• Merge commit 34067fcc: fix worktrees dan test coverage
• PR #128761: stop repeated startup cleanup errors
• OpenClaw managed worktrees documentation
• Gateway maintenance cleanup caller