@nitra/cursor 4.1.2 → 5.0.1

package/scripts/dispatcher/lib/docs/subagent-runner.md

@@ -1,173 +0,0 @@
-# subagent-runner.mjs
-
-## Огляд
-
-`subagent-runner.mjs` — модуль абстракції спавну сфокусованого субагента для Активного Раннера (фаза Ф3/Ф4 диспетчера). Реалізує специфікацію §15.1: надає уніфікований інтерфейс `runStep(prompt, opts)` поверх трьох можливих backend-ів:
-
-1. `claude-agent-sdk` — програмний доступ через пакет `@anthropic-ai/claude-agent-sdk`, потребує змінної середовища `ANTHROPIC_API_KEY`.
-2. `claude -p` — CLI-аутентифікація користувача через виконуваний `claude` у `PATH`.
-3. `cursor-agent -p` — CLI-аутентифікація через виконуваний `cursor-agent` у `PATH`.
-
-Якщо жоден backend недоступний — модуль кидає виняток із текстом `NO_BACKEND` (polyfill без runner-а не стартує, §2.2).
-
-Згідно з коментарем у заголовку файлу, для inner-спавну навмисно НЕ використовується pi.dev: у автономному режимі pi.dev — це зовнішній драйвер, тож спавнити ним внутрішні субагенти призвело б до рекурсії (§9.1).
-
-Усі probe-залежності (`spawn`, `isInPath`, `canImportSdk`, `query`) проектовані під ін'єкцію — для тестування без реальних процесів та без встановленого SDK.
-
-## Експорти / API
-
-Модуль експортує чотири іменовані функції:
-
-- `isBinaryInPath(name, spawn?)` — перевірка наявності бінарника в `PATH`.
-- `selectBackend({ hasApiKey, canImportSdk, isInPath })` — вибір backend-а за пріоритетом.
-- `cliRunner(bin, deps?)` — фабрика runner-а для CLI-варіанту.
-- `sdkRunner(deps?)` — фабрика runner-а для SDK-варіанту.
-- `createRunner(deps?)` — головний фасад, що сам визначає та повертає потрібний runner.
-
-Внутрішня (не експортована) функція: `probeSdk()` — перевіряє можливість динамічного імпорту SDK.
-
-Константа модульного рівня `NO_BACKEND` — текст повідомлення помилки, коли жоден backend недоступний.
-
-## Функції
-
-### `isBinaryInPath(name, spawn = spawnSync)`
-
-Перевіряє, чи є виконуваний бінарник у `PATH` через виклик `command -v <name>`.
-
-- Параметри:
-  - `name` (`string`) — ім'я виконуваного.
-  - `spawn` (`typeof spawnSync`, optional) — ін'єкція для тестів; за замовчуванням `spawnSync` із `node:child_process`.
-- Повертає: `boolean` — `true`, якщо `spawn` повернув статус `0`; інакше `false`. Якщо `r.status` дорівнює `null`/`undefined`, трактується як `1` (тобто `false`).
-- Side effects: виклик дочірнього процесу `command -v` через shell (`shell: true`).
-
-### `selectBackend({ hasApiKey, canImportSdk, isInPath })`
-
-Вибирає backend за чітко зафіксованим пріоритетом: SDK > Claude CLI > Cursor CLI.
-
-- Параметри (один об'єкт):
-  - `hasApiKey` (`boolean`) — чи задана `ANTHROPIC_API_KEY`.
-  - `canImportSdk` (`boolean`) — чи імпортується `@anthropic-ai/claude-agent-sdk`.
-  - `isInPath` (`(name: string) => boolean`) — предикат наявності бінарника у `PATH`.
-- Повертає: рядковий літерал `'sdk'`, `'claude'`, `'cursor'` або `null`.
-- Логіка:
-  1. Якщо `hasApiKey` і `canImportSdk` одночасно істинні — `'sdk'`.
-  2. Інакше якщо `isInPath('claude')` — `'claude'`.
-  3. Інакше якщо `isInPath('cursor-agent')` — `'cursor'`.
-  4. Інакше — `null`.
-- Side effects: відсутні (за умови, що `isInPath` чистий).
-
-### `cliRunner(bin, deps = {})`
-
-Створює CLI-runner на основі бінарника `claude` або `cursor-agent` (обидва підтримують прапор `-p` для подачі промпта зі stdin).
-
-- Параметри:
-  - `bin` (`'claude' | 'cursor-agent'`) — який саме CLI запускати.
-  - `deps.spawn` (`typeof spawnSync`, optional) — ін'єкція; за замовчуванням `spawnSync`.
-- Повертає об'єкт:
-  - `backend` — рядок, що дорівнює переданому `bin`.
-  - `runStep(prompt, { cwd } = {})` — синхронна функція, що викликає `spawn(bin, ['-p'], { input: prompt, cwd, encoding: 'utf8' })`. Повертає `{ ok: boolean, output: string }`, де:
-    - `ok` — `true`, якщо `r.status === 0` (null/undefined трактується як 1 → `false`).
-    - `output` — конкатенація `stdout` та `stderr` (порожні рядки, якщо undefined).
-- Side effects: спавн дочірнього CLI-процесу при кожному виклику `runStep`.
-
-### `sdkRunner(deps = {})`
-
-Створює SDK-runner, який працює через async-iterable `query` з пакета `@anthropic-ai/claude-agent-sdk`.
-
-- Параметри:
-  - `deps.query` (`(input: object) => AsyncIterable`, optional) — ін'єкція функції `query` для тестів. Якщо не задано — модуль динамічно імпортує `@anthropic-ai/claude-agent-sdk` і бере звідти `query`.
-- Повертає об'єкт:
-  - `backend` — рядок `'sdk'`.
-  - `runStep(prompt, { cwd } = {})` — `async` функція, що повертає `Promise<{ ok: boolean, output: string }>`.
-- Логіка `runStep`:
-  1. Лінива ініціалізація `query` (якщо не передано в `deps`).
-  2. Виклик `query({ prompt, options: { cwd, maxTurns: 20, allowedTools: ['Read', 'Edit', 'Bash'] } })`.
-  3. Ітерує асинхронно по повідомленнях:
-     - Якщо `msg.text` — рядок, додає його до `output`.
-     - Якщо `msg.type === 'result'`, фіналізує `ok = msg.is_error !== true`.
-  4. У разі винятку — повертає `{ ok: false, output: String(error?.message ?? error) }`.
-- Side effects: динамічний імпорт SDK (один раз на виклик, якщо `query` не ін'єктовано); мережеві/процесні дії SDK; обмеження інструментів виключно до `Read`, `Edit`, `Bash`.
-
-### `createRunner(deps = {})`
-
-Головний фасад модуля. Підбирає та повертає runner відповідно до доступних backend-ів.
-
-- Параметри (об'єкт `deps` для тестів; усі поля опціональні):
-  - `backend` — явне переозначення вибору (`'sdk'`/`'claude'`/`'cursor'`).
-  - `env` — мапа змінних середовища; за замовчуванням `processEnv` (`process.env`).
-  - `isInPath` — функція; за замовчуванням обгортка над `isBinaryInPath(name, deps.spawn)`.
-  - `canImportSdk` — заздалегідь обчислений прапор; інакше викликається `probeSdk()`.
-  - `spawn` — використовується як `deps.spawn` для дефолтного `isInPath`.
-  - `query` — пробрасується в `sdkRunner` як `deps.query`.
-- Повертає: `Promise<runner>`, де `runner` має форму `{ backend, runStep }` (синхронний для CLI, асинхронний для SDK — обидва типи представлені в одному фасаді).
-- Логіка:
-  1. Резолвить `env`, `isInPath`, `canImportSdk`.
-  2. Якщо `deps.backend` не задано — викликає `selectBackend({ hasApiKey: Boolean(env.ANTHROPIC_API_KEY), canImportSdk, isInPath })`.
-  3. Якщо backend усе ще `null`/falsy — `throw new Error(NO_BACKEND)`.
-  4. Для `'sdk'` — повертає `sdkRunner(deps)`.
-  5. Для `'claude'` — повертає `cliRunner('claude', deps)`.
-  6. Для будь-якого іншого ненульового — повертає `cliRunner('cursor-agent', deps)` (тобто `'cursor'` мапиться на `cursor-agent`).
-- Side effects: можливий динамічний імпорт SDK через `probeSdk()`; виклики `spawn` через дефолтний `isInPath`.
-
-### `probeSdk()` (внутрішня)
-
-Перевіряє, чи можна динамічно імпортувати `@anthropic-ai/claude-agent-sdk`.
-
-- Параметри: відсутні.
-- Повертає: `Promise<boolean>` — `true`, якщо `import` успішний, інакше `false` (виняток поглинається порожнім `catch`).
-- Side effects: динамічний `import()` модуля SDK.
-
-## Залежності
-
-- `node:child_process` — `spawnSync` (синхронний спавн дочірніх процесів для `command -v` та CLI-runner-а).
-- `node:process` — `env` як `processEnv` (читання змінних середовища, передусім `ANTHROPIC_API_KEY`).
-- `@anthropic-ai/claude-agent-sdk` (optional, динамічний `import`) — джерело функції `query` для SDK-runner-а; відсутність пакета — допустимий сценарій (`probeSdk()` ловить виняток).
-
-Зовнішні виконувані файли, очікувані у `PATH`:
-
-- `command` — POSIX-shell builtin для `command -v`.
-- `claude` — CLI Claude Code.
-- `cursor-agent` — CLI Cursor Agent.
-
-Жодних інших імпортів із локального проєкту модуль не робить — він самодостатній.
-
-## Потік виконання / Використання
-
-Типовий сценарій використання у диспетчері (Активний Раннер, фази Ф3/Ф4):
-
-1. Виклик `await createRunner()` без параметрів.
-2. Усередині `createRunner` виконується probe доступних backend-ів:
-   - перевіряється `process.env.ANTHROPIC_API_KEY`;
-   - намагається динамічно імпортувати `@anthropic-ai/claude-agent-sdk`;
-   - перевіряються `claude` та `cursor-agent` у `PATH` через `command -v`.
-3. `selectBackend` повертає перший доступний backend за пріоритетом SDK → claude → cursor.
-4. Якщо нічого не знайдено — кидається `Error(NO_BACKEND)`, що зупиняє стартування polyfill-а (§2.2).
-5. Інакше повертається об'єкт `{ backend, runStep }`.
-6. Викликаючий код передає `runStep(prompt, { cwd })`:
-   - для SDK — отримує `Promise<{ ok, output }>`, працюючи з обмеженим набором інструментів `Read`/`Edit`/`Bash` та лімітом `maxTurns: 20`;
-   - для CLI — отримує синхронний `{ ok, output }` після завершення дочірнього процесу.
-
-Для тестування потік ін'єктується наскрізно: будь-яку із залежностей (`spawn`, `isInPath`, `canImportSdk`, `query`, `env`, `backend`) можна перевизначити, що дозволяє покривати модуль unit-тестами без реальних процесів і без SDK.
-
-Особливості та інваріанти:
-
-- Пріоритет backend-ів зафіксований у `selectBackend` і не змінюється від виклику до виклику.
-- `runStep` у CLI-варіанті завжди синхронний, у SDK-варіанті — асинхронний; форма результату `{ ok, output }` уніфікована.
-- `output` у CLI завжди склеює `stdout` та `stderr` без розділювача.
-- У SDK-варіанті помилки під час ітерації `query` ловляться й конвертуються в `{ ok: false, output: <message> }`, тобто `runStep` не пробрасує винятки нагору.
-- Значення `null`/`undefined` для `r.status` у `spawnSync`-результатах послідовно нормалізується через `?? 1`, що дає поведінку "невідомий статус == помилка".
-
-## Rebuild Test
-
-Документ описує лише той API, що присутній у файлі `subagent-runner.mjs`:
-
-- Експорти: `isBinaryInPath`, `selectBackend`, `cliRunner`, `sdkRunner`, `createRunner` — усі п'ять перевірено за вихідним кодом.
-- Внутрішня функція `probeSdk` зафіксована як приватна (не експортована).
-- Константа `NO_BACKEND` згадана як модульна.
-- Імпорти `spawnSync` із `node:child_process` та `env` як `processEnv` із `node:process` зафіксовані.
-- Опційна залежність `@anthropic-ai/claude-agent-sdk` згадана з акцентом на динамічний import у двох місцях (`sdkRunner.runStep` та `probeSdk`).
-- Пріоритет `sdk → claude → cursor` і поведінка `createRunner` за відсутності backend (throw `NO_BACKEND`) відповідають коду.
-- Деталі `sdkRunner` (`maxTurns: 20`, `allowedTools: ['Read', 'Edit', 'Bash']`, обробка `msg.type === 'result'` та `msg.is_error`) узяті безпосередньо з тіла функції.
-- Формула `r.status ?? 1` для нормалізації статусу описана точно так, як у коді.
-
-Жодних припущень про невидимі в файлі деталі (тестові файли, інтеграцію з конкретними викликами в інших модулях диспетчера) у документі не зроблено.

package/scripts/dispatcher/lib/events.mjs

@@ -1,67 +0,0 @@
-/**
- * WAL — append-only журнал подій `flow` (spec §4.1.2, §9).
- *
- * Sibling-файл `.worktrees/<sanitized-branch>.events.jsonl` (JSON Lines). Єдиний
- * журнал: субсумує і переходи стану (`step_*`, `blocked`…), і api-облік
- * (`api_call`). Append-only → краш-безпечніший за перезапис: торваний останній
- * рядок (краш посеред append) при читанні **толеруємо** (пропускаємо), а не
- * валимо весь журнал.
- *
- * **WAL-інваріант** (забезпечує `state-store.recordTransition`): подію
- * дописуємо ДО зміни високорівневого статусу у snapshot `.flow.json`.
- *
- * Усі шляхи — абсолютні (`no-relative-fs-path`).
- */
-import { appendFileSync, existsSync, readFileSync } from 'node:fs'
-import { basename, dirname, isAbsolute, join } from 'node:path'
-
-/**
- * Шлях sibling-журналу подій для checkout-каталогу worktree.
- * @param {string} worktreeDir абсолютний шлях checkout (`…/.worktrees/feat-x`)
- * @returns {string} `…/.worktrees/feat-x.events.jsonl`
- */
-export function flowEventsPath(worktreeDir) {
-  if (!isAbsolute(worktreeDir)) {
-    throw new Error(`flowEventsPath: очікується абсолютний шлях (отримано: ${worktreeDir})`)
-  }
-  return join(dirname(worktreeDir), `${basename(worktreeDir)}.events.jsonl`)
-}
-
-/**
- * Дописує одну подію (з міткою часу `at`) у журнал. Створює файл за потреби.
- * @param {string} eventsPath абсолютний шлях `.events.jsonl`
- * @param {object} event подія (напр. `{ type: 'step_started', step: 2 }`)
- * @param {() => number} [now] фабрика часу (ms) — ін'єкція для тестів
- * @returns {object} фактично записаний запис (зі `at`)
- */
-export function appendEvent(eventsPath, event, now = Date.now) {
-  if (!isAbsolute(eventsPath)) {
-    throw new Error(`appendEvent: очікується абсолютний шлях (отримано: ${eventsPath})`)
-  }
-  const record = { at: new Date(now()).toISOString(), ...event }
-  appendFileSync(eventsPath, `${JSON.stringify(record)}\n`, 'utf8')
-  return record
-}
-
-/**
- * Читає всі події. Відсутній файл → `[]`. Непарсабельні рядки (порожні або
- * торваний останній) **пропускаються** (append-only толерантність).
- * @param {string} eventsPath абсолютний шлях `.events.jsonl`
- * @returns {object[]} розпарсені події у порядку запису
- */
-export function readEvents(eventsPath) {
-  if (!isAbsolute(eventsPath)) {
-    throw new Error(`readEvents: очікується абсолютний шлях (отримано: ${eventsPath})`)
-  }
-  if (!existsSync(eventsPath)) return []
-  return readFileSync(eventsPath, 'utf8')
-    .split('\n')
-    .filter(line => line.trim() !== '')
-    .flatMap(line => {
-      try {
-        return [JSON.parse(line)]
-      } catch {
-        return []
-      }
-    })
-}

package/scripts/dispatcher/lib/executor.mjs

@@ -1,107 +0,0 @@
-/**
- * Executor (spec §3 Ф3) — виконує план покроково через SubagentRunner + verify.
- *
- * Інваріанти:
- *  - **мікропромпт зі стану** (§3 Ф3): субагент отримує лише поточний крок +
- *    критерії + останню помилку, не історію переписки;
- *  - **commit лише після зеленого verify** (§4.1.7): repair-спроби не комітять,
- *    тож HEAD завжди = останній зелений крок;
- *  - **repair ≤ maxRepairAttempts**, далі — HITL (`blocked-on-human`, §4.2).
- *
- * Усі побічні дії (`runner`/`verify`/`commit`) ін'єктуються — тестується без
- * реальних LLM/git/gates.
- */
-import { readState, recordTransition } from './state-store.mjs'
-
-/**
- * Мікропромпт для кроку (§3 Ф3): лише поточний крок + критерії + остання помилка.
- * @param {{ step: number, task: string, acceptance?: string, last_error?: string }} step крок плану
- * @param {{ branch?: string }} state стан (для контексту гілки)
- * @returns {string} промпт субагента
- */
-export function microprompt(step, state) {
-  const lines = [
-    'Реалізуй РІВНО цей крок плану (не більше). Iron Law of TDD: спершу падаючі тести, тоді код.',
-    `Гілка: ${state.branch ?? '—'}`,
-    `Крок ${step.step}: ${step.task}`
-  ]
-  if (step.acceptance) lines.push(`Критерії приймання: ${step.acceptance}`)
-  if (step.hint) lines.push(`Підказка людини (HITL): ${step.hint}`)
-  if (step.last_error) lines.push(`Попередня спроба впала на перевірці:\n${step.last_error}\nВиправ це.`)
-  return lines.join('\n')
-}
-
-/**
- * Оновлює крок плану за індексом (pure).
- * @param {{ plan: object[] }} state стан
- * @param {number} index індекс кроку
- * @param {object} patch часткове оновлення кроку
- * @returns {object} новий стан
- */
-export function patchStep(state, index, patch) {
-  return { ...state, plan: state.plan.map((s, i) => (i === index ? { ...s, ...patch } : s)) }
-}
-
-/**
- * Виконує план зі стану.
- * @param {{ statePath: string, eventsPath: string }} paths шляхи стану й журналу
- * @param {{ runner: { runStep: (prompt: string, opts?: object) => object }, verify: (cwd: string) => Promise<{ pass: boolean, failedOutput?: string }> | { pass: boolean, failedOutput?: string }, commit: (cwd: string, msg: string) => void, cwd?: string, maxRepairAttempts?: number, log?: (m: string) => void, now?: () => number }} deps ін'єкції
- * @returns {Promise<{ status: 'done' | 'blocked-on-human', step?: number }>} результат
- */
-export async function executePlan(paths, deps) {
-  const { runner, verify, commit, cwd, maxRepairAttempts = 3, log = () => { /* noop */ }, now = Date.now } = deps
-  let state = readState(paths.statePath)
-  if (!state?.plan?.length) {
-    throw new Error('executor: у стані немає плану — спершу planner')
-  }
-
-  for (let i = 0; i < state.plan.length; i++) {
-    if (state.plan[i].status === 'done') continue
-
-    let done = false
-    while (state.plan[i].retry_count < maxRepairAttempts && !done) {
-      const step = state.plan[i]
-      log(`executor: крок ${step.step} (спроба ${step.retry_count + 1})`)
-      await runner.runStep(microprompt(step, state), { cwd })
-      const verdict = await verify(cwd)
-      if (verdict.pass) {
-        commit(cwd, `flow: step ${step.step} — ${step.task}`) // commit ЛИШЕ після зеленого
-        state = recordTransition(
-          paths,
-          { type: 'step_done', step: step.step },
-          s => patchStep(s, i, { status: 'done' }),
-          now
-        )
-        done = true
-      } else {
-        state = recordTransition(
-          paths,
-          { type: 'step_retry', step: step.step },
-          s => patchStep(s, i, { retry_count: s.plan[i].retry_count + 1, last_error: verdict.failedOutput ?? null }),
-          now
-        )
-      }
-    }
-
-    if (!done) {
-      const failed = state.plan[i]
-      const question = {
-        id: `q-${i}`,
-        step: failed.step,
-        question: `Крок ${failed.step} «${failed.task}» не проходить verify після ${maxRepairAttempts} спроб. Що робити?`,
-        status: 'open',
-        answer: ''
-      }
-      recordTransition(
-        paths,
-        { type: 'blocked', step: failed.step },
-        s => ({ ...s, status: 'blocked-on-human', hitl: [...(s.hitl ?? []), question] }),
-        now
-      )
-      return { status: 'blocked-on-human', step: failed.step }
-    }
-  }
-
-  recordTransition(paths, { type: 'plan_done' }, s => ({ ...s, status: 'built' }), now)
-  return { status: 'done' }
-}

package/scripts/dispatcher/lib/plan-panel.mjs

@@ -1,76 +0,0 @@
-/**
- * Agent↔agent brainstorm (bmad party-mode + superpowers dispatching у наших
- * термінах): персони-субагенти пропонують погляди, суддя-субагент синтезує одну
- * відповідь. Спільний для фази `spec` (mode: 'spec' — підходи) і `plan`
- * (mode: 'plan' — JSON-кроки). Перевикористовує runner-інтерфейс Фасада B
- * (`runStep(prompt, opts) => { ok, output }`, як `planner.mjs`/`active.mjs`).
- *
- * HITL: panel лише ПОВЕРТАЄ синтез — апрув людини й збереження артефакту робить
- * агент за контрактом `flow.mdc` (фіксація — окрема команда `flow spec`/`flow plan`).
- */
-
-/** Персони панелі: [ім'я, системний промпт]. */
-const PERSONAS = [
-  ['architect', 'Ти — architect. Запропонуй найчистішу архітектуру розв’язання. Стисло, по суті.'],
-  ['skeptic', 'Ти — skeptic. Назви ризики, граничні випадки і що може піти не так. Стисло.'],
-  ['tester', 'Ти — tester. Опиши, які тести доведуть коректність. Стисло.']
-]
-
-/**
- * Промпт судді за режимом.
- * @param {'spec' | 'plan'} mode режим синтезу
- * @param {string} proposals склеєні думки персон
- * @param {string} task опис задачі
- * @returns {string} промпт судді
- */
-function judgePrompt(mode, proposals, task) {
-  const head =
-    mode === 'plan'
-      ? [
-          'Синтезуй із думок персон ОДИН покроковий план реалізації.',
-          'Кожен крок — ≤ 5 хв розробки, з критерієм приймання.',
-          'Поверни ЛИШЕ JSON-масив без коментарів: [{ "task": "...", "acceptance": "..." }, ...].'
-        ]
-      : [
-          'Синтезуй із думок персон 2-3 підходи до розв’язання з рекомендацією й коротким дизайном.',
-          'Поверни людино-читабельний текст (Markdown).'
-        ]
-  return [...head, '', proposals, '', `Задача: ${task}`].join('\n')
-}
-
-/**
- * Проводить панель і повертає синтез.
- * @param {{ task: string, cwd: string, runner: { runStep: (p: string, o?: object) => { ok: boolean, output: string } | Promise<{ ok: boolean, output: string }> }, log?: (m: string) => void, mode?: 'spec' | 'plan' }} input ін'єкції
- * @returns {Promise<{ task: string, acceptance?: string }[] | string | null>} кроки (plan), текст (spec) або null (фейл)
- */
-export async function runPanel({ task, cwd, runner, log = console.error, mode = 'plan' }) {
-  if (!runner) {
-    log('panel: нема runner — режим --panel недоступний')
-    return null
-  }
-  const proposals = await Promise.all(
-    PERSONAS.map(async ([name, sys]) => {
-      const r = await runner.runStep(`${sys}\n\nЗадача: ${task}`, { cwd })
-      return `### ${name}\n${r.ok ? r.output : '(порожньо)'}`
-    })
-  )
-  const judge = await runner.runStep(judgePrompt(mode, proposals.join('\n\n'), task), { cwd })
-  if (!judge.ok) {
-    log('panel: суддя-синтез завершився помилкою')
-    return null
-  }
-  if (mode === 'spec') return judge.output
-
-  const start = judge.output.indexOf('[')
-  const end = judge.output.lastIndexOf(']')
-  if (start === -1 || end === -1 || end < start) {
-    log('panel: суддя не повернув JSON-план')
-    return null
-  }
-  try {
-    return JSON.parse(judge.output.slice(start, end + 1))
-  } catch {
-    log('panel: невалідний JSON синтезу')
-    return null
-  }
-}

package/scripts/dispatcher/lib/state-store.mjs

@@ -1,173 +0,0 @@
-/**
- * Crash-safe сховище runtime-стану `flow` (spec §4, §4.1).
- *
- * Локація — **sibling-файл** `.worktrees/<sanitized-branch>.flow.json` поруч із
- * checkout (НЕ всередині нього: файл усередині worktree = untracked у feature-
- * гілці й ризикує потрапити в `git add -A`). Деривація шляху: для checkout-
- * директорії `.worktrees/feat-x` стан → `.worktrees/feat-x.flow.json`.
- *
- * Crash-safety (§4.1):
- *  - **atomic write**: temp на тому ж FS → `fsync` файла → `rename` (атомарна
- *    заміна; частковий запис неможливий);
- *  - **fail-closed на corruption**: нечитабельний/невалідний JSON або несумісний
- *    `schema_version` → throw (не стартуємо новий flow над зіпсованим станом).
- *
- * Усі шляхи — абсолютні (вимога `no-relative-fs-path`).
- */
-import {
-  closeSync,
-  existsSync,
-  fsyncSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  writeFileSync
-} from 'node:fs'
-import { basename, dirname, isAbsolute, join } from 'node:path'
-import { randomBytes } from 'node:crypto'
-import { pid } from 'node:process'
-
-import { appendEvent } from './events.mjs'
-
-export const SCHEMA_VERSION = 1
-
-/**
- * Шлях sibling-файла стану для заданого checkout-каталогу worktree.
- * @param {string} worktreeDir абсолютний шлях checkout (напр. `…/.worktrees/feat-x`)
- * @returns {string} абсолютний шлях `…/.worktrees/feat-x.flow.json`
- */
-export function flowStatePath(worktreeDir) {
-  if (!isAbsolute(worktreeDir)) {
-    throw new Error(`flowStatePath: очікується абсолютний шлях (отримано: ${worktreeDir})`)
-  }
-  return join(dirname(worktreeDir), `${basename(worktreeDir)}.flow.json`)
-}
-
-/**
- * fsync файла за абсолютним шляхом (дані на диск до rename).
- * @param {string} path абсолютний шлях
- * @returns {void}
- */
-function fsyncPath(path) {
-  const fd = openSync(path, 'r')
-  try {
-    fsyncSync(fd)
-  } finally {
-    closeSync(fd)
-  }
-}
-
-/**
- * Атомарно записує стан: temp(той самий каталог)+fsync+rename. Додає
- * `schema_version`. Повертає фактично записаний об'єкт.
- * @param {string} statePath абсолютний шлях `.flow.json`
- * @param {object} state стан без `schema_version`
- * @returns {object} записаний об'єкт (зі `schema_version`)
- */
-export function writeState(statePath, state) {
-  if (!isAbsolute(statePath)) {
-    throw new Error(`writeState: очікується абсолютний шлях (отримано: ${statePath})`)
-  }
-  const dir = dirname(statePath)
-  mkdirSync(dir, { recursive: true })
-  const payload = { schema_version: SCHEMA_VERSION, ...state }
-  const tmp = join(dir, `.${basename(statePath)}.${pid}.${randomBytes(6).toString('hex')}.tmp`)
-  writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
-  fsyncPath(tmp)
-  renameSync(tmp, statePath)
-  // best-effort fsync каталогу (durability rename). Не на всіх платформах
-  // (Windows кидає EISDIR/EPERM) — тому загорнуто й помилки ігноруємо.
-  try {
-    fsyncPath(dir)
-  } catch {
-    /* fsync каталогу недоступний на цій платформі — некритично */
-  }
-  return payload
-}
-
-/**
- * Читає стан. Відсутній файл → null. Пошкоджений JSON або несумісний
- * `schema_version` → throw (**fail-closed**, §4.1.6).
- * @param {string} statePath абсолютний шлях `.flow.json`
- * @returns {object | null} стан або null, якщо файлу нема
- */
-export function readState(statePath) {
-  if (!isAbsolute(statePath)) {
-    throw new Error(`readState: очікується абсолютний шлях (отримано: ${statePath})`)
-  }
-  if (!existsSync(statePath)) return null
-  const raw = readFileSync(statePath, 'utf8')
-  let parsed
-  try {
-    parsed = JSON.parse(raw)
-  } catch {
-    throw new Error(`readState: пошкоджений стан (невалідний JSON) у ${statePath} — fail-closed`)
-  }
-  if (typeof parsed !== 'object' || parsed === null || parsed.schema_version !== SCHEMA_VERSION) {
-    throw new Error(
-      `readState: несумісний або пошкоджений schema_version у ${statePath} ` +
-        `(очікується ${SCHEMA_VERSION}) — fail-closed`
-    )
-  }
-  return parsed
-}
-
-/**
- * Читає стан, застосовує `fn` і атомарно записує результат. Якщо файлу нема —
- * `fn` отримує `{}`.
- * @param {string} statePath абсолютний шлях `.flow.json`
- * @param {(state: object) => object} fn трансформер стану
- * @returns {object} записаний об'єкт
- */
-export function updateState(statePath, fn) {
-  const current = readState(statePath)
-  return writeState(statePath, fn(current ?? {}))
-}
-
-/**
- * Видаляє sibling-файл стану (cleanup при `worktree remove` / `flow cancel`).
- * Ідемпотентно (відсутній файл — не помилка).
- * @param {string} statePath абсолютний шлях `.flow.json`
- * @returns {void}
- */
-export function removeState(statePath) {
-  if (!isAbsolute(statePath)) {
-    throw new Error(`removeState: очікується абсолютний шлях (отримано: ${statePath})`)
-  }
-  rmSync(statePath, { force: true })
-}
-
-/**
- * WAL-перехід (§4.1.2): спершу дописує подію в журнал, ТОДІ атомарно змінює
- * статус у snapshot. Якщо запис стану впаде — подія вже durable (журнал —
- * джерело для reconcile при `resume`).
- * @param {{ statePath: string, eventsPath: string }} paths шляхи стану й журналу
- * @param {object} event подія переходу
- * @param {(state: object) => object} stateFn трансформер стану
- * @param {() => number} [now] фабрика часу (ms)
- * @returns {object} записаний стан
- */
-export function recordTransition({ statePath, eventsPath }, event, stateFn, now = Date.now) {
-  appendEvent(eventsPath, event, now)
-  return updateState(statePath, stateFn)
-}
-
-/**
- * Прибирає всі runtime-sibling-и worktree: `.flow.json`, `.events.jsonl`,
- * лок-каталог `.flow-lock-<branch>/`. Ідемпотентно. Викликається `flow cancel`
- * і `worktree remove` (інакше sibling-и осиротіють — git їх не чистить).
- * @param {string} worktreeDir абсолютний шлях checkout (`…/.worktrees/feat-x`)
- * @returns {void}
- */
-export function cleanupFlowSiblings(worktreeDir) {
-  if (!isAbsolute(worktreeDir)) {
-    throw new Error(`cleanupFlowSiblings: очікується абсолютний шлях (отримано: ${worktreeDir})`)
-  }
-  const base = basename(worktreeDir)
-  const dir = dirname(worktreeDir)
-  rmSync(join(dir, `${base}.flow.json`), { force: true })
-  rmSync(join(dir, `${base}.events.jsonl`), { force: true })
-  rmSync(join(dir, `.flow-lock-${base}`), { recursive: true, force: true })
-}

package/scripts/dispatcher/lib/subagent-runner.mjs

@@ -1,53 +0,0 @@
-/**
- * SubagentRunner — спавн субагента через pi (провайдер-нейтрально).
- * Модель обирається через resolveModel('avg') (каскад local→cloud) або через deps.model.
- *
- * Контракт runner-а: { backend: 'pi', runStep(prompt, { cwd }) → Promise<{ ok, output }> }.
- * Усі callers (planner, executor, plan-panel, review, budget) використовують саме цей контракт.
- *
- * pi НЕ спавниться рекурсивно коли pi — зовнішній драйвер (§9.1).
- * У цьому проєкті зовнішній драйвер — Claude Code; pi як субагент — безпечно.
- */
-import { spawnSync } from 'node:child_process'
-
-import { resolveModel } from '../../../lib/models.mjs'
-
-/**
- * Викликає pi і повертає { ok, output }.
- * @param {string} prompt текст промпта
- * @param {string} model  provider/model-id або '' для pi-дефолту
- * @param {{ cwd?: string }} [opts] опційні параметри (cwd)
- * @returns {{ ok: boolean, output: string }} результат із статусом і output
- */
-function callPi(prompt, model, { cwd } = {}) {
-  const modelArgs = model ? ['--model', model] : []
-  const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session'], {
-    cwd,
-    encoding: 'utf8',
-    timeout: 600_000
-  })
-  const ok = !r.error && r.status === 0
-  const output = (r.stdout ?? '') + (r.error ? r.error.message : (ok ? '' : (r.stderr ?? '')))
-  return { ok, output }
-}
-
-/**
- * Створює pi-runner. Повертає { backend: 'pi', runStep }.
- * @param {{ model?: string, callPi?: Function }} [deps]  ін'єкції для тестів
- * @returns {Promise<{ backend: string, runStep: (prompt: string, opts?: object) => Promise<{ ok: boolean, output: string }> }>} runner із backend='pi' і методом runStep
- */
-export function createRunner(deps = {}) {
-  const model = deps.model ?? resolveModel('avg')
-  const callPiFn = deps.callPi ?? callPi
-
-  return {
-    backend: 'pi',
-    runStep(prompt, opts = {}) {
-      try {
-        return callPiFn(prompt, model, opts)
-      } catch (error) {
-        return { ok: false, output: String(error?.message ?? error) }
-      }
-    }
-  }
-}