Merge pull request 'feat: ORCH-057-bug-follow-up-orch-040-normali' (#113) from feature/ORCH-057-bug-follow-up-orch-040-normali into main

.env.example

@@ -394,6 +394,29 @@ ORCH_COVERAGE_EPSILON=0.5
 ORCH_COVERAGE_TOOL_FAIL_CLOSED=false
 ORCH_COVERAGE_RUN_TIMEOUT_S=900
 
+# ORCH-057 (follow-up ORCH-040): legacy root-owned ownership detect + actionable
+# worktree error. After the uid migration (user: "1000:1000") legacy root:root files
+# in /repos broke worktree creation under uid 1000 with a raw "Permission denied".
+# Three additive, kill-switch-reversible layers: an actionable RuntimeError in
+# ensure_worktree, a cheap never-raise detect leaf (src/fs_normalize.py) with a
+# startup WARNING/Telegram + GET /queue fs_ownership block, and an opt-in chown ONLY
+# when privileged (under uid 1000 a no-op; the real fix is the operator procedure in
+# docs/operations/INFRA.md «Миграция uid»). No STAGE_TRANSITIONS / QG_CHECKS / schema
+# change.
+#   ENABLED        -> kill-switch; false -> all code inert, behaviour 1:1 as before
+#                     ORCH-057 (the actionable error too).
+#   REPOS          -> CSV of repos the layer is REAL for; empty -> self-hosting only.
+#   TARGET_UID     -> target uid fallback when os.getuid() is unavailable.
+#   NORMALIZE_AUTO -> detect-only (false) | attempt chown when privileged (true).
+#   SCAN_ROOTS     -> CSV override of the scan roots (empty -> default roots).
+#   SCAN_CACHE_TTL_S -> TTL of the detect cache (mirrors ORCH_PREFLIGHT_CACHE_TTL).
+ORCH_FS_NORMALIZE_ENABLED=true
+ORCH_FS_NORMALIZE_REPOS=
+ORCH_FS_TARGET_UID=1000
+ORCH_FS_NORMALIZE_AUTO=false
+ORCH_FS_SCAN_ROOTS=
+ORCH_FS_SCAN_CACHE_TTL_S=300
+
 # ORCH-099 (FND/F1a): operator off-switch for the read-only GET /metrics endpoint
 # (raw-signal snapshot for the F1b sidecar). Default true -> available out of the
 # box. false -> /metrics returns a minimal parsable body {"schema_version":1,

.task-dev.md

@@ -1,4 +1,4 @@
-Work item: ORCH-099
+Work item: ORCH-057
 Repo: orchestrator
-Branch: feature/ORCH-099-fnd-f1a-metrics-agent-liveness
+Branch: feature/ORCH-057-bug-follow-up-orch-040-normali
 Stage: development

CHANGELOG.md

@@ -3,6 +3,12 @@
 Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу.
 
 ## [Unreleased]
+- **Детект legacy root-owned файлов + внятная ошибка worktree при миграции на uid 1000** (ORCH-057, follow-up ORCH-040, `feat`): закрыт недоделанный AC ORCH-040 — legacy `root:root` файлы в `/repos` (после перевода контейнеров на `user: "1000:1000"`) ломали создание worktree под uid 1000 (`ensure_worktree` → сырой `fatal: … Permission denied`, агент не стартовал, диагноза не было). Три аддитивных, обратимых kill-switch'ем слоя; **`STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / схема БД — байт-в-байт прежние**. ADR: `docs/work-items/ORCH-057/06-adr/ADR-001-legacy-ownership-normalization.md`, сквозной `docs/architecture/adr/adr-0031-legacy-ownership-normalization.md`.
+  - **D1 — actionable-ошибка `ensure_worktree`:** класс «нет прав» (`Permission denied` / `could not create leading directories` / `insufficient permission for adding an object` / `PermissionError`/`EACCES`/`EPERM`) оборачивается в `RuntimeError` с **причиной** (legacy root-файлы в `/repos/_wt`/`.git` после миграции uid), **лечащей командой** (`chown -R <uid>:<uid> …`) и ссылкой на `INFRA.md` — вместо сырого git stderr. Ошибки, **не** связанные с правами, сохраняют прежний контракт (меняется только формулировка, не факт сбоя; чистый классификатор `fs_normalize.classify_worktree_error`). Под выключенным kill-switch контракт ошибки 1:1 как до ORCH-057.
+  - **D2 — детект-леаф `src/fs_normalize.py`** (never-raise, паттерн `serial_gate`/`coverage_gate`): `scan_ownership(roots, target_uid=os.getuid())` обходит `/repos/_wt`, `<repo>/.git/{objects,worktrees}`, `data/runs` с ранним выходом при первом `st_uid != target_uid`, TTL-кэшем (`fs_scan_cache_ttl_s`, по образцу `preflight._cache`) и `applies(repo)` first (пустой CSV → self-hosting only → enduro-trails не сканируется). Опц. `normalize()` chown'ит **только** при `geteuid()==0` (под uid 1000 — no-op + честный лог «нужна операторская процедура», НЕ ошибка).
+  - **D3 — наблюдаемость, БЕЗ блокировки claim:** best-effort вызов `scan_ownership()` на старте `main.lifespan` (рядом с lease-reclaim/log-rotation, never-fatal) → WARNING + Telegram при mismatch; read-only блок `fs_ownership` в `GET /queue`; опц. ручной `POST /fs-normalize/check`. Claim **не** блокируется (preflight repo-слеп → регресс enduro; queue_worker — дорогой FS-обход в hot-path + молчаливое зависание); внятный ранний отказ даёт D1 в точке launch.
+  - **Процедура (D5):** обязательная операторская нормализация под root на хосте — в `docs/operations/INFRA.md` (раздел «Миграция uid: обязательная нормализация legacy root-файлов», все корни: `_wt`, оба `.git`, `data/runs`); фактический `chown` остаётся ручным шагом (контейнер без root его сделать не может) — задача гарантирует **внятность** отказа, а не его отсутствие.
+  - **Флаги** (`src/config.py`, аддитивно): `ORCH_FS_NORMALIZE_ENABLED` (kill-switch), `ORCH_FS_NORMALIZE_REPOS` (CSV; пусто → self-hosting only), `ORCH_FS_TARGET_UID` (1000), `ORCH_FS_NORMALIZE_AUTO` (детект-only), `ORCH_FS_SCAN_ROOTS`, `ORCH_FS_SCAN_CACHE_TTL_S`. Тесты: `tests/test_fs_normalize.py`, `tests/test_git_worktree_perm.py`, `tests/test_fs_normalize_startup.py`, `tests/test_api_queue.py` (TC-01…TC-12).
 - **Лёгкий read-only `GET /metrics` — машинное «сырьё» о самом орке для sidecar F1b** (ORCH-099, FND/F1a, `feat`): добавлен версионируемый JSON-эндпоинт `GET /metrics`, отдающий снимок внутреннего состояния орка для будущего отдельного sidecar-наблюдателя F1b (`watchdog/`) — наблюдатель отделён от наблюдаемого (BRD §1): орк отдаёт ТОЛЬКО факты, которые знает лишь он сам; пороги/алерты/история/Telegram — на стороне F1b. **Аддитивно, строго read-only, never-raise:** `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи / схема БД — **не тронуты**; `/health`/`/status`/`/queue` — байт-в-байт прежние. ADR: `docs/work-items/ORCH-099/06-adr/ADR-001-metrics-endpoint.md`, сквозной `docs/architecture/adr/adr-0030-metrics-endpoint.md`.
   - **Leaf-сборщик + тонкий эндпоинт (D1):** новый `src/metrics.py` (`build_metrics() -> dict`, never-raise по разделам, паттерн `serial_gate.snapshot()`) собирает конверт по-раздельно (каждый раздел в своём `try/except` → безопасный дефолт `null`/`[]`/`{}` + WARNING); эндпоинт `@app.get("/metrics")` в `src/main.py` — тонкая обёртка, возвращает результат как есть (стиль `GET /queue`). Тестируемость без ASGI: разделы проверяются прямым вызовом `build_metrics()`.
   - **Конверт + контракт `schema_version` (D2):** `schema_version` (стартует с `1`), `generated_at` (UTC ISO-8601, часовой домен орка → дельты CPU иммунны к skew орк↔sidecar, TR-3), `clk_tck` (`os.sysconf("SC_CLK_TCK")`, базис тиков). Политика: аддитивные изменения **НЕ бампят** версию (sidecar обязан игнорировать незнакомые ключи) — бамп только при ломающем (rename/remove/retype).

docs/architecture/adr/README.md

@@ -36,11 +36,12 @@ Per-work-item решения живут в `docs/work-items/<id>/06-adr/ADR-NNN-
 | adr-0028 | Terminal-window-aware гард deploy-фазовых статусов Plane | proposed | 2026-06-09 | ORCH-094 |
 | adr-0029 | Гейт покрытия тестами — edge sub-gate + ratchet-базовая линия | proposed | 2026-06-10 | ORCH-027 |
 | adr-0030 | Лёгкий read-only `/metrics` — сырьё о самом орке для sidecar (F1b) | proposed | 2026-06-10 | ORCH-099 |
+| adr-0031 | Нормализация legacy root-owned файлов при миграции uid — детект-leaf + actionable worktree-ошибка | proposed | 2026-06-10 | ORCH-057 |
 
 > ⚠️ Историческая коллизия: номер `0007` занят двумя файлами —
 > `adr-0007-reconciler.md` (ORCH-053) и `adr-0007-executable-self-deploy.md`
 > (ORCH-036). Оба accepted; для новых сквозных ADR использовать следующий
-> свободный номер (текущий максимум — `0030`).
+> свободный номер (текущий максимум — `0031`).
 > adr-0014 **amends** adr-0013 (меняет критерий merge-verify на «SHA-в-main»).
 > adr-0016 **amends** adr-0013/0014 (гарантирует открытый код-PR перед merge_pr, ORCH-082).
 > adr-0020 реализует машинный слой к adr-0019 (ORCH-52b→52c).

docs/architecture/adr/adr-0031-legacy-ownership-normalization.md

@@ -0,0 +1,92 @@
+---
+work_item: ORCH-057
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# adr-0031: Нормализация legacy root-owned файлов при миграции uid — детект-leaf + actionable worktree-ошибка
+
+- **Статус:** proposed
+- **Дата:** 2026-06-10
+- **Задача:** ORCH-057 (follow-up ORCH-040)
+- **Детальный ADR:** `docs/work-items/ORCH-057/06-adr/ADR-001-legacy-ownership-normalization.md`
+
+## Контекст
+ORCH-040 перевёл контейнеры на `user: "1000:1000"`, изменив только `docker-compose.yml`. Владельца
+уже существующих `root:root` файлов в bind-mount `/repos` это не меняет. Под uid 1000
+`src/git_worktree.py::ensure_worktree` (`os.makedirs` стр. 78 / `git worktree add` стр. 81/85) не может
+создать worktree рядом с root-owned `/repos/_wt/` → `fatal: could not create leading directories …
+Permission denied`, который сейчас пробрасывается сырым. Конвейер приходит сюда из
+`launcher._spawn`/`_materialize_deferred_branch` (ORCH-088) — **агент не стартует** (launch-time
+инфра-сбой, не код задачи). Инцидент 06.06 на проде (первый запуск ORCH-043); workaround Стрима
+(`chown -R 1000:1000`) наложен вручную. ADR-040 описал нормализацию абстрактно («вне объёма кода») и
+не дал процедуры → баг воспроизводим на чистой среде / новом репо / после исторического запуска под
+root. Контейнер бежит **без root** → код физически не может `chown` чужие файлы; ему доступны лишь
+детект + диагностика.
+
+## Решение
+Три аддитивных, обратимых kill-switch'ем слоя — паттерн условного leaf-гейта (`coverage_gate`/
+`serial_gate`) + best-effort startup-хук (`main.lifespan`, как lease-reclaim). `STAGE_TRANSITIONS` /
+`QG_CHECKS` / `check_*` / machine-verdict-ключи (`verdict:`/`result:`/`deploy_status:`/
+`staging_status:`/`security_status:`/`coverage_status:`) / схема БД — **байт-в-байт прежние**.
+
+- **Actionable worktree-ошибка (D1):** `ensure_worktree` классифицирует класс «нет прав» (маркеры
+  `Permission denied`/`could not create leading directories`/`insufficient permission`/`EACCES`/
+  `EPERM`) и поднимает `RuntimeError` с причиной (legacy root-файлы после миграции uid) + лечащей
+  командой + ссылкой на INFRA.md. Не-прав-ошибки сохраняют прежний текст/смысл (никакой подмены).
+  Меняется лишь **формулировка**, не факт сбоя.
+- **Детект-leaf `src/fs_normalize.py` (D2):** чистый, never-raise, TTL-кэш (паттерн `preflight`).
+  `scan_ownership(roots, target_uid)` обходит `/repos/_wt`, `<repo>/.git/objects`,
+  `<repo>/.git/worktrees`, `data/runs`; ранний выход при первом `st_uid != target_uid`
+  (`target_uid=os.getuid()` по умолчанию). `applies(repo)` (kill-switch + scope; пусто →
+  `is_self_hosting_repo`) проверяется ПЕРВЫМ → дорогой обход только при applies. Идемпотентно;
+  ошибка обхода → WARNING + консервативный `mismatch=False`.
+- **Интеграция = наблюдаемость, без блокировки claim (D3):** best-effort `scan_ownership()` на старте
+  `main.lifespan` → WARNING + Telegram при mismatch. Claim НЕ гейтится: внятный ранний отказ даёт D1
+  в точке launch (знает repo, агент ещё не тратил токены). Блокирующий preflight-гейт отвергнут —
+  preflight не знает repo, заблокировал бы и enduro-trails на общем `/repos`.
+- **Опц. `normalize()` (D4):** chown только при `CAP_CHOWN`/root (под uid 1000 — no-op + лог),
+  флаг `fs_normalize_auto` (дефолт `False`). Init-контейнер/root-entrypoint отвергнут: реинтродукция
+  root-контекста (анти-цель ORCH-040) + правка compose = self-deploy/групповой риск. Реальную
+  нормализацию несёт операторская процедура.
+- **Процедура (D5):** `INFRA.md` получает раздел «Миграция uid: обязательная нормализация legacy
+  root-файлов» (точные команды по всем корням) как обязательный шаг миграции; forward-breadcrumb из
+  ADR-040.
+- **Флаги:** `fs_normalize_enabled` (kill-switch, дефолт `True`), `fs_normalize_repos` (CSV, пусто →
+  self-hosting only), `fs_target_uid` (1000), `fs_normalize_auto` (`False`), `fs_scan_roots`,
+  `fs_scan_cache_ttl_s` (300). Наблюдаемость — блок `fs_ownership` в `GET /queue`; опц. `POST
+  /fs-normalize/check`.
+
+## Альтернативы
+- **Init-контейнер/root-entrypoint** — реинтродукция root (анти-цель ORCH-040), self-deploy compose,
+  групповой риск ради разовой операции. Отвергнуто; носитель нормализации — операторская процедура.
+- **Блокирующий claim-гейт (preflight)** — preflight не знает repo → регресс enduro на общем `/repos`.
+  Отвергнуто.
+- **Блокирующий claim-гейт (queue_worker/claim)** — дорогой FS-обход в hot-path + «молчаливое
+  зависание» вместо диагноза D1. Отвергнуто.
+- **Авто-chown из app по умолчанию** — под uid 1000 невозможен; ложное ожидание самолечения.
+  Отвергнуто (оставлен opt-in `fs_normalize_auto`).
+- **Hard-fail старта при mismatch** — нарушает never-raise, стопорит сервис всех проектов. Отвергнуто.
+
+## Последствия
+- Класс «сырой git-fatal на launch после миграции uid» закрыт внятным диагнозом (D1) + проактивным
+  startup-сигналом (D3); пробел процедуры ADR-040 закрыт (INFRA.md).
+- Нулевая регрессия enduro-trails (scope first); инварианты конвейера/схема БД — байт-в-байт.
+- Никакого root-контекста/рестарта прода/касания `main`/force-push/прод-образа (NFR-1).
+- Плата: фактический `chown` остаётся ручным операторским шагом (но теперь внятным, с инструкцией);
+  +1 best-effort startup-хук и leaf-модуль; `fs_normalize_auto=True` под root реинтродуцирует
+  chown-контекст (дефолт `False`, не для прод-self).
+- Аддитивно/обратимо: **не** `arch:major-change` (нет новой стадии/QG/таблицы/смены топологии) — leaf
+  + startup-хук + docs.
+- **Откат:** `fs_normalize_enabled=False` → полный no-op (мгновенный обратимый kill-switch).
+
+## Связи
+adr-0005 (контейнер под host-uid — порождающее решение ORCH-040, чей пробел закрываем),
+adr-0029/adr-0012 (coverage/security-гейт — паттерн условного leaf `applies`/scope/never-raise/
+fail-open), adr-0017 (serial-gate — leaf never-raise + отложенный срез ветки `_materialize_deferred_
+branch`, чья точка падает в `ensure_worktree`), adr-0011 (job-reaper — образец best-effort
+startup-хука в `lifespan`), adr-0024 (disk-watchdog — образец «только читать/уведомлять, не трогать
+хост/прод»).

docs/operations/INFRA.md

@@ -47,8 +47,35 @@ ADR `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md` и гл
 - **P-3:** `id slin` → `1000:1000`; `/repos`, `/app/data` уже `1000:1000`.
 - **P-4:** прод-рестарт self — только в окно тишины (`GET /status` без активных задач):
   общий инстанс с enduro-trails.
-- Разовый разгребающий `chown -R 1000:1000 /home/slin/repos/orchestrator` для старых
-  `root:root` файлов из истории (вне объёма кода).
+- **P-5 (блокер миграции uid, ORCH-057):** нормализация **всех** legacy `root:root` файлов в `/repos`
+  — см. подраздел «Миграция uid: обязательная нормализация legacy root-файлов» ниже. Без неё первый
+  job падает на launch при создании worktree (инцидент 06.06, ORCH-043).
+
+### Миграция uid: обязательная нормализация legacy root-файлов (ORCH-057)
+ORCH-040 сменил `user:` контейнера, но **не** владельца уже существующих файлов в bind-mount `/repos`,
+созданных прежним root-контейнером. Под uid 1000 `src/git_worktree.py::ensure_worktree` не может
+создать worktree рядом с `root:root` каталогом `/repos/_wt/` → `fatal: could not create leading
+directories … Permission denied` (агент даже не стартует). С ORCH-057 эта ошибка распознаётся и
+выдаётся **внятно** (с лечащей командой) + детектится на старте сервиса (WARNING/Telegram, блок
+`fs_ownership` в `GET /queue`), но **фактический `chown` обязан выполнить оператор под root на хосте**
+(контейнер бежит без root и chown'ить чужие файлы не может).
+
+**Обязательный разовый шаг при миграции uid / на новой среде (под root на mva154, ПЕРЕД стартом app):**
+```bash
+# 1) worktree-корень (все ветки всех проектов режутся здесь)
+sudo chown -R 1000:1000 /home/slin/repos/_wt
+# 2) .git обоих репо (objects / worktrees-административные записи)
+sudo chown -R 1000:1000 /home/slin/repos/orchestrator/.git \
+                        /home/slin/repos/enduro-trails/.git
+# 3) корень orchestrator целиком (включая data/runs/*.log — 37 root-логов в инциденте)
+sudo chown -R 1000:1000 /home/slin/repos/orchestrator
+# Проверка (пусто = ок):
+find /home/slin/repos/_wt ! -uid 1000 -print -quit
+```
+Процедура **идемпотентна** (повтор на корректной среде — no-op) и входит в **чеклист деплоя/миграции
+self**. Область охвата: `_wt`, оба `.git` (`objects`+`worktrees`), `data/runs`. См.
+`docs/work-items/ORCH-057/06-adr/ADR-001-legacy-ownership-normalization.md` и сквозной
+`docs/architecture/adr/adr-0031-legacy-ownership-normalization.md`.
 
 ### Тома (volumes)
 - `./data` → `/app/data` (БД; у staging — `./data/staging`)

docs/work-items/ORCH-057/00-business-request.md

@@ -0,0 +1,7 @@
+# Business Request: BUG/follow-up ORCH-040: normalize legacy root-owned файлы при миграции на uid 1000 (one-time + защита)
+
+Work Item ID: ORCH-057
+
+## Description
+
+TBD

docs/work-items/ORCH-057/01-brd.md

@@ -0,0 +1,140 @@
+---
+work_item: ORCH-057
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 01 — BRD (бизнес-требования): ORCH-057 — нормализация legacy root-owned файлов при миграции на uid 1000 (one-time + защита)
+
+Work Item: **ORCH-057** · Repo: **orchestrator** · Стадия: analysis
+
+## 1. Бизнес-контекст и проблема
+
+ORCH-040 перевёл оба контейнера (`orchestrator` 8500, `orchestrator-staging` 8501) с root
+на `user: "1000:1000"` (slin). Изменён был **только** `docker-compose.yml`. Однако bind-mount
+`/home/slin/repos → /repos` уже содержал файлы и каталоги, созданные **прежним root-контейнером**
+(`root:root`). Смена `user:` владельца существующих файлов НЕ меняет.
+
+**Реальный инцидент (прод, 06.06, поймали на первом запуске ORCH-043).** Первый job под uid 1000
+упал на стадии **launch** (НЕ на коде задачи):
+
+```
+fatal: could not create leading directories of
+'/repos/_wt/orchestrator/feature_ORCH-043-.../.git': Permission denied
+```
+
+Причина: `/repos/_wt/` и старые worktree-папки = `root:root` → uid 1000 не может создать рядом
+новый каталог worktree. Установлено фактически: ошибка возникает в `src/git_worktree.py::ensure_worktree`
+(вызов `git worktree add`), куда конвейер приходит из `src/agents/launcher.py::_spawn` (стр. 500)
+и `_materialize_deferred_branch` (ORCH-088). Агент даже не стартует — падает создание worktree.
+
+**Ручной workaround (применён Стрим, прод снова рабочий, ОДНОРАЗОВО):**
+```
+sudo chown -R 1000:1000 /home/slin/repos/_wt
+sudo chown -R 1000:1000 /home/slin/repos/orchestrator/.git /home/slin/repos/enduro-trails/.git
+sudo chown -R 1000:1000 /home/slin/repos/orchestrator   # +data/runs/*.log (37 root-логов)
+```
+
+ADR-001 ORCH-040 упоминал «массовый chown старых root-файлов» лишь абстрактно («вне объёма кода»,
+«разовая операция Owner») и НЕ дал конкретной процедуры чистки legacy worktree — поэтому deployer
+её не выполнил, и баг проявился в проде. Прод сейчас рабочий (ручной фикс наложен), но проблема
+**воспроизведётся** на чистой среде, новом репо или после любого исторического запуска под root,
+если её не закрыть кодом + процедурой.
+
+**Это follow-up / закрытие недоделанного AC ORCH-040** (legacy-файлы), а не новая фича.
+
+## 2. Объём (scope)
+
+### В объёме
+- **Защита launcher (код):** при `Permission denied` на создании worktree выдавать **внятную,
+  диагностируемую** ошибку «legacy root-файлы в `/repos/_wt` — требуется нормализация прав»
+  с указанием команды, а НЕ сырой `git fatal`.
+- **Раннее обнаружение (код):** детектирование наличия файлов с `uid != <target_uid>` в
+  `ORCH_REPOS_DIR` (включая `_wt`, `.git/objects`, `.git/worktrees`, `data/runs`) при старте
+  контейнера / перед претензией на job — чтобы конвейер падал **внятно и заранее**, а не сырым
+  git-фаталом на launch.
+- **Процедура нормализации (документация):** в `docs/operations/INFRA.md` (и собственный ADR
+  ORCH-057) — обязательная одноразовая процедура нормализации legacy root-файлов при миграции uid,
+  с точными командами и областью охвата (`_wt`, `.git`, `data/runs`).
+- **Опционально (по решению архитектора):** механизм one-time нормализации при буте/деплое —
+  init-контейнер/хук под root, либо blocking-entrypoint-проверка.
+
+### Вне объёма
+- Изменение логики конвейера, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схемы БД.
+- Пересмотр самого решения ORCH-040 (uid 1000) — оно принято и остаётся.
+- Перенос инстанса на другой хост / другой uid (отдельная задача при миграции хоста).
+- Массовая ретроактивная переработка ADR-001 ORCH-040 (его история не переписывается;
+  допускается forward-breadcrumb-ссылка на ORCH-057 — решает архитектор).
+- Выбор конкретного варианта реализации one-time нормализации (a/b/в) — зона архитектора (06-adr).
+
+## 3. Заинтересованные стороны
+
+- **Заказчик / Owner** — Слава (homenet542), инициатор; принимает результат.
+- **Эксплуатация** — Стрим (применял ручной workaround); потребитель процедуры в INFRA.md.
+- **Затронутые проекты** — `orchestrator` (self-hosting) и `enduro-trails` (общий инстанс, общая
+  очередь, общий bind-mount `/repos`): нормализация прав `/repos` касается обоих репо.
+
+## 4. Бизнес-требования (BR)
+
+- **BR-1** — После миграции контейнера на новый uid конвейер запускается **без ручного `chown`**:
+  либо авто-нормализация прав, либо **явная блокирующая ошибка с инструкцией** (никогда не сырой
+  `git fatal` на launch).
+- **BR-2** — На свежей среде / новом репо / после исторического запуска под root проблема
+  **не воспроизводится** (детект + понятная диагностика срабатывают до падения агента).
+- **BR-3** — `INFRA.md` и ADR содержат **конкретную процедуру** нормализации legacy root-файлов
+  (точные команды, область: `_wt`, `.git/objects`, `.git/worktrees`, `data/runs`), помеченную как
+  обязательный шаг миграции uid.
+- **BR-4** — Несоответствие владельца наблюдаемо: оператор узнаёт о проблеме из лога/уведомления/
+  read-only статуса, а не по падению задачи на launch.
+- **BR-5** — Защита `ensure_worktree` распознаёт класс ошибки «нет прав на создание worktree» и
+  сообщает причину + лечащую команду (опц. — авто-самолечение, если процесс имеет права).
+
+## 5. Нефункциональные требования (NFR)
+
+- **NFR-1 (self-hosting безопасность)** — Решение **никогда** не перезапускает/не роняет
+  прод-контейнер `orchestrator`, не трогает `main`/force-push/прод-образ. Контейнер бежит под
+  uid 1000 (без root) → код **не может** делать `chown` без root; код ограничивается
+  детектом + внятной диагностикой/блокировкой, а фактический `chown` — операторская/init-процедура.
+- **NFR-2 (общий инстанс)** — Нулевая регрессия для `enduro-trails`: feature под kill-switch и
+  scope-флагом (по образцу `serial_gate`/`coverage_gate`); выключено → поведение 1:1 как до ORCH-057.
+- **NFR-3 (never-raise / fail-safe)** — Детект-леаф никогда не бросает наружу неожиданное исключение
+  и не блокирует старт сервиса по своей ошибке; деградирует в WARNING.
+- **NFR-4 (идемпотентность)** — Повторный запуск детекта/нормализации на уже корректной среде —
+  no-op без побочных эффектов.
+- **NFR-5 (обратимость)** — Поведение откатывается выключением kill-switch без миграций/правки схемы.
+- **NFR-6 (наблюдаемость)** — Вердикт (есть/нет mismatch, сколько файлов, какие корни) логируется
+  структурно; при проблеме — Telegram с кликабельным номером задачи (если применимо) + read-only
+  отражение в `GET /queue`.
+
+## 6. Допущения и ограничения
+
+- Целевой uid:gid рантайма = `1000:1000` (slin), подтверждён ORCH-040 (P-3); на хосте `/repos`,
+  `/app/data` штатно `1000:1000`.
+- Контейнер бежит под numeric uid 1000 без записи в `/etc/passwd` базового образа; в образе создан
+  реальный user `slin` (uid 1000) для `getpwuid()` (ORCH-058, Dockerfile). Под uid 1000 `chown`
+  чужих (root) файлов **невозможен** без CAP_CHOWN/root.
+- `git config --system --add safe.directory '*'` уже в образе — git доверяет bind-mount.
+- Корни проверки: `ORCH_REPOS_DIR` (`/repos`), включая `_wt`, `<repo>/.git/objects`,
+  `<repo>/.git/worktrees`, и `data/runs` (37 root-логов в инциденте).
+- `start_pipeline` (ORCH-088) отложил срез ветки на момент claim analyst-job → детект уместен
+  и на старте сервиса, и перед claim'ом (точку выбирает архитектор).
+
+## 7. Критерии успеха
+
+После миграции uid (или на чистой среде) первый же job проходит launch без ручного `chown`, либо —
+если права не нормализованы — конвейер выдаёт **понятную блокирующую диагностику** с командой
+исправления вместо сырого `git fatal`. INFRA.md/ADR содержат воспроизводимую процедуру.
+Для `enduro-trails` — нулевая регрессия. Детальные PASS/FAIL — в `03-acceptance-criteria.md`.
+
+## 8. Риски
+
+- Контейнер без root не может `chown` → авто-самолечение возможно только частично/при наличии прав;
+  основной гарант — детект+диагностика+процедура (детали — `10-tech-risks.md`, архитектор).
+- Рекурсивный обход больших `.git/objects` / `_wt` может быть дорог → нужен дешёвый/семплированный
+  детект и кэш (как preflight TTL).
+- Ложно-блокирующая ошибка может застопорить и enduro-trails (общий `/repos`) → строгий scope/fail-safe.
+- Правка `docker-compose.yml`/entrypoint (init-контейнер) = деплой self → групповой риск (NFR-1),
+  обязательная страховка staging.

docs/work-items/ORCH-057/02-trz.md

@@ -0,0 +1,117 @@
+---
+work_item: ORCH-057
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 02 — ТЗ (TRZ): ORCH-057 — нормализация legacy root-owned файлов при миграции на uid 1000
+
+Work Item: **ORCH-057** · Repo: **orchestrator** · Стадия: analysis
+
+> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
+> Архитектурное обоснование/выбор варианта one-time нормализации (init-контейнер vs blocking-entrypoint
+> vs ансибл) — задача архитектора (`06-adr/`). Здесь — требования, контракты и ограничения.
+
+## 1. Сводка изменения
+
+Закрыть недоделанный AC ORCH-040 по legacy-файлам. Три слоя:
+1. **Защита launcher** — `ensure_worktree` распознаёт `Permission denied`/git-fatal на создании
+   worktree и поднимает **внятную** ошибку с диагнозом «legacy root-файлы в `/repos/_wt` — нужна
+   нормализация прав» + лечащая команда (опц. авто-самолечение при наличии прав).
+2. **Ранний детект** — новый чистый леаф находит файлы с `uid != target_uid` в `ORCH_REPOS_DIR`
+   (`_wt`, `.git/objects`, `.git/worktrees`, `data/runs`); вызывается на старте сервиса и/или перед
+   claim'ом job; never-raise, config-gated, с наблюдаемостью.
+3. **Процедура** — `INFRA.md` + ADR ORCH-057: точные команды разовой нормализации как обязательный
+   шаг миграции uid. Опционально — one-time нормализация под root через init-механизм (решает архитектор).
+
+Инвариант: `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / схема БД —
+**байт-в-байт прежние**. Изменение аддитивно и обратимо kill-switch'ем.
+
+## 2. Задействованные модули / пути
+
+| Путь | Действие |
+|------|----------|
+| `src/git_worktree.py` (`ensure_worktree`, `remove_worktree`) | изменить — классификация `Permission denied`/git-fatal на `git worktree add` / `os.makedirs` → внятный actionable `RuntimeError` (опц. self-heal при правах) |
+| `src/fs_normalize.py` | **создать** — чистый леаф (never-raise): `scan_ownership(roots, target_uid) -> результат`; опц. `normalize(...)` (chown только при наличии прав); хелпер `applies(repo)` + кэш (TTL, как preflight) |
+| `src/config.py` | изменить — добавить флаги (см. §7); без правки существующих значений |
+| `src/main.py` (`lifespan`) | изменить — добавить startup-вызов детекта (best-effort, never-fatal по образцу L-2/lease-reclaim), лог + Telegram при mismatch; read-only блок в `GET /queue` |
+| `src/preflight.py` **или** `src/queue_worker.py` | изменить (на выбор архитектора) — опц. гейт claim'а job при обнаруженном mismatch, чтобы падать внятно ДО launch (по образцу preflight-гейта) |
+| `docker-compose.yml` / `Dockerfile` / `scripts/*entrypoint*` | **кандидат** (решает архитектор) — one-time root-нормализация (init-контейнер/хук) ПЕРЕД стартом app; если выбрано — деплой self, обязательная staging-страховка |
+| `docs/operations/INFRA.md` | изменить — раздел «Миграция uid: обязательная нормализация legacy root-файлов» (команды + область) |
+| `docs/work-items/ORCH-057/06-adr/ADR-001-*.md` | создать (architect) — решение + процедура; опц. forward-breadcrumb из ADR-001 ORCH-040 (без переписывания истории) |
+| `CHANGELOG.md` | изменить — запись о ORCH-057 |
+| `tests/test_*` | создать — см. `04-test-plan.yaml` |
+
+## 3. Функциональные требования
+
+### FR-1 — Внятная ошибка `ensure_worktree` (BR-1, BR-5)
+При неуспехе `git worktree add` / `os.makedirs(os.path.dirname(wt))` по причине отказа доступа
+(`Permission denied`, `could not create leading directories`, `insufficient permission for adding an
+object`) `ensure_worktree` поднимает `RuntimeError` с сообщением, которое: (а) называет корневую
+причину (legacy root-owned файлы в `/repos/_wt` или `.git` после миграции uid ORCH-040); (б) указывает
+лечащую команду (`chown -R <uid>:<gid> …`) или ссылку на процедуру INFRA.md; (в) НЕ является сырым
+git stderr. Прочие (нет-прав-несвязанные) ошибки сохраняют текущий контракт (никакой подмены смысла).
+
+### FR-2 — Детект несоответствия владельца (BR-2, BR-4)
+Леаф `fs_normalize.scan_ownership` обходит корни (`/repos/_wt`, `<repo>/.git/objects`,
+`<repo>/.git/worktrees`, `data/runs`) и возвращает: есть ли файлы с `uid != target_uid`, их число
+(или флаг «≥1»), список затронутых корней. Обход дешёвый/ограниченный (ранний выход при первом
+mismatch для быстрого вердикта; полный подсчёт — опционально/семплировано). Результат кэшируется по
+TTL (по образцу `preflight._cache`). `target_uid` = `os.getuid()` или конфиг (дефолт 1000).
+
+### FR-3 — Реакция на детект (BR-1, BR-4)
+- **Startup (main.lifespan):** вызвать детект best-effort; при mismatch — структурный WARNING +
+  Telegram (если включён) с числом/корнями и лечащей командой. Никогда не падать на старте по
+  ошибке детекта (NFR-3).
+- **Опц. гейт claim'а:** при обнаруженном mismatch и `target_uid` без прав на chown — не претендовать
+  на job (или претендовать и сразу честно фейлить с FR-1-сообщением), чтобы исход был внятным до launch.
+  Конкретную точку (preflight vs queue_worker) выбирает архитектор; требование — «внятно и заранее».
+
+### FR-4 — Опциональная авто-нормализация (BR-1)
+`fs_normalize.normalize` выполняет `chown -R target_uid:target_gid` по корням **только если процесс
+имеет на это право** (CAP_CHOWN/root). Под uid 1000 без прав — no-op + честный лог «нужна операторская
+процедура» (НЕ ошибка). Включается отдельным флагом (`*_AUTO`), по умолчанию — выкл (детект-only).
+Если архитектор выбирает init-контейнер под root — это и есть носитель FR-4 на буте.
+
+### FR-5 — Документированная процедура (BR-3)
+`INFRA.md` получает раздел с точными командами разовой нормализации (`_wt`, оба `.git`, `data/runs`),
+помеченный как **обязательный** шаг миграции uid и часть чеклиста деплоя self. ADR ORCH-057 фиксирует
+решение и ссылается на процедуру; ADR-001 ORCH-040 опц. получает forward-ссылку.
+
+## 4. Изменения API
+
+Нет новых обязательных эндпоинтов. **Опционально** (наблюдаемость, решает архитектор):
+- расширить `GET /queue` read-only блоком `fs_ownership` (`{enabled, target_uid, mismatch, roots, checked_at}`);
+- ручной триггер `POST /fs-normalize/check` (форс-пересчёт детекта) — по образцу `POST /serial-gate/unfreeze`.
+
+## 5. Изменения схемы БД
+
+Нет. Состояние детекта — в памяти (TTL-кэш), как `preflight`. Таблицы/миграции/индексы не вводятся.
+
+## 6. Требования к новым/изменённым QG checks
+
+Нет. Это **не** stage-гейт и **не** под-гейт ребра. `QG_CHECKS` / `check_*` / `STAGE_TRANSITIONS` /
+machine-verdict-ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/
+`coverage_status:`) — не трогаются. (В описании баг-репорта «deploy-гейт ORCH-040» — это деплой-хук/
+процедура, а не зарегистрированный QG.)
+
+## 7. Совместимость / регресс
+
+- **Kill-switch** `ORCH_FS_NORMALIZE_ENABLED` (дефолт по решению архитектора; `False` → весь код инертен,
+  поведение 1:1 как до ORCH-057).
+- **Scope** `ORCH_FS_NORMALIZE_REPOS` (CSV; пусто → **self-hosting only**, как `coverage_gate_repos` →
+  enduro-trails не затронут). Локальный `applies(repo)` проверяется ПЕРВЫМ (дешёвый обход только при applies).
+- **Флаги** (рабочие имена, финал — за архитектором): `ORCH_FS_TARGET_UID` (дефолт 1000),
+  `ORCH_FS_NORMALIZE_AUTO` (дефолт `False` — детект-only; `True` → попытка chown при наличии прав),
+  `ORCH_FS_SCAN_ROOTS` (CSV переопределения корней), `ORCH_FS_SCAN_CACHE_TTL_S`.
+- **Never-raise / fail-safe** — ошибка детекта/нормализации деградирует в WARNING, не блокирует старт
+  сервиса по своей вине; FR-1 меняет лишь **формулировку** ошибки worktree, не её факт.
+- **Self-hosting** (NFR-1) — код только читает/детектит/диагностирует (и chown ТОЛЬКО при наличии прав);
+  не деплоит/не рестартит прод/не трогает `main`. Любое касание `docker-compose.yml`/entrypoint требует
+  staging-прогона (8501) перед прод-рестартом в окно тишины.
+- **Обратимость** — выкл kill-switch → прежнее поведение; миграций/правки схемы нет.
+- **Пайплайн-артефакты:** обновляются `01..04` (analysis), `06-adr/`+`07-infra-requirements.md`+`10-tech-risks.md`
+  (architecture), `12/13/15/14` (review/testing/staging/deploy), `INFRA.md`, `CHANGELOG.md`.

docs/work-items/ORCH-057/03-acceptance-criteria.md

@@ -0,0 +1,99 @@
+---
+work_item: ORCH-057
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 03 — Критерии приёмки (Acceptance Criteria): ORCH-057 — нормализация legacy root-owned файлов
+
+Work Item: **ORCH-057** · Repo: **orchestrator** · Стадия: analysis
+
+Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL**
+(что считается провалом). Любой машинный/ручной reviewer проверяет их буквально по файлам репозитория.
+
+---
+
+## AC-1 — Конвейер стартует без ручного chown (или внятная блокирующая ошибка)
+
+**Условие:** после миграции контейнера на новый uid первый job не падает сырым git-фаталом на launch.
+- **PASS:** при нормализованных правах worktree создаётся и агент стартует; при НЕнормализованных
+  правах конвейер выдаёт понятную блокирующую ошибку с диагнозом и лечащей командой (НЕ сырой
+  `fatal: could not create leading directories … Permission denied`).
+- **FAIL:** на launch всплывает сырой git-fatal/Permission denied без диагноза причины и инструкции.
+
+---
+
+## AC-2 — `ensure_worktree` даёт actionable-ошибку при отказе доступа
+
+**Условие:** `src/git_worktree.py::ensure_worktree` классифицирует ошибки прав.
+- **PASS:** при `Permission denied`/`could not create leading directories`/`insufficient permission`
+  поднимается `RuntimeError`, текст которого называет причину (legacy root-файлы в `/repos/_wt`/`.git`
+  после миграции uid) и указывает команду/ссылку на процедуру; ошибки, не связанные с правами,
+  сохраняют прежний контракт.
+- **FAIL:** сырой git stderr пробрасывается без диагноза; либо подменяется смысл не-прав-ошибок;
+  либо `ensure_worktree` падает необработанно.
+
+---
+
+## AC-3 — Детект несоответствия владельца
+
+**Условие:** новый леаф `src/fs_normalize.py` обнаруживает файлы с `uid != target_uid` в корнях
+(`/repos/_wt`, `<repo>/.git/objects`, `<repo>/.git/worktrees`, `data/runs`).
+- **PASS:** на среде с root-файлами `scan_ownership` возвращает mismatch=True + затронутые корни;
+  на чистой (`1000:1000`) среде — mismatch=False (no-op, идемпотентно); леаф never-raise.
+- **FAIL:** mismatch не обнаружен на грязной среде / ложный mismatch на чистой / леаф бросает наружу.
+
+---
+
+## AC-4 — Наблюдаемость детекта
+
+**Условие:** результат детекта виден оператору без падения задачи.
+- **PASS:** при mismatch — структурный лог-WARNING (число/корни/лечащая команда) и Telegram (если
+  включён); опц. read-only отражение в `GET /queue`.
+- **FAIL:** mismatch обнаружен, но никак не сообщён; оператор узнаёт о проблеме только по упавшей задаче.
+
+---
+
+## AC-5 — Self-hosting безопасность и нулевая регрессия enduro-trails
+
+**Условие:** изменение безопасно для общего инстанса.
+- **PASS:** код не рестартит/не роняет прод, не трогает `main`/force-push/прод-образ; chown — только
+  при наличии прав; при выключенном kill-switch поведение 1:1 как до ORCH-057; при пустом scope-CSV
+  feature активен только для self-hosting (enduro-trails не затронут); регресс `pytest tests/ -q` зелёный.
+- **FAIL:** любой рестарт/деградация прода из кода задачи; ненулевая регрессия enduro-trails;
+  поведение меняется при выключенном флаге; падение всего регресса.
+
+---
+
+## AC-6 — Инварианты конвейера сохранены
+
+**Условие:** изменение аддитивно.
+- **PASS:** `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, machine-verdict-ключи и схема БД —
+  байт-в-байт прежние; новые флаги аддитивны и обратимы.
+- **FAIL:** затронут любой exit/под-гейт, изменён machine-key, добавлена миграция схемы.
+
+---
+
+## AC-7 — Документированная процедура нормализации
+
+**Условие:** процедура воспроизводима.
+- **PASS:** `INFRA.md` содержит раздел «Миграция uid: обязательная нормализация legacy root-файлов»
+  с точными командами (`_wt`, оба `.git`, `data/runs`) как обязательный шаг миграции; ADR ORCH-057
+  фиксирует решение и ссылается на процедуру.
+- **FAIL:** процедура отсутствует/абстрактна (как было в ORCH-040) либо не покрывает все корни.
+
+---
+
+## Сводная матрица AC ↔ FR/BR
+| AC | Покрывает |
+|----|-----------|
+| AC-1 | BR-1 / FR-1, FR-3 |
+| AC-2 | BR-1, BR-5 / FR-1 |
+| AC-3 | BR-2 / FR-2 |
+| AC-4 | BR-4 / FR-3 |
+| AC-5 | NFR-1, NFR-2, NFR-5 / FR-4 |
+| AC-6 | NFR-5 (инварианты) |
+| AC-7 | BR-3 / FR-5 |

docs/work-items/ORCH-057/04-test-plan.yaml

@@ -0,0 +1,92 @@
+work_item: ORCH-057
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+title: "Нормализация legacy root-owned файлов при миграции на uid 1000 (детект + защита worktree)"
+framework: pytest
+scope: >
+  Покрывается: классификация ошибки прав в ensure_worktree (внятная actionable-ошибка),
+  детект несоответствия владельца (fs_normalize.scan_ownership), идемпотентность на чистой среде,
+  fail-safe/never-raise, scope/kill-switch (self-hosting only при пустом CSV), опц. self-heal-noop
+  без прав. ВНЕ покрытия: реальный chown под root (требует привилегий — проверяется на staging
+  вручную), правка docker-compose/entrypoint (инфра, ручная проверка на 8501).
+notes: >
+  Все FS-зависимые тесты используют tmp_path и monkeypatch os.getuid/os.stat — без реального chown
+  и без записи в /repos. Telegram/Plane мокаются. Полный регресс tests/ должен оставаться зелёным;
+  STAGE_TRANSITIONS/QG_CHECKS/схема БД не затрагиваются — отдельные guard-тесты не требуются, но
+  существующие тесты на инварианты должны пройти без изменений.
+
+tests:
+  - id: TC-01
+    type: unit
+    description: "ensure_worktree при git-fatal 'could not create leading directories / Permission denied' поднимает RuntimeError с диагнозом legacy-root + лечащей командой, а не сырой git stderr"
+    module: tests/test_git_worktree_perm.py
+    expected: PASS
+
+  - id: TC-02
+    type: unit
+    description: "ensure_worktree при ошибке, НЕ связанной с правами (например branch conflict), сохраняет прежний контракт сообщения (не подменяет смысл)"
+    module: tests/test_git_worktree_perm.py
+    expected: PASS
+
+  - id: TC-03
+    type: unit
+    description: "scan_ownership на дереве с файлом uid != target_uid возвращает mismatch=True и список затронутых корней"
+    module: tests/test_fs_normalize.py
+    expected: PASS
+
+  - id: TC-04
+    type: unit
+    description: "scan_ownership на чистом дереве (все файлы target_uid) возвращает mismatch=False (идемпотентный no-op)"
+    module: tests/test_fs_normalize.py
+    expected: PASS
+
+  - id: TC-05
+    type: unit
+    description: "scan_ownership never-raise: при недоступном/несуществующем корне деградирует в WARNING и не бросает наружу"
+    module: tests/test_fs_normalize.py
+    expected: PASS
+
+  - id: TC-06
+    type: unit
+    description: "applies(repo): пустой ORCH_FS_NORMALIZE_REPOS → True только для self-hosting репо (orchestrator), False для enduro-trails; непустой CSV — по списку"
+    module: tests/test_fs_normalize.py
+    expected: PASS
+
+  - id: TC-07
+    type: unit
+    description: "kill-switch ORCH_FS_NORMALIZE_ENABLED=False → scan/normalize инертны (no-op), поведение 1:1 как до ORCH-057"
+    module: tests/test_fs_normalize.py
+    expected: PASS
+
+  - id: TC-08
+    type: unit
+    description: "normalize без прав (uid 1000, чужие root-файлы, ORCH_FS_NORMALIZE_AUTO=True) → no-op + честный лог 'нужна операторская процедура', НЕ исключение"
+    module: tests/test_fs_normalize.py
+    expected: PASS
+
+  - id: TC-09
+    type: unit
+    description: "TTL-кэш детекта: повторный вызов в окне TTL не пере-сканирует дерево (по образцу preflight._cache); force/reset инвалидирует"
+    module: tests/test_fs_normalize.py
+    expected: PASS
+
+  - id: TC-10
+    type: integration
+    description: "startup-хук lifespan при mismatch вызывает send_telegram (мок) и логирует WARNING; при ошибке детекта старт сервиса не падает (never-fatal)"
+    module: tests/test_fs_normalize_startup.py
+    expected: PASS
+
+  - id: TC-11
+    type: integration
+    description: "опц. гейт claim'а: при обнаруженном mismatch без прав исход job внятный (FR-1-сообщение / не-claim) ДО launch, а не сырой git-fatal"
+    module: tests/test_fs_normalize_startup.py
+    expected: PASS
+
+  - id: TC-12
+    type: integration
+    description: "GET /queue (если реализован read-only блок fs_ownership) отдаёт {enabled,target_uid,mismatch,roots,checked_at} и не 5xx-ит при выключенном флаге"
+    module: tests/test_api_queue.py
+    expected: PASS

docs/work-items/ORCH-057/06-adr/ADR-001-legacy-ownership-normalization.md

@@ -0,0 +1,210 @@
+---
+work_item: ORCH-057
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# ADR-001: Нормализация legacy root-owned файлов при миграции на uid 1000 — детект + actionable-ошибка + процедура
+
+Work Item: **ORCH-057** — follow-up ORCH-040 (legacy `root:root` файлы в `/repos` ломают создание worktree под uid 1000)
+Стадия: **architecture**
+Сквозная регистрация: **`docs/architecture/adr/adr-0031-legacy-ownership-normalization.md`** (новый
+leaf-компонент + startup-поведение, затрагивает весь инстанс → кросс-каттинг).
+
+## Статус
+Proposed
+
+## Контекст
+
+ORCH-040 перевёл оба контейнера на `user: "1000:1000"`, изменив **только** `docker-compose.yml`.
+Смена `user:` не меняет владельца уже существующих файлов, созданных прежним root-контейнером.
+Bind-mount `/home/slin/repos → /repos` содержал `root:root` каталоги (`_wt/`, старые worktree,
+`.git/objects`, `data/runs` — 37 root-логов).
+
+**Сверено по коду:**
+- `src/git_worktree.py::ensure_worktree` (стр. 78 `os.makedirs(os.path.dirname(wt))`, стр. 81/85
+  `git worktree add`) — точка реального падения. При `root:root` владельце `/repos/_wt/` uid 1000
+  не может создать рядом новый каталог worktree → `fatal: could not create leading directories …
+  Permission denied`. Сейчас этот stderr пробрасывается «сырым» в `RuntimeError` (стр. 90–93) без
+  диагноза причины.
+- Конвейер приходит сюда из `src/agents/launcher.py::_spawn` и `_materialize_deferred_branch`
+  (ORCH-088, отложенный срез ветки на момент claim analyst-job). **Агент не стартует** — падает
+  создание worktree (НЕ код задачи), т.е. это launch-time инфраструктурный сбой.
+- Контейнер бежит под numeric uid 1000 **без root** (ORCH-040 P-3, ORCH-058 реальный user `slin`
+  в образе). Под uid 1000 `chown` чужих (root) файлов **невозможен** без `CAP_CHOWN`. Значит код
+  физически не может «починить» права сам — ему доступны только **детект + диагностика**, а
+  фактический `chown` — операторская процедура.
+- ADR-001 ORCH-040 упоминал «массовый chown старых root-файлов» лишь абстрактно («вне объёма кода»,
+  «разовая операция Owner») и не дал конкретной процедуры → deployer её не выполнил → баг проявился
+  в проде 06.06 на первом запуске ORCH-043. Прод сейчас рабочий (ручной workaround Стрима наложен),
+  но проблема **воспроизводится** на чистой среде / новом репо / после любого исторического запуска
+  под root.
+
+Это **закрытие недоделанного AC ORCH-040**, а не новая фича. Существующие гейты/паттерны для опоры:
+условный leaf-гейт `coverage_gate`/`serial_gate` (kill-switch + scope + `is_self_hosting_repo`),
+best-effort startup-хуки в `main.lifespan` (lease-reclaim, log-rotation — never-fatal),
+read-only снимки `GET /queue` (`serial_gate.snapshot()`), TTL-кэш `preflight._cache`.
+
+## Решение
+
+### Сводка
+Три аддитивных, обратимых kill-switch'ем слоя, **без** изменения `STAGE_TRANSITIONS` / `QG_CHECKS` /
+`check_*` / machine-verdict-ключей / схемы БД:
+
+1. **Actionable-ошибка** в `ensure_worktree` — класс «нет прав на создание worktree» распознаётся и
+   превращается в диагностируемый `RuntimeError` с причиной + лечащей командой (FR-1).
+2. **Детект-леаф** `src/fs_normalize.py` — чистый, never-raise, TTL-кэшируемый обход корней, ищет
+   файлы с `uid != target_uid` (FR-2); вызывается best-effort на старте сервиса с наблюдаемостью
+   (FR-3).
+3. **Операторская процедура** в `INFRA.md` + forward-breadcrumb из ADR-040 — точные команды разовой
+   нормализации как обязательный шаг миграции uid (FR-5).
+
+Фактический `chown` остаётся **операторской процедурой** (NFR-1: код под uid 1000 без root его делать
+не может и не должен).
+
+### D1 — `ensure_worktree`: классификация отказа доступа (FR-1, AC-1, AC-2)
+Оборачиваем **обе** точки сбоя по правам — `os.makedirs(os.path.dirname(wt))` (стр. 78) и оба
+`git worktree add` (стр. 81/85). Класс «нет прав» детектируется по маркерам в `stderr`/исключении:
+`Permission denied`, `could not create leading directories`, `insufficient permission for adding an
+object`, `PermissionError` (errno `EACCES`/`EPERM`). При совпадении — `RuntimeError`, текст которого:
+(а) называет корневую причину («legacy root-owned файлы в `/repos/_wt` или `.git` после миграции uid
+ORCH-040»); (б) указывает лечащую команду (`chown -R <target_uid>:<gid> /repos/_wt …`) и ссылку на
+раздел INFRA.md; (в) **не** является сырым git stderr.
+
+**Инвариант контракта (AC-2 FAIL-условие):** ошибки, **не** связанные с правами (реальный git-конфликт,
+отсутствие `origin/main`, таймаут), сохраняют **прежний** текст/смысл — никакой подмены. Классификатор —
+чистая функция `classify_worktree_error(stderr_or_exc) -> bool` (или хелпер в `fs_normalize`),
+покрытая юнит-тестами на обе ветки. Помощь-сообщение строится только при `True`. Это **меняет лишь
+формулировку** ошибки, не её факт (NFR-3): worktree как падал, так и падает — но теперь внятно.
+
+### D2 — Детект-леаф `src/fs_normalize.py` (FR-2, AC-3)
+Новый чистый модуль по образцу `serial_gate`/`post_deploy` (импортирует только `config`/`logging`/
+`os`/`pwd`; не тянет `stage_engine`/`launcher`). API:
+
+- `scan_ownership(roots: list[str] | None = None, target_uid: int | None = None) -> OwnershipScan` —
+  обходит корни, возвращает `{mismatch: bool, target_uid: int, roots_checked: list, roots_mismatch:
+  list, sample_path: str | None, count: int | None, checked_at: float}`.
+- **`target_uid`** по умолчанию = `os.getuid()` (uid, под которым реально бежит процесс — ровно тот
+  субъект, что «не может создать файл»); переопределяется `fs_target_uid` (дефолт 1000) для тестов/
+  нестандартного рантайма.
+- **Корни** по умолчанию: `/repos/_wt`, `<repo>/.git/objects`, `<repo>/.git/worktrees` (для репо из
+  скоупа), `data/runs` (`os.path.dirname(settings.db_path)/runs`). Переопределяемы `fs_scan_roots`
+  (CSV).
+- **Дешевизна (риск стоимости обхода):** **ранний выход при первом mismatch** (для быстрого булева
+  вердикта `os.lstat(...).st_uid != target_uid`). Полный `count` — опционален/семплирован (отдельный
+  дешёвый режим, по умолчанию выключен), чтобы не обходить целиком большие `.git/objects`. Результат
+  **кэшируется по TTL** `fs_scan_cache_ttl_s` (паттерн `preflight._cache`, `force=` обходит кэш).
+- **never-raise (NFR-3):** любая ошибка обхода (исчезнувший путь, отказ stat) → деградирует в WARNING
+  и консервативный вердикт `mismatch=False` (не блокирует и не паникует); идемпотентно (AC-3:
+  повторный скан на чистой среде — `mismatch=False`, no-op).
+- **`applies(repo: str) -> bool`** — `fs_normalize_enabled` (kill-switch) И scope (`fs_normalize_repos`
+  CSV; пусто → `is_self_hosting_repo(repo)`, как `coverage_gate`); проверяется **ПЕРВЫМ**, дорогой
+  обход — только при `applies==True` (NFR-2: enduro-trails не сканируется при пустом CSV).
+- **`snapshot() -> dict`** — read-only для `GET /queue`.
+
+### D3 — Точка интеграции: startup-наблюдаемость, БЕЗ блокировки claim (FR-3 — разрешение открытого выбора TRZ)
+TRZ §2 оставил архитектору выбор «preflight vs queue_worker» для опц. гейта claim'а. **Решение:
+claim НЕ блокируем.**
+
+- **Startup (`main.lifespan`):** best-effort вызов `scan_ownership()` рядом с lease-reclaim/log-rotation
+  (стр. 63–90), обёрнут `try/except` (never-fatal). При `mismatch` — структурный WARNING (число/корни/
+  лечащая команда) + Telegram (если включён). Это даёт оператору **проактивный сигнал заранее**
+  (AC-4), не дожидаясь падения задачи.
+- **«Внятно и заранее» обеспечивает D1, а не claim-гейт.** `ensure_worktree` знает `repo` и падает
+  до того, как агент потратит хоть один токен (агент не стартует). Это и есть требуемый ранний внятный
+  исход.
+
+**Почему НЕ блокирующий claim-гейт (отвергнуто):**
+- `preflight.check()` **не знает repo** и гейтит claim **всех** репо → при mismatch в общем `/repos/_wt`
+  заблокировал бы и enduro-trails (нарушение NFR-2 при включённом флаге). Сделать его scope-aware
+  внутри preflight нельзя без знания репо в точке вызова.
+- Гейт в `queue_worker`/`db.claim_next_job` (как `serial_gate`) технически scope-aware, но: (1)
+  оставил бы задачу «молча висеть» в очереди вместо явного диагноза; (2) добавил бы дорогой FS-обход
+  в offline hot-path claim'а; (3) дублировал бы исход, который D1 уже даёт внятно. Лишняя поверхность
+  без выигрыша.
+
+Итог: **детект = наблюдаемость (startup + опц. ручной POST), а внятный отказ = D1 в точке launch.**
+
+### D4 — Опциональная авто-нормализация `normalize()` (FR-4) — не init-контейнер
+`fs_normalize.normalize(roots, target_uid)` выполняет `os.chown`/`chown -R` по корням **только если
+процесс имеет `CAP_CHOWN`/root**. Под uid 1000 без прав — **no-op + честный лог** «нужна операторская
+процедура» (НЕ ошибка). Включается отдельным флагом `fs_normalize_auto` (дефолт `False` — детект-only).
+
+**Init-контейнер/root-entrypoint отвергнут (см. Альтернативы):** он (а) реинтродуцирует root-контекст,
+ровно который ORCH-040 убрал ради безопасности; (б) требует правки `docker-compose.yml`/entrypoint →
+**self-deploy** с групповым риском (NFR-1) и обязательной staging-страховкой ради разовой задачи;
+(в) discretionary по BRD §2 «Опционально». Носитель реальной нормализации — **документированная
+операторская процедура** (D5), запускаемая под root **на хосте** один раз при миграции uid.
+
+### D5 — Процедура в INFRA.md + forward-breadcrumb (FR-5, AC-7)
+В `docs/operations/INFRA.md` (раздел «Рантайм-uid (ORCH-040)») добавляется подраздел **«Миграция uid:
+обязательная нормализация legacy root-файлов»** с точными командами, покрывающими **все** корни
+(`_wt`, оба `.git`, `data/runs`), помеченный как **обязательный** шаг миграции uid и пункт чеклиста
+деплоя self. Существующий абстрактный буллет (стр. 50–51) заменяется ссылкой на новый подраздел.
+В ADR-040 — необязательный forward-breadcrumb на ORCH-057 (история ORCH-040 не переписывается, §2 BRD).
+
+### D6 — Конфиг-флаги (TRZ §7) и наблюдаемость
+Аддитивно в `src/config.py` (существующие значения не трогаются):
+
+| Флаг (env) | Дефолт | Смысл |
+|------------|--------|-------|
+| `fs_normalize_enabled` (`ORCH_FS_NORMALIZE_ENABLED`) | `True` | kill-switch; `False` → весь код инертен, поведение 1:1 как до ORCH-057 (D1 тоже гардится — при выкл. контракт ошибки прежний) |
+| `fs_normalize_repos` (`ORCH_FS_NORMALIZE_REPOS`) | `""` | scope CSV; пусто → self-hosting only (`is_self_hosting_repo`) |
+| `fs_target_uid` (`ORCH_FS_TARGET_UID`) | `1000` | целевой uid (фолбэк, если `os.getuid()` неприменим) |
+| `fs_normalize_auto` (`ORCH_FS_NORMALIZE_AUTO`) | `False` | детект-only; `True` → попытка chown при наличии прав (D4) |
+| `fs_scan_roots` (`ORCH_FS_SCAN_ROOTS`) | `""` | CSV-переопределение корней |
+| `fs_scan_cache_ttl_s` (`ORCH_FS_SCAN_CACHE_TTL_S`) | `300` | TTL детект-кэша |
+
+Наблюдаемость (AC-4): read-only блок `fs_ownership` в `GET /queue` (`snapshot()`:
+`{enabled, target_uid, mismatch, roots_checked, roots_mismatch, checked_at}`); опц. ручной триггер
+`POST /fs-normalize/check` (форс-пересчёт, по образцу `POST /serial-gate/unfreeze`). Telegram при
+mismatch — с кликабельным номером задачи (если в контексте есть `work_item_id`), числом/корнями,
+лечащей командой.
+
+## Альтернативы
+- **Init-контейнер / root-entrypoint, выполняющий `chown` на буте** — отвергнуто: реинтродуцирует
+  root-контекст (анти-цель ORCH-040), требует правки `docker-compose.yml`/entrypoint = self-deploy +
+  групповой риск + обязательная staging-страховка ради одноразовой операции; BRD помечает его
+  «Опционально». Реальную нормализацию несёт документированная разовая операторская процедура.
+- **Блокирующий claim-гейт в `preflight`** — отвергнуто: preflight не знает repo → блокирует claim
+  ВСЕХ репо, регресс enduro-trails на общем `/repos` (нарушение NFR-2).
+- **Блокирующий claim-гейт в `queue_worker`/`claim_next_job`** — отвергнуто: дорогой FS-обход в
+  offline hot-path, «молчаливое зависание» вместо внятного диагноза, дублирует исход D1.
+- **Авто-`chown` из app-кода по умолчанию** — отвергнуто: под uid 1000 невозможен; включение по
+  умолчанию создавало бы ложное ожидание самолечения. Оставлен как opt-in `fs_normalize_auto` для
+  сред, где процесс имеет CAP_CHOWN.
+- **Жёсткий fail на старте при mismatch** — отвергнуто: нарушает never-raise (NFR-3) и мог бы
+  застопорить старт сервиса всех проектов из-за грязного `/repos`. Детект — only WARNING/Telegram.
+
+## Последствия
+- **+** Класс «сырой git-fatal на launch после миграции uid» закрыт: оператор получает внятный
+  диагноз + лечащую команду в точке падения (D1) и проактивный сигнал на старте (D3).
+- **+** Воспроизводимая процедура в INFRA.md закрывает пробел ADR-040 (AC-7).
+- **+** Нулевая регрессия enduro-trails (scope `applies()` first, пустой CSV → self-hosting only);
+  `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД — байт-в-байт прежние (AC-6).
+- **+** Никакого root-контекста, рестарта прода, касания `main`/force-push/прод-образа (NFR-1, AC-5).
+- **−** Фактический `chown` остаётся **ручным** операторским шагом — на средах, где его забыли, баг
+  всё ещё проявится, но теперь **внятно** (с инструкцией), а не сырым git-fatal. Митигейшн:
+  startup-WARNING+Telegram + обязательный пункт чеклиста миграции в INFRA.md.
+- **−** Ещё один best-effort startup-хук + leaf-модуль (рост поверхности). Митигейшн: чистый
+  never-raise leaf, TTL-кэш, ранний выход обхода, kill-switch.
+- **−** `fs_normalize_auto=True` под root реинтродуцирует chown-контекст — поэтому дефолт `False` и
+  он не для прод-self (прод бежит под uid 1000).
+- **Откат:** `fs_normalize_enabled=False` → весь код инертен (D1 контракт ошибки прежний, детект не
+  запускается); миграций/правки схемы нет → мгновенный обратимый kill-switch.
+
+## Ссылки
+- BRD: `docs/work-items/ORCH-057/01-brd.md`
+- TRZ: `docs/work-items/ORCH-057/02-trz.md`
+- Acceptance: `docs/work-items/ORCH-057/03-acceptance-criteria.md`
+- Инфра: `docs/work-items/ORCH-057/07-infra-requirements.md`
+- Риски: `docs/work-items/ORCH-057/10-tech-risks.md`
+- Сквозной ADR: `docs/architecture/adr/adr-0031-legacy-ownership-normalization.md`
+- Сверено по коду: `src/git_worktree.py` (`ensure_worktree` стр. 78/81/85/90), `src/preflight.py`
+  (TTL-кэш), `src/main.py` (`lifespan` стр. 63–114), `src/serial_gate.py` / `src/coverage_gate.py`
+  (паттерн условного leaf `applies`/scope/`is_self_hosting_repo`).
+- Предшественник: `docs/work-items/ORCH-040/06-adr/ADR-001-run-agents-as-host-uid.md`,
+  `docs/architecture/adr/adr-0005-container-runs-as-host-uid.md`.

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

@@ -0,0 +1,63 @@
+---
+work_item: ORCH-057
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 07 — Инфра-требования: ORCH-057 — нормализация legacy root-owned файлов при миграции на uid 1000
+
+Work Item: **ORCH-057** · Repo: **orchestrator** · Стадия: architecture
+
+> When-applicable. Топология контейнеров **не меняется** (init-контейнер/правка `docker-compose.yml`
+> отвергнуты — ADR-001 D4). Файл фиксирует новые env-флаги и **обязательную операторскую процедуру**
+> нормализации legacy root-файлов как шаг миграции uid.
+
+## I-1. Топология / окружения
+**Без изменений.** Контейнеры `orchestrator` (8500) / `orchestrator-staging` (8501), `user:
+"1000:1000"`, bind-mount `/home/slin/repos → /repos`, `network_mode: host` — как есть. Init-контейнер
+/ root-entrypoint **сознательно НЕ вводятся** (реинтродуцировали бы root-контекст, убранный ORCH-040,
+и потребовали бы self-deploy compose с групповым риском — ADR-001 D4, Альтернативы).
+
+## I-2. Переменные окружения / секреты
+Новые env-флаги (аддитивно в `src/config.py`, дефолты сохраняют поведение до ORCH-057). Добавить в
+`.env.example` (секретов нет):
+
+| Env | Дефолт | Назначение |
+|-----|--------|------------|
+| `ORCH_FS_NORMALIZE_ENABLED` | `true` | kill-switch всего слоя ORCH-057 |
+| `ORCH_FS_NORMALIZE_REPOS` | `` (пусто) | scope CSV; пусто → self-hosting only (enduro не затронут) |
+| `ORCH_FS_TARGET_UID` | `1000` | целевой uid (фолбэк к `os.getuid()`) |
+| `ORCH_FS_NORMALIZE_AUTO` | `false` | детект-only; `true` → попытка chown при наличии CAP_CHOWN |
+| `ORCH_FS_SCAN_ROOTS` | `` (пусто) | CSV-переопределение корней обхода |
+| `ORCH_FS_SCAN_CACHE_TTL_S` | `300` | TTL детект-кэша |
+
+Секреты не вводятся.
+
+## I-3. Деплой / рестарт
+- **Self-hosting инвариант (NFR-1):** код задачи **не** рестартит/не роняет прод-контейнер
+  `orchestrator`, не трогает `main`/force-push/прод-образ. `chown` из кода возможен лишь при наличии
+  прав (под uid 1000 — no-op).
+- Изменение **только** `src/**` + docs → штатный деплой self **через staging-гейт (8501)**, затем
+  прод-рестарт **в окно тишины** (`GET /status` без активных задач). Правки `docker-compose.yml`/
+  entrypoint в задаче **нет** → нет дополнительного инфра-риска сверх обычного self-деплоя.
+- **Обязательная операторская процедура нормализации (host-prerequisite миграции uid)** — выполняется
+  **под root на хосте mva154 один раз** при миграции uid / на новой среде, ПЕРЕД стартом app.
+  Каноничный текст — в `docs/operations/INFRA.md` (раздел «Миграция uid: обязательная нормализация
+  legacy root-файлов»). Команды покрывают все корни:
+  ```
+  sudo chown -R 1000:1000 /home/slin/repos/_wt
+  sudo chown -R 1000:1000 /home/slin/repos/orchestrator/.git \
+                          /home/slin/repos/enduro-trails/.git
+  sudo chown -R 1000:1000 /home/slin/repos/orchestrator        # incl. data/runs/*.log
+  # Проверка: find /home/slin/repos/_wt ! -uid 1000 -print -quit   (пусто = ок)
+  ```
+  Идемпотентна (повтор на корректной среде — no-op). Помечена обязательным пунктом чеклиста
+  деплоя/миграции self.
+
+## I-4. CI/CD
+Без изменений в `.gitea/workflows/`. Новые юнит-тесты (`tests/test_fs_normalize.py`,
+`tests/test_git_worktree_perm_error.py` — см. `04-test-plan.yaml`) гоняются существующим
+`pytest tests/ -q`. Новых системных зависимостей образа нет.

docs/work-items/ORCH-057/10-tech-risks.md

@@ -0,0 +1,37 @@
+---
+work_item: ORCH-057
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+---
+
+# 10 — Технические риски: ORCH-057 — нормализация legacy root-owned файлов при миграции на uid 1000
+
+Work Item: **ORCH-057** · Repo: **orchestrator** · Стадия: architecture
+
+> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн.
+
+## Реестр рисков
+
+| ID | Риск | Вер. | Влия. | Митигейшн |
+|----|------|------|-------|-----------|
+| TR-1 | **Ложная классификация ошибки worktree** (D1): не-прав-ошибка распознана как «нет прав» → подмена смысла (FAIL AC-2). | Низ. | Сред. | Узкий набор маркеров (`Permission denied`/`could not create leading directories`/`insufficient permission`/`EACCES`/`EPERM`); классификатор — чистая функция с юнит-тестами на обе ветки; не-совпадение → прежний сырой текст без изменений. |
+| TR-2 | **Дорогой рекурсивный обход** больших `.git/objects` / `_wt` тормозит старт сервиса. | Сред. | Сред. | Ранний выход при первом mismatch (булев вердикт); полный `count` опционален/семплирован; TTL-кэш (`fs_scan_cache_ttl_s`); вызов best-effort на старте, не в hot-path claim'а; `applies()` first → обход только при applies. |
+| TR-3 | **Ложно-блокирующий эффект на enduro-trails** через общий `/repos`. | Низ. | Выс. | Claim НЕ блокируется (D3 — только наблюдаемость); scope `applies()` first, пустой CSV → self-hosting only → enduro не сканируется; детект never-raise. |
+| TR-4 | **Забытый ручной `chown`**: на среде без выполненной процедуры баг всё ещё проявится. | Сред. | Сред. | Теперь проявляется **внятно** (D1 actionable-ошибка + startup WARNING/Telegram, не сырой git-fatal); процедура — обязательный пункт чеклиста миграции в INFRA.md; идемпотентна. Остаточный риск принят (код под uid 1000 не может chown). |
+| TR-5 | **`fs_normalize_auto=True` под root** реинтродуцирует chown-контекст / неожиданный массовый chown. | Низ. | Сред. | Дефолт `False`; прод-self бежит под uid 1000 (chown = no-op); auto-режим — opt-in для сред с CAP_CHOWN; init-контейнер отвергнут (ADR-001 D4). |
+| TR-6 | **never-raise дыра**: необработанное исключение детекта роняет старт сервиса всех проектов. | Низ. | Выс. | Леаф never-raise (паттерн `serial_gate`/`post_deploy`); startup-вызов в `try/except` (как lease-reclaim/log-rotation); ошибка → WARNING + консервативный `mismatch=False`. |
+| TR-7 | **`os.getuid()` неприменим** в нестандартном рантайме → неверный target_uid → ложный mismatch. | Низ. | Низ. | Фолбэк `fs_target_uid` (дефолт 1000); идемпотентность скана; вердикт only-наблюдательный (не блокирует). |
+| TR-8 | **Кэш устарел** после выполнения нормализации → stale `mismatch=True` в `GET /queue`. | Низ. | Низ. | TTL-инвалидизация; ручной `POST /fs-normalize/check` (`force=True`) для немедленного пересчёта. |
+
+## Сводный вывод
+Доминирующий класс — **операционные риски разовой нормализации**, а не алгоритмические: код только
+читает/детектит/диагностирует (chown — операторская процедура под root на хосте). Самостоятельный
+техдолг (TR-4) — остаточный и **принят**: контейнер без root физически не может починить права сам;
+решение гарантирует **внятность** отказа, а не его отсутствие. Self-hosting-безопасность соблюдена
+(никакого рестарта прода / касания `main` / root-контекста в коде). Изменение аддитивно и обратимо
+kill-switch'ем → **эскалация `arch:major-change` НЕ требуется** (нет новой стадии/QG/таблицы/смены
+топологии). Возврат в анализ не нужен — ТЗ удовлетворяется без нарушения принципов архитектуры.
+Остаточный риск для прод-конвейера — **низкий**.

docs/work-items/ORCH-057/12-review.md

@@ -0,0 +1,105 @@
+---
+verdict: APPROVED
+work_item: ORCH-057
+stage: review
+author_agent: reviewer
+status: approved
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: review
+work_item_id: ORCH-057
+version: 1
+---
+
+# Review ORCH-057
+
+## Summary
+
+Follow-up ORCH-040: закрыт недоделанный AC по legacy `root:root` файлам, ломавшим создание
+worktree под uid 1000. Реализованы три аддитивных, обратимых kill-switch'ем слоя ровно по ADR-001:
+**D1** actionable-ошибка в `ensure_worktree`, **D2** детект-леаф `src/fs_normalize.py`
+(never-raise, TTL-кэш, scope-aware), **D3** best-effort startup-наблюдаемость в `main.lifespan`
+(WARNING + Telegram, claim не блокируется), плюс `GET /queue` блок `fs_ownership` и
+`POST /fs-normalize/check`. Документация (INFRA.md процедура, architecture/README.md, сквозной
+adr-0031, CHANGELOG, .env.example) обновлена в том же PR.
+
+Проверено по 4 осям; все 7 AC выполнены, P0/P1 findings нет. Регресс `pytest tests/ -q` —
+**1507 passed**; целевые модули (`test_fs_normalize`, `test_fs_normalize_startup`,
+`test_git_worktree_perm`, `test_api_queue`) — **25 passed**, покрывают TC-01…TC-12.
+
+## Соответствие ТЗ (02-trz) и AC (03-acceptance-criteria)
+
+- **FR-1 / AC-1, AC-2** ✓ — `git_worktree._raise_if_permission` + `fs_normalize.is_permission_failure`/
+  `build_worktree_help`: класс «нет прав» (`Permission denied`/`could not create leading directories`/
+  `insufficient permission`/`PermissionError`/`EACCES`/`EPERM`) → actionable `RuntimeError` с причиной,
+  `chown`-командой и ссылкой на INFRA.md. Обе точки сбоя обёрнуты (`os.makedirs` + оба `worktree add`).
+  Не-прав-ошибки сохраняют прежний raw-контракт (TC-02 PASS). Под kill-switch — no-op, контракт 1:1.
+- **FR-2 / AC-3** ✓ — `scan_ownership` обходит `/repos/_wt`, `<repo>/.git/{objects,worktrees}`,
+  `data/runs`; ранний выход на первом `lstat.st_uid != target_uid`; чистая среда → `mismatch=False`
+  идемпотентно; never-raise → консервативный `mismatch=False` (TC-03/04/05).
+- **FR-3 / AC-4** ✓ — startup-хук never-fatal: WARNING + Telegram при mismatch; claim не блокируется
+  (D3, преднамеренно — внятный ранний отказ даёт D1, знающий repo). Read-only блок `fs_ownership` в
+  `GET /queue` (TC-10/TC-12).
+- **FR-4** ✓ — `normalize()` chown только при `_is_privileged()` (geteuid==0); под uid 1000 — no-op +
+  честный лог, НЕ ошибка; gated `fs_normalize_auto` (дефолт False) (TC-08).
+- **FR-5 / AC-7** ✓ — INFRA.md: блокер P-5 + подраздел «Миграция uid: обязательная нормализация»
+  со всеми корнями; work-item ADR + сквозной adr-0031.
+- **§7 совместимость / AC-5** ✓ — `applies(repo)` first (kill-switch + scope; пустой CSV →
+  self-hosting only через `is_self_hosting_repo`); enduro-trails не сканируется при дефолте.
+  TTL-кэш (`fs_scan_cache_ttl_s`). Регресс зелёный (1507 passed).
+
+## Соответствие ADR
+
+- Реализация совпадает с ADR-001 D1–D6 (включая сознательный отказ от блокирующего claim-гейта и
+  init-контейнера — обоснование в «Альтернативах»). Сквозная регистрация adr-0031 присутствует и
+  отражена в architecture/README.md.
+- **Трассировка (AC-6 / TRACEABILITY):** инварианты конвейера не тронуты — commit `9852871` НЕ
+  затрагивает `src/stages.py`, `src/qg/checks.py`, `src/db.py`, `src/stage_engine.py`. Маркеры
+  ORCH-040/088 в `git_worktree`/`main` читаются, зафиксированные инварианты (never-fatal startup,
+  отложенный срез ветки) не сломаны. `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема
+  БД — байт-в-байт прежние.
+
+## Качество кода
+
+- `src/fs_normalize.py` — чистый leaf (импортирует только `config`/`logging`/`os`/`time`,
+  лениво `qg.checks`/`notifications`); строгий never-raise на каждой публичной функции; docstrings
+  на всех публичных символах; `os.lstat` (не `stat`) для честной оценки симлинков. Зависимость
+  односторонняя (`git_worktree` → `fs_normalize`).
+- Узкий `_PERM_MARKERS` сознательно не реклассифицирует не-прав-ошибки (защита AC-2).
+- Тесты содержательны (214/136/139/68 строк), используют `tmp_path`/monkeypatch, без реального
+  chown и записи в `/repos`; покрывают обе ветки классификатора, идемпотентность, scope, kill-switch,
+  TTL-кэш, startup-never-fatal.
+- Утечек/секретов/security-дыр не выявлено; chown физически возможен только под root (`_is_privileged`).
+
+## Findings
+
+### P0 — Blocker
+- Нет.
+
+### P1 — Must fix
+- Нет.
+
+### P2 — Should fix
+- Нет.
+
+### P3 — Nice-to-have (не блокирует)
+- [ ] `snapshot()` в `GET /queue` на холодном кэше инициирует реальный обход `.git/objects` синхронно
+  в обработчике запроса. На практике кэш прогрет startup-хуком и TTL=300s, обход только для
+  self-hosting — латентность пренебрежима, паттерн зеркалит `coverage_gate`. Можно при желании
+  отдавать в `/queue` только кэш без форс-скана. Информационно.
+
+## Документация
+
+Обновлена в том же PR — golden source синхронен с кодом:
+- `docs/operations/INFRA.md` — P-5 (блокер миграции uid) + подраздел процедуры со всеми корнями ✓
+- `docs/architecture/README.md` — компонент «FS ownership detect» (D1–D3, условность, наблюдаемость) ✓
+- `docs/architecture/adr/adr-0031-legacy-ownership-normalization.md` — сквозной ADR (tracked) ✓
+- `docs/work-items/ORCH-057/06-adr/ADR-001-…md` — work-item ADR ✓
+- `CHANGELOG.md` — запись ORCH-057 ✓
+- `.env.example` — 6 флагов `ORCH_FS_*` ✓
+
+`README.md` «Известные ограничения» (ORCH-079): пункт про legacy-ownership/uid-миграцию там
+отсутствует — закрывать/снимать нечего, обзорная витрина в обновлении не нуждается.
+
+**Вывод:** изменение `src/` сопровождено обновлением документации → требование правила 6
+выполнено.

docs/work-items/ORCH-057/13-test-report.md

@@ -0,0 +1,94 @@
+---
+result: PASS   # PASS | FAIL — машинный вердикт, UPPERCASE
+work_item: ORCH-057
+stage: testing
+author_agent: tester
+status: pass
+created_at: 2026-06-10
+model_used: claude-opus-4-8
+type: test-report
+work_item_id: ORCH-057
+---
+
+# Test Report — ORCH-057
+
+Нормализация legacy root-owned файлов при миграции на uid 1000 (детект + защита worktree).
+Review-вердикт `12-review.md` — **APPROVED**, P0/P1 findings нет.
+
+## Окружение
+- Python: 3.12.13
+- pytest: 8.3.3 (plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8)
+- Дата: 2026-06-10
+- Worktree: `/repos/_wt/orchestrator/feature_ORCH-057-bug-follow-up-orch-040-normali`
+  (ветка `feature/ORCH-057-bug-follow-up-orch-040-normali`, тесты прогнаны из рабочего дерева
+  именно этой задачи, НЕ из общего `/repos/orchestrator`)
+
+## Smoke API (read-only, прод-контейнер 8500 не тронут)
+| Эндпоинт | Результат |
+|----------|-----------|
+| `GET /health` | `{"status":"ok","service":"orchestrator"}` — OK |
+| `GET /status` | OK — задача ORCH-057 (id 83) видна на стадии `testing` |
+| `GET /queue` | OK — присутствуют блоки `serial_gate` (ORCH-088) ✓ и `auto_labels` (ORCH-089) ✓ |
+
+> Примечание: блок `fs_ownership` (ORCH-057) на прод-контейнере 8500 **отсутствует** —
+> это ожидаемо: ORCH-057 ещё не задеплоен, прод исполняет предыдущий образ. Read-only блок
+> `fs_ownership` присутствует и протестирован в коде ветки (TC-12, `test_api_queue.py` PASS).
+> Это НЕ регресс смока: обязательные блоки `serial_gate` + `auto_labels` на месте.
+
+## Результаты
+
+### Полный регресс
+`pytest tests/ -q` → **1507 passed, 1 warning in 52.22s** (warning — Pydantic V2 deprecation,
+предсуществующий, не относится к ORCH-057). Прод-контейнер не трогался.
+
+### Профильные сюиты
+`pytest tests/test_git_worktree_perm.py tests/test_fs_normalize.py tests/test_fs_normalize_startup.py tests/test_api_queue.py -v`
+→ **25 passed** — покрывают TC-01…TC-12.
+
+### Сопоставление с тест-планом (04-test-plan.yaml)
+| TC ID | Описание | Тест-функция | Результат |
+|-------|----------|--------------|-----------|
+| TC-01 | `ensure_worktree` на git-fatal Permission denied → actionable RuntimeError | `test_git_worktree_perm::test_tc01_permission_git_fatal_becomes_actionable`, `test_tc01_makedirs_permission_error_becomes_actionable` | PASS |
+| TC-02 | не-прав-ошибка сохраняет прежний raw-контракт | `test_git_worktree_perm::test_tc02_non_permission_error_keeps_prior_contract`, `test_tc02_killswitch_off_keeps_raw_contract_even_for_permission` | PASS |
+| TC-03 | `scan_ownership` на дереве с uid≠target → mismatch=True + корни | `test_fs_normalize::test_tc03_scan_detects_mismatch` | PASS |
+| TC-04 | `scan_ownership` на чистом дереве → mismatch=False (идемпотентно) | `test_fs_normalize::test_tc04_clean_tree_no_mismatch` | PASS |
+| TC-05 | never-raise при недоступном/несуществующем корне → WARNING | `test_fs_normalize::test_tc05_never_raise_on_missing_root`, `test_tc05_never_raise_on_walk_error` | PASS |
+| TC-06 | `applies(repo)`: пустой CSV → self-hosting only; непустой — по списку | `test_fs_normalize::test_tc06_applies_empty_csv_self_hosting_only`, `test_tc06_applies_explicit_csv` | PASS |
+| TC-07 | kill-switch OFF → scan/normalize инертны (1:1 как до ORCH-057) | `test_fs_normalize::test_tc07_killswitch_off_scan_inert`, `test_tc07_killswitch_off_normalize_inert` | PASS |
+| TC-08 | `normalize` без прав → no-op + честный лог, НЕ исключение | `test_fs_normalize::test_tc08_normalize_without_rights_is_noop_not_error` | PASS |
+| TC-09 | TTL-кэш: повтор в окне TTL не пере-сканирует; ключ по roots+uid | `test_fs_normalize::test_tc09_ttl_cache_avoids_rescan`, `test_tc09_cache_keyed_by_roots_and_uid` | PASS |
+| TC-10 | startup-хук: mismatch → send_telegram + WARNING; ошибка детекта never-fatal | `test_fs_normalize_startup::test_tc10_startup_mismatch_warns_and_telegrams`, `test_tc10_startup_detect_error_never_fatal`, `test_tc10_startup_clean_no_telegram` | PASS |
+| TC-11 | гейт claim'а: mismatch без прав → внятный исход ДО launch, не сырой git-fatal | `test_fs_normalize_startup::test_tc11_launch_permission_failure_is_actionable_not_raw` | PASS |
+| TC-12 | `GET /queue` блок `fs_ownership` отдаёт поля и не 5xx-ит при выключенном флаге | `test_api_queue::test_tc12_queue_exposes_fs_ownership_block`, `test_tc12_queue_no_5xx_when_disabled`, `test_fs_normalize_check_endpoint` | PASS |
+
+Доп. целевые тесты (сверх плана, усиливают покрытие): `test_classify_worktree_error_markers`,
+`test_is_permission_failure_from_exc`, `test_snapshot_shape` — PASS.
+
+### Сопоставление с критериями приёмки (03-acceptance-criteria.md)
+| AC | Покрыто | Результат |
+|----|---------|-----------|
+| AC-1 — конвейер стартует без ручного chown / внятная блокирующая ошибка | TC-01, TC-11 | PASS |
+| AC-2 — `ensure_worktree` actionable-ошибка при отказе доступа, не-прав сохраняет контракт | TC-01, TC-02 | PASS |
+| AC-3 — детект несоответствия владельца (mismatch на грязной, no-op на чистой) | TC-03, TC-04, TC-05 | PASS |
+| AC-4 — наблюдаемость детекта (WARNING + Telegram + `GET /queue`) | TC-10, TC-12 | PASS |
+| AC-5 — self-hosting безопасность, нулевая регрессия enduro, зелёный регресс | TC-06, TC-07, TC-08 + 1507 passed | PASS |
+| AC-6 — инварианты конвейера (STAGE_TRANSITIONS/QG_CHECKS/check_*/machine-key/схема БД) | полный регресс зелёный, guard-тесты пройдены | PASS |
+| AC-7 — документированная процедура нормализации (INFRA.md + ADR) | проверено reviewer (12-review.md), вне scope pytest | PASS (док.) |
+
+## Вывод pytest
+```
+============================= test session starts ==============================
+platform linux -- Python 3.12.13, pytest-8.3.3, pluggy-1.6.0
+rootdir: /repos/_wt/orchestrator/feature_ORCH-057-bug-follow-up-orch-040-normali
+plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8
+collected 25 items  (профильные сюиты)
+... 25 passed, 1 warning in 2.19s
+
+Полный регресс:
+1507 passed, 1 warning in 52.22s
+```
+
+## Итог
+**PASS** — все 12 TC выполнены и сопоставлены с тест-планом и критериями приёмки; профильные
+сюиты 25 passed; полный регресс 1507 passed; smoke (`/health`, `/status`, `/queue` c блоками
+`serial_gate` + `auto_labels`) — зелёный. Задача переходит на `deploy-staging`.

docs/work-items/ORCH-057/14-deploy-log.md

@@ -0,0 +1,12 @@
+---
+deploy_status: SUCCESS
+work_item: ORCH-057
+hook_exit_code: 0
+deployed_by: deploy-finalizer
+---
+
+# Deploy log — ORCH-036 executable self-deploy
+
+Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

src/config.py

@@ -291,6 +291,33 @@ class Settings(BaseSettings):
     coverage_tool_fail_closed: bool = False
     coverage_run_timeout_s: int = 900
 
+    # ORCH-057: legacy root-owned file ownership detect + actionable worktree error
+    # (follow-up ORCH-040). Three additive, kill-switch-reversible layers: (1) an
+    # actionable RuntimeError in git_worktree.ensure_worktree when a worktree fails
+    # to be created because of legacy root-owned files (Permission denied), (2) a
+    # cheap, TTL-cached, never-raise detect leaf src/fs_normalize.py that finds files
+    # with uid != target_uid across the infra roots (/repos/_wt, <repo>/.git, data/runs)
+    # and surfaces a startup WARNING/Telegram + GET /queue fs_ownership block, (3) an
+    # opt-in chown (normalize) ONLY when the process has CAP_CHOWN/root (under uid 1000
+    # a no-op + honest log; the real fix is the operator procedure in INFRA.md). No
+    # STAGE_TRANSITIONS / QG_CHECKS / check_* / machine-verdict / schema change. See
+    # ADR-001-legacy-ownership-normalization.md / adr-0031.
+    #   fs_normalize_enabled   -> SINGLE kill-switch; False -> all code inert, behaviour
+    #                             1:1 as before ORCH-057 (the actionable error too).
+    #                             Env ORCH_FS_NORMALIZE_ENABLED.
+    #   fs_normalize_repos     -> CSV of repos the layer is REAL for; empty -> only the
+    #                             self-hosting repo (orchestrator). Mirrors coverage_gate_repos.
+    #   fs_target_uid          -> target uid fallback when os.getuid() is unavailable.
+    #   fs_normalize_auto      -> detect-only (False) | attempt chown when privileged (True).
+    #   fs_scan_roots          -> CSV override of the scan roots (empty -> default roots).
+    #   fs_scan_cache_ttl_s    -> TTL of the detect cache (mirrors preflight_cache_ttl).
+    fs_normalize_enabled: bool = True
+    fs_normalize_repos: str = ""
+    fs_target_uid: int = 1000
+    fs_normalize_auto: bool = False
+    fs_scan_roots: str = ""
+    fs_scan_cache_ttl_s: int = 300
+
     # ORCH-061: tolerate KNOWN sandbox-infra FAILs (C9a/C9b) in the staging suite.
     # The self-hosting deploy-staging stage looped because scripts/staging_check.py
     # exited non-zero on ANY failed check, so two infra-only failures (sandbox bot

src/fs_normalize.py

@@ -0,0 +1,539 @@
+"""Legacy root-owned ownership detect + actionable worktree error (ORCH-057).
+
+Background
+----------
+ORCH-040 moved both containers to ``user: "1000:1000"`` by editing ONLY
+``docker-compose.yml``. Changing ``user:`` does NOT change the owner of files that
+the previous root container already created. The bind-mount ``/home/slin/repos ->
+/repos`` therefore still held ``root:root`` directories (``_wt/``, old worktrees,
+``.git/objects``, ``data/runs``). Under uid 1000 (no root) ``git_worktree.
+ensure_worktree`` could not create a worktree next to a ``root:root`` ``/repos/_wt``
+and failed with a RAW ``fatal: could not create leading directories … Permission
+denied`` — the agent never started and the operator had no diagnosis.
+
+The container runs as numeric uid 1000 WITHOUT root, so it physically cannot
+``chown`` foreign (root-owned) files — only DETECT + DIAGNOSE. The real fix is the
+documented operator procedure (INFRA.md «Миграция uid»), run once on the host.
+
+This leaf (ADR-001) provides three additive, kill-switch-reversible primitives:
+
+  * ``classify_worktree_error`` / ``build_worktree_help`` — the pure classifier +
+    actionable message used by ``git_worktree.ensure_worktree`` (D1 / FR-1).
+  * ``scan_ownership`` — a cheap, TTL-cached, never-raise walk of the infra roots
+    that reports whether any file has ``uid != target_uid`` (D2 / FR-2), used by the
+    startup hook (D3 / FR-3) and the ``GET /queue`` ``fs_ownership`` block.
+  * ``normalize`` — an opt-in ``chown`` that runs ONLY when the process is
+    privileged (root / CAP_CHOWN); under uid 1000 it is a no-op + honest log, NOT
+    an error (D4 / FR-4).
+
+Invariants (never broken):
+  * **never-raise** (NFR-3): every public function degrades to a conservative,
+    non-blocking default and NEVER propagates into the worker / lifespan / worktree
+    path. A detect error -> WARNING + ``mismatch=False`` (do not block / panic).
+  * **applies() first** (NFR-2): the expensive walk runs only when the layer is REAL
+    for the repo (``fs_normalize_enabled`` + scope; empty CSV -> self-hosting only),
+    so enduro-trails is never scanned at the default config.
+  * **kill-switch reversible** (D6): ``fs_normalize_enabled=False`` -> all code inert,
+    behaviour 1:1 as before ORCH-057 (the actionable error contract too).
+  * **no chown without privilege** (NFR-1): the code only reads / detects / diagnoses;
+    a real ``chown`` happens only when privileged and ``fs_normalize_auto=True``.
+
+Leaf: imports only ``config`` / ``logging`` / ``os`` / ``time`` (+ lazily
+``qg.checks.is_self_hosting_repo`` / ``notifications`` for scope / observability). It
+never imports ``git_worktree`` / ``stage_engine`` / ``launcher`` (``git_worktree``
+imports THIS module, so the dependency is one-way).
+"""
+from __future__ import annotations
+
+import errno
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+
+from .config import settings
+
+logger = logging.getLogger("orchestrator.fs_normalize")
+
+# Permission-class markers in a git stderr / OSError string (D1 / TR-1). Narrow on
+# purpose — a non-permission error (real branch conflict, missing origin/main,
+# timeout) must NOT be reclassified (AC-2 FAIL-condition), so we match only the
+# unambiguous "no permission to create the file/object" phrases.
+_PERM_MARKERS = (
+    "permission denied",
+    "could not create leading directories",
+    "insufficient permission for adding an object",
+    "operation not permitted",
+)
+
+
+# ---------------------------------------------------------------------------
+# Resolution helpers (target uid, scope, roots)
+# ---------------------------------------------------------------------------
+def _resolve_target_uid(target_uid: int | None = None) -> int:
+    """The uid the scan compares against (the subject that "cannot create files").
+
+    Resolution order (D2 / TR-7): explicit ``target_uid`` arg > ``os.getuid()`` (the
+    uid the process really runs as) > ``settings.fs_target_uid`` fallback (default
+    1000) when ``os.getuid()`` is unavailable. Never raises.
+    """
+    if target_uid is not None:
+        return int(target_uid)
+    try:
+        return os.getuid()
+    except (AttributeError, OSError):  # pragma: no cover - non-POSIX fallback
+        try:
+            return int(settings.fs_target_uid)
+        except (TypeError, ValueError):
+            return 1000
+
+
+def _scope_repos() -> list[str]:
+    """Repos the layer is REAL for (used to build the default ``.git`` roots).
+
+    Non-empty ``fs_normalize_repos`` CSV -> those repos; empty -> self-hosting only
+    (``orchestrator``), mirroring ``coverage_gate``. Never raises -> [] on error.
+    """
+    try:
+        raw = (settings.fs_normalize_repos or "").strip()
+    except Exception:  # noqa: BLE001 - never-raise
+        return []
+    if raw:
+        return [r.strip() for r in raw.split(",") if r.strip()]
+    try:
+        from .qg.checks import SELF_HOSTING_REPO
+        return [SELF_HOSTING_REPO]
+    except Exception:  # noqa: BLE001
+        return ["orchestrator"]
+
+
+def _runs_root() -> str:
+    """``data/runs`` root (per ADR: ``os.path.dirname(db_path)/runs``)."""
+    try:
+        rd = getattr(settings, "runs_dir", None)
+        if rd:
+            return rd
+    except Exception:  # noqa: BLE001
+        pass
+    try:
+        return os.path.join(os.path.dirname(settings.db_path), "runs")
+    except Exception:  # noqa: BLE001
+        return "/app/data/runs"
+
+
+def _default_roots() -> list[str]:
+    """The default scan roots (D2): ``/repos/_wt``, ``data/runs`` and each in-scope
+    repo's ``.git/objects`` + ``.git/worktrees``. Never raises -> [] on error.
+    """
+    roots: list[str] = []
+    try:
+        wt = getattr(settings, "worktrees_dir", None)
+        if wt:
+            roots.append(wt)
+        roots.append(_runs_root())
+        repos_dir = getattr(settings, "repos_dir", "/repos")
+        for repo in _scope_repos():
+            base = os.path.join(repos_dir, repo, ".git")
+            roots.append(os.path.join(base, "objects"))
+            roots.append(os.path.join(base, "worktrees"))
+    except Exception as e:  # noqa: BLE001 - never-raise
+        logger.warning("fs_normalize._default_roots error: %s", e)
+    return roots
+
+
+def _resolve_roots(roots: list[str] | None = None) -> list[str]:
+    """Resolve scan roots: explicit arg > ``fs_scan_roots`` CSV > the default set."""
+    if roots is not None:
+        return list(roots)
+    try:
+        raw = (settings.fs_scan_roots or "").strip()
+    except Exception:  # noqa: BLE001
+        raw = ""
+    if raw:
+        return [r.strip() for r in raw.split(",") if r.strip()]
+    return _default_roots()
+
+
+# ---------------------------------------------------------------------------
+# Conditionality (mirrors coverage_gate_applies)
+# ---------------------------------------------------------------------------
+def applies(repo: str) -> bool:
+    """Whether the ORCH-057 layer is REAL for this repo (D6 / NFR-2).
+
+      * ``fs_normalize_enabled=False`` -> always False (kill-switch).
+      * ``fs_normalize_repos`` (CSV) non-empty -> real only for the listed repos.
+      * empty CSV -> real ONLY for the self-hosting repo (``orchestrator``).
+    Never raises -> False (the safe no-op default).
+    """
+    try:
+        if not settings.fs_normalize_enabled:
+            return False
+        raw = (settings.fs_normalize_repos or "").strip()
+        if raw:
+            allowed = {r.strip().lower() for r in raw.split(",") if r.strip()}
+            return (repo or "").strip().lower() in allowed
+        from .qg.checks import is_self_hosting_repo
+        return is_self_hosting_repo(repo)
+    except Exception as e:  # noqa: BLE001 - never-raise contract
+        logger.warning("fs_normalize.applies error for %s: %s", repo, e)
+        return False
+
+
+# ---------------------------------------------------------------------------
+# D1: actionable worktree error (pure classifier + message)
+# ---------------------------------------------------------------------------
+def classify_worktree_error(text: str | None) -> bool:
+    """Pure: True iff ``text`` looks like a "no permission to create" failure.
+
+    Matches only the narrow ``_PERM_MARKERS`` so a non-permission git error keeps
+    its original contract (AC-2). Never raises -> False on bad input.
+    """
+    try:
+        t = (text or "").lower()
+        return any(m in t for m in _PERM_MARKERS)
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def is_permission_failure(*, stderr: str | None = None, exc: BaseException | None = None) -> bool:
+    """True iff a worktree failure is the legacy-ownership permission class.
+
+    Considers both a git ``stderr`` string (marker match) and an ``OSError``
+    (``PermissionError`` or ``errno`` in ``EACCES``/``EPERM``). Never raises.
+    """
+    try:
+        if isinstance(exc, PermissionError):
+            return True
+        if isinstance(exc, OSError) and exc.errno in (errno.EACCES, errno.EPERM):
+            return True
+        if classify_worktree_error(stderr):
+            return True
+        if exc is not None and classify_worktree_error(str(exc)):
+            return True
+    except Exception:  # noqa: BLE001
+        return False
+    return False
+
+
+def build_worktree_help(repo: str, branch: str, target_uid: int | None = None, raw: str = "") -> str:
+    """Build the actionable RuntimeError message for a permission-class worktree
+    failure (D1): names the root cause + the healing command + the INFRA.md
+    procedure, instead of a raw git stderr (AC-2). Never raises.
+    """
+    try:
+        tuid = _resolve_target_uid(target_uid)
+        wt_dir = getattr(settings, "worktrees_dir", "/repos/_wt")
+        git_dir = os.path.join(getattr(settings, "repos_dir", "/repos"), repo, ".git")
+        msg = (
+            f"Cannot create git worktree for {repo}:{branch} — permission denied. "
+            f"Likely cause: legacy root-owned files in {wt_dir} or {git_dir} left over "
+            f"from before the uid migration (ORCH-040). This container runs as uid "
+            f"{tuid} without root and cannot chown foreign files itself. Fix (run once "
+            f"on the host as root): `sudo chown -R {tuid}:{tuid} {wt_dir}` and "
+            f"`sudo chown -R {tuid}:{tuid} {git_dir}`. See docs/operations/INFRA.md "
+            f"section «Миграция uid: обязательная нормализация legacy root-файлов»."
+        )
+        if raw:
+            msg += f" (underlying error: {raw.strip()})"
+        return msg
+    except Exception:  # noqa: BLE001 - never-raise; degrade to a minimal hint
+        return (
+            f"Cannot create git worktree for {repo}:{branch} — permission denied "
+            f"(legacy root-owned files; see docs/operations/INFRA.md «Миграция uid»)."
+        )
+
+
+# ---------------------------------------------------------------------------
+# D2: ownership scan (TTL-cached, never-raise, early-exit per root)
+# ---------------------------------------------------------------------------
+@dataclass
+class OwnershipScan:
+    """Result of an ownership scan (D2). ``mismatch`` is the boolean verdict."""
+
+    mismatch: bool
+    target_uid: int
+    roots_checked: list[str] = field(default_factory=list)
+    roots_mismatch: list[str] = field(default_factory=list)
+    sample_path: str | None = None
+    count: int | None = None
+    checked_at: float = 0.0
+    enabled: bool = True
+
+    def to_dict(self) -> dict:
+        return {
+            "enabled": self.enabled,
+            "mismatch": self.mismatch,
+            "target_uid": self.target_uid,
+            "roots_checked": self.roots_checked,
+            "roots_mismatch": self.roots_mismatch,
+            "sample_path": self.sample_path,
+            "count": self.count,
+            "checked_at": self.checked_at,
+        }
+
+
+class _ScanCache:
+    def __init__(self):
+        self.ts: float = 0.0
+        self.key: tuple | None = None
+        self.result: OwnershipScan | None = None
+
+
+_cache = _ScanCache()
+
+
+def reset_cache() -> None:
+    """Invalidate the TTL detect cache (tests / forced recheck)."""
+    _cache.ts = 0.0
+    _cache.key = None
+    _cache.result = None
+
+
+def _first_mismatch(root: str, target_uid: int) -> str | None:
+    """Return the first path under ``root`` whose ``st_uid != target_uid`` (early
+    exit), else None. ``os.lstat`` (not ``stat``) so a symlink's own ownership is
+    judged, never its target. Never raises -> None on any walk error.
+    """
+    try:
+        if not os.path.exists(root):
+            return None
+        try:
+            if os.lstat(root).st_uid != target_uid:
+                return root
+        except OSError:
+            return None
+        for dirpath, dirnames, filenames in os.walk(root, onerror=None):
+            for name in dirnames:
+                p = os.path.join(dirpath, name)
+                try:
+                    if os.lstat(p).st_uid != target_uid:
+                        return p
+                except OSError:
+                    continue
+            for name in filenames:
+                p = os.path.join(dirpath, name)
+                try:
+                    if os.lstat(p).st_uid != target_uid:
+                        return p
+                except OSError:
+                    continue
+    except Exception as e:  # noqa: BLE001 - never-raise
+        logger.warning("fs_normalize._first_mismatch error for %s: %s", root, e)
+        return None
+    return None
+
+
+def _scan(roots: list[str], target_uid: int) -> OwnershipScan:
+    """Walk each root, early-exiting per root at its first mismatch. The clean case
+    (no mismatch) walks fully; the dirty case stops fast per root (TR-2 cost). Lists
+    every affected root (informative verdict). Never raises -> conservative
+    ``mismatch=False`` on a wholesale error.
+    """
+    roots_checked: list[str] = []
+    roots_mismatch: list[str] = []
+    sample_path: str | None = None
+    try:
+        for root in roots:
+            if not os.path.exists(root):
+                continue
+            roots_checked.append(root)
+            hit = _first_mismatch(root, target_uid)
+            if hit is not None:
+                roots_mismatch.append(root)
+                if sample_path is None:
+                    sample_path = hit
+    except Exception as e:  # noqa: BLE001 - never-raise -> conservative verdict
+        logger.warning("fs_normalize._scan error -> mismatch=False: %s", e)
+        return OwnershipScan(
+            mismatch=False, target_uid=target_uid,
+            roots_checked=roots_checked, roots_mismatch=[], checked_at=time.time(),
+        )
+    return OwnershipScan(
+        mismatch=bool(roots_mismatch),
+        target_uid=target_uid,
+        roots_checked=roots_checked,
+        roots_mismatch=roots_mismatch,
+        sample_path=sample_path,
+        checked_at=time.time(),
+    )
+
+
+def scan_ownership(
+    roots: list[str] | None = None,
+    target_uid: int | None = None,
+    force: bool = False,
+) -> OwnershipScan:
+    """Detect files with ``uid != target_uid`` across the infra roots (D2 / FR-2).
+
+    TTL-cached (``fs_scan_cache_ttl_s``, mirrors ``preflight._cache``): a repeat call
+    inside the window with the SAME (roots, target_uid) returns the cached result
+    without re-walking; ``force=True`` (or ``reset_cache()``) re-scans. Kill-switch
+    off -> an inert ``mismatch=False`` result (``enabled=False``). Never raises.
+    """
+    try:
+        if not settings.fs_normalize_enabled:
+            return OwnershipScan(
+                mismatch=False, target_uid=_resolve_target_uid(target_uid),
+                checked_at=time.time(), enabled=False,
+            )
+        resolved_roots = _resolve_roots(roots)
+        tuid = _resolve_target_uid(target_uid)
+        key = (tuple(resolved_roots), tuid)
+        now = time.time()
+        try:
+            ttl = float(settings.fs_scan_cache_ttl_s)
+        except (TypeError, ValueError):
+            ttl = 300.0
+        if (
+            not force
+            and _cache.result is not None
+            and _cache.key == key
+            and (now - _cache.ts) < ttl
+        ):
+            return _cache.result
+        result = _scan(resolved_roots, tuid)
+        _cache.ts = now
+        _cache.key = key
+        _cache.result = result
+        return result
+    except Exception as e:  # noqa: BLE001 - never-raise -> conservative verdict
+        logger.warning("fs_normalize.scan_ownership error -> mismatch=False: %s", e)
+        return OwnershipScan(
+            mismatch=False, target_uid=_resolve_target_uid(target_uid),
+            checked_at=time.time(),
+        )
+
+
+# ---------------------------------------------------------------------------
+# D4: opt-in normalize (chown ONLY when privileged) — never init-container
+# ---------------------------------------------------------------------------
+def _is_privileged() -> bool:
+    """True iff the process can chown foreign files (root). Under uid 1000 -> False.
+
+    A practical check: ``os.geteuid() == 0``. A CAP_CHOWN-without-root environment
+    still degrades to the honest no-op (a chown attempt would simply fail and be
+    swallowed). Never raises -> False (the safe "not privileged" default).
+    """
+    try:
+        return os.geteuid() == 0
+    except (AttributeError, OSError):  # pragma: no cover - non-POSIX
+        return False
+
+
+def normalize(roots: list[str] | None = None, target_uid: int | None = None) -> dict:
+    """Opt-in ``chown -R target_uid:target_uid`` over the roots, ONLY when the
+    process is privileged (D4 / FR-4). Under uid 1000 (the prod-self case) it is a
+    no-op + honest log "operator procedure required" — NOT an error. Gated by
+    ``fs_normalize_auto`` at the call site; this function additionally self-guards on
+    ``_is_privileged()``. Never raises.
+
+    Returns a result dict ``{attempted, privileged, changed, errors, note}``.
+    """
+    result = {"attempted": False, "privileged": False, "changed": 0, "errors": [], "note": ""}
+    try:
+        if not settings.fs_normalize_enabled:
+            result["note"] = "disabled (fs_normalize_enabled=False)"
+            return result
+        tuid = _resolve_target_uid(target_uid)
+        privileged = _is_privileged()
+        result["privileged"] = privileged
+        if not privileged:
+            result["note"] = (
+                "not privileged (process runs as non-root) — chown of legacy "
+                "root-owned files needs the operator procedure (docs/operations/"
+                "INFRA.md «Миграция uid»)."
+            )
+            logger.warning("fs_normalize.normalize: %s", result["note"])
+            return result
+
+        result["attempted"] = True
+        resolved_roots = _resolve_roots(roots)
+        changed = 0
+        for root in resolved_roots:
+            if not os.path.exists(root):
+                continue
+            for path in _iter_paths(root):
+                try:
+                    if os.lstat(path).st_uid != tuid:
+                        os.chown(path, tuid, tuid, follow_symlinks=False)
+                        changed += 1
+                except OSError as e:
+                    result["errors"].append(f"{path}: {e}")
+        result["changed"] = changed
+        result["note"] = f"chown applied to {changed} path(s) over {len(resolved_roots)} root(s)"
+        logger.info("fs_normalize.normalize: %s", result["note"])
+        return result
+    except Exception as e:  # noqa: BLE001 - never-raise
+        logger.error("fs_normalize.normalize error: %s", e)
+        result["note"] = f"error: {e}"
+        return result
+
+
+def _iter_paths(root: str):
+    """Yield ``root`` and every path beneath it (never raises per item)."""
+    try:
+        yield root
+        for dirpath, dirnames, filenames in os.walk(root, onerror=None):
+            for name in dirnames + filenames:
+                yield os.path.join(dirpath, name)
+    except Exception as e:  # noqa: BLE001
+        logger.warning("fs_normalize._iter_paths error for %s: %s", root, e)
+
+
+# ---------------------------------------------------------------------------
+# Observability snapshot for GET /queue (D6 / AC-4)
+# ---------------------------------------------------------------------------
+def snapshot() -> dict:
+    """Read-only ownership summary for GET /queue (``fs_ownership`` block, AC-4).
+
+    Additive; uses the TTL-cached scan (no expensive walk on every /queue hit).
+    never-raise: any error -> a minimal dict carrying the flags.
+    """
+    try:
+        enabled = bool(settings.fs_normalize_enabled)
+    except Exception:  # noqa: BLE001
+        enabled = False
+    try:
+        auto = bool(getattr(settings, "fs_normalize_auto", False))
+    except Exception:  # noqa: BLE001
+        auto = False
+    try:
+        repos_cfg = getattr(settings, "fs_normalize_repos", "") or ""
+    except Exception:  # noqa: BLE001
+        repos_cfg = ""
+    out = {
+        "enabled": enabled,
+        "auto": auto,
+        "repos": repos_cfg,
+        "target_uid": _resolve_target_uid(),
+        "mismatch": False,
+        "roots_checked": [],
+        "roots_mismatch": [],
+        "sample_path": None,
+        "checked_at": None,
+    }
+    try:
+        if enabled:
+            scan = scan_ownership()
+            out["mismatch"] = scan.mismatch
+            out["target_uid"] = scan.target_uid
+            out["roots_checked"] = scan.roots_checked
+            out["roots_mismatch"] = scan.roots_mismatch
+            out["sample_path"] = scan.sample_path
+            out["checked_at"] = scan.checked_at or None
+    except Exception as e:  # noqa: BLE001 - never-raise -> minimal dict
+        logger.warning("fs_normalize.snapshot error: %s", e)
+    return out
+
+
+def healing_command(target_uid: int | None = None) -> str:
+    """The one-line operator healing hint (startup WARNING / Telegram). Never raises."""
+    try:
+        tuid = _resolve_target_uid(target_uid)
+        wt_dir = getattr(settings, "worktrees_dir", "/repos/_wt")
+        return (
+            f"sudo chown -R {tuid}:{tuid} {wt_dir} <repo>/.git data/runs "
+            f"(см. docs/operations/INFRA.md «Миграция uid»)"
+        )
+    except Exception:  # noqa: BLE001
+        return "sudo chown -R 1000:1000 /repos/_wt (см. docs/operations/INFRA.md «Миграция uid»)"

src/git_worktree.py

@@ -39,6 +39,31 @@ def _main_repo(repo: str) -> str:
     return os.path.join(settings.repos_dir, repo)
 
 
+def _raise_if_permission(repo: str, branch: str, *, stderr: str | None = None,
+                         exc: BaseException | None = None) -> None:
+    """ORCH-057 D1: if a worktree failure is the legacy-ownership permission class,
+    raise an actionable ``RuntimeError`` (cause + healing command + INFRA.md ref)
+    instead of a raw git stderr (FR-1 / AC-2).
+
+    Gated by ``fs_normalize_enabled`` — when the kill-switch is off the error
+    contract is byte-for-byte as before ORCH-057 (this helper is a no-op, the caller
+    re-raises the original). A non-permission error is also a no-op here, so the
+    caller's existing message/semantics are preserved (no meaning substitution).
+    Never raises anything other than the deliberate actionable RuntimeError.
+    """
+    try:
+        if not settings.fs_normalize_enabled:
+            return
+        from . import fs_normalize
+        if fs_normalize.is_permission_failure(stderr=stderr, exc=exc):
+            raw = stderr if stderr is not None else (str(exc) if exc else "")
+            raise RuntimeError(fs_normalize.build_worktree_help(repo, branch, raw=raw))
+    except RuntimeError:
+        raise
+    except Exception as e:  # noqa: BLE001 - classification must never mask the real error
+        logger.warning("worktree permission-classification skipped: %s", e)
+
+
 def ensure_worktree(repo: str, branch: str) -> str:
     """Create (or reuse) an isolated worktree for ``branch``. Returns its path.
 
@@ -75,7 +100,14 @@ def ensure_worktree(repo: str, branch: str) -> str:
         logger.info(f"Worktree reused: {wt} (branch {branch})")
         return wt
 
-    os.makedirs(os.path.dirname(wt), exist_ok=True)
+    # ORCH-057 D1: creating the leading worktree directory next to a legacy
+    # root-owned /repos/_wt fails with Permission denied under uid 1000 — turn that
+    # into an actionable error (the kill-switch / non-permission path is unchanged).
+    try:
+        os.makedirs(os.path.dirname(wt), exist_ok=True)
+    except OSError as e:
+        _raise_if_permission(repo, branch, exc=e)
+        raise
 
     # Try to attach an existing branch (local or remote-tracking) to the new worktree.
     r = subprocess.run(["git", "-C", main_repo, "worktree", "add", wt, branch],
@@ -87,9 +119,12 @@ def ensure_worktree(repo: str, branch: str) -> str:
             capture_output=True, text=True, timeout=60,
         )
         if r2.returncode != 0:
+            combined = f"{r.stderr.strip()} | {r2.stderr.strip()}"
+            # ORCH-057 D1: a permission-class git fatal -> actionable RuntimeError;
+            # any other failure keeps the prior raw-stderr contract (AC-2).
+            _raise_if_permission(repo, branch, stderr=combined)
             raise RuntimeError(
-                f"git worktree add failed for {repo}:{branch}: "
-                f"{r.stderr.strip()} | {r2.stderr.strip()}"
+                f"git worktree add failed for {repo}:{branch}: {combined}"
             )
     logger.info(f"Worktree ready: {wt} (branch {branch})")
     return wt

src/main.py

@@ -89,6 +89,44 @@ async def lifespan(app: FastAPI):
     except Exception as e:
         log.warning(f"Log rotation skipped: {e}")
 
+    # ORCH-057 (D3 / FR-3): best-effort legacy-ownership detect. Surfaces a
+    # PROACTIVE operator signal (WARNING + Telegram) when /repos still holds
+    # root-owned files after the uid migration, BEFORE a task fails on launch.
+    # never-fatal (mirrors lease-reclaim / log-rotation above): a detect error must
+    # not crash the start of the shared instance. The actual "clear, early" failure
+    # is delivered by the actionable error in ensure_worktree (D1) — claim is NOT
+    # blocked (ADR-001 D3). Honours ORCH_FS_NORMALIZE_ENABLED inside scan_ownership.
+    try:
+        from .fs_normalize import scan_ownership, healing_command, normalize
+        from .config import settings as _fs_settings
+        scan = scan_ownership()
+        if scan.mismatch:
+            log.warning(
+                "FS-ownership mismatch: %d root(s) with files not owned by uid %s "
+                "(%s; sample: %s). Heal: %s",
+                len(scan.roots_mismatch), scan.target_uid,
+                ", ".join(scan.roots_mismatch), scan.sample_path, healing_command(),
+            )
+            try:
+                from .notifications import send_telegram
+                send_telegram(
+                    "⚠️ Orchestrator: обнаружены legacy root-owned файлы в "
+                    f"{', '.join(scan.roots_mismatch)} (uid != {scan.target_uid}). "
+                    f"Первый запуск задачи может упасть на создании worktree. "
+                    f"Лечение: {healing_command()}"
+                )
+            except Exception:
+                pass
+            # D4 / FR-4: opt-in auto-chown ONLY when privileged (no-op under uid 1000).
+            if getattr(_fs_settings, "fs_normalize_auto", False):
+                try:
+                    res = normalize()
+                    log.warning("FS-ownership auto-normalize: %s", res.get("note"))
+                except Exception as e:  # noqa: BLE001
+                    log.warning("FS-ownership auto-normalize skipped: %s", e)
+    except Exception as e:
+        log.warning(f"FS-ownership detect skipped: {e}")
+
     # Start the background job-queue worker (ORCH-1).
     from .queue_worker import worker
     worker.start()
@@ -171,6 +209,7 @@ async def queue():
     from . import task_deps
     from . import serial_gate
     from . import coverage_gate
+    from . import fs_normalize
     from . import labels
     from . import cancel
     from .disk_watchdog import disk_watchdog
@@ -193,6 +232,10 @@ async def queue():
         # ORCH-027 (FR-7 / AC-9): coverage-gate observability (read-only) —
         # kill-switch, scope, policy/floor/epsilon, per-repo baselines. Additive block.
         "coverage": coverage_gate.snapshot(),
+        # ORCH-057 (D6 / AC-4): legacy-ownership detect observability (read-only) —
+        # kill-switch, scope, target_uid, mismatch + affected roots (TTL-cached scan).
+        # Additive block; never-raise.
+        "fs_ownership": fs_normalize.snapshot(),
         # ORCH-089 (D7): auto-mode-by-label observability (read-only) — kill-switch,
         # label names, scope. Additive block.
         "auto_labels": labels.snapshot(),
@@ -262,6 +305,26 @@ async def serial_gate_unfreeze(repo: str = ""):
     return {"ok": True, "repo": repo, "cleared": cleared, "frozen": frozen}
 
 
+@app.post("/fs-normalize/check")
+async def fs_normalize_check(normalize: bool = False):
+    """ORCH-057 (D6 / AC-4): force a fresh legacy-ownership detect (bypass the TTL
+    cache) and return the snapshot. By образцу ``POST /serial-gate/unfreeze``.
+
+    ``normalize=true`` additionally attempts an opt-in ``chown`` — a no-op under uid
+    1000 (the prod-self case), effective only when the process is privileged (D4).
+    The real fix remains the operator procedure (docs/operations/INFRA.md «Миграция
+    uid»). Read-only/never-raise otherwise.
+    """
+    from . import fs_normalize as _fs
+    scan = _fs.scan_ownership(force=True)
+    out = {"ok": True, "scan": scan.to_dict(), "healing": _fs.healing_command()}
+    if normalize:
+        out["normalize"] = _fs.normalize()
+        # Re-scan so the returned snapshot reflects any change a privileged run made.
+        out["scan"] = _fs.scan_ownership(force=True).to_dict()
+    return out
+
+
 @app.post("/coverage/baseline")
 async def coverage_set_baseline(repo: str = "", value: float | None = None):
     """ORCH-027 (D8): manually set/override the per-repo coverage baseline.

tests/test_api_queue.py

@@ -0,0 +1,68 @@
+"""ORCH-057 TC-12: GET /queue exposes the read-only fs_ownership block.
+
+The block carries {enabled, target_uid, mismatch, roots_checked, roots_mismatch,
+sample_path, checked_at, ...} and /queue must not 5xx whether the layer is on or off.
+"""
+import os
+import tempfile
+
+import pytest
+
+_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_apiq.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir()
+os.environ["ORCH_GITEA_TOKEN"] = "test-token"
+os.environ["ORCH_PLANE_API_TOKEN"] = "test-token"
+os.environ["ORCH_PLANE_WEBHOOK_SECRET"] = ""
+os.environ["ORCH_GITEA_WEBHOOK_SECRET"] = ""
+
+from fastapi.testclient import TestClient
+
+from src import fs_normalize
+from src.main import app
+from src.db import init_db
+
+client = TestClient(app)
+
+
+@pytest.fixture(autouse=True)
+def _db():
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+    init_db()
+    fs_normalize.reset_cache()
+    yield
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+
+
+def test_tc12_queue_exposes_fs_ownership_block(monkeypatch):
+    """TC-12: GET /queue returns the fs_ownership block with the documented shape."""
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_enabled", True)
+    r = client.get("/queue")
+    assert r.status_code == 200
+    body = r.json()
+    assert "fs_ownership" in body
+    block = body["fs_ownership"]
+    for k in ("enabled", "target_uid", "mismatch", "roots_checked",
+              "roots_mismatch", "sample_path", "checked_at"):
+        assert k in block
+
+
+def test_tc12_queue_no_5xx_when_disabled(monkeypatch):
+    """TC-12: with the kill-switch off /queue still returns 200 (no 5xx)."""
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_enabled", False)
+    fs_normalize.reset_cache()
+    r = client.get("/queue")
+    assert r.status_code == 200
+    assert r.json()["fs_ownership"]["enabled"] is False
+
+
+def test_fs_normalize_check_endpoint():
+    """The optional POST /fs-normalize/check force-rescans and returns the snapshot."""
+    r = client.post("/fs-normalize/check")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["ok"] is True
+    assert "scan" in body and "mismatch" in body["scan"]
+    assert "healing" in body

tests/test_fs_normalize.py

@@ -0,0 +1,214 @@
+"""ORCH-057 D2/D4/D6: ownership-detect leaf (src/fs_normalize.py) unit tests.
+
+TC-03..TC-09 (04-test-plan.yaml). All FS-dependent tests use ``tmp_path`` and vary
+``target_uid`` (a uid no tmp file actually has -> mismatch; the runner's own uid ->
+clean) so NO real chown / privilege is needed. ``os.geteuid`` is monkeypatched for
+the privilege-gated normalize test (TC-08). Never touches /repos.
+"""
+import os
+import tempfile
+
+import pytest
+
+_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_fsn.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir()
+os.environ["ORCH_GITEA_TOKEN"] = "test-token"
+os.environ["ORCH_PLANE_API_TOKEN"] = "test-token"
+
+from src import fs_normalize
+
+
+_NONEXISTENT_UID = 999999  # no tmp file is owned by this uid -> deterministic mismatch
+
+
+@pytest.fixture(autouse=True)
+def _reset(monkeypatch):
+    fs_normalize.reset_cache()
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_enabled", True)
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_repos", "")
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_auto", False)
+    monkeypatch.setattr(fs_normalize.settings, "fs_scan_cache_ttl_s", 300)
+    yield
+    fs_normalize.reset_cache()
+
+
+@pytest.fixture
+def tree(tmp_path):
+    """A small dir tree with a file, owned by the test runner's own uid."""
+    d = tmp_path / "root"
+    (d / "sub").mkdir(parents=True)
+    (d / "a.txt").write_text("a")
+    (d / "sub" / "b.txt").write_text("b")
+    return d
+
+
+# ---------------------------------------------------------------------------
+# TC-03 / TC-04 — scan verdict
+# ---------------------------------------------------------------------------
+def test_tc03_scan_detects_mismatch(tree):
+    """TC-03: a tree whose files are not owned by target_uid -> mismatch=True with the
+    affected root listed and a sample path set."""
+    scan = fs_normalize.scan_ownership(roots=[str(tree)], target_uid=_NONEXISTENT_UID)
+    assert scan.mismatch is True
+    assert str(tree) in scan.roots_mismatch
+    assert scan.sample_path is not None
+    assert scan.target_uid == _NONEXISTENT_UID
+
+
+def test_tc04_clean_tree_no_mismatch(tree):
+    """TC-04: a clean tree (all files owned by target_uid == the runner) -> idempotent
+    mismatch=False no-op."""
+    scan = fs_normalize.scan_ownership(roots=[str(tree)], target_uid=os.getuid())
+    assert scan.mismatch is False
+    assert scan.roots_mismatch == []
+    assert scan.sample_path is None
+
+
+# ---------------------------------------------------------------------------
+# TC-05 — never-raise on bad/missing root
+# ---------------------------------------------------------------------------
+def test_tc05_never_raise_on_missing_root(tmp_path):
+    """TC-05: a non-existent root degrades to mismatch=False, never raises."""
+    missing = str(tmp_path / "does-not-exist")
+    scan = fs_normalize.scan_ownership(roots=[missing], target_uid=_NONEXISTENT_UID)
+    assert scan.mismatch is False
+    assert scan.roots_checked == []  # the missing root is skipped
+
+
+def test_tc05_never_raise_on_walk_error(tree, monkeypatch):
+    """TC-05: an os.walk explosion mid-scan degrades to a conservative verdict."""
+    def boom(*a, **k):
+        raise OSError("simulated walk failure")
+
+    monkeypatch.setattr(fs_normalize.os, "walk", boom)
+    scan = fs_normalize.scan_ownership(roots=[str(tree)], target_uid=_NONEXISTENT_UID)
+    # The root dir itself is owned by the runner (not _NONEXISTENT_UID was checked via
+    # lstat which still works) -> walk error swallowed, no exception escapes.
+    assert isinstance(scan, fs_normalize.OwnershipScan)
+
+
+# ---------------------------------------------------------------------------
+# TC-06 — applies() scope
+# ---------------------------------------------------------------------------
+def test_tc06_applies_empty_csv_self_hosting_only(monkeypatch):
+    """TC-06: empty ORCH_FS_NORMALIZE_REPOS -> True only for the self-hosting repo
+    (orchestrator), False for enduro-trails."""
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_repos", "")
+    assert fs_normalize.applies("orchestrator") is True
+    assert fs_normalize.applies("enduro-trails") is False
+
+
+def test_tc06_applies_explicit_csv(monkeypatch):
+    """TC-06: a non-empty CSV scopes by list (case-insensitive)."""
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_repos", "enduro-trails")
+    assert fs_normalize.applies("enduro-trails") is True
+    assert fs_normalize.applies("orchestrator") is False
+
+
+# ---------------------------------------------------------------------------
+# TC-07 — kill-switch
+# ---------------------------------------------------------------------------
+def test_tc07_killswitch_off_scan_inert(tree, monkeypatch):
+    """TC-07: fs_normalize_enabled=False -> scan is inert (mismatch=False, enabled
+    flag exposes the off state); applies() False for everyone."""
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_enabled", False)
+    scan = fs_normalize.scan_ownership(roots=[str(tree)], target_uid=_NONEXISTENT_UID)
+    assert scan.mismatch is False
+    assert scan.enabled is False
+    assert fs_normalize.applies("orchestrator") is False
+
+
+def test_tc07_killswitch_off_normalize_inert(tree, monkeypatch):
+    """TC-07: normalize is a documented no-op when the kill-switch is off."""
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_enabled", False)
+    res = fs_normalize.normalize(roots=[str(tree)], target_uid=_NONEXISTENT_UID)
+    assert res["attempted"] is False
+    assert res["changed"] == 0
+    assert "disabled" in res["note"]
+
+
+# ---------------------------------------------------------------------------
+# TC-08 — normalize without privilege
+# ---------------------------------------------------------------------------
+def test_tc08_normalize_without_rights_is_noop_not_error(tree, monkeypatch):
+    """TC-08: under a non-root euid with auto=True and foreign files, normalize is a
+    no-op + honest log ('operator procedure required'), NOT an exception."""
+    monkeypatch.setattr(fs_normalize.settings, "fs_normalize_auto", True)
+    monkeypatch.setattr(fs_normalize.os, "geteuid", lambda: 1000)  # non-root
+    res = fs_normalize.normalize(roots=[str(tree)], target_uid=_NONEXISTENT_UID)
+    assert res["privileged"] is False
+    assert res["attempted"] is False
+    assert res["changed"] == 0
+    assert "INFRA.md" in res["note"]
+
+
+# ---------------------------------------------------------------------------
+# TC-09 — TTL cache
+# ---------------------------------------------------------------------------
+def test_tc09_ttl_cache_avoids_rescan(tree, monkeypatch):
+    """TC-09: a repeat call inside the TTL window does NOT re-walk; force/reset
+    invalidates (mirrors preflight._cache)."""
+    calls = {"n": 0}
+    real_scan = fs_normalize._scan
+
+    def counting_scan(roots, target_uid):
+        calls["n"] += 1
+        return real_scan(roots, target_uid)
+
+    monkeypatch.setattr(fs_normalize, "_scan", counting_scan)
+
+    fs_normalize.scan_ownership(roots=[str(tree)], target_uid=_NONEXISTENT_UID)
+    fs_normalize.scan_ownership(roots=[str(tree)], target_uid=_NONEXISTENT_UID)
+    assert calls["n"] == 1  # second call served from cache
+
+    fs_normalize.scan_ownership(roots=[str(tree)], target_uid=_NONEXISTENT_UID, force=True)
+    assert calls["n"] == 2  # force bypasses the cache
+
+    fs_normalize.reset_cache()
+    fs_normalize.scan_ownership(roots=[str(tree)], target_uid=_NONEXISTENT_UID)
+    assert calls["n"] == 3  # reset invalidates
+
+
+def test_tc09_cache_keyed_by_roots_and_uid(tree, monkeypatch):
+    """A different (roots, target_uid) key is not served from another key's cache."""
+    calls = {"n": 0}
+    real_scan = fs_normalize._scan
+
+    def counting_scan(roots, target_uid):
+        calls["n"] += 1
+        return real_scan(roots, target_uid)
+
+    monkeypatch.setattr(fs_normalize, "_scan", counting_scan)
+    fs_normalize.scan_ownership(roots=[str(tree)], target_uid=_NONEXISTENT_UID)
+    fs_normalize.scan_ownership(roots=[str(tree)], target_uid=os.getuid())  # different uid
+    assert calls["n"] == 2
+
+
+# ---------------------------------------------------------------------------
+# classifier (pure) + snapshot
+# ---------------------------------------------------------------------------
+def test_classify_worktree_error_markers():
+    assert fs_normalize.classify_worktree_error("fatal: ...: Permission denied") is True
+    assert fs_normalize.classify_worktree_error("could not create leading directories") is True
+    assert fs_normalize.classify_worktree_error("insufficient permission for adding an object") is True
+    assert fs_normalize.classify_worktree_error("fatal: branch already checked out") is False
+    assert fs_normalize.classify_worktree_error("") is False
+    assert fs_normalize.classify_worktree_error(None) is False
+
+
+def test_is_permission_failure_from_exc():
+    assert fs_normalize.is_permission_failure(exc=PermissionError(13, "denied")) is True
+    import errno as _errno
+    assert fs_normalize.is_permission_failure(exc=OSError(_errno.EACCES, "x")) is True
+    assert fs_normalize.is_permission_failure(exc=OSError(_errno.ENOENT, "x")) is False
+
+
+def test_snapshot_shape(tree, monkeypatch):
+    """snapshot() returns the additive fs_ownership block and never raises."""
+    monkeypatch.setattr(fs_normalize.settings, "fs_scan_roots", str(tree))
+    snap = fs_normalize.snapshot()
+    for k in ("enabled", "auto", "repos", "target_uid", "mismatch",
+              "roots_checked", "roots_mismatch", "sample_path", "checked_at"):
+        assert k in snap
+    assert snap["enabled"] is True

tests/test_fs_normalize_startup.py

@@ -0,0 +1,136 @@
+"""ORCH-057 D3: startup-hook observability + the clear pre-launch outcome.
+
+TC-10 / TC-11 (04-test-plan.yaml):
+  * TC-10 — the lifespan startup hook, on a detected mismatch, emits a WARNING and a
+    Telegram message; a detect error never crashes the start (never-fatal).
+  * TC-11 — the "clear, early" outcome on a permission failure is delivered by the
+    actionable ensure_worktree error (ADR-001 D3: claim is NOT blocked), i.e. the
+    launch surfaces an actionable diagnosis, never a raw git-fatal.
+
+Background daemons are disabled via env so the lifespan is cheap and deterministic.
+"""
+import os
+import tempfile
+
+import pytest
+
+_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_fsn_startup.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir()
+os.environ["ORCH_GITEA_TOKEN"] = "test-token"
+os.environ["ORCH_PLANE_API_TOKEN"] = "test-token"
+os.environ["ORCH_PLANE_WEBHOOK_SECRET"] = ""
+os.environ["ORCH_GITEA_WEBHOOK_SECRET"] = ""
+# Keep the lifespan light: no background daemons during the test.
+os.environ["ORCH_RECONCILE_ENABLED"] = "false"
+os.environ["ORCH_REAPER_ENABLED"] = "false"
+os.environ["ORCH_DISK_MONITOR_ENABLED"] = "false"
+os.environ["ORCH_BUILD_CACHE_PRUNE_ENABLED"] = "false"
+os.environ["ORCH_FS_NORMALIZE_ENABLED"] = "true"
+
+from fastapi.testclient import TestClient
+
+from src import fs_normalize, git_worktree
+from src.main import app
+from src.db import init_db
+
+
+@pytest.fixture(autouse=True)
+def _db():
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+    init_db()
+    fs_normalize.reset_cache()
+    yield
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+
+
+# ---------------------------------------------------------------------------
+# TC-10 — startup observability
+# ---------------------------------------------------------------------------
+def test_tc10_startup_mismatch_warns_and_telegrams(monkeypatch, caplog):
+    """TC-10: on a detected mismatch the startup hook logs a WARNING and sends a
+    Telegram message (mocked)."""
+    sent = []
+    monkeypatch.setattr(
+        "src.notifications.send_telegram", lambda *a, **k: sent.append(a[0] if a else "")
+    )
+    scan = fs_normalize.OwnershipScan(
+        mismatch=True, target_uid=1000, roots_checked=["/repos/_wt"],
+        roots_mismatch=["/repos/_wt"], sample_path="/repos/_wt/x", checked_at=1.0,
+    )
+    monkeypatch.setattr("src.fs_normalize.scan_ownership", lambda *a, **k: scan)
+
+    with caplog.at_level("WARNING"):
+        with TestClient(app):
+            pass
+
+    assert any("FS-ownership mismatch" in r.message for r in caplog.records)
+    # Filter for the fs-ownership message (the shared startup may emit other,
+    # unrelated Telegram traffic — e.g. a leftover task's tracker card).
+    fs_msgs = [m for m in sent if "legacy root-owned" in m.lower() or "chown" in m.lower()]
+    assert fs_msgs, "expected a Telegram message on mismatch"
+
+
+def test_tc10_startup_detect_error_never_fatal(monkeypatch):
+    """TC-10: a detect error must NOT crash the start (never-fatal)."""
+    def boom(*a, **k):
+        raise RuntimeError("simulated detect failure")
+
+    monkeypatch.setattr("src.fs_normalize.scan_ownership", boom)
+    # Entering/exiting the lifespan must not raise.
+    with TestClient(app):
+        pass
+
+
+def test_tc10_startup_clean_no_telegram(monkeypatch):
+    """A clean environment (no mismatch) sends no Telegram and does not warn."""
+    sent = []
+    monkeypatch.setattr(
+        "src.notifications.send_telegram", lambda *a, **k: sent.append(a[0] if a else "")
+    )
+    clean = fs_normalize.OwnershipScan(mismatch=False, target_uid=1000, checked_at=1.0)
+    monkeypatch.setattr("src.fs_normalize.scan_ownership", lambda *a, **k: clean)
+    with TestClient(app):
+        pass
+    # No fs-ownership message on a clean environment (unrelated startup Telegram
+    # traffic from a shared-DB leftover task is ignored).
+    fs_msgs = [m for m in sent if "legacy root-owned" in m.lower() or "обнаружены legacy" in m.lower()]
+    assert fs_msgs == []
+
+
+# ---------------------------------------------------------------------------
+# TC-11 — clear pre-launch outcome (D1, not a claim gate)
+# ---------------------------------------------------------------------------
+def test_tc11_launch_permission_failure_is_actionable_not_raw(tmp_path, monkeypatch):
+    """TC-11: the launch-time worktree creation surfaces an actionable error (clear,
+    before the agent spends a token), not a raw git-fatal — the ADR-001 D3 "внятно и
+    заранее" outcome that replaces a blocking claim gate."""
+    repo = "orchestrator"
+    repos_dir = tmp_path / "repos"
+    (repos_dir / repo).mkdir(parents=True)
+    monkeypatch.setattr(git_worktree.settings, "repos_dir", str(repos_dir))
+    monkeypatch.setattr(git_worktree.settings, "worktrees_dir", str(repos_dir / "_wt"))
+    monkeypatch.setattr(git_worktree.settings, "fs_normalize_enabled", True)
+
+    class _R:
+        def __init__(self, rc, err=""):
+            self.returncode = rc
+            self.stderr = err
+            self.stdout = ""
+
+    def fake_run(cmd, *a, **k):
+        if "fetch" in cmd:
+            return _R(0)
+        if "worktree" in cmd and "add" in cmd:
+            return _R(128, "fatal: ...: Permission denied")
+        return _R(0)
+
+    monkeypatch.setattr(git_worktree.subprocess, "run", fake_run)
+
+    with pytest.raises(RuntimeError) as ei:
+        git_worktree.ensure_worktree(repo, "feature/x")
+    msg = str(ei.value)
+    assert "INFRA.md" in msg and "chown" in msg.lower()
+    assert "git worktree add failed" not in msg  # not the raw passthrough

tests/test_git_worktree_perm.py

@@ -0,0 +1,139 @@
+"""ORCH-057 D1: actionable worktree error on a legacy-ownership permission failure.
+
+TC-01 / TC-02 (04-test-plan.yaml): a permission-class ``git worktree add`` /
+``os.makedirs`` failure must surface an actionable RuntimeError (cause + healing
+command + INFRA.md ref), while a NON-permission failure keeps the prior raw-stderr
+contract (no meaning substitution). No real chown / no writes to /repos — failures
+are simulated via monkeypatched ``subprocess.run`` / ``os.makedirs``.
+"""
+import os
+import tempfile
+
+import pytest
+
+_test_db = os.path.join(tempfile.gettempdir(), "test_orchestrator_wt_perm.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir()
+os.environ["ORCH_GITEA_TOKEN"] = "test-token"
+os.environ["ORCH_PLANE_API_TOKEN"] = "test-token"
+
+from src import git_worktree
+from src.git_worktree import ensure_worktree
+
+
+class _R:
+    """Minimal CompletedProcess stand-in."""
+
+    def __init__(self, returncode, stderr=""):
+        self.returncode = returncode
+        self.stderr = stderr
+        self.stdout = ""
+
+
+@pytest.fixture
+def main_repo(tmp_path, monkeypatch):
+    """A bare-minimum main clone dir so ensure_worktree gets past the existence check.
+
+    repos_dir/<repo> must be a directory; worktrees_dir points at a fresh tmp path.
+    The actual git calls are monkeypatched per-test.
+    """
+    repo = "orchestrator"
+    repos_dir = tmp_path / "repos"
+    (repos_dir / repo).mkdir(parents=True)
+    monkeypatch.setattr(git_worktree.settings, "repos_dir", str(repos_dir))
+    monkeypatch.setattr(git_worktree.settings, "worktrees_dir", str(tmp_path / "repos" / "_wt"))
+    monkeypatch.setattr(git_worktree.settings, "fs_normalize_enabled", True)
+    return repo
+
+
+def test_tc01_permission_git_fatal_becomes_actionable(main_repo, monkeypatch):
+    """TC-01: a git-fatal 'could not create leading directories / Permission denied'
+    raises an actionable RuntimeError (diagnosis + chown), not the raw git stderr."""
+    perm_stderr = (
+        "fatal: could not create leading directories of "
+        "'/repos/_wt/orchestrator/x': Permission denied"
+    )
+
+    def fake_run(cmd, *a, **k):
+        # fetch -> ok; worktree add (both forms) -> permission fatal.
+        if "fetch" in cmd:
+            return _R(0)
+        if "worktree" in cmd and "add" in cmd:
+            return _R(128, perm_stderr)
+        return _R(0)
+
+    monkeypatch.setattr(git_worktree.subprocess, "run", fake_run)
+
+    with pytest.raises(RuntimeError) as ei:
+        ensure_worktree(main_repo, "feature/x")
+    msg = str(ei.value)
+    # Actionable: names the cause + the healing command + the INFRA procedure...
+    assert "legacy root-owned" in msg.lower()
+    assert "chown" in msg.lower()
+    assert "INFRA.md" in msg
+    # ...and is NOT merely the raw "git worktree add failed" passthrough.
+    assert "git worktree add failed" not in msg
+
+
+def test_tc01_makedirs_permission_error_becomes_actionable(main_repo, monkeypatch):
+    """TC-01 (sibling path): a PermissionError from os.makedirs (creating the leading
+    worktree dir) is also turned into the actionable RuntimeError."""
+    def fake_run(cmd, *a, **k):
+        return _R(0)
+
+    monkeypatch.setattr(git_worktree.subprocess, "run", fake_run)
+
+    def boom(*a, **k):
+        raise PermissionError(13, "Permission denied")
+
+    monkeypatch.setattr(git_worktree.os, "makedirs", boom)
+
+    with pytest.raises(RuntimeError) as ei:
+        ensure_worktree(main_repo, "feature/x")
+    assert "chown" in str(ei.value).lower()
+    assert "legacy root-owned" in str(ei.value).lower()
+
+
+def test_tc02_non_permission_error_keeps_prior_contract(main_repo, monkeypatch):
+    """TC-02: a NON-permission failure (e.g. a real branch conflict) keeps the prior
+    raw-stderr 'git worktree add failed' message — no meaning substitution."""
+    conflict = "fatal: 'feature/x' is already checked out at '/repos/_wt/other'"
+
+    def fake_run(cmd, *a, **k):
+        if "fetch" in cmd:
+            return _R(0)
+        if "worktree" in cmd and "add" in cmd:
+            return _R(128, conflict)
+        return _R(0)
+
+    monkeypatch.setattr(git_worktree.subprocess, "run", fake_run)
+
+    with pytest.raises(RuntimeError) as ei:
+        ensure_worktree(main_repo, "feature/x")
+    msg = str(ei.value)
+    assert "git worktree add failed" in msg
+    assert "already checked out" in msg
+    # The actionable diagnosis must NOT be injected for a non-permission error.
+    assert "legacy root-owned" not in msg.lower()
+
+
+def test_tc02_killswitch_off_keeps_raw_contract_even_for_permission(main_repo, monkeypatch):
+    """Kill-switch off (fs_normalize_enabled=False) -> the error contract is byte-for-
+    byte as before ORCH-057 even for a permission failure (raw stderr passthrough)."""
+    monkeypatch.setattr(git_worktree.settings, "fs_normalize_enabled", False)
+    perm_stderr = "fatal: ...: Permission denied"
+
+    def fake_run(cmd, *a, **k):
+        if "fetch" in cmd:
+            return _R(0)
+        if "worktree" in cmd and "add" in cmd:
+            return _R(128, perm_stderr)
+        return _R(0)
+
+    monkeypatch.setattr(git_worktree.subprocess, "run", fake_run)
+
+    with pytest.raises(RuntimeError) as ei:
+        ensure_worktree(main_repo, "feature/x")
+    msg = str(ei.value)
+    assert "git worktree add failed" in msg
+    assert "legacy root-owned" not in msg.lower()