# 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).