@nitra/cursor 3.22.0 → 3.23.1

package/scripts/dispatcher/lib/docs/events.md

@@ -0,0 +1,182 @@
+# events.mjs — WAL-журнал подій `flow`
+
+## Огляд
+
+Модуль `events.mjs` реалізує **append-only WAL** (Write-Ahead Log) журнал подій для підсистеми `flow` (специфікація §4.1.2, §9). Журнал зберігається у sibling-файлі поряд із checkout-каталогом worktree: для `…/.worktrees/feat-x` файл подій має шлях `…/.worktrees/feat-x.events.jsonl` (формат JSON Lines — по одному JSON-об'єкту на рядок).
+
+Журнал є **єдиним** для двох категорій подій:
+
+- **Переходи стану** flow (наприклад, `step_started`, `step_completed`, `blocked` тощо).
+- **Облік API-викликів** (події типу `api_call`).
+
+Ключові інваріанти та властивості:
+
+- **Append-only**. Нові записи лише дописуються в кінець файлу. Це робить журнал **краш-безпечнішим** за повний перезапис: якщо аварія сталася посередині запису рядка, ушкоджений (торваний) рядок при читанні **толерується** — він просто пропускається, а решта журналу залишається валідною.
+- **WAL-інваріант**: подію слід дописати в журнал **ДО** оновлення високорівневого статусу у snapshot-файлі `.flow.json`. За дотримання цього інваріанта відповідає сторонній викликач — `state-store.recordTransition`.
+- **Усі шляхи — абсолютні**. Модуль явно валідує кожен вхідний `path` і кидає помилку для відносних шляхів (правило проекту `no-relative-fs-path`).
+
+Модуль використовує **синхронні** Node.js fs-API (`appendFileSync`, `readFileSync`, `existsSync`), що адекватно для коротких записів короткоживучих CLI/dispatcher-сценаріїв і гарантує лінійний порядок без race-conditions у межах одного процесу.
+
+## Експорти / API
+
+Усі експорти — іменовані ESM-функції.
+
+| Експорт                                | Тип                                         | Призначення                                                                                         |
+| -------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `flowEventsPath(worktreeDir)`          | `(string) => string`                        | Обчислити абсолютний шлях sibling-журналу для checkout-каталогу worktree.                           |
+| `appendEvent(eventsPath, event, now?)` | `(string, object, () => number?) => object` | Дописати одну подію (зі стампом `at`) у журнал; повертає фактично записаний об'єкт.                 |
+| `readEvents(eventsPath)`               | `(string) => object[]`                      | Прочитати всі події з журналу в порядку запису; відсутній файл → `[]`; невалідні рядки ігноруються. |
+
+Default-експорт відсутній.
+
+## Функції
+
+### `flowEventsPath(worktreeDir)`
+
+**Сигнатура.** `function flowEventsPath(worktreeDir: string): string`
+
+**Параметри.**
+
+- `worktreeDir` — **абсолютний** шлях до checkout-каталогу worktree (наприклад, `/repo/.worktrees/feat-x`).
+
+**Повертає.** Абсолютний шлях до sibling-файлу журналу подій: каталог-батько (`dirname(worktreeDir)`) + базове ім'я worktree + суфікс `.events.jsonl`. Наприклад, для входу `/repo/.worktrees/feat-x` повертається `/repo/.worktrees/feat-x.events.jsonl`.
+
+**Помилки.** Якщо `worktreeDir` не є абсолютним шляхом — кидає `Error` з префіксом `flowEventsPath: очікується абсолютний шлях …`.
+
+**Side effects.** Жодних. Чиста функція (працює лише з рядками через `path`-утиліти).
+
+**Деталі реалізації.** Використовує `dirname` і `basename` з `node:path`, що робить функцію крос-платформною щодо роздільників шляху (хоча в результаті завжди формується шлях у стилі поточної ОС).
+
+### `appendEvent(eventsPath, event, now?)`
+
+**Сигнатура.** `function appendEvent(eventsPath: string, event: object, now?: () => number): object`
+
+**Параметри.**
+
+- `eventsPath` — **абсолютний** шлях до файлу `.events.jsonl`.
+- `event` — об'єкт події, наприклад `{ type: 'step_started', step: 2 }`. Може містити довільні поля.
+- `now` — _необов'язкова_ фабрика часу, що повертає мілісекунди (за замовчуванням `Date.now`). Дозволяє **ін'єкцію** детермінованого часу у тестах.
+
+**Повертає.** Фактично записаний запис у формі `{ at, ...event }`, де `at` — ISO-рядок часу (`new Date(now()).toISOString()`). Поля переданого `event` накладаються **поверх** `at`, тому якщо в `event` уже є власне поле `at`, воно перепише згенероване (це може бути корисно для бек-філу/міграцій).
+
+**Side effects.**
+
+- **Файлова система**: дописує один рядок (`JSON.stringify(record) + '\n'`) у `eventsPath` через `appendFileSync` із кодуванням `utf8`. Якщо файлу не існує — він **створюється** автоматично (`appendFileSync` діє як append-or-create).
+- **Жодних мережевих, БД- чи stdout-ефектів.**
+
+**Помилки.**
+
+- Якщо `eventsPath` не абсолютний — кидає `Error` з префіксом `appendEvent: очікується абсолютний шлях …`.
+- Будь-яка помилка `appendFileSync` (відсутня тека-батько, права, EROFS тощо) пробрасується назовні як є.
+
+**Краш-безпека.** Якщо процес аварійно завершиться під час `appendFileSync`, у файлі може залишитися **частково записаний останній рядок**. Це навмисно толерується читачем (`readEvents`), тому WAL не вимагає fsync чи двофазного запису для базової стійкості.
+
+### `readEvents(eventsPath)`
+
+**Сигнатура.** `function readEvents(eventsPath: string): object[]`
+
+**Параметри.**
+
+- `eventsPath` — **абсолютний** шлях до файлу `.events.jsonl`.
+
+**Повертає.** Масив об'єктів-подій у тому самому порядку, в якому вони були дописані (хронологічний порядок append-only). Якщо файлу немає — повертається `[]`.
+
+**Side effects.** Лише читання файлу (`readFileSync`, `existsSync`). Файл **не модифікується** і **не створюється**.
+
+**Поведінка при пошкодженнях.**
+
+- Порожні рядки (включно з трейлінговим `\n` після останнього запису) **відфільтровуються** через `line.trim() !== ''`.
+- Кожен непорожній рядок намагається парситися як JSON. Якщо `JSON.parse` кидає виняток (наприклад, торваний останній рядок після краху під час `appendFileSync`), цей рядок **пропускається** (через `flatMap` + порожній масив у `catch`), і читання продовжується далі. Інші рядки повертаються нормально.
+- Це і є **append-only толерантність**: один пошкоджений запис не валить весь журнал.
+
+**Помилки.** Якщо `eventsPath` не абсолютний — кидає `Error` з префіксом `readEvents: очікується абсолютний шлях …`. Інші помилки fs (наприклад, EACCES при `readFileSync`) пробрасуються.
+
+**Складність.** Лінійна за розміром файлу (`O(N)`), читання здійснюється повністю в пам'ять. Для дуже довгих журналів варто розглянути потокове читання — модуль навмисно тримає просту синхронну реалізацію.
+
+## Залежності
+
+### Зовнішні (Node.js stdlib)
+
+- `node:fs`
+  - `appendFileSync` — атомарний (на рівні syscall) append одного запису.
+  - `existsSync` — перевірка наявності файлу перед читанням.
+  - `readFileSync` — повне читання файлу журналу.
+- `node:path`
+  - `basename`, `dirname`, `isAbsolute`, `join` — формування sibling-шляху і валідація абсолютних шляхів.
+
+### Внутрішні
+
+Модуль **не має внутрішніх імпортів**. Він — найнижчий рівень WAL-абстракції, на який спираються інші частини dispatcher/flow:
+
+- `state-store.recordTransition` (споживач) — викликає `appendEvent` перед оновленням `.flow.json` (забезпечення WAL-інваріанта).
+- Будь-який код обліку `api_call`-подій також використовує `appendEvent`.
+- Читачі (наприклад, інструменти діагностики, відновлення стану, аналітики) використовують `readEvents`.
+
+## Потік виконання / Використання
+
+### Типовий життєвий цикл подій worktree
+
+1. **Обчислення шляху журналу** — один раз на сесію/процес:
+   ```js
+   import { flowEventsPath, appendEvent, readEvents } from './events.mjs'
+   const eventsPath = flowEventsPath('/repo/.worktrees/feat-x')
+   // → '/repo/.worktrees/feat-x.events.jsonl'
+   ```
+2. **Дозапис події під час переходу стану** (через `state-store.recordTransition`, що дотримується WAL-інваріанта):
+   ```js
+   appendEvent(eventsPath, { type: 'step_started', step: 2 })
+   // потім: оновити .flow.json
+   ```
+3. **Дозапис обліку API-виклику** (тим самим API, у тому ж файлі):
+   ```js
+   appendEvent(eventsPath, {
+     type: 'api_call',
+     provider: 'anthropic',
+     model: 'claude-opus',
+     tokens: 1234
+   })
+   ```
+4. **Читання історії** (наприклад, для відновлення стану або аудиту):
+   ```js
+   const events = readEvents(eventsPath)
+   for (const ev of events) {
+     // обробка ev.at, ev.type, …
+   }
+   ```
+
+### Сценарій краху
+
+1. `appendFileSync` починає писати рядок, процес гине посеред запису.
+2. Файл містить N−1 валідних рядків + один торваний (наприклад, без `}` і `\n` у кінці).
+3. На наступному старті `readEvents`:
+   - відфільтрує порожні рядки;
+   - спробує `JSON.parse` для кожного непорожнього;
+   - на торваному останньому отримає виняток → `flatMap` поверне `[]` для нього → запис **пропускається**;
+   - решта N−1 подій нормально потрапить у результат.
+4. Дані до моменту краху збережено; пошкоджений запис вважається втраченим — це прийнятна семантика append-only WAL.
+
+### Інваріанти, що накладає модуль
+
+- **Усі шляхи — абсолютні** (`isAbsolute` перевірка у всіх трьох експортах).
+- **Кодування файлу — UTF-8** (явно вказано як в `appendFileSync`, так і в `readFileSync`).
+- **Формат рядка — однорядковий JSON + `\n`** (jsonl).
+- **`at` — ISO-8601-рядок UTC** (через `Date.prototype.toISOString`).
+- **Порядок збереження — порядок дозапису** (нативна семантика append-only).
+
+### Чого модуль свідомо не робить
+
+- Не реалізує **rotation / compaction** журналу — це відповідальність вищих рівнів або інфраструктури worktree.
+- Не виконує **fsync** після кожного append — покладається на ОС-кеш та append-only толерантність читача.
+- Не валідує **схему події** — приймає будь-який `object` (контрактом структури подій відає `flow`-специфікація і споживачі).
+- Не обробляє **багатопроцесний конкурентний доступ** — для одного worktree передбачається один пишучий процес; для читача конкурентність безпечна, оскільки `appendFileSync` атомарно дозаписує цілий буфер.
+
+## Rebuild Test
+
+Документація достатня, щоб переписати модуль з нуля:
+
+- три іменовані експорти з точними сигнатурами;
+- формула sibling-шляху (`dirname` + `basename` + `.events.jsonl`);
+- WAL-інваріант і його носій (`state-store.recordTransition`);
+- формат запису (`{ at: ISO, ...event }`, `JSON.stringify` + `\n`, кодування UTF-8);
+- стратегія читання (`existsSync`-гард → split `\n` → фільтр порожніх → `JSON.parse` у `try/catch` + `flatMap`);
+- правила валідації абсолютних шляхів і повідомлення про помилки.

package/scripts/dispatcher/lib/docs/executor.md

@@ -0,0 +1,190 @@
+# executor.mjs
+
+## Огляд
+
+Модуль `executor.mjs` — це **Фаза 3 (Ф3) диспетчера** з flow-специфікації: він покроково виконує план, що раніше зібрав `planner`, і просуває стан через журнал подій. Відповідно до спеки (§3 Ф3), кожен крок плану надсилається в субагент через **мікропромпт зі стану** — субагент бачить лише поточний крок, критерії приймання й, опційно, останню помилку (без історії переписки чи історії інших кроків).
+
+Базові інваріанти, які реалізовано в коді:
+
+- **Мікропромпт зі стану** (§3 Ф3): субагент отримує тільки поточний крок + критерії + останню помилку, а не повний контекст ланцюга кроків.
+- **Commit лише після зеленого `verify`** (§4.1.7): жоден repair-прохід не комітиться, тому `HEAD` git-репозиторію завжди вказує на останній «зелений» крок плану.
+- **Repair обмежений `maxRepairAttempts`** (за замовчуванням 3): коли спроби вичерпано, виконання переходить у режим `blocked-on-human` (HITL, §4.2) і записує питання в `state.hitl`.
+
+Усі побічні дії (запуск субагента, верифікація, commit, годинник) **інжектуються** через об’єкт `deps`. Це робить модуль повністю детермінованим і тестованим: реальний LLM, git і ворота (gates) не викликаються з нього напряму.
+
+## Експорти / API
+
+Модуль експортує три функції (ESM, named exports):
+
+| Експорт       | Тип        | Призначення                                                                                                                          |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `microprompt` | `function` | Чиста функція побудови тексту мікропромпта для конкретного кроку плану.                                                              |
+| `patchStep`   | `function` | Чиста функція, що повертає новий обʼєкт стану з оновленим кроком за індексом (immutable update).                                     |
+| `executePlan` | `async`    | Головна функція: читає стан, ітерує план, дергає `runner`/`verify`/`commit`, записує транзиції стану та повертає підсумковий статус. |
+
+Default-експорту немає.
+
+## Функції
+
+### `microprompt(step, state)`
+
+**Сигнатура:**
+
+```js
+function microprompt(step, state) → string
+```
+
+**Параметри:**
+
+- `step` — обʼєкт поточного кроку плану. Очікувані поля:
+  - `step` (`number`) — номер кроку (для людини).
+  - `task` (`string`) — формулювання задачі кроку.
+  - `acceptance` (`string`, опційно) — критерії приймання.
+  - `hint` (`string`, опційно) — підказка від людини (HITL).
+  - `last_error` (`string`, опційно) — останній текст помилки `verify` для repair-спроби.
+- `state` — поточний стан flow. Використовується лише поле `state.branch` для рядка «Гілка: …» (якщо немає — підставляється `'—'`).
+
+**Повертає:** рядок-промпт, який скріплює кілька рядків через `\n`:
+
+1. Заклик зробити **рівно** один крок плану з нагадуванням про Iron Law of TDD (спершу падаючі тести, тоді код).
+2. `Гілка: <state.branch ?? '—'>`.
+3. `Крок <step.step>: <step.task>`.
+4. (Якщо є `acceptance`) `Критерії приймання: …`.
+5. (Якщо є `hint`) `Підказка людини (HITL): …`.
+6. (Якщо є `last_error`) `Попередня спроба впала на перевірці:\n<last_error>\nВиправ це.`.
+
+**Side effects:** немає — це чиста функція форматування.
+
+### `patchStep(state, index, patch)`
+
+**Сигнатура:**
+
+```js
+function patchStep(state, index, patch) → newState
+```
+
+**Параметри:**
+
+- `state` — обʼєкт стану з масивом `state.plan` (`object[]`).
+- `index` (`number`) — індекс кроку в `state.plan`, який треба оновити.
+- `patch` (`object`) — поля, які треба змерджити в крок (`{ ...step, ...patch }`).
+
+**Повертає:** новий обʼєкт стану `{ ...state, plan: [...] }`, де крок під `index` замінено на `{ ...step, ...patch }`, інші кроки залишаються тими самими посиланнями.
+
+**Side effects:** немає — immutable update через `Array.prototype.map`.
+
+### `executePlan(paths, deps)`
+
+**Сигнатура:**
+
+```js
+async function executePlan(paths, deps) → Promise<{ status: 'done' | 'blocked-on-human', step?: number }>
+```
+
+**Параметри:**
+
+- `paths` — обʼєкт зі шляхами до файлів стану й журналу подій:
+  - `paths.statePath` — шлях до файлу стану, що читається `readState`.
+  - `paths.eventsPath` — шлях до журналу подій (передається далі в `recordTransition`).
+- `deps` — обʼєкт ін’єкцій:
+  - `runner` (обовʼязково) — обʼєкт із методом `runStep(prompt, opts?)`. Викликається з мікропромптом і `{ cwd }`.
+  - `verify` (обовʼязково) — `(cwd) → { pass: boolean, failedOutput?: string }` або проміс такого ж обʼєкта. Поле `pass` визначає, чи крок зелений; `failedOutput` йде у `last_error`.
+  - `commit` (обовʼязково) — `(cwd, msg) → void`. Викликається **лише** після зеленого `verify`, з повідомленням `flow: step <N> — <task>`.
+  - `cwd` (опційно) — робочий каталог, який передається `runner` і `verify`/`commit`.
+  - `maxRepairAttempts` (`number`, за замовчуванням `3`) — максимальна кількість repair-спроб на крок (перша спроба теж рахується в `retry_count`).
+  - `log` (`(msg) => void`, за замовчуванням `() => {}`) — лоґер прогресу.
+  - `now` (`() => number`, за замовчуванням `Date.now`) — джерело часу для `recordTransition`.
+
+**Повертає:**
+
+- `{ status: 'done' }` — якщо всі кроки плану позначено `done`, фінальна транзиція `plan_done` піднімає `state.status = 'built'`.
+- `{ status: 'blocked-on-human', step: <N> }` — якщо на якомусь кроці вичерпано `maxRepairAttempts`. Тоді у стан додано HITL-питання й виставлено `state.status = 'blocked-on-human'`.
+
+**Кидає:** `Error('executor: у стані немає плану — спершу planner')` — якщо `readState` повертає порожній обʼєкт або `plan` відсутній/порожній.
+
+**Side effects:**
+
+- Читає файл стану через `readState(paths.statePath)`.
+- Записує транзиції в журнал/стан через `recordTransition(paths, event, reducer, now)` для подій: `step_done`, `step_retry`, `blocked`, `plan_done`.
+- Викликає `runner.runStep(...)` — потенційний LLM/субагент-виклик.
+- Викликає `verify(cwd)` — потенційний запуск тестів/гейтів.
+- Викликає `commit(cwd, msg)` — git-commit; **тільки** при зеленому `verify`.
+- Записує повідомлення через `log(...)`.
+
+## Залежності
+
+### Внутрішні модулі (імпорти)
+
+- `./state-store.mjs`:
+  - `readState(statePath)` — синхронне читання обʼєкта стану з диска.
+  - `recordTransition(paths, event, reducer, now)` — атомарне оновлення стану й запис події в `events`-журнал; повертає новий стан.
+
+### Інжектовані залежності (через `deps`)
+
+- `runner.runStep` — реалізація запуску субагента (наприклад, `subagent-runner.mjs`).
+- `verify` — функція верифікації (наприклад, обгортка над тест-командою/ворітьми).
+- `commit` — функція git-комміту.
+- `log`, `now` — необовʼязкові утиліти.
+
+### Зовнішні залежності
+
+Стандартних модулів Node.js немає у файлі напряму — увесь I/O делеговано в `state-store.mjs` та інжектовані залежності.
+
+## Потік виконання / Використання
+
+### Алгоритм `executePlan`
+
+1. **Деструктуризація `deps`** з дефолтами: `maxRepairAttempts = 3`, `log = noop`, `now = Date.now`.
+2. **Зчитування стану**: `state = readState(paths.statePath)`. Якщо `state?.plan` відсутній або порожній — кидається помилка `executor: у стані немає плану — спершу planner`.
+3. **Ітерація плану** циклом `for (let i = 0; i < state.plan.length; i++)`:
+   - Якщо крок уже `status === 'done'` — пропустити (resume-friendly).
+   - Інакше зайти у внутрішній `while`-цикл, поки `retry_count < maxRepairAttempts` і `done === false`:
+     1. Зчитати свіжий `step = state.plan[i]`.
+     2. Залогувати: `executor: крок N (спроба M)`, де `M = retry_count + 1`.
+     3. `await runner.runStep(microprompt(step, state), { cwd })` — виконати крок субагентом з мікропромптом.
+     4. `verdict = await verify(cwd)` — перевірити результат.
+     5. **Якщо `verdict.pass === true`:**
+        - `commit(cwd, "flow: step <step.step> — <step.task>")`.
+        - `recordTransition(paths, { type: 'step_done', step }, s => patchStep(s, i, { status: 'done' }), now)`.
+        - `done = true`, вихід з `while`.
+     6. **Інакше (red):**
+        - `recordTransition` із подією `step_retry`, що інкрементує `retry_count` і кладе `last_error: verdict.failedOutput ?? null`.
+        - `while` повторює спробу (наступна ітерація прочитає вже оновлений `state.plan[i]`).
+4. **Якщо `while` вийшов з `done === false`** (тобто всі спроби спалено):
+   - Будується HITL-питання `{ id: 'q-<i>', step, question: '…не проходить verify після N спроб…', status: 'open', answer: '' }`.
+   - `recordTransition` із подією `blocked`, що ставить `state.status = 'blocked-on-human'` і додає питання в `state.hitl`.
+   - Повертається `{ status: 'blocked-on-human', step: failed.step }` — подальші кроки не запускаються.
+5. **Після успішного проходу всіх кроків** записується фінальна транзиція `plan_done`, що піднімає `state.status = 'built'`, і функція повертає `{ status: 'done' }`.
+
+### Інваріанти, які тримає алгоритм
+
+- **HEAD git завжди зелений**: `commit` викликається тільки в гілці `verdict.pass === true`. Жодна repair-спроба не записується в git.
+- **Стан eventsourcing-friendly**: усі зміни плану й верхнього статусу йдуть через `recordTransition`, тож у журналі подій лежить повна історія `step_done` / `step_retry` / `blocked` / `plan_done`.
+- **Resume-семантика**: при повторному виклику `executePlan` уже виконані кроки (`status === 'done'`) пропускаються; кроки з частковим `retry_count` продовжаться з того ж лічильника, але вже без обнулення (поки лічильник менший за `maxRepairAttempts`).
+- **Мінімальний контекст субагента**: усе, що знає субагент про задачу — це повернений `microprompt(step, state)`; жодного «склейного» історичного контексту в нього не передається.
+
+### Приклад використання
+
+```js
+import { executePlan } from './executor.mjs'
+
+const result = await executePlan(
+  { statePath: '.flow/state.json', eventsPath: '.flow/events.jsonl' },
+  {
+    runner: subagentRunner, // { runStep(prompt, { cwd }) }
+    verify: async cwd => runGates(cwd), // { pass, failedOutput }
+    commit: (cwd, msg) => gitCommit(cwd, msg),
+    cwd: process.cwd(),
+    maxRepairAttempts: 3,
+    log: m => console.error(m)
+  }
+)
+
+if (result.status === 'blocked-on-human') {
+  // потрібна відповідь людини у state.hitl[] для кроку result.step
+}
+```
+
+### Інтеграція в диспетчер
+
+`executor.mjs` — третя фаза (Ф3) flow-диспетчера, що йде після `planner.mjs` (який наповнює `state.plan`) і працює зі сховищем стану `state-store.mjs`. Цей файл не знає про конкретні CLI-команди диспетчера — він викликається з `commands.mjs`/`active.mjs` або тестів, де користувач підставляє реальні реалізації `runner`, `verify`, `commit`.

package/scripts/dispatcher/lib/docs/flow-lock.md

@@ -0,0 +1,161 @@
+# flow-lock.mjs
+
+## Огляд
+
+Модуль `flow-lock.mjs` надає тонку обгортку над спільною утилітою `withLock` для серіалізації мутацій стану `flow` у межах конкретного git worktree (per-branch). Він не реалізує власної логіки взяття/звільнення лока — натомість **повторно використовує** перевірений механізм `withLock` (spec §4.1.3), який уже коректно:
+
+- чистить stale-локи (TTL + перевірка процесу через `process.kill(pid, 0)`);
+- релізить лок на `SIGINT` / `SIGTERM`;
+- підтримує очікування з poll-інтервалом і таймаутом.
+
+Ключові поведінкові відмінності цього модуля від базового `withLock` (override-и для контексту `flow`):
+
+- **`onWaitTimeout: 'fail'`** — fail-closed. На відміну від lint, де після таймауту прийнятно стартонути «без лока», для `flow` мутацію стану двома writer-ами одночасно не допускається. Якщо лок не вдалось узяти за `waitTimeout` — кидається помилка.
+- **`getFingerprint: () => null`** — dedup за «однаковим деревом» вимкнено. Flow повинен виконатись завжди, а не пропускатись через те, що інший writer щойно мутував той самий стан.
+- **Лок-каталог — sibling до worktree-checkout**: `.flow-lock-<branch>/` створюється поряд із самим worktree-каталогом (`.worktrees/.flow-lock-<branch>/`), а не в глобальному кеш-каталозі ОС. Це усуває залежність від `XDG_CACHE_HOME` / `os.tmpdir()` і прив’язує лок до того ж тому, де живе стан.
+
+Модуль входить у бібліотеку диспетчера (`npm/scripts/dispatcher/lib/`) і є будівельним блоком для усіх кроків, що змінюють persistent-стан `flow` конкретної гілки.
+
+## Експорти / API
+
+Модуль експортує одну іменовану функцію:
+
+| Експорт                                   | Тип        | Призначення                                                                              |
+| ----------------------------------------- | ---------- | ---------------------------------------------------------------------------------------- |
+| `withFlowLock(worktreeDir, runFn, opts?)` | `function` | Виконує `runFn` під per-branch локом flow, прив’язаним до конкретного worktree-каталогу. |
+
+Default export відсутній.
+
+## Функції
+
+### `withFlowLock(worktreeDir, runFn, opts = {})`
+
+Виконує користувацьку асинхронну (або синхронну) функцію `runFn` ексклюзивно для конкретного worktree. Якщо інший процес уже тримає лок, очікує до `opts.waitTimeout`, інакше кидає помилку (fail-closed).
+
+#### Сигнатура
+
+```js
+withFlowLock(worktreeDir: string,
+             runFn: () => unknown | Promise<unknown>,
+             opts?: object): Promise<unknown>
+```
+
+#### Параметри
+
+- `worktreeDir` — `string`, **абсолютний** шлях до checkout-каталогу worktree (наприклад, `/repo/.worktrees/feat-x`). Якщо шлях не абсолютний, функція кидає `Error` (див. нижче).
+- `runFn` — `() => unknown | Promise<unknown>`, критична секція. Викликається без аргументів усередині лока. Може повертати як значення, так і `Promise`.
+- `opts` — `object`, опціональний. Прокидається у `withLock` як є (через spread). Дозволяє переозначити, зокрема:
+  - `waitTimeout` — максимальний час очікування лока (мс);
+  - `pollInterval` — період опитування стану лока (мс);
+  - будь-які інші поля, що підтримує `withLock`.
+
+  **Увага:** опції з override-ів (`onWaitTimeout`, `cacheDir`, `getFingerprint`) **можуть бути перевизначені** користувачем, бо `...opts` стоїть після них у літералі. Якщо потрібно зберегти fail-closed поведінку — не передавайте ці три поля.
+
+#### Повертає
+
+`Promise<unknown>` — те, що повернув `runFn`. Якщо `runFn` кинув помилку — `Promise` відхиляється тією ж помилкою (лок звільнюється у `finally` всередині `withLock`).
+
+#### Винятки
+
+- `Error('withFlowLock: очікується абсолютний шлях (отримано: <worktreeDir>)')` — якщо `worktreeDir` не є абсолютним шляхом (`!isAbsolute(worktreeDir)`).
+- Будь-яка помилка, кинута з `withLock`: зокрема, при `onWaitTimeout: 'fail'` — помилка таймауту очікування лока.
+- Будь-яка помилка, кинута з `runFn` — пробрасується без обгортки.
+
+#### Side effects
+
+- Створює (через `withLock`) каталог `${dirname(worktreeDir)}/.flow-lock-${basename(worktreeDir)}/` для зберігання lock-файлу та допоміжних артефактів (PID, мітки часу — деталі визначає `withLock`).
+- На час виконання `runFn` тримає файловий лок у вищезгаданому каталозі.
+- Реагує на `SIGINT`/`SIGTERM` (через хендлери у `withLock`) — звільняє лок при перериванні процесу.
+- Не виконує жодних мережевих чи git-операцій сам по собі — лише обчислює шляхи та делегує у `withLock`.
+
+#### Логіка обчислення параметрів лока
+
+Усередині функції:
+
+1. `base = basename(worktreeDir)` — ім’я останнього сегменту шляху (наприклад, `feat-x` для `/repo/.worktrees/feat-x`). Використовується як суфікс імені лока та назви кеш-каталогу.
+2. `cacheDir = join(dirname(worktreeDir), `.flow-lock-${base}`)` — каталог, у якому `withLock` зберігає сам lock-файл. Розташовується **поряд** із worktree-каталогом, а не всередині нього (sibling).
+3. Виклик `withLock(name, runFn, options)`:
+   - `name = `flow-${base}`` — стабільний ідентифікатор лока, унікальний у межах гілки.
+   - `options`:
+     - `onWaitTimeout: 'fail'` — fail-closed по таймауту очікування;
+     - `cacheDir` — обчислений вище;
+     - `getFingerprint: () => null` — dedup вимкнено: рівноцінні запуски не «склеюються»;
+     - `...opts` — користувацькі опції зверху (можуть переозначити будь-яке з трьох попередніх полів).
+
+## Залежності
+
+### Зовнішні (Node.js core)
+
+- `node:path` — імпортуються `basename`, `dirname`, `isAbsolute`, `join`. Використовуються для валідації абсолютності шляху та обчислення sibling-каталогу лока і `name` лока.
+
+### Внутрішні (репозиторій)
+
+- `../../utils/with-lock.mjs` (відносно `npm/scripts/dispatcher/lib/flow-lock.mjs` — це `npm/scripts/utils/with-lock.mjs`) — спільна утиліта `withLock`. Відповідає за:
+  - створення lock-файлу;
+  - очищення stale-локів за TTL і `process.kill(pid, 0)`;
+  - обробку `SIGINT`/`SIGTERM`;
+  - polling/wait/timeout логіку;
+  - dedup за fingerprint (тут — вимкнено).
+
+Інших зовнішніх npm-залежностей модуль не має.
+
+## Потік виконання / Використання
+
+### Високорівневий потік виклику
+
+1. Викликач формує абсолютний шлях `worktreeDir` (наприклад, `/repo/.worktrees/feat-x`).
+2. Передає його в `withFlowLock(worktreeDir, runFn, opts?)`.
+3. `withFlowLock`:
+   - валідує, що `worktreeDir` абсолютний (інакше — кидає);
+   - обчислює `base` та `cacheDir`;
+   - делегує у `withLock('flow-<base>', runFn, { onWaitTimeout: 'fail', cacheDir, getFingerprint: () => null, ...opts })`.
+4. `withLock`:
+   - намагається взяти лок у `cacheDir`;
+   - якщо лок зайнятий — чекає до `waitTimeout` з кроком `pollInterval` (значення за замовчуванням — з `withLock`);
+   - якщо за таймаут лок не взято — через `onWaitTimeout: 'fail'` кидає помилку;
+   - якщо взято — виконує `runFn` і у `finally` звільняє лок;
+   - реєструє хендлери `SIGINT`/`SIGTERM`, що звільняють лок при перериванні.
+5. Результат `runFn` повертається через `Promise`.
+
+### Приклад використання
+
+```js
+import { withFlowLock } from './flow-lock.mjs'
+
+const worktreeDir = '/repo/.worktrees/feat-x'
+
+await withFlowLock(
+  worktreeDir,
+  async () => {
+    // Критична секція: мутації стану flow для гілки feat-x
+    await mutateFlowState(worktreeDir)
+  },
+  { waitTimeout: 30_000, pollInterval: 250 }
+)
+```
+
+Поведінка:
+
+- Якщо інший процес уже виконує `withFlowLock` для **того ж самого** `worktreeDir`, поточний виклик чекатиме до 30 с.
+- Якщо за 30 с лок не звільниться — буде кинуто помилку (fail-closed).
+- Для **іншого** `worktreeDir` (інша гілка) лок не блокує — `name` лока містить `basename(worktreeDir)`, тож гілки серіалізуються незалежно.
+
+### Розташування артефактів на диску
+
+Для `worktreeDir = /repo/.worktrees/feat-x`:
+
+- worktree-checkout: `/repo/.worktrees/feat-x/`
+- lock-каталог (sibling): `/repo/.worktrees/.flow-lock-feat-x/`
+
+Sibling-розміщення обрано свідомо, аби:
+
+- не «забруднювати» сам worktree файлом лока (він не є частиною робочого дерева);
+- не залежати від глобального кеш-каталогу ОС (інакше лок-семантика «per-branch у цьому репо» загубилась би на машинах з нестандартним `XDG_CACHE_HOME`).
+
+### Гарантії та обмеження
+
+- **Серіалізація per-branch:** два паралельні виклики `withFlowLock` для одного `worktreeDir` виконуються послідовно.
+- **Незалежність гілок:** виклики для різних `worktreeDir` (різний `basename`) не блокують одне одного.
+- **Fail-closed:** при недоступному локі writer **не** запуститься «оптимістично» — на відміну від lint-сценаріїв.
+- **Без dedup:** навіть якщо викликач передасть свій `getFingerprint`, дефолт `() => null` вимикає «склеювання» однакових запусків; для увімкнення dedup потрібно явно передати `getFingerprint` в `opts` (override `...opts` після дефолтів дозволяє це).
+- **Обов’язковий абсолютний шлях:** відносні шляхи відхиляються одразу — це усуває клас помилок «лок узяли не там, де думали».