@7n/test 0.11.2 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.12.1] - 2026-07-04
+
+### Changed
+
+- test(core): моки node:fs під vitest-shim і актуалізація shouldDedup-очікування
+
+## [0.12.0] - 2026-07-04
+
+### Added
+
+- 🤖 feat(core): спільний prompt-budget (бюджет символів + per-call maxTokens за типом задачі через streamFn-обгортку), батчинг fix-tests під бюджет з анти-starvation, повтор на обрізану генерацію (stopReason length)
+
+### Fixed
+
+- 🤖 fix(core): coverage-скан виключає `**/*.d.ts` — vitest 4 прибрав дефолтний exclude, і v8-remap падав із RolldownError на TS-синтаксисі декларацій у цільових проєктах (CLI-прапорець у coverage-per-file та exclude у shim-конфігу)
+- CLI більше не висить після завершення роботи: явний process.exit у bin (незакриті pi-сесії тримали event loop) і session.dispose() у finally для callText/callAgent
+
 ## [0.11.2] - 2026-07-04
 
 ### Fixed

package/bin/7n-test.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
 import { run } from '../src/index.js'
 
-process.exitCode = await run(process.argv.slice(2))
+// Незакриті pi-сесії (createAgentSession) тримають event loop, тож без явного
+// process.exit процес висить після завершення роботи навіть з кодом 0.
+// eslint-disable-next-line n/no-process-exit
+process.exit(await run(process.argv.slice(2)))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/test",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "description": "CLI-утиліта @7n/test",
   "keywords": [
     "7n",

package/src/coverage-per-file.mjs

@@ -112,6 +112,8 @@ export async function measureCoveragePerFile(dir) {
         '--coverage.reporter=lcov',
         // vitest 4 прибрав coverage.all — явний include, щоб файли без тестів лишались у lcov (0%)
         '--coverage.include=**/*.{js,mjs,ts,vue}',
+        // vitest 4 прибрав дефолтний exclude **/*.d.ts — без нього v8-remap падає на TS-синтаксисі декларацій
+        '--coverage.exclude=**/*.d.ts',
         `--coverage.reportsDirectory=${lcovDir}`,
         '--reporter=verbose',
         '--reporter=json',

package/src/docs/coverage-per-file.md

@@ -3,7 +3,7 @@ type: JS Module
 title: coverage-per-file.mjs
 resource: npm/src/coverage-per-file.mjs
 docgen:
-  crc: d167dff5
+  crc: 2b4a460d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98

package/src/docs/fix-tests.md

@@ -3,30 +3,33 @@ type: JS Module
 title: fix-tests.mjs
 resource: npm/src/fix-tests.mjs
 docgen:
-  crc: b807d1bc
+  crc: f82de3c4
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.98
+  tier: local-min-retry
+  score: 90
+  issues: internal-name:callText,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Цей модуль виявляє падаючі юніт-тести, запускаючи `vitest run --reporter=json` для збору помилок з конфігураційного файлу `results.json`. Подалі, він ітерує через виявлені файли, використовуючи текстовий режим pi SDK для отримання виправленого коду, який записується напряму, повторюючи спроби до досягнення `MAX_FIX_ATTEMPTS`. Процес реалізований з механізмом перехоплення помилок (`fail-safe`), щоб не кидати винятків.
+Виявляє падаючі unit-тести та автоматично їх виправляє з використанням pi SDK (text mode). Процес починається з запуску `vitest run --reporter=json` за допомогою `getFailingTests`, що створює перелік файлів з помилками. Потім функція `fixFailingTests` для кожного файлу читає його вміст та вміст відповідного source-файлу. Використовуючи `callText`, інструмент отримує виправлений код, який потім записується напряму через `writeFileSync` у тест-файл, що усуває проблеми точного матчу рядків, характерні для Edit-інструментів. Всі операції спираються на конфігурацію, описану в `results.json`.
 
 ## Поведінка
 
 Поведінка:
-getFailingTests виявляє падаючі юніт-тести, запускаючи vitest у JSON-режимі та повертаючи список цих файлів разом з повідомленнями про помилки.
-buildFixTestsPrompt створює деталізований текстовий промпт, що містить поточний вміст падаючих тест-файлів та відповідні вихідні файли, для інструмента LLM.
-fixFailingTests ітерує через падаючі тести, отримує виправлення від LLM за допомогою текстового режиму pi SDK та записує оновлений код напряму у відповідні файли, повторюючи спроби до MAX_FIX_ATTEMPTS.
+getFailingTests запускає vitest у JSON-режимі та повертає список падаючих тест-файлів з повідомленнями про помилки.
+buildFixTestsPrompt створює повний текстовий промпт для LLM, що містить вміст падаючих тест-файлів та їхні помилки.
+buildFixTestsBatch розподіляє падаючі тест-файли на батчі для LLM, враховуючи обмеження промпту.
+fixFailingTests ітерує по падаючих тестах, викликаючи LLM для виправлень та записує виправлений код безпосередньо у файли.
 
 ## Публічний API
 
-- getFailingTests — Виконує тестування за допомогою Vitest у форматі JSON і повертає файли тестів з помилками, що не пройшли.
-- buildFixTestsPrompt — Створює спеціальне повідомлення (prompt) для виправлення одного файлу, що не пройшов тест, включаючи вміст поточного файлу.
-- fixFailingTests — Знаходить та виправляє помилкові тести, використовуючи текстовий режим SDK pi та пряме записування файлів.
+getFailingTests — Виконує тестування у JSON-форматі та надає список файлів із проваленими тестами разом із повідомленнями про помилки.
+buildFixTestsPrompt — Створює запит для ШІ з вмістом одного файлу із проваленим тестом, щоб ШІ міг відновити його, не звертаючись до файлової системи.
+buildFixTestsBatch — Групує файли для виправлення відповідно до заданого обсягу. Менші файли потрапляють у основну групу, а більші — у резерв на подальший прохід. Файл, який сам по собі перевищує обсяг, завжди отримує окремий запит з обрізанням.
+fixFailingTests — Визначає та виправляє провалених тестів, використовуючи можливості pi SDK для роботи з текстом та прямий запис у файли. Якщо всі тести вже проходять, він повертається одразу з кількістю 0.
 
 ## Гарантії поведінки
 
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- (специфічних машинно-виведених гарантій немає)

package/src/docs/gen-tests.md

@@ -3,7 +3,7 @@ type: JS Module
 title: gen-tests.mjs
 resource: npm/src/gen-tests.mjs
 docgen:
-  crc: 243806c4
+  crc: 0d24dc95
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/src/fix-tests.mjs

@@ -20,6 +20,7 @@ import { tmpdir } from 'node:os'
 import { join, relative } from 'node:path'
 import { env } from 'node:process'
 import { callText, MEMORY_ERROR_RE } from './lib/pi-client.mjs'
+import { budgetFor, capText, packBatch } from './lib/prompt-budget.mjs'
 import { findTestRules } from './gen-tests.mjs'
 import { parseFailingTests } from './coverage-per-file.mjs'
 import { resolveVitestRun } from './lib/vitest-shim.mjs'
@@ -108,6 +109,44 @@ function extractCode(text) {
   return text.slice(bodyStart + 1, end).trim()
 }
 
+/**
+ * Читає складники секції одного падаючого файлу для промпту.
+ * @param {{file: string, errors: string[]}} failure падаючий тест-файл
+ * @param {string} [dir] project root
+ * @returns {{file: string, errBlock: string, testCode: string, sourceCode: string|null}} сирі частини секції
+ */
+function readFailureParts({ file, errors }, dir) {
+  const absPath = dir ? join(dir, file) : file
+  const testCode = existsSync(absPath) ? readFileSync(absPath, 'utf8').slice(0, 6000) : '(файл не знайдено)'
+  // Heuristically find source file: strip tests/ prefix from path
+  const sourcePath = inferSourcePath(absPath)
+  const sourceCode =
+    sourcePath && existsSync(sourcePath) ? readFileSync(sourcePath, 'utf8').slice(0, MAX_SRC_BYTES) : null
+  return { file, errBlock: errors.join('\n\n'), testCode, sourceCode }
+}
+
+/**
+ * Складає секцію файлу з готових частин.
+ * @param {{file: string, errBlock: string, testCode: string, sourceCode: string|null}} parts частини з `readFailureParts`
+ * @returns {string} markdown-секція файлу
+ */
+function buildFileSection({ file, errBlock, testCode, sourceCode }) {
+  return [
+    `### \`${file}\``,
+    '',
+    '**Помилки:**',
+    '```',
+    errBlock,
+    '```',
+    '',
+    '**Поточний тест-файл:**',
+    '```js',
+    testCode,
+    '```',
+    ...(sourceCode ? ['', '**Source (для довідки, не міняй):**', '```js', sourceCode, '```'] : [])
+  ].join('\n')
+}
+
 /**
  * Builds a prompt to fix one failing test file.
  * Includes current file content so the LLM doesn't need file-read tools.
@@ -117,34 +156,17 @@ function extractCode(text) {
  */
 export function buildFixTestsPrompt(failures, dir) {
   const testRules = dir ? findTestRules(dir) : null
+  const sections = failures.map(f => buildFileSection(readFailureParts(f, dir)))
+  return buildPromptShell(sections, testRules)
+}
 
-  const sections = failures.map(({ file, errors }) => {
-    const absPath = dir ? join(dir, file) : file
-    const testCode = existsSync(absPath) ? readFileSync(absPath, 'utf8').slice(0, 6000) : '(файл не знайдено)'
-
-    // Heuristically find source file: strip tests/ prefix from path
-    const sourcePath = inferSourcePath(absPath)
-    const sourceCode =
-      sourcePath && existsSync(sourcePath) ? readFileSync(sourcePath, 'utf8').slice(0, MAX_SRC_BYTES) : null
-
-    const errBlock = errors.join('\n\n')
-
-    return [
-      `### \`${file}\``,
-      '',
-      '**Помилки:**',
-      '```',
-      errBlock,
-      '```',
-      '',
-      '**Поточний тест-файл:**',
-      '```js',
-      testCode,
-      '```',
-      ...(sourceCode ? ['', '**Source (для довідки, не міняй):**', '```js', sourceCode, '```'] : [])
-    ].join('\n')
-  })
-
+/**
+ * Обгортає секції файлів спільними правилами й інструкцією формату відповіді.
+ * @param {string[]} sections markdown-секції падаючих файлів
+ * @param {string|null} testRules конвенції тестів проєкту
+ * @returns {string} повний текст промпту
+ */
+function buildPromptShell(sections, testRules) {
   return [
     'Виправ падаючі unit-тести. Поверни ПОВНИЙ вміст КОЖНОГО виправленого тест-файлу.',
     '',
@@ -176,6 +198,54 @@ export function buildFixTestsPrompt(failures, dir) {
   ].join('\n')
 }
 
+/**
+ * Складає промпт під бюджет `budgetFor('fix')`: скільки файлів влазить —
+ * стільки в батч (найменші першими), решта — у `deferred` на наступний
+ * прохід. Файл, що сам-один перевищує бюджет, отримує соло-промпт із
+ * внутрішнім обрізанням (`fitToBudget`: спершу ріжеться source-довідка,
+ * потім vitest-помилки; сам тест-код захищений) — ніколи не скипається.
+ * @param {Array<{file: string, errors: string[]}>} failures падаючі тест-файли
+ * @param {string} [dir] project root
+ * @returns {{prompt: string, included: string[], deferred: string[]}} промпт + розподіл файлів
+ */
+export function buildFixTestsBatch(failures, dir) {
+  const testRules = dir ? findTestRules(dir) : null
+  const shellOverhead = buildPromptShell([], testRules).length
+  const sectionBudget = Math.max(1000, budgetFor('fix').maxPromptChars - shellOverhead)
+
+  const parts = failures.map(f => {
+    const p = readFailureParts(f, dir)
+    return { ...p, section: buildFileSection(p) }
+  })
+  const { included, deferred } = packBatch(
+    parts.map(p => ({ key: p.file, size: p.section.length })),
+    sectionBudget
+  )
+
+  if (included.length === 0) {
+    // Соло-режим: навіть найменший файл не влазить — жорстко обрізаємо
+    // нутрощі секції (source геть, помилки до чверті бюджету, тест-код —
+    // найцінніше — до половини), замість мовчазного skip
+    const smallest = parts.toSorted((a, b) => a.section.length - b.section.length)[0]
+    console.log(`  ⚠ ${smallest.file}: секція завелика (${smallest.section.length} симв.) — соло-виклик з обрізанням`)
+    const section = buildFileSection({
+      file: smallest.file,
+      errBlock: capText(smallest.errBlock, Math.floor(sectionBudget / 4)),
+      testCode: capText(smallest.testCode, Math.floor(sectionBudget / 2)),
+      sourceCode: null
+    })
+    return {
+      prompt: buildPromptShell([section], testRules),
+      included: [smallest.file],
+      deferred: failures.map(f => f.file).filter(f => f !== smallest.file)
+    }
+  }
+
+  const includedSet = new Set(included)
+  const sections = parts.filter(p => includedSet.has(p.file)).map(p => p.section)
+  return { prompt: buildPromptShell(sections, testRules), included, deferred }
+}
+
 /**
  * Parses fenced JavaScript blocks with file markers from LLM response.
  * @param {string} text LLM response text.
@@ -256,7 +326,8 @@ function writeFixedFiles(fixed, remaining, dir) {
  * @returns {Promise<{count: number, fixed: number, remaining: number}>} fix result summary
  */
 export async function fixFailingTests(dir, opts = {}) {
-  const callTextFn = opts.callTextFn ?? (prompt => callText(prompt, { model: MODEL, cwd: dir }))
+  const callTextFn =
+    opts.callTextFn ?? (prompt => callText(prompt, { model: MODEL, cwd: dir, maxTokens: budgetFor('fix').maxTokens }))
   const failures = opts.failures ?? (await getFailingTests(dir))
 
   if (failures.length === 0) return { count: 0, fixed: 0, remaining: 0 }
@@ -268,15 +339,29 @@ export async function fixFailingTests(dir, opts = {}) {
   console.log()
 
   let remaining = failures
-  for (let attempt = 1; attempt <= MAX_FIX_ATTEMPTS && remaining.length > 0; attempt++) {
-    if (attempt > 1) {
-      console.log(`\n🔄 Спроба ${attempt}/${MAX_FIX_ATTEMPTS}: залишилось ${remaining.length} файлів...\n`)
+  const attempts = new Map()
+  let prevDeferred = new Set()
+  for (;;) {
+    // Спроби рахуються per-file (лише коли файл реально був у батчі),
+    // тож deferred-черга не з'їдає ліміт файлів, які ще не пробували
+    const eligible = remaining
+      .filter(f => (attempts.get(f.file) ?? 0) < MAX_FIX_ATTEMPTS)
+      // Анти-starvation: відкладені минулого разу файли йдуть першими
+      .toSorted((a, b) => (prevDeferred.has(b.file) ? 1 : 0) - (prevDeferred.has(a.file) ? 1 : 0))
+    if (eligible.length === 0) break
+
+    const batch = buildFixTestsBatch(eligible, dir)
+    if (batch.deferred.length) {
+      console.log(
+        `  📦 батч: ${batch.included.length} файлів, відкладено на наступний прохід: ${batch.deferred.length}`
+      )
     }
+    for (const file of batch.included) attempts.set(file, (attempts.get(file) ?? 0) + 1)
+    prevDeferred = new Set(batch.deferred)
 
-    const prompt = buildFixTestsPrompt(remaining, dir)
     let response
     try {
-      response = await callTextFn(prompt)
+      response = await callTextFn(batch.prompt)
     } catch (error) {
       // memory-guard: не звичайна per-file помилка — RAM-стеля фіксована, продовжувати
       // до наступного файлу немає сенсу. Пробиваємо нагору до CLI, аби процес завершився.
@@ -292,7 +377,12 @@ export async function fixFailingTests(dir, opts = {}) {
       break
     }
 
-    writeFixedFiles(fixed, remaining, dir)
+    const includedSet = new Set(batch.included)
+    writeFixedFiles(
+      fixed,
+      eligible.filter(f => includedSet.has(f.file)),
+      dir
+    )
 
     remaining = await getFailingTests(dir)
   }

package/src/gen-tests.mjs

@@ -17,6 +17,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { spawnSync } from 'node:child_process'
 import { join, relative, dirname } from 'node:path'
 import { callText, MEMORY_ERROR_RE } from './lib/pi-client.mjs'
+import { budgetFor } from './lib/prompt-budget.mjs'
 import { resolveVitestRun } from './lib/vitest-shim.mjs'
 import { extractExportsWithComplexity } from './classify-exports.mjs'
 import { analyzeModule } from './lib/ast-analyze.mjs'
@@ -867,7 +868,7 @@ async function generateSharedHeader(ctx, dir, callTextFn) {
   try {
     const headerResp = await callTextFn(
       buildHeaderPrompt({ file, testFilePath, importPath, hasSideEffects, content, exports, testRules, astInfo }),
-      { cwd: dir }
+      { cwd: dir, maxTokens: budgetFor('header').maxTokens }
     )
     const header = extractCode(headerResp)
     if (header) return header
@@ -892,7 +893,7 @@ async function generateLocalBlock(opts) {
   const result = await generateBlockWithLoop(
     blockPrompt,
     callLocalFn,
-    {},
+    { maxTokens: budgetFor('block').maxTokens },
     header,
     dir,
     testDir,
@@ -920,7 +921,7 @@ async function generateCloudBlock(opts) {
   const result = await generateBlockWithLoop(
     blockPrompt,
     callTextFn,
-    { cwd: dir },
+    { cwd: dir, maxTokens: budgetFor('block').maxTokens },
     header,
     dir,
     testDir,
@@ -1109,7 +1110,7 @@ async function generateOneTest(fileInfo, dir, callTextFn) {
   const prompt = buildSingleFilePrompt(fileInfo, dir)
   let response
   try {
-    response = await callTextFn(prompt, { cwd: dir })
+    response = await callTextFn(prompt, { cwd: dir, maxTokens: budgetFor('single-file').maxTokens })
   } catch (error) {
     if (MEMORY_ERROR_RE.test(error.message ?? '')) throw error
     console.error(`  ✗ pi помилка для ${fileInfo.file}: ${error.message}`)
@@ -1181,7 +1182,9 @@ export async function generateTests(files, dir, opts = {}) {
 
   const callTextFn = opts.callText ?? callText
   const localModel = resolveLocalModel(opts)
-  const localFn = localModel ? prompt => callTextFn(prompt, { model: localModel, cwd: dir }) : null
+  const localFn = localModel
+    ? (prompt, opts = {}) => callTextFn(prompt, { ...opts, model: localModel, cwd: dir })
+    : null
 
   const mode = localFn ? `per-export (local:${localModel} + cloud)` : 'single-file (cloud)'
   console.log(`\n🤖 Генерую тести для ${files.length} файлів [${mode}]...\n`)

package/src/lib/docs/index.md

@@ -10,5 +10,6 @@ resource: npm/src/lib/
 | ------------------------------------- | --------- |
 | [ast-analyze.mjs](ast-analyze.md)     | JS Module |
 | [pi-client.mjs](pi-client.md)         | JS Module |
+| [prompt-budget.mjs](prompt-budget.md) | JS Module |
 | [runtime-probe.mjs](runtime-probe.md) | JS Module |
 | [vitest-shim.mjs](vitest-shim.md)     | JS Module |

package/src/lib/docs/pi-client.md

@@ -3,7 +3,7 @@ type: JS Module
 title: pi-client.mjs
 resource: npm/src/lib/pi-client.mjs
 docgen:
-  crc: 0aa22b9a
+  crc: e7f3471e
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98

package/src/lib/docs/prompt-budget.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: prompt-budget.mjs
+resource: npm/src/lib/prompt-budget.mjs
+docgen:
+  crc: 010265bd
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Слугує єдиною точкою правди для визначення ліміту символів промпту та стелі відповіді (`maxTokens`) залежно від типу задачі (наприклад, `gen-tests`, `fix-tests`). Це механізм захисту від надмірного розширення промпту. Надає функції для внутрішнього обрізання тексту (`fitToBudget`), що виключає низькопріоритетні частини промпту, щоб він вмістився у встановлений ліміт, а також для ефективного групування цілих одиниць вмісту (`packBatch`) для подальшої пакетної обробки.
+
+## Поведінка
+
+Поведінка
+budgetFor повертає встановлений ліміт символів для промпту та максимальну кількість токенів для заданого типу LLM-задачі.
+capText обрізає вхідний текст до заданого максимального розміру, зберігаючи його структуру з головною та хвостовою частинами, розділеними маркером.
+fitToBudget збирає частини промпту, обрізаючи або відкидаючи нижчопріоритетні частини доти, доки сумарний обсяг не вкладеться у заданий ліміт символів, при цьому найвищий пріоритет завжди захищено.
+packBatch групує одиниці (файли) у батчи, сортуючи їх за розміром, щоб вмістити якомога більше у межах заданого бюджету; одиниці, що не вмістилися, відкладаються для наступного проходу.
+
+## Публічний API
+
+budgetFor — надає бюджет, необхідний для певної категорії завдання.
+capText — безпечно укорочує текст, зберігаючи його початок, маркер та кінець.
+fitToBudget — розміщує блоки у межах заданого бюджету: спочатку зменшує вміст, а потім відкидає найнижчі за пріоритетом, поки обсяг не втиснеться. Найважливіший елемент завжди залишається повним.
+packBatch — згруповує файли для обробки: спочатку обирає найменші для оптимізації кількості виправлень за один раз. Якщо елемент занадто великий, він відкладається для окремої обробки, де застосовується жорсткіше обрізання.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/src/lib/docs/runtime-probe.md

@@ -3,7 +3,7 @@ type: JS Module
 title: runtime-probe.mjs
 resource: npm/src/lib/runtime-probe.mjs
 docgen:
-  crc: 31dd4fd6
+  crc: 6455ded4
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98

package/src/lib/docs/vitest-shim.md

@@ -3,7 +3,7 @@ type: JS Module
 title: vitest-shim.mjs
 resource: npm/src/lib/vitest-shim.mjs
 docgen:
-  crc: e08618cc
+  crc: 144cb026
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.97
@@ -18,7 +18,7 @@ docgen:
 
 VITEST_BIN — Абсолютний шлях до вбудованого виконуваного файлу Vitest.
 VITEST_SHIM_CONFIG — Абсолютний шлях до тимчасового файлу конфігурації Vitest, що забезпечує роботу збірки без встановлення Vitest у цільовому проекті.
-ensureVitestShim — Гарантує існування файлу конфігурації Vitest, записуючи мінімальний конфіг у тимчасову директорію, ігноруючи шляхи до `node_modules`.
+ensureVitestShim — Гарантує існування файлу конфігурації Vitest, записуючи мінімальний конфіг у тимчасову директорію, ігноруючи шляхи до `node_modules` та декларації типів `**/*.d.ts`.
 
 ## Публічний API
 
@@ -28,4 +28,4 @@ ensureVitestShim — Гарантує існування файлу конфіг
 
 ## Гарантії поведінки
 
-- Свідомо пропускає шляхи: `node_modules`.
+- Свідомо пропускає шляхи: `node_modules` і декларації типів `**/*.d.ts` (vitest 4 прибрав дефолтний exclude — без нього v8-remap падає на TS-синтаксисі декларацій).

package/src/lib/pi-client.mjs

@@ -1,5 +1,5 @@
 /**
- * Programmatic pi client via @earendil-works/pi-coding-agent SDK.
+ * Programmatic pi client via `@earendil-works/pi-coding-agent` SDK.
  * Replaces spawnSync('pi', ...) with direct in-process calls.
  *
  * Two modes:
@@ -9,7 +9,7 @@
  * Both retry transient connection failures (e.g. a shared local model server
  * that's momentarily busy under concurrent load) with exponential backoff
  * instead of failing the caller's file on the first hiccup. A memory-guard
- * rejection gets its own longer bounded backoff: oMLX обслуговує один промпт
+ * rejection gets its own longer bounded backoff: oMLX (local model server)
  * одночасно, тож відмова зазвичай відображає залишкову пам'ять попереднього
  * запиту, яку сервер вивільняє сам за десятки секунд. Лише після
  * `N_PI_MEMORY_RETRY_ATTEMPTS` невдач тіло запиту друкується в stdout і
@@ -23,15 +23,19 @@ import { setTimeout as sleep } from 'node:timers/promises'
 
 let _registry = null
 /**
- *
+ * Повертає або ініціалізує спільний model registry для поточного процесу.
+ * @returns {object} спільний registry
  */
-async function getRegistry() {
+function getRegistry() {
   if (_registry) return _registry
   _registry = ModelRegistry.create(AuthStorage.create())
   return _registry
 }
 
 const RETRYABLE_ERROR_RE = /connection error|ECONNREFUSED|ETIMEDOUT|fetch failed|network/i
+const OMLX_CODE_RE = /"(?:omlx_)?code"\s*:\s*"([^"]+)"/
+const OMLX_ESTIMATED_BYTES_RE = /"estimated_bytes"\s*:\s*(\d+)/
+const OMLX_LIMIT_BYTES_RE = /"limit_bytes"\s*:\s*(\d+)/
 /** Matches a local model server (e.g. oMLX) rejecting a prompt for lack of RAM. */
 export const MEMORY_ERROR_RE = /memory guard|memory limit|prefill would require/i
 const MAX_ATTEMPTS = Number(env.N_PI_RETRY_ATTEMPTS) || 4
@@ -52,9 +56,9 @@ const MEMORY_MAX_DELAY_MS = 60_000
  * @returns {{omlxCode?: string, estimatedBytes?: number, limitBytes?: number} | null} знайдені поля або `null`
  */
 function parseOmlxErrorDetails(message) {
-  const code = /"(?:omlx_)?code"\s*:\s*"([^"]+)"/.exec(message)?.[1]
-  const estimated = /"estimated_bytes"\s*:\s*(\d+)/.exec(message)?.[1]
-  const limit = /"limit_bytes"\s*:\s*(\d+)/.exec(message)?.[1]
+  const code = OMLX_CODE_RE.exec(message)?.[1]
+  const estimated = OMLX_ESTIMATED_BYTES_RE.exec(message)?.[1]
+  const limit = OMLX_LIMIT_BYTES_RE.exec(message)?.[1]
   if (!code && !estimated && !limit) return null
   const details = {}
   if (code) details.omlxCode = code
@@ -132,17 +136,41 @@ async function withRetry(fn, requestBody) {
   }
 }
 
+/**
+ * Стеля відповіді моделі для подвоєння на `stopReason: 'length'` — межа
+ * `maxTokens` реєстру для локальної моделі (див. `~/.pi/agent/models.json`).
+ */
+const MAX_TOKENS_CEILING = 32_768
+
+/**
+ * Обгортає `session.agent.streamFn`, додаючи per-call `maxTokens` у
+ * options LLM-виклику. SDK не має публічного per-call параметра
+ * (спайк: `session.prompt(text, options)` не прокидає options у loop
+ * config), але `options.maxTokens` у streamFn перекриває дефолт моделі —
+ * перевірено на дроті через myllm-проксі (`max_completion_tokens`
+ * змінюється).
+ * @param {object} session сесія з `createAgentSession`
+ * @param {number} maxTokens стеля відповіді для всіх викликів цієї сесії
+ * @returns {void}
+ */
+function applyMaxTokens(session, maxTokens) {
+  const orig = session.agent.streamFn
+  session.agent.streamFn = (model, context, options) => orig(model, context, { ...options, maxTokens })
+}
+
 /**
  * Sends a single prompt to pi in text mode (no tools) and returns the response.
  * Reads auth/model config from ~/.pi/ same as the CLI.
- * @param {string} prompt
- * @param {object} [opts]
- * @param {string} [opts.cwd]
- * @param {string} [opts.model] provider/model-id passed to pi (e.g. "openai/gpt-4o"); omit for pi default
- * @returns {Promise<string>}
+ * @param {string} prompt текст запиту для моделі
+ * @param {object} [opts] додаткові параметри виклику
+ * @param {string} [opts.cwd] робоча директорія для session
+ * @param {string} [opts.model] provider/model-id для pi (наприклад, "openai/gpt-4o"); без значення — default pi
+ * @param {number} [opts.maxTokens] стеля відповіді для цього виклику (перекриває дефолт моделі);
+ *   на `stopReason: 'length'` (обрізана генерація) виклик повторюється один раз із подвоєною стелею
+ * @returns {Promise<string>} текстова відповідь моделі
  */
 export async function callText(prompt, opts = {}) {
-  return withRetry(async () => {
+  const result = await withRetry(async () => {
     const cwd = opts.cwd ?? process.cwd()
     const sessionOpts = {
       tools: [],
@@ -154,35 +182,51 @@ export async function callText(prompt, opts = {}) {
       const slashIdx = opts.model.indexOf('/')
       const provider = slashIdx === -1 ? null : opts.model.slice(0, slashIdx)
       const modelId = slashIdx === -1 ? opts.model : opts.model.slice(slashIdx + 1)
-      const resolved = provider ? registry.find(provider, modelId) : null
+      const resolved = provider ? Reflect.apply(registry.find, registry, [provider, modelId]) : null
       sessionOpts.modelRegistry = registry
       sessionOpts.model = resolved ?? opts.model
     }
     const { session } = await createAgentSession(sessionOpts)
+    if (opts.maxTokens) applyMaxTokens(session, opts.maxTokens)
+    try {
+      await session.prompt(prompt)
 
-    await session.prompt(prompt)
-
-    const state = session.state
-    const last = state.messages.at(-1)
-    if (!last || last.role !== 'assistant') return ''
-    if (last.stopReason === 'error' || last.stopReason === 'aborted') {
-      throw new Error(`pi error: ${last.errorMessage ?? last.stopReason}`)
+      const state = session.state
+      const last = state.messages.at(-1)
+      if (!last || last.role !== 'assistant') return { text: '', truncated: false }
+      if (last.stopReason === 'error' || last.stopReason === 'aborted') {
+        throw new Error(`pi error: ${last.errorMessage ?? last.stopReason}`)
+      }
+      return {
+        text: last.content
+          .filter(c => c.type === 'text')
+          .map(c => c.text)
+          .join(''),
+        truncated: last.stopReason === 'length'
+      }
+    } finally {
+      session.dispose()
     }
-    return last.content
-      .filter(c => c.type === 'text')
-      .map(c => c.text)
-      .join('')
   }, prompt)
+
+  // Обрізана генерація зі зниженою стелею — не палимо retry-цикли колера
+  // на «invalid block», а один раз повторюємо з подвоєною стелею.
+  if (result.truncated && opts.maxTokens && opts.maxTokens < MAX_TOKENS_CEILING && !opts._lengthRetried) {
+    const doubled = Math.min(opts.maxTokens * 2, MAX_TOKENS_CEILING)
+    console.log(`  ⚠ відповідь обрізана (stopReason: length) — повтор із maxTokens ${opts.maxTokens} → ${doubled}`)
+    return callText(prompt, { ...opts, maxTokens: doubled, _lengthRetried: true })
+  }
+  return result.text
 }
 
 /**
  * Sends a prompt to pi in agent mode with full coding tools (read/write/bash/edit).
  * The agent writes test files directly — no need to parse output.
- * @param {string} prompt
- * @param {string} cwd project root where files should be written
- * @returns {Promise<void>}
+ * @param {string} prompt текст завдання для агента
+ * @param {string} cwd робоча директорія, куди агент може писати файли
+ * @returns {Promise<void>} проміс завершується після виконання агента
  */
-export async function callAgent(prompt, cwd) {
+export function callAgent(prompt, cwd) {
   return withRetry(async () => {
     const { session } = await createAgentSession({
       tools: ['read', 'write', 'edit', 'bash', 'grep', 'find', 'ls'],
@@ -190,6 +234,10 @@ export async function callAgent(prompt, cwd) {
       cwd
     })
 
-    await session.prompt(prompt)
+    try {
+      await session.prompt(prompt)
+    } finally {
+      session.dispose()
+    }
   }, prompt)
 }

package/src/lib/prompt-budget.mjs

@@ -0,0 +1,131 @@
+/**
+ * Спільний бюджет LLM-промптів (фаза 2 спеки
+ * `docs/specs/2026-07-04-omlx-prompt-budget.md`, Д3): єдина точка правди
+ * для ліміту символів промпту та стелі відповіді (`maxTokens`) за типом
+ * задачі. Захищає від класу проблем «безлімітна секція роздула промпт до
+ * memory guard» — кожен колер (gen-tests, fix-tests) бере бюджет звідси
+ * замість власних розрізнених констант.
+ *
+ * Дві незалежні утиліти:
+ * - `fitToBudget` — внутрішньопромптове обрізання: дропає/вкорочує
+ *   низькопріоритетні chunks, поки промпт не влізе в ліміт;
+ * - `packBatch` — батчинг цілих одиниць (файлів): скільки влазить зараз,
+ *   решта — у наступний прохід.
+ */
+
+/** Бюджети за типом задачі: ліміт символів промпту і стеля відповіді. */
+const BUDGETS = {
+  header: { maxPromptChars: 8000, maxTokens: 2048 },
+  block: { maxPromptChars: 40_000, maxTokens: 8192 },
+  'single-file': { maxPromptChars: 60_000, maxTokens: 16_384 },
+  fix: { maxPromptChars: 60_000, maxTokens: 16_384 }
+}
+
+/** Частка голови chunk-а, що лишається при обрізанні (решта — хвіст + маркер). */
+const TRUNCATE_HEAD_RATIO = 0.7
+/** Мінімальний розмір, до якого має сенс обрізати chunk (менше — просто дроп). */
+const MIN_TRUNCATED_CHARS = 400
+
+/**
+ * Повертає бюджет для типу задачі.
+ * @param {'header'|'block'|'single-file'|'fix'} taskKind тип LLM-задачі
+ * @returns {{maxPromptChars: number, maxTokens: number}} копія бюджету
+ */
+export function budgetFor(taskKind) {
+  const budget = BUDGETS[taskKind]
+  if (!budget) throw new Error(`prompt-budget: невідомий taskKind "${taskKind}"`)
+  return { ...budget }
+}
+
+/**
+ * Символьно-безпечне обрізання середини: голова + маркер + хвіст.
+ * @param {string} text вихідний текст
+ * @param {number} maxChars цільовий розмір
+ * @returns {string} обрізаний текст із маркером
+ */
+export function capText(text, maxChars) {
+  return truncateMiddle(text, maxChars)
+}
+
+/**
+ * Внутрішня реалізація `capText` (окреме ім'я — щоб `fitToBudget` не
+ * залежав від публічного контракту).
+ * @param {string} text вихідний текст
+ * @param {number} maxChars цільовий розмір
+ * @returns {string} обрізаний текст із маркером
+ */
+function truncateMiddle(text, maxChars) {
+  const chars = [...text]
+  if (chars.length <= maxChars) return text
+  const head = Math.floor(maxChars * TRUNCATE_HEAD_RATIO)
+  const tail = Math.max(0, maxChars - head)
+  const dropped = chars.length - head - tail
+  return `${chars.slice(0, head).join('')}\n...[обрізано ${dropped} символів]...\n${chars.slice(chars.length - tail).join('')}`
+}
+
+/**
+ * Вкладає chunks у бюджет: спершу обрізає, потім дропає найнижчі
+ * пріоритети, поки сумарний текст не влізе. Chunk із НАЙВИЩИМ
+ * пріоритетом (сама задача / останній user-запит) захищений — його
+ * текст не ріжеться і не дропається ніколи.
+ * @param {Array<{text: string, priority: number, label?: string}>} chunks частини промпту; нижчий priority ріжеться першим
+ * @param {number} maxChars бюджет символів на весь результат
+ * @returns {{text: string, dropped: string[]}} зібраний промпт + мітки скорочених/викинутих частин
+ */
+export function fitToBudget(chunks, maxChars) {
+  const parts = chunks.map((c, i) => ({ ...c, label: c.label ?? `chunk#${i}`, kept: true, out: c.text }))
+  const maxPriority = Math.max(...parts.map(p => p.priority))
+  const total = () => parts.filter(p => p.kept).reduce((sum, p) => sum + p.out.length + 1, 0)
+  const dropped = []
+
+  const candidates = parts.filter(p => p.priority < maxPriority).toSorted((a, b) => a.priority - b.priority)
+  // Прохід 1: обрізати кандидатів (від найнижчого пріоритету)
+  for (const part of candidates) {
+    if (total() <= maxChars) break
+    const overflow = total() - maxChars
+    const target = Math.max(MIN_TRUNCATED_CHARS, part.out.length - overflow)
+    if (part.out.length > target) {
+      part.out = truncateMiddle(part.out, target)
+      dropped.push(`${part.label} (обрізано)`)
+    }
+  }
+  // Прохід 2: дропнути кандидатів цілком, якщо обрізання не вистачило
+  for (const part of candidates) {
+    if (total() <= maxChars) break
+    part.kept = false
+    dropped.push(`${part.label} (видалено)`)
+  }
+
+  return {
+    text: parts
+      .filter(p => p.kept)
+      .map(p => p.out)
+      .join('\n'),
+    dropped
+  }
+}
+
+/**
+ * Пакує одиниці (файли) у бюджет: найменші першими, щоб максимізувати
+ * кількість виправлень за один виклик. Одиниця, що сама-одна перевищує
+ * бюджет, потрапляє в `deferred` — колер робить для неї соло-виклик із
+ * жорсткішим внутрішнім обрізанням (`fitToBudget`), а не мовчазний skip.
+ * @param {Array<{key: string, size: number}>} items одиниці з розмірами
+ * @param {number} maxChars бюджет символів на батч
+ * @returns {{included: string[], deferred: string[]}} ключі включених і відкладених одиниць
+ */
+export function packBatch(items, maxChars) {
+  const sorted = items.toSorted((a, b) => a.size - b.size)
+  const included = []
+  const deferred = []
+  let used = 0
+  for (const item of sorted) {
+    if (item.size + (included.length === 0 ? 0 : used) <= maxChars) {
+      included.push(item.key)
+      used += item.size
+    } else {
+      deferred.push(item.key)
+    }
+  }
+  return { included, deferred }
+}

package/src/lib/vitest-shim.mjs

@@ -51,7 +51,8 @@ export function ensureVitestShim() {
       `      include: ['**/*.{js,mjs,ts,vue}'],\n` +
       // Exclude test files that use non-vitest runners (bun:test, jest) from
       // the coverage scan so they don't cause import errors or skewed data.
-      `      exclude: ['**/node_modules/**'],\n` +
+      // *.d.ts: vitest 4 прибрав дефолтний exclude — v8-remap падає на TS-синтаксисі декларацій.
+      `      exclude: ['**/node_modules/**', '**/*.d.ts'],\n` +
       `    },\n` +
       `  },\n` +
       `})\n`