orchestrator/docs/work-items/ORCH-040/02-trz.md

# 02 — ТЗ: agent-файлы под uid хоста (не root)

Work Item: **ORCH-040**

## 1. Суть требования
Артефакты конвейера (worktree + docs) должны создаваться на хосте под
`uid:gid = 1000:1000` (slin), а не `root:root`. При этом сохраняется работа
claude-auth, git, ssh-деплоя и docker.sock.

## 2. Задействованные модули и файлы

| Файл | Роль в задаче |
|------|----------------|
| `docker-compose.yml` | runtime-режим контейнера (prod `orchestrator` + `orchestrator-staging`). Основная точка изменения. |
| `Dockerfile` | возможные правки под непривилегированный запуск (safe.directory уже есть; при необходимости — создание пользователя/прав). |
| `src/agents/launcher.py` | `HOME=/home/slin` хардкод (env Popen ~стр.326 и git_env ~стр.513); путь `CLAUDE_BIN` (стр.187). Проверить совместимость при смене uid; править ТОЛЬКО при необходимости. |
| `docs/operations/INFRA.md` | блок «Тома (volumes)» (SSH-маунт `/root/.ssh`), карта рантайма — обновить. |
| `CHANGELOG.md` | запись об изменении. |
| `docs/work-items/ORCH-040/06-adr/` | ADR с выбором варианта + обоснованием (создаёт архитектор). |

## 3. Варианты решения (вход для ADR — выбор и обоснование за архитектором)

> Анализ фиксирует варианты как требование «выбрать и обосновать в ADR».
> Рекомендация разведки — Вариант 1.

1. **Вариант 1 (рекомендован): `user: "1000:1000"` в docker-compose.**
   Все файлы сразу `slin:slin`, git на хосте без chown. Обязательные довески:
   - сохранить/проверить `group_add: ["999"]` (docker.sock) — **уже присутствует**;
   - обеспечить доступ uid 1000 к claude creds (`/home/slin/.claude/.credentials.json`):
     `chown 1000:1000` на хосте ИЛИ права на чтение для 1000 (задокументировать);
   - поправить SSH-маунт: `/home/slin/.orchestrator-ssh` → домашний каталог uid 1000
     (`/home/slin/.ssh`), а не `/root/.ssh`; согласовать с `HOME` в launcher;
   - проверить запуск `claude.exe` + `git` + `ssh` под uid 1000.

2. **Вариант 2: subprocess агента под непривилегированным uid внутри контейнера**
   (`Popen preexec_fn setuid` / `gosu`). Точечно, но сложнее; контейнер остаётся root.

3. **Вариант 3 (fallback, костыль): chown-хук нормализации прав после стадии**
   (`chown -R 1000:1000` worktree/доки). Лечит симптом, не корень. Применять, только
   если В1 неустранимо рвёт creds/sock.

## 4. Требуемые изменения (при выбранном Варианте 1)

### 4.1 docker-compose.yml (оба сервиса: `orchestrator`, `orchestrator-staging`)
- Добавить `user: "1000:1000"`.
- Сохранить `group_add: ["999"]` (НЕ удалять).
- Изменить SSH-маунт: target `/root/.ssh` → каталог `.ssh` пользователя 1000,
  синхронно с `HOME`, который форсит launcher (`/home/slin`). То есть привести к
  единому HOME: маунт `/home/slin/.orchestrator-ssh` → `/home/slin/.ssh:ro`.
- Маунт `/home/slin/.claude` и `.claude.json` — оставить; проверить доступ uid 1000.

### 4.2 Доступ к claude creds
- Обеспечить, что `/home/slin/.claude/.credentials.json` читается uid 1000
  (на хосте — операция Owner; в ТЗ зафиксировать команду и проверку).

### 4.3 src/agents/launcher.py
- Проверить, что `HOME=/home/slin` остаётся валиден под uid 1000 (домашний каталог
  существует и доступен). Менять ТОЛЬКО при доказанной необходимости.
- Не менять CLAUDE_BIN, если запуск под 1000 подтверждён.

### 4.4 Dockerfile
- Менять при необходимости (например, гарантировать существование `/home/slin` и
  права). `git config --system --add safe.directory '*'` уже есть — оставить.

## 5. Изменения API
Нет.

## 6. Изменения схемы БД
Нет.

## 7. Новые QG checks
Нет. Существующий staging-гейт (`check_staging_status`, ORCH-35) — обязательная
страховка перед прод-деплоем self (без изменений).

## 8. Артефакты pipeline, которые должны быть созданы/обновлены
- `06-adr/ADR-NNN-<slug>.md` — выбор варианта + обоснование (мины 1–3, SSH, HOME).
- `docs/operations/INFRA.md` — обновить блок volumes (SSH target) и, при изменении
  режима, упоминание uid рантайма.
- `CHANGELOG.md` — запись `fix:`/`refactor:` по Conventional Commits.
- `12-review.md`, `13-test-report.md`, `15-staging-log.md` — по ходу конвейера.

## 9. Порядок безопасного внедрения (требование)
1. Живая разведка прав creds/sock/ssh ДО кода.
2. Применить и проверить на **staging (8501)** end-to-end.
3. Прод-рестарт контейнера под новым uid — только в окно тишины (нет активных задач).
4. Регресс на хосте: новые tracked-артефакты `1000:1000`, `git pull` под slin без ошибок.

## 10. Зависимости и host-prerequisites (действия на хосте, вне кода)

Эти пункты — предусловия для Варианта 1; их выполняет Owner на хосте mva154 (в гит
не коммитятся, но фиксируются в ADR/INFRA как обязательная процедура). Без них
переход контейнера на uid 1000 ломает конвейер (МИНА 2 — блокер).

| # | Предусловие | Команда / проверка | Зачем |
|---|-------------|--------------------|-------|
| P-1 | Доступ uid 1000 к claude creds | `chown -R 1000:1000 /home/slin/.claude` (вкл. `.credentials.json`); проверка `sudo -u '#1000' test -r /home/slin/.claude/.credentials.json` | МИНА 2: без доступа preflight ORCH-044 завернёт весь конвейер |
| P-2 | SSH-ключи в HOME нового uid и читаемы | ключи в `/home/slin/.orchestrator-ssh` читаемы uid 1000; маунт ведёт в `/home/slin/.ssh` (см. §4.1) | деплой по ssh (DEPLOY_SSH_*) |
| P-3 | Подтверждение uid:gid рантайма | `id slin` → `uid=1000 gid=1000`; `/repos` и `/app/data` уже `1000:1000` (подтверждено разведкой) | целевые файлы создаются под slin |
| P-4 | Окно тишины для рестарта self | `GET /status` → нет активных задач перед рестартом прод-контейнера | self-hosting: общий инстанс с enduro-trails |

> **Открытый выбор для ADR (не решается анализом):** способ обеспечения P-1 —
> `chown` creds (рекомендация разведки) vs. ослабление read-прав vs. отказ от
> Варианта 1 в пользу Варианта 3 (chown-хук). Анализ фиксирует P-1 как
> обязательное предусловие при любом из вариантов 1/2; для Варианта 3 — неактуально.

## 11. Подтверждённые факты текущего рантайма (anchor для Dev)
Сверено с веткой `feature/ORCH-040-root-git` на 06.06:
- `docker-compose.yml`: оба сервиса имеют `group_add: ["999"]` (МИНА 1 — НЕ удалять);
  SSH-маунт обоих = `/home/slin/.orchestrator-ssh:/root/.ssh:ro` (требует правки target);
  claude-маунты = `/home/slin/.claude` и `/home/slin/.claude.json:ro`.
- `src/agents/launcher.py`: `HOME="/home/slin"` форсится в env Popen (стр. 326) и в
  git_env (стр. 513); `CLAUDE_BIN="/opt/claude-code/bin/claude.exe"` (стр. 187).