@nitra/cursor 12.15.1 → 12.16.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [12.16.1] - 2026-06-26
+
+### Changed
+
+- docs(skill-meta): уточнено опис tier — абстрактна тира (capability), не провайдер; кожна каскадить local→cloud
+
+## [12.16.0] - 2026-06-26
+
+### Added
+
+- feat: skills-cli pi-runner + pi-agent-skill — надбудова skills-CLI поверх pi
+
+### Changed
+
+- feat: pi-native agentic fix-engine — міграція з omlx на pi (squash)
+
 ## [12.15.1] - 2026-06-26
 
 ### Changed

package/bin/n-cursor.js

@@ -1544,7 +1544,7 @@ try {
       break
     }
     case 'skill': {
-      process.exitCode = runSkillsCli(args)
+      process.exitCode = await runSkillsCli(args)
 
       break
     }

package/lib/docs/index.md

@@ -6,9 +6,12 @@ resource: npm/lib/
 
 # npm/lib
 
-| Файл                            | Тип       |
-| ------------------------------- | --------- |
-| [llm.mjs](llm.md)               | JS Module |
-| [models.mjs](models.md)         | JS Module |
-| [omlx-trace.mjs](omlx-trace.md) | JS Module |
-| [omlx.mjs](omlx.md)             | JS Module |
+| Файл                                            | Тип       |
+| ----------------------------------------------- | --------- |
+| [pi-agent-fix.mjs](pi-agent-fix.md)             | JS Module |
+| [pi-agent-skill.mjs](pi-agent-skill.md)         | JS Module |
+| [pi-model-tiers.mjs](pi-model-tiers.md)         | JS Module |
+| [pi-one-shot.mjs](pi-one-shot.md)               | JS Module |
+| [pi-telemetry-store.mjs](pi-telemetry-store.md) | JS Module |
+| [pi-trace.mjs](pi-trace.md)                     | JS Module |
+| [pi-write-guard.mjs](pi-write-guard.md)         | JS Module |

package/lib/docs/pi-agent-fix.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: pi-agent-fix.mjs
+resource: npm/lib/pi-agent-fix.mjs
+docgen:
+  crc: 4cf083e2
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Файл надає інструментарій для автоматизованого виправлення кодів згідно з визначеними правилами. За допомогою функції `buildFixPrompt` формується деталізований запит для агента, що містить опис порушення та відповідне правило. Далі, `runPiAgentFix` ініціює процес застосування виправлень у проєкті. Цей процес реалізовано з механізмом безпеки (fail-safe), що гарантує відсутність винятків на виході.
+
+## Поведінка
+
+Поведінка:
+buildFixPrompt створює текстовий опис завдання для агента, інформуючи про виявлене порушення правила, надаючи текст самого правила та звіт про попередні невдачі.
+runPiAgentFix запускає цикл виправлення з використанням агентної сесії, застосовуючи патч у файли проєкту, управляючи безпекою змін, збираючи телеметрію та повертаючи результат виконання.
+
+## Публічний API
+
+buildFixPrompt — Створює деталізований запит для автоматичного виправлення, включаючи оригінальне правило, описане порушення та можливий відгук щодо попередніх невдач. Додає в інструкцію вимогу попереднього аналізу AST та самоперевірки після редагування.
+runPiAgentFix — Ініціює єдину спробу автоматичного виправлення (руна) з використанням AI-агента, передаючи йому деталі, такі як модель, рівень пріоритету, відгук, викликаючий агент та інші конфігураційні параметри.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/lib/docs/pi-agent-skill.md

@@ -0,0 +1,36 @@
+---
+type: JS Module
+title: pi-agent-skill.mjs
+resource: npm/lib/pi-agent-skill.mjs
+docgen:
+  crc: 2c9fe32d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Виконує один скіл `@nitra/cursor` як вбудованого pi-агента через публічну функцію `runPiAgentSkill`: подає готовий промпт у сесію, де агент сам **читає, редагує й створює файли та виконує shell-команди** (`bash`) у робочому каталозі. Це повний user-trust (паритет із ручним `claude -p`) — write-guard не накладається, бо скіл запускає користувач явно. Модель береться з однієї тири (`min`/`avg`/`max`, дефолт `max`). Будь-яка помилка перехоплюється (fail-safe) і повертається у результаті, а не кидається назовні.
+
+## Поведінка
+
+1. Ініціалізація сесії агента: Визначає конфігурацію агента на основі вказаних параметрів, включаючи обраний рівень моделі, робочу директорію та рівень обчислення.
+2. Виконання скілу: Запускає агентну сесію з поданим промптом.
+3. Обробка відповідей: Під час виконання скілу, відповіді асистента виводяться у стандартний потік виводу.
+4. Моніторинг: Відстежується кількість ітерацій та викликів інструментів.
+5. Захист від нескінченності: Застосовується механізм обмеження кількості ітерацій (`TURN_CEILING`) та загального тайм-ауту для запобігання зависанню.
+6. Обробка збоїв: У разі виникнення помилки під час ініціалізації, конфігурації або виконання, вона фіксується, а функція повертає стан невдачі.
+7. Фіналізація: Після завершення виконання (успішно або через таймаут/переповнення ліміту) збирається телеметрія, яка включає статистику сесії, і результат повертається у вигляді об'єкта з інформацією про успішність.
+
+## Публічний API
+
+runPiAgentSkill — Викликає певний агентський функціонал (скіл) через платформу pi з визначеними параметрами складності та обмеженнями виконання.
+
+## Гарантії поведінки
+
+- Повний user-trust: агент має read/edit/write/bash і мутує проєкт у робочому каталозі (без write-guard).
+- Runaway-backstop: перевищення стелі ітерацій (`N_CURSOR_SKILL_TURN_CEILING`) або таймауту (`N_CURSOR_SKILL_TIMEOUT_MS`) обриває сесію.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe); повертає `{ ok, telemetry, error }`.
+- Pi вантажиться lazy (тверда межа CI — модуль pi-free до першого виклику).

package/lib/docs/pi-model-tiers.md

@@ -0,0 +1,46 @@
+---
+type: JS Module
+title: pi-model-tiers.mjs
+resource: npm/lib/pi-model-tiers.mjs
+docgen:
+  crc: 05b8d5cd
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей модуль відповідає за конфігурацію та забезпечення доступу до моделей, спираючись на дані з `models.json` та `auth.json`. Він надає параметри для локальних (`LOCAL_MIN` по `LOCAL_MAX`) та хмарних (`CLOUD_MIN` по `CLOUD_MAX`) моделей, а також реалізує логіку для визначення відповідного рівня мислення за заданим тиром. Основна функція полягає в ініціалізації глобального реєстру моделей (`getRegistry`) та розпізнаванні специфікаторів за допомогою `parseModelId`.
+
+## Поведінка
+
+Поведінка:
+LOCAL_MIN — надає конфігураційне значення для мінімальної локальної моделі.
+LOCAL_AVG — надає конфігураційне значення для середньої локальної моделі.
+LOCAL_MAX — надає конфігураційне значення для максимальної локальної моделі.
+CLOUD_MIN — надає конфігураційне значення для мінімальної хмарної моделі.
+CLOUD_AVG — надає конфігураційне значення для середньої хмарної моделі.
+CLOUD_MAX — надає конфігураційне значення для максимальної хмарної моделі.
+resolveModel — визначає шлях до моделі на основі вибраного рівня (min, avg, max) за каскадною політикою.
+thinkingLevelForTier — визначає відповідний дискретний рівень мислення залежно від rung-тиру моделі.
+parseModelId — розбиває специфікатор моделі у форматі `"provider/model-id"` на окремі частини.
+resolveModelSpec — знаходить об'єкт моделі у регістра через наданий специфікатор, використовуючи інжектований registry.
+getRegistry — асинхронно ініціалізує та повертає екземпляр `ModelRegistry` з конфігурацій `models.json` та `auth.json`.
+
+## Публічний API
+
+LOCAL_MIN — Забезпечує швидке виконання моделей без використання хмарних сервісів.
+LOCAL_AVG — Надає середні можливості локальних моделей для виконання завдань.
+LOCAL_MAX — Дозволяє використовувати найпотужніші доступні локальні моделі.
+CLOUD_MIN — Забезпечує мінімальний рівень продуктивності від хмарних моделей, вимагає підключення через `pi auth`.
+CLOUD_AVG — Використовує середній за можливостями хмарний двигун.
+CLOUD_MAX — Дозволяє отримати максимальну якість від хмарних моделей.
+resolveModel — Визначає найкращу модель для виконання, обираючи між локальними та хмарними варіантами залежно від запитуваного рівня (`min`, `avg`, `max`).
+thinkingLevelForTier — Призначає відповідний рівень обробки (`low`, `medium`, `high`) на основі обраного рівня моделі для коректної роботи з пам'яттю та ресурсами.
+parseModelId — Розбирає загальний рядок ідентифікатора моделі у дві частини: назву постачальника та його ідентифікатор.
+resolveModelSpec — Перетворює текстовий рядок ідентифікатора моделі у структурований об'єкт, який використовується всіма компонентами системи.
+getRegistry — Зберігає ідентифікаторів та специфікацій усіх доступних моделей у єдиній кешованій довіднику.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/lib/docs/pi-one-shot.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: pi-one-shot.mjs
+resource: npm/lib/pi-one-shot.mjs
+docgen:
+  crc: d69067a3
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей механізм виконує одноразовий запит до мовної моделі (LLM) через публічну функцію `runOneShot`. Він збирає необхідну інформацію, ініціює взаємодію та консолідує вхідні дані у єдиний текстовий запит. Функція завжди перехоплює помилки (fail-safe) та не кидає винятків назовні. У разі успішного отримання відповіді від LLM, що є операцією лише для читання (read-only), повертається згенерований текст, дані про використання моделі та метадані.
+
+## Поведінка
+
+Поведінка:
+
+1. Для виконання одноразового LLM-виклику спочатку збирається необхідна інформація для доступу до моделі, використовуючи надані рівні моделі.
+2. Після визначення моделі створюється сесія для взаємодії з LLM, використовуючи налаштування, які гарантують виконання завдання без використання інструментів.
+3. Всі вхідні повідомлення об'єднуються в єдиний текстовий запит.
+4. Система чекає відповіді від LLM, обмеженої заданим часовим лімітом.
+5. Під час очікування відбувається збір генерованого тексту та метаданих об'єднання (usage) відповіді.
+6. У разі будь-якої помилки під час пошуку моделі, створення сесії чи самого виклику, виклик завершується з повідомленням про помилку.
+7. У разі успіху, функція повертає згенерований текст, інформацію про використання моделі, статус помилки та метадані моделі, використовуючи інформацію, зібрану під час взаємодії з сесією.
+
+## Публічний API
+
+- runOneShot — виконує обмежений LLM-виклик одноразово.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/lib/docs/pi-telemetry-store.md

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: pi-telemetry-store.mjs
+resource: npm/lib/pi-telemetry-store.mjs
+docgen:
+  crc: e6ec7d6c
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей модуль керує життєвим циклом та записом даних телеметрії. Він надає функції для визначення директорії телеметрії, генерації унікального ідентифікатора запису, реєстрації виправлень телеметрії та зчитування кількості відкритих записів. Система функціонує з механізмом безпечного перехоплення помилок, не генеруючи винятків. При виникненні певних збоїв модуль може повертати пусте значення замість викидання помилки.
+
+## Поведінка
+
+Поведінка:
+telemetryDir визначає базовий шлях для зберігання глобальних даних телеметрії.
+signatureOf створює унікальний короткий хеш для запису, що представляє структурну сутність правок.
+recordFixTelemetry додає або оновлює запис про спробу виправлення у глобальному сторі, обробляючи потенційні секрети та повтори.
+openCount підраховує кількість відкритих записів для заданого правила у телеметричному сторі.
+
+## Публічний API
+
+telemetryDir — вказує на директорію, де зберігаються дані телеметрії, яку можна перевизначити через змінну середовища `N_CURSOR_TELEMETRY_DIR`.
+signatureOf — генерує унікальний ідентифікатор для збереження змін, поєднуючи назву правила та структуру внесених правок.
+recordFixTelemetry — записує або згортає одну спробу виправлення у сховище даних телеметрії, ніколи не викликаючи помилку.
+openCount — фіксує кількість активних записів, пов'язаних із певним правилом, що допомагає визначити поріг для дистиляційного аналізу.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/lib/docs/pi-trace.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: pi-trace.mjs
+resource: npm/lib/pi-trace.mjs
+docgen:
+  crc: da5862a0
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей модуль реалізує механізм фіксації шляхів трасування для процесів LLM. Він надає функції `tracePath` для ініціалізації трасування шляху та `writeTrace` для додавання нових записів до глобального трасування. Механізм розроблено з принципом fail-safe, що гарантує стабільність роботи, перехоплюючи будь-які помилки файлової системи без генерації винятків.
+
+## Поведінка
+
+tracePath визначає повний шлях до глобального файлу трасування LLM, використовуючи змінну оточення `N_CURSOR_TRACE_PATH` або шлях за замовчуванням у домашньому каталозі.
+writeTrace додає новий запис трасування у файл, забезпечуючи створення необхідних директорій, але при цьому ігнорує будь-які помилки введення/виведення для забезпечення стійкості виклику LLM.
+
+## Публічний API
+
+tracePath — Вказує на розташування глобального трасувального файлу.
+writeTrace — Записує окремий запис трасування у форматі JSONL.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/lib/docs/pi-write-guard.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: pi-write-guard.mjs
+resource: npm/lib/pi-write-guard.mjs
+docgen:
+  crc: d18851b6
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль забезпечує безпечну взаємодію з файловою системою в межах структури Git-репозиторію. Він визначає кореневу директорію Git-репозиторію, створює механізм захисту від запису та відстежує нові файли для підтримки механізму відкату змін.
+
+Функція NEW_FILE фіксує шляхи до нових файлів у системі, що допомагає коректно керувати їхнім станом під час відкату змін. Функція gitRoot встановлює директорію кореня Git-репозиторію, виходячи з поточної робочої директорії. Механізм createWriteGuard запобігає несанкціонованим змінам файлів, перехоплюючи спроби модифікації та ігноруючи директорії, такі як .git, гарантуючи при цьому безпечний вихід із будь-яких помилок.
+
+## Поведінка
+
+NEW_FILE — Фіксує, що файл, якого до запису ще не існувало, позначається для подальшого видалення при відкаті.
+gitRoot — Визначає кореневу директорію Git-репозиторію, починаючи з поточної робочої директорії, або повертає null, якщо репозиторій не виявлено.
+createWriteGuard — Створює захист від запису, який перехоплює спроби агентів модифікувати файли, перевіряючи їхню область дії відносно git-репозиторію, запобігаючи запису у `.git/` та ігнорованих файлів, а також зберігаючи попередній стан файлів перед їх зміною.
+
+## Публічний API
+
+NEW_FILE — Позначає ціль, яку слід відновити, якщо файл не існував до спроби запису.
+gitRoot — Визначає кореневу директорію Git-репозиторію поточного робочого каталогу; дорівнює null, якщо це не Git-репозиторій.
+createWriteGuard — Створює захист від запису для однієї сесії виправлення, що включає визначення поточного робочого каталогу, кореня Git, та механізм для тестування.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.git`.

package/lib/pi-agent-fix.mjs

@@ -0,0 +1,253 @@
+/** @see ./docs/pi-agent-fix.md */
+
+/**
+ * Agentic fix-worker поверх pi `createAgentSession` (§1/§2/§5/§12 спеки pi-migration).
+ *
+ * Замінює `llm-worker.runLlmWorker` (`{changes}`+`applyChanges`) на агентний цикл, де
+ * pi сам читає контекст і **застосовує патч** вбудованими `edit`/`write`. Інтегрує:
+ *   - тири → Model ([pi-model-tiers]),
+ *   - write-safety §12 ([pi-write-guard]) через `DefaultResourceLoader` + **fail-closed canary**,
+ *   - custom-tools `ast_facts` (§3б) і `self_check` (§4+5, advisory),
+ *   - turn-ceiling backstop (`session.abort()` на перевищенні),
+ *   - телеметрію §7 (turns/tool-calls/повні edits) у [pi-trace].
+ *
+ * Контракт (application-agnostic seam §2): повертає `{ applied, touchedFiles, telemetry,
+ * error, rollback }` — застосуванням володіє worker, orchestrator робить лише зовнішній
+ * verdict-recheck і за провалу кличе `rollback()` (clean-slate per rung).
+ *
+ * Pi вантажиться lazy (тверда межа CI). Логіка інжектована через `deps` для unit-тестів.
+ */
+
+import { env } from 'node:process'
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+import { getRegistry, resolveModelSpec, thinkingLevelForTier } from './pi-model-tiers.mjs'
+import { createWriteGuard, gitRoot } from './pi-write-guard.mjs'
+import { writeTrace } from './pi-trace.mjs'
+import { extractContext } from '../scripts/utils/ast-extract.mjs'
+
+/** Аварійна стеля turns на одну сесію (runaway-backstop §4+5). Override: `N_CURSOR_FIX_TURN_CEILING`. */
+const TURN_CEILING = Number(env.N_CURSOR_FIX_TURN_CEILING) || 50
+
+/**
+ * Будує fix-промпт для рунга: правило + порушення + (опц.) feedback попереднього провалу
+ * + інструкція «ast_facts перед edit, self_check після».
+ * @param {{ ruleId: string, violation: string, ruleText?: string, feedback?: object }} args
+ * @returns {string} промпт
+ */
+export function buildFixPrompt({ ruleId, violation, ruleText, feedback }) {
+  const parts = [`Виправ порушення правила "${ruleId}" у цьому проєкті.`]
+  if (ruleText) parts.push(`## Правило\n${ruleText}`)
+  parts.push(`## Порушення\n${violation}`)
+  if (feedback?.previousError) {
+    parts.push(`## Попередня спроба не спрацювала\n${feedback.previousError}\nСпробуй інший підхід.`)
+  }
+  parts.push(
+    'Перед редагуванням JS/TS-файлу спершу виклич `ast_facts` на ньому. ' +
+      'Після правок виклич `self_check`, щоб підтвердити, що порушення зникло. ' +
+      'Редагуй лише потрібне, не чіпай стороннє.'
+  )
+  return parts.join('\n\n')
+}
+
+/** Гонка з таймаутом; на таймаут кличе `onTimeout` (abort) і реджектить. */
+function withTimeout(promise, ms, onTimeout) {
+  if (!ms || ms <= 0) return promise
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      onTimeout?.()
+      reject(new Error(`fix timeout ${ms}ms`))
+    }, ms)
+  })
+  return Promise.race([Promise.resolve(promise).finally(() => clearTimeout(timer)), timeout])
+}
+
+/**
+ * Дефолтна фабрика pi-сесії: loader із write-guard, custom-tools ast_facts+self_check.
+ * @returns {Promise<object>} pi AgentSession
+ */
+async function defaultCreateSession({ registry, model, thinkingLevel, cwd, factory, astContext, selfCheck }) {
+  const { createAgentSession, SessionManager, DefaultResourceLoader, SettingsManager, defineTool } =
+    await import('@earendil-works/pi-coding-agent')
+  const agentDir = `${homedir()}/.pi/agent`
+  const loader = new DefaultResourceLoader({
+    cwd,
+    agentDir,
+    settingsManager: SettingsManager.create(cwd, agentDir),
+    extensionFactories: [factory]
+  })
+  await loader.reload()
+
+  const astTool = defineTool({
+    name: 'ast_facts',
+    label: 'AST facts',
+    description:
+      'Extract structured AST facts (imports, exports, top-level functions) from a JS/TS source file. Call this before editing a file to understand it without reading the whole content.',
+    parameters: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'file path' } },
+      required: ['path']
+    },
+    execute: async (_id, { path }) => ({
+      content: [{ type: 'text', text: JSON.stringify(astContext(path)) }],
+      details: {}
+    })
+  })
+  const checkTool = defineTool({
+    name: 'self_check',
+    label: 'Self check',
+    description:
+      'Re-run the rule check on the given files to see whether the violation is resolved. Advisory: use it to decide if more edits are needed.',
+    parameters: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } }, required: [] },
+    execute: async (_id, { files }) => ({
+      content: [{ type: 'text', text: JSON.stringify(await selfCheck(files ?? [])) }],
+      details: {}
+    })
+  })
+
+  const { session } = await createAgentSession({
+    modelRegistry: registry,
+    model,
+    thinkingLevel,
+    cwd,
+    tools: ['read', 'grep', 'find', 'edit', 'write', 'ls', 'ast_facts', 'self_check'],
+    customTools: [astTool, checkTool],
+    sessionManager: SessionManager.inMemory(),
+    resourceLoader: loader
+  })
+  return session
+}
+
+/**
+ * Проводить ОДНУ агентну fix-спробу (рунг) для правила.
+ * @param {string} ruleId id правила
+ * @param {string} violation violation-output (вже з concern-маркерами §1а)
+ * @param {string} cwd корінь проєкту
+ * @param {{
+ *   model: string, tier?: string, feedback?: object, caller?: string, timeoutMs?: number, ruleText?: string,
+ *   deps?: { createSession?: Function, getRegistry?: Function, registry?: object, root?: string|null,
+ *            astContext?: Function, selfCheck?: Function, trace?: Function, clock?: () => number }
+ * }} opts
+ * @returns {Promise<{ applied: boolean, touchedFiles: string[], telemetry: object|null, error: string|null, rollback: () => void }>}
+ */
+export async function runPiAgentFix(ruleId, violation, cwd, opts = {}) {
+  const { model: modelSpec, tier = null, feedback, caller = `fix:${ruleId}`, timeoutMs, ruleText, deps = {} } = opts
+  const createSession = deps.createSession ?? defaultCreateSession
+  const getReg = deps.getRegistry ?? getRegistry
+  const trace = deps.trace ?? writeTrace
+  const clock = deps.clock ?? (() => Date.now())
+  const astContext = deps.astContext ?? (p => extractContext(resolve(cwd, p)))
+  const selfCheck = deps.selfCheck ?? (async () => ({ ok: false, output: 'self_check недоступний' }))
+  const noop = () => {}
+
+  const fail = error => {
+    trace({ caller, backend: 'pi-ai', kind: 'agent', rule: ruleId, rung: tier, model: modelSpec, cwd, error })
+    return { applied: false, touchedFiles: [], telemetry: null, error, rollback: noop }
+  }
+
+  // §12 git-precondition: нема git → fix пропускається.
+  const root = deps.root !== undefined ? deps.root : gitRoot(cwd)
+  if (!root) return fail('fix пропущено: не git-репо (§12 precondition)')
+
+  let registry
+  let model
+  try {
+    registry = deps.registry ?? (await getReg())
+    model = resolveModelSpec(registry, modelSpec)
+    if (!model) return fail(`модель не знайдена: ${modelSpec}`)
+  } catch (e) {
+    return fail(`registry: ${e.message}`)
+  }
+
+  const guard = createWriteGuard({ cwd, root })
+  let session
+  try {
+    session = await createSession({
+      registry,
+      model,
+      thinkingLevel: thinkingLevelForTier(tier ?? ''),
+      cwd,
+      factory: guard.factory,
+      astContext,
+      selfCheck
+    })
+  } catch (e) {
+    return fail(`session: ${e.message}`)
+  }
+
+  // §12 fail-closed canary: guard мусив приєднатись через loader.
+  if (!guard.state.attached) return fail('write-guard не приєднався — fix скасовано (§12 fail-closed)')
+
+  // Телеметрія §7 із subscribe + turn-ceiling backstop.
+  const turns = []
+  let turnCount = 0
+  let toolCallCount = 0
+  let backstopHit = false
+  session.subscribe(event => {
+    switch (event.type) {
+      case 'turn_start':
+        turnCount++
+        turns.push({ i: turnCount, toolCalls: [], usage: null, finish: null })
+        if (turnCount > TURN_CEILING) {
+          backstopHit = true
+          session.abort?.()
+        }
+        break
+      case 'tool_execution_start':
+        toolCallCount++
+        break
+      case 'tool_execution_end':
+        turns.at(-1)?.toolCalls.push({ name: event.toolName, status: event.isError ? 'error' : 'ok' })
+        break
+      case 'message_end': {
+        const t = turns.at(-1)
+        if (t && event.message?.usage) {
+          t.usage = event.message.usage
+          t.finish = event.message.stopReason ?? null
+        }
+        break
+      }
+      default:
+        break
+    }
+  })
+
+  const startedAt = clock()
+  let error = null
+  try {
+    await withTimeout(session.prompt(buildFixPrompt({ ruleId, violation, ruleText, feedback })), timeoutMs, () =>
+      session.abort?.()
+    )
+  } catch (e) {
+    error = e.message
+  }
+
+  const touchedFiles = guard.touchedFiles()
+  const telemetry = {
+    rule: ruleId,
+    rung: tier,
+    model: modelSpec,
+    turns,
+    turnCount,
+    toolCallCount,
+    edits: guard.state.editLog,
+    blocks: guard.state.blocks,
+    backstopHit,
+    wallMs: clock() - startedAt
+  }
+  trace({
+    caller,
+    backend: 'pi-ai',
+    kind: 'agent',
+    rule: ruleId,
+    rung: tier,
+    model: modelSpec,
+    cwd,
+    turnCount,
+    toolCallCount,
+    backstopHit,
+    error
+  })
+  return { applied: touchedFiles.length > 0, touchedFiles, telemetry, error, rollback: guard.rollback }
+}