@nitra/cursor 12.15.1 → 12.16.1

package/lib/pi-agent-skill.mjs

@@ -0,0 +1,181 @@
+/** @see ./docs/pi-agent-skill.md */
+
+/**
+ * Agentic skill-runner поверх pi `createAgentSession`
+ * (спека docs/specs/2026-06-26-skills-cli-pi-runner-design.md §5).
+ *
+ * Виконує один скіл як pi-агента: готовий `buildSkillPrompt`-рядок → `session.prompt`.
+ * Повний user-trust набір вбудованих tools (`read/grep/find/edit/write/ls/bash`), БЕЗ
+ * write-guard — скіл є явною user-invocation (паритет із `claude -p`, який теж без
+ * обмежень). Модель — з ОДНОГО тиру (`main.json.tier`, дефолт `max`), без escalation-
+ * сходів fix-engine. Runaway-backstop: turn-ceiling + per-call timeout. Асистентський
+ * текст стрімиться у stdout (паритет із `claude -p`). Телеметрія `kind:"skill"` у
+ * глобальний trace ([pi-trace]).
+ *
+ * Pi вантажиться lazy (тверда межа CI). Логіка інжектована через `deps` для unit-тестів.
+ */
+
+import { env, stdout } from 'node:process'
+import { getRegistry, resolveModel, resolveModelSpec } from './pi-model-tiers.mjs'
+import { writeTrace } from './pi-trace.mjs'
+
+/** Аварійна стеля turns на сесію скіла (runaway-backstop). Override: `N_CURSOR_SKILL_TURN_CEILING`. */
+const TURN_CEILING = Number(env.N_CURSOR_SKILL_TURN_CEILING) || 80
+
+/** Дефолтний timeout одного скіл-виклику (скіли довгі). Override: `N_CURSOR_SKILL_TIMEOUT_MS`. */
+const DEFAULT_TIMEOUT_MS = Number(env.N_CURSOR_SKILL_TIMEOUT_MS) || 600_000
+
+/** Повний user-trust набір вбудованих tools. `bash` — обовʼязковий (taze→bun, coverage→тести). */
+const SKILL_TOOLS = ['read', 'grep', 'find', 'edit', 'write', 'ls', 'bash']
+
+/** Тира скіла → pi `thinkingLevel` (одна тира на виклик, без rung-сходів). */
+const THINKING_BY_TIER = { min: 'low', avg: 'medium', max: 'high' }
+
+/**
+ * Дефолтна фабрика pi-сесії: повний tool-set із `bash`, БЕЗ custom-tools і write-guard.
+ * @returns {Promise<object>} pi AgentSession
+ */
+async function defaultCreateSession({ registry, model, cwd, thinkingLevel }) {
+  const { createAgentSession, SessionManager } = await import('@earendil-works/pi-coding-agent')
+  const { session } = await createAgentSession({
+    modelRegistry: registry,
+    model,
+    tools: SKILL_TOOLS,
+    thinkingLevel: thinkingLevel ?? 'medium',
+    cwd: cwd ?? process.cwd(),
+    sessionManager: SessionManager.inMemory()
+  })
+  return session
+}
+
+/** Гонка з таймаутом; на таймаут кличе `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(`skill timeout ${ms}ms`))
+    }, ms)
+  })
+  return Promise.race([Promise.resolve(promise).finally(() => clearTimeout(timer)), timeout])
+}
+
+/**
+ * Виконує ОДИН скіл агентно через pi.
+ * @param {string} prompt готовий промпт (`buildSkillPrompt`)
+ * @param {{
+ *   skillId?: string,
+ *   tier?: 'min'|'avg'|'max',
+ *   modelSpec?: string,
+ *   cwd?: string,
+ *   thinkingLevel?: 'off'|'minimal'|'low'|'medium'|'high'|'xhigh',
+ *   timeoutMs?: number,
+ *   caller?: string,
+ *   deps?: { createSession?: Function, getRegistry?: Function, registry?: object, trace?: Function, clock?: () => number, out?: (s: string) => void }
+ * }} [opts]
+ * @returns {Promise<{ ok: boolean, telemetry: object|null, error: string|null }>}
+ */
+export async function runPiAgentSkill(prompt, opts = {}) {
+  const {
+    skillId = 'skill',
+    tier = 'max',
+    modelSpec,
+    cwd = process.cwd(),
+    thinkingLevel,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    caller = `skill:${skillId}`,
+    deps = {}
+  } = opts
+  const createSession = deps.createSession ?? defaultCreateSession
+  const getReg = deps.getRegistry ?? getRegistry
+  const trace = deps.trace ?? writeTrace
+  const clock = deps.clock ?? (() => Date.now())
+  const out = deps.out ?? (s => stdout.write(s))
+
+  const fail = (error, model) => {
+    trace({ caller, backend: 'pi-ai', kind: 'skill', skill: skillId, tier, model: model ?? null, cwd, error })
+    return { ok: false, telemetry: null, error }
+  }
+
+  let registry
+  let spec
+  let model
+  try {
+    registry = deps.registry ?? (await getReg())
+    spec = modelSpec ?? resolveModel(tier) // '' допустимо → дефолт провайдера pi
+    model = spec ? resolveModelSpec(registry, spec) : null
+    if (spec && !model) return fail(`модель не знайдена: ${spec}`, spec)
+  } catch (e) {
+    return fail(`registry: ${e.message}`, null)
+  }
+
+  let session
+  try {
+    session = await createSession({
+      registry,
+      model,
+      cwd,
+      thinkingLevel: thinkingLevel ?? THINKING_BY_TIER[tier] ?? 'medium'
+    })
+  } catch (e) {
+    return fail(`session: ${e.message}`, spec)
+  }
+
+  let turnCount = 0
+  let toolCallCount = 0
+  let backstopHit = false
+  session.subscribe(event => {
+    switch (event.type) {
+      case 'turn_start':
+        turnCount++
+        if (turnCount > TURN_CEILING) {
+          backstopHit = true
+          session.abort?.()
+        }
+        break
+      case 'tool_execution_start':
+        toolCallCount++
+        break
+      case 'message_update':
+        if (event.assistantMessageEvent?.type === 'text_delta') {
+          out(event.assistantMessageEvent.delta ?? '')
+        }
+        break
+      default:
+        break
+    }
+  })
+
+  const startedAt = clock()
+  let error = null
+  try {
+    await withTimeout(session.prompt(prompt), timeoutMs, () => session.abort?.())
+  } catch (e) {
+    error = e.message
+  }
+
+  const telemetry = {
+    skill: skillId,
+    tier,
+    model: spec || null,
+    turnCount,
+    toolCallCount,
+    backstopHit,
+    wallMs: clock() - startedAt
+  }
+  trace({
+    caller,
+    backend: 'pi-ai',
+    kind: 'skill',
+    skill: skillId,
+    tier,
+    model: spec || null,
+    cwd,
+    turnCount,
+    toolCallCount,
+    backstopHit,
+    error
+  })
+  return { ok: !error && !backstopHit, telemetry, error }
+}

package/lib/pi-model-tiers.mjs

@@ -0,0 +1,109 @@
+/** @see ./docs/pi-model-tiers.md */
+
+/**
+ * Тир-конфіг моделей для pi-embed fix-engine і shared LLM consumers.
+ *
+ * Замінює `models.mjs` після міграції на pi-SDK: тири лишаються політикою n-cursor
+ * (які env-моделі = який тир), але резолвінг тепер через pi `ModelRegistry.find`,
+ * а не ручний routing на omlx/pi-CLI.
+ *
+ * Формат значень env — `"provider/model-id"` (pi-формат), напр.:
+ *   N_LOCAL_MIN_MODEL=omlx/gemma-4-e4b-it-OptiQ-4bit
+ *   N_CLOUD_MIN_MODEL=openai/gpt-5.4-mini
+ *   N_CLOUD_AVG_MODEL=openai/gpt-5.4
+ *
+ * Pi вантажиться ВИКЛЮЧНО у `getRegistry()` (lazy dynamic import) — модуль сам по собі
+ * pi-free, тому pure-функції (`parseModelId`, `resolveModelSpec`, `thinkingLevelForTier`,
+ * `resolveModel`) юніт-тестуються без pi (registry інжектується).
+ */
+
+import { env } from 'node:process'
+
+// ── Тири (env-політика) ──────────────────────────────────────────────────────
+
+/** Швидкий локальний inference. Напр.: omlx/gemma-4-e4b-it-OptiQ-4bit */
+export const LOCAL_MIN = env.N_LOCAL_MIN_MODEL ?? ''
+/** Середній локальний. */
+export const LOCAL_AVG = env.N_LOCAL_AVG_MODEL ?? ''
+/** Максимальний локальний. */
+export const LOCAL_MAX = env.N_LOCAL_MAX_MODEL ?? ''
+/** Мінімальний хмарний (потрібен ключ у pi auth). Напр.: openai/gpt-5.4-mini */
+export const CLOUD_MIN = env.N_CLOUD_MIN_MODEL ?? ''
+/** Середній хмарний. Напр.: openai/gpt-5.4 */
+export const CLOUD_AVG = env.N_CLOUD_AVG_MODEL ?? ''
+/** Максимальний хмарний. Напр.: openai/gpt-5.5 */
+export const CLOUD_MAX = env.N_CLOUD_MAX_MODEL ?? ''
+
+/**
+ * Каскадне розв'язання абстрактного тиру в `"provider/model-id"` (контракт із
+ * `models.mjs`, збережений для shared one-shot consumers):
+ *   'min' → LOCAL_MIN → LOCAL_AVG → LOCAL_MAX → CLOUD_MIN
+ *   'avg' → LOCAL_AVG → LOCAL_MAX → CLOUD_AVG
+ *   'max' → LOCAL_MAX → CLOUD_MAX
+ * @param {'min'|'avg'|'max'} tier тир
+ * @returns {string} `"provider/model-id"` або `''` (pi-дефолт провайдера)
+ * @throws {TypeError} якщо tier невідомий
+ */
+export function resolveModel(tier) {
+  if (tier === 'min') return LOCAL_MIN || LOCAL_AVG || LOCAL_MAX || CLOUD_MIN
+  if (tier === 'avg') return LOCAL_AVG || LOCAL_MAX || CLOUD_AVG
+  if (tier === 'max') return LOCAL_MAX || CLOUD_MAX
+  throw new TypeError(`resolveModel: unknown tier "${tier}". Use 'min', 'avg', or 'max'.`)
+}
+
+// ── Escalation-rung → pi thinkingLevel (§3) ──────────────────────────────────
+
+/**
+ * pi `thinkingLevel` за rung-тиром fix-драбини: слабка локальна — `low`,
+ * cloud-min — `medium`, cloud-avg (найдорожча, найскладніше) — `high`. Замінює
+ * ручний числовий `thinkingBudget`-плюмбінг старого omlx-каналу.
+ * @param {string} tier rung-тир (`local-min` | `local-min-retry` | `cloud-min` | `cloud-avg`)
+ * @returns {'off'|'minimal'|'low'|'medium'|'high'|'xhigh'} дискретний рівень
+ */
+export function thinkingLevelForTier(tier) {
+  if (tier === 'cloud-avg') return 'high'
+  if (tier === 'cloud-min') return 'medium'
+  return 'low' // local-min, local-min-retry
+}
+
+// ── Парсинг і резолвінг через pi ─────────────────────────────────────────────
+
+/**
+ * Розбирає `"provider/model-id"` у пару. Перший `/` — роздільник (model-id може
+ * містити власні `/`). Порожній провайдер чи id → `null` (malformed).
+ * @param {string} spec `"provider/model-id"`
+ * @returns {{ provider: string, id: string } | null} пара або null
+ */
+export function parseModelId(spec) {
+  if (typeof spec !== 'string') return null
+  const i = spec.indexOf('/')
+  if (i < 1 || i === spec.length - 1) return null
+  return { provider: spec.slice(0, i), id: spec.slice(i + 1) }
+}
+
+/**
+ * Резолвить `"provider/model-id"` у pi Model-обʼєкт через інжектований registry.
+ * `createAgentSession` чекає саме Model-обʼєкт (НЕ рядок) — див. Спайк 2.
+ * @param {{ find: (provider: string, id: string) => object|null|undefined }} registry pi ModelRegistry
+ * @param {string} spec `"provider/model-id"`
+ * @returns {object|null} pi Model або null (malformed/не знайдено)
+ */
+export function resolveModelSpec(registry, spec) {
+  const parsed = parseModelId(spec)
+  if (!parsed) return null
+  return registry.find(parsed.provider, parsed.id) ?? null
+}
+
+/**
+ * Lazy singleton pi `ModelRegistry` (вантажить `~/.pi/agent/models.json` + `auth.json`).
+ * **Єдина** точка, де модуль торкається pi — dynamic import тримає `--read-only`
+ * шлях pi-free (тверда межа CI). Кешується на процес.
+ * @returns {Promise<object>} pi ModelRegistry
+ */
+let _registry = null
+export async function getRegistry() {
+  if (_registry) return _registry
+  const { ModelRegistry, AuthStorage } = await import('@earendil-works/pi-coding-agent')
+  _registry = ModelRegistry.create(AuthStorage.create())
+  return _registry
+}

package/lib/pi-one-shot.mjs

@@ -0,0 +1,129 @@
+/** @see ./docs/pi-one-shot.md */
+
+/**
+ * Bounded one-shot LLM-виклик поверх pi (§3а спеки pi-migration).
+ *
+ * Для shared не-agent consumers (`doc-files` generation/judge, `text/cspell`
+ * класифікація, ADR-normalize): «messages → текст», без write-tool, без агентного
+ * циклу. Реалізовано як `createAgentSession({ noTools: 'all' })` + `session.prompt`
+ * (агент без tools = plain completion) — перевикористовує верифікований pi-embed
+ * (той самий ModelRegistry/AuthStorage, що й agent-fix), замість окремого
+ * raw-pi-ai streaming-плюмбінгу.
+ *
+ * Замінює `callLlm`/прямий omlx-канал для не-agent задач. Pi вантажиться lazy
+ * (тверда межа CI). Повертає structured `{ content, usage, error, model, caller }`.
+ */
+
+import { getRegistry, resolveModel, resolveModelSpec } from './pi-model-tiers.mjs'
+import { writeTrace } from './pi-trace.mjs'
+
+/** Дефолтний timeout одного one-shot виклику. */
+const DEFAULT_TIMEOUT_MS = 120_000
+
+/**
+ * Дефолтна фабрика сесії (lazy pi). `noTools:'all'` → чистий completion.
+ * Інструкції НЕ йдуть через `replaceInstructions`: слабкі локальні моделі (gemma-4b)
+ * трактують system-prompt-інструкції як «правила для підтвердження» й мета-рамблять
+ * замість виконувати. Тому system-повідомлення зливаються у prompt (див. runOneShot) —
+ * перевірено: інлайн-інструкції модель ВИКОНУЄ, у system-промпті — переказує.
+ * @returns {Promise<object>} pi AgentSession
+ */
+async function defaultCreateSession({ registry, model, cwd, thinkingLevel }) {
+  const { createAgentSession, SessionManager } = await import('@earendil-works/pi-coding-agent')
+  const { session } = await createAgentSession({
+    modelRegistry: registry,
+    model,
+    noTools: 'all',
+    thinkingLevel: thinkingLevel ?? 'off',
+    cwd: cwd ?? process.cwd(),
+    sessionManager: SessionManager.inMemory()
+  })
+  return session
+}
+
+/** Гонка проміса з таймаутом (мс ≤ 0 → без таймауту). */
+function withTimeout(promise, ms) {
+  if (!ms || ms <= 0) return promise
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`one-shot timeout ${ms}ms`)), ms)
+  })
+  return Promise.race([Promise.resolve(promise).finally(() => clearTimeout(timer)), timeout])
+}
+
+/**
+ * Виконує bounded one-shot LLM-виклик.
+ * @param {{
+ *   messages: Array<{role: string, content: string}>,
+ *   modelTier?: 'min'|'avg'|'max',
+ *   modelSpec?: string,
+ *   thinkingLevel?: 'off'|'minimal'|'low'|'medium'|'high'|'xhigh',
+ *   timeoutMs?: number,
+ *   caller?: string,
+ *   cwd?: string,
+ *   deps?: { createSession?: Function, getRegistry?: Function, registry?: object, trace?: Function }
+ * }} args параметри
+ * @returns {Promise<{ content: string, usage: object|null, error: string|null, model: string|null, caller: string }>} результат
+ */
+export async function runOneShot({
+  messages,
+  modelTier = 'min',
+  modelSpec,
+  thinkingLevel,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  caller = 'one-shot',
+  cwd,
+  deps = {}
+} = {}) {
+  const createSession = deps.createSession ?? defaultCreateSession
+  const getReg = deps.getRegistry ?? getRegistry
+  const trace = deps.trace ?? writeTrace
+
+  // Усі повідомлення (system+user) зливаються в один prompt — інлайн-інструкції
+  // слабка локальна модель ВИКОНУЄ, а в system-промпті (replaceInstructions) — переказує.
+  const userText = messages.map(m => m.content).join('\n\n')
+
+  const fail = (error, model) => {
+    trace({ caller, backend: 'pi-ai', kind: 'one-shot', model: model ?? null, cwd: cwd ?? null, error })
+    return { content: '', usage: null, error, model: model ?? null, caller }
+  }
+
+  let registry
+  let spec
+  let model
+  try {
+    registry = deps.registry ?? (await getReg())
+    spec = modelSpec ?? resolveModel(modelTier)
+    model = spec ? resolveModelSpec(registry, spec) : null
+    if (spec && !model) return fail(`модель не знайдена: ${spec}`, spec)
+  } catch (e) {
+    return fail(`registry: ${e.message}`, null)
+  }
+
+  let session
+  try {
+    session = await createSession({ registry, model, cwd, thinkingLevel })
+  } catch (e) {
+    return fail(`session: ${e.message}`, spec)
+  }
+
+  let text = ''
+  let usage = null
+  session.subscribe(event => {
+    if (event.type === 'message_update' && event.assistantMessageEvent?.type === 'text_delta') {
+      text += event.assistantMessageEvent.delta ?? ''
+    } else if (event.type === 'message_end' && event.message?.usage) {
+      usage = event.message.usage
+    }
+  })
+
+  let error = null
+  try {
+    await withTimeout(session.prompt(userText), timeoutMs)
+  } catch (e) {
+    error = e.message
+  }
+
+  trace({ caller, backend: 'pi-ai', kind: 'one-shot', model: spec, cwd: cwd ?? null, usage, error })
+  return { content: text.trim(), usage, error, model: spec, caller }
+}

package/lib/pi-trace.mjs

@@ -0,0 +1,40 @@
+/** @see ./docs/pi-trace.md */
+
+/**
+ * Глобальний append-only LLM wire-trace (§7 спеки pi-migration).
+ *
+ * Замінює project-local `omlx-trace.mjs`: єдиний trace живе глобально
+ * (`~/.n-cursor/llm-trace.jsonl`), щоб (1) прибрати службовий шум із consumer-репо,
+ * (2) лишити cross-project телеметрію mineable в одному місці. Старі project-local
+ * `<cwd>/.n-cursor/llm-trace.jsonl` більше не створюються.
+ *
+ * Записувач **best-effort**: будь-яка IO-помилка ковтається — трасування ніколи не
+ * валить виклик LLM. Шлях перевизначається `N_CURSOR_TRACE_PATH` (для тестів/CI).
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { env } from 'node:process'
+
+/** Шлях глобального trace (env-override `N_CURSOR_TRACE_PATH`). @returns {string} */
+export function tracePath() {
+  return env.N_CURSOR_TRACE_PATH || join(homedir(), '.n-cursor', 'llm-trace.jsonl')
+}
+
+/**
+ * Дописує один trace-запис (JSONL). Поля за §7: `caller`, `rule`, `rung`, `model`,
+ * `backend:"pi-ai"`, `kind:"agent"|"one-shot"`, `cwd`, плюс довільна корисна навантага.
+ * Ніколи не кидає.
+ * @param {object} record запис трасування
+ * @param {string} [path] шлях (за замовч. `tracePath()`)
+ * @returns {void}
+ */
+export function writeTrace(record, path = tracePath()) {
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    appendFileSync(path, `${JSON.stringify({ ts: new Date().toISOString(), ...record })}\n`)
+  } catch {
+    // best-effort: трасування не повинно валити виклик
+  }
+}

package/lib/pi-write-guard.mjs

@@ -0,0 +1,147 @@
+/** @see ./docs/pi-write-guard.md */
+
+/**
+ * Write-safety guard для pi-agent fix-engine (§12 спеки pi-migration).
+ *
+ * Рішення §1 «патч застосовує агент» забирає dry-run, тому контроль над записом
+ * виносимо у три незалежні під-механізми, що спираються на одну git-precondition:
+ *   - **Scope/Denylist** — превентивний veto через `pi.on('tool_call')`: блок запису
+ *     поза git-root, під `.git/`, або в будь-що, що матчить `git check-ignore`.
+ *   - **Snapshot** — per-file pre-image (наявний вміст або позначка NEW) на перший
+ *     дотик; покриває abort посеред запису.
+ *   - **Rollback** — відновлення pre-image (або видалення NEW-файлів) на провал verdict-а.
+ *
+ * ⚠️ Розводка: фабрику передавати ВИКЛЮЧНО через `new DefaultResourceLoader({
+ * extensionFactories: [factory] })` → `resourceLoader`. Top-level
+ * `createAgentSession({ extensionFactories })` **мовчки ігнорується** (Спайк 3,
+ * fail-open). Тому caller ОБОВ'ЯЗКОВО перевіряє `state.attached` (fail-closed canary)
+ * перед `session.prompt` і скасовує fix, якщо guard не приєднався.
+ *
+ * Pi-free: фабрика лише shape-сумісна з ExtensionAPI (`pi.on`), імпортів pi нема.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+/** Sentinel pre-image для файлу, якого до запису не існувало (rollback = видалити). */
+export const NEW_FILE = Symbol('new-file')
+
+/** Tool-и, що пишуть на диск і підлягають veto. */
+const WRITE_TOOLS = new Set(['edit', 'write'])
+
+/**
+ * git-root для cwd (`git rev-parse --show-toplevel`) або null, якщо не git-репо.
+ * Fix-шлях вимагає git → caller на null **пропускає fix** (§12 precondition).
+ * @param {string} cwd робоча директорія
+ * @returns {string|null} абсолютний git-root або null
+ */
+export function gitRoot(cwd) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' })
+  if (r.status !== 0) return null
+  return r.stdout.trim() || null
+}
+
+/**
+ * realpath шляху з найкращих зусиль: для наявного — повний realpath; для ще-неіснуючого
+ * (NEW-файл) — realpath батьківської теки + basename; інакше — як є. Знімає розбіжність
+ * symlink-шляхів (macOS `/tmp` → `/private/tmp`), через яку tracked-файл хибно блокувався.
+ * @param {string} p шлях
+ * @returns {string} нормалізований абсолютний шлях
+ */
+function realpathBestEffort(p) {
+  try {
+    return realpathSync(p)
+  } catch {
+    try {
+      return join(realpathSync(dirname(p)), basename(p))
+    } catch {
+      return p
+    }
+  }
+}
+
+/** Чи `abs` під `root` (захист від `..`-escape). @param {string} root @param {string} abs */
+function isUnder(root, abs) {
+  const rel = relative(root, abs)
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
+}
+
+/** Чи `abs` ігнорований git'ом (`git check-ignore -q`, exit 0 = ignored). */
+function isIgnored(root, abs) {
+  return spawnSync('git', ['check-ignore', '-q', '--', abs], { cwd: root }).status === 0
+}
+
+/**
+ * Створює write-guard для однієї fix-сесії.
+ * @param {{ cwd: string, root?: string|null, checkIgnore?: (root: string, abs: string) => boolean }} opts
+ *   cwd — робоча директорія; root — git-root (за替замовч. обчислюється); checkIgnore — інжекція для тестів
+ * @returns {{
+ *   factory: (pi: { on: Function }) => void,
+ *   state: { attached: boolean, root: string|null, preImages: Map<string, string|symbol>, blocks: Array<{path:string,reason:string}> },
+ *   rollback: () => void,
+ *   touchedFiles: () => string[]
+ * }} guard
+ */
+export function createWriteGuard({ cwd, root, checkIgnore = isIgnored }) {
+  const rawRoot = root === undefined ? gitRoot(cwd) : root
+  const gitRootDir = rawRoot ? realpathBestEffort(rawRoot) : rawRoot
+  // editLog — повні правки агента (oldText/newText / content) для телеметрії §7.
+  const state = { attached: false, root: gitRootDir, preImages: new Map(), blocks: [], editLog: [] }
+
+  const factory = pi => {
+    state.attached = true
+    // Синхронний хендлер: уся робота (spawnSync/fs) синхронна; pi коректно
+    // awaitить і не-Promise return (Спайк 3). Так veto детерміновано тестується.
+    pi.on('tool_call', event => {
+      if (!WRITE_TOOLS.has(event?.toolName)) return undefined
+      const raw = event?.input?.path
+      if (typeof raw !== 'string' || raw === '') return undefined // не резолвимо — хай pi сам
+
+      // realpath-нормалізація: edit-шлях агента може бути symlink-варіантом root'а.
+      const abs = realpathBestEffort(isAbsolute(raw) ? raw : resolve(cwd, raw))
+      const block = reason => {
+        state.blocks.push({ path: abs, reason })
+        return { block: true, reason }
+      }
+
+      // 1. Scope: під git-root.
+      if (!gitRootDir || !isUnder(gitRootDir, abs)) return block(`запис поза git-root: ${raw}`)
+      // 2. .git/ (поза моделлю ignore).
+      const rel = relative(gitRootDir, abs)
+      if (rel === '.git' || rel.startsWith(`.git${sep}`)) return block(`запис у .git/ заблоковано: ${raw}`)
+      // 3. Denylist = git-ignored (build-артефакти, node_modules, .env, .worktrees…).
+      if (checkIgnore(gitRootDir, abs)) return block(`запис у git-ignored заблоковано: ${raw}`)
+
+      // 4. Allow + Snapshot pre-image на перший дотик + лог правки (телеметрія §7).
+      if (!state.preImages.has(abs)) {
+        state.preImages.set(abs, existsSync(abs) ? readFileSync(abs, 'utf8') : NEW_FILE)
+      }
+      state.editLog.push({
+        path: abs,
+        tool: event.toolName,
+        edits: event.input?.edits ?? null, // edit: [{oldText,newText}]
+        content: event.input?.content ?? null // write: повний вміст
+      })
+      return undefined
+    })
+  }
+
+  /** Відновлює pre-image усіх зачеплених файлів (NEW → видалити). */
+  function rollback() {
+    for (const [abs, pre] of state.preImages) {
+      if (pre === NEW_FILE) {
+        if (existsSync(abs)) rmSync(abs)
+      } else {
+        writeFileSync(abs, pre)
+      }
+    }
+  }
+
+  /** Список абсолютних шляхів, яких агент торкнувся (для scoped re-check verdict §4+5). */
+  function touchedFiles() {
+    return [...state.preImages.keys()]
+  }
+
+  return { factory, state, rollback, touchedFiles }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.15.1",
+  "version": "12.16.1",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -62,6 +62,10 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
+  "optionalDependencies": {
+    "@earendil-works/pi-ai": "0.80.2",
+    "@earendil-works/pi-coding-agent": "0.80.2"
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=25"

package/rules/doc-files/js/docgen-files-batch.mjs

@@ -12,8 +12,24 @@ import {
 import { basename, dirname, join, relative } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { classifyOmlxError, preflightLocalModel } from '../../../lib/llm.mjs'
 import { generateDoc, DEFAULT_LOCAL_MODEL } from './docgen-gen.mjs'
+
+/**
+ * Класифікує помилку генерації для batch-логіки (замінює `classifyOmlxError` після
+ * pi-міграції — помилки приходять як винятки з generateDoc/pi-one-shot):
+ *   - `permanent` — pre-send guard «Prompt too long» → skip (не ретраїти);
+ *   - `systemic`  — модель/сервер/registry/RAM упали → circuit-breaker abort;
+ *   - `transient` — таймаут (можна було б ретраїти);
+ *   - `infra`     — інше (рахуємо як помилку, але без abort).
+ * @param {string} msg повідомлення помилки
+ * @returns {'permanent'|'systemic'|'transient'|'infra'} клас
+ */
+function classifyDocgenError(msg) {
+  if (/prompt too long|pre-send guard|too long/i.test(msg)) return 'permanent'
+  if (/registry:|session:|не знайдена|memory|enomem|connection refused|econnrefused/i.test(msg)) return 'systemic'
+  if (/timeout|etimedout/i.test(msg)) return 'transient'
+  return 'infra'
+}
 import { crc32, stampDoc, readDocQuality, readDocModel, QUALITY_THRESHOLD } from './docgen-crc.mjs'
 import { resolveRoot, scanForDocFiles, scanOrphanedDocs } from './docgen-scan.mjs'
 
@@ -134,7 +150,7 @@ async function generateOne(file, root, progress, stats) {
     }
     return 'ok'
   } catch (error) {
-    const cls = classifyOmlxError(error.message)
+    const cls = classifyDocgenError(error.message)
     if (cls === 'permanent') {
       stats.skipped.push(file.sourcePath)
       process.stdout.write(`⊘ skip (permanent): ${error.message}\n`)
@@ -307,9 +323,8 @@ export async function runDocFilesGenCli(argv) {
  * @returns {Promise<number>} 0 — без помилок; 1 — фейл preflight або є помилки; 2 — systemic-abort
  */
 export async function runGenerationBatch(targets, root, { headline } = {}) {
-  const problem = preflightLocalModel(DEFAULT_LOCAL_MODEL)
-  if (problem) {
-    console.error(`✗ fix-doc-files: ${problem}`)
+  if (!DEFAULT_LOCAL_MODEL) {
+    console.error('✗ fix-doc-files: локальну модель не задано (N_LOCAL_MIN_MODEL)')
     return 1
   }