@7n/rules 1.0.0

package/scripts/lib/lint-surface/docs/tier-sampling-bench.md

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: tier-sampling-bench.mjs
+resource: npm/scripts/lib/lint-surface/tier-sampling-bench.mjs
+docgen:
+  crc: 87d81bc2
+  model: manual
+---
+
+## Огляд
+
+Модуль запускає реальний bench для experiment-only tier sampling поверх lint fix ladder. Він створює тимчасові git-fixtures, викликає `runAgentFix` через `runTierSamplingExperiment`, перевіряє результат deterministic detector-ом і записує JSON із підсумками clean/rescue/latency.
+
+## Поведінка
+
+Runner будує experiment ladder із `local-min`, `cloud-min`, `cloud-avg`, `cloud-max` за поточними env-моделями. Для кожної fixture/tier пари створюється окремий тимчасовий git repo, щоб write-guard `runAgentFix` мав git-root і щоб результати різних tier-ів не впливали один на одного.
+
+Для `cloud-min` і `cloud-avg` запускаються два sampling profiles: `conservative` і `exploratory`. Для `local-min` і `cloud-max` запускається один conservative candidate. Профіль потрапляє у rule text як інструкція до агента; success все одно визначає тільки injected detector.
+
+Після кожного tier-а runner пише progress JSONL у stdout. Наприкінці він записує повний JSON-result у `docs/specs/2026-06-30-lint-tier-sampling-consensus-results.json` або шлях із `--out`.
+
+A/B-прапорці Фази A run-harness: bench шанує той самий env-опт-ін, що й default-worker — `N_LLM_FIX_ANCHORED` (`1` — anchored-профіль на всіх тирах, `cloud` — лише не-local) — і додатково `N_LLM_FIX_BENCH_VERIFY=1`, який вмикає evidence-гейт A1 у worker-і бенча (verify = injected detector фікстури, фідбек провалу у ту саму сесію). Це дозволяє порівнювати baseline / anchored / verify конфігурації тим самим прогоном.
+CLI-запуск завершується після summary, щоб відкриті агентські handle-и не тримали процес живим після запису результату.
+
+## Публічний API
+
+- `runTierSamplingBench` — запускає bench, повертає об'єкт результату і пише JSON-файл.
+
+CLI-параметри:
+
+- `--out <path>` — шлях до JSON-result.
+- `--tier <a,b>` — звузити список tier-ів.
+- `--fixture <a,b>` — звузити список fixtures.
+
+## Гарантії поведінки
+
+- Не змінює production `runFixPipeline`.
+- Не пише у consumer repo: усі LLM edits відбуваються у temporary git-fixtures.
+- Judge/consensus не є oracle: detector є єдиним джерелом success.
+- Результат містить raw attempts, selected candidate і агреговану summary по tier-ах.

package/scripts/lib/lint-surface/docs/tier-sampling-experiment.md

@@ -0,0 +1,35 @@
+---
+type: JS Module
+title: tier-sampling-experiment.mjs
+resource: npm/scripts/lib/lint-surface/tier-sampling-experiment.mjs
+docgen:
+  crc: f6a46f92
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл слугує експериментальною обгорткою для перевірки процесу виправлення (lint fix ladder). Він моделює ізольовані потенційні рішення для певного рівня, відкочуючи робоче дерево до початкового стану S1 перед кожною спробою. Мета модуля — ізольовано протестувати кандидати, які пройшли автоматичне виявлення чистоти, щоб оцінити їхню цінність через механізм зворотного зв'язку.
+
+## Поведінка
+
+EXPERIMENT_TIER_ORDER визначає фіксований порядок експериментальних рівнів.
+buildExperimentLadder конструює список експериментальних етапів на основі наданих моделей для кожного tier.
+samplingProfilesForTier генерує список можливих профілів відбору для певного tier.
+chooseCleanCandidate вибирає найкращий кандидат серед усіх спроб, які пройшли перевірку на чистоту.
+runTierSamplingExperiment виконує послідовність випробувань (sampling) для заданого tier, тестуючи кандидатів, обираючи найкращого та застосовуючи його патч для фінальної перевірки.
+
+## Публічний API
+
+* EXPERIMENT_TIER_ORDER — Визначає пріоритетність випробувань (tiers).
+* buildExperimentLadder — Створює ієрархію для експериментів, не впливаючи на конфігурацію продакшену.
+* samplingProfilesForTier — Повідомляє про доступні варіанти збору зразків для конкретного рівня випробувань.
+* chooseCleanCandidate — Вибирає оптимальний варіант з усіх тестових спроб, базуючись на мінімальній кількості змін у файлах, розмірі патчу та латентності.
+* runTierSamplingExperiment — Проводить комплекс випробувань для одного рівня: для кожного варіанту повертається до початкового стану, запускається робочий процес, оцінюється якість, а при виборі — застосовується відповідний виправлення.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/scripts/lib/lint-surface/docs/types.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: types.mjs
+resource: npm/scripts/lib/lint-surface/types.mjs
+docgen:
+  crc: 4120f280
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+---
+
+## Огляд
+
+Цей модуль фіксує контракти `unified lint surface` (spec: docs/specs/2026-06-29-unified-lint-surface.md). Він описує спільні типи даних, необхідні для взаємодії між компонентами системи, які базуються на конфігурації `concern.json`. Контракт передбачає два основні ролі: функція `lint -> LintResult`, яка лише виявляє порушення (read-only), та централізований конвеєр виправлення (T0 + tier ladder). Всі типи визначені як `@typedef {import}` та слугують спільними для runner-а, detector-ів, T0-патернів та fix-worker-ів.
+
+## Поведінка
+
+1. Контекст для перевірки визначається через абсолютний шлях до коріня репозиторію, унікальний ідентифікатор правила та ідентифікатор concern-а. Додатково може вказуватися абсолютний шлях до каталогу concern-а або відносний перелік файлів для пофайлового запуску.
+2. Detector створює результат перевірки, який містить перелік виявлених порушень або технічних діагностик.
+3. Кожне порушення фіксується за унікальною комбінацією `ruleId`, `concernId` та стабільного коду причини. Для порушення вказується описовий текст, а також опціональні метадані, специфічні для concern-а.
+4. T0-патерн визначає, чи застосовний для групи порушень. Якщо патерн ідемпотентний та самодостатній, він може автоматично ініціювати виправлення без детального аналізу кожного порушення.
+5. Застосування T0-патерну генерує змінені файли. Ці зміни фіксуються через механізм `recordWrite` у контексті worker-а, який реєструється в центральному runner'і для забезпечення можливості відкату. Для записів, що є самодостатніми кінцевими станами (файлові доки зі свіжим CRC), контекст додатково надає опційний `recordDurableWrite` — такі файли переживають rollback провального rung-а й не входять у semantic-collateral veto.
+6. Fix-worker виконує виправлення на заданому рівні складності (tier). Контекст rung-а несе per-tier `timeoutMs` (ADR 260620-0556), який worker зобовʼязаний прокинути у свій LLM-виклик, щоб зависла сесія переривалась зсередини. Контекст також несе опційний evidence-гейт (Фаза A1 run-harness): `verify` — item-scoped canonical re-detect для петлі всередині рунга (НЕ заміна зовнішнього вердикту runner-а), та `verifyMax` — ліміт додаткових verify-ітерацій. Результатом є перелік абсолютних шляхів змінених файлів.
+7. Параметри перевірки можуть визначатися через `concern.json`, який вказує, чи повинна перевірка здійснюватися через виконуваний код (template) або через рего-інтерпретатор (rego).
+8. Режим запуску concern-а може бути встановлений як пофайловий для обробки кожного файлу окремо, або як повний для аналізу всього дерева.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/lint-surface/docs/violation-reporter.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: violation-reporter.mjs
+resource: npm/scripts/lib/lint-surface/violation-reporter.mjs
+docgen:
+  crc: b8010de2
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль є drop-in заміною для `createCheckReporter`, призначеною для міграції check-concern'ів у detector-и. Він ініціалізує спеціалізований репортер, який замість виведення статусу (pass/fail) накопичує об'єкти `LintViolation[]`. Після процесу перевірки, для визначення загального результату, повинен викликатися метод `reporter.result`, який повертає повний список зібраних порушень, на відміну від попередньої реалізації, що повертала `exit code`.
+
+## Поведінка
+
+1. Викликати функцію createViolationReporter, передаючи їй контекст concern-а.
+2. Функція створює об'єкт репортера, що накопичує об'єкти LintViolation.
+3. У разі успіху, викликаний метод pass не виконує жодних дій.
+4. У разі виявлення порушення, викликаний метод fail з повідомленням та необов'язковими опціями (string або object) додає об'єкт LintViolation до внутрішнього списку, використовуючи ID concern-а як причину за замовчуванням.
+5. Для отримання результату виконання, викликаний метод result повертає об'єкт, що містить список зібраних порушень.
+
+## Публічний API
+
+* createViolationReporter — інструмент для фіксації знайдених у коді помилок (порушень) та повернення загального результату перевірки.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/lint-surface/ladder.mjs

@@ -0,0 +1,92 @@
+/**
+ * Pure tier-ladder helpers для central fix-pipeline. Декопльовано від старого
+ * orchestrator.mjs (який видаляється на cutover). Логіка ескалації — спека
+ * 2026-06-19-fix-escalation-cascade + 2026-06-29-unified-lint-surface §Tier Ladder.
+ */
+import { env } from 'node:process'
+
+// Per-tier дефолти — ADR 260620-0556 (fail-fast escalation): локальний 4b-рунг
+// об'єктивно не закінчить важкий промпт за хвилини (curl 28), хмарний SSE без
+// таймауту здатен висіти годинами на ESTABLISHED TCP — драбина має рухатись далі.
+//
+// Override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`:
+// мілісекунди на ОДИН rung відповідного класу (local-min/local-min-retry та
+// cloud-min/cloud-avg). Значення потрапляє worker-у як `ctx.timeoutMs` (внутрішній
+// abort LLM-виклику; batch-worker-и, як doc-files, ріжуть під нього беклог м'яким
+// дедлайном), а runner додатково тримає backstop ×1.25 навколо всього worker-виклику.
+// Робочий важіль для повільної локальної моделі чи великої черги batch-концерну:
+// підняти локальний таймаут понад вартість одного файлу. Невалідне значення
+// (NaN/0/порожньо) → дефолт.
+const LOCAL_TIMEOUT_MS = Number(env.N_LOCAL_FIX_TIMEOUT_MS) || 45_000
+const CLOUD_TIMEOUT_MS = Number(env.N_CLOUD_FIX_TIMEOUT_MS) || 120_000
+
+/** Дефолтний кеп на виклики cloud-avg за прогін (щоб ladder на N concern-ів не спалив avg). */
+export const DEFAULT_MAX_AVG = 3
+
+/** Реальний транспорт-збій провайдера (мережа/сокет) — НЕ агентний backstop-timeout. */
+const TRANSPORT_RE = /etimedout|timed out|econnrefused|connection refused/i
+
+/** Systemic — повтор тієї ж моделі марний (нема git, fail-closed guard, відсутня модель, auth). */
+const SYSTEMIC_RE = /не git-репо|fail-closed|write-guard|модель не знайдена|registry:|session:|немає ключа|api key/i
+
+/** Агентний backstop-timeout worker-а — класифікуємо як quality (ladder ескалює, не обриває). */
+const FIX_TIMEOUT_RE = /^fix timeout /i
+
+/**
+ * @typedef {object} Rung
+ * @property {'local-min'|'local-min-retry'|'cloud-min'|'cloud-avg'} tier назва тиру сходинки.
+ * @property {string} model ідентифікатор моделі для цього rung-а.
+ * @property {boolean} feedback використати feedback попереднього rung-а.
+ * @property {boolean} local чи це локальний (не cloud) rung.
+ * @property {boolean} isAvg під avg-кепом.
+ * @property {number} timeoutMs таймаут виклику rung-а в мс.
+ */
+
+/**
+ * Будує ladder за наявними тирами; rung-и з порожнім model відсіюються.
+ * @param {{ localMin: string, cloudMin: string, cloudAvg: string }} models моделі по тирах.
+ * @returns {Rung[]} відфільтрований список rung-ів для ескалації.
+ */
+export function buildLadder({ localMin, cloudMin, cloudAvg }) {
+  return [
+    { tier: 'local-min', model: localMin, feedback: false, local: true, isAvg: false, timeoutMs: LOCAL_TIMEOUT_MS },
+    {
+      tier: 'local-min-retry',
+      model: localMin,
+      feedback: true,
+      local: true,
+      isAvg: false,
+      timeoutMs: LOCAL_TIMEOUT_MS
+    },
+    { tier: 'cloud-min', model: cloudMin, feedback: true, local: false, isAvg: false, timeoutMs: CLOUD_TIMEOUT_MS },
+    { tier: 'cloud-avg', model: cloudAvg, feedback: true, local: false, isAvg: true, timeoutMs: CLOUD_TIMEOUT_MS }
+  ].filter(r => r.model)
+}
+
+/**
+ * Класифікує помилку worker-а: systemic | transport | quality.
+ * Агентний backstop-timeout → quality (ladder падає на сильніший rung, не обрив).
+ * @param {string|null|undefined} error текст помилки worker-а.
+ * @returns {'systemic'|'transport'|'quality'|null} категорія помилки або null якщо помилки нема.
+ */
+export function classifyFixError(error) {
+  if (!error) return null
+  if (FIX_TIMEOUT_RE.test(error)) return 'quality'
+  if (SYSTEMIC_RE.test(error)) return 'systemic'
+  if (TRANSPORT_RE.test(error)) return 'transport'
+  return 'quality'
+}
+
+/**
+ * Рішення після провального rung-а: обірвати ladder / пропустити модель.
+ * @param {Rung} rung rung, що провалився.
+ * @param {string|null|undefined} error текст помилки worker-а.
+ * @returns {'break'|'skip-model'|null} рішення про ескалацію або null для продовження.
+ */
+export function decideAfterFailure(rung, error) {
+  if (!error) return null
+  const kind = classifyFixError(error)
+  if (kind === 'systemic') return rung.local ? 'skip-model' : 'break'
+  if (!rung.local && kind === 'transport') return 'break'
+  return null
+}

package/scripts/lib/lint-surface/lint-lock.mjs

@@ -0,0 +1,247 @@
+/**
+ * Глобальна черга запусків `n-rules lint --full`: у кожен момент на машині
+ * виконується щонайбільше один **full**-прогін, наступні чекають у черзі й
+ * стартують після звільнення лока. Рішення spec-дискусії 2026-07-03 (ревізія):
+ * лок береться **лише** на `--full` — дельта/scoped/`--no-fix` запуски короткі
+ * й ідуть без черги; довгі whole-tree прогони серіалізуються та отримують
+ * видимість: процес у черзі показує свою позицію, решту черги і живий
+ * прогрес-бар активного прогону (читає його зі стан-файлу).
+ * `hook --post-tool-use` лок не бере: read-only, per-file, відповідає миттєво.
+ *
+ * Механіка — наявний {@link withLock} (mkdir-лок, перехоплення лока мертвого PID,
+ * poll-черга, TTL-дедуплікація за fingerprint) з відмінностями від per-rule
+ * використання (`run-standard-lint.mjs`):
+ *   - `cacheDir` у `os.tmpdir()` замість `<git-common-dir>` → скоуп machine-wide
+ *     (на macOS tmpdir per-user), а не per-repo;
+ *   - fingerprint дедуплікації домішує варіант виклику (rules/`--no-fix`/cwd) до
+ *     знімка дерева — інакше scoped-успіх хибно пропускав би ширший прогін;
+ *   - `staleThreshold` піднято до 6 год: дефолтні 30 хв «перехоплювали» б живий
+ *     лок довгого прогону; краші покриває PID-перевірка;
+ *   - `waitTimeout` 45 хв (full-прогони довгі), далі fail-closed (Error, exit 1),
+ *     а не дефолтний `run-unlocked` — мовчазний паралельний запуск це саме те,
+ *     що черга має унеможливити.
+ *
+ * Спільний стан у `GLOBAL_CACHE_DIR`:
+ *   - `lock/owner.json` — власник лока (пише withLock; pid/cwd/startedAt);
+ *   - `queue/<enqueuedAt>-<pid>.json` — реєстрація процесів у черзі (для списку);
+ *   - `progress.json` — знімок прогресу активного прогону (пише publisher
+ *     через `createProgressReporter({ onUpdate })`, читають процеси в черзі).
+ */
+import { createHash } from 'node:crypto'
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+import { isPidAlive, withLock } from '../../utils/with-lock.mjs'
+import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
+import { renderProgressLine } from './progress.mjs'
+
+/** Machine-wide директорія стану лока/черги — спільна для всіх репо й worktree. */
+export const GLOBAL_CACHE_DIR = join(tmpdir(), 'n-rules', 'lint-full')
+
+const QUEUE_DIR = join(GLOBAL_CACHE_DIR, 'queue')
+const PROGRESS_FILE = join(GLOBAL_CACHE_DIR, 'progress.json')
+
+/** Дедлайн очікування в черзі: full-прогони довгі, 20 хв дефолту withLock замало. */
+const WAIT_TIMEOUT_MS = 45 * 60_000
+
+/** Поріг time-based staleness (див. модульний коментар). */
+const STALE_THRESHOLD_MS = 6 * 3_600_000
+
+/** Мінімальний інтервал між записами progress.json (не молотити диск на кожен tick). */
+const PUBLISH_MIN_INTERVAL_MS = 500
+
+/** Інтервал append-рядків черги в не-TTY режимі (CI/пайпи). */
+const NON_TTY_WAIT_LOG_INTERVAL_MS = 10_000
+
+/** Знімок прогресу вважається живим, якщо оновлювався не давніше за це. */
+const PROGRESS_FRESH_MS = 60_000
+
+/**
+ * Fingerprint для TTL-дедуплікації: стан робочого дерева + варіант виклику lint.
+ * null (→ дедуплікація вимкнена, черга працює) коли:
+ *   - не в git-репо (worktreeFingerprint дасть null);
+ *   - `--cwd` вказує не на процесний cwd — git-команди fingerprint-а виконуються
+ *     у `process.cwd()`, тож знімок відповідав би не тому дереву, що лінтиться.
+ * @param {{cwd: string, full: boolean, rules: string[], noFix: boolean}} variant осі виклику lint
+ * @param {() => string | null} [getTreeFp] знімок дерева (ін'єкція для тестів)
+ * @returns {string | null} sha256-hex або null, якщо дедуп не можна застосувати
+ */
+export function lintLockFingerprint(variant, getTreeFp = worktreeFingerprint) {
+  if (variant.cwd !== processCwd()) return null
+  const treeFp = getTreeFp()
+  if (treeFp === null) return null
+  const axes = { cwd: variant.cwd, full: variant.full, noFix: variant.noFix, rules: [...variant.rules].toSorted() }
+  return createHash('sha256')
+    .update(`${treeFp}\n${JSON.stringify(axes)}`)
+    .digest('hex')
+}
+
+/**
+ * Publisher прогресу активного прогону: приймає знімки від
+ * `createProgressReporter({ onUpdate })` і (throttled) пише їх у стан-файл,
+ * звідки процеси в черзі читають прогрес-бар активного прогону.
+ * @param {{file?: string, minIntervalMs?: number}} [opts] override-и для тестів
+ * @returns {{ onUpdate: (snap: { done: number, total: number, found: number, fixed: number, current: string }) => void, stop: () => void }} publisher
+ */
+export function createProgressPublisher(opts = {}) {
+  const file = opts.file ?? PROGRESS_FILE
+  const minIntervalMs = opts.minIntervalMs ?? PUBLISH_MIN_INTERVAL_MS
+  let lastWriteAt = 0
+  return {
+    onUpdate: snap => {
+      const now = Date.now()
+      if (now - lastWriteAt < minIntervalMs) return
+      lastWriteAt = now
+      try {
+        mkdirSync(dirname(file), { recursive: true })
+        writeFileSync(file, JSON.stringify({ pid: process.pid, updatedAt: now, cwd: processCwd(), ...snap }))
+      } catch {
+        // best-effort: без стан-файлу процеси в черзі просто не побачать бар
+      }
+    },
+    stop: () => {
+      try {
+        rmSync(file, { force: true })
+      } catch {
+        // best-effort: застарілий файл відфільтрує PROGRESS_FRESH_MS/pid-перевірка
+      }
+    }
+  }
+}
+
+/**
+ * Список живих учасників черги у порядку постановки. Записи мертвих PID
+ * прибираються по дорозі (best-effort).
+ * @param {string} queueDir директорія реєстрацій черги
+ * @returns {Array<{ pid: number, cwd: string, enqueuedAt: number }>} черга
+ */
+function listQueue(queueDir) {
+  /** @type {Array<{ pid: number, cwd: string, enqueuedAt: number }>} */
+  const entries = []
+  let names
+  try {
+    names = readdirSync(queueDir)
+  } catch {
+    return entries
+  }
+  for (const name of names) {
+    const path = join(queueDir, name)
+    try {
+      const entry = JSON.parse(readFileSync(path, 'utf8'))
+      if (typeof entry?.pid === 'number' && isPidAlive(entry.pid)) {
+        entries.push(entry)
+      } else {
+        rmSync(path, { force: true })
+      }
+    } catch {
+      rmSync(path, { force: true })
+    }
+  }
+  return entries.toSorted((a, b) => a.enqueuedAt - b.enqueuedAt)
+}
+
+/**
+ * Читає знімок прогресу активного прогону; null, якщо файла нема, він
+ * застарілий або належить не поточному власнику лока.
+ * @param {number} ownerPid PID власника лока
+ * @param {string} progressFile шлях стан-файлу прогресу
+ * @returns {{ done: number, total: number, found: number, fixed: number, current: string } | null} знімок
+ */
+function readOwnerProgress(ownerPid, progressFile) {
+  try {
+    const snap = JSON.parse(readFileSync(progressFile, 'utf8'))
+    if (snap?.pid !== ownerPid) return null
+    if (Date.now() - snap.updatedAt > PROGRESS_FRESH_MS) return null
+    return snap
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Рядок стану черги для процесу, що стоїть у черзі: позиція, хто працює (pid + тека),
+ * прогрес-бар власника і перелік решти черги.
+ * @param {{ pid: number, cwd?: string }} owner власник лока (owner.json)
+ * @param {Array<{ pid: number, cwd: string }>} queue живі учасники черги (у порядку постановки)
+ * @param {{ done: number, total: number, found: number, fixed: number, current: string } | null} snap знімок прогресу власника
+ * @returns {string} однорядковий стан черги (без завершального \n)
+ */
+export function renderWaitLine(owner, queue, snap) {
+  const myIdx = queue.findIndex(e => e.pid === process.pid)
+  const pos = (myIdx === -1 ? queue.length : myIdx) + 1
+  const ownerDir = owner.cwd ? ` (${basename(owner.cwd)})` : ''
+  const bar = snap ? ` · ${renderProgressLine(snap)}` : ''
+  const others = queue
+    .filter(e => e.pid !== process.pid)
+    .map(e => `pid ${e.pid} (${basename(e.cwd)})`)
+    .join(', ')
+  const tail = others ? ` · чекають: ${others}` : ''
+  return `⏳ lint --full у черзі #${pos}/${Math.max(queue.length, pos)} · працює pid ${owner.pid}${ownerDir}${bar}${tail}`
+}
+
+/**
+ * UI очікування для хуків withLock: реєструє процес у черзі, на кожен tick
+ * рендерить рядок стану (TTY — перемальовування одного рядка на stderr;
+ * не-TTY — append раз на {@link NON_TTY_WAIT_LOG_INTERVAL_MS}), по завершенню
+ * прибирає реєстрацію і чистить рядок.
+ * @param {{ isTTY?: boolean, log?: (s: string) => void, queueDir?: string, progressFile?: string }} [opts] override-и для тестів
+ * @returns {{ onWaitStart: (owner: object) => void, onWaitTick: (owner: object) => void, onWaitEnd: () => void }} хуки
+ */
+function createWaitUi(opts = {}) {
+  const isTTY = opts.isTTY ?? process.stderr.isTTY === true
+  const log = opts.log ?? (s => process.stderr.write(s))
+  const queueDir = opts.queueDir ?? QUEUE_DIR
+  const progressFile = opts.progressFile ?? PROGRESS_FILE
+  const queueFile = join(queueDir, `${Date.now()}-${process.pid}.json`)
+  let lastAppendAt = 0
+
+  return {
+    onWaitStart: () => {
+      try {
+        mkdirSync(queueDir, { recursive: true })
+        writeFileSync(queueFile, JSON.stringify({ pid: process.pid, cwd: processCwd(), enqueuedAt: Date.now() }))
+      } catch {
+        // best-effort: без реєстрації процес просто не видно у списку черги
+      }
+    },
+    onWaitTick: owner => {
+      const line = renderWaitLine(owner, listQueue(queueDir), readOwnerProgress(owner.pid, progressFile))
+      if (isTTY) {
+        // \r + ANSI clear-line: один рядок, що перемальовується на кожен tick
+        log(`\r\u{1B}[2K${line}`)
+      } else if (Date.now() - lastAppendAt >= NON_TTY_WAIT_LOG_INTERVAL_MS) {
+        lastAppendAt = Date.now()
+        log(`${line}\n`)
+      }
+    },
+    onWaitEnd: () => {
+      rmSync(queueFile, { force: true })
+      if (isTTY) log('\r\u{1B}[2K')
+    }
+  }
+}
+
+/**
+ * Виконує `runFn` під глобальним локом full-прогонів. Не-full варіанти
+ * (дельта/scoped/`--no-fix`) виконуються одразу, без лока й черги.
+ * @param {{cwd: string, full: boolean, rules: string[], noFix: boolean}} variant осі виклику lint
+ * @param {() => number | Promise<number>} runFn реальна робота lint; повертає exit code
+ * @param {{ttl?: number, staleThreshold?: number, waitTimeout?: number, pollInterval?: number, cacheDir?: string, getFingerprint?: () => string | null, isTTY?: boolean, log?: (s: string) => void, queueDir?: string, progressFile?: string}} [opts] override-и `withLock`/UI (для тестів)
+ * @returns {Promise<number>} exit code виконаного запуску (або 0 при дедуплікації)
+ */
+export function withGlobalLintLock(variant, runFn, opts = {}) {
+  if (!variant.full) return Promise.resolve(runFn())
+  const { isTTY, log, queueDir, progressFile, ...lockOpts } = opts
+  const ui = createWaitUi({ isTTY, log, queueDir, progressFile })
+  return withLock('lint-full', runFn, {
+    cacheDir: GLOBAL_CACHE_DIR,
+    staleThreshold: STALE_THRESHOLD_MS,
+    waitTimeout: WAIT_TIMEOUT_MS,
+    onWaitTimeout: 'fail',
+    getFingerprint: () => lintLockFingerprint(variant),
+    ...ui,
+    ...lockOpts
+  })
+}