infrastructure/WALKTHROUGH.md

# WALKTHROUGH — Infrastructure (капитанский журнал)

Хронология работ, команд, решений и ошибок. Цель — воспроизводимость.

---

## 2026-09-12 — Инцидент: зависший davfs2 (Яндекс.Диск), «не работает systemd»

### Симптом
- Бэкапы на /mnt/yandex-disk не сделались (встали).
- Любое обращение к /mnt зависает: `ls /mnt`, `ls /mnt/yandex-disk` — висят без ошибки.
- «systemd не работает»: сервисы не управляются.

### Разбор (по шагам)
1. `grep yandex /proc/mounts` → точка жива: `https://webdav.yandex.ru /mnt/yandex-disk fuse rw,...`
   - Это ручное/скриптовое монтирование, а НЕ systemd unit.
2. `systemctl status mnt-yandex-disk.mount` → «could not be found». **Причина «сломанного systemd»**: точка смонтирована мимо unit-а, systemd ею не управляет и «не находит» её. Не systemd виноват, а ресурс, которым он пытается управлять.
3. `ps aux | grep davfs` → демон живой: `/sbin/mount.davfs https://webdav.yandex.ru /mnt/yandex-disk -o rw uid=1000 file_mode=600 dir_mode=700` (процесс). FUSE-соединение есть (/sys/fs/fuse/connections), но запросы не обслуживаются.
4. `curl -I https://webdav.yandex.ru` → отвечает 302 мгновенно. **Сервер жив, сеть жива — завис только локальный FUSE-мост** (клиент davfs2), а не сервер.

### Почему «всё висит»
FUSE-драйвер, который не обслуживает запросы, не выдаёт ошибку — он молчит. Любой syscall (readdir/stat) к этой точке уходит в FUSE и ждёт ответа; процесс висит, пока ядро не таймаутнет. Отсюда ощущение «зависла вся система»: любой процесс, дотронувшийся до /mnt/yandex-disk, встаёт.

### Лечение (данные не теряются — они в облаке)
```bash
# 1. Найти PID демона
ps aux | grep mount.davfs
# 2. Убить жёстко (-15 демон в подвешенном состоянии не обработает)
sudo kill -9 <PID>
# 3. Размонтировать (davfs может ругнуться на пропавший pid — это нормально)
sudo umount /mnt/yandex-disk
# 4. Убрать осиротевший pid-файл, чтобы следующий старт был чистым
sudo rm -f /var/run/mount.davfs/mnt-yandex-disk.pid
# 5. Проверить, что размонтировано
grep yandex /proc/mounts   # пусто
# 6. Смонтировать заново (креды из /etc/davfs2/secrets)
sudo mount.davfs https://webdav.yandex.ru /mnt/yandex-disk \
  -o rw,uid=1000,file_mode=600,dir_mode=700
# 7. Проверить глубину
ls /mnt/yandex-disk/projects
ls /mnt/yandex-disk/obsidian/mozg
```
Результат: точка смонтирована, каталоги отвечают мгновенно, данные на месте.

### Конфиг монтирования (/etc/fstab)
```
https://webdav.yandex.ru  /mnt/yandex-disk  davfs  _netdev,auto,rw,uid=1000,file_mode=600,dir_mode=700  0  0
```
Секреты: /etc/davfs2/secrets (root:root 600).

### Выводы / правила на будущее
1. Сетевые диски (WebDAV/SMB/NFS через FUSE) — самое хрупкое звено. Выглядят как папки, но это процессы, которые могут замереть тихо, без логов.
2. «Не отвечает systemd» = «не отвечает ресурс, которым systemd управляет». Проверять цепочку: сервис → точка монтирования → процесс → сеть.
3. `curl -I` на источник ДО убийства монтирования — 10 секунд уверенности, что лечим клиента, а не сервер.
4. Бэкап на сетевой диск — не бэкап. Нужна вторая дверь (или watchdog, который тихо перемонтирует).
5. Watchdog (открытая задача в TODO): детектор «/mnt/yandex-disk не отвечает > N сек» → тихое перемонтирование, без шума (cron no_agent).

### Артефакты
- Статус: STATUS.md
- Задачи: TODO.md
- Пост для блога: (опыт был подготовлен как техноблог-пост в сессии)

---

## 2026-09-10 — herdr: установка плагина herdr-sidebar

### Задача
Поставить плагин alexarthurs/herdr-sidebar (VS Code-style сайдбар для herdr) и разобраться с особенностями установки.

### Ход работы
1. `herdr plugin install alexarthurs/herdr-sidebar` → ошибка `No such file or directory (os error 2)`.
   - Причина: монорепо — плагин в поддиректории. Правильная команда:
     ```
     herdr plugin install alexarthurs/herdr-sidebar/plugins/herdr-sidebar --yes
     ```
2. Установка прошла, но `herdr plugin list` под пользователем estorozhenko показал «No plugins installed».
   - **Причина (важный кейс):** herdr хранит конфиг/плагины в `$HOME/.config/herdr/` — привязка к `$HOME`, а не к бинарю. Я ставил с `HOME=/opt/hermes/.hermes/home` (сессия агента), поэтому плагин ушёл в `/opt/hermes/.hermes/home/.config/herdr/`, а пользователь смотрит в `/home/estorozhenko/.config/herdr/`.
   - Лечение: переустановка от имени пользователя:
     ```
     sudo -u estorozhenko -H /home/estorozhenko/.local/bin/herdr plugin install alexarthurs/herdr-sidebar/plugins/herdr-sidebar --yes
     ```
   - Проверка: `sudo -u estorozhenko -H /home/estorozhenko/.local/bin/herdr plugin list` → `herdr-sidebar (enabled)`.
3. Nerd Font: при первом запуске бинарь herdr-sidebar спрашивает про JetBrainsMono Nerd Font. Встроенная установка упала: в системе нет `unzip` (exit 127), а бинарь вызывает его.
   - Лечение вручную (python3 вместо unzip):
     ```
     curl -fsSL https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.zip -o /tmp/jbm.zip
     python3 -c "import zipfile; zipfile.ZipFile('/tmp/jbm.zip').extractall('/home/estorozhenko/.local/share/fonts')"
     sudo -u estorozhenko -H fc-cache -f /home/estorozhenko/.local/share/fonts
     ```
   - Проверка: `sudo -u estorozhenko -H fc-list | grep -i "JetBrainsMono Nerd"` — найден (96 TTF, Nerd Font + Mono).

### Выводы / правила на будущее
1. Устанавливать herdr-плагины ТОЛЬКО от имени пользователя, который реально пользуется herdr (иначе «No plugins installed» из-за привязки к `$HOME/.config/herdr`).
2. Монорепо-плагины: путь указывается с поддиректорией `owner/repo/subdir`.
3. Встроенный установщик Nerd Font плагина требует `unzip` в системе; при его отсутствии ставить шрифт вручную через python3 zipfile + fc-cache от нужного пользователя.
4. Сам факт установки шрифта НЕ меняет профиль терминала — иконки в TUI появятся, но активный шрифт терминала (где сидит herdr) должен быть Nerd Font, иначе глифы будут квадратиками.

### Артефакты
- Пост для техблога про herdr и плагины подготовлен: /tmp/herdr-post.md