@nitra/cursor 4.1.0 → 4.1.1

package/scripts/dispatcher/graph/lib/node-state.mjs

@@ -0,0 +1,157 @@
+/**
+ * Деривація стану вузла з файлової системи (immutable file-presence protocol).
+ *
+ * Стан визначається виключно наявністю файлів у tasks/<node>/:
+ *   invalidated > resolved > pending-audit > running > failed > waiting > needs-plan
+ *
+ * Чиста функція — FS ін'єктується. Не пише нічого на диск.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { hasPendingAudit, latestFactNNN } from './nnn.mjs'
+
+/** Всі можливі стани вузла. */
+export const NODE_STATES = /** @type {const} */ ([
+  'needs-plan',
+  'waiting',
+  'running',
+  'pending-audit',
+  'resolved',
+  'failed',
+  'invalidated'
+])
+
+/**
+ * Перевіряє чи директорія є composite-вузлом (містить дочірні директорії з task.md).
+ * @param {string} nodeDir абсолютний шлях до директорії вузла
+ * @param {{ readdirSync?: (d: string) => string[], existsSync?: (p: string) => boolean }} [deps] ін'єкції
+ * @returns {boolean} true якщо є хоча б один дочірній вузол
+ */
+export function isComposite(nodeDir, deps = {}) {
+  const readdir = deps.readdirSync ?? readdirSync
+  const exists = deps.existsSync ?? existsSync
+
+  let entries
+  try {
+    entries = readdir(nodeDir)
+  } catch {
+    return false
+  }
+
+  return entries.some(name => {
+    const childTask = join(nodeDir, name, 'task.md')
+    return exists(childTask)
+  })
+}
+
+/**
+ * Деривує composite-стан з масиву станів дочірніх вузлів.
+ * @param {string[]} childStates масив станів дочірніх вузлів
+ * @returns {string} агрегований стан
+ */
+export function deriveCompositeState(childStates) {
+  if (childStates.length === 0) return 'waiting'
+  if (childStates.some(s => s === 'invalidated')) return 'invalidated'
+  if (childStates.some(s => s === 'failed')) return 'failed'
+  if (childStates.some(s => s === 'running')) return 'running'
+  if (childStates.some(s => s === 'pending-audit')) return 'pending-audit'
+  if (childStates.every(s => s === 'resolved')) return 'resolved'
+  return 'waiting'
+}
+
+/**
+ * Деривує стан одного вузла з присутності файлів.
+ *
+ * Пріоритет: invalidated > resolved > pending-audit > running > failed > waiting > needs-plan
+ *
+ * @param {string} nodeDir абсолютний шлях до директорії вузла
+ * @param {Set<string>} activeWorktrees set імен активних worktree (наприклад, 'my-node-1234567890')
+ * @param {{
+ *   readdirSync?: (d: string) => string[],
+ *   readFileSync?: (p: string, enc: string) => string,
+ *   existsSync?: (p: string) => boolean
+ * }} [deps] ін'єкції
+ * @returns {string} стан вузла
+ */
+export function deriveNodeState(nodeDir, activeWorktrees, deps = {}) {
+  const readdir = deps.readdirSync ?? readdirSync
+  const readFile = deps.readFileSync ?? ((p, enc) => readFileSync(p, enc))
+  const exists = deps.existsSync ?? existsSync
+
+  // Файл task.md обов'язковий
+  if (!exists(join(nodeDir, 'task.md'))) {
+    return 'needs-plan'
+  }
+
+  let files
+  try {
+    files = readdir(nodeDir)
+  } catch {
+    return 'needs-plan'
+  }
+
+  const fileSet = new Set(files)
+
+  // 1. invalidated — sentinel файл
+  if (fileSet.has('invalidated')) return 'invalidated'
+
+  // 2. resolved — є fact_NNN.md і немає invalidated
+  const factNNN = latestFactNNN(nodeDir, readdir)
+  if (factNNN !== null) return 'resolved'
+
+  // 3. pending-audit — є pending-audit_NNN.md без відповідного audit-result_NNN.md
+  const { has: hasPending } = hasPendingAudit(nodeDir, readdir)
+  if (hasPending) return 'pending-audit'
+
+  // 4. running — активний worktree існує (перевіряємо за prefix node dir name)
+  const nodeName = nodeDir.split('/').filter(Boolean).pop() ?? ''
+  if (activeWorktrees.size > 0) {
+    for (const wt of activeWorktrees) {
+      // worktree name: sanitized-node-path-epoch
+      if (wt.includes(sanitizeNodeName(nodeName))) return 'running'
+    }
+  }
+
+  // 5. failed — є run_NNN.md з result:failed, без fact_NNN.md і без активного worktree
+  const runFiles = files.filter(f => /^run_\d+\.md$/.test(f))
+  if (runFiles.length > 0) {
+    // Перевіряємо останній run файл
+    let hasFailedRun = false
+    for (const runFile of runFiles) {
+      try {
+        const content = readFile(join(nodeDir, runFile), 'utf8')
+        if (content.includes('result: failed') || content.includes('result:failed')) {
+          hasFailedRun = true
+        }
+      } catch {
+        // пропускаємо нечитабельні файли
+      }
+    }
+    if (hasFailedRun) return 'failed'
+  }
+
+  // 6. waiting — є plan_NNN.md АБО mode:agent
+  const hasPlan = files.some(f => /^plan_\d+\.md$/.test(f))
+  if (hasPlan) return 'waiting'
+
+  // Читаємо mode з task.md
+  try {
+    const taskContent = readFile(join(nodeDir, 'task.md'), 'utf8')
+    if (taskContent.includes('mode: agent')) return 'waiting'
+  } catch {
+    // пропускаємо
+  }
+
+  // 7. needs-plan — task.md є, mode:human (default), немає plan_NNN.md
+  return 'needs-plan'
+}
+
+/**
+ * Санітизує ім'я вузла для використання в назві worktree.
+ * @param {string} name ім'я вузла (може містити /)
+ * @returns {string} санітизоване ім'я
+ */
+export function sanitizeNodeName(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, '-')
+}

package/scripts/dispatcher/graph/lib/scanner.mjs

@@ -0,0 +1,235 @@
+/**
+ * DAG-сканер вузлів задач.
+ *
+ * Рекурсивно обходить tasks_dir, знаходить всі вузли (директорії з task.md),
+ * читає їх залежності з task.md front-matter, деривує стани та виконує
+ * топологічне сортування (Kahn's algorithm).
+ *
+ * FS ін'єктується. Нічого не пише на диск.
+ */
+import { execSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parseFrontMatter } from './frontmatter.mjs'
+import { deriveNodeState, isComposite } from './node-state.mjs'
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   path: string,
+ *   dir: string,
+ *   deps: string[],
+ *   state: string,
+ *   composite: boolean,
+ *   children: string[]
+ * }} NodeInfo
+ */
+
+/**
+ * Рекурсивно знаходить всі вузли DAG у tasks_dir.
+ * Вузол = директорія що містить task.md.
+ * @param {string} tasksDir абсолютний шлях до tasks/
+ * @param {{
+ *   readdirSync?: (d: string) => string[],
+ *   existsSync?: (p: string) => boolean,
+ *   readFileSync?: (p: string, enc: string) => string
+ * }} [deps] ін'єкції
+ * @returns {{ dir: string, relPath: string }[]} список знайдених вузлів
+ */
+export function findNodes(tasksDir, deps = {}) {
+  const readdir = deps.readdirSync ?? readdirSync
+  const exists = deps.existsSync ?? existsSync
+
+  const nodes = []
+
+  function scan(dir, prefix = '') {
+    let entries
+    try {
+      entries = readdir(dir)
+    } catch {
+      return
+    }
+
+    const hasTaskMd = entries.includes('task.md')
+    if (hasTaskMd) {
+      nodes.push({
+        dir,
+        relPath: prefix ? prefix : dir.split('/').pop() ?? dir
+      })
+    }
+
+    // Рекурсивно шукаємо дочірні директорії
+    for (const name of entries) {
+      // Пропускаємо зарезервовані та приховані директорії/файли
+      if (name.startsWith('.') || name.includes('.')) continue
+      const childDir = join(dir, name)
+      // Перевіряємо що це директорія (якщо має subdirs або task.md)
+      const childRelPath = prefix ? `${prefix}/${name}` : name
+      try {
+        // Перевірка що childDir — дійсно директорія
+        readdir(childDir)
+        scan(childDir, childRelPath)
+      } catch {
+        // не директорія або не читається
+      }
+    }
+  }
+
+  scan(tasksDir)
+  return nodes
+}
+
+/**
+ * Сканує DAG і повертає всі вузли з деривованими станами.
+ * @param {string} tasksDir абсолютний шлях до tasks/
+ * @param {Set<string>} activeWorktrees активні worktree imена
+ * @param {{
+ *   readdirSync?: (d: string) => string[],
+ *   existsSync?: (p: string) => boolean,
+ *   readFileSync?: (p: string, enc: string) => string
+ * }} [deps] ін'єкції
+ * @returns {NodeInfo[]} список вузлів
+ */
+export function scanNodes(tasksDir, activeWorktrees, deps = {}) {
+  const readdir = deps.readdirSync ?? readdirSync
+  const exists = deps.existsSync ?? existsSync
+  const readFile = deps.readFileSync ?? ((p, enc) => readFileSync(p, enc))
+
+  const found = findNodes(tasksDir, { readdirSync: readdir, existsSync: exists, readFileSync: readFile })
+
+  return found.map(({ dir, relPath }) => {
+    let fm = {}
+    try {
+      const taskContent = readFile(join(dir, 'task.md'), 'utf8')
+      fm = parseFrontMatter(taskContent)
+    } catch {
+      // порожній front-matter
+    }
+
+    const deps_ = Array.isArray(fm.deps) ? fm.deps.map(String) : []
+    const state = deriveNodeState(dir, activeWorktrees, { readdirSync: readdir, readFileSync: readFile, existsSync: exists })
+    const composite = isComposite(dir, { readdirSync: readdir, existsSync: exists })
+
+    // Дочірні вузли
+    let children = []
+    if (composite) {
+      let entries
+      try {
+        entries = readdir(dir)
+      } catch {
+        entries = []
+      }
+      children = entries
+        .filter(name => !name.startsWith('.') && !name.endsWith('.md') && !name.endsWith('.json'))
+        .filter(name => {
+          try {
+            return exists(join(dir, name, 'task.md'))
+          } catch {
+            return false
+          }
+        })
+        .map(name => `${relPath}/${name}`)
+    }
+
+    return {
+      id: relPath,
+      path: relPath,
+      dir,
+      deps: deps_,
+      state,
+      composite,
+      children
+    }
+  })
+}
+
+/**
+ * Топологічне сортування вузлів (алгоритм Кана).
+ * Вузли без залежностей — першими. Циклічні залежності — не гарантовано.
+ * @param {NodeInfo[]} nodes вузли зі списком deps
+ * @returns {NodeInfo[]} відсортований список (або той самий порядок якщо циклічні)
+ */
+export function topoSort(nodes) {
+  const idToNode = new Map(nodes.map(n => [n.id, n]))
+  const inDegree = new Map(nodes.map(n => [n.id, 0]))
+  const adj = new Map(nodes.map(n => [n.id, []]))
+
+  for (const node of nodes) {
+    for (const dep of node.deps) {
+      if (idToNode.has(dep)) {
+        adj.get(dep).push(node.id)
+        inDegree.set(node.id, (inDegree.get(node.id) ?? 0) + 1)
+      }
+    }
+  }
+
+  const queue = nodes.filter(n => (inDegree.get(n.id) ?? 0) === 0).map(n => n.id)
+  const sorted = []
+
+  while (queue.length > 0) {
+    const id = queue.shift()
+    const node = idToNode.get(id)
+    if (node) sorted.push(node)
+    for (const next of (adj.get(id) ?? [])) {
+      const deg = (inDegree.get(next) ?? 0) - 1
+      inDegree.set(next, deg)
+      if (deg === 0) queue.push(next)
+    }
+  }
+
+  // Якщо є цикли — додаємо решту у кінець
+  if (sorted.length < nodes.length) {
+    for (const n of nodes) {
+      if (!sorted.includes(n)) sorted.push(n)
+    }
+  }
+
+  return sorted
+}
+
+/**
+ * Перевіряє чи всі залежності вузла resolved.
+ * @param {NodeInfo} node вузол
+ * @param {Map<string, NodeInfo>} nodeMap map id -> NodeInfo
+ * @returns {boolean} true якщо всі deps resolved
+ */
+export function areDepsResolved(node, nodeMap) {
+  return node.deps.every(dep => {
+    const depNode = nodeMap.get(dep)
+    return depNode?.state === 'resolved'
+  })
+}
+
+/**
+ * Знаходить активні worktrees з git worktree list.
+ * @param {string} root корінь репо
+ * @param {{ execSync?: (cmd: string, opts?: object) => string }} [deps] ін'єкції
+ * @returns {Set<string>} set імен worktree
+ */
+export function getActiveWorktrees(root, deps = {}) {
+  const execSyncFn = deps.execSync ?? ((cmd, opts) => execSync(cmd, opts))
+  try {
+    const out = execSyncFn('git worktree list --porcelain', { cwd: root, encoding: 'utf8' })
+    return parseWorktreeList(String(out))
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * Парсить вивід `git worktree list --porcelain` і повертає набір імен worktree.
+ * @param {string} output вивід команди
+ * @returns {Set<string>} set імен (останній компонент шляху)
+ */
+export function parseWorktreeList(output) {
+  const names = new Set()
+  for (const line of output.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      const path = line.slice('worktree '.length).trim()
+      const name = path.split('/').pop() ?? ''
+      if (name) names.add(name)
+    }
+  }
+  return names
+}

package/scripts/dispatcher/graph/lib/worktree-ops.mjs

@@ -0,0 +1,193 @@
+/**
+ * Git worktree management для graph task system.
+ *
+ * Atomic mkdir lock: EEXIST → skip (вже запущено).
+ * Worktree name: sanitize(node-path) + '-' + epoch (секунди).
+ *
+ * Всі git операції через execSync (node:child_process). FS через ін'єкцію.
+ */
+import { execSync } from 'node:child_process'
+import { mkdirSync, readdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { sanitizeNodeName } from './node-state.mjs'
+
+/**
+ * Генерує ім'я worktree для вузла.
+ * @param {string} nodePath відносний шлях вузла (напр. "research/collect-data")
+ * @param {number} [epochSec] epoch в секундах (default: Date.now()/1000)
+ * @returns {string} ім'я worktree
+ */
+export function makeWorktreeName(nodePath, epochSec) {
+  const epoch = epochSec ?? Math.floor(Date.now() / 1000)
+  const sanitized = sanitizeNodeName(nodePath.replace(/\//g, '-'))
+  return `${sanitized}-${epoch}`
+}
+
+/**
+ * Створює git worktree для вузла з atomic mkdir lock.
+ * Повертає null якщо worktree вже існує (EEXIST → вже запущено).
+ *
+ * @param {string} worktreesDir абсолютний шлях до .worktrees/
+ * @param {string} worktreeName ім'я нового worktree
+ * @param {string} root корінь репо
+ * @param {{
+ *   execSync?: (cmd: string, opts?: object) => string,
+ *   mkdirSync?: (p: string, opts?: object) => void
+ * }} [deps] ін'єкції
+ * @returns {{ worktreePath: string } | null} шлях worktree або null якщо вже існує
+ */
+export function createWorktree(worktreesDir, worktreeName, root, deps = {}) {
+  const execSyncFn = deps.execSync ?? ((cmd, opts) => execSync(cmd, opts))
+  const mkdirSyncFn = deps.mkdirSync ?? mkdirSync
+
+  const worktreePath = join(worktreesDir, worktreeName)
+
+  // Atomic mkdir lock: якщо директорія вже є — хтось вже запустив цей вузол
+  try {
+    mkdirSyncFn(worktreePath, { recursive: false })
+  } catch (err) {
+    if (err.code === 'EEXIST') return null
+    throw err
+  }
+
+  try {
+    // Видаляємо порожню директорію — git worktree add створить її сам
+    rmSync(worktreePath, { recursive: true, force: true })
+    execSyncFn(`git worktree add "${worktreePath}" HEAD`, { cwd: root, encoding: 'utf8' })
+  } catch (err) {
+    // Якщо git worktree add не вдався — прибираємо директорію
+    try {
+      rmSync(worktreePath, { recursive: true, force: true })
+    } catch {
+      // пропускаємо
+    }
+    throw err
+  }
+
+  return { worktreePath }
+}
+
+/**
+ * Видаляє git worktree.
+ * @param {string} worktreePath абсолютний шлях до worktree
+ * @param {string} root корінь репо
+ * @param {{
+ *   execSync?: (cmd: string, opts?: object) => string
+ * }} [deps] ін'єкції
+ */
+export function removeWorktree(worktreePath, root, deps = {}) {
+  const execSyncFn = deps.execSync ?? ((cmd, opts) => execSync(cmd, opts))
+  try {
+    execSyncFn(`git worktree remove --force "${worktreePath}"`, { cwd: root, encoding: 'utf8' })
+  } catch {
+    // Якщо не вдалось через git — видаляємо вручну
+    try {
+      rmSync(worktreePath, { recursive: true, force: true })
+      execSyncFn('git worktree prune', { cwd: root, encoding: 'utf8' })
+    } catch {
+      // пропускаємо — можливо вже видалено
+    }
+  }
+}
+
+/**
+ * Мерджить зміни з worktree у main-гілку і видаляє worktree.
+ * @param {string} worktreePath абсолютний шлях до worktree
+ * @param {string} root корінь репо
+ * @param {{
+ *   execSync?: (cmd: string, opts?: object) => string
+ * }} [deps] ін'єкції
+ * @returns {{ ok: boolean, error?: string }} результат
+ */
+export function mergeWorktree(worktreePath, root, deps = {}) {
+  const execSyncFn = deps.execSync ?? ((cmd, opts) => execSync(cmd, opts))
+
+  try {
+    // Отримуємо ім'я гілки worktree
+    const branch = execSyncFn('git rev-parse --abbrev-ref HEAD', {
+      cwd: worktreePath,
+      encoding: 'utf8'
+    }).trim()
+
+    // Додаємо всі зміни і комітимо
+    execSyncFn('git add -A', { cwd: worktreePath, encoding: 'utf8' })
+
+    let hasChanges = false
+    try {
+      execSyncFn('git diff --cached --quiet', { cwd: worktreePath, encoding: 'utf8' })
+    } catch {
+      hasChanges = true
+    }
+
+    if (hasChanges) {
+      execSyncFn('git commit -m "graph: node task completion"', { cwd: worktreePath, encoding: 'utf8' })
+    }
+
+    // Якщо worktree на окремій гілці — мерджимо в main
+    if (branch && branch !== 'HEAD' && branch !== 'main' && branch !== 'master') {
+      execSyncFn(`git merge --no-ff "${branch}" -m "graph: merge node ${branch}"`, {
+        cwd: root,
+        encoding: 'utf8'
+      })
+    }
+  } catch (err) {
+    return { ok: false, error: err.message ?? String(err) }
+  }
+
+  // Видаляємо worktree
+  removeWorktree(worktreePath, root, { execSync: execSyncFn })
+  return { ok: true }
+}
+
+/**
+ * Повертає список активних worktrees з репо.
+ * @param {string} root корінь репо
+ * @param {{
+ *   execSync?: (cmd: string, opts?: object) => string
+ * }} [deps] ін'єкції
+ * @returns {Set<string>} set імен worktrees
+ */
+export function listActiveWorktrees(root, deps = {}) {
+  const execSyncFn = deps.execSync ?? ((cmd, opts) => execSync(cmd, opts))
+
+  try {
+    const out = execSyncFn('git worktree list --porcelain', { cwd: root, encoding: 'utf8' })
+    const names = new Set()
+    for (const line of String(out).split('\n')) {
+      if (line.startsWith('worktree ')) {
+        const path = line.slice('worktree '.length).trim()
+        const name = path.split('/').pop() ?? ''
+        if (name) names.add(name)
+      }
+    }
+    return names
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * Знаходить worktree що належить вузлу (за prefix).
+ * @param {string} nodePath відносний шлях вузла
+ * @param {string} worktreesDir абсолютний шлях до .worktrees/
+ * @param {{
+ *   readdirSync?: (d: string) => string[],
+ *   execSync?: (cmd: string, opts?: object) => string
+ * }} [deps] ін'єкції
+ * @returns {string | null} абсолютний шлях до worktree або null
+ */
+export function findNodeWorktree(nodePath, worktreesDir, deps = {}) {
+  const readdirSyncFn = deps.readdirSync ?? readdirSync
+  const prefix = sanitizeNodeName(nodePath.replace(/\//g, '-'))
+
+  let entries
+  try {
+    entries = readdirSyncFn(worktreesDir)
+  } catch {
+    return null
+  }
+
+  const match = entries.find(name => name.startsWith(prefix + '-') || name === prefix)
+  return match ? join(worktreesDir, match) : null
+}

package/scripts/dispatcher/graph-tasks.mjs

@@ -0,0 +1,92 @@
+/**
+ * `n-cursor graph` — task DAG orchestration system.
+ *
+ * Управляє задачами у `tasks/<node>/` директоріях. Стан вузлів деривується
+ * з файлів (immutable protocol): task.md + plan/run/fact/pending-audit/audit-result/invalidated.
+ *
+ * Підкоманди:
+ *   setup         — ініціалізація проєкту (.n-cursor.json, tasks/, git hook)
+ *   init <name>   — створити task.md шаблон
+ *   plan [<path>] [--mode agent]  — Stage 1: написати plan_NNN.md
+ *   status [<path>] [--json]      — показати стан DAG
+ *   scan [--json]                 — повний скан, exit 1 якщо failed
+ *   run [<path>] [--actor a] [--auto]  — запустити вузол(и)
+ *   kill <path>                   — вбити worktree + каскадна інвалідація + видалити plan_*.md
+ *   invalidate <path> [--no-cascade]   — позначити як invalidated
+ *   done <path>                   — успіх → merge worktree
+ *   audit <path>                  — pending-audit_NNN.md + merge agent worktree
+ *   failed <path>                 — провал → run_NNN.md (failed)
+ *   spawn <path>                  — composite → перевірити дочірні вузли
+ *   watch                         — одноразовий скан: audit queue + stale + needs-plan
+ */
+
+import { cmdSetup } from './graph/lib/cmd-setup.mjs'
+import { cmdInit } from './graph/lib/cmd-init.mjs'
+import { cmdPlan } from './graph/lib/cmd-plan.mjs'
+import { cmdStatus } from './graph/lib/cmd-status.mjs'
+import { cmdScan } from './graph/lib/cmd-scan.mjs'
+import { cmdRun } from './graph/lib/cmd-run.mjs'
+import { cmdKill } from './graph/lib/cmd-kill.mjs'
+import { cmdInvalidate } from './graph/lib/cmd-invalidate.mjs'
+import { cmdDone, cmdAudit, cmdFailed, cmdSpawn } from './graph/lib/cmd-signals.mjs'
+import { cmdWatch } from './graph/lib/cmd-watch.mjs'
+
+const USAGE = [
+  'Usage: n-cursor graph <command> [args]',
+  '',
+  'Commands:',
+  '  setup                          init project: .n-cursor.json, tasks/, git hook',
+  '  init <name>                    create task.md template',
+  '  plan [<path>] [--mode agent]   Stage 1: write plan_NNN.md',
+  '  status [<path>] [--json]       show DAG state',
+  '  scan [--json]                  full scan, exit 1 if failed',
+  '  run [<path>] [--actor a] [--auto]  run node(s)',
+  '  kill <path>                    kill worktree + cascade invalidate + delete plan_*.md',
+  '  invalidate <path> [--no-cascade]   mark invalidated',
+  '  done <path>                    success → merge worktree',
+  '  audit <path>                   pending-audit_NNN.md + merge agent worktree',
+  '  failed <path>                  failure → write run_NNN.md',
+  '  spawn <path>                   composite → validate children registered',
+  '  watch                          one-shot scan: audit queue + stale + needs-plan'
+].join('\n')
+
+/** @type {Record<string, (args: string[], deps: object) => Promise<number>>} */
+const COMMANDS = {
+  setup: cmdSetup,
+  init: cmdInit,
+  plan: cmdPlan,
+  status: cmdStatus,
+  scan: cmdScan,
+  run: cmdRun,
+  kill: cmdKill,
+  invalidate: cmdInvalidate,
+  done: cmdDone,
+  audit: cmdAudit,
+  failed: cmdFailed,
+  spawn: cmdSpawn,
+  watch: cmdWatch
+}
+
+/**
+ * Точка входу `n-cursor graph` та `n-cursor watch`.
+ * Парсить підкоманду і маршрутизує до відповідного handler-а.
+ *
+ * @param {string[]} args аргументи після `graph` (або `watch`)
+ * @param {{
+ *   cwd?: string,
+ *   log?: (m: string) => void,
+ *   [key: string]: unknown
+ * }} [deps] ін'єкції (пробрасуються до підкоманд)
+ * @returns {Promise<number>} exit code
+ */
+export async function runGraphTasksCli(args, deps = {}) {
+  const [sub, ...rest] = args
+
+  if (!sub || !Object.hasOwn(COMMANDS, sub)) {
+    console.error(USAGE)
+    if (sub) console.error(`\nНевідома підкоманда: "${sub}"`)
+    return 1
+  }
+
+  return await COMMANDS[sub](rest, deps)
+}

package/scripts/dispatcher/index.mjs

@@ -8,9 +8,9 @@
  * flow failed  — CWD → node path → `graph failed <path>`
  * flow spawn   — CWD → node path → `graph spawn <path>`
  */
-import { plan } from './lib/flow-plan.mjs'
-import { verify } from './lib/flow-verify.mjs'
-import { audit, done, failed, spawn } from './lib/flow-signals.mjs'
+import { cmdPlan as plan } from './graph/lib/cmd-plan.mjs'
+import { cmdVerify as verify } from './graph/lib/cmd-verify.mjs'
+import { cmdAudit as audit, cmdDone as done, cmdFailed as failed, cmdSpawn as spawn } from './graph/lib/cmd-signals.mjs'
 
 const USAGE = [
   'Usage:',