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