architect(ET): auto-commit from architect run_id=158

docs/work-items/ORCH-044/07-infra-requirements.md

@@ -0,0 +1,46 @@
+# 07 — Требования к инфраструктуре
+
+**Work Item:** ORCH-044
+**Основано на:** ADR-001, ТЗ `02-trz.md`
+
+## Топология
+**Без изменений.** Новых контейнеров, портов, сервисов, очередей не вводится. Прод
+`orchestrator` (8500) и staging `orchestrator-staging` (8501) остаются как есть
+(`docs/operations/INFRA.md`).
+
+## Учётные данные claude (P1)
+- Launcher спавнит claude с `HOME=/home/slin` (`src/agents/launcher.py`). Preflight ДОЛЖЕН
+  резолвить путь к credentials от **этого же** HOME, а не от окружения процесса оркестратора.
+- Ожидаемое расположение файла OAuth-токена: **`/home/slin/.claude/.credentials.json`**
+  (структура: `claudeAiOauth.expiresAt` — epoch **ms**).
+- Файл — секрет; в гит НЕ коммитится (правило агентов №8). На хосте монтируется в контейнер
+  как раньше; задача его расположение **не меняет**, только начинает читать.
+- ⚠️ **Проверить на staging:** реальный путь файла внутри контейнера совпадает с
+  резолвленным preflight. Несовпадение ⇒ ложный auth-fail и блок очереди (R-1).
+
+## Новые переменные окружения (env-карта)
+Документировать в `docs/operations/INFRA.md` и docstring `src/config.py`:
+
+| Env | Default | Назначение |
+|-----|---------|------------|
+| `ORCH_PREFLIGHT_CHECK_AUTH` | `true` | Включение token-free auth-проверки в preflight. Аварийный тумблер: `false` возвращает старое поведение (только bin + `--version`). |
+| `ORCH_CLAUDE_CREDENTIALS_PATH` | `""` | Явный путь к `.credentials.json`. Пусто ⇒ `<AGENT_HOME>/.claude/.credentials.json`. |
+| `ORCH_AUTH_EXPIRY_SKEW_SECONDS` | `0` | Запас на рассинхрон часов при сравнении `expiresAt`. |
+
+`--effort` env (`ORCH_AGENT_EFFORT_*`) — **вне scope**; прод-хотфикс `ORCH_AGENT_EFFORT_*=""`
+в `.env` **оставить как есть** (ORCH-50).
+
+## Эксплуатационные процедуры
+- **Аварийный откат auth-гейта без редеплоя кода:** выставить `ORCH_PREFLIGHT_CHECK_AUTH=false`
+  в `.env` и перезапустить воркер обычной процедурой выката (НЕ в рамках этой задачи).
+- **Диагностика:** auth-причина видна в `GET /queue` (`preflight_reason`) и в warning-логе
+  `orchestrator.preflight`.
+- **Re-login:** при детекте auth-маркера в логе launcher сбрасывает preflight-кеш, поэтому
+  после ручного `claude /login` следующий тик воркера (≤ `preflight_cache_ttl`) подхватит
+  валидную сессию автоматически.
+
+## Self-hosting / деплой (AC-17)
+- Изменения только в слое preflight/launch — **не** требуют рестарта/падения прод-контейнера
+  в рамках задачи.
+- Выкатка self-доработки ORCH — **через staging-гейт (8501)** перед прод-деплоем
+  (CLAUDE.md, `docs/operations/INFRA.md`, ADR-0003).