@taskless-app/swarm 0.4.9 → 0.5.0

package/README.md

@@ -16,28 +16,99 @@ CLI, который поднимает у вас на машине **рой др
 пишут код через `claude` CLI в изолированных git worktree — репозиторий, с которым
 работаете, тоже должен быть на месте (склонирован локально).
 
-Без установки — одной командой на задачу:
+Три команды, одинаковые на **macOS, Linux и WSL**:
 
 ```bash
-npx @taskless-app/swarm login --workspace <slug>        # войти в свой Taskless-воркспейс
-npx @taskless-app/swarm start                          # поднять демон роя
+npm i -g @taskless-app/swarm
+swarm install                      # довести окружение машины до рабочего состояния
+swarm login --workspace <slug>     # войти в свой Taskless-воркспейс
+swarm start                        # поднять рой: уходит в фон, терминал остаётся вам
+swarm --help                       # список остальных команд (spawn/ls/questions/answer/…)
 ```
 
-Или один раз глобально:
+Без установки — одной командой на задачу (тогда `swarm install` пропускается, и за
+окружение отвечаете вы):
 
 ```bash
-npm i -g @taskless-app/swarm
-swarm login --workspace <slug>
-swarm start                        # поднять рой: уходит в фон, терминал остаётся вам
-swarm --help                       # список остальных команд (spawn/ls/questions/answer/…)
+npx @taskless-app/swarm login --workspace <slug>
+npx @taskless-app/swarm start
+```
+
+## Установка окружения: `swarm install` и `swarm doctor`
+
+`swarm install` — не список советов, а установка: команда проверяет пункты и **делает
+сама всё, что может**, а там, где без вас нельзя, показывает точную строку и объясняет
+зачем. Проверяются: версия Node, `claude` и `gh` (включая вход в GitHub), глобальный
+пакет роя и его версия против опубликованной, `playwright-core` и системные библиотеки
+Chromium для скриншотов, Docker (**только** если он нужен найденному репозиторию),
+клоны репозиториев и `SWARM_REPO`, живой токен и уже поднятый демон.
+
+```bash
+swarm install          # проверить и довести до рабочего состояния
+swarm install --yes    # заранее разрешить sudo-команды (неинтерактивный запуск)
+swarm doctor           # ТА ЖЕ проверка без установки: что не так и как чинить
 ```
 
-**Пути к репозиториям указывать не нужно.** Демон сам находит клоны на машине: у
-каждого в `.git/config` записан origin, и по нему клон сопоставляется с репозиторием
-проекта в Taskless. Смотрит в привычных местах (`~/projects`, `~/code`, `~/src`,
+Что стоит знать про поведение:
+
+- **Разница платформ спрятана внутрь.** На macOS — Homebrew и обычно без повышения
+  прав; на Linux и в WSL — системный пакетный менеджер (apt/dnf/pacman/zypper/apk), а
+  значит `sudo`. Команда для вас одна и та же.
+- **Про права — честно.** Там, где нужен `sudo`, команда показывает точную строку и
+  что именно она поставит, и **спрашивает согласие**. Не интерактивный запуск без
+  `--yes` — строка просто печатается, пункт остаётся красным. Молча повышать права на
+  вашей машине она не будет.
+- **Ставится только то, чего действительно нет.** Каждый пункт сперва проверяется: на
+  маке, где Chromium и так поднимается, системные библиотеки никто ставить не полезет.
+- **Повторный запуск безопасен.** На машине, где всё стоит, `swarm install` ничего не
+  делает и не перезапускает — просто говорит «готово». Живой токен не требует
+  повторного `swarm login`; работающий демон не глушится и второй копией на тот же
+  порт не подменяется — команда скажет, что его нужно перезапустить самому.
+- **Не притворяется, что всё хорошо.** Если Chromium не поднимается — так и написано:
+  скриншоты недоступны, UI-задачи будут сдаваться без них. Проверка настоящая: рой
+  реально запускает headless Chromium тем же кодом, что `swarm shot`, — потому что
+  наличие файлов ничего не доказывает (в WSL пакет на месте, а `libnss3.so` нет).
+
+`swarm doctor` печатает состояние и причину — его вывод и стоит присылать, когда
+что-то не работает, вместо переписки «попробуй запустить, скажи что вывелось».
+
+## Обновление: `swarm update`
+
+```bash
+swarm update           # обновить рой до опубликованной версии
+```
+
+Обновление своей же программы — её собственная работа: помнить, каким менеджером
+поставлен пакет (`npm`/`pnpm`/`bun`/`yarn` — глобальные каталоги у них разные) и что
+пакет называется не так, как команда, вы не обязаны. Версия уже свежая — команда так и
+скажет и ничего не сделает.
+
+Демон **сам говорит, что устарел**: при старте, если установленная версия отстала от
+опубликованной, в лог уходит одна строка с точной командой обновления. И отдельно
+помните: Node держит модуль-граф с момента старта процесса, поэтому обновление пакета
+не переезжает в **живой** демон само — после `swarm update` нужен
+`swarm stop && swarm start`. Команда об этом напомнит, если демон поднят.
+
+**Пути к репозиториям указывать не нужно.** Демон спрашивает у Taskless, за какие
+репозитории отвечает ваш рой (проекты с включённым роем), и сам находит их клоны на
+машине: у каждого клона в `.git/config` записан origin, и по нему он сопоставляется с
+репозиторием проекта. Смотрит в привычных местах (`~/projects`, `~/code`, `~/src`,
 `~/work`, …) на три уровня вглубь — на типовой машине это десятки миллисекунд. Клоны
 лежат где-то ещё — скажите один раз, `swarm start --repo <путь>`, дальше запомнится.
 
+Что нашлось и где — печатает `swarm status`. Оттуда же видно два случая, о которых рой
+не молчит: **клона нет** (тогда прогоны этого репозитория будут стоять — рой сам не
+клонирует, диск ваш) и **клонов два** (рой называет обе копии и говорит, в какой
+работает). То же самое видно в Taskless: на вкладке «Рой» проекта — отдельным пунктом
+онбординга, а прогон, чей репозиторий не держит ни одна машина, прямо говорит, чего он
+ждёт, вместо того чтобы молча стоять в очереди.
+
+Свои каталоги поиска — `SWARM_SCAN_ROOTS=~/dev,/srv/repos` (порядок значим: при двух
+копиях побеждает первый корень); выключить поиск целиком — `SWARM_SCAN_ROOTS=off`.
+Глубина — `SWARM_SCAN_DEPTH` (по умолчанию 3), период пересборки карты —
+`SWARM_REPO_MAP_MS` (по умолчанию 15 минут; новый swarm-проект подхватится без
+перезапуска демона).
+
 **Демон открепляется от терминала.** `swarm start` не занимает окно: процесс уходит
 в фон, а весь вывод пишется в `~/.taskless-swarm/overmind.log` — тот самый файл, из
 которого агент читает хвост лога удалённо. Посмотреть: `swarm logs -f`. Нужен вывод
@@ -55,7 +126,9 @@ swarm --help                       # список остальных коман
 Гасить демона по имени процесса (`pkill -f overmind`) не нужно — есть штатные команды:
 
 ```bash
-swarm status               # жив ли демон, на паузе ли рой, сколько дронов в работе
+swarm status               # жив ли демон, на паузе ли рой, сколько дронов в работе,
+                           # какие репозитории у роя и где нашлись их клоны
+swarm doctor               # окружение машины: что не так и как чинить
 swarm pause «причина»      # не брать НОВУЮ работу; живые дроны доработают
 swarm resume               # снова брать работу
 swarm stop                 # погасить демона на этой машине
@@ -82,8 +155,13 @@ swarm remove --yes         # отключить машину от роя цел
 ## Windows
 
 Рой работает на Windows, но **рекомендуемый способ — WSL2**: там он ведёт себя ровно
-как на macOS/Linux. Нативная Windows проверена вживую 02–03.08.2026 (Windows 11 Pro),
-рой поднимается и доводит задачи до конца, но у неё есть особенности:
+как на macOS/Linux, и `swarm install` работает так же, как на Linux. На нативной
+Windows та же команда говорит это вслух, делает свою часть (пакеты npm — они
+кросс-платформенные; системных зависимостей Chromium там нет) и **не выдаёт
+линуксовых советов**: `sudo apt-get` пользователю PowerShell не поможет.
+
+Нативная Windows проверена вживую 02–03.08.2026 (Windows 11 Pro), рой поднимается и
+доводит задачи до конца, но у неё есть особенности:
 
 - `ps` и `lsof` на Windows нет. Демон берёт снапшот процессов через
   `Get-CimInstance Win32_Process` (нужен PowerShell в `PATH`) и гасит дерево процессов
@@ -155,8 +233,12 @@ swarm_daemon_log(hostId, lines)  # хвост лога самого демона
 и запрос, и доставка скоупятся владельцем машины.
 
 Лог самого демона заводится сам: фоновый `swarm start` пишет в
-`~/.taskless-swarm/overmind.log` и ротирует его при старте (прошлый — `.1`). Свой
-путь — `SWARM_DAEMON_LOG`. Смотреть на месте:
+`~/.taskless-swarm/overmind.log`. Свой путь — `SWARM_DAEMON_LOG`. Ротация идёт **и при
+старте, и на живом демоне** (он рассчитан на недели без рестарта, и раньше у такого
+процесса ротация не срабатывала ни разу): перерос потолок — содержимое уезжает в `.1`,
+прошлые поколения сдвигаются, старые сверх лимита удаляются. Ручки —
+`SWARM_DAEMON_LOG_MAX_BYTES` (по умолчанию 16 МБ), `SWARM_DAEMON_LOG_KEEP` (2 поколения),
+`SWARM_DAEMON_LOG_CHECK_MS` (как часто демон смотрит на размер, 1 мин). Смотреть на месте:
 
 ```bash
 swarm logs            # хвост лога демона (по умолчанию 200 строк)