Контрольные точки и /rollback

VibeOS может автоматически создавать снимок вашего проекта перед деструктивными операциями и восстанавливать его одной командой. Контрольные точки включаются по желанию начиная с v2 — большинство пользователей никогда не используют /rollback, а хранилище теневых копий со временем занимает значительный объём, поэтому по умолчанию функция отключена.

Включите контрольные точки для сеанса с помощью --checkpoints:

vibeos chat --checkpoints

Или включите глобально в ~/.vibeos/config.yaml:

checkpoints:
  enabled: true

Эта страховочная сеть работает на основе внутреннего Менеджера контрольных точек, который хранит единый общий теневой git-репозиторий в ~/.vibeos/checkpoints/store/ — ваш реальный .git проекта никогда не затрагивается. Все проекты, с которыми работает агент, используют одно и то же хранилище, поэтому объектная база данных git с адресацией по содержимому дедуплицируется между проектами и между шагами.

Что вызывает создание контрольной точки

Контрольные точки создаются автоматически перед:

• Файловыми инструментами — write_file и patch
• Деструктивными командами терминала — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, перенаправлениями вывода (>), а также git reset/clean/checkout

Агент создаёт не более одной контрольной точки на каталог за шаг, чтобы длительные сеансы не порождали множество снимков.

Краткая справка

Слеш-команды внутри сеанса:

Команда	Описание
/rollback	Показать все контрольные точки со статистикой изменений
/rollback <N>	Восстановить состояние до контрольной точки N (также отменяет последний шаг чата)
/rollback diff <N>	Показать различия между контрольной точкой N и текущим состоянием
/rollback &lt;N&gt; <файл>`	Восстановить один файл из контрольной точки N

CLI для просмотра и управления хранилищем вне сеанса:

Команда	Описание
vibeos checkpoints	Показать общий размер, количество проектов, разбивку по проектам
vibeos checkpoints status	То же, что и checkpoints
vibeos checkpoints list	Псевдоним для status
vibeos checkpoints prune	Принудительная очистка: удалить осиротевшие/устаревшие записи, сборка мусора, соблюдение лимита размера
vibeos checkpoints clear	Полностью очистить базу контрольных точек (с запросом подтверждения)
vibeos checkpoints clear-legacy	Удалить только архивы legacy-* после миграции с v1

Как работают контрольные точки

На высоком уровне:

• VibeOS обнаруживает, когда инструменты собираются изменить файлы в вашем рабочем дереве.
• Один раз за шаг диалога (на каталог) он:
  • Определяет разумный корень проекта для файла.
  • Инициализирует или повторно использует единое общее теневое хранилище в ~/.vibeos/checkpoints/store/.
  • Индексирует изменения в индекс проекта, строит дерево и создаёт коммит в ссылку проекта (refs/vibeos/<хеш-проекта>`).
• Эти ссылки проектов образуют историю контрольных точек, которую вы можете просматривать и восстанавливать через /rollback.

Конфигурация

Настройте в ~/.vibeos/config.yaml:

checkpoints:
  enabled: false              # главный выключатель (по умолчанию: false — по желанию)
  max_snapshots: 20           # макс. контрольных точек на проект (обеспечивается перезаписью ссылки + gc)
  max_total_size_mb: 500      # жёсткий лимит общего размера хранилища; удаляются самые старые коммиты
  max_file_size_mb: 10        # пропускать любые файлы больше этого размера

  # Автообслуживание (включено по умолчанию): очистка ~/.vibeos/checkpoints/ при запуске
  # и удаление записей проектов, чья рабочая директория больше не существует
  # (осиротевшие) или чья last_touch старше retention_days. Выполняется не чаще
  # одного раза в min_interval_hours, отслеживается через маркер .last_prune.
  auto_prune: true
  retention_days: 7
  delete_orphans: true
  min_interval_hours: 24

Чтобы отключить всё:

checkpoints:
  enabled: false
  auto_prune: false

Когда enabled: false, Менеджер контрольных точек ничего не делает и никогда не выполняет git-операции. Когда auto_prune: false, хранилище растёт, пока вы не запустите vibeos checkpoints prune вручную.

Просмотр контрольных точек

Из сеанса CLI:

/rollback

VibeOS отвечает отформатированным списком со статистикой изменений:

📸 Контрольные точки для /path/to/project:

  1. 4270a8c  2026-03-16 04:36  перед patch  (1 файл, +1/-0)
  2. eaf4c1f  2026-03-16 04:35  перед write_file
  3. b3f9d2e  2026-03-16 04:34  перед терминал: sed -i s/old/new/ config.py  (1 файл, +1/-1)

  /rollback <N>             восстановить до контрольной точки N
  /rollback diff <N>        просмотреть изменения с контрольной точки N
  /rollback <N> <файл>      восстановить один файл из контрольной точки N

Просмотр хранилища из оболочки

vibeos checkpoints

Пример вывода:

База контрольных точек: /home/you/.vibeos/checkpoints
Общий размер:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
Проекты:        12

  WORKDIR                                                       КОММИТОВ    ПОСЛЕДНЕЕ ИЗМ.  СОСТОЯНИЕ
  /home/you/code/vibeos-agent                                        20       2ч назад  активно
  /home/you/code/experiments/rl-runner                                8       1д назад  активно
  /home/you/code/old-prototype                                        3       9д назад  осиротевший
  ...

Архивы legacy (1):
  legacy-20260506-050616                           4.2 MB

Очистить с помощью: vibeos checkpoints clear-legacy

Принудительная полная очистка (игнорирует 24-часовой маркер идемпотентности):

vibeos checkpoints prune --retention-days 3 --max-size-mb 200

Предварительный просмотр изменений с помощью /rollback diff

Прежде чем выполнять восстановление, просмотрите, что изменилось с момента контрольной точки:

/rollback diff 1

Показывается сводка статистики git diff, за которой следует сам diff.

Восстановление с помощью /rollback

/rollback 1

За кулисами VibeOS:

1. Проверяет, существует ли целевой коммит в теневом хранилище.
2. Создаёт снимок перед откатом текущего состояния, чтобы вы могли позже «отменить отмену».
3. Восстанавливает отслеживаемые файлы в вашей рабочей директории.
4. Отменяет последний шаг диалога, чтобы контекст агента соответствовал восстановленному состоянию файловой системы.

Восстановление одного файла

Восстановите только один файл из контрольной точки, не затрагивая остальную часть каталога:

/rollback 1 src/broken_file.py

Гарантии безопасности и производительности

• Наличие git — если git не найден в PATH, контрольные точки прозрачно отключаются.
• Область каталога — VibeOS пропускает слишком широкие каталоги (корень /, домашний $HOME).
• Размер репозитория — каталоги с более чем 50 000 файлов пропускаются.
• Лимит размера файла — файлы больше max_file_size_mb (по умолчанию 10 МБ) исключаются из снимка. Предотвращает случайное сохранение наборов данных, весов моделей или сгенерированного медиа.
• Лимит общего размера хранилища — когда хранилище превышает max_total_size_mb (по умолчанию 500 МБ), самый старый коммит каждого проекта удаляется по кругу, пока размер не станет меньше лимита.
• Реальная очистка — max_snapshots обеспечивается перезаписью ссылки проекта и последующим запуском git gc --prune=now, чтобы рыхлые объекты не накапливались.
• Снимки без изменений — если с момента последнего снимка нет изменений, контрольная точка пропускается.
• Нефатальные ошибки — все ошибки внутри Менеджера контрольных точек логируются на уровне отладки; ваши инструменты продолжают работу.

Где хранятся контрольные точки

~/.vibeos/checkpoints/
  ├── store/                 # единый общий bare git-репозиторий
  │   ├── HEAD, objects/     # внутренности git (общие для всех проектов)
  │   ├── refs/vibeos/<hash> # указатель ветки проекта
  │   ├── indexes/<hash>     # git-индекс проекта
  │   ├── projects/<hash>.json  # рабочая директория + created_at + last_touch
  │   └── info/exclude
  ├── .last_prune            # маркер идемпотентности автоочистки
  └── legacy-<ts>/           # архивированные до-v2 теневые репозитории проектов

Каждый <hash> вычисляется из абсолютного пути рабочей директории. Обычно вам никогда не нужно трогать их вручную — используйте vibeos checkpoints status/prune/clear`.

Миграция с v1

До переписывания на v2 каждая рабочая директория получала свой собственный полный теневой git-репозиторий непосредственно в ~/.vibeos/checkpoints/<hash>/. Такая структура не могла дедуплицировать объекты между проектами и имела задокументированный неработающий очиститель — хранилище росло без ограничений.

При первом запуске v2 все до-v2 теневые репозитории перемещаются в ~/.vibeos/checkpoints/legacy-<timestamp>/, чтобы новая структура с единым хранилищем начиналась чистой. Старая история /rollback всё ещё доступна при ручном просмотре архива legacy с помощью git; когда вы убедитесь, что она вам не нужна, выполните:

vibeos checkpoints clear-legacy

чтобы освободить место. Архивы legacy также удаляются auto_prune после retention_days.

Рекомендации

• Включайте контрольные точки только когда они нужны — vibeos chat --checkpoints или enabled: true в профиле.
• Используйте /rollback diff перед восстановлением — просмотрите, что изменится, чтобы выбрать правильную контрольную точку.
• Используйте /rollback вместо git reset, когда хотите отменить только изменения, сделанные агентом.
• Периодически проверяйте vibeos checkpoints status, если регулярно используете контрольные точки — показывает, какие проекты активны и сколько места занимает хранилище.
• Комбинируйте с Git worktrees для максимальной безопасности — держите каждый сеанс VibeOS в отдельном worktree/ветке, используя контрольные точки как дополнительный уровень защиты.

Для запуска нескольких агентов параллельно в одном репозитории смотрите руководство по Git worktrees.