Background task queue for AI CLIs — schedule prompts, retry on rate limits, manage everything via Web UI or Telegram bot.
Works with Claude Code, OpenAI Codex, Qwen Code, Cursor Agent, or any CLI that accepts a prompt argument.
Универсальный планировщик промптов для AI CLI — очередь, планирование и автоматический retry.
Работает с любым AI CLI: Claude Code, Codex, Qwen Code и другими.
Одна очередь для разовых задач, расписаний и автономных workflow.
- Мульти-провайдер — Claude, Codex, Qwen, Cursor Agent, или любой свой CLI
- Очередь задач с приоритетами (1 — высший, 10 — низший)
- Планирование — запуск промптов в заданное время
- Выбор модели — для Claude Code провайдеров (sonnet/opus/haiku) и любых провайдеров с явным списком
models(Web UI + бот) - Rate limit detection — автоматическое определение лимитов API; перегрузка провайдера (529 overloaded) отличается от исчерпанной квоты и так и называется в уведомлении
- Exponential backoff — retry с нарастающей задержкой (60s → 1h)
- Crash recovery — при перезапуске воркера зависшие задачи возвращаются в очередь
- CLI + Web UI — два интерфейса на выбор
- Telegram бот — управление задачами через Telegram с авторизацией по номеру телефона
- Пароль на создание задач в боте — опциональная защита через
PP_TASK_PASSWORD - Автономный режим — флаг на задачу для запуска Claude или Codex без интерактивных подтверждений. В веб-форме запоминается явный выбор пользователя в этом браузере; в новом браузере флаг выключен, скрытая галка для session-target не передаётся в задачу.
- Уведомления — Telegram бот присылает сообщение как только задача завершилась (с результатом или ошибкой)
- Интеграция с herdr — задачи выполняются в живых терминальных сессиях: permission-диалог не роняет задачу, а ждёт подтверждения (с уведомлением в Telegram); режим
keep_paneоставляет сессию открытой для продолжения - Общее окно «Настройки» — тёмная, светлая или системная тема с сохранением выбора в браузере; переход к помощникам, воркфлоу и расписанию. Светлая палитра адаптирована из пакета Евгения Кержаева (#106).
- herdr → Telegram мост — уведомления о заблокированных/завершённых агентах herdr с кнопками «Подтвердить / Экран / Ответить»
- Опциональная авторизация Web UI/API — токен через
PP_API_TOKEN - Скилы Claude Code — запуск
/skill-nameчерез Web UI и бота (для всех Claude Code провайдеров) - Продолжение сессии — кнопка 💬 в боте после завершённой задачи для диалога в той же сессии
- Пауза воркера — кнопка ⏸ в Web UI и боте, чтобы временно остановить обработку без потери задач
- Автоперезапуск worker'а — при обновлении кода пакета worker сам перезапускается между задачами
- Повторяющиеся задачи — поле Recur:
6h,30m,daily@09:00— новая задача создаётся автоматически, в том числе после неудачного прогона - Экран расписания — кнопка 🗓 в Web UI: все повторяющиеся задачи как серии — период, следующий запуск, исход прошлого и пометка «оборвана»
- Диагностика внешних конвейеров — локальные профили показывают backlog, возраст, churn, ETA и проектные health-check без запуска LLM и расхода токенов
- Правка задачи в очереди — провайдер, модель, эффорт, повтор и приоритет меняются прямо в карточке, без пересоздания задачи
- Фоновый запуск (detached) — запустить процесс в фоне и сразу завершить задачу (для серверов, ботов, polling-скриптов)
- Per-task таймаут — индивидуальный лимит времени задачи в Web UI (переопределяет глобальный
PP_TASK_TIMEOUT) - Свой git worktree на задачу — галка «🌿 свой worktree»: агент работает в отдельном чекауте на ветке
pp/t<id>, твоё рабочее дерево не трогается, результат виден как diff - Срыв среды ≠ провал задачи — отказ доступа (401/403/5xx) или обрыв ответа возвращает задачу в очередь вместо
failed - Сторож запретов — PreToolUse-хук режет типовые катастрофические команды у задач Claude Code с
--dangerously-skip-permissions: диалога там нет, значит запрет должен держать не он. Это страховка от случайностей, а не песочница; Codex и другие CLI идут без него (см. «Границы сторожа») - Права задачи —
none/read/write/full: запрос ограничений через адаптер CLI. Неподдерживаемый уровень или конфликтующие настройки останавливают запуск (fail closed). - Маршруты заявок (flows) — заявки извне (форма сайта, письма) идут по шагам из JSON-файла: агент с ограниченными правами, решение человека кнопкой в Telegram, команды, публичная лента. Доверие — часть описания: маршрут, дающий тексту извне лишнюю власть, не загрузится (docs/FLOWS.md)
- Параллельные задачи —
PP_CONCURRENCY=N: worker выполняет несколько задач одновременно, но никогда две в одном рабочем дереве - Отмена running-задач — из Web UI, бота или API: worker убивает всё принадлежащее задаче дерево процессов в течение пары секунд
- Уведомления об обновлениях — баннер в Web UI когда выходит новая версия
- Дашборд стоимости — статистика расходов за сегодня / неделю / всего по провайдерам
- Дописать решателю — приписка к задаче: пара фраз, которые уйдут в следующий прогон (в том числе в повтор после rate limit)
- Итог задачи —
PP_VERDICT=1: агент заканчивает строкойИТОГ: ГОТОВО | НУЖЕН ЧЕЛОВЕК | НЕ СМОГ | …, и уведомление сразу говорит, надо ли идти смотреть; тихий итогПУСТО(«делать нечего») в Telegram не шлётся — для повторяющихся дежурных задач - Расход за окно лимита —
pp usage: сколько сожжено за последние 5 ч по ВСЕМ сессиям Claude Code, включая herdr-задачи и живую переписку - Tray-приложение — двойной клик на
pp.exe, иконка в трее, всё управление мышью - Standalone .exe — сборка без зависимостей через PyInstaller
- SQLite — данные хранятся локально в
~/.promptpilot/ - Workflow Orchestrator (W3) — planner разбивает большую задачу на утверждаемые этапы, затем автономный цикл «исполнитель → deterministic gate → независимый аудитор» ведёт каждый этап до PASS; этап можно отдать вовне — человеку или внешнему инструменту — и принять его результат на то же ревью; есть crash recovery, лимиты, provenance и JSON/Markdown-экспорт для анализа
Обычный (не detached) запуск на Windows помещается в отдельный Job Object ещё
до того, как начинает выполняться первая инструкция процесса. Поэтому при
таймауте, отмене или аварийном завершении worker закрывает именно локальное
дерево этой задачи — включая cmd/npm-обёртки и их потомков — не затрагивая
соседние задачи и другие программы. Если создать такую границу не удалось,
задача не запускается (fail closed).
Архитектура автономного цикла описана в
docs/WORKFLOW_ORCHESTRATOR_SPEC.md.
W0–W3 реализованы: можно импортировать прежние раунды, поручить сильному planner
разбиение новой задачи, отредактировать и один раз утвердить план, после чего
PromptPilot автоматически передаёт ход между executor, gate и reviewer и
сохраняет непрерывный журнал. Настройка описана в
docs/WORKFLOW_AUTOMATION_GUIDE.md.
В Web UI кнопка Workflows → Новый workflow открывает четырёхшаговый мастер:
задача, команда агентов, правила автоматизации и preflight. Перед созданием он
без выполнения проектного кода проверяет Git-путь, имя ветки, доступность
providers и синтаксис gate-команд. Есть рекомендуемый, экономный и усиленный
профили, а повторяющиеся настройки можно сохранить как локальный шаблон.
Экран сразу показывает, у кого «мяч» и какой переход произойдёт дальше.
Минимальный ручной пилот:
pp workflow create workflow.json
pp workflow import-history <id-or-slug> history.json
pp workflow start <id-or-slug> --base-sha <sha>
pp workflow dispatch <id-or-slug> executor --file executor-prompt.md
pp workflow sync <id-or-slug>
pp workflow gate <id-or-slug> PASS --gate-id tests
pp workflow dispatch <id-or-slug> reviewer --file reviewer-prompt.md
pp workflow sync <id-or-slug>
pp workflow review <id-or-slug> PASS --summary "Принято"
pp workflow list
pp workflow show <id-or-slug>
pp workflow rounds <id-or-slug>
pp workflow events <id-or-slug> --json
pp workflow findings <id-or-slug>Формат переноса старых итераций и правила отделения проверенных фактов от
ручных воспоминаний описаны в
docs/HISTORY_IMPORT_GUIDE.md.
- Скачай последний релиз: github.com/ivanarama/PromptPilot/releases
- Распакуй архив
PromptPilot-vX.X.X-windows.zipв любую папку - Заполни
.env(шаблон уже в архиве) - Запусти
start.ps1илиpp.exe tray
git clone https://github.com/ivanarama/PromptPilot.git
cd PromptPilot
pip install -e .Или установка из pip-пакета (из релиза):
pip install promptpilot-X.X.X-py3-none-any.whlТребования: Python 3.10+, хотя бы один AI CLI в PATH (claude, codex, qwen и т.д.).
git clone https://github.com/ivanarama/PromptPilot.git
cd PromptPilot
docker compose up -d --build
# Web UI: http://localhost:8420 (по умолчанию только loopback)docker compose поднимает два сервиса — server и worker — с общей SQLite БД
на volume promptpilot-data (данные переживают пересборку). Образ уже включает
Node.js и @anthropic-ai/claude-code и работает под non-root пользователем.
- Аутентификация Claude в контейнере: проще всего через LiteLLM-прокси —
задайте
ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKENв.envрядом сdocker-compose.yml. Альтернатива для обычной подписки — примонтировать свой логин: добавьте в сервисыvolumes: - ~/.claude:/home/pp/.claude. - Рабочие репозитории: чтобы задачи работали по вашим проектам, примонтируйте
их в контейнер
worker(пример вdocker-compose.yml) и задайтеPP_PROJECTS_ROOT. - Безопасность: порт публикуется только на
127.0.0.1:8420. Чтобы открыть в сеть — поменяйте на"8420:8420"и задайтеPP_API_TOKEN(тогда/api/*требуютAuthorization: Bearer <token>), либо ставьте за reverse-proxy. - Telegram-бот выключен по умолчанию: раскомментируйте сервис
botвdocker-compose.ymlи задайтеPP_TG_TOKEN(при необходимостиPP_TG_PROXY). - Ограничение: Docker-вариант локальный и одномашинный — herdr и раздача задач по ssh на другие машины из контейнера не работают.
./build.sh # → dist/pp
./dist/pp serverИспользует тот же кроссплатформенный pp.spec, что и Windows. Tray-зависимости
(pystray/Pillow) в Linux-сборку не входят — pp tray там просто сообщит об
этом и предложит pp worker/pp server/pp bot.
# Добавить задачу
pp add "Объясни что такое рекурсия"
# Запустить воркер (выполняет задачи)
pp worker
# В другом терминале — запустить веб-интерфейс
pp server
# UI доступен на http://127.0.0.1:8420 (браузер не открывается автоматически)Важно:
pp workerиpp server— два отдельных процесса, которым нужно работать одновременно. Пока воркер не запущен, задачи просто висят вpending.
Двойной клик на pp.exe — иконка появляется в системном трее, worker и server стартуют автоматически.
Правый клик на иконке:
▶ Worker ← кликнуть = остановить
▶ Server ← кликнуть = остановить
■ Bot ← кликнуть = запустить (нужен PP_TG_TOKEN в .env)
─────────────────
Запустить все
Остановить все
─────────────────
Открыть Web UI ← открывает браузер на http://127.0.0.1:8420
─────────────────
Выход ← останавливает все сервисы и закрывает трей
Цвет иконки показывает состояние: 🟢 все работают / 🟠 частично / ⚫ остановлено.
Или явно через команду:
pp traypp worker # запустить воркер
pp server # запустить веб-UI
pp bot # запустить Telegram бот
pp add "промпт" # добавить задачу
pp list # список задач
# и т.д.Оба режима работают с одной и той же БД и настройками.
Все настройки — токен бота, путь к claude.exe, разрешённые номера — хранятся в .env файле.
Скопируй шаблон и заполни:
copy .env.example .env
notepad .env.env рядом с pp.exe (или рядом со скриптом):
PP_TG_TOKEN=7123456789:AAF...
PP_TG_ALLOWED_PHONES=+79001234567,+79007654321
PP_CLAUDE_EXE=C:\Users\YourName\.local\bin\claude.exe
PP_GH_EXE=C:\Program Files\GitHub CLI\gh.exe
PP_GO_EXE=C:\Program Files\Go\bin\go.exe
PP_DEFAULT_CLI=claudeАвторизация Claude: PromptPilot запускает
claude.exeкак обычный процесс — он наследует окружение текущего пользователя. Достаточно один раз выполнитьclaude auth loginна этой машине, больше ничего настраивать не нужно.
Порядок поиска .env:
- Рядом с
pp.exe— для дистрибуции - Текущая рабочая директория — для разработки
~/.promptpilot/.env— постоянный пользовательский конфиг
Значения из .env применяются только если переменная не задана в окружении — то есть $env:PP_TG_TOKEN всегда перекрывает .env.
Запустить воркер + сервер в фоне:
.\start.ps1Запустить всё включая Telegram бота:
$env:PP_TG_TOKEN = "ваш-токен"
$env:PP_TG_ALLOWED_PHONES = "+79001234567"
.\start.ps1 -BotЛоги пишутся в .\logs\. Остановить:
.\stop.ps1Скрипт автоматически использует dist\pp.exe если он собран, иначе pp из PATH.
Сборка standalone-бинаря (не требует Python на целевой машине):
.\build.ps1На выходе: dist\pp.exe. Использование аналогично:
.\dist\pp.exe worker
.\dist\pp.exe server
.\dist\pp.exe bot
.\dist\pp.exe add "промпт"Примечание: при первом запуске
pp.exeможет занять несколько секунд — PyInstaller распаковывает бандл во временную папку.
Кириллица и любые не-ASCII промпты безопасны: при не-UTF-8 локали CLI перезапускается в UTF-8 Mode, а битую вставку из терминала (
привет)pp addдетектирует и чинит автоматически.
pp add "промпт" # добавить задачу (дефолтный провайдер)
pp add "промпт" -c codex # через Codex
pp add "промпт" -c qwen # через Qwen
pp add "промпт" -c claude-z # через кастомный алиас
pp add "промпт" -p 1 # с приоритетом (1 = высший)
pp add "промпт" -a "2026-03-25T03:00" # запланировать на время
pp add -f prompts.txt # добавить из файла (по строке)
pp add "промпт" -d /path/to/project # задать рабочую директорию
pp add "промпт" -d /repo -w # в своём git worktree (ветка pp/t<id>)
pp list # задачи (по умолчанию последние 20; -n N — больше)
pp list -s pending # фильтр по статусу
pp status 1 # детали задачи #1
pp cancel 1 # отменить задачу
pp delete 1 # удалить задачу
pp stats # статистика
pp purge --days 7 # удалить старые завершённые задачи
pp note 42 "перечитай комментарий" # дописать решателю к задаче #42
pp note 42 --clear # убрать приписку
pp usage # расход за окно лимита (5 ч)
pp usage --hours 24 --json # то же машинно, за сутки
pp flows list # маршруты заявок и их заявки (docs/FLOWS.md)
pp flows check flow.json # проверить файл маршрута, ничего не запуская
pp flows approve 12 --note "без огня" # решение по заявке, которая его ждёт
pp flows run # вести заявки (start.ps1 и трей запускают сами)
pp guard --rules # правила сторожа запретов
pp guard "git push origin main" # что сторож сделает с командой
pp worker # запустить воркер
pp server # запустить веб-UI
pp server -p 9000 # на другом порту
pp bot # запустить Telegram бот
У Telegram-задач агент получает инструкцию сохранить запрошенные файлы в отдельную
папку .promptpilot-results/<task>-<attempt> внутри рабочего каталога (или worktree).
Готовые файлы он помечает в итоговом ответе строками PP-FILE: <абсолютный путь>
вне блоков кода. Бот прикладывает их документами к результату задачи, в тот же чат.
Обычные ссылки на исходники не считаются вложениями; служебные строки скрываются
в карточке результата, полном выводе и Web UI.
Файл читается на той машине, где выполнялась задача: локально либо по настроенному SSH, включая Windows OpenSSH/PowerShell. Допускаются только обычные файлы из папки результата этой задачи; выход за папку, ссылки наружу и типичные файлы ключей/ учётных данных отклоняются. Лимит — пять файлов по 50 МБ; для большего результата агенту предлагается архив. Папку результата следует исключать из коммитов.
Для ответа через «Окна → Ответить» бот передаёт агенту отдельную папку и инструкцию
записать после копирования .pp-files.json с именами файлов и их SHA-256. Доставка
привязана к исходному чату, машине и следующему завершению той же сессии. Она
работает и при отключённых общих уведомлениях об агентах (PP_HERDR_WATCH=0).
При изменении содержимого файла после записи манифеста загрузка отклоняется.
Очередь документов сохраняется в SQLite вместе с отметкой о доставке текстового результата. После перезапуска отправленные документы не ставятся в очередь снова; при временной недоступности машины или Telegram отправка повторяется до 24 часов. Telegram не даёт ключа идемпотентности: если соединение оборвалось после фактического приёма документа, повторная попытка может создать дубликат. Отсутствующий или слишком большой файл сопровождается отдельным сообщением, а текст результата сохраняется.
Если в окне видны 1 question и shift+↑ to answer, карточка предлагает
«Открыть вопрос». Кнопка открывает вопрос в терминале и показывает его текст
с вариантами в чате. Стрелки меняют выбранный вариант, «Выбрать» передаёт Enter.
Открытие вопроса само по себе ответ не отправляет. Если экран изменился,
бот сначала показывает новое содержимое; старый выбор не передаётся.
- Создай бота через @BotFather, получи токен.
- Задай переменные окружения:
$env:PP_TG_TOKEN = "токен-от-botfather"
$env:PP_TG_ALLOWED_PHONES = "+79001234567,+79007654321"- Запусти:
pp botПри первом открытии бота пользователь видит кнопку «Поделиться контактом». Бот получает номер телефона и сверяет с PP_TG_ALLOWED_PHONES. При совпадении — доступ открыт.
Авторизованные пользователи сохраняются в ~/.promptpilot/tg_users.json. Повторная авторизация при перезапуске не нужна.
Альтернатива env-переменной — файл ~/.promptpilot/tg_config.json:
{
"allowed_phones": ["+79001234567", "+79007654321"]
}| Функция | Описание |
|---|---|
| 📋 Задачи | Список задач с пагинацией и статусами |
🖥 Окна (/windows) |
Живые herdr-сессии по всем машинам: статус, проект, хвост экрана; в карточке — 💬 промпт прямо в панель и клавиши permission-диалога |
| ➕ Добавить задачу | Промпт → провайдер → модель (если у провайдера есть список) → приоритет → skip-permissions → оставить herdr-сессию? (для herdr) → директория → расписание → повтор → режим запуска |
| 📊 Статистика | Сводка по статусам |
| 🔌 Провайдеры | Список провайдеров с деталями: команда, модели, env-переменные (ключи маскированы), источник настройки |
| Детали задачи | Промпт, результат, ошибка; кнопки: отмена (работает и для running — процесс будет убит), сброс, удаление |
| 💬 Ответить | Продолжить диалог с моделью в той же сессии |
⚡ Скилы (/skills) |
Список Claude Code скилов; выбор запускает пошаговое создание задачи |
| 🔔 Уведомления | Автоматически присылает результат или ошибку после завершения задачи |
| 📎 Вложения | Скриншот или файл прямо в мастере: подпись к фото становится текстом задачи |
Файл можно приложить и в боте, и в веб-интерфейсе — агент получит абсолютный путь к нему приписанным к промпту («Приложенные файлы (читай по этим путям)») и прочитает файл сам.
В боте — на шаге ввода промпта или на карточке подтверждения: пришли фото (подпись к нему станет текстом задачи) либо документ. Файлы принимаются и на остальных шагах мастера — альбом из нескольких скриншотов Telegram отправляет отдельными сообщениями, они долетают уже после того, как мастер шагнул дальше. Ограничение Telegram: боту не отдают файлы больше 20 МБ.
В вебе — кнопка 📎, перетаскивание в поле промпта или просто Ctrl+V
скриншота из буфера.
Где лежат файлы: ~/.promptpilot/attachments/<uuid>/<имя> (бот) и
~/.promptpilot/uploads/ (веб). Наружу каталоги не раздаются. Файлы
недосозданной задачи бот удаляет сам, а вложения созданных задач остаются на
диске — автоочистки по возрасту пока нет.
Ограничение: вложения работают только для задач на локальной машине. Файл лежит на этом хосте, и агент на другой машине его не увидит — бот и веб в этом случае не дадут запустить задачу и скажут, почему.
После завершения задачи в деталях появляется кнопка 💬 Ответить — если модель спросила что-то или ты хочешь продолжить диалог:
- Открой детали завершённой задачи → нажми 💬 Ответить
- Введи ответ или следующий вопрос
- Бот создаст новую задачу с флагом
--resume <session_id>— Claude продолжит разговор в том же контексте
Цепочка не ограничена: каждый «ответ» тоже получает кнопку 💬. Новая задача наследует провайдера, рабочую директорию и флаги оригинальной.
При создании задачи через бота последний шаг — выбор режима запуска:
Как запустить?
[▶ Обычно (ждать результата)] [🔁 Фоново (сервер/бот)]
Обычно — воркер ждёт завершения команды и сохраняет результат. Подходит для разовых задач.
Фоново — процесс запускается отдельно и сразу отвязывается. Задача помечается completed (PID XXXX), воркер переходит к следующей задаче. Процесс живёт независимо до ручной остановки.
Когда использовать «Фоново»:
- Запустить другой бот / сервер
- Скрипт с бесконечным polling-циклом
- Любой процесс, который никогда не завершится самостоятельно
Примечание: в режиме «Фоново» воркер не перехватывает вывод и не знает об ошибках после старта. Если процесс упал сразу — в задаче это не отобразится.
Кнопка 🔌 Провайдеры показывает inline-кнопки со списком провайдеров. При нажатии — карточка с деталями:
- Команда запуска (или «Исполнитель: herdr» для herdr-провайдеров)
- Список моделей (или «по умолчанию»)
- Env-переменные (API-ключи маскированы:
sk-...xyz) - Источник настройки (
builtin,providers.json, или оба) и путь к файлу
Если задана переменная PP_TASK_PASSWORD, бот запрашивает пароль перед созданием задачи. При неверном вводе создание отменяется; введённое сообщение автоматически удаляется из чата.
PP_TASK_PASSWORD=mysecretpasswordПросмотр задач и статистика паролем не защищены — только создание.
Если на машине установлена платформа 1С:Предприятие 8.3, в меню бота появляется кнопка «🔧 1С обработка» (и команда /epf): пришли .epf/.erf, текст задачи и базу — PromptPilot сам декомпилирует обработку в XML-проект (git + cc-1c-skills), отдаст задачу агенту, а по завершении соберёт и вернёт готовый .epf.
То же самое доступно в веб-интерфейсе — кнопка «🔧 1С»: создание доработки (файл + текст + база) и редактор настроек (пишет секцию "1c" в tg_config.json, действует сразу; переменные PP_1C_* сильнее настроек из формы). Задачи из /epf помечены в списке бейджем 🔧 со статусом сборки.
Настройка (.env или секция "1c" в tg_config.json):
PP_1C_EXE_PATH=C:\Program Files\1cv8\8.3.25\bin\1cv8.exe # иначе — реестр/Program Files
PP_1C_BASES_ROOT=C:\1c-bases # сканирование баз для выбора
PP_1C_BASE_PATH=C:\1c-bases\БППустаяДляСборки3_0_188_22 # база декомпиляции по умолчанию
PP_1C_UT_BASE=C:\1c-bases\УТПустаяДляСборки11_5_25_80 # пресеты: ut11/bp3/erp/unf/aa
PP_1C_SKILLS_DIR=C:\Users\me\.claude\skills\cc-1c-skills # иначе клонируется самБез найденного 1cv8.exe кнопка в меню не показывается — остальной PromptPilot не меняется.
Встроенные провайдеры:
| Имя | Описание | Скилы | Выбор модели |
|---|---|---|---|
claude |
Claude Code (Anthropic) — дефолт | ✅ | ✅ sonnet / opus / haiku |
claude-z |
Claude Code с альтернативным API (GLM, z.ai и др.) | ✅ | ✅ sonnet / opus / haiku |
codex |
OpenAI Codex | — | — |
qwen |
Qwen Code | — | — |
cursor |
Cursor Agent | — | — |
opencode |
OpenCode AI (GPT-4o/5, o1/o3 и др.) | — | ✅ из списка моделей |
Любой провайдер с
supports_skills=Trueсчитается Claude Code-совместимым и получает выбор модели автоматически.
Команды управления:
pp provider # список всех (+пометки hidden / not installed)
pp provider add <name> ... # добавить
pp provider hide <name> # убрать из списков Web UI и бота (unhide — вернуть)
pp provider remove <name> # удалитьКастомные провайдеры сохраняются в ~/.promptpilot/providers.json. Провайдеры,
чей исполняемый файл не найден на машине, автоматически не показываются в
списках Web UI и бота; ненужные (например claude-z без ключа z.ai) можно
скрыть вручную: pp provider hide claude-z.
Дефолтный провайдер: переменная PP_DEFAULT_CLI (по умолчанию claude).
Путь к claude ищется в PATH автоматически (claude на Linux/macOS,
claude.exe на Windows), переопределяется через PP_CLAUDE_EXE. opencode
ищется в PATH, затем в ~/.opencode/bin (официальный установщик) и npm-биндирах.
pp provider add myai \
--cmd "myai run {prompt}" \
--desc "My AI Tool"С переменными окружения и поддержкой скилов:
pp provider add claude-z `
--cmd "C:\Users\<username>\.local\bin\claude.exe -p --verbose --output-format stream-json {prompt}" `
--desc "Claude Code (GLM via z.ai)" `
--env "ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic" `
--env "ANTHROPIC_AUTH_TOKEN=your-token-here" `
--env "ANTHROPIC_DEFAULT_SONNET_MODEL=glm-4.7" `
--env "ANTHROPIC_DEFAULT_OPUS_MODEL=glm-4.7"Windows:
subprocessне видит PowerShell-функции и алиасы — нужен полный путь к исполняемому файлу..cmd/.bat-обёртки (npm-инструменты вродеqwen,codex) находятся автоматически черезshutil.which.
Для ограниченных прав задачи клон провайдера должен напрямую
запускать поддерживаемый CLI (claude или codex exec) без конфликтующих
настроек прав. Нельзя подтвердить ограничение произвольной обёртки одной
таблицей аргументов rights; такая команда доступна только с full или в
прежнем режиме без поля rights.
herdr — терминальный мультиплексор для
AI-агентов. PromptPilot умеет выполнять задачи не headless-процессом, а в
живой herdr-сессии: агент виден, к нему можно подключиться и вмешаться,
а главное — задача, упёршаяся в permission-диалог, не падает и не требует
--dangerously-skip-permissions: агент переходит в состояние blocked,
в Telegram приходит уведомление, вы подтверждаете действие — задача
продолжается.
Провайдер с исполнителем herdr описывается так (~/.promptpilot/providers.json):
"claude-herdr": {
"executor": "herdr",
"kind": "claude",
"description": "Claude Code в herdr-сессии",
"supports_skills": true
}Добавить можно тремя способами:
Web UI — кнопка ⚙ Providers → форма «Добавить провайдер» → тип «herdr-сессия» → указать имя, агента (kind) и, при желании, список моделей через запятую — тогда при создании задачи появится выпадашка выбора модели.
CLI:
pp provider add claude-herdr --executor herdr --kind claude --desc "Claude в herdr"
pp provider add opencode-herdr --executor herdr --kind opencode \
--desc "OpenCode в herdr" \
--models "opencode/big-pickle,opencode/mimo-v2.5-free,opencode/deepseek-v4-flash-free"providers.json — вручную, поле "models": [...] опционально.
kind — любой агент, который поддерживает herdr: claude, codex, gemini,
cursor, opencode, grok, copilot, droid, amp, kilo и другие
(полный список: herdr agent start --help). Список доступных моделей opencode:
opencode models. Выбранная модель передаётся агенту флагом --model при
старте сессии.
Режимы завершения:
- «🖥 оставить сессию открытой» — галочка при создании задачи (Web UI;
в боте — отдельный шаг для herdr-провайдеров), по умолчанию включена:
результат сохраняется в базу, но сессия остаётся — приходите, читаете
транскрипт и продолжаете диалог в той же панели. Снятая галочка — панель
закрывается после задачи. (Провайдерный флаг
"keep_pane": trueтоже поддерживается и форсирует режим.) - detached (галочка «Фоновый запуск» в боте) — промпт отправлен, задача сразу completed, агент работает в открытой панели.
Ограничения: интерактивная сессия не отдаёт stream-json, поэтому cost/session_id для herdr-задач не считаются (дашборд стоимости и кнопка 💬 неактивны).
В Telegram при добавлении задачи выберите 🖥 Окна Herdr. Можно отправить промпт в существующее окно или нажать ➕ Новое окно, выбрать установленного агента (например, Codex или Claude), модель и папку проекта. После подтверждения задача запустится в новой вкладке Herdr. Вручную добавлять провайдера для этого не требуется. Кнопка создания доступна и когда открытых сессий ещё нет. По умолчанию созданная сессия остаётся открытой после завершения задачи.
На шаге выбора локальной директории кнопка ➕ Новая папка позволяет создать папку по имени внутри текущего каталога или указать полный путь. Если при ручном вводе путь ещё не существует, бот предложит 📁 Создать и выбрать. Недостающие родительские папки тоже создаются. Для удалённых машин эта кнопка не предлагается.
Встроенный провайдер herdr-session отправляет промпт в уже открытую
панель herdr — оставленную задачей (pp-kept-N) или запущенную вручную:
- Web UI: выберите провайдера
herdr-session— появится выпадашка живых сессий (панель · агент · статус · имя); в боте — те же кнопки. - Работает вся механика задач: очередь, расписание («в 09:00 подведи итоги»), recurrence, blocked-уведомления, отмена, результат в базу.
- Чужая панель никогда не закрывается и не переименовывается; если панель закрыли до запуска — задача падает с понятной ошибкой (и уведомлением).
- Поэтому отмена или таймаут задачи в чужой панели останавливает только ожидание PromptPilot: сам пользовательский агент может продолжить работу, и это явно записывается в результат задачи. Созданная самой задачей панель, напротив, закрывается с проверкой; неудачное закрытие считается ошибкой, а не успешной отменой.
- Так удобно строить цепочки продолжений в одну сессию — аналог «💬 Ответить» для herdr-задач.
Обратная сторона моста: не ждать уведомления, а самому зайти и посмотреть, чем
заняты агенты. Список живых панелей собирается по всем машинам с herdr
(agent list), в карточке — статус, проект, хвост экрана и действия:
- 💬 Ответить — промпт уходит прямо в панель (
agent prompt), мимо очереди задач: быстро, но без записи в задачи и без учёта стоимости. - Enter / 2 / 3 / Esc — ответ на permission-диалог, когда агент
blocked. - Панели задач PromptPilot помечены номером задачи (
#42).
Отправленные так промпты журналируются в таблицу prompt_log — время, проект
(cwd панели), машина, панель и текст; сами транскрипты не дублируются, их
хранит агент (~/.claude/projects/…). Выключается через PP_LOG_PROMPTS=0.
У запущенной herdr-задачи раскрытая карточка показывает блок Экран агента: хвост панели (обновляется раз в 4 секунды, пока карточка раскрыта), статус агента и кнопки Enter / 2 / 3 / Esc — тот же ответ на permission-диалог, что в боте, но с десктопа. Раньше заблокированная задача выглядела в вебе как бесконечный «running now», и разблокировать её можно было только из Telegram или из самого herdr.
Эндпоинты сознательно узкие: GET /api/tasks/{id}/screen и
POST /api/tasks/{id}/keys работают только через id задачи (не через
произвольный pane_id), а список клавиш — ровно enter, 2, 3, esc.
Произвольного ввода в чужой терминал через веб нет.
Web UI: ⚙ Providers → «Изменить» у нужного провайдера — форма заполнится текущими значениями; сохранение с тем же именем перезаписывает. У встроенных провайдеров так создаётся переопределение (сбрасывается кнопкой «Сбросить к встроенному»). Замаскированные env-секреты при редактировании нужно ввести заново.
Повторяющаяся задача хранится как постоянная серия, а каждый запуск — отдельное вхождение этой серии. Кнопка 🗓 Расписание в Web UI показывает период, параметры (провайдер, модель, эффорт, машина), следующий запуск, результат прошлого прогона и статистику здоровья. Кнопка «Изменить» правит всю серию: основной интервал, effort, приоритет и таймаут сохраняются для будущих запусков, даже если текущий уже работает.
Для временного разбора накопившейся очереди есть «ускорение»: например,
основной интервал 4h, временный 1h. PromptPilot автоматически вернёт 4h
по указанной дате или после N последовательных итогов ПУСТО. Серия также
ставится на паузу, возобновляется, запускается немедленно или окончательно
завершается из Web UI и Telegram (/schedule). При сокращении интервала уже
созданный будущий запуск переносится ближе сразу; ждать старого четырёхчасового
scheduled_at больше не нужно. Более длинный интервал, наоборот, не откладывает
запуск, который уже должен состояться раньше. Если единственное вхождение было
отменено, «Запустить сейчас» создаёт для активной серии новое и тем самым
восстанавливает её без пересоздания расписания.
Для серий, входящих в настроенный pipeline-профиль, действует защита от
бессмысленного цикла: если два запуска подряд завершаются одним и тем же
объяснённым итогом НУЖЕН ЧЕЛОВЕК или НЕ СМОГ, PromptPilot ставит серию на
обычную паузу и не создаёт третье вхождение. При сравнении игнорируются только
служебные метаданные, SHA/UUID и номер самой scheduler-задачи; номера issue и PR
остаются частью причины, поэтому разные блокеры не склеиваются. После устранения
причины обычное «Возобновить» создаёт ровно одно новое вхождение.
Для очередей с item_blockers: true адресный блокер паркует отдельный PR,
а серия продолжает обслуживать остальные задачи. FIX и MERGE учитывают также
PR, которые после передачи сменили маршрут и исчезли из поиска своей очереди.
Подписанный fallback MERGE сохраняет точную цель даже при устаревшем снимке
дашборда. Для НЕ СМОГ парковка разрешена только при совпадении с проверенной
целью инструмента; общий сбой доступа или неоднозначный ответ сохраняет защиту
всей серии. Парковка ограничена 24 часами, снимается при изменении измеренного
состояния либо HEAD точной цели; ручные «Возобновить» и «Запустить сейчас»
сохраняют адресную парковку. Она ограничивает выбор работы и не заменяет proof,
REVIEW, CI,
ship или запрет обходить интеграционного владельца.
Для новых парковок MERGE после НЕ СМОГ доступна одна дополнительная попытка,
когда неизменный HEAD прошёл проверенный переход от положительного legacy REVIEW
с действующим ship к первому незавершённому base-sync-intent (previous=none).
Перед первым next merge worker сохраняет исходный proof через read-only
inspect-merge-progress --number <PR> --head <SHA>. Проверка ограничена одним PR,
32 API-запросами и общим GitHub-бюджетом: два стабильных полных чтения timeline
до медленных проверок и ещё два после них, источник REVIEW, actor, ship, CI и
история main должны совпасть. Подписанное свидетельство на пять минут связано с
репозиторием, конфигурацией и рабочим каталогом; оно не разрешает мутации.
Повторный запуск атомарно расходует переход на реальное вхождение задачи до
next, сохраняя исходный срок и причину парковки. Ошибка или смена цели не
возвращает попытку. Обычные election, gate, CI и CAS выполняются независимо.
Этот узкий протокол требует item_blockers: true, одиночной очереди MERGE в
режиме auto/tool, встроенного адаптера CLI, costed GitHub-budget route
tool_preflight (не менее 32 core и 32 GraphQL), fallback_handoff: "target-v1"
и уже существующего локального ключа подписей. Старый CLI, отсутствующий ключ, устаревший cache или недоказанный
переход сохраняют ограничение. Исторические парковки, НУЖЕН ЧЕЛОВЕК, typed
history, carried chains и cleanup не получают такого исключения. Установка
нового CLI/worker и создание ключа относятся к отдельному rollout; инспекция
ничего не создаёт на GitHub и не создаёт отсутствующий ключ.
В общей очереди карточка повторяющейся задачи показывает короткое имя серии, а
полный служебный промпт остаётся внутри раскрытой карточки. Если серия поставлена
на паузу, будущий запуск явно помечается PAUSED и не выглядит как готовый к
исполнению queued. Остальные ожидающие задачи также различаются явно:
SCHEDULED означает будущий запуск по времени, а QUEUED — уже готовый запуск,
который ждёт свободного worker.
У задач workflow карточка показывает роль, этап и номер собственного раунда.
История завершённых задач сохраняет их прежний этап после перехода миссии к
следующему. У обычной задачи такой отметки нет, даже если совпадают папка или
текст промпта. Поля workflow_id, role, workflow_round_no и
workflow_stage_* доступны в списке и деталях задачи; неизвестная или
неоднозначная связь остаётся пустой. Planner отмечается по текущей сохранённой
связи плана с задачей, без выдуманного этапа.
Отдельная кнопка «📈 Конвейеры» в главной панели и команда бота /pipeline
показывают любой настроенный pipeline-профиль. Явное «Обновить» считает
внешний backlog через GitHub CLI, сопоставляет его с ёмкостью одного прогона и
атомарно сохраняет полный последний успешный ответ и исторический снимок по
profile_id. Обычное открытие читает только SQLite и не обращается к GitHub —
в том числе после перезапуска server или bot. Возраст, источник и признак
устаревания снимка видны в интерфейсе. Узкое место — этап с максимальным ETA:
учитываются backlog / (capacity × активные реплики), интервал серии и средняя
длительность её выполнения. Без явного replicas число реплик равно единице.
PromptPilot не поставляет профили конкретных проектов. Метки, запросы и лимиты
задаются пользователем в ~/.promptpilot/pipeline_profiles.json (или файле из
PP_PIPELINE_PROFILES), поэтому чужие репозитории не появляются в новой установке.
Если в профиле включён priority_control, дашборд показывает элементы очередей
и позволяет поставить P0…P3 либо вернуть автоматическую оценку. Кнопка
«⚡ Следующим» ставит P0 и переносит будущий запуск всех серий-реплик
соответствующей очереди на ближайшее время; поставленная на паузу серия при
этом остаётся на паузе.
Одинаковые диагностические сигналы в окне конвейера сворачиваются в одну строку
со списком и количеством PR; владелец single-flight барьера всегда показывается
первым, чтобы было видно, какой PR сейчас должен пройти REVIEW → MERGE. В основной
карточке служебные коды и сырая health-сводка заменяются понятными формулировками:
какой PR следующий, выполняется ли REVIEW прямо сейчас, сколько решений ждут
человека и сколько PR ещё переходят со старого формата протокола.
В карточке текущего запуска можно показывать фактический этап и счётчики проверок. Исполнитель сообщает их локальной командой:
pp task-progress --task-id 42 --started-at '2026-11-03T00:00:00+00:00' \
--stage 'Race UI2' --passed 414 --skipped 5 --total 469
pp task-progress --task-id 42 --started-at '2026-11-03T00:00:00+00:00' \
--stage 'Race UI2' --status waiting --wait-reason 'Ожидание PostgreSQL'Номер и время начала должны соответствовать действительно выполняющемуся
запуску. Для исполнителей, которым переданы PP_TASK_ID и
PP_TASK_STARTED_AT, эти два параметра можно опустить. Без достоверного
общего количества тестов счётчики не передают. Пропуски отображаются отдельно
от успешно выполненных тестов. Панель читает эти локальные записи без GitHub,
показывает время этапа и возраст последнего обновления; через три минуты без
обновлений помечает прогресс устаревшим. Запись прогресса не меняет итог задачи,
очередь, допуск, проверки или полномочия исполнителя.
Модуль promptpilot.owner_waits позволяет проектному preflight временно
исключать подтверждённое ожидание конкретного OWNER-кандидата. Он требует
полный свежий состав очереди и точные отпечатки кандидата, HEAD и окружения;
запись действует не дольше десяти минут. Другие кандидаты остаются доступны.
Новая информация, изменение условий, неизвестные данные и истечение срока
возвращают обычную проверку. Это механизм отрицательного допуска: он никогда
не выдаёт решение, ship или право на запись в GitHub. Сам по себе модуль
не включается в профилях и не создаёт ожидания по тексту комментария.
Снимки активных профилей собираются фоново каждые пять минут
(PP_PIPELINE_SNAPSHOT_INTERVAL, 0 отключает). Дашборд показывает Δ backlog,
вход/выход, переходы между очередями, churn, возраст элементов и смысловые итоги
прогонов за 5 и 24 часа, а также тренд backlog за 7 и 30 дней. Это обычные
GitHub API, SQLite и арифметика — LLM не
вызывается и токены не расходуются. После первого запуска историческим карточкам
нужно накопить соответствующее окно; до этого интерфейс честно показывает покрытие.
Команда бота /pipeline переиспользует тот же durable-снимок, поэтому её
обычное чтение не запускает отдельную принудительную диагностику GitHub. До
первого успешного фонового или явного обновления панель честно показывает
«нет снимка», не подменяя неизвестный backlog нулём.
В таблице каждого этапа видны номер, время и итог последнего завершённого запуска;
отдельная карточка показывает время последнего REVIEW. Для Codex PromptPilot
использует JSONL-режим CLI и сохраняет точные input/output tokens. Старые
текстовые запуски остаются с пометкой «нет данных»: их расход не оценивается по
длительности и не выдумывается задним числом. «ГОТОВО без действий» учитывается
отдельно от продуктивных прогонов. Исторические НЕ СМОГ и технические падения
остаются в статистике окна, но красное здоровье учитывает только ещё не
восстановленные инциденты: последующий штатный итог той же серии помечает старый
сбой как восстановленный.
Локальным агентам PromptPilot добавляет в PATH каталоги из PP_GH_EXE и
PP_GO_EXE. На Windows также автоматически обнаруживаются стандартные установки
GitHub CLI и Go в C:\Program Files. Поэтому tray/служба не зависит от того,
успело ли приложение получить обновлённый пользовательский PATH.
Идентификатор JSONL-сессии сохраняется сразу после события thread.started, а
не только в финале. Если worker или процесс Codex оборвался после создания
ветки/worktree, retry запускает codex exec resume для той же сессии. Благодаря
этому продолжение знает о собственных незавершённых изменениях и не объявляет их
«чужой работой» после повторного запуска.
stop.ps1 не полагается только на .pp-pids.json: после hot-reload PID worker
меняется. Скрипт получает актуальный worker PID из heartbeat API, server PID —
из слушателя PP_PORT, проверяет командную строку процесса и лишь затем
останавливает дерево. Поэтому штатный stop не оставляет скрытый worker, который
продолжает расходовать токены после «остановки» старого launcher PID.
Рекомендация считается прозрачно: backlog / (capacity × активные реплики)
даёт число необходимых параллельных прогонов, а один цикл равен
интервал + средняя длительность прогона — повтор
назначается после завершения предыдущего запуска. Поэтому серия 15m со средним
выполнением 30 минут даёт примерно один результат за 45 минут, а не четыре в час.
Профиль задаёт желаемое время очистки (target_clear_hours, обычно 8 часов),
интервал выбирается из практичных пресетов. Если одна длительность прогонов уже
не позволяет уложиться в цель, дашборд предлагает увеличить ёмкость или
параллелизм. ETA — нижняя оценка: она не учитывает новые входящие задачи и
ожидание более приоритетных серий в общей очереди worker; для этапа с
manual_gate: true ускорение не предлагается, потому что его ограничивает
решение человека.
Worker публикует heartbeat в общей SQLite БД. Активный профиль немедленно
становится красным, если heartbeat отсутствует или устарел; running, который
пережил настроенный task_timeout, отдельно показывается как зависший запуск.
Это позволяет отличить медленную очередь от остановившегося исполнителя без
ожидания пятичасового окна статистики. Завершившийся итогом НЕ СМОГ или
технически упавший прогон тоже сразу делает профиль красным: жёлтая проектная
диагностика больше не маскирует потраченные токены без результата.
Каждая строка расписания — самостоятельная серия со своим working_dir.
Аналитический профиль объединяет нужные серии в одну логическую цепочку по
series_contains. Несколько проектов — это несколько профилей; раздел
«Конвейеры» покажет их в выпадающем списке и не смешивает снимки. Пользовательский файл по умолчанию:
~/.promptpilot/pipeline_profiles.json:
{
"profiles": {
"my-project": {
"title": "MyProject: сопровождение",
"repository": "owner/my-project",
"target_clear_hours": 8,
"github_budget": {
"minimum_remaining": {
"core": 250,
"search": 2,
"graphql": 100
},
"priority_one_headroom": {
"core": 1200,
"search": 12,
"graphql": 1000
},
"costs": {
"insights": {"core": 1200, "search": 10, "graphql": 500},
"skill": {"core": 3750, "search": 20, "graphql": 2000},
"tool_preflight": {"core": 1200, "search": 10, "graphql": 500},
"tool": {"core": 2000, "search": 10, "graphql": 1500},
"fallback_targeted": {"core": 3000, "search": 20, "graphql": 2000}
},
"reset_grace_seconds": 60,
"lease_seconds": 900,
"busy_retry_seconds": 30,
"starvation_timeout_seconds": 900,
"unavailable_retry_seconds": 300
},
"priority_control": {
"trusted_account": "YOUR_GITHUB_LOGIN",
"default_level": "p2",
"aging_hours": 168,
"max_items": 12
},
"queues": [
{
"id": "plan",
"title": "Планы",
"query": "is:issue is:open label:plan-needed label:approved -label:hold -label:manual -label:plan-in-review",
"capacity": 1,
"series_contains": "MyProject - PLAN",
"backlog_diagnostic_field": "plan_candidates",
"wake_when": {"field": "plan_candidates"},
"wake_after_success": ["review"],
"dispatch_gate": {
"skip_when_empty": true
}
},
{
"id": "fix",
"title": "Исправления",
"queries": [
"is:issue is:open label:ready-fix -label:in-work -label:needs-decision -label:plan-needed -label:plan-in-review -label:hold -label:manual",
"is:issue is:open label:approved -label:in-work -label:plan-needed -label:plan-in-review -label:hold -label:manual"
],
"capacity": 1,
"series_contains": "MyProject - FIX",
"backlog_diagnostic_field": "fix_candidates",
"wake_when": {"field": "fix_candidates"},
"wake_after_success": ["review"],
"dispatch_gate": {
"skip_when_empty": true
}
},
{
"id": "review",
"title": "Ревью",
"query": "is:pr is:open -label:changes-requested -label:needs-decision -label:hold",
"capacity": 2,
"series_contains": "MyProject - REVIEW",
"backlog_diagnostic_field": "review_backlog",
"wake_when": {"field": "review_candidates"},
"wake_after_success": ["merge"],
"execution": {
"mode": "auto",
"command": ["{python}", "-m", "promptpilot.project_pipeline", "--config", "pipelinectl.json", "next", "{stage}"],
"required_paths": ["pipelinectl.json"]
}
},
{
"id": "merge",
"title": "Слияние",
"query": "is:pr is:open label:ship",
"capacity": 1,
"series_contains": "MyProject - MERGE",
"backlog_diagnostic_field": "merge_candidates",
"wake_when": {"field": "merge_executable"},
"wake_after_success": ["review"],
"execution": {
"mode": "auto",
"command": ["{python}", "-m", "promptpilot.project_pipeline", "--config", "pipelinectl.json", "next", "{stage}"],
"required_paths": ["pipelinectl.json"]
},
"dispatch_gate": {
"skip_when_empty": true,
"defer_when_diagnostics_match": [{
"field": "review_candidates",
"key": "stage",
"values": ["integration-review", "legacy-integration-review"]
}],
"defer_for": "10m"
}
}
],
"health_check": {
"command": ["/absolute/path/to/project-health", "-json"],
"working_dir": "/absolute/path/to/project",
"timeout_seconds": 180,
"cache_seconds": 1800
}
}
}
}При PP_CONCURRENCY=3 профиль может закрепить три логических слота за разными
частями бесконечного конвейера. Это универсальная конфигурация: PromptPilot не
знает названий этапов заранее и связывает их с очередями того же профиля:
"scheduler": {
"lanes": [
{"id": "integration", "queues": ["merge", "review"], "borrow": true},
{"id": "production", "queues": ["review", "fix"], "borrow": true},
{"id": "intake", "queues": ["triage", "plan"], "borrow": true}
]
}Каждая запись — один слот, queues задаёт его локальный порядок. Поэтому
интеграционный слот сначала берёт MERGE, а при его отсутствии REVIEW;
производственный — REVIEW, затем FIX; входной — TRIAGE, затем PLAN. Если своей
работы нет, borrow: true разрешает слоту взять runnable-задачу другой полосы.
Занятый слот не считается свободным до завершения точного запуска. Выбор и
claim одной задачи происходят в одной SQLite-транзакции, поэтому два слота не
получат одно вхождение. Без scheduler остаётся прежний порядок
priority → created_at → id.
Полоса становится выделенным физическим слотом только когда
PP_CONCURRENCY не меньше числа настроенных lanes. При меньшей
конкурентности это остаются детерминированные предпочтения свободных слотов, а
не резерв ёмкости; отдельную гарантию от ожидания GitHub API даёт описанный ниже
github_budget.starvation_timeout_seconds.
При включённом starvation timeout конфигурации scheduler нужна хотя бы одна
recovery-полоса с borrow: true; иначе lane policy считается невалидной и worker
откатывается к глобальному claim, чтобы переименованная очередь не удерживала
admission-эстафету навсегда.
Очередь REVIEW может явно владеть несколькими независимыми сериями. Для этого
используется отдельное поле replicas; capacity по-прежнему означает, сколько
целей обрабатывает один запуск, и не подменяет число исполнителей:
{
"id": "review",
"capacity": 1,
"replicas": 2,
"series_contains": "MyProject - REVIEW",
"execution": {
"mode": "auto",
"stage": "review",
"command": [
"{python}", "-m", "promptpilot.project_pipeline",
"--config", "pipelinectl.json", "next", "{stage}"
],
"required_paths": ["pipelinectl.json"]
}
}Нужно создать ровно две активные повторяющиеся серии, например
MyProject - REVIEW 1 и MyProject - REVIEW 2. Каждой задаётся существующий
абсолютный и отличный от остальных working_dir — обычно два git worktree.
Отличие проверяется по identity каталога (device/inode), поэтому symlink и
варианты регистра одного APFS/NTFS-каталога не считаются разными репликами.
Реплики выполняются на той же машине и используют общую локальную SQLite:
удалённые machine, динамический worktree задачи, отсутствующие каталоги и
дубли путей блокируются до запуска провайдера. Если настроен scheduler, REVIEW
должен присутствовать минимум в двух lanes; без scheduler достаточно общей
конкурентности worker не меньше двух.
В pipelinectl.json для параллельного REVIEW обязательны
review_completion_gate: "target-v1" и fallback_handoff: "target-v1".
Необязательный target_reservation_ttl_seconds задаёт TTL локальной резервации
(по умолчанию равен review_lease_seconds, допустимо 300–28800 секунд):
{
"review_completion_gate": "target-v1",
"fallback_handoff": "target-v1",
"parallel_content_review": false,
"review_lease_seconds": 7200,
"target_reservation_ttl_seconds": 7200
}До запуска модели next review атомарно резервирует точный
repository/stage/PR/HEAD за конкретной попыткой PP_TASK_ID; mutex действует
на весь PR даже при смене stage или HEAD. Если первая цель уже занята другой
репликой, election берёт следующую, не начиная повторное ревью. Обычный
complete review и gate-fallback проверяют и продлевают ту же резервацию
непосредственно перед первой GitHub-мутацией. Обычный terminal exit освобождает
резервацию. TTL задаёт частоту lease heartbeat, но истёкшая строка намеренно не
крадётся, пока её exact task attempt всё ещё running: после жёсткого падения
startup recovery сначала по сохранённому ownership descriptor подтверждает
остановку headless/Herdr-провайдера, затем атомарно requeue/cancel задачи и
освобождает fence. Если остановку доказать нельзя, задача и PR остаются в
quarantine; вручную удалять такую резервацию небезопасно. Резервация — только
локальный scheduling fence и не заменяет GraphQL/HEAD/timeline/CAS-гейты.
parallel_content_review: true — отдельный opt-in для двух REVIEW-реплик.
Если checker публикует parallel_review_candidates, свободная реплика может
взять обычный PR, пока первая проверяет интеграционную дельту. В этом списке
допустимы только обычные REVIEW до третьего круга: полный skill/fallback и
следующий интеграционный PR по-прежнему ждут владельца. Каждый параллельный PR
получает свою атомарную резервацию PR/HEAD и подписанный target-v1 lease;
перед публикацией повторно проверяется его собственная timeline. Старый checker
или отсутствие второй реплики закрывают только параллельный opt-in: обычное
содержательное REVIEW и штатный fallback интеграционного владельца продолжаются.
Отсутствующее поле allowlist у старого checker не даёт ни одной параллельной цели.
Если поле присутствует, его целостность проверяется при любом значении флага:
повреждённый или противоречивый снимок по-прежнему закрывает гейт. Отказ точного
target-gate параллельного PR даёт wait, без расширения в full-skill fallback.
MERGE остаётся
single-flight и не берёт PR из этого списка.
После включения opt-in у REVIEW-очереди wake_when.field можно переключить
с review_candidates на review_dispatch_candidates: это только сигнал
пробуждения для владельца и свободной реплики, а не разрешение на запись.
run_now, wake_when, wake_after_success и adaptive_cadence применяются ко
всем совпавшим репликам. Дашборд показывает каждую серию, её каталог и состояние,
а ETA использует суммарную параллельную ёмкость. Сейчас replicas > 1
намеренно разрешено только для REVIEW; MERGE и прочие изменяющие этапы остаются
single-flight.
Полоса выбирает только серию TRIAGE. Порядок целей внутри неё — recovery,
ручной P0, затем обычный backlog — остаётся контрактом репозиторного next и
его свежих gate-проверок. Так машинное расписание не может обойти recovery или
самостоятельно назначить GitHub-цель.
Очередь может также владеть своей частотой:
{
"id": "fix",
"adaptive_cadence": {
"idle_recurrence": "30m",
"busy_recurrence": "15m",
"backlog_above": 3
}
},
{
"id": "triage",
"adaptive_cadence": {
"idle_recurrence": "30m",
"busy_recurrence": "15m",
"backlog_above": 0,
"empty_runs_before_idle": 2
}
},
{
"id": "plan",
"wake_when": {"field": "plan_candidates"},
"adaptive_cadence": {
"idle_recurrence": "4h",
"event_wake": true
}
}Полный свежий снимок включает быстрый интервал только выше порога. Для TRIAGE
он снимается существующим счётчиком серии после двух последовательных ПУСТО;
FIX возвращается к 30 минутам сразу при backlog ≤ 3. PLAN просыпается через
wake_when/wake_after_success, а 4 часа остаются страховкой от потерянного
события. Обычное чтение кэша расписание не меняет. Более длинный интервал не
откладывает уже назначенный ранний запуск.
priority_control необязателен. Он использует GitHub-метки queue:p0…
queue:p3 для ручного решения и queue:auto:p0…queue:auto:p3 для оценки,
перенесённой с issue на PR. Ручная метка старше автоматической; без обеих
critical/security получает P0, bug — P1, enhancement/documentation/default —
P2, question — P3. Каждые aging_hours ожидания эффективный уровень повышается
на один до P1, поэтому низкий приоритет не означает вечное ожидание, а P0
остаётся полосой для действительно срочной работы. Если
проектный исполнитель сортирует кандидатов сам, он должен применять те же
правила: PromptPilot управляет метками и показывает порядок, но не подменяет
безопасный выбор внутри репозитория. Проверка trusted_account не даёт случайно
менять приоритет под другой учётной записью GitHub CLI.
Если выбранное решение требует сначала архитектурного плана, FIX должен
передать issue меткой plan-needed, сохранив человеческий approved. Отдельная
серия PLAN создаёт PR только с плановым документом и переводит issue в
plan-in-review; такой PR проходит обычные REVIEW, человеческий ship и MERGE.
Ручная queue:p0…queue:p3 при этом копируется с issue на plan-PR, поэтому
ускорение действует на весь маршрут, а не теряется перед REVIEW плана.
После merge проектный handoff снимает plan-in-review и возвращает issue в FIX.
Так «сначала план» является исполняемым этапом, а не тупиком needs-decision.
В workflow со sticky-разрешением метка ship означает «слить этот точный HEAD,
когда его REVIEW успешно завершится». Она не исключает PR из первой review-
очереди и может быть поставлена до финального служебного completion: HEAD epoch,
последний trusted label-transition и последующий каноничный review proof вместе
защищают решение от переноса на другой код. Поэтому человеку не приходится
снимать и повторно ставить ship из-за гонки между UI и завершением REVIEW.
github_budget необязателен и включается только присутствием в профиле. Перед
GitHub-работой PromptPilot читает бесплатный для primary REST rate limit
GET /rate_limit, а GraphQL-остаток и текущий viewer — коротким
GraphQL-запросом, обычно стоимостью в один GraphQL point. Поле
minimum_remaining задаёт аварийный остаток, который
нельзя обещать ни одному запуску, а costs — консервативную верхнюю оценку
расхода каждого маршрута. Допуск вычисляется как
remaining - резервы выполняющихся задач - cost маршрута >= minimum_remaining.
Необязательный точный вектор priority_one_headroom сохраняет поверх аварийного
остатка запас для задач PromptPilot с приоритетом 1: для задач приоритетов
2–10 он прибавляется к minimum_remaining, а задача приоритета 1 может его
использовать. Полное обновление статистики считается низкоприоритетной работой и
тоже сохраняет этот запас. Ненулевой priority_one_headroom требует полной
таблицы costs во всех включённых профилях с тем же GitHub token; при общем
token PromptPilot покомпонентно применяет максимальный запас из этих профилей.
Это admission-резерв для срочного запуска, а не гарантия неизменности живого
лимита GitHub во время уже работающих задач.
Опция essential_snapshot_headroom: true (по умолчанию выключена, требует
costs) позволяет необходимому полному обновлению очередей использовать мягкий
запас P1, если совместимого полного снимка нет, он устарел или инвалидирован.
Состояние снимка повторно проверяется под общей scan-lease: обновление свежего
снимка и дополнительные запросы отчёта сохраняют обычный низкий приоритет.
Аварийный minimum_remaining, резервы выполняющихся задач и передача бюджета
самой старой ожидающей задаче остаются обязательными. Опция не снимает WIP,
ship, CI или HEAD-проверки.
Для essential-профиля можно отдельно задать github_budget.refresh_ahead_seconds
(целое от 1 до 299, по умолчанию 0). Например, 150 запускает фоновое
обновление, когда до истечения пяти минут остаётся 150 секунд. Самплер учитывает
длительность сбора и публикации, а не добавляет к ней ещё пять минут сна;
обычные профили сохраняют свой интервал. Настройка требует включённого budgeting
с полной таблицей costs. Досрочный scan проходит прежний допуск, сохраняет
резервы и мягкий запас P1; при отказе действует существующий defer/backoff.
Срок действия Source не продлевается, старый timestamp не обновляется без
полной публикации, и ни одна проверка Native/Source не снимается. Ошибка
checker остаётся отказом. Более частый сбор расходует API-бюджет, поэтому режим
включается явно; числовые оценки расходов и предельные остатки не меняются.
При essential_snapshot_headroom допуск задач также оставляет сверх обычного остатка стоимость
одного необходимого scan: покомпонентный максимум costs.insights включённых
essential-профилей общего аккаунта. Этот запас сохраняется и для P1, и для
самого старого ожидающего задания; параллельные резервы проверяют его атомарно.
Для несрочных задач применяется максимум этого запаса и мягкого P1-запаса,
а не их сумма: уже защищённая стоимость scan не учитывается дважды.
Для P1 заимствуемой остаётся только часть мягкого запаса сверх стоимости scan.
Сам scan проверяется по прежнему остатку со своей стоимостью — второй раз запас
не прибавляется. Это предотвращает запуск долгой работы, чьи суммарные резервы
уже не оставляют места для заключительного обновления даже после reset Search.
Расход сторонних клиентов и фактическое превышение оценки costs по-прежнему
могут закрыть поздний гейт; гарантии неизменности живого лимита нет.
Общий статус обновления очереди публикует только scan insights. Отказ или
успешный допуск отдельной задачи не заменяет и не очищает этот статус.
Это не отменяет настоящую инвалидизацию снимка: устаревшие epoch, профиль,
lease или TTL по-прежнему требуют нового допущенного полного обновления.
Резерв хранится в общей SQLite БД, привязан к точной попытке задачи и снимается
в finally, поэтому два worker-потока могут безопасно выполнять дешёвые
REVIEW/MERGE одновременно, не расходуя один и тот же остаток дважды. Полный
skill остаётся дорогим: стартовые 3750 + 250 Core сохраняют прежний защитный
порог около 4000, тогда как project tool не блокируется тем же blanket-порогом.
Значения в примере намеренно консервативны. Для другой конфигурации измерьте
расход каждого маршрута на самой большой штатной очереди и округлите верхнюю
границу вверх; заниженная cost превращает резерв в ложную гарантию.
При отказе приёма новой работы dispatch_gate возвращает дополнительный
wip_diagnostics (pp-wip-diagnostics-v1, authoritative: false). В нём отдельно
видны состояние снимка (missing/partial/stale/fresh), его возраст и TTL,
состояние последнего обновления и наблюдение WIP с настроенным порогом.
refresh_budget сохраняет именно решение допуска scan: остаток GitHub,
резервы, стоимость, подписанный прогноз и фактически применённый безопасный
остаток, включая запас P1. Эти числа копируются из admission result, а не
пересчитываются из настроек UI. Общий github_budget по-прежнему описывает
текущий zero-cost before-route остаток: его allowed: true не означает,
что обновление снимка допущено. Если старый формат не сохранил scan decision,
refresh_budget равен null; нулевая стоимость не подставляется.
Старый полный WIP и неполное наблюдение помечаются раздельно. Их наличие не
открывает допуск: действующие action, defer_for, пороги и гейты сохраняются.
snapshot.retry_at — нижняя граница повторного refresh из последнего отказа,
а не обещание запуска worker точно в это время. Для отсутствующих данных
возвращается null. Диагностика не делает дополнительных GitHub scan и не
копирует произвольный текст исключений или другие поля admission в сообщение.
При действительно низком живом лимите задача откладывается до reset ресурса
плюс reset_grace_seconds. Если лимит достаточен, но временно обещан другой
задаче, ожидание остаётся прерываемым: освобождение точной резервации сразу
будит такие задачи, а busy_retry_seconds служит страховочным опросом после
аварии процесса. Приоритетная эстафета сохраняется до фактического резервирования
бюджета, поэтому уже запущенный менее приоритетный этап не обгоняет разбуженный.
Жёсткий reset живого лимита этим сигналом не сокращается.
Необязательный starvation_timeout_seconds (по умолчанию 0, выключено;
рекомендуемое начальное значение 900) ограничивает голодание при непрерывном
потоке более приоритетных запусков. После дедлайна самая старая задача с
durable reservation/priority/scan handoff (но не с ожиданием живого quota reset)
получает временную admission-эстафету:
новые резервы ждут, пока текущие освободятся и она зарезервирует бюджет. Более
новая задача не обходит более старую; при одинаковом времени ожидания порядок
задают priority и id. Эстафета меняет только порядок: исходный priority задачи,
minimum_remaining и priority_one_headroom не меняются, поэтому P3/P4 не
заимствуют запас P1. Если без чужих reservations живого лимита всё равно мало,
задача переходит в обычное ожидание reset и сразу освобождает эстафету. Для
профилей с общим GitHub token действует минимальный положительный timeout;
отсутствие настройки во всех профилях полностью сохраняет прежнюю строгую
приоритетную семантику.
Недоступный лимит, повреждённый ledger или некорректная конфигурация работают
fail-closed на unavailable_retry_seconds. Для профилей с одним GitHub token и
PP_DATA_DIR PromptPilot покомпонентно применяет самый большой настроенный hard
reserve; одинаковые значения упрощают эксплуатацию, а оценки маршрутов могут
различаться. Профиль без costs сохраняет прежнюю семантику: весь
minimum_remaining служит единым стартовым порогом без provider-reservation.
Одна SQLite lease на общий PP_DATA_DIR сериализует дорогие GitHub-сканы между
worker, веб-сервером и ботом. Lease обновляется во время работы, автоматически
перехватывается после истечения и проверяется в той же транзакции, что публикация
снимка: потерявший владение процесс не может записать устаревший результат.
Фоновый sampler, ручное обновление и preflight перед задачей используют тот же
барьер. wake_after_success задаёт локальный граф зависимостей: успешный этап
помечает старый снимок устаревшим и ставит перечисленные серии на ближайший
запуск без повторного полного GitHub-скана; их свежий project preflight остаётся
обязательным барьером. Поэтому целью может быть только очередь с настроенным
execution; пустой массив лишь инвалидирует снимок без немедленного запуска.
Если целевая серия уже выполняется или ждёт retry после rate limit, wake-intent
сохраняется в SQLite и применяется к её следующему recurrence; сам backoff при
этом не сокращается, а событие не теряется в гонке.
Если бюджет мал, последний хороший снимок
остаётся доступен, но не будит серии; UI и бот показывают причину и точное время
следующей попытки, возраст последнего /rate_limit, живые резервы и остаток,
который ещё можно выдать. Обычное чтение кэшированного дашборда берёт это из
SQLite и не обращается к GitHub.
Без github_budget сохраняется прежнее поведение профиля.
health_check необязателен. Это проектная команда без shell, которая должна
вернуть JSON со state: green|yellow|red, summary и массивом findings.
PromptPilot по умолчанию переиспользует результат дорогой проверки 30 минут,
продолжая собирать снимки активных очередей каждые 5 минут. Кнопка «Обновить»
обходит оба кэша, пока worker не поставлен на общую паузу. cache_seconds
позволяет изменить период; ошибка checker
кэшируется не дольше минуты, чтобы временный отказ быстро восстановился. Панель
также показывает остаток и время сброса GitHub REST, Search и GraphQL budgets.
Общая пауза — строгий барьер GitHub I/O: sampler, завершение ранее запущенной
задачи и даже явное «Обновить» сохраняют последний снимок без нового опроса.
Текущие heartbeat, pause и статусы задач накладываются на него из локальной БД,
поэтому состояние worker остаётся актуальным. Команда
не должна вызывать LLM; для GitHub-проверок путь из PP_GH_EXE передаётся ей как
GH_EXE. Таймаут по умолчанию — 180 секунд; для больших репозиториев его можно
увеличить до 900. Ошибка или timeout самой команды отображается как
«диагностика не выполнена», а не как доказанное нарушение инварианта.
dispatch_gate тоже необязателен и настраивается у конкретного этапа. Перед
запуском провайдера PromptPilot использует только полный общий снимок не старше
пяти минут; устаревший или частичный снимок не может объявить очередь пустой;
проектная процедура остаётся источником свежей проверки перед мутацией. При
skip_when_empty пустой запуск завершается как ПУСТО, не запуская LLM. Поле
defer_when_diagnostics_nonempty задаёт простую зависимость от непустого массива
в JSON health_check. Когда один массив содержит несколько состояний, используйте
defer_when_diagnostics_match: в примере MERGE возвращается в pending только для
элементов со stage integration-review/legacy-integration-review, но проходит
для integration-merge-ready. Это даёт автоматический порядок REVIEW → MERGE
даже при более высоком приоритете MERGE и не расходует токены на ожидание. Если
профиль или checker сломан, gate fail-open: задача запускается обычным способом,
чтобы ошибка наблюдаемости не остановила полезную работу.
Для этапа, чья каноническая процедура требует свежий Native-снимок ещё до
начала работы, можно явно задать dispatch_gate.require_fresh_snapshot: true.
Опция принимает только JSON boolean; другое значение откладывает запуск как
ошибку конфигурации. При отсутствии полного доступного снимка, stale,
invalidated, refresh_blocked или ошибке чтения задача возвращается в pending
не ранее чем через 30 секунд до загрузки провайдера и резервирования бюджета
исполнения, чтобы не пропускать следующее короткое окно свежести кэша.
Это ожидание (snapshot_admission.state), а не ПУСТО и не успешный прогон.
При отсутствии пригодного снимка проверка сама выполняет обычный budgeted refresh
под общим scan lease, до запуска провайдера; отказ или ошибка оставляют задачу
в pending. Под canonical profile lock повторно проверяется кэш: несколько
готовых запусков используют уже опубликованный свежий снимок. Требуется полная
membership именно текущей очереди, а не новая глобальная зависимость от
несвязанных очередей; ошибки настроенного checker блокируют запуск, его
содержательные red-находки обрабатываются прежними проектными гейтами.
При паузе worker или смене профиля во время refresh запуск откладывается.
Ручной/API force-refresh сохраняет прежнее поведение. Свежий снимок пропускает задачу к прежним
WIP, ownership, бюджетным и проектным гейтам; свежесть не разрешает мутацию.
По умолчанию опция выключена: прежний fallback к проектной проверке сохраняется.
Опция не меняет TTL, период sampler, API floors или правила защищённых задач.
wake_when необязателен. Он указывает поле диагностики, которое означает, что
этапу уже есть что делать. После полезного (ГОТОВО) запуска и при фоновом
обновлении профиля PromptPilot переводит ближайший pending-запуск серии на
«сейчас». Один и тот же неизменившийся снимок будит серию только один раз:
НУЖЕН ЧЕЛОВЕК, НЕ СМОГ или другой результат не создаёт бесконечный цикл и не
тратит токены повторно. Новое состояние диагностики снова разрешает автозапуск;
ручной «Запустить сейчас» всегда остаётся доступен. Можно добавить key и
values, если готовность определяется только некоторыми состояниями элементов.
При ПУСТО, паузе серии или пустом поле пробуждения нет.
backlog_diagnostic_field заменяет приблизительный размер GitHub Search точным
массивом из health_check. Это особенно важно для REVIEW: поисковый запрос
намеренно не исключает stale-метку reviewed, а checker уже различает новый
HEAD, актуально проверенный HEAD и интеграционный handoff. Для REVIEW используйте
review_backlog (вся ожидающая работа), а wake_when оставьте на
review_candidates (только исполняемая сейчас работа) либо, после включения
параллельного opt-in, на review_dispatch_candidates. Для MERGE аналогично:
merge_candidates показывает весь backlog, а merge_executable содержит только
PR, который разрешено сливать прямо сейчас с учётом single-flight barrier.
Не исключайте reviewed из поискового запроса REVIEW: метка относится к старому
HEAD и после нового push может остаться. Канонический health_check отличает
актуальное ревью (reviewed_waiting_ship) от устаревшей метки и возвращает новый
HEAD в review_candidates. Для двухполосной схемы он также публикует
content_review_candidates, integration_owner, merge_candidates и
merge_executable: single-flight сериализует интеграцию. Пока владелец в
интеграционном REVIEW, обычные PR остаются backlog; opt-in
parallel_content_review позволяет второй реплике брать только явно указанные
checker'ом parallel_review_candidates. Уже взятый содержательный REVIEW
остаётся валиден, если
параллельно появился или сменил состояние несвязанный integration_owner;
завершение всё равно проверяет собственные HEAD и timeline lease этого PR.
Уже запущенная локальная Native-задача с действующим skill или
fallback_targeted-резервом может
обновить полный Source-снимок командой
pp pipelinectl source-refresh --profile <profile-id>. Команда использует
worker PP_TASK_ID, фактические start/session/priority и существующий резерв;
переданный PP_TASK_STARTED_AT обязан совпадать. Отсутствующий timestamp
старого обычного worker разрешается по точной running-строке, без ручной
подстановки. При чужой, отменённой или изменившейся попытке обновление запрещено.
Это обычный costed insights scan под общим scan lease с реальным priority
задачи. Маршрут берётся только из единственного существующего Native-резерва,
его стоимость обязана совпадать с текущей канонической политикой этого маршрута.
Маршрут нельзя выбрать аргументом CLI или подсказкой в окружении.
Собственный резерв учитывается один раз и не создаётся повторно;
чужие резервы не очищаются и не изменяются. Например, при Search30,
собственном резерве12, цене scan10 и hard floor2 для priority1 достаточно24;
soft P1 headroom нижних приоритетов сохраняется. Полный checker и cache/history
публикуются через штатные CAS и дополнительный task/session/admission fence.
source_refreshed:true выдаётся только после собственной полной публикации;
команда не разрешает продуктовые мутации, не запускает исполнителя или задачу.
При ожидании возвращается exit3, при отказе — exit2. Обычные project-only
команды pipelinectl, включая capabilities, продолжают работать без Native DB.
Если нужны только свежие лимиты для отдельного бюджетного checkpoint,
используй pp pipelinectl budget-refresh --profile <profile-id> из той же
допущенной Native-задачи. Команда сохраняет прежние стоимость insights,
резервы, priority и floors, но останавливается после защищённой записи лимитов:
Source/checker/cache/history не обновляются, Source и mutation admission не
выдаются. Результат не продлевает TTL и не заменяет последующие гейты.
Подробности и семантика отказов — в
описании task-bound budget refresh.
Worker передаёт фактический PP_TASK_STARTED_AT вместе с PP_TASK_ID обычным
CLI и новым herdr-панам, заменяя унаследованные/provider значения. Это marker
попытки, а не изменение приоритета или разрешение обходить очередь/бюджет.
Отдельная команда pp pipelinectl --config pipelinectl.json inventory
показывает идентичность PR из GitHub в режиме чтения. Байтовый контракт,
эталонные фикстуры и границы первого среза описаны в
PR_IDENTITY_V1.md. Протокол разрешений v2 пока выключен.
Для поиска влитых PR после простоя доступны две команды:
pp pipelinectl --config pipelinectl.json tail-discover --max-pages 5
pp pipelinectl --config pipelinectl.json tail-backlog --json --limit 100tail-discover читает GitHub и сохраняет кандидатов и курсор в локальной
SQLite PromptPilot (PP_DATA_DIR). Первый обход охватывает историю слияний
в заданную базовую ветку. Повторяйте команду с тем же каталогом данных,
пока она возвращает state: incomplete. После двух совпавших проходов
всех интервалов результат содержит state: complete и дату, по которую
история проверена. Следующий обход захватывает последние 48 часов предыдущего.
При сбое источника команда возвращает ненулевой код. После устранения причины
её можно запустить повторно.
tail-backlog показывает сохранённые PR и счётчики для репозитория и базовой
ветки из конфигурации. Если для этой ветки ещё нет совместимой контрольной
точки, discovery и age_seconds равны null. Уже найденные PR этой ветки
остаются в очереди. Для следующей страницы передайте значение next_after
через --after. Статус pending-proof означает,
что PR найден и замечания его ревью ещё предстоит проверить. Команды
не создают задачи или комментарии в GitHub.
Ручной и плановый обработчик OneBase берут работу из одной очереди, когда
используют одну установку PromptPilot, один файл конфигурации, один
PP_DATA_DIR и оператор явно включил "tail_durable_drain": true.
Включение рабочего профиля предусмотрено после совместной приёмки этапов B и C.
- После
tail-discoverкомандаtail-nextперечитывает PR и историю ревью в GitHub. Она возвращает до пяти кандидатов, причину ожидания по проверенным PR и точную версию источника для готовых пунктов. Доказанное пустое ревью или допустимая старая отметка завершения закрывают запись локально. - Каноническая процедура проверяет источник через
tail-gate --number M --version V. Перед созданием она сверяет находку со свежей базовой веткой и проверяет смысловые дубли текущего прогона. - Для проверенного пункта процедура вызывает
tail-create --number M --version V --item N [--context-file PATH]. Эта команда пишет в GitHub. В описание заявки входят заголовок исходного PR, формулировка из ревью и ссылка на него. В файле UTF-8 можно пояснить, где в свежей базовой ветке проявляется проблема и к чему она приводит. Это пояснение видно триажу. Ключ защиты от дублей вычисляется по заголовку и формулировке пункта ревью. Файл со служебными маркерами отклоняется до записи. Она перечитывает разрешение перед каждой записью, проверяет захват пункта и сохраняет постоянные маркеры против повторного создания. Результатexisting-issueпередаёт номер в процедуру восстановления. Приambiguous-createоператору нужно сверить результат по маркерам.
Для REVIEW/MERGE повторяемые GitHub-проверки можно вынести из промпта в проектный CLI. PromptPilot не привязан ни к Claude, ни к Codex: он сам выполняет безопасный preflight до запуска провайдера и только затем решает, нужна ли модель. В очередь профиля добавляется:
"execution": {
"mode": "auto",
"stage": "review",
"command": [
"{python}", "-m", "promptpilot.project_pipeline",
"--config", "pipelinectl.json", "next", "{stage}"
],
"required_paths": ["pipelinectl.json"],
"probe_command": [
"{python}", "-m", "promptpilot.project_pipeline",
"--config", "pipelinectl.json", "capabilities"
]
}{python} заменяется интерпретатором запущенного PromptPilot, {stage} — id
этапа. Команда и относительные пути проверяются в working_dir серии без
вызова LLM, после чего command выполняется с таймаутом timeout_seconds
(по умолчанию 180 секунд). Режимы:
| Режим | Поведение |
|---|---|
auto |
empty/wait завершается без модели; audit/merge/cleanup получает короткий prompt с готовым lease; fallback или недоступный CLI использует исходный prompt/скилл |
tool |
CLI обязателен; при отсутствии, ошибке или fallback запуск завершается НУЖЕН ЧЕЛОВЕК без токенов |
skill |
всегда используется исходный prompt, как до появления pipelinectl |
Эффективный маршрут (auto → tool, auto → skill или blocked) виден в
дашборде и боте для каждого этапа. Это позволяет заметить незапланированный
fallback сразу, а не по суточному расходу токенов. Пустой REVIEW/MERGE
закрывается самим preflight с явной записью «провайдер не запускался».
Для replicas > 1 небезопасный нетаргетированный auto → skill отключён:
недоступный CLI, malformed lease или fallback без signed target блокирует запуск
до модели, а доказанный target-v1 handoff остаётся разрешён.
Интеграционный владелец на integration-review или
legacy-integration-review оставляет MERGE на полном skill-маршруте — кроме
доказанного переноса ship через один механический base-sync (opt-in
base_sync_carry, см. ниже).
REST health не доказывает timeline lineage: одинаковый снимок может означать
как штатное ожидание REVIEW, так и испорченный handoff, где MERGE обязан снять
устаревший ship. Поэтому такой снимок нельзя превращать в action=wait без
полного fallback-гейта.
Экспериментально, не включать в работе (#42): opt-in base_sync_merge: true
в pipelinectl.json не завершён. После update-branch он не публикует
pp:base-sync-intent/done, поэтому обновлённый владелец уходит в
legacy-integration-review и всё равно требует полного скилла, а механическое
интеграционное REVIEW (проверки 1–6) не реализовано: для него нужны
provenance-поля от health-checker проекта. capabilities показывает
"base_sync_merge": "experimental", выдача такого lease пишет предупреждение в
stderr, а текущее поведение закреплено tests/test_base_sync_public_path.py.
Как задумано:
владелец барьера обслуживается детерминированно, когда его готовность доказана.
В состоянии BEHIND выдаётся lease update-branch: единственная мутация —
обновление ветки под CAS expected_head_sha, ответ проверяется до какого-либо
публикуемого факта (конфликт 422 ничего не публикует — урок ошибки из #42);
сам MERGE и done-маркер выполняются обычным путём на обновлённом HEAD.
Если после последнего base-sync у текущего HEAD уже есть новый канонический
proof reviewed, обычный MERGE сохраняет этот proof и его digest. Непрерывный
доверенный ship связывается с ним по полной цепочке pp:base-sync-intent/done:
точные previous, родители каждого to, committed proof каждого from до его
intent и новый proof текущего HEAD после последнего done. Исходный ship должен
следовать за anchor исходной эпохи; он может предшествовать заключению её ревью.
Каждая база должна быть предком живого protected main. Его SHA читается из
отдельного server ref и повторно проверяется после чтения графа и timeline:
baseRefOid PR может сохранять исторический commit. Подпись Git-коммита не
является условием разрешения. После дополнительных REST-чтений графа и ancestry
повторяется полное стабильное чтение timeline; отзыв метки или новое ревью
закрывают выдачу lease. Проверки CI, владельца, exact-HEAD CAS и исходного
cleanup-intent сохраняются. Уже влитый PR завершает cleanup без требования
живой метки ship. Этот путь не включает экспериментальные настройки.
Перенос ship через один механический base-sync (#42, opt-in, по умолчанию
выключен): "base_sync_carry": true и обязательно явный required_checks.
После base-sync HEAD — двухродительское слияние to = merge(from, base).
Без нового ревью to обычный proof from его не покрывает. Решение
владельца по #42: уже выданный доверенный ship переносится, если непосредственно
перед мутацией доказаны все четыре условия:
- у
fromканоничный неизменённый committed proof сOutcome-Label: reviewed; доверенныйshipпоставлен после опубликованного заключения ревью и остаётся последним переходом метки; PR целится в ту же базовую ветку; нет более позднегоpp:review-again,hold/needs-decision/changes-requested; - родители
to— ровно[from, base],base— предок текущей вершины базовой ветки (как её видит GitHub); ни коммита, ни force-push, ни смены базы после; - дерево
toпобайтово совпадает с бесконфликтным воспроизведением слиянияbaseвfrom(git merge-tree); разрешение конфликтов не переносится; - все
required_checksзелёные на точномto.
Снимок base_sync_candidate от health-checker проекта (ivanarama/onebase#2412,
заменивший исходный ivanarama/onebase#1776) — только
описательные данные: каждое условие доказывается по GraphQL-ленте, git в рабочей
копии и живому состоянию PR, а снимок лишь сверяется. Переход доказывается
графом, а не местом коммита слияния в ленте: GitHub ставит PullRequestCommit по
дате коммита, а не push (onebase#1561). Поэтому to должен встречаться в ленте
ровно один раз, а эпоха from без этого ребра — идти до конца без посторонних
коммитов, force-push, restore, смены базы, pp:review-again и без собственного
ревью to. Доказанный перенос
next merge отдаёт lease mode: carry; complete merge проверяет всё заново до
и после merge-intent и вливает с CAS по точному sha. next review такой
цели ждёт (ПУСТО), не тратя модель; идущий CI — ожидание; не доказано хоть
одно условие — обычное интеграционное REVIEW, ничего не публикуется. Переносится
только один переход: если база уехала снова (BEHIND), нужен REVIEW.
capabilities показывает "base_sync_carry": "experimental"; сквозные тесты —
tests/test_base_sync_carry.py.
Условие 3 требует git не старше 2.38: побайтовое дерево выдаёт только
merge-tree --write-tree, а старая форма команды печатает читаемый diff без OID.
Заменить это сравнением списков файлов, git diff --stat или флагом mergeable
от GitHub нельзя — ни одно из них ничего не говорит о содержимом. Системный git
на Mac бывает старше (/usr/bin/git — Apple Git 2.37.1), поэтому бинарь задаётся
отдельно и системный не подменяется: "git_bin" в pipelinectl.json или
PP_GIT_BIN. Проверка возможности выполняется до попытки переноса, в
единственном месте, которое строит доказательство, поэтому ею закрыты все
маршруты. Если найденный git не умеет --write-tree, перенос отказывает с
названной причиной (бинарь, его версия, нужная версия), ничего не публикует и
цель уходит на обычное интеграционное REVIEW. Это отказ, а не ожидание: сам по
себе git новее не станет, а зависший перенос держал бы полосу без выхода.
В состоянии CLEAN владелец проходит те же proof/labels/CI-гейты, что и
обычный ship PR, и сливается с base_sync_owner-lease, чтобы барьер от его
собственного номера не ронял завершение. REST-only снимки (merge_executable
без списка) сохраняют полный fallback даже с opt-in.
Если для MERGE настроен более высокий приоритет и priority_one_headroom,
подписанный и привязанный к точной попытке integration-review временно
наследует приоритет активной MERGE-серии: этот REVIEW является зависимостью,
которая освобождает сам MERGE. Обычный content REVIEW запас не использует.
Временный приоритет хранится только у текущего вхождения серии, переживает
смену попытки при безопасном
budget-defer, снимается при смене маршрута, а следующий запуск повторяющейся
REVIEW-серии снова получает её настроенный приоритет.
Для подготовки типизированных REVIEW-отчётов доступна локальная команда
pp pipelinectl validate-routing-report --report report.json --head <SHA>.
Она проверяет только формат и hash; техническая передача остаётся выключенной.
Формат, общие fixtures и оставшаяся парная приёмка описаны в
docs/REVIEW_ROUTING_V1.md.
Встроенный promptpilot.project_pipeline реализует общий protocol v1. Проект
задаёт repository, доверенный аккаунт, health-команду, base branch и required
checks в pipelinectl.json. Обычный REVIEW получает ровно один кандидат и
opaque lease. При review_completion_gate: "target-v1" полный health служит
только начальным election: complete review пересчитывает draft, routing,
review-depth, HEAD и два одинаковых полных GraphQL snapshot только выданного PR,
затем сам выполняет review → claim → label → completion. Изменения чужих PR не
отменяют уже выполненный содержательный аудит. Без явного opt-in сохраняется
совместимый режим health с повторным глобальным allowlist-check.
Обычный CLEAN MERGE аналогично повторяет proof/labels/CI и использует merge с
точным SHA. Base-sync, carry, legacy re-ship, конфликт, recovery и третий круг
намеренно возвращают action=fallback: их продолжает полная проектная
процедура. Таким образом быстрый путь не ослабляет сложные гейты.
Отдельный явный запрос доверенного владельца pp:review-again, опубликованный
после полного committed proof текущего HEAD, разрешает ещё один полный аудит
этого HEAD в режиме target-v1. Подписанный lease содержит
explicit_full_current_review: точные HEAD, эпоху, неизменённый комментарий
запроса, глубину и digest предыдущего proof. Исполнитель заново доказывает эти
факты по полной ленте перед публикацией; счётчик прошлых ревью сохраняется.
Запрос позволяет пересмотреть needs-decision/changes-requested, но hold,
manual и draft закрывают выполнение. После completion тот же запрос повторно
не используется. Без такого запроса остаются обычный лимит двух автоматических
кругов и fallback; новый положительный proof и отдельное разрешение ship
по-прежнему необходимы для слияния.
Проект с обновлёнными каноническими скиллами может включить
fallback_handoff: "target-v1" в pipelinectl.json. Тогда доказанный fallback
передаёт точную цель в локальном envelope promptpilot-fallback-target-v1 с
next_already_run=true, выполненной командой, полным preflight и HMAC lease
на два часа. auto не теряет эту информацию и не просит агента повторить
next. Неполный/противоречивый handoff блокируется даже в auto; без opt-in
остаётся старый путь. Непосредственно перед первой мутацией скилл обязан
выполнить выданную gate_command (gate-fallback <stage> --lease ...). Она
проверяет подпись, срок и конфигурацию, заново запускает полный проектный health
и подтверждает тот же PR/HEAD/stage в allowlist. Интеграционный PR должен
оставаться единственным executable owner, обычный MERGE — первой исполняемой
целью без owner. Обычное REVIEW допускает перестановку чужой очереди при
сохранении точной цели в content allowlist. Pending MERGE cleanup закрывает gate
и возвращается в recovery следующим запуском.
Для cross-repo sync проект может выдать content-кандидат со stage
pre-review-validation и объектом pre_review_sync: положительные int64
intent_comment_id/done_comment_id, lowercase SHA-1 from/to/base,
lowercase SHA-256 identity_sha256 и RFC3339 intent_created_at/
done_created_at. Набор из восьми полей точный, head == to, а done должен
быть позже intent. Такой кандидат никогда не бывает integration_owner или
merge_executable и требует fallback_handoff: "target-v1": HMAC lease
связывает все поля, но не заменяет проверку происхождения. До gate полный скилл,
оставаясь read-only, обязан сначала доказать provenance стабильными GraphQL-
снимками, затем провести обычное полное ревью всего diff и тестов. Свежий gate
выполняется ровно один раз, когда аудит закончен и агент готов к первой мутации;
быстрый action=audit/complete review для этого stage запрещён.
action=validated — только read-only scheduling proof; ответ явно содержит
mutation_authorized=false. Все GraphQL, ship, CI, base-sync и CAS-проверки
остаются в полном скилле. Handoff обслуживает один PR и при отказе не переходит
к другому. До первой мутации на доказанном handoff-пути выполняются ровно два
полных health scan: election и свежий gate. С настроенным
wake_after_success следующий этап будится локально, поэтому продуктивный
fallback расходует два scan вместо прежних четырёх (4 → 2). Профиль без
локального графа сохраняет совместимый третий scan после completion.
Cleanup-проверки и GraphQL по-прежнему
расходуют GitHub API. Для ручного запуска и legacy/recovery fallback без
доказанной цели такой бюджет scan не обещается.
До необратимого merge быстрый путь публикует в PR неизменяемый
pp:merge-cleanup-intent: точный HEAD, hash review-proof и тела PR, а также
same-repository closing issues. Только после него повторяются proof/labels/CI и
отправляется compare-and-merge. Если процесс оборвался до ответа GitHub, новый
запуск по серверному MergedEvent различает открытый PR и уже выполненный merge.
Для влитого PR он продолжает action=cleanup: снимает in-work только с
закрытых связанных issues, идемпотентно завершает PLAN-handoff, снимает ship и
последним публикует pp:merge-cleanup-done. Поэтому crash после успешного merge
не вызывает второй merge и не оставляет промежуточные метки навсегда.
Новые protocol-комментарии больше не выглядят пустыми в GitHub: над скрытой
неизменяемой строкой есть короткая видимая подпись PromptPilot service marker.
Старые HTML-only markers продолжают распознаваться, поэтому их не нужно
редактировать и уже созданные review-proof не обесцениваются.
Target-v1 lease ограничен по времени и защищён HMAC локальным 256-битным ключом
из PP_PIPELINE_LEASE_KEY_FILE либо каталога PP_DATA_DIR. Подпись обнаруживает
повреждение или подмену opaque-токена в штатном cooperative execution, но не
является OS-песочницей: локальный процесс с доступом к ключу и GitHub-аккаунту
входит в доверенную границу. Поэтому подпись не заменяет live-авторизацию: все
разрешающие факты цели пересчитываются, а MERGE и интеграционные состояния
по-прежнему сохраняют глобальный gate.
Claude и Codex получают одну и ту же команду и JSON. Различаются только тонкие
файлы обнаружения навыка (.claude/skills и .agents/skills); логика CLI и
lease от модели не зависят.
Статус в Web UI и боте читается так:
| Статус | Значение |
|---|---|
green — «работает штатно» |
Инварианты соблюдены, активных ожиданий нет |
yellow — «есть ожидания» |
Выполняется восстанавливаемая транзакция или нужен ход человека; это не поломка |
red — ошибка |
Worker не работает, запуск превысил timeout, серия оборвана либо нарушен проектный инвариант |
Причина и конкретные findings выводятся рядом со статусом. Поэтому жёлтый
индикатор сам по себе не требует останавливать очередь: сначала нужно прочитать,
какое именно ожидание он показывает.
Жёлтый статус означает ожидаемый handoff или ход человека; подробная причина видна в той же карточке.
У двух цепочек могут быть одинаковые этапы: добавьте проект в первую строку
промпта (MyProject - REVIEW, OtherProject - REVIEW) и используйте такое же
уникальное значение в series_contains. Профиль влияет только на аналитику;
интервалы, effort, пауза и временное ускорение принадлежат самим сериям.
Сейчас профиль и серии связываются по названию. Отдельного мастера «Создать всю цепочку из шаблона» пока нет: этапы создаются как повторяющиеся задачи, а потом собираются профилем. Это важное отличие от Workflow-оркестратора: workflow ведёт конечную разработку «исполнитель → аудитор → исправление», а расписание обслуживает бесконечные дежурные очереди TRIAGE/PLAN/FIX/REVIEW/MERGE.
Серия без запланированного вхождения помечается «оборвана» — она сама не
продолжится. Раньше в это состояние приводило любое падение: следующее
вхождение создавалось только после успешного прогона, поэтому один rate limit
тихо убивал дежурную задачу насовсем. Теперь расписание продлевается и после
failed, а в Telegram уходит «🔁 задача упала, но расписание продолжено —
следующий запуск в …». Отменённая серия не продлевается: отмена — это решение
человека, а не сбой.
Одно вхождение в очереди (pending/rate_limited) по-прежнему можно править
в карточке. Для постоянного изменения расписания используйте экран серии.
-
Claude Code и Codex — уровень
low|medium|high|xhigh|maxзадаётся полем и работает на двух уровнях:- у провайдера — «Эффорт рассуждений» в форме провайдера (⚙ Providers)
или
pp provider add ... --effort max. Это дефолт: с ним живут все задачи провайдера, в том числе этапы конвейеров; - у задачи — селект «Effort» рядом с «Model» в веб-мастере и кнопка «Эффорт» в разделе «Дополнительно» бота. Перекрывает провайдера на один прогон и наследуется следующими вхождениями повторяющейся задачи.
Пустое значение = «по умолчанию»: PromptPilot не передаёт override и уровень выбирает сам CLI. Для Claude используется
--effort, для Codex — одноразовый-c model_reasoning_effort=...; глобальная конфигурация агента не меняется. Если настройка уже вписана руками в шаблон команды или аргументы провайдера, выигрывает написанное руками. Остальным агентам effort не передаётся. - у провайдера — «Эффорт рассуждений» в форме провайдера (⚙ Providers)
или
-
OpenCode — два пути:
-
headless: флаг
--variant high|max|minimalвcmd-шаблоне (opencode run --variant max {prompt}); -
herdr-сессия: у TUI флага запуска нет, но variant задаётся через агент-профиль в
~/.config/opencode/opencode.jsonc:{ "agent": { "max": { "mode": "primary", "variant": "max" } } }и доп. аргументы провайдера
--agent max.
-
Заводить отдельных провайдеров под каждый уровень (claude-herdr и
claude-herdr-max) больше не нужно — но если такие уже есть, они продолжают
работать: эффорт провайдера просто становится их дефолтом.
Побочно: cmd-провайдер, собранный вокруг самого claude (клон встроенного
через «Изменить»), теперь отмечается как Claude-провайдер автоматически — ему
достаются скилы, выбор модели, --resume и эффорт. Раньше такой клон выглядел
«неизвестным CLI» и молча ронял всё перечисленное.
Минимальный плагин для herdr 0.7.5+ лежит в herdr-plugin/. Установка:
herdr plugin install ivanarama/PromptPilot/herdr-plugin # из GitHub
herdr plugin link /path/to/PromptPilot/herdr-plugin # локальная копияПлагин — тонкая обёртка над pp: сам PromptPilot он не ставит и без него не
работает. Если pp на машине нет (не в PATH, не в ~/.local/bin, модуль
promptpilot не импортируется), плагин не пытается запустить что-то наугад —
он показывает уведомление herdr со ссылкой на установку и пишет то же самое в
~/.promptpilot/startup.log.
Что даёт:
- автозапуск worker'а — при старте herdr-сервера плагин поднимает
pp worker, если тот ещё не запущен (уже работающий не трогается); - постановка задачи из панели — action «PromptPilot: поставить задачу»
(палитра действий,
herdr plugin action invoke enqueue --plugin promptpilotили клавишаctrl+alt+e) открывает popup: ввёл текст — задача ушла в очередь с рабочей директорией текущей панели.
После правок манифеста нужен herdr plugin unlink promptpilot + повторный
link.
По умолчанию агент работает прямо в указанной директории — то есть в том же
рабочем дереве, где сидишь ты. Галка 🌿 свой worktree (Web UI, шаг мастера
в боте, pp add -w, поле worktree: true в API) меняет это: задача получает
собственный чекаут репозитория на ветке pp/t<id>.
Что это даёт:
- твоё рабочее дерево остаётся нетронутым — незакоммиченные правки в безопасности, ветка не переключается;
- результат — ветка, а не грязный
git status: смотришь diff, вливаешь или выбрасываешь целиком; - retry после rate-limit возвращается на ту же ветку и в тот же чекаут, а не наслаивается на полуизменённое дерево;
- две задачи по одному репозиторию могут идти параллельно (см.
PP_CONCURRENCY).
Куда попадает чекаут:
| Исполнитель | Расположение |
|---|---|
| herdr-провайдеры | herdr создаёт worktree-workspace сам (herdr worktree create) — его видно в UI herdr, там же можно закрыть или удалить. Работает и на удалённой машине |
| обычные (headless) | <родитель репозитория>/.pp-worktrees/<repo>-t<id>, либо PP_WORKTREES_ROOT/<repo>/t<id> |
Путь и ветка сохраняются в задаче и показываются в Web UI, боте и pp status <id>
— вместе с короткой сводкой «коммитов: N, незакоммиченных файлов: M».
Нюансы:
- Директория обязана быть git-репозиторием. Не репозиторий — галка в Web UI недоступна, шага в боте нет, а задача, созданная через API, честно падает с ошибкой вместо тихого запуска в общем дереве.
- Игнорируемые файлы не переезжают. Свежий чекаут — без
.env,node_modules,venv. PromptPilot копирует в него то, что перечислено вPP_WORKTREE_COPY(по умолчанию.env) — и только те файлы, которые git действительно игнорирует. Остальное — сборка, установка зависимостей — на совести самой задачи. - Чекаут не удаляется после задачи — в нём результат. Исключение: если
агент не оставил ни коммитов, ни изменений, herdr-исполнитель убирает пустой
чекаут за собой. Ветка
pp/t<id>остаётся всегда. - На удалённых машинах worktree поддерживают только herdr-провайдеры: headless-команда по ssh выполняется в домашней директории и в чекаут просто не зайдёт — такая задача падает с явным сообщением.
PP_CONCURRENCY=1 (по умолчанию) — worker берёт задачи строго по одной, как
раньше. Больше единицы — задачи идут в пуле потоков, и очередь при этом
обходит всё, что столкнулось бы с уже работающей задачей:
- две задачи с одной рабочей директорией (на одной машине) одновременно не запустятся — второй агент подождёт, пока первый закончит;
- задачи со своим worktree не блокируют никого и ничего: у каждой свой чекаут — именно в этом сочетании параллелизм и раскрывается;
- задачи в одну и ту же открытую herdr-сессию (
herdr-session) сериализуются по сессии.
Захват задачи атомарный (BEGIN IMMEDIATE + условный UPDATE), так что гонки
за одну задачу нет. Предположение остаётся прежним: worker'ов — один
процесс; второй при старте вернёт running-задачи первого в очередь
(recover_running). Нужно больше параллелизма — поднимай PP_CONCURRENCY, а
не второй worker.
Раньше любой ненулевой код возврата означал failed. Но отказ в доступе
(API Error: 401/403/5xx, Failed to authenticate) и обрыв ответа на полуслове
(Connection closed mid-response, terminal_reason=api_error, ECONNRESET,
EAI_AGAIN) — это не вина задачи. Причём обрыв почти всегда приходится на конец
прогона: работа сделана и закоммичена, не доехало только последнее слово.
Теперь такая задача возвращается в очередь со статусом rate_limited и
обычным экспоненциальным backoff'ом, а в error пишется, что именно случилось.
Считается это против max_retries, так что навсегда сломанная среда всё-таки
доводит задачу до failed, а не крутит её вечно.
Что НЕ считается срывом среды: API Error: 400, падения тестов, отсутствующие
модули, ошибки компиляции — всё это провал задачи и честный failed. Коды
сокетов (ENOTFOUND и прочие) сверяются с учётом регистра: иначе
ModuleNotFoundError читался бы как обрыв связи.
PP_MIN_FREE_MB (по умолчанию 0 — проверки нет): если свободной памяти меньше,
worker не берёт новую задачу и говорит об этом один раз, а не каждый опрос.
Слоты PP_CONCURRENCY сами по себе ничего не знают о том, потянет ли машина ещё
один прогон — а на деле она уходит в своп, и следом API начинает отказывать. На
Linux читается MemAvailable, на Windows — GlobalMemoryStatusEx; там, где
померить нельзя, очередь не останавливается.
Прогон идёт, а видно, что копает не туда — не перечитал свежий комментарий, работает по старому описанию. Приписка к задаче добавляет пару фраз, которые пойдут в следующий прогон отдельным блоком после промпта, с прямым указанием, что это написано последним и главнее всего выше.
pp note 42 "перечитай комментарий, идёшь не туда"
pp note 42 # показать
pp note 42 --clear # убратьВ Web UI — поле «Дописать решателю» в развёрнутой карточке задачи; в списке у
такой задачи стоит пометка ✎ приписка.
Живёт при задаче, а не при прогоне — и это главное:
- идущий прогон её уже не увидит — она уйдёт в следующий прогон (после rate limit или срыва среды); если нужно применить прямо сейчас, проще пересоздать задачу с уже вписанной припиской;
- одноразовая: задача дошла до вердикта — приписка снимается, чтобы не лезть во все следующие прогоны;
- но срыв по вине среды или rate limit её сохраняет — та попытка приписку так и не увидела;
- в повторяющиеся копии задачи она не попадает: следующая копия создаётся из сохранённого промпта, а не из того, что получил конкретный прогон.
PP_VERDICT=1 дописывает к промпту просьбу закончить одной строкой:
ИТОГ: ГОТОВО | УЖЕ СДЕЛАНО | НУЖЕН ЧЕЛОВЕК | НЕ СМОГ | ПУСТО
Итог парсится и хранится у задачи, показывается в Web UI, боте и pp status.
Разница практическая: код возврата говорит только «процесс завершился», а
🟡 НУЖЕН ЧЕЛОВЕК в уведомлении сразу говорит, надо ли идти смотреть.
ПУСТО — тихий итог для повторяющихся задач: «проснулся по расписанию, делать
нечего». Такая задача завершается как обычно (итог в базе, виден в списках),
но уведомление в Telegram не отправляется — иначе дежурный робот,
просыпающийся каждые два часа, превращает бота в будильник. Ошибки (failed)
шлются всегда, независимо от итога.
Только targeted fallback после выполненного next дополнительно разрешает
точную форму ИТОГ: УСТАРЕЛО (gate-fallback: ...): exact target, HEAD или её
executable-позиция изменились до первой мутации. Generic skill/workflow и
иная форма УСТАРЕЛО классифицируются как настоящий НЕ СМОГ. Первый такой
исход создаёт следующее вхождение сразу для свежего election; второй подряд
идёт по обычному интервалу. Durable-ограничитель сбрасывается любым non-stale
исходом. В дашборде валидные перевыборы считаются отдельно. Неоднозначный отказ,
проблема доступа и ошибка после начатой мутации по-прежнему должны заканчиваться
НЕ СМОГ или НУЖЕН ЧЕЛОВЕК, а не быстрым циклом перевыбора.
Парсится он всегда, даже когда мы не просили — если агент сам закончил такой
строкой, итог подхватится. Для обычного headless-ответа учитывается только
последняя непустая строка ИТОГ: …; пояснение отделяется тире или скобками.
Цитаты > ИТОГ: … и старые строки внутри отчёта не становятся итогом задачи.
Однократное уточнение пропущенного итога использует того же провайдера и
принимает только успешный ответ с явной финальной строкой. Ненулевой exit и
stream-result с ошибкой не подтверждают вердикт. Этот запрос запускается
только с принудительным rights=none; если CLI не поддерживает отключение
инструментов, уточнение пропускается без перехода к более широким правам.
Неподтверждённый результат конвейера по-прежнему останавливает попытку.
Каждый прогон помечен в своём окружении переменной PP_TASK_ID, и метку
наследует процесс агента. Поэтому живой прогон опознаётся по процессу, а не
по нашим же записям — и переживает смерть worker'а.
При старте recover_running() возвращает в очередь зависшие running-задачи, но
теперь обходит те, чей агент всё ещё работает: раньше перезапуск worker'а
выдёргивал очередь из-под живых агентов, а второй процесс worker'а на старте
отбирал задачи у первого. Поиск идёт по /proc (Linux); там, где так нельзя,
поведение прежнее.
Дашборд стоимости считает деньги по результатам задач — а herdr-задачи стоимости не дают вообще: интерактивная сессия не отдаёт stream-json. Чем больше работы уходит в herdr, тем слепее был дашборд.
pp usage (и строка «Окно 5ч» в Web UI) закрывает дыру, разбирая транскрипты,
которые Claude Code пишет в ~/.claude/projects/**/*.jsonl — в том числе для
herdr-панелей:
За последние 5 ч — оценка по прайсу API:
всего: $18.40 26.1 млн токенов сессий: 4
задачи: $12.05
прочее: $6.35 (живая переписка ест то же окно лимита)
Почему именно так:
- Считаем по сообщениям, а не по кускам. В транскрипте каждое сообщение
записано целиком и с полным
usage— суммировать можно. В потоковом журнале headless-прогона наоборот: сообщение разбито на куски с частичным usage, и суммирование занижает выход в сотню раз. Поэтому для headless-задач по-прежнему берётся готовый итог из событияresult. - Лимит общий на человека, поэтому в счёт идут и твои собственные сессии — иначе на вопрос «сколько осталось» ответить нельзя.
- Задача узнаётся по
session_id, а если его нет — по своему worktree. Обычныйworking_dirв признаки не годится: его задача делит с человеком, и живая переписка засчитывалась бы задаче (проверено — так и было). - Кэш считается отдельно: чтение ×0.1 от входа, запись ×1.25. Без этого счёт мимо на порядок — кэш-чтений на порядок больше обычного входа.
- Деньги — оценка по прайсу API, а не счёт. На подписке они не списываются; полезны как мера того, куда уходит окно.
Окно скользящее — «последние 5 часов», а не доля выбранной нормы: точку сброса API называет только событием лимита, которого в транскриптах нет.
Одно поле говорит, что агенту можно, — одинаково для любого CLI:
| Права | Смысл | Claude Code | Codex |
|---|---|---|---|
none |
без инструментов: текст на входе, текст на выходе | --tools "" |
— |
read |
читать, ничего не менять | --restricted --tools Read,Glob,Grep |
не поддерживается: локальная песочница не ограничивает внешние MCP/apps |
write |
читать и править файлы в папке задачи, не запуская команд | --restricted --tools Read,Glob,Grep,Edit,Write --permission-mode acceptEdits |
не поддерживается: workspace-write допускает команды |
full |
всё | --dangerously-skip-permissions |
--dangerously-bypass-approvals-and-sandbox |
Задаётся в веб-форме («Права»), pp add --rights read, полем rights в
POST /api/tasks и в ролях workflow (roles.executor.rights); аудитору full
запрещён. Без поля всё как раньше: решает skip_permissions. Поле переходит в
следующие вхождения повторяющейся задачи.
- Fail closed. Провайдер без нужного уровня задачу не запустит: API и CLI
откажут сразу, воркер — до старта процесса. Ограничения поддерживаются только
прямыми командами известных CLI. Wrapper, произвольная таблица
rightsиkindсами по себе не доказывают ограничения. Конфликтующие флаги прав, профилей и настроек в шаблоне отклоняются; удалите их для ограниченного запуска. Для неизвестного CLI доступен толькоfull— команда как настроена. У Claude ограниченный запуск также запрещает MCP-инструменты (mcp__*), поскольку--toolsуправляет только встроенными инструментами. - Что именно можно — решает CLI. Ограниченные уровни требуют Claude Code
с поддержкой
--restricted(2.1.248 или новее); он ограничивает файловые инструменты рабочими папками, а адаптер отдельно запрещает MCP. Для Codex уровниnone/read/writeнедоступны до отдельного проверенного адаптера: локальная command-песочница не запрещает воздействия через внешние MCP/apps. - Задачу в открытую herdr-сессию ограничить нельзя: агент в ней уже запущен со своими правами.
- Доп-запрос за потерянным
ИТОГидёт без инструментов, если провайдер это умеет.
Текст из чужих рук (письма, формы) — повод давать агенту none или read:
права ограничивают, что он может сделать, если текст попробует им управлять.
Заявки извне принимает один движок, а не отдельный скрипт на каждый случай.
Маршрут — JSON-файл в ~/.promptpilot/flows/: откуда приходят заявки (почтовый
ящик, issues GitLab), насколько им доверять (owner / team / client /
public) и какие шаги они проходят — агент с правами, решение человека,
команда, публикация, действия в GitLab, ответ письмом, финиш; с условиями,
повторами и участками «по одной заявке».
- Агент отвечает блоком
PP_RESULT_JSONпо схеме шага — не свободным текстом, в котором ищут волшебные слова. - Доверие проверяется при загрузке: в маршруте для чужих до решения человека
агент получает не больше
read, после — не большеwrite; текст заявки не попадает в командную строку и пути; в промпте он обрамлён как данные. - Решения — кнопками в Telegram, в окне «📨 Заявки» веб-интерфейса или
pp flows approve/reject; у каждой заявки — дописываемый журнал. pp flows runведёт заявки;start.ps1и трей запускают его сами, если маршруты есть.
Полное описание и примеры — docs/FLOWS.md: «Сказки Королевства» (форма сайта → триаж → стена → реализация в своей ветке → тесты → ревью → слияние), oneservice (GitLab: хранитель → исполнитель → ревью → слияние) и письма клиентов (триаж → исполнение → ответ письмом).
Задача с --dangerously-skip-permissions не спрашивает человека ни о чём —
значит, и остановить её диалогом нельзя. Останавливает PreToolUse-хук: он
видит команду до запуска и срабатывает независимо от режима разрешений.
Заблокированное — код 2 и причина в stderr, её читает модель; всё
заблокированное пишется в ~/.promptpilot/guard.log.
По умолчанию (PP_GUARD=auto) сторож включается ровно там, где больше некому
спросить: у задач с skip_permissions, и только для Claude Code провайдеров —
формат хука их. PP_GUARD=1 — всегда, PP_GUARD=0 — никогда.
Что запрещено «из коробки»: удаление корня и домашнего каталога, удаление
.git, форс-пуш и удаление веток на сервере, пуш в main/master (в том
числе git push origin HEAD из main — ветка проверяется отдельно, регулярка не
видит, что именно пушат), git worktree remove|prune (в чужих worktree идёт
работа других задач), sudo, запись на устройства, выключение машины.
Правила намеренно узкие: срабатывать они должны на катастрофе, а не на слове
sudo внутри сообщения коммита — поэтому команды опознаются по позиции в
строке, а main-fix не считается веткой main. Посмотреть и проверить:
pp guard --rules # какие правила действуют
pp guard "git push origin main" # что будет с этой командой (ничего не запускается)Дополнить или заменить — ~/.promptpilot/guard.json:
{"extend": [{"pattern": "npm\\s+publish", "reason": "Публикация — только руками"}]}{"replace": [...]} вместо extend отключает встроенные правила целиком.
Сломанный или нечитаемый файл оставляет встроенные правила в силе — сторож,
который сам себя разоружает из-за лишней запятой, хуже отсутствующего.
Ограничение: на удалённых машинах сторож не ставится — файл настроек с хуком лежит здесь, а путь к нему там ничего не значит.
- Только Claude Code. Хук — механизм Claude Code. Codex с
--dangerously-bypass-approvals-and-sandbox, agy и любые другие CLI с полными правами работают без сторожа. - Шаблоны, а не песочница. Сторож узнаёт типовые команды по тексту
(
git push --force,git -C repo push origin main,rm -rf ~…). Та же операция, записанная иначе — черезpython -c, скрипт в файле или другой инструмент, — пройдёт. Сторож ловит ошибки, а не злой умысел. - Текст из чужих рук (письма, формы, заявки) нельзя отдавать агенту с полными правами в расчёте на сторожа. Такому агенту нужны урезанные права или отдельная среда без секретов.
Машина — отдельное измерение задачи: регистрируете машины, а те же самые провайдеры работают на любой из них.
Web UI: ⚙ Providers → «🖥 Машины» → имя + user@host → «Добавить и
проверить» — PromptPilot сам определяет по ssh, какие CLI есть на машине
(login-shell PATH). После этого в форме задачи появляется поле Машина
(💻 локально / vm2 / ...), и список провайдеров фильтруется по возможностям
выбранной машины. В боте — тот же шаг «Где выполнить задачу?».
Как выполняется: ssh host bash -lc '<команда провайдера>' — исполняемый
файл ищется в PATH удалённой машины, env-блок провайдера (например,
claude-z с GLM) пробрасывается, stream-json проходит насквозь — стоимость,
session_id и rate-limit-детекция работают как локально.
Требования: ssh по ключу (BatchMode), нужные CLI на машинах (и их PATH в
~/.profile). Ограничение: detached-задачи (фоновый запуск headless-процесса)
— только локально; headless-команда выполняется в домашней директории
удалённой машины.
Низкоуровневая альтернатива — обёртка scripts/pp-ssh-run <host> <cmd...> {prompt} как cmd-шаблон провайдера (полный контроль над командой и путями).
herdr-провайдеры (включая herdr-session) работают на машинах так же, как
локально: PromptPilot вызывает herdr CLI удалённой машины по ssh, а панель с
агентом живёт там — подключиться к ней можно командой
herdr --remote <host> (она есть в уведомлениях и в мета-строке результата).
- Проба машины сама находит herdr-провайдеров: нужен
herdrв login-shell PATH машины и CLI соответствующегоkind(claude,opencode, ...). Если агент установлен не в системный PATH (например, opencode в~/.opencode/bin), допишите путь в~/.profileмашины и нажмите «Перепроверить» — иначе провайдер в списке машины не появится. - herdr server на машине поднимается автоматически (
herdr serverв фоне), если он там ещё не запущен. - Работают все режимы: blocked-ожидание с уведомлением и кнопками, keep-pane,
detached,
herdr-session(выпадашка живых сессий показывает сессии выбранной машины). - Рабочая директория задачи должна существовать на целевой машине. Если её там нет (или поле пустое), herdr молча откроет панель в домашней директории машины — задача выполнится не там, где вы ждали.
- Уже зарегистрированные машины нужно один раз «Перепроверить» — старая запись
в
machines.jsonне знает про herdr-провайдеров.
Дальше A — главная машина: на ней PromptPilot (worker, Web UI, бот) и общая очередь; B — вторая машина, на которую уезжают задачи. На B не нужны ни Python, ни PromptPilot — только herdr и сам агент.
1. На B поставить herdr и агента. Тем же способом, что и на A; обновление —
herdr update. Версии herdr на A и B лучше держать одинаковыми: подключение
herdr --remote требует совместимого протокола.
2. Проверить PATH login-шелла на B. PromptPilot ходит на машину как
ssh B bash -lc '...', то есть видит PATH из ~/.profile/~/.bash_profile, а
не из ~/.bashrc (он читается только интерактивными шеллами). С машины A:
ssh B "bash -lc 'command -v herdr; command -v claude'"Обе строки должны напечататься. Если пусто — на B в ~/.profile:
export PATH="$HOME/.local/bin:$PATH" # herdr, claude
export PATH="$HOME/.opencode/bin:$PATH" # если нужен opencode3. Настроить ssh по ключу (с A на B).
ssh-keygen -t ed25519 # если ключа ещё нет
ssh-copy-id user@B
ssh -o BatchMode=yes user@B true && echo OKBatchMode обязателен: PromptPilot никогда не отвечает на запрос пароля. Если
ключ с парольной фразой — держите ssh-agent и следите, чтобы воркер видел
SSH_AUTH_SOCK.
4. Зарегистрировать машину. Web UI: ⚙ Providers → 🖥 Машины → имя vm2
user@B→ «Добавить и проверить». Или через API:
curl -s -X POST localhost:8420/api/machines \
-H 'Content-Type: application/json' -d '{"name":"vm2","host":"user@B"}'В ответе — список найденных провайдеров; там должны быть claude-herdr и
herdr-session. Если их нет — вернитесь к шагу 2 (herdr или агент не видны
login-шеллу) и нажмите «Перепроверить» (POST /api/machines/vm2/probe).
5. Поставить задачу. В форме задачи: Машина — vm2, провайдер —
claude-herdr, рабочая директория — путь, который существует на B. В боте
это шаг «Где выполнить задачу?». Дальше PromptPilot сам поднимет herdr server на
B (если не запущен), создаст вкладку pp-t<id>-*, стартует агента и отправит
промпт; упёрся в permission-диалог — задача останется running, а в Telegram
придёт уведомление с кнопками.
6. Подключиться к живой сессии на B. С машины A — herdr --remote user@B,
на самой B — просто herdr. Эта же команда приходит в уведомлении и в
мета-строке результата. Оставленные задачами сессии называются pp-kept-<id>;
отправить в такую сессию следующий промпт можно провайдером herdr-session
(выпадашка показывает сессии выбранной машины).
herdr есть и под Windows — нативный herdr.exe из preview-канала:
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"WSL не нужен. PromptPilot определяет, на каком языке разговаривать с машиной,
сам — при добавлении/перепроверке машины и хранит это в machines.json полем
"shell": "posix" | "powershell" (в списке машин видно значком 🐧/🪟):
- posix — команда уходит как
ssh host bash -lc '<...>'; - powershell — как
ssh host powershell -EncodedCommand <base64/UTF-16LE>. Кодирование не украшательство: виндовый sshd сначала отдаёт командную строкуcmd.exe, и никакие кавычки через него живыми не проходят. В base64 нет символов, которые cmd трактует по-своему, поэтому скрипт доезжает байт в байт. Перед скриптом выставляется[Console]::OutputEncoding = UTF8— иначе JSON herdr'а и любая кириллица возвращаются кракозябрами.
Что нужно на Windows-машине:
herdr.exeи агент (claude) — в PATH пользователя, под которым ходит ssh (проверка:ssh winbox powershell -NoProfile -c "Get-Command herdr, claude").- OpenSSH Server (Параметры → Приложения → Дополнительные компоненты) с
входом по ключу; публичный ключ для админской учётки кладётся не в
~/.ssh/authorized_keys, а вC:\ProgramData\ssh\administrators_authorized_keys. - Шелл по умолчанию менять не надо — PowerShell вызывается явно; работает и
дефолтный
cmd.exe. - Порт, отличный от 22, задавайте алиасом в
~/.ssh/configна машине A — в поле «хост» можно писать имя алиаса.
Дальше всё как обычно: «Добавить и проверить» → в списке claude-herdr,
herdr-session → задача с этой машиной → подключение herdr --remote winbox.
Рабочая директория задачи — в виндовой записи (C:\work\proj).
Если на Windows-машине настроен Git Bash как shell для sshd, проба определит её
как posix — это не ошибка: такой машиной можно рулить обычным bash -lc.
Если что-то не так
| Симптом | Причина / что сделать |
|---|---|
| В списке машины нет herdr-провайдеров | ssh B "bash -lc 'command -v herdr'" пуст → PATH в ~/.profile (шаг 2), затем «Перепроверить» |
| «herdr server на машине … не запущен и не удалось его поднять» | зайдите на B и запустите herdr server руками; проверьте ssh B "bash -lc 'herdr status server --json'" |
| ssh спрашивает пароль | ключи не разложены или agent недоступен (шаг 3); на Windows-машине для админской учётки ключ кладётся в administrators_authorized_keys |
| Windows-машина определилась как posix и падает | на ней sshd отдаёт bash (Git Bash/WSL), но herdr стоит нативный — либо уберите bash из DefaultShell и перепроверьте машину, либо держите herdr там же, где bash |
| Задача отработала «не в том каталоге» | указанной рабочей директории нет на B — herdr молча ушёл в $HOME |
Задача висит в running |
агент в blocked ждёт человека: подключитесь (herdr --remote B) или подтвердите кнопкой в Telegram |
Бот (если запущен) наблюдает за всеми агентами herdr — не только за
задачами PromptPilot — на этой машине и на каждой зарегистрированной машине
с herdr-провайдерами — и присылает уведомление, когда агент заблокирован
диалогом или закончил работу незамеченным. В тексте уведомления видно, на
какой машине агент. Кнопки при блокировке:
✅ Подтвердить (Enter) · 📺 Экран · ✍️ Ответить — работают и для
удалённых панелей, так что разблокировать агента на любой машине можно прямо
с телефона. Отключение: PP_HERDR_WATCH=0.
При первом успешном опросе источника уже завершённые панели запоминаются без массовой рассылки. После этого идентичность завершения и сообщения каждому получателю сохраняются в SQLite одной транзакцией. Завершение за время выключенного бота попадёт в очередь при следующем опросе, а перезапуск не сбрасывает дедупликацию. Источники разделены по машине и адресу подключения. completion_seq: 0 — полноценный номер; state_change_seq используется только при отсутствии completion_seq.
Восстанавливается последнее видимое завершение каждой панели: отсутствующую или уже заменённую историю список herdr не предоставляет. Для интерфейсов без sequence сохраняется временная политика наблюдения; восстановление истории для них не обещается. Ошибка доставки оставляет сообщение в постоянной очереди; если Telegram принял сообщение, но подтверждение потерялось до записи результата, возможен повтор. У уведомления о завершении остаются кнопки «Экран» и «Ответить»; подтверждение Enter показывается для заблокированного агента.
Идентичность завершения опирается на непрозрачный terminal_id, а при его отсутствии — на доступный native agent_session. Переименование агента или перемещение той же сессии между панелями не создаёт нового завершения. Новый terminal_id отличает заменённый процесс, даже если номер completion_seq снова равен нулю. Для старого интерфейса без обоих идентификаторов наблюдаемое исчезновение панели начинает новую локальную жизнь; если смена процесса и сброс счётчика произошли незаметно между опросами, восстановить такую историю достоверно нельзя.
Для каждого запуска через herdr с ожиданием результата (без detached) PromptPilot добавляет собственный случайный маркер конца промпта. Ответ, успешный итог и диагноз квоты принимаются только из текста после маркера этой попытки. Общий заголовок роли, повторение того же задания и маркер старой попытки не подтверждают новый ответ.
Если обычное чтение не содержит маркера, адаптер один раз расширяет окно до 1000 отображённых строк — это предел проверенного herdr, а не 1000 логических строк отчёта. При свёрнутом промпте, потере истории или интерфейсе, который не показывает маркер, результат остаётся неподтверждённым и возвращается понятная ошибка корреляции. Весь видимый старый экран вместо ответа не используется. Проверьте совместимость адаптера; результат можно посмотреть в панели, только если она сохранилась. При этой ошибке адаптер закрывает созданную им вкладку/рабочую область после проверки владения; чужая сессия, переданная через herdr_target, остаётся открытой.
В режиме PP_CODEX_APP_SERVER=auto PromptPilot подключается к уже запущенному
Codex App Server через локальный control socket, а для зарегистрированной
удалённой машины — через её SSH-подключение. Проверено с Codex 0.169.0.
Новый daemon не запускается; модель, авторизация и разрешения открытого диалога
сохраняются. PP_CODEX_APP_SERVER=0 возвращает прежний способ работы.
Диалог связывается с панелью по native session ID либо по однозначному совпадению каталога и названия загруженного диалога. Если связи нет, версия Codex не подходит или daemon недоступен, остаётся herdr. После неопределённого результата отправки запрос не дублируется через другой адаптер.
В Telegram видны текст вопроса и варианты ответа; доступны кнопки выбора и свободный ответ. Повторные и устаревшие ответы проверяются. Для сообщений, переданных через App Server, завершение и полный ответ привязаны к конкретному turn ID и сохраняются вместе с очередью доставки в SQLite. «Проверю…» и изменение терминального статуса не подтверждают выполнение. Старые кнопки экрана, подтверждения разрешений, очередь, расписания, повторы и выдача созданных файлов остаются доступны. Вывод окна можно получить файлом; для терминального пути доступно до 1000 отображённых строк.
npm install -g @nothumanwork/cursor-agents-sdk
winget install BurntSushi.ripgrep.MSVCДобавь в .env:
CURSOR_API_KEY=crsr_your_key_here
Ключ: cursor.com/settings → API Keys. Первый запуск занимает ~60 секунд.
Скилы — команды (/skill-name) из ~/.claude/commands/, ~/.claude/skills/ и плагинов Claude Code. Доступны для всех провайдеров с supports_skills=True.
При выборе Claude-провайдера под полем промпта появляется кнопка ⚡ Skills. Нажми — откроется список скилов с описаниями. Выбор подставляет /skill-name в промпт.
Кнопка ⚡ Скилы в главном меню или команда /skills. Поддерживает глобальные скилы и скилы конкретного проекта (📁 Скилы проекта...).
GET /api/skills — все доступные скилы
GET /api/skills?provider=claude — только если провайдер поддерживает скилы
GET /api/skills?provider=claude&workdir=/path — + локальные скилы проекта
Минималистичный dark-theme UI на http://127.0.0.1:8420:
- Выбор провайдера и модели (дропдаун модели появляется автоматически для Claude Code провайдеров)
- Добавление задач с приоритетом и расписанием (Ctrl+Enter для отправки)
- Чекбокс
--dangerously-skip-permissions - ⚡ Skills — раскрывает список доступных скилов
- Фильтры по статусу, раскрытие деталей задачи
- Отмена (в т.ч. running-задач — процесс будет убит) и удаление задач
- Recur, per-task таймаут, галочка «🖥 оставить сессию открытой» (herdr)
- Кнопка ⏸ Pause воркера и панель стоимости по провайдерам
- ⚙ Providers — управление провайдерами: список с пометками (встроенный/кастомный, «не установлен», «скрыт»), добавление (команда-шаблон или herdr-сессия: агент, доп. аргументы, модели, env), «Изменить», «Скрыть/Показать», «Удалить» / «Сбросить к встроенному»
- В выпадашке провайдеров у формы задачи — только установленные и не скрытые
- Автообновление каждые 5 секунд
Доступ с другой машины — через SSH-туннель:
ssh -L 8420:127.0.0.1:8420 user@server # затем открой http://localhost:8420По умолчанию API открыт только на 127.0.0.1 и без авторизации. Если сервер
нужно открыть наружу (PP_HOST=0.0.0.0), задайте токен:
PP_API_TOKEN=длинный-случайный-токен
Браузер покажет стандартное окно логина (имя любое, пароль — токен); скрипты
ходят с заголовком Authorization: Bearer <токен> или curl -u x:<токен>.
Без токена запросы получают 401.
Без токена сервер защищается от атак через браузер самого пользователя:
- отвечает только на запросы с
Hostвидаlocalhost,*.localhostили IP-адрес. Чужое имя (так выглядит DNS-rebinding, когда страница злоумышленника подменяет адрес своего домена на127.0.0.1) получает 403; - изменяющий запрос из браузера (
POST/PATCH/DELETE) принимается, только если егоOriginсовпадает с этим сервером целиком: схема, имя и порт. Страница на другом порту той же машины получает 403. Скрипты иcurlзаголовокOriginне шлют, для них ничего не меняется.
Если UI открывается по имени — через reverse-proxy или туннель:
- имя — в
PP_ALLOWED_HOSTS(через запятую), это проверкаHost.*отключает её, но проверкаOriginостаётся; - полный публичный адрес страницы — в
PP_ALLOWED_ORIGINS(через запятую), напримерhttps://pp.example.com. Он сравнивается точно, по схеме, имени и порту. Имя изPP_ALLOWED_HOSTSсамо по себе изменяющие запросы не разрешает: страница наhttp://pp.example.com:3000получит 403. Если прокси стоит на той же машине и передаётHostиX-Forwarded-Proto, запрос и так приходит с публичной схемой и именем, и этот список не нужен.
С PP_API_TOKEN защиту обеспечивает токен, и эти проверки не применяются.
GET /api/tasks — список задач (?status=pending&limit=50)
POST /api/tasks — создать задачу (все поля TaskCreate, вкл. keep_pane, worktree)
GET /api/tasks/{id} — детали задачи
PATCH /api/tasks/{id} — отменить (для running — worker убьёт процесс) / сменить приоритет
DELETE /api/tasks/{id} — удалить
POST /api/tasks/{id}/reset — сбросить зависшую задачу в pending
GET /api/stats — статистика по статусам
GET /api/stats/costs — стоимость: today / week / total / by_provider
GET /api/stats/usage — расход за окно лимита по всем сессиям (?hours=5)
POST /api/tasks/{id}/note — дописать решателю ({"text": "..."}; пустой текст убирает)
GET /api/worker/status — paused + state/heartbeat_at/age_seconds/pid
POST /api/worker/pause|resume — пауза/возобновление выбора новых задач; уже взятые продолжаются
GET /api/version — проверка обновлений (кэш 24 ч)
GET /api/providers — провайдеры (description, supports_skills, models, available, hidden, executor)
GET /api/providers/manage — полная информация для настроек (env-секреты маскированы)
POST /api/providers — создать/изменить провайдера
DELETE /api/providers/{name} — удалить кастомного провайдера
POST /api/providers/{name}/hide|unhide — скрыть/показать в списках
GET /api/skills — скилы (?provider=claude&workdir=/path)
GET /api/projects — проекты из PP_PROJECTS_ROOT ({name, path, git})
POST /api/workflows — создать draft workflow
POST /api/workflows/validate-setup — read-only preflight мастера создания
GET /api/workflows — список workflow (?status=draft&limit=50)
GET /api/workflows/{id} — детали workflow
PATCH /api/workflows/{id} — обновить draft-метаданные с expected_version
POST /api/workflows/{id}/start — создать первый новый раунд
POST /api/workflows/{id}/dispatch — поставить executor/reviewer task в очередь
POST /api/workflows/{id}/gate — записать результат ручного W1-гейта
POST /api/workflows/{id}/review — записать структурированный verdict аудитора
POST /api/workflows/{id}/human-input — решение человека/возобновление
GET /api/workflows/{id}/external — задание этапа вне PromptPilot
POST /api/workflows/{id}/external-request — выдать задание (ручной режим)
POST /api/workflows/{id}/external-result — сдать результат внешнего этапа
POST /api/workflows/{id}/cancel — отменить workflow и связанные задачи
POST /api/workflows/{id}/sync — восстановить проекцию из состояния tasks
POST /api/workflows/{id}/history/import — импортировать старые раунды и факты
GET /api/workflows/{id}/rounds — раунды
GET /api/workflows/{id}/rounds/{round_id}/runs — запуски ролей
GET /api/workflows/{id}/events — история (?after_seq=0&limit=200); tail=true — последние события в хронологическом порядке
GET /api/workflows/{id}/findings — текущие findings
GET /api/workflows/{id}/artifacts — зарегистрированные артефакты
GET /api/flows — маршруты заявок, счётчики, ошибки загрузки
GET /api/flows/items — заявки (?flow=&status=&limit=)
GET /api/flows/items/{id} — заявка + журнал
POST /api/flows/items/{id}/decision — решение: {"decision": "approve|reject", "note": "…"}
POST /api/flows/items/{id}/retry|skip|cancel — заявке нужен человек
POST /api/flows/{name}/items — завести заявку вручную
| Переменная | По умолчанию | Описание |
|---|---|---|
PP_DATA_DIR |
~/.promptpilot |
Директория для БД |
PP_POLL_INTERVAL |
5 |
Интервал опроса очереди (сек) |
PP_TASK_TIMEOUT |
0 (без лимита) |
Глобальный таймаут задачи, сек; у задачи переопределяется индивидуально |
PP_BASE_DELAY |
60 |
Начальная задержка retry (сек) |
PP_MAX_DELAY |
3600 |
Максимальная задержка retry (сек) |
PP_MAX_RETRIES |
5 |
Макс. кол-во retry по умолчанию |
PP_CONCURRENCY |
1 |
Сколько задач worker выполняет одновременно |
PP_PIPELINE_SNAPSHOT_INTERVAL |
300 |
Интервал фоновых снимков активных pipeline-профилей, сек; 0 отключает |
PP_MIN_FREE_MB |
0 (без проверки) |
Не начинать новую задачу, если свободно меньше памяти |
PP_VERDICT |
0 |
Просить агента заканчивать строкой ИТОГ: ... (дописывается к промпту) |
PP_GUARD |
auto |
Сторож запретов: auto — при skip_permissions, 1 — всегда, 0 — выключен |
PP_WORKTREE_PREFIX |
pp/ |
Префикс ветки задачи с worktree (pp/t42) |
PP_WORKTREES_ROOT |
— | Куда класть чекауты; пусто = .pp-worktrees рядом с репозиторием |
PP_WORKTREE_COPY |
.env |
Игнорируемые git'ом файлы, которые копировать в новый чекаут (через запятую; пусто — не копировать) |
PP_DEFAULT_CLI |
claude |
Провайдер по умолчанию |
PP_HOST |
127.0.0.1 |
Хост веб-сервера |
PP_PORT |
8420 |
Порт веб-сервера |
PP_API_TOKEN |
— | Токен авторизации Web UI/API (пусто = без авторизации) |
PP_ALLOWED_HOSTS |
— | Имена хостов, на которые сервер без токена отвечает кроме localhost и IP-адресов (reverse-proxy, туннель); * — не проверять Host |
PP_ALLOWED_ORIGINS |
— | Полные адреса страниц (https://pp.example.com), с которых без токена принимаются изменяющие запросы кроме самого сервера; сравниваются точно: схема, имя и порт |
PP_TG_TOKEN |
— | Токен Telegram бота |
PP_TG_ALLOWED_PHONES |
— | Разрешённые номера (через запятую) |
PP_TASK_PASSWORD |
— | Пароль для создания задач через бота |
PP_PROJECTS_ROOT |
— | Корневая папка проектов для быстрого выбора директории |
PP_CLAUDE_EXE |
из PATH | Путь к claude / claude.exe |
PP_GH_EXE |
стандартный путь/PATH | Путь к GitHub CLI; его каталог добавляется в окружение локальных агентов |
PP_GO_EXE |
стандартный путь/PATH | Путь к Go; его каталог добавляется в окружение локальных агентов |
PP_HERDR_BIN |
herdr |
Путь к herdr CLI |
PP_HERDR_KEEP_PANE |
0 |
Форсировать «оставить сессию» независимо от галочки задачи |
PP_HERDR_READ_LINES |
300 |
Сколько строк транскрипта читать как результат |
PP_HERDR_START_TIMEOUT_MS |
60000 |
Таймаут готовности агента при старте сессии |
PP_HERDR_WORKTREE_TIMEOUT_SECONDS |
300 |
Таймаут herdr-операций create/open/remove для worktree |
PP_HERDR_WATCH |
1 |
herdr→Telegram мост (уведомления о blocked/done) |
PP_HERDR_WATCH_INTERVAL |
10 |
Интервал опроса агентов herdr (сек) |
PP_HERDR_RENOTIFY_COOLDOWN |
600 |
Антидубль blocked-уведомлений: повтор с тем же экраном в течение этого срока молчит (сек) |
| Статус | Описание |
|---|---|
pending |
В очереди |
running |
Выполняется |
completed |
Успешно завершена |
failed |
Завершена с ошибкой |
rate_limited |
Ожидает retry: rate limit или срыв по вине среды (см. ниже) |
cancelled |
Отменена |
Карта ядра и надстроек, точки подключения конвейера, процессы и границы доверия — docs/ARCHITECTURE.md.
promptpilot/
├── config.py — настройки, провайдеры, скилы, build_cmd
├── models.py — Pydantic-модели
├── db.py — SQLite (очередь, CRUD, планирование)
├── worker.py — воркер (subprocess → любой AI CLI)
├── cli.py — CLI (Click)
├── api.py — REST API (FastAPI)
├── bot.py — Telegram бот (python-telegram-bot)
├── flows.py — маршруты заявок: шаги, доверие, журнал (docs/FLOWS.md)
├── flow_connectors.py — входы и выходы маршрутов: почтовый ящик, публичная лента
├── tg_auth.py — авторизация по номеру телефона
└── static/
└── index.html — веб-интерфейс
start.ps1 — запустить все сервисы
stop.ps1 — остановить все сервисы
build.ps1 — собрать dist\pp.exe
pp.spec — конфиг PyInstaller
Воркер и сервер — два отдельных процесса, работающих с одной SQLite БД. По
умолчанию воркер выполняет задачи по одной; PP_CONCURRENCY>1 включает
параллельное выполнение (см. раздел «Параллельные задачи»).
По умолчанию утверждённый план неизменяем. Для отдельного workflow можно
явно включить config.planning.allow_editing_approved_plan: true. В окне
плана появится «Перепланировать хвост». Завершённые этапы и текущий этап
заморожены; менять можно только следующие pending-этапы, которые никогда
не запускались и не имеют раундов или сохранённого результата.
POST /api/workflows/{id}/plan/amend принимает полный список stages,
expected_version показанного пользователю workflow и reason (от трёх
непробельных символов). Полная спецификация замороженного префикса должна
совпадать с сохранённой. Действуют обычные проверки уникальности кодов,
зависимостей на предыдущие этапы, финального integration и лимита этапов.
Конфликт версии или небезопасное состояние возвращает 409 без изменения
истории. Событие plan.amended сохраняет причину и полные старый и новый хвост.
Будущие этапы с сохранённым кодом сохраняют также ID и дату создания. Если
подключена память этапов, удалить этап с привязанными заметками можно только
после явного удаления или переназначения этих заметок; перепланирование их
молча не теряет.
Необязательный аддон tools/addons/plan_pilot предоставляет
approved_stage_amend(...): читает workflow и этапы локального API, проверяет
переданный gate_canon, затем отправляет изменение с исходной CAS-версией.
Он работает только с loopback HTTP(S), не следует редиректам и не включается
автоматически. Встроенный пример канона относится только к указанной в нём
миссии; для своей миссии передайте собственный словарь. Канон проверяет
наличие строк проверок и не заменяет проверку их смысла или независимое ревью.
MIT — см. LICENSE.



