@taskless-app/swarm 0.2.2 → 0.4.0

package/README.md

@@ -34,6 +34,89 @@ swarm --help                       # список остальных коман
 
 Полный гайд по настройке и запуску роя — на [taskless.ru](https://taskless.ru).
 
+## Windows
+
+Рой работает на Windows, но **рекомендуемый способ — WSL2**: там он ведёт себя ровно
+как на macOS/Linux. Нативная Windows проверена вживую 02–03.08.2026 (Windows 11 Pro),
+рой поднимается и доводит задачи до конца, но у неё есть особенности:
+
+- `ps` и `lsof` на Windows нет. Демон берёт снапшот процессов через
+  `Get-CimInstance Win32_Process` (нужен PowerShell в `PATH`) и гасит дерево процессов
+  через `taskkill /T /F` — групповых сигналов (`kill(-pid)`) Windows не умеет.
+  У `Win32_Process` нет рабочего каталога процесса, поэтому процессы worktree
+  опознаются по командной строке и по родству, а не по `cwd`, — детект чуть грубее.
+- **Длинные пути.** Демон включает `core.longpaths=true` для рабочего репозитория сам.
+  Без него `git worktree remove` падает `Filename too long` на `node_modules`.
+- **Бинарь `claude`.** `spawn` на Windows ищет исполняемый файл по `PATHEXT`, поэтому
+  bash-обёртка `~/bin/claude` без расширения ему не видна. Демон сам находит
+  `claude.exe` в `%APPDATA%\Claude\claude-code\<версия>` и в MSIX-копии под
+  `%LOCALAPPDATA%\Packages\Claude*`. Нестандартная установка — укажите путь явно:
+  `SWARM_CLAUDE_BIN=D:\path\to\claude.exe`.
+- **Docker Desktop** вызовы `docker ps` может подвешивать, пока поднимается, — и вместе
+  с ними тик демона. Для тестов на фейк-базе Docker дронам не нужен вовсе.
+
+## Лимит дронов: машина + проект
+
+`maxDrones` — двухуровневый: личный (`uiPrefs.swarm.maxDrones` в профиле — «Рой»
+в настройках Taskless) — жёсткий потолок дронов **этой машины**, физическая
+ёмкость железа; проектный (`swarmConfig.maxDrones`, `set_project_swarm`) — квота
+**внутри** машинного капа, сколько из этих дронов одновременно может занять
+один проект. Оба подхватываются без рестарта демона.
+
+Демон = машина: кап и счётчик активных дронов считаются **по Taskless-аккаунту**,
+которым демон залогинен (`swarm login`), а не по физическому железу напрямую.
+Если поднимаете второй демон на выделенном сервере отдельного проекта и не
+хотите, чтобы он делил кап с ноутбуком оператора — заводите ему **отдельный
+Taskless-аккаунт** и логиньте под ним. Один и тот же аккаунт на двух машинах
+делит один кап и один счётчик дронов (они реально соревнуются за слоты); разные
+аккаунты — полностью независимые капы, без единой правки конфига.
+
+## Несколько машин: закрепить прогон
+
+Один аккаунт может держать демона на нескольких машинах (ноутбук + рабочая станция).
+Очередь у них общая: свободный прогон берёт тот демон, у которого репозиторий прогона
+есть локально. Когда работа обязана идти именно на конкретной машине — закрепите
+прогон за ней:
+
+```bash
+swarm hosts                                  # какие машины есть: имя, пульс, id
+swarm spawn PRJ-42 --host Hunt-gaming-laptop # закрепить прогон за машиной (имя или id)
+```
+
+Закреплённый прогон возьмёт **только** демон этой машины — остальные его не видят.
+Если машина не на связи, прогон её ждёт и на другую **не уезжает**: это осознанный
+выбор оператора, а не сбой (в дашборде `/swarm` видно, какую машину он ждёт и что
+она молчит). Снять закрепление — выбрать «Любая машина» в модалке прогона или
+`swarm_run_upsert{runId, hostId:null}`.
+
+Без `--host` всё работает как раньше: прогон свободен, а машина, которая его взяла и
+потом замолчала на 15 минут, отпускает его обратно в очередь.
+
+## Логи с удалённой машины
+
+Когда дрон спотыкается, нужен сырой лог — а он лежит файлом на машине демона
+(`~/.taskless-swarm/run-logs/<id>/`). Просить владельца машины показать хвост больше
+не нужно: **MCP-тулы отдают его сами**, независимо от того, где выполнялся прогон.
+
+```
+swarm_run_log(runId, lines)      # хвост лога прогона (stdout + stderr дрона)
+swarm_daemon_log(hostId, lines)  # хвост лога самого демона — когда дрон не стартовал вовсе
+```
+
+Прод к демону за домашним роутером не стучится, поэтому запрос уезжает **командой в
+ответе на пульс** — ответ приходит со следующим пульсом (~15с), тул ждёт его сам.
+Отдаётся только ХВОСТ (потолок и по строкам, и по байтам) и только транзитом: в базе
+трекера лог не оседает, строка обмена умирает на чтении. Чужие логи недоступны —
+и запрос, и доставка скоупятся владельцем машины.
+
+Лог самого демона демон не заводит (пишет в stdout) — заведите его перенаправлением
+или укажите свой путь:
+
+```bash
+swarm start --repo <путь> >> ~/.taskless-swarm/overmind.log 2>&1   # путь по умолчанию
+SWARM_DAEMON_LOG=/var/log/overmind.log swarm start --repo <путь>   # свой путь
+```
+
 ## Правообладатель и лицензия
 
 © 2026 Ilya Smurov. Проприетарное коммерческое ПО — см. [LICENSE](./LICENSE).