# 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 без ошибок.