@nitra/cursor 12.3.1 → 12.3.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [12.3.2] - 2026-06-20
+
+### Fixed
+
+- fix-каскад: per-tier timeout (локалі fail-fast ~45s замість стіни 120s, env N_LOCAL_FIX_TIMEOUT_MS/N_CLOUD_FIX_TIMEOUT_MS) + хмарний транспортний збій (pi ETIMEDOUT/spawn) обриває драбину замість ескалації на cloud-avg — не палиться avg-бюджет
+
 ## [12.3.1] - 2026-06-20
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.3.1",
+  "version": "12.3.2",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/scripts/lib/fix/docs/llm-worker.md

@@ -3,7 +3,7 @@ type: JS Module
 title: llm-worker.mjs
 resource: npm/scripts/lib/fix/llm-worker.mjs
 docgen:
-  crc: de9eb68c
+  crc: 857c510e
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -18,7 +18,7 @@ docgen:
 
 ## Публічний API
 
-- `runLlmWorker(ruleId, violationOutput, projectRoot, opts)` — виправляє одне порушення; `opts`: `model`, `feedback`, `caller`. Повертає `{ ok, error, changes, diagnosis }`.
+- `runLlmWorker(ruleId, violationOutput, projectRoot, opts)` — виправляє одне порушення; `opts`: `model`, `feedback`, `caller`, `timeoutMs` (per-tier ліміт виклику; драбина задає коротший для локальних рунгів). Повертає `{ ok, error, changes, diagnosis }`.
 
 ## Гарантії поведінки
 

package/scripts/lib/fix/docs/orchestrator.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrator.mjs
 resource: npm/scripts/lib/fix/orchestrator.mjs
 docgen:
-  crc: 78dfe86b
+  crc: d327ab6d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -19,7 +19,8 @@ docgen:
    - рунг `local-min` — перший прохід без feedback;
    - рунг `local-min-retry` — той самий локальний тир, але з feedback попереднього рунга (попередні зміни + залишковий violation);
    - рунги `cloud-min` / `cloud-avg` — хмарні моделі (через pi), теж із feedback.
-5. Достроковий вихід драбини: systemic-помилка локального тиру пропускає рунги тієї ж моделі; відсутній API-ключ на хмарному обриває драбину; вичерпаний avg-кеп пропускає avg-рунг (із записом у лог).
+   Кожен рунг має per-tier `timeoutMs`: локальні **fail-fast** (`N_LOCAL_FIX_TIMEOUT_MS`, дефолт 45s — не палити стіну 120s на повільному локальному inference), хмарні — повний (`N_CLOUD_FIX_TIMEOUT_MS`, дефолт 120s).
+5. Достроковий вихід драбини: systemic-помилка локального тиру пропускає рунги тієї ж моделі; відсутній API-ключ на хмарному обриває драбину; хмарний транспортний збій (pi таймаут/spawn) обриває драбину, щоб не палити avg-бюджет на ту саму стіну; вичерпаний avg-кеп пропускає avg-рунг (із записом у лог).
 6. Після обробки всіх правил — фінальна перевірка. Усі чисті → успіх; інакше — ознака нерозв'язаних.
 
 ## Публічний API

package/scripts/lib/fix/llm-worker.mjs

@@ -117,11 +117,12 @@ function buildPrompt(ruleId, ruleMdc, output, files, feedback = null) {
  * @param {string} prompt текст промпта
  * @param {string} model назва моделі (provider/id, `omlx/...` або '')
  * @param {string} caller мітка викликача для wire-trace (`fix:<rule>:<rung>`)
+ * @param {number} [timeoutMs] ліміт виклику (драбина задає per-tier; undefined → дефолт callLlm)
  * @returns {{ text: string, error?: string }} текст відповіді або повідомлення про помилку
  */
-function callModel(prompt, model, caller) {
+function callModel(prompt, model, caller, timeoutMs) {
   try {
-    return { text: callLlm([{ role: 'user', content: prompt }], model, { timeoutMs: 120_000, caller }) }
+    return { text: callLlm([{ role: 'user', content: prompt }], model, { timeoutMs, caller }) }
   } catch (error) {
     const msg = String(error.message)
     if (API_KEY_RE.test(msg)) {
@@ -146,9 +147,10 @@ function callModel(prompt, model, caller) {
  * @param {string} ruleId ID правила
  * @param {string} violationOutput  output з fix check для цього rule
  * @param {string} projectRoot      абсолютний шлях до кореня проєкту
- * @param {{ model?: string, feedback?: object|null, caller?: string }} opts опції:
+ * @param {{ model?: string, feedback?: object|null, caller?: string, timeoutMs?: number }} opts опції:
  *   `model` — перевизначення моделі; `feedback` — контекст попереднього рунга
- *   драбини (retry-with-feedback); `caller` — мітка для wire-trace
+ *   драбини (retry-with-feedback); `caller` — мітка для wire-trace; `timeoutMs` —
+ *   per-tier ліміт виклику (драбина: локалі fail-fast, хмара повний)
  * @returns {{ ok: boolean, error?: string, changes: Array<{path:string}>, diagnosis: string|null }}
  *   статус виправлення, помилка, запропоновані зміни і само-аналіз моделі
  */
@@ -156,6 +158,7 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   const model = opts.model ?? MODEL
   const feedback = opts.feedback ?? null
   const caller = opts.caller ?? 'fix'
+  const timeoutMs = opts.timeoutMs
 
   // 1. Читаємо rule .mdc
   const mdcPath = join(projectRoot, '.cursor', 'rules', `n-${ruleId}.mdc`)
@@ -166,7 +169,7 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
 
   // 3. Будуємо prompt і викликаємо модель
   const prompt = buildPrompt(ruleId, ruleMdc, violationOutput, files, feedback)
-  const { text, error: modelError } = callModel(prompt, model, caller)
+  const { text, error: modelError } = callModel(prompt, model, caller, timeoutMs)
 
   if (modelError) return { ok: false, error: modelError, changes: [], diagnosis: null }
   if (!text) return { ok: false, error: 'model returned empty response', changes: [], diagnosis: null }

package/scripts/lib/fix/orchestrator.mjs

@@ -1,5 +1,6 @@
 /** @see ./docs/orchestrator.md */
 
+import { env } from 'node:process'
 import { runFixCheck } from './run-fix-check.mjs'
 import { runT0AutoCli } from './t0.mjs'
 import { logEscalation } from './escalation-log.mjs'
@@ -13,9 +14,24 @@ import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/models.mjs'
  */
 const DEFAULT_MAX_AVG = 3
 
+/**
+ * Timeout одного LLM-виклику за тиром. Локальні рунги **fail-fast**: не палити
+ * стіну 120s на повільному 4b (curl exit 28) — швидше абортнути й ескалувати.
+ * Хмарні — повний. Перевизначення: `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`.
+ */
+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
+
 /** Маркер дружнього повідомлення про відсутній API-ключ (з `llm-worker.callModel`). */
 const NO_KEY_RE = /немає ключа|api key/i
 
+/**
+ * Хмарний транспорт (pi) упав на рівні процесу: таймаут/spawn-помилка. Стіна часу
+ * однакова для всіх cloud-рунгів (та сама pi-транспортна стіна), а cloud-avg — інша
+ * модель, не більший timeout. Ескалація на неї лише спалить avg-бюджет → обрив.
+ */
+const CLOUD_TRANSPORT_RE = /etimedout|timed out|pi error/i
+
 /**
  * Будує драбину ескалації за наявними тирами (спека 2026-06-19-fix-escalation-cascade):
  *  1. `local-min`       — `N_LOCAL_MIN_MODEL`, перший прохід;
@@ -24,14 +40,14 @@ const NO_KEY_RE = /немає ключа|api key/i
  *  4. `cloud-avg`       — `N_CLOUD_AVG_MODEL` (через pi), з feedback, під avg-кепом.
  * Рунги з незаданим тиром (`''`) відсіюються — драбина стискається до доступних.
  * @param {{ localMin: string, cloudMin: string, cloudAvg: string }} models тири з env
- * @returns {Array<{ tier: string, model: string, feedback: boolean, local: boolean, isAvg: boolean }>} драбина
+ * @returns {Array<{ tier: string, model: string, feedback: boolean, local: boolean, isAvg: boolean, timeoutMs: number }>} драбина
  */
 export function buildLadder({ localMin, cloudMin, cloudAvg }) {
   return [
-    { tier: 'local-min', model: localMin, feedback: false, local: true, isAvg: false },
-    { tier: 'local-min-retry', model: localMin, feedback: true, local: true, isAvg: false },
-    { tier: 'cloud-min', model: cloudMin, feedback: true, local: false, isAvg: false },
-    { tier: 'cloud-avg', model: cloudAvg, feedback: true, local: false, isAvg: true }
+    { 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)
 }
 
@@ -40,6 +56,8 @@ export function buildLadder({ localMin, cloudMin, cloudAvg }) {
  *  - `break`     — відсутній API-ключ на хмарному (інші хмарні рунги теж без ключа);
  *  - `skip-model` — systemic-помилка локального тиру (memory-guard/auth/down): повтор
  *                   тієї ж моделі марний → пропустити рунги з цим model.
+ *  - `break`     — також хмарний транспорт упав (pi таймаут/spawn): решта cloud-рунгів
+ *                  під тією ж стіною → обрив, щоб не палити avg-бюджет.
  * @param {{ local: boolean }} rung поточний рунг
  * @param {string|null|undefined} error помилка виклику worker
  * @returns {'break'|'skip-model'|null} дія для драбини
@@ -48,6 +66,7 @@ function decideAfterFailure(rung, error) {
   if (!error) return null
   if (NO_KEY_RE.test(error)) return 'break'
   if (rung.local && classifyOmlxError(error) === 'systemic') return 'skip-model'
+  if (!rung.local && CLOUD_TRANSPORT_RE.test(error)) return 'break'
   return null
 }
 
@@ -93,7 +112,8 @@ export async function escalateRule(rule, cwd, deps) {
     const res = worker.runLlmWorker(rule.ruleId, currentViolation, cwd, {
       model: rung.model,
       feedback: rung.feedback ? feedback : null,
-      caller: `fix:${rule.ruleId}:${rung.tier}`
+      caller: `fix:${rule.ruleId}:${rung.tier}`,
+      timeoutMs: rung.timeoutMs
     })
     if (rung.isAvg) avgUsed++