Troubleshooting

Checklist debug từ PATH, status, Codex hook đến SSH authentication và log files.

1. Luôn bắt đầu bằng status

Khi báo lỗi, ghi lại Herdr version, OS, terminal và local/remote context.

herdr -V
herdr status

2. herdr: command not found

command -v herdr
echo "$PATH"
source ~/.bashrc

Nếu cài bằng package manager, update và PATH phải theo package manager đó.

3. Codex integration không hoạt động

codex --version
ls -la ~/.codex
herdr integration status
herdr integration status --outdated-only
herdr integration install codex

Config directory của Codex phải tồn tại trước khi Herdr install integration.

4. Remote attach không authenticate

# Test OpenSSH trước
ssh workbox

# Nếu key có passphrase, đảm bảo ssh-agent đã load key
ssh-add -l

Nếu SSH bình thường chưa hoạt động, sửa SSH trước rồi mới debug Herdr remote.

5. Diagnostic logs

ls -lah ~/.config/herdr/
tail -n 200 ~/.config/herdr/herdr-server.log
tail -n 200 ~/.config/herdr/herdr-client.log

# Debug logging
HERDR_LOG=herdr=debug herdr

6. Chiến lược reset an toàn

1. Detach thay vì kill nếu chỉ muốn thoát UI.
2. Backup config trước khi sửa mạnh.
3. Nếu keybindings rối: herdr config reset-keys.
4. Chỉ herdr server stop khi chấp nhận các process trong panes dừng.