@nitra/cursor 1.41.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [2.0.0] - 2026-05-31
+
+### Added
+
+- n-cursor flow (v2.0-a Ф0-Ф1.1): каркас dispatcher + CLI `case 'flow'` (init/verify/release/run/resume/cancel/repair — поки stub-и), Capability Router з явною декларацією моделі (native/polyfill, default→polyfill лише за наявного runner-а), crash-safe state-store (.flow.json sibling, atomic temp+fsync+rename, fail-closed на corruption). 29 unit-тестів (withTmpDir).
+- n-cursor flow v2.0-a Ф1.2-Ф1.4: WAL-журнал .events.jsonl (append-only, торований останній рядок толерується), per-branch lock через reuse withLock із fail-closed override (додано опцію onWaitTimeout у спільний with-lock, back-compat), cleanupFlowSiblings (.flow.json/.events.jsonl/lock). recordTransition (WAL: подія до зміни статусу). +22 тести.
+- n-cursor flow v2.0-a Ф2 (verify): reviewer.mjs — Level-1 «Суддя» проганяє lint+coverage gates через ін'єктований runner (fail-fast, fingerprint на повному pass через reuse worktree-fingerprint); flow verify — Пасивний Турнікет: запускає gates у поточному worktree, записує результати+fingerprint у наявний стан (recordTransition), exit 0/1. +11 тестів.
+- n-cursor flow v2.0-a Ф2·2: flow init (n-cursor worktree add + detect-existing-isolation через git rev-parse, init .flow.json з base_commit; reuse worktreePaths/sanitizeBranch) + flow release (n-cursor change + completion snapshot у стан і task record) + snapshot.mjs (buildCompletionSnapshot/upsertSummaryBlock/writeSummaryToTaskRecord). reviewer тепер захоплює вивід проваленого gate. Пасивний Турнікет (init/verify/release) завершено. +18 тестів.
+- n-cursor flow Ф2·4: bundled-правило flow (матеріалізується як .cursor/rules/n-flow.mdc) — контракт Пасивного Турнікета для IDE-агентів (Cursor/Claude Code): init -> сам пишеш код (TDD) -> verify (3 спроби на фейл) -> release. alwaysApply; pure-doc + стандартний fix.mjs (runStandardRule). Авто-дискавериться, активується при sync. Завершує Фасад A повністю.
+- n-cursor flow v2.0-a Ф3 (двигун-блоки): SubagentRunner (§15.1) — selectBackend (sdk>claude>cursor за ANTHROPIC_API_KEY/PATH, fail коли нічого нема), cliRunner (claude/cursor-agent -p, CLI-auth), sdkRunner (claude-agent-sdk, dynamic import); planner — parsePlan (валідація+нормалізація, fail-closed на невалідному) + generatePlan. Усе з мок-ін'єкцією (нуль реальних API/SDK у тестах). +24 тести.
+- n-cursor flow v2.0-a Ф4·a: executor.mjs — серце Активного Раннера. Виконує план покроково: мікропромпт зі стану (не історія) -> спавн субагента -> verify -> commit ЛИШЕ після зеленого (commit-інваріант §4.1.7) -> repair (per-step retry) -> на вичерпанні HITL (blocked-on-human + structured question). microprompt/patchStep — pure. Усе з ін'єкцією runner/verify/commit (нуль реальних LLM/git у тестах). +6 тестів.
+- n-cursor flow v2.0-a Ф4·b: Активний Раннер end-to-end. flow run (ensureWorktree -> planner -> executor; exit 0 done / 1 fail / 2 blocked-on-human), flow resume (safe-resume git reset + HITL-відповіді як hint + свіжі спроби), flow cancel (cleanup sibling-ів), flow repair (--discard-step-work / діагностика). ensureWorktree витягнуто як спільне для init/run. Усі 7 підкоманд реальні. +12 тестів (103 у dispatcher). v2.0-a (Фасади A+B) функціонально завершено.
+- n-cursor flow v2.0-a: (1) budget guard для flow run --autonomous (withBudget обгортає runner, BudgetExceeded при перевищенні maxApiCalls з .n-cursor.json flow.autonomous; на abort -> status failed, exit 1). (2) Ф1.4 борг закрито: worktree remove тепер reuse-кличе cleanupFlowSiblings (flow-sibling-и не осиротіють). Заодно виправлено передіснуючі switch-case-braces у worktree-cli. +4 тести.
+- n-cursor flow v2.0-b: команда n-cursor trace — наскрізна простежуваність (§5.4/§7). Читає front-matter артефактів у docs/{tasks,specs,plans,adr}, будує ланцюг за лінками adr/spec/plan/change/task, флагує розриви (лінк на неіснуючий файл) з exit 1; --json для machine-readable. parseFrontMatter/analyze/render — pure, FS ін'єктовний. Підтверджено на власних spec<->plan. +10 тестів.
+
+### Changed
+
+- n-cursor flow v2.0.0 (major): Dual-Mode Dispatcher — Пасивний Турнікет (flow init/verify/release) + Активний Раннер (flow run/resume/cancel/repair) + n-cursor trace + docs/{specs,plans} міграція
+
 ## [1.41.0] - 2026-05-31
 
 ### Changed

package/bin/n-cursor.js

@@ -1534,6 +1534,22 @@ try {
 
       break
     }
+    case 'flow': {
+      // n-cursor flow — Dual-Mode Dispatcher (spec §8): Пасивний Турнікет
+      // (init/verify/release) + Активний Раннер (run) навколо .flow.json.
+      const { runFlowCli } = await import('../scripts/dispatcher/index.mjs')
+      process.exitCode = await runFlowCli(args)
+
+      break
+    }
+    case 'trace': {
+      // n-cursor trace — наскрізна простежуваність (spec §5.4/§7): граф
+      // ADR↔spec↔plan↔change за front-matter + флаг розривів. exit 1 на розрив.
+      const { runTraceCli } = await import('../scripts/dispatcher/trace.mjs')
+      process.exitCode = runTraceCli(args)
+
+      break
+    }
     case undefined:
     case '': {
       await runSync()
@@ -1543,7 +1559,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill, worktree, lint-ci`
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill, worktree, lint-ci, flow, trace`
       )
       process.exitCode = 1
     }

package/package.json

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

package/rules/flow/fix.mjs

@@ -0,0 +1,18 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+ * Pure-doc contract-правило: програмних concern-ів немає, тож по суті валідує `.mdc`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/flow/fix.mjs — повний еквівалент `npx @nitra/cursor fix flow`.
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  process.exit(await runRuleCli(import.meta.dirname))
+}

package/rules/flow/flow.mdc

@@ -0,0 +1,51 @@
+---
+description: Контракт Пасивного Турнікета n-cursor flow — IDE-агент сам пише код, але ізолює/перевіряє/релізить через flow init/verify/release.
+globs:
+alwaysApply: true
+---
+
+# n-cursor flow — Пасивний Турнікет (контракт виконавця)
+
+`n-cursor flow` — це Dual-Mode Dispatcher. В інтерактивному середовищі (Cursor
+Composer, Claude Code) працює **Пасивний Турнікет**: ти, агент, **сам пишеш
+код**, а `n-cursor` лише ізолює роботу, **судить** її якість і релізить. Жодного
+прихованого спавну субагентів — керуєш ти.
+
+## Контракт (виконуй у цьому порядку)
+
+1. **Старт** — на початку задачі:
+
+   ```
+   npx @nitra/cursor flow init <branch> "<опис>"
+   ```
+
+   Створює ізольований worktree (`.worktrees/<branch>/`) і стан задачі. Якщо ти
+   вже в worktree — новий не вкладається.
+
+2. **Пиши код** сам, кроками. TDD: спершу падаючі тести, тоді реалізація.
+
+3. **Перевіряй** після кожного логічного кроку:
+
+   ```
+   npx @nitra/cursor flow verify
+   ```
+
+   Проганяє Quality Gates (lint + coverage). Повертає `0` (pass) або `1` із
+   виводом проваленого gate.
+
+4. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
+   **3 спроби**; якщо не вдається — зупинись і поклич людину.
+
+5. **Фініш** — лише після зеленого `verify`:
+
+   ```
+   npx @nitra/cursor flow release --bump <patch|minor|major> --section <Added|Changed|Fixed> --message "<що зроблено>"
+   ```
+
+   Генерує `.changes/` і пише completion snapshot. Гілка готова до merge.
+
+## Чого не роби
+
+- Не обходь `verify` — це єдиний критерій «готово».
+- Не редагуй `version` чи `CHANGELOG.md` вручну (це робить CI з `.changes/`).
+- Не коміть стан `.worktrees/<branch>.flow.json` у гілку — він поза git.

package/rules/flow/meta.json

@@ -0,0 +1 @@
+{}

package/rules/js-bun-db/js-bun-db.mdc

@@ -2,7 +2,7 @@
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 globs: "**/package.json,**/src/conn/**"
 alwaysApply: false
-version: '1.12'
+version: '1.14'
 ---
 
 ## Підтримувані версії баз даних
@@ -57,16 +57,12 @@ const sql = format(`MERGE INTO t USING (VALUES %s) AS s(id, date, data) ON ...`,
 await pgWrite.unsafe(sql)
 
 // ✅ UNNEST — 3 параметри незалежно від розміру batch; план стабільний і може кешуватись
-const ids   = batch.map(r => r.id)
-const dates = batch.map(r => r.date)
-const data  = batch.map(r => JSON.stringify(r.data))
-
 await pgWrite`
   WITH s(id, date, data) AS (
     SELECT * FROM unnest(
-      ${ids}::int[],
-      ${dates}::date[],
-      ${data}::jsonb[]
+      ${pgWrite.array(batch.map(r => r.id),   'int4')},
+      ${pgWrite.array(batch.map(r => r.date), 'date')},
+      ${pgWrite.array(batch.map(r => r.data), 'jsonb')}
     )
   )
   MERGE INTO my_table AS t
@@ -98,6 +94,22 @@ await pgWrite`
 `
 ```
 
+## JSONB-параметри: без `JSON.stringify`
+
+Bun SQL серіалізує JS-об'єкти й масиви у JSON автоматично — викликати `JSON.stringify` перед передачею в `::jsonb` / `::jsonb[]` **заборонено**.
+
+```javascript
+// ❌ зайвий JSON.stringify — подвійна серіалізація або зайвий рядок
+await sql`INSERT INTO events (details) VALUES (${JSON.stringify(detailsForEvent)}::jsonb)`
+
+await sql`SELECT * FROM unnest(${sql.array(batch.map(r => JSON.stringify(r.data)), 'jsonb')})`
+
+// ✅ об'єкт/масив передається напряму
+await sql`INSERT INTO events (details) VALUES (${detailsForEvent}::jsonb)`
+
+await sql`SELECT * FROM unnest(${sql.array(batch.map(r => r.data), 'jsonb')})`
+```
+
 `UNION ALL`-цикл замість `unnest` підходить для малих динамічних запитів (2–5 рядків), де кожна гілка семантично різна. Для bulk upsert — завжди `unnest`.
 
 ### Заборонений «drop-in» шим

package/rules/js-lint/js/data/tooling/oxlint-canonical.json

@@ -396,5 +396,5 @@
     "builtin": true
   },
   "globals": {},
-  "ignorePatterns": ["**/schema.graphql", "**/auto-imports.d.ts"]
+  "ignorePatterns": ["npm/types/**", "demo/node/rules-demo.js", "**/schema.graphql", "**/auto-imports.d.ts"]
 }

package/scripts/dispatcher/index.mjs

@@ -0,0 +1,48 @@
+/**
+ * CLI-диспетчер `n-cursor flow` (spec §8 Dual-Mode Dispatcher).
+ *
+ * Два фасади навколо єдиного джерела істини `.flow.json`:
+ *  - **Пасивний Турнікет** (Фасад A): `init`, `verify`, `release` — для IDE-
+ *    агентів (Cursor/Claude Code), що самі пишуть код; `n-cursor` лише судить.
+ *  - **Активний Раннер** (Фасад B): `run`, `resume`, `cancel`, `repair` —
+ *    повний 5-фазний polyfill-цикл для headless/CI.
+ */
+import { cancel, repair, resume, run } from './lib/active.mjs'
+import { init, release, verify } from './lib/commands.mjs'
+
+const USAGE = [
+  'Usage:',
+  '  npx @nitra/cursor flow init "<опис>"      # Фасад A: worktree + .flow.json',
+  '  npx @nitra/cursor flow verify             # Фасад A: Quality Gates (pass/fail)',
+  '  npx @nitra/cursor flow release            # Фасад A: .changes + completion snapshot',
+  '  npx @nitra/cursor flow run "<опис>"       # Фасад B: повний 5-фазний цикл',
+  '  npx @nitra/cursor flow resume             # продовжити з чекпойнта',
+  '  npx @nitra/cursor flow cancel             # скасувати, прибрати стан',
+  '  npx @nitra/cursor flow repair [--discard-step-work]   # відновлення пошкодженого стану'
+].join('\n')
+
+/** Підкоманди flow. */
+export const SUBCOMMANDS = ['init', 'verify', 'release', 'run', 'resume', 'cancel', 'repair']
+
+/**
+ * Усі handler-и реальні (Ф2 Турнікет + Ф4 Активний Раннер).
+ * @type {Record<string, (rest: string[], deps: object) => Promise<number>>}
+ */
+export const DEFAULT_HANDLERS = { init, verify, release, run, resume, cancel, repair }
+
+/**
+ * Точка входу `case 'flow'` у `bin/n-cursor.js`. Парсить підкоманду й
+ * маршрутизує до handler-а. Невідома/відсутня підкоманда → usage + код 1.
+ * @param {string[]} args аргументи після `flow`
+ * @param {{ handlers?: Record<string, (rest: string[], deps: object) => Promise<number>> }} [deps] ін'єкція handler-ів (для тестів)
+ * @returns {Promise<number>} exit code
+ */
+export async function runFlowCli(args, deps = {}) {
+  const [sub, ...rest] = args
+  const handlers = deps.handlers ?? DEFAULT_HANDLERS
+  if (!sub || ! Object.hasOwn(handlers, sub)) {
+    console.error(USAGE)
+    return 1
+  }
+  return await handlers[sub](rest, deps)
+}

package/scripts/dispatcher/lib/active.mjs

@@ -0,0 +1,226 @@
+/**
+ * Активний Раннер (spec §8.1 Фасад B): `run`/`resume`/`cancel`/`repair`. Зшиває
+ * ensureWorktree + planner + executor + verify у повний 5-фазний цикл. Уся IO
+ * ін'єктується (`runner`/`verify`/`commit`/`run`/`now`) — тестується без
+ * реальних LLM/git/gates.
+ */
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+import { BudgetExceeded, withBudget } from './budget.mjs'
+import { ensureWorktree, realRun } from './commands.mjs'
+import { flowEventsPath } from './events.mjs'
+import { executePlan } from './executor.mjs'
+import { generatePlan } from './planner.mjs'
+import { runReview } from './reviewer.mjs'
+import {
+  cleanupFlowSiblings,
+  flowStatePath,
+  readState,
+  updateState,
+  writeState
+} from './state-store.mjs'
+import { createRunner } from './subagent-runner.mjs'
+
+/**
+ * Дефолтний commit: `git add -A && git commit -m` у worktree.
+ * @param {string} cwd worktree
+ * @param {string} msg повідомлення
+ * @returns {void}
+ */
+function defaultCommit(cwd, msg) {
+  spawnSync('git', ['add', '-A'], { cwd })
+  spawnSync('git', ['commit', '-m', msg], { cwd })
+}
+
+/**
+ * Дефолтний verify для executor-а: проганяє gates і повертає verdict.
+ * @param {string} cwd worktree
+ * @returns {{ pass: boolean, failedOutput: string | null }} verdict
+ */
+function defaultVerify(cwd) {
+  return runReview({ run: realRun, cwd, fingerprint: () => null })
+}
+
+/**
+ * Читає `flow.autonomous` із `.n-cursor.json` (бюджет автономного режиму).
+ * @param {string} cwd корінь
+ * @returns {{ maxApiCalls?: number, maxCostUsd?: number, onBudgetExceeded?: string }} конфіг бюджету
+ */
+function readFlowAutonomous(cwd) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(cwd, '.n-cursor.json'), 'utf8'))
+    return cfg?.flow?.autonomous ?? {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * `flow run [--autonomous] <branch> "<task>"` — повний цикл: ensureWorktree →
+ * план → executor. У `--autonomous` runner обгортається budget guard-ом (§9.4).
+ * @param {string[]} rest аргументи (`--autonomous` + `<branch> <task...>`)
+ * @param {{ runner?: object, verify?: (cwd: string) => object, commit?: (cwd: string, msg: string) => void, run?: (cmd: string, args: string[], opts: object) => object, autonomous?: boolean, budget?: object, cwd?: string, log?: (m: string) => void, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code: 0 done, 1 fail, 2 blocked-on-human
+ */
+export async function run(rest, deps = {}) {
+  const log = deps.log ?? console.error
+  const now = deps.now ?? Date.now
+  const autonomous = deps.autonomous ?? rest.includes('--autonomous')
+  const positional = rest.filter(a => !a.startsWith('--'))
+
+  const ew = ensureWorktree(positional, deps)
+  if (ew.code !== 0) return ew.code
+  const { worktreeDir, branch, desc, baseCommit } = ew
+  const statePath = flowStatePath(worktreeDir)
+  writeState(statePath, {
+    branch,
+    status: 'in_progress',
+    started_at: new Date(now()).toISOString(),
+    metadata: { base_commit: baseCommit },
+    plan: []
+  })
+
+  let runner
+  try {
+    runner = deps.runner ?? (await createRunner(deps))
+  } catch (error) {
+    log(`run: ${error.message}`)
+    return 1
+  }
+  if (autonomous) {
+    const budget = deps.budget ?? readFlowAutonomous(deps.cwd ?? processCwd())
+    runner = withBudget(runner, { maxApiCalls: budget.maxApiCalls, log })
+  }
+
+  try {
+    const plan = await generatePlan({ runner, task: desc, cwd: worktreeDir })
+    updateState(statePath, s => ({ ...s, plan }))
+    const result = await executePlan(
+      { statePath, eventsPath: flowEventsPath(worktreeDir) },
+      { runner, verify: deps.verify ?? defaultVerify, commit: deps.commit ?? defaultCommit, cwd: worktreeDir, log, now }
+    )
+    if (result.status === 'done') {
+      log('run: build done — далі `flow release`')
+      return 0
+    }
+    if (result.status === 'blocked-on-human') {
+      log(`run: blocked-on-human на кроці ${result.step}`)
+      return 2
+    }
+    return 1
+  } catch (error) {
+    if (error instanceof BudgetExceeded) {
+      log(`run: ${error.message} — abort`)
+      updateState(statePath, s => ({ ...s, status: 'failed' }))
+      return 1
+    }
+    log(`run: ${error.message}`)
+    return 1
+  }
+}
+
+/**
+ * `flow resume` — продовжує з чекпойнта. Safe-resume (§4.1.7): скидає частковий
+ * доробок до останнього коміту; застосовує HITL-відповіді як підказки й дає
+ * крокам свіжі спроби.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {object} [deps] ін'єкції (як у `run`)
+ * @returns {Promise<number>} exit code
+ */
+export async function resume(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const now = deps.now ?? Date.now
+  const run_ = deps.run ?? realRun
+
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  if (!state) {
+    log('resume: стану нема')
+    return 1
+  }
+
+  const openHitl = (state.hitl ?? []).filter(q => !q.answer)
+  if (state.status === 'blocked-on-human' && openHitl.length > 0) {
+    log(`resume: ще blocked — ${openHitl.length} відкритих HITL-питань (заповни answer і повтори)`)
+    return 2
+  }
+  if (!state.plan?.length) {
+    log('resume: нема плану')
+    return 1
+  }
+
+  // safe-resume: скинути частковий доробок невдалого кроку до останнього коміту
+  run_('git', ['reset', '--hard', 'HEAD'], { cwd })
+
+  // застосувати HITL-відповіді як hint + дати незавершеним крокам свіжі спроби
+  const answers = new Map((state.hitl ?? []).filter(q => q.answer).map(q => [q.step, q.answer]))
+  updateState(statePath, s => ({
+    ...s,
+    status: 'in_progress',
+    plan: s.plan.map(st =>
+      st.status === 'done' ? st : { ...st, retry_count: 0, ...(answers.has(st.step) ? { hint: answers.get(st.step) } : {}) }
+    ),
+    hitl: (s.hitl ?? []).map(q => (q.answer ? { ...q, status: 'answered' } : q))
+  }))
+
+  let runner
+  try {
+    runner = deps.runner ?? (await createRunner(deps))
+  } catch (error) {
+    log(`resume: ${error.message}`)
+    return 1
+  }
+
+  const result = await executePlan(
+    { statePath, eventsPath: flowEventsPath(cwd) },
+    { runner, verify: deps.verify ?? defaultVerify, commit: deps.commit ?? defaultCommit, cwd, log, now }
+  )
+  if (result.status === 'done') return 0
+  if (result.status === 'blocked-on-human') return 2
+  return 1
+}
+
+/**
+ * `flow cancel` — скасування: прибирає transient sibling-и (стан/журнал/lock).
+ * @param {string[]} _rest аргументи
+ * @param {{ cwd?: string, log?: (m: string) => void }} [deps] ін'єкції
+ * @returns {Promise<number>} 0
+ */
+export async function cancel(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  cleanupFlowSiblings(cwd)
+  log('cancel: стан і sibling-и прибрано')
+  return 0
+}
+
+/**
+ * `flow repair [--discard-step-work]` — fail-closed escape: діагностика стану або
+ * жорстке скидання робочого дерева до HEAD (свідоме викидання доробку).
+ * @param {string[]} rest аргументи
+ * @param {{ run?: (cmd: string, args: string[], opts: object) => object, cwd?: string, log?: (m: string) => void }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function repair(rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const run_ = deps.run ?? realRun
+
+  if (rest.includes('--discard-step-work')) {
+    run_('git', ['reset', '--hard', 'HEAD'], { cwd })
+    log('repair: робоче дерево скинуто до HEAD (--discard-step-work)')
+    return 0
+  }
+  try {
+    const state = readState(flowStatePath(cwd))
+    log(state ? `repair: стан валідний (status: ${state.status})` : 'repair: стану нема')
+    return 0
+  } catch (error) {
+    log(`repair: стан пошкоджено — ${error.message}. Спробуй \`flow repair --discard-step-work\` або \`flow cancel\`.`)
+    return 1
+  }
+}

package/scripts/dispatcher/lib/budget.mjs

@@ -0,0 +1,36 @@
+/**
+ * Budget guard для автономного режиму (spec §9.4): обгортає SubagentRunner
+ * лічильником викликів і кидає `BudgetExceeded` при перевищенні `maxApiCalls`.
+ * Це запобіжник проти неконтрольованих витрат на сервері (де нема людини).
+ *
+ * (`maxCostUsd` — коли runner повертатиме tokens/cost; наразі рахуємо виклики.)
+ */
+
+/** Помилка перевищення бюджету (ловиться в `run`, §9.4). */
+export class BudgetExceeded extends Error {}
+
+/**
+ * Обгортає runner лічильником API-викликів.
+ * @param {{ backend?: string, runStep: (prompt: string, opts?: object) => object }} runner базовий runner
+ * @param {{ maxApiCalls?: number, log?: (m: string) => void }} [opts] ліміт і лог
+ * @returns {{ backend: string, runStep: (prompt: string, opts?: object) => Promise<object>, readonly calls: number }} обгорнутий runner
+ */
+export function withBudget(runner, opts = {}) {
+  const maxApiCalls = opts.maxApiCalls ?? Number.POSITIVE_INFINITY
+  const log = opts.log ?? (() => {})
+  let calls = 0
+  return {
+    backend: runner.backend,
+    get calls() {
+      return calls
+    },
+    async runStep(prompt, stepOpts) {
+      if (calls >= maxApiCalls) {
+        throw new BudgetExceeded(`budget: вичерпано maxApiCalls=${maxApiCalls}`)
+      }
+      calls += 1
+      log(`budget: API-виклик ${calls}/${maxApiCalls}`)
+      return runner.runStep(prompt, stepOpts)
+    }
+  }
+}

package/scripts/dispatcher/lib/capability.mjs

@@ -0,0 +1,81 @@
+/**
+ * Capability Router — резолвер режиму оркестрації (`native` vs `polyfill`)
+ * за **явною декларацією моделі** (spec §2.2).
+ *
+ * Рантайм-детекції моделі в кодобазі немає — тому модель НЕ вгадуємо, а
+ * оголошуємо за пріоритетом: CLI `--model` > env `N_CURSOR_FLOW_MODEL` >
+ * config `flow.model`. Default-режим (`polyfill`) дозволений ЛИШЕ за наявного
+ * `SubagentRunner` (§15.1); інакше — fail (caller кидає помилку), бо polyfill
+ * без runner-а не «працює з будь-якою моделлю».
+ *
+ * Усі функції чисті (без I/O) — джерела (`args`/`env`/`config`/`matrix`/
+ * `hasRunner`) передаються ззовні, що робить модуль тривіально тестованим.
+ */
+
+export const DEFAULT_ORCHESTRATION = 'polyfill'
+
+/**
+ * Витягує значення `--model <value>` з argv. Не мутує вхід.
+ * @param {string[]} args аргументи підкоманди flow
+ * @returns {string | null} оголошена модель або null
+ */
+export function parseModelFlag(args) {
+  const i = args.indexOf('--model')
+  return i !== -1 && i + 1 < args.length ? args[i + 1] : null
+}
+
+/**
+ * Оголошена модель за пріоритетом CLI > env > config.
+ * @param {{ cliModel?: string | null, envModel?: string | null, configModel?: string | null }} sources джерела декларації
+ * @returns {string | null} модель або null, якщо ніде не оголошено
+ */
+export function declaredModel({ cliModel = null, envModel = null, configModel = null } = {}) {
+  return cliModel || envModel || configModel || null
+}
+
+/**
+ * Режим оркестрації для оголошеної моделі за `capability-matrix`.
+ * Невідома/неоголошена модель → `matrix.default` → `DEFAULT_ORCHESTRATION`.
+ * @param {string | null} model оголошена модель
+ * @param {{ models?: Record<string, { orchestration?: string }>, default?: { orchestration?: string } }} matrix матриця можливостей
+ * @returns {'native' | 'polyfill'} режим
+ */
+export function orchestrationFor(model, matrix) {
+  const entry = model && matrix && matrix.models ? matrix.models[model] : null
+  return (
+    (entry && entry.orchestration) ||
+    (matrix && matrix.default && matrix.default.orchestration) ||
+    DEFAULT_ORCHESTRATION
+  )
+}
+
+/**
+ * Чи стартує polyfill: потрібен доступний `SubagentRunner`.
+ * @param {{ hasRunner: boolean }} ctx контекст середовища
+ * @returns {boolean} true, якщо runner у наявності
+ */
+export function polyfillStartable({ hasRunner }) {
+  return hasRunner === true
+}
+
+/**
+ * Повний резолв: оголошена модель + режим. Кидає, якщо polyfill без runner-а.
+ * @param {{ args?: string[], env?: Record<string, string | undefined>, config?: { flow?: { model?: string } }, matrix: object, hasRunner: boolean }} input джерела
+ * @returns {{ model: string | null, mode: 'native' | 'polyfill' }} оголошена модель і режим
+ */
+export function resolveFlow({ args = [], env = {}, config = {}, matrix, hasRunner }) {
+  const model = declaredModel({
+    cliModel: parseModelFlag(args),
+    envModel: env.N_CURSOR_FLOW_MODEL ?? null,
+    configModel: (config && config.flow && config.flow.model) ?? null
+  })
+  const mode = orchestrationFor(model, matrix)
+  if (mode === 'polyfill' && !polyfillStartable({ hasRunner })) {
+    throw new Error(
+      'n-cursor flow: режим polyfill потребує доступного SubagentRunner ' +
+        '(`claude` або `cursor-agent` у PATH), але жодного не знайдено. ' +
+        'Оголосіть модель із native_workflows (--model) або встановіть CLI-runner.'
+    )
+  }
+  return { model, mode }
+}