# Автоматический цикл агентов

## Однократная настройка

Скопировать `runner.example.json` в `runner.local.json` и заменить `argv` на команду своего **агентного CLI с доступом к файлам и инструментам**. Обычный текстовый вызов модели без execution harness не сможет выполнять задачи.

Команда запускается без shell из project root; полный новый prompt поступает в stdin UTF-8. Дополнительно доступны placeholders `{root}`, `{task}`, `{role}`, `{agent}`, `{action}`, `{prompt_file}` в аргументах и environment variables `LUMA_PROJECT_ROOT`, `LUMA_TASK_ID`, `LUMA_ROLE`, `LUMA_AGENT_ID`, `LUMA_ACTION`, `LUMA_PROMPT_FILE`.

Пример формы настройки (имя/флаги заменить реальными для вашего harness):

```json
{"argv": ["your-agent-cli", "--prompt-file", "{prompt_file}"], "git_commits": true, "max_sessions": 1000, "timeout_seconds": 1800, "max_prompt_chars": 80000}
```

`commands_by_role` позволяет указать другую argv-array для отдельных ролей, например crypto/security. Не хранить secrets в аргументах/JSON; использовать безопасное окружение harness. Конкретная модель и команда не выдумываются автоматически.

Harness обязан запускать новую conversation/session для каждого процесса, исполнять file/tool commands, соблюдать project sandbox и завершаться после submit/review/escalate. Не использовать флаги resume/thread reuse и auto-next-task внутри harness.

Автоматические commits включены по умолчанию. Перед первым реальным запуском foundation должна быть сохранена начальным commit в Git checkout с активной веткой, настроенной identity и чистым index/working tree. Каждый agent transition заканчивается отдельным осмысленным commit перед следующим процессом. Executor и reviewer заранее пишут сообщения; Git выполняет runner. Правила, примеры и восстановление — `docs/GIT_WORKFLOW.md`.

## Запуск

```sh
python3 scripts/runner.py --dry-run
python3 scripts/runner.py --config runner.local.json
# Ограничить согласованным этапом:
python3 scripts/runner.py --config runner.local.json --stage S00
```

Dry run не назначает tasks, не пишет state и работает без настроенной модели. Он показывает первую задачу и размер prompt. После настройки один обычный запуск последовательно выполняет очередь: executor → новый reviewer → следующий executor. Каждый subprocess имеет новый agent id и читает master prompt заново.

## Blocker flow

1. Текущий агент записывает handoff/issue, `escalate`, заканчивает работу.
   Runner сохраняет checkpoint незавершённой работы и причины; это не acceptance. Только после commit запускается resolver.
2. Оригинал blocked, resolver todo с ограниченным scope и исходными prerequisites. Resolver не зависит от blocked оригинала.
3. Runner приоритетно запускает нового resolver-агента.
4. Другой новый процесс проверяет resolver.
5. Только done resolver автоматически снимает блокировку оригинала. Оригинал возвращается в todo либо review, прежний reporter id retired.
6. Новый executor/reviewer читает исходную карточку и handoff; потом продолжается обычная очередь.

Nested blocker проходит тот же процесс. Глубина выше 3 или 6 remediation на одну root task автоматически переводит очередную remediation в ожидание внешнего решения. Так не возникает бесконечного создания одинаковых задач/процессов.

## Когда требуется пользователь

Credentials/оплата/неопределённое продуктовое решение/действие внешнего администратора, достигнутый blocker limit, нарушение scope или ненастроенный CLI. `requires_user_input` не означает автоматическое done; задача ждёт конкретного input.

После внешнего исправления:

```sh
python3 scripts/tasks.py release-external <RESOLVER-ID> --agent coordinator-new --role orchestrator \
  --reason 'Конкретное условие выполнено; ссылка на безопасное подтверждение'
python3 scripts/runner.py --config runner.local.json
```

Release только делает resolver готовым к проверяемой реализации, не завершает его и не снимает блокировку оригинала.

## Остановка и безопасность исполнения

`max_sessions` ограничивает число новых процессов за invocation; exhaustion возвращает summary, не done. Runner наблюдает terminal transition: после escalate/submit/approve/reject прекращает старый process group на POSIX, даже если harness пытается продолжать. Новый процесс запускается только после завершения старого. Timeout также прекращает process group, затем создаётся remediation. На других ОС harness должен гарантировать остановку дочерних процессов. До завершения старого процесса новый не запускается.

`.runner.lock` запрещает два coordinator процесса в одном checkout. Не удалять lock живого runner; после сбоя проверить PID runner и возможного child agent, остановить только подтверждённо зависшие собственные процессы и восстановить запуск. Автоматического stealing чужой активной задачи нет.

Изменения исходников сравниваются со scope. Workflow metadata/generated files являются служебным исключением; проверка не заменяет OS sandbox и не доказывает отсутствие записи за пределами project root. Запускать harness в отдельном checkout, без параллельных ручных правок и с write sandbox только проекта. При scope violation runner сохраняет incident/remediation и останавливается, не откатывая потенциально чужие изменения автоматически.

Журналы: `state/runs/<agent-id>/run.json`, `prompt.md`, `output.log`; хранить без secrets. Каждый report содержит task/role, exit/status, timeout/violation и результат, не включает private command environment.

## Гарантии инструмента

Dependency/role guards, retired reporter, recovery journal definitions+state, fresh subprocess IDs, bounded prompts, separate reviewer, automatic unblocking only after done и stop на внешнем blocker. Истинность evidence/качество модели/OS sandbox обеспечиваются реальным harness и review, а не названием роли.

В поставляемой основе автоматизация проверяется fake tool-capable harness в isolated temporary project, включая реальные commits в временных Git repositories, независимое review и ошибки hooks/messages. Реальные 275 продуктовых задач не запускаются при обновлении основы.