@7n/test 0.2.0

package/src/gen-tests.mjs

@@ -0,0 +1,143 @@
+/**
+ * Test generation via pi SDK (one file at a time).
+ *
+ * Uses callText() for text-mode generation: gets raw code back,
+ * extracts the ```js block, writes the file directly.
+ * No subprocess, no confirmation prompts.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { callText } from './lib/pi-client.mjs'
+
+const MAX_SRC_BYTES = 6000
+
+/** Test file candidates relative to source file. */
+function testCandidates(file) {
+  const base = file.replace(/\.[^.]+$/, '')
+  const lastSlash = base.lastIndexOf('/')
+  const name = lastSlash === -1 ? base : base.slice(lastSlash + 1)
+  const dir = lastSlash === -1 ? '' : base.slice(0, lastSlash)
+  return [`${base}.test.mjs`, `${base}.test.js`, ...(dir ? [`${dir}/tests/${name}.test.mjs`] : [])]
+}
+
+/**
+ * Extracts the first ```js...``` block from LLM text output.
+ * @param {string} text
+ * @returns {string}
+ */
+function extractCode(text) {
+  const match = text.match(/```(?:js|javascript|mjs|ts)?\n([\s\S]*?)```/)
+  return match ? match[1].trim() : ''
+}
+
+/**
+ * Builds a display-only summary prompt (used in tests).
+ * @param {Array<{file: string, pct: number, reason: string}>} files
+ * @param {string} dir
+ * @returns {string}
+ */
+export function buildGenTestsPrompt(files, dir) {
+  return files
+    .map(({ file, pct, reason }) => {
+      const absPath = join(dir, file)
+      let content = ''
+      if (existsSync(absPath)) {
+        content = readFileSync(absPath, 'utf8')
+        if (content.length > MAX_SRC_BYTES) content = content.slice(0, MAX_SRC_BYTES) + '\n...(truncated)'
+      }
+      return (
+        `### \`${file}\` (покриття: ${pct.toFixed(1)}%)\n` +
+        (reason ? `Причина: ${reason}\n\n` : '') +
+        (content ? `\`\`\`js\n${content}\n\`\`\`` : '(вміст недоступний)')
+      )
+    })
+    .join('\n\n')
+}
+
+function buildSingleFilePrompt(fileInfo, dir) {
+  const { file, pct, reason } = fileInfo
+  const absPath = join(dir, file)
+  let content = ''
+  if (existsSync(absPath)) {
+    content = readFileSync(absPath, 'utf8')
+    if (content.length > MAX_SRC_BYTES) content = content.slice(0, MAX_SRC_BYTES) + '\n...(truncated)'
+  }
+
+  const existingTestFile = testCandidates(file).find(c => existsSync(join(dir, c)))
+  let existingSection = ''
+  if (existingTestFile) {
+    const tc = readFileSync(join(dir, existingTestFile), 'utf8')
+    existingSection = `\n\nІснуючий тест (доповни):\n\`\`\`js\n${tc.slice(0, 3000)}\n\`\`\``
+  }
+
+  return [
+    `Напиши повний unit-тест для файлу \`${file}\` (покриття зараз ${pct.toFixed(1)}%).`,
+    reason ? `Причина: ${reason}` : '',
+    '',
+    'Правила (СУВОРО):',
+    '- Перший рядок: `import { vi, describe, it, expect, beforeEach } from "vitest"`',
+    '- Мокуй залежності: `vi.mock("module", () => ({ fn: vi.fn() }))` + `vi.mocked(fn)`',
+    '- НІКОЛИ `jest.*`, НІКОЛИ `require()`',
+    '- Лише поведінкові тести — НЕ тестуй приватні деталі реалізації',
+    '- Поверни ЛИШЕ код тесту у блоці ```js ... ``` — без пояснень',
+    '',
+    `Джерело (\`${file}\`):`,
+    '```js',
+    content || '(недоступно)',
+    '```',
+    existingSection
+  ]
+    .filter(Boolean)
+    .join('\n')
+}
+
+/**
+ * Generates a test for one file via pi text mode.
+ * @param {{file: string, pct: number, reason: string}} fileInfo
+ * @param {string} dir
+ * @param {Function} callTextFn
+ * @returns {Promise<string|null>} written test path or null
+ */
+async function generateOneTest(fileInfo, dir, callTextFn) {
+  const prompt = buildSingleFilePrompt(fileInfo, dir)
+
+  let response
+  try {
+    response = await callTextFn(prompt, { cwd: dir })
+  } catch (err) {
+    console.error(`  ✗ pi помилка для ${fileInfo.file}: ${err.message}`)
+    return null
+  }
+
+  const code = extractCode(response)
+  if (!code) {
+    console.error(`  ✗ pi не повернула код для ${fileInfo.file}`)
+    return null
+  }
+
+  const testPath = join(dir, testCandidates(fileInfo.file)[0])
+  writeFileSync(testPath, code + '\n', 'utf8')
+  console.log(`  ✓ Записано: ${relative(dir, testPath)}`)
+  return testPath
+}
+
+/**
+ * Generates tests for all given files (one pi call per file).
+ * @param {Array<{file: string, pct: number, reason: string}>} files
+ * @param {string} dir project root
+ * @param {{ callText?: Function, generateOne?: Function }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function generateTests(files, dir, opts = {}) {
+  if (files.length === 0) return
+
+  const callTextFn = opts.callText ?? callText
+  const generateOneFn = opts.generateOne ?? ((f, d) => generateOneTest(f, d, callTextFn))
+
+  console.log(`\n🤖 Генерую тести для ${files.length} файлів (pi SDK, по одному)...\n`)
+
+  for (const fileInfo of files) {
+    console.log(`  → ${fileInfo.file} (${fileInfo.pct.toFixed(1)}%)`)
+    await generateOneFn(fileInfo, dir)
+  }
+}

package/src/index.js

@@ -0,0 +1,21 @@
+import { resolve } from 'node:path'
+import { cwd as getCwd } from 'node:process'
+
+export async function run(args) {
+  const flags = (args ?? []).filter(a => a.startsWith('--'))
+  const positional = (args ?? []).filter(a => !a.startsWith('--'))
+  const [first] = positional
+
+  if (flags.includes('--help') || flags.includes('-h') || first === '--help' || first === '-h') {
+    console.log('Usage: n [directory] [--no-mutation]')
+    console.log('  Runs coverage analysis, generates missing tests, then mutation testing.')
+    console.log('  --no-mutation  Skip mutation testing phase.')
+    console.log('  Defaults to current directory when no argument is given.')
+    return 0
+  }
+
+  const dir = first ? resolve(first) : getCwd()
+  const noMutation = flags.includes('--no-mutation')
+  const { runAutoTest } = await import('./run.mjs')
+  return runAutoTest(dir, { noMutation })
+}

package/src/lib/pi-client.mjs

@@ -0,0 +1,61 @@
+/**
+ * Programmatic pi client via @earendil-works/pi-coding-agent SDK.
+ * Replaces spawnSync('pi', ...) with direct in-process calls.
+ *
+ * Two modes:
+ *   callText(prompt, model?)  — text-only, no tools, returns string
+ *   callAgent(prompt, cwd)    — coding tools enabled, writes files directly
+ */
+import { createAgentSession, SessionManager } from '@earendil-works/pi-coding-agent'
+
+/**
+ * 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>}
+ */
+export async function callText(prompt, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd()
+  const sessionOpts = {
+    tools: [],
+    sessionManager: SessionManager.inMemory(cwd),
+    cwd,
+    ...(opts.model ? { model: opts.model } : {})
+  }
+  const { session } = await createAgentSession(sessionOpts)
+
+  await session.prompt(prompt)
+
+  const state = session.state
+  const last = state.messages[state.messages.length - 1]
+  if (!last || last.role !== 'assistant') return ''
+  if (last.stopReason === 'error' || last.stopReason === 'aborted') {
+    throw new Error(`pi error: ${last.errorMessage ?? last.stopReason}`)
+  }
+  return last.content
+    .filter(c => c.type === 'text')
+    .map(c => c.text)
+    .join('')
+}
+
+/**
+ * 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>}
+ */
+export async function callAgent(prompt, cwd) {
+  const { session } = await createAgentSession({
+    tools: ['read', 'write', 'edit', 'bash', 'grep', 'find', 'ls'],
+    sessionManager: SessionManager.inMemory(cwd),
+    cwd
+  })
+
+  await session.prompt(prompt)
+}

package/src/run.mjs

@@ -0,0 +1,88 @@
+/**
+ * Main auto-test loop: coverage → assess → gen-tests → loop until max → mutation + fix.
+ *
+ * Phase 1 (loop, max 5 iterations):
+ *   1. Measure per-file line coverage via vitest+lcov.
+ *   2. pi CLI assesses which uncovered files actually need tests.
+ *   3. pi agent generates tests for those files.
+ *   4. Repeat until coverage maxes out or no improvement.
+ *
+ * Phase 2:
+ *   5. Mutation testing via existing coverage providers (requires .n-cursor.json#rules).
+ *   6. Auto-fix survived mutants via pi agent.
+ */
+import { measureCoveragePerFile, getUncoveredFiles } from './coverage-per-file.mjs'
+import { assessNeed } from './assess-need.mjs'
+import { generateTests } from './gen-tests.mjs'
+import { runCoverageSteps } from './coverage/coverage.mjs'
+import { withLock } from './scripts/utils/with-lock.mjs'
+
+const MAX_ITERATIONS = 5
+const COVERAGE_THRESHOLD = 80
+
+/**
+ * @param {string} dir absolute path to project root
+ * @param {{ noMutation?: boolean }} [opts]
+ * @returns {Promise<number>} exit code
+ */
+export async function runAutoTest(dir, opts = {}) {
+  console.log(`\n📁 ${dir}\n`)
+
+  let prevUncoveredCount = Infinity
+
+  for (let i = 1; i <= MAX_ITERATIONS; i++) {
+    console.log(`\n── Ітерація ${i}/${MAX_ITERATIONS}: coverage ──\n`)
+
+    const allFiles = await measureCoveragePerFile(dir)
+    if (allFiles.length === 0) {
+      console.log('⚠ Vitest coverage не повернула даних — перевір налаштування vitest.')
+      break
+    }
+
+    const uncovered = getUncoveredFiles(allFiles, COVERAGE_THRESHOLD)
+    const covered = allFiles.length - uncovered.length
+    const pct = ((covered / allFiles.length) * 100).toFixed(1)
+
+    console.log(`\n✓ Покриття: ${pct}% файлів (${covered}/${allFiles.length})`)
+
+    if (uncovered.length === 0) {
+      console.log('✓ Всі файли мають достатнє покриття — переходжу до мутантів.')
+      break
+    }
+
+    if (uncovered.length >= prevUncoveredCount) {
+      console.log('⚠ Покриття не покращилось після генерації тестів — зупиняю цикл.')
+      break
+    }
+    prevUncoveredCount = uncovered.length
+
+    console.log(`\n── Оцінюю ${uncovered.length} непокритих файлів (LLM) ──\n`)
+    const assessed = await assessNeed(uncovered, dir)
+    const needsTests = assessed.filter(f => f.needsTests)
+
+    if (needsTests.length === 0) {
+      console.log('✓ LLM вирішила: жоден непокритий файл не потребує unit-тестів.')
+      break
+    }
+
+    console.log(`\n→ Потребують тестів (${needsTests.length}):`)
+    for (const f of needsTests) {
+      console.log(`  • ${f.file} (${f.pct.toFixed(1)}%) — ${f.reason}`)
+    }
+
+    await generateTests(needsTests, dir)
+  }
+
+  if (opts.noMutation) {
+    console.log('\n── Мутаційне тестування пропущено (--no-mutation) ──\n')
+    return 0
+  }
+
+  console.log('\n── Мутаційне тестування + автофікс ──\n')
+  const code = await withLock('coverage', () => runCoverageSteps({ fix: true, cwd: dir }))
+  if (code === 0) {
+    console.log('\n♻️  Повторний coverage після агента...\n')
+    return withLock('coverage', () => runCoverageSteps({ fix: false, cwd: dir }))
+  }
+  return code
+}

package/src/scripts/lib/changed-files.mjs

@@ -0,0 +1,77 @@
+/**
+ * Збір змінених файлів для quick-режиму lint-оркестратора.
+ *
+ * Quick лінтить лише те, що змінено в робочому дереві: tracked-modified + staged
+ * (`git diff HEAD`) і нові untracked (`git ls-files --others --exclude-standard`).
+ * Видалені файли не повертаються. Поза git-репо або при помилці git — порожній список.
+ */
+import { spawnSync } from 'node:child_process'
+
+/**
+ * @param {string[]} args аргументи git
+ * @param {string} cwd корінь
+ * @returns {string[]} непорожні рядки stdout або [] при помилці
+ */
+function gitLines(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  if (r.status !== 0 || r.error) return []
+  return r.stdout
+    .split('\n')
+    .map(s => s.trim())
+    .filter(Boolean)
+}
+
+/**
+ * Relative-posix список змінених + untracked файлів робочого дерева.
+ * @param {string} [cwd] корінь репо
+ * @returns {string[]} унікальні шляхи (без видалених)
+ */
+export function collectChangedFiles(cwd = process.cwd()) {
+  const modified = gitLines(['diff', 'HEAD', '--name-only', '--diff-filter=ACMR'], cwd)
+  const untracked = gitLines(['ls-files', '--others', '--exclude-standard'], cwd)
+  return [...new Set([...modified, ...untracked])]
+}
+
+/**
+ * Визначає git base для scoped-перевірок без зовнішнього runtime-стану.
+ * Пріоритет: локальна `main`, потім `origin/main`; якщо обидві відсутні,
+ * повертає null і caller порівнює лише робоче дерево з HEAD.
+ * @param {string} [cwd] корінь репо
+ * @returns {string|null} merge-base commit або null
+ */
+export function resolveChangedBase(cwd = process.cwd()) {
+  for (const ref of ['main', 'origin/main']) {
+    const result = spawnSync('git', ['merge-base', 'HEAD', ref], { cwd, encoding: 'utf8' })
+    const base = result.status === 0 && !result.error ? result.stdout.trim() : ''
+    if (base) return base
+  }
+  return null
+}
+
+/**
+ * Список змінених + untracked файлів **відносно базового комміту**.
+ *
+ * `git diff <base>` (без `..`/`...`, без `HEAD`) порівнює base-комміт із поточним
+ * **робочим деревом** — тобто однаково ловить і закомічене від base, і staged, і
+ * незакомічені модифікації. Це гарантує однакову поведінку незалежно від того, чи
+ * зміни вже закомічені у worktree. Без `base` — fallback на `collectChangedFiles`
+ * (робоче дерево vs HEAD).
+ * @param {string|null} [base] базовий комміт
+ * @param {string} [cwd] корінь репо
+ * @returns {string[]} унікальні шляхи (без видалених)
+ */
+export function collectChangedFilesSince(base, cwd = process.cwd()) {
+  if (!base) return collectChangedFiles(cwd)
+  // Fail-closed: недосяжний base (rebase/force-update/shallow prune) інакше дав би `git diff`
+  // exit 128 → порожній список → gate мовчки пройшов би без перевірки. Краще явна помилка.
+  const verify = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${base}^{commit}`], { cwd, encoding: 'utf8' })
+  if (verify.status !== 0 || verify.error) {
+    throw new Error(
+      `collectChangedFilesSince: base-комміт «${base}» недосяжний у ${cwd} ` +
+        '(rebase/force-update?) — coverage --changed не може визначити scope'
+    )
+  }
+  const changed = gitLines(['diff', base, '--name-only', '--diff-filter=ACMR'], cwd)
+  const untracked = gitLines(['ls-files', '--others', '--exclude-standard'], cwd)
+  return [...new Set([...changed, ...untracked])]
+}

package/src/scripts/lib/read-n-cursor-config-lite.mjs

@@ -0,0 +1,59 @@
+/**
+ * Light read-only `.n-cursor.json` reader для standalone `check.mjs` invocation.
+ *
+ * НЕ робить auto-rules detection, merge, schema sync — це справа повного `readConfig` у CLI.
+ * Тут лише: прочитати файл (якщо є), повернути `{ rules: string[], disableRules: string[] }`.
+ *
+ * Спостереження whitelist:
+ *   - якщо `.n-cursor.json` НЕМАЄ → правило вважається enabled (поведінка "open by default"),
+ *     щоб `bun rules/<id>/check.mjs` з будь-якої тимчасової директорії працювало для debug.
+ *   - якщо файл є з `rules:[…]`, але правила там немає → правило не enabled.
+ *   - якщо правило в `disable-rules` → не enabled, навіть якщо у `rules:[…]`.
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const CONFIG_FILE = '.n-cursor.json'
+
+/**
+ * @typedef {object} LiteConfig
+ * @property {boolean} exists чи існує .n-cursor.json у поточному каталозі
+ * @property {string[]} rules id правил з whitelist (порожній якщо файл відсутній)
+ * @property {string[]} disableRules id правил, явно вимкнених у `disable-rules`
+ */
+
+/**
+ * @param {string} [cwd] корінь, у якому шукати .n-cursor.json (default — `process.cwd()`)
+ * @returns {Promise<LiteConfig>} стан конфігу
+ */
+export async function readNCursorConfigLite(cwd = process.cwd()) {
+  const configPath = join(cwd, CONFIG_FILE)
+  if (!existsSync(configPath)) {
+    return { exists: false, rules: [], disableRules: [] }
+  }
+  const raw = await readFile(configPath, 'utf8')
+  /** @type {{ rules?: unknown, ['disable-rules']?: unknown }} */
+  const parsed = JSON.parse(raw)
+  const rules = Array.isArray(parsed.rules) ? parsed.rules.filter(r => typeof r === 'string') : []
+  const disableRules = Array.isArray(parsed['disable-rules'])
+    ? parsed['disable-rules'].filter(r => typeof r === 'string')
+    : []
+  return { exists: true, rules, disableRules }
+}
+
+/**
+ * Чи активне правило згідно з конфігом.
+ *   - файл відсутній → true (open by default для debug);
+ *   - правило явно в `disable-rules` → false;
+ *   - правило у `rules` → true;
+ *   - інакше → false.
+ * @param {LiteConfig} config розпарсений lite-конфіг
+ * @param {string} ruleId id правила (= basename каталогу)
+ * @returns {boolean} чи запускати правило
+ */
+export function isRuleEnabled(config, ruleId) {
+  if (!config.exists) return true
+  if (config.disableRules.includes(ruleId)) return false
+  return config.rules.includes(ruleId)
+}

package/src/scripts/utils/lock-cache-dir.mjs

@@ -0,0 +1,37 @@
+/**
+ * Обчислення директорії стану `withLock` (lock + dedup), СПІЛЬНОЇ для всіх git-worktree.
+ *
+ * Лок-стан (`lock/owner.json`, `result.json`) має бути один на головний checkout
+ * і всі linked-worktree. Інакше важкі команди (eslint/oxlint/jscpd, conftest,
+ * hadolint, per-rule fix), запущені в різних worktree, НЕ серіалізуються —
+ * кожен worktree має власний `node_modules/.cache/`, локи одне одного не бачать,
+ * і паралельний eslint перевантажує CPU/диск на macOS.
+ *
+ * `git rev-parse --git-common-dir` повертає той самий `.git` головного репо з
+ * будь-якого worktree, тож стан кладемо під `<git-common-dir>/n-cursor/<key>`
+ * (всередині `.git` — спільне, ніколи не трекається, переживає `bun i`).
+ * Поза git-репо (git недоступний / каталог не репо) — fallback на per-checkout
+ * `node_modules/.cache/n-cursor/<key>`, як було історично.
+ */
+import { spawnSync } from 'node:child_process'
+import { join, resolve } from 'node:path'
+
+/**
+ * @param {string} key ключ локу (`lint-ga`, `fix-bun`, …)
+ * @param {{cwd?:string, spawn?:typeof import('child_process').spawnSync}} [opts] робоча директорія та sync-виклик git (ін'єкція для тестів)
+ * @returns {string} абсолютний шлях до директорії стану локу для цього ключа
+ */
+export function resolveLockCacheDir(key, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd()
+  const spawn = opts.spawn ?? spawnSync
+
+  const r = spawn('git', ['rev-parse', '--git-common-dir'], { cwd, encoding: 'utf8' })
+  const commonDir = r.status === 0 && !r.error ? r.stdout.trim() : ''
+
+  if (commonDir === '') {
+    return join(cwd, 'node_modules/.cache/n-cursor', key)
+  }
+  // commonDir буває відносним (`.git` з кореня) або абсолютним (linked-worktree):
+  // resolve проти cwd дає однаковий абсолютний `<main>/.git` в обох випадках.
+  return join(resolve(cwd, commonDir), 'n-cursor', key)
+}

package/src/scripts/utils/with-lock.mjs

@@ -0,0 +1,149 @@
+/**
+ * Guard-механізм: атомарний lock + dedup для важких команд.
+ * Алгоритм: mkdirSync-based lock, перевірка живості PID, sha256-dedup з TTL.
+ */
+import * as fs from 'node:fs'
+import { join } from 'node:path'
+import * as os from 'node:os'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { resolveLockCacheDir } from './lock-cache-dir.mjs'
+import { worktreeFingerprint } from './worktree-fingerprint.mjs'
+
+const DEFAULTS = {
+  ttl: 600_000,
+  staleThreshold: 1_800_000,
+  waitTimeout: 1_200_000,
+  pollInterval: 1500,
+  onWaitTimeout: 'run-unlocked'
+}
+
+/**
+ * Чи процес із заданим PID ще живий на поточному host.
+ * @param {number} pid ідентифікатор процесу з owner.json
+ * @returns {boolean} true, якщо process.kill(pid, 0) не кинув помилку
+ */
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Повертає функцію, що знімає lock-директорію.
+ * @param {string} lockDir абсолютний шлях до lock-директорії
+ * @returns {() => void} release-колбек для finally/signal handler
+ */
+function makeRelease(lockDir) {
+  return () => fs.rmSync(lockDir, { recursive: true, force: true })
+}
+
+/**
+ * Чи можна пропустити повторний прогін за кешованим result.json.
+ * @param {{exitCode:number, fingerprint:string|null, finishedAt:number}} result попередній результат з result.json
+ * @param {string|null} fingerprint поточний fingerprint робочого дерева
+ * @param {number} ttl TTL дедуплікації в мілісекундах
+ * @returns {boolean} true, якщо попередній успішний прогін можна повторно використати
+ */
+export function shouldDedup(result, fingerprint, ttl) {
+  if (result.exitCode !== 0) return false
+  if (fingerprint === null || result.fingerprint !== fingerprint) return false
+  if (Date.now() - result.finishedAt >= ttl) return false
+  return true
+}
+
+/**
+ * Серіалізує важку команду через атомарний lock і dedup за fingerprint.
+ * @param {string} key ключ локу (наприклад `lint-ga`, `fix-bun`)
+ * @param {() => number | Promise<number>} runFn основна робота; повертає exit code
+ * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, onWaitTimeout?:'run-unlocked'|'fail', cacheDir?:string, getFingerprint?:() => string | null}} [opts] TTL, шлях кешу, поведінка на таймаут (default `run-unlocked`; `fail` = fail-closed) та override fingerprint
+ * @returns {Promise<number>} exit code виконаної або дедуплікованої команди
+ */
+export async function withLock(key, runFn, opts = {}) {
+  const { ttl, staleThreshold, waitTimeout, pollInterval, onWaitTimeout } = { ...DEFAULTS, ...opts }
+  const getFingerprint = opts.getFingerprint ?? worktreeFingerprint
+  const cacheDir = opts.cacheDir ?? resolveLockCacheDir(key)
+  const lockDir = join(cacheDir, 'lock')
+  const ownerFile = join(lockDir, 'owner.json')
+  const resultFile = join(cacheDir, 'result.json')
+  const release = makeRelease(lockDir)
+
+  const fingerprint = getFingerprint()
+  fs.mkdirSync(cacheDir, { recursive: true })
+
+  const loopStart = Date.now()
+
+  while (true) {
+    if (Date.now() - loopStart >= waitTimeout) {
+      if (onWaitTimeout === 'fail') {
+        throw new Error(`${key}: не вдалося взяти лок за ${waitTimeout / 60_000} хв — fail-closed`)
+      }
+      console.error(`⚠️ ${key}: чекав ${waitTimeout / 60_000} хв — запускаю без локу`)
+      return await runFn()
+    }
+    try {
+      fs.mkdirSync(lockDir)
+      fs.writeFileSync(
+        ownerFile,
+        JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: Date.now(), fingerprint })
+      )
+      break
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error
+      let owner
+      try {
+        owner = JSON.parse(fs.readFileSync(ownerFile, 'utf8'))
+      } catch {
+        fs.rmSync(lockDir, { recursive: true, force: true })
+        continue
+      }
+      const stale =
+        Date.now() - owner.startedAt > staleThreshold || (os.hostname() === owner.host && !isAlive(owner.pid))
+      if (stale) {
+        console.error(`🧹 ${key}: знайдено застарілий лок — очищаю`)
+        fs.rmSync(lockDir, { recursive: true, force: true })
+        continue
+      }
+      console.error(`⏳ ${key}: чекаю, лок тримає pid ${owner.pid}…`)
+      await sleep(pollInterval)
+    }
+  }
+
+  console.error(`🔒 ${key}: лок взято`)
+
+  try {
+    const raw = fs.readFileSync(resultFile, 'utf8')
+    const result = JSON.parse(raw)
+    if (shouldDedup(result, fingerprint, ttl)) {
+      const elapsed = Math.round((Date.now() - result.finishedAt) / 1000)
+      console.error(`♻️ ${key}: те саме дерево, ${elapsed}с тому — пропускаю`)
+      release()
+      return 0
+    }
+  } catch {
+    /* result.json не існує або пошкоджений */
+  }
+
+  // Після release лок ре-рейзиться той самий сигнал: `once` вже зняв обробник,
+  // тож процес завершується дефолтною дією з коректним кодом (130/143)
+  const onSignal = signal => {
+    release()
+    process.kill(process.pid, signal)
+  }
+  process.once('SIGINT', onSignal)
+  process.once('SIGTERM', onSignal)
+
+  let code
+  try {
+    code = await runFn()
+    fs.writeFileSync(resultFile, JSON.stringify({ finishedAt: Date.now(), exitCode: code, fingerprint }))
+  } finally {
+    process.off('SIGINT', onSignal)
+    process.off('SIGTERM', onSignal)
+    release()
+  }
+
+  return code
+}

package/src/scripts/utils/worktree-fingerprint.mjs

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+
+/**
+ * Fingerprint поточного стану git-робочого дерева.
+ * @param {typeof import('child_process').spawnSync} [spawn] sync-виклик git (ін'єкція для тестів)
+ * @returns {string|null} sha256-hex (64 символи) або null, якщо не в git-репо
+ */
+export function worktreeFingerprint(spawn = spawnSync) {
+  /**
+   * @param {string[]} args аргументи підкоманди git
+   * @returns {string} stdout git-команди
+   */
+  function git(args) {
+    const r = spawn('git', args, { encoding: 'utf8' })
+    if (r.status !== 0 || r.error) throw new Error(`git ${args[0]} failed`)
+    return r.stdout
+  }
+
+  try {
+    const commitHash = git(['rev-parse', 'HEAD']).trim()
+    const diffText = git(['diff', 'HEAD'])
+    // -z: NUL-розділення без C-екранування. Без нього імена з не-ASCII символами
+    // повертаються у `"..."` формі, і `git hash-object` не знаходить файл → throw → fingerprint=null.
+    const untrackedRaw = git(['ls-files', '-z', '--others', '--exclude-standard'])
+    const untrackedFiles = untrackedRaw.split('\0').filter(Boolean)
+    const pairs = untrackedFiles.map(f => `${f}:${git(['hash-object', f]).trim()}`).toSorted()
+    const raw = [commitHash, diffText, ...pairs].join('\n')
+    return createHash('sha256').update(raw).digest('hex')
+  } catch {
+    return null
+  }
+}