@goodandready/dsh-cron 0.3.12 → 0.3.14

package/README.md

@@ -90,6 +90,30 @@ graph TD
 
 ## ✨ Features & Capabilities
 
+### 🐝 Swarm Delegation & Parallel Multi-Agent Execution (#350)
+- **Controlled Worker Pool**: Configure `concurrencyLimit` (1..10, default 3) to execute independent subtasks in parallel without overloading system resources.
+- **Fault-Tolerant Decomposition**: Subtask failures are isolated; the swarm aggregates all successful results and flags partial errors gracefully.
+- **Automated Synthesis**: Aggregates worker outputs into a structured Markdown digest or delegates synthesis to a designated synthesizer model.
+- **Swarm Metrics & History**: Run history records total, succeeded, failed counts, and duration alongside detailed per-worker execution logs.
+
+### 🔍 Git Diff & Interactive Patch Review (#351)
+- **Automatic Diff Capture**: Tasks running in Git worktrees capture modified files, stat summary, and unified diffs (up to 256 KiB) automatically.
+- **1-Click Discard**: Revert uncommitted working directory changes safely with a single click (`git reset --hard HEAD && git clean -fd`).
+- **1-Click Apply**: Re-apply previously captured diffs directly to the repository (`git apply --whitespace=fix`).
+- **Interactive Run Preview**: Color-coded diff inspector embedded directly into the execution history drawer.
+
+### 🔀 Decision Nodes & Conditional IF/ELSE Branching (#352)
+- **Conditional Routing**: Tasks can define `branchRules` evaluating execution outcomes (`exitCode`, `output`, `output.json.<path>`, `status`) with operators (`equals`, `notequals`, `contains`, `gt`, `gte`, `lt`, `lte`, `regex`, `exists`).
+- **Fallback Else**: Optional `elseTask` triggers when no branch condition matches.
+- **Deadlock-Free Synchronization**: Untriggered branch tasks are safely recorded with `status: 'skipped'`, unblocking downstream join barriers (`joinPolicy: 'all_success'`).
+- **Graph Visualization**: DAG Graph View displays decision badges (`🔀 Decision`) and condition labels on connecting edges.
+
+### 🩺 Autonomous Self-Healing Doctor (#353)
+- **Failure Classification**: Automatic detection of 8 failure categories: `syntax_error`, `dependency_missing`, `rate_limit`, `auth_failed`, `schema_change`, `timeout`, `network_error`, `runtime_error`.
+- **Unified Diff**: Clean line-by-line diff preview of proposed fixes before application.
+- **1-Click Apply & Revert**: Dedicated `/doctor/apply` and `/doctor/revert` endpoints with full revision backup (up to 10 versions preserved in `task.revisions`).
+- **Guarded Autonomous Auto-Healing**: When `autoHeal: true`, high-confidence fixes are applied automatically with a strict 24-hour rate limit to prevent repair loops.
+
 ### 1. Visual Task Manager & Sidebar Action
 Click the clock icon in the DSH sidebar (positioned next to the new-session button) to open the management panel:
 * **Status Filter Tabs**: toggle between **All**, **Active**, **Paused**, and **Completed** tasks.

package/README.ru.md

@@ -90,6 +90,30 @@ graph TD
 
 ## ✨ Возможности
 
+### 🐝 Роевая декомпозиция задач и мультиагентный запуск (Swarm Delegation) (#350)
+- **Управляемый пул воркеров**: Настройка `concurrencyLimit` (1..10, по умолчанию 3) для параллельного выполнения независимых подзадач без перегрузки системы.
+- **Отказоустойчивая декомпозиция**: Ошибки отдельных воркеров изолированы; рой объединяет успешные результаты и корректно фиксирует частичные сбои.
+- **Автоматический синтез**: Сведение результатов всех воркеров в структурированный Markdown-дайджест или через выделенную модель-синтезатор.
+- **Метрики и история роя**: Сохранение количества успешных/сбойных задач, времени выполнения и детальных логов каждого воркера.
+
+### 🔍 Просмотр Git Diff и интерактивное подтверждение патчей (#351)
+- **Автоматический захват диффов**: Задачи в Git-каталогах автоматически сохраняют список файлов, сводку изменений и унифицированный diff (до 256 КиБ).
+- **1-Click Discard**: Безопасный откат незакоммиченных изменений в один клик (`git reset --hard HEAD && git clean -fd`).
+- **1-Click Apply**: Повторное наложение сохранённого патча на рабочий каталог (`git apply --whitespace=fix`).
+- **Интерактивный просмотр**: Цветовая подсветка строк diff в карточке истории запусков.
+
+### 🔀 Решающие узлы и условные развилки IF/ELSE (#352)
+- **Маршрутизация по условию**: Задачи могут задавать `branchRules` для проверки результата (`exitCode`, `output`, `output.json.<path>`, `status`) через операторы (`equals`, `notequals`, `contains`, `gt`, `gte`, `lt`, `lte`, `regex`, `exists`).
+- **Ветка Else**: Резервная задача `elseTask` запускается, если ни одно из правил не совпало.
+- **Защита от взаимных блокировок**: Невыбранные ветви автоматически регистрируются со статусом `skipped`, предотвращая зависание барьеров синхронизации (`joinPolicy: 'all_success'`).
+- **Визуализация в графе**: DAG Graph View отображает бейджи решающих узлов (`🔀 Decision`) и условия на соединительных линиях.
+
+### 🩺 Автономный Доктор самовосстановления (Self-Healing Doctor) (#353)
+- **Классификация сбоев**: Автоматическое распознавание 8 типов ошибок (`syntax_error`, `dependency_missing`, `rate_limit`, `auth_failed`, `schema_change`, `timeout`, `network_error`, `runtime_error`).
+- **Unified Diff**: Наглядный просмотр диффа предлагаемого исправления до его применения.
+- **1-Click применение и откат**: API эндпоинты `/doctor/apply` и `/doctor/revert` с сохранением до 10 ревизий в `task.revisions`.
+- **Безопасная авто-починка**: При включённом `autoHeal: true` патчи с высокой уверенностью (`high`) применяются автоматически с лимитом не чаще 1 раза в сутки.
+
 ### 1. Визуальный менеджер задач
 Нажмите на иконку-часы в сайдбаре DSH (рядом с кнопкой новой сессии), чтобы открыть панель:
 * **Табы фильтрации**: **Все**, **Активные**, **На паузе**, **Завершённые**.

package/README.zh.md

@@ -90,6 +90,30 @@ graph TD
 
 ## ✨ 功能与能力
 
+### 🐝 群蚁协同委托与多智能体并行执行 (Swarm Delegation) (#350)
+- **受控工作池**：配置并发限制 `concurrencyLimit`（1..10，默认 3），在不耗尽系统资源的前提下并行处理独立子任务。
+- **高容错分解**：单个子任务异常完全隔离，群体自动聚合所有成功输出，并在存在异常时清晰上报。
+- **智能结果汇编**：支持将所有工作节点的执行输出聚合成结构化 Markdown 报告或交由综合模型提炼总结。
+- **群体指标与历史**：运行历史完整记录成功/失败统计、耗时及每个子节点的执行快照与日志。
+
+### 🔍 Git Diff 变更查看与交互式补丁审查 (#351)
+- **自动 Diff 捕获**：在 Git 工作区执行的任务会自动捕获变更文件列表、状态统计及完整 Unified Diff（最高 256 KiB）。
+- **一键丢弃 (Discard)**：一键清空工作区未提交改动，安全重置仓库状态（`git reset --hard HEAD && git clean -fd`）。
+- **一键应用 (Apply)**：将保存的 Diff 补丁直接重新注入并应用到工作区（`git apply --whitespace=fix`）。
+- **交互式审阅面板**：在运行详情抽屉中直接查看带有色彩区分的高亮 Diff 变更对比。
+
+### 🔀 决策节点与条件分支 IF/ELSE (#352)
+- **条件路由**：任务可配置 `branchRules`（评估 `exitCode`、`output`、`output.json.<path>` 等字段），支持 `equals`、`notequals`、`contains`、`gt`、`lt`、`regex` 等操作符。
+- **回退分支**：若无匹配规则，自动执行 `elseTask`。
+- **死锁防护**：未触发的分支自动标记为 `skipped`，确保后续汇聚栅栏（`joinPolicy: 'all_success'`）正常通过。
+- **DAG 可视化**：图谱界面直观展示决策标识（`🔀 Decision`）与连线判断条件。
+
+### 🩺 自愈医生（Self-Healing Doctor）(#353)
+- **故障诊断分类**：自动分类 8 类运行故障（语法错误、缺少依赖、频率限制、认证失效、架构变更、超时、网络错误、运行时异常）。
+- **统一代码差分**：生成直观的标准 Unified Diff 对比。
+- **一键应用与回滚**：提供 `/doctor/apply` 与 `/doctor/revert` 接口，自动保留多达 10 个历史版本（`task.revisions`）。
+- **受控自主修复**：启用 `autoHeal: true` 时，高可信度（`high`）修复自动生效，且强制 24 小时频次限制防止死循环。
+
 ### 1. 可视化任务管理器
 点击 DSH 侧边栏中的时钟图标（位于“新会话”按钮旁）打开管理面板：
 * **状态过滤标签**：**全部**、**活跃**、**已暂停**、**已完成**。

package/lib/api.js

@@ -1,3 +1,5 @@
+import { captureGitDiff, discardGitChanges, applyGitDiff } from './git-diff.js';
+import { applyDoctorFix, revertDoctorFix, diagnoseFailure } from './doctor.js';
 import { handleTaskWebhookRoute } from './api-task-webhook.js';
 import { rollbackPromptVersion, sanitizePromptHistory } from './prompt-evolver.js';
 import { sanitizeAdaptiveConfig } from './adaptive.js';
@@ -81,6 +83,7 @@ export function createCronApiHandler(store, scheduler, collection) {
       const scope = parts[1]; // 'tasks' | 'action' | 'heartbeat-ping'
       const id = parts[2];
       const action = parts[3];
+      const subAction = parts[4];
 
       if (scope === 'telegram' && id === 'webhook') {
         await handleTelegramWebhook({ store, scheduler, req, res });
@@ -131,7 +134,7 @@ export function createCronApiHandler(store, scheduler, collection) {
         return;
       }
 
-      await handleTaskItem({ store, scheduler, req, res, url, id, action, apiToken, ctx });
+      await handleTaskItem({ store, scheduler, req, res, url, id, action, subAction, apiToken, ctx });
     } catch (err) {
       sendJson(res, err.statusCode || 500, { ok: false, error: err.message });
     }
@@ -293,7 +296,7 @@ function buildTaskRecord(store, body, taskType, parsed) {
 
 // ------------------------------------------------------------ single task
 
-async function handleTaskItem({ store, scheduler, req, res, url, id, action, apiToken, ctx }) {
+async function handleTaskItem({ store, scheduler, req, res, url, id, action, subAction, apiToken, ctx }) {
   if (action === 'heartbeat') {
     handleHeartbeatPing({ store, req, res, taskId: id, apiToken, ctx });
     return;
@@ -344,6 +347,43 @@ async function handleTaskItem({ store, scheduler, req, res, url, id, action, api
       sendJson(res, 200, { ok: true, history: store.getHistory(id, limit) });
       return;
     }
+    if (action === 'git-diff') {
+      const task = store.get(id);
+      if (!task) {
+        sendJson(res, 404, NOT_FOUND);
+        return;
+      }
+      const runs = store.getHistory(id, 10);
+      const runId = url.searchParams.get('runId') || subAction;
+      const targetRun = runId ? runs.find((r) => r.id === runId) : runs[0];
+      const diffData = targetRun?.gitDiff || null;
+      sendJson(res, 200, {
+        ok: true,
+        taskId: id,
+        runId: targetRun?.id || null,
+        gitDiff: diffData,
+      });
+      return;
+    }
+    if (action === 'doctor') {
+      const task = store.get(id);
+      if (!task) {
+        sendJson(res, 404, NOT_FOUND);
+        return;
+      }
+      const runs = store.getHistory(id, 5);
+      const latestRun = runs[0] || null;
+      const reportRun = runs.find((r) => r.doctorReport) || latestRun;
+      sendJson(res, 200, {
+        ok: true,
+        taskId: id,
+        doctorReport: reportRun?.doctorReport || null,
+        revisions: task.revisions || [],
+        previousPrompt: task.previousPrompt || null,
+        autoHeal: Boolean(task.autoHeal || task.selfHealing?.autoApply),
+      });
+      return;
+    }
     if (!action) {
       const task = store.get(id);
       if (!task) {
@@ -362,7 +402,7 @@ async function handleTaskItem({ store, scheduler, req, res, url, id, action, api
     }
   }
   if (req.method === 'POST') {
-    const handled = await handleItemPost({ store, scheduler, req, res, url, id, action });
+    const handled = await handleItemPost({ store, scheduler, req, res, url, id, action, subAction });
     if (handled) return;
   }
   if (req.method === 'PATCH') {
@@ -377,7 +417,141 @@ async function handleTaskItem({ store, scheduler, req, res, url, id, action, api
 }
 
 /** Task actions that are plain POSTs. Returns true when one matched. */
-async function handleItemPost({ store, scheduler, req, res, url, id, action }) {
+async function handleItemPost({ store, scheduler, req, res, url, id, action, subAction }) {
+  if (action === 'git-diff' && (subAction === 'discard' || subAction === 'revert')) {
+    const task = store.get(id);
+    if (!task) {
+      sendJson(res, 404, NOT_FOUND);
+      return true;
+    }
+    const targetDir = task.cwd;
+    if (!targetDir) {
+      sendJson(res, 400, { ok: false, error: 'Task does not define a working directory (cwd)' });
+      return true;
+    }
+    const result = await discardGitChanges(targetDir);
+    sendJson(res, result.ok ? 200 : 500, result);
+    return true;
+  }
+
+  if (action === 'git-diff' && subAction === 'apply') {
+    const task = store.get(id);
+    if (!task) {
+      sendJson(res, 404, NOT_FOUND);
+      return true;
+    }
+    const body = await readBody(req, res);
+    const bodyData = (body && body.body) || {};
+    let patch = bodyData.diff || bodyData.patch;
+    if (!patch) {
+      const runs = store.getHistory(id, 5);
+      const targetRun = runs.find((r) => r.gitDiff?.diff);
+      patch = targetRun?.gitDiff?.diff;
+    }
+    if (!patch) {
+      sendJson(res, 400, { ok: false, error: 'No diff patch provided or found in run history' });
+      return true;
+    }
+    const targetDir = task.cwd;
+    if (!targetDir) {
+      sendJson(res, 400, { ok: false, error: 'Task does not define a working directory (cwd)' });
+      return true;
+    }
+    const result = await applyGitDiff(targetDir, patch);
+    sendJson(res, result.ok ? 200 : 500, result);
+    return true;
+  }
+
+  if ((action === 'doctor' && subAction === 'apply') || action === 'doctor-apply') {
+    const task = store.get(id);
+    if (!task) {
+      sendJson(res, 404, NOT_FOUND);
+      return true;
+    }
+    const body = await readBody(req, res);
+    const bodyData = (body && body.body) || {};
+    let fix = bodyData.fix || bodyData.doctorReport;
+    if (!fix) {
+      const runs = store.getHistory(id, 5);
+      const reportRun = runs.find((r) => r.doctorReport);
+      fix = reportRun?.doctorReport;
+    }
+    if (!fix || !fix.suggestedFix) {
+      sendJson(res, 400, { ok: false, error: 'No doctor fix found to apply' });
+      return true;
+    }
+    try {
+      const result = await applyDoctorFix(task, fix, { store, user: bodyData.user || 'operator' });
+      if (!result.ok) {
+        sendJson(res, 400, { ok: false, error: result.error });
+        return true;
+      }
+      sendJson(res, 200, {
+        ok: true,
+        taskId: id,
+        task: redactTaskSecrets(task),
+        revision: result.revision,
+      });
+    } catch (err) {
+      sendJson(res, 500, { ok: false, error: err.message });
+    }
+    return true;
+  }
+
+  if ((action === 'doctor' && subAction === 'revert') || action === 'doctor-revert') {
+    const task = store.get(id);
+    if (!task) {
+      sendJson(res, 404, NOT_FOUND);
+      return true;
+    }
+    const body = await readBody(req, res);
+    const bodyData = (body && body.body) || {};
+    try {
+      const result = await revertDoctorFix(task, { store, user: bodyData.user || 'operator' });
+      if (!result.ok) {
+        sendJson(res, 400, { ok: false, error: result.error });
+        return true;
+      }
+      sendJson(res, 200, {
+        ok: true,
+        taskId: id,
+        task: redactTaskSecrets(task),
+        revertedCode: result.revertedCode,
+      });
+    } catch (err) {
+      sendJson(res, 500, { ok: false, error: err.message });
+    }
+    return true;
+  }
+
+  if ((action === 'doctor' && subAction === 'diagnose') || action === 'doctor-diagnose') {
+    const task = store.get(id);
+    if (!task) {
+      sendJson(res, 404, NOT_FOUND);
+      return true;
+    }
+    const body = await readBody(req, res);
+    const bodyData = (body && body.body) || {};
+    const runId = bodyData.runId;
+    const runs = store.getHistory(id, 10);
+    const targetRun = runId ? runs.find((r) => r.id === runId) : runs[0];
+    if (!targetRun) {
+      sendJson(res, 404, { ok: false, error: 'No run history found to diagnose' });
+      return true;
+    }
+    try {
+      const doctorReport = await diagnoseFailure({
+        task,
+        runInfo: targetRun,
+        ask: scheduler?.askModel,
+      });
+      targetRun.doctorReport = doctorReport;
+      sendJson(res, 200, { ok: true, taskId: id, doctorReport });
+    } catch (err) {
+      sendJson(res, 500, { ok: false, error: err.message });
+    }
+    return true;
+  }
   if (action === 'prompt-rollback') {
     const task = store.get(id);
     if (!task) {
@@ -698,6 +872,7 @@ export async function handleExternalTaskRequest({ store, scheduler, req, res, ur
   }
   const id = parts[3];
   const action = parts[4];
+  const subAction = parts[5];
 
   if (!id) {
     if (req.method === 'GET') {
@@ -716,7 +891,7 @@ export async function handleExternalTaskRequest({ store, scheduler, req, res, ur
   }
 
   if (req.method === 'POST') {
-    const handled = await handleItemPost({ store, scheduler, req, res, url, id, action });
+    const handled = await handleItemPost({ store, scheduler, req, res, url, id, action, subAction });
     if (handled) return;
   }
   if (req.method === 'GET' && !action) {

package/lib/branching.js

@@ -0,0 +1,341 @@
+/**
+ * Decision Nodes and Branching Rules Engine (#352)
+ *
+ * Evaluates conditional IF/ELSE logic on task outcomes in DAG chains.
+ * Inspects exit codes, execution statuses, stdout/stderr, and deep JSON paths.
+ */
+
+/**
+ * Safely resolves a nested field from the execution context.
+ *
+ * Supported paths:
+ * - Direct fields: 'status', 'exitCode', 'output', 'stdout', 'stderr', 'durationMs', 'costUsd'
+ * - JSON paths: 'output.json.severity', 'json.data.status', 'stdout.json.items[0].id'
+ * - Nested objects: 'outcome.status', 'runInfo.error', 'task.type'
+ *
+ * @param {Object} context Execution context containing outcome, runInfo, and/or task
+ * @param {string} path Dot-separated property path
+ * @returns {any} Resolved value or undefined
+ */
+export function resolveField(context, path) {
+  if (!context || !path || typeof path !== 'string') return undefined;
+
+  const trimmedPath = path.trim();
+  if (!trimmedPath) return undefined;
+
+  // Flattened lookup root: blend context, outcome, runInfo
+  const root = {
+    ...(context.outcome || {}),
+    ...(context.runInfo || {}),
+    ...(context.task ? { task: context.task } : {}),
+    ...context,
+  };
+
+  // If path refers to stdout or stderr, fallback to output if not explicitly separated
+  if (trimmedPath === 'stdout' && root.stdout === undefined) {
+    return root.output;
+  }
+  if (trimmedPath === 'stderr' && root.stderr === undefined) {
+    return root.error;
+  }
+
+  // Handle json sub-paths (e.g. output.json.foo, json.bar, stdout.json.baz)
+  if (trimmedPath.startsWith('output.json.') || trimmedPath.startsWith('stdout.json.') || trimmedPath.startsWith('json.')) {
+    let rawText = '';
+    let jsonSubPath = '';
+
+    if (trimmedPath.startsWith('output.json.')) {
+      rawText = root.output ?? root.stdout ?? '';
+      jsonSubPath = trimmedPath.slice('output.json.'.length);
+    } else if (trimmedPath.startsWith('stdout.json.')) {
+      rawText = root.stdout ?? root.output ?? '';
+      jsonSubPath = trimmedPath.slice('stdout.json.'.length);
+    } else {
+      rawText = root.output ?? root.stdout ?? '';
+      jsonSubPath = trimmedPath.slice('json.'.length);
+    }
+
+    let parsed = null;
+    if (typeof rawText === 'object' && rawText !== null) {
+      parsed = rawText;
+    } else if (typeof rawText === 'string') {
+      try {
+        parsed = JSON.parse(rawText.trim());
+      } catch {
+        // Attempt to extract JSON from markdown fences if present
+        const jsonMatch = rawText.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+        if (jsonMatch) {
+          try {
+            parsed = JSON.parse(jsonMatch[1].trim());
+          } catch {
+            return undefined;
+          }
+        } else {
+          return undefined;
+        }
+      }
+    }
+
+    if (!parsed || typeof parsed !== 'object') return undefined;
+    return getNestedValue(parsed, jsonSubPath);
+  }
+
+  return getNestedValue(root, trimmedPath);
+}
+
+/**
+ * Traverses an object using a dot-path, supporting simple array indexing like `items[0].id` or `items.0.id`.
+ *
+ * @param {Object} obj Root object
+ * @param {string} path Dot path
+ * @returns {any}
+ */
+export function getNestedValue(obj, path) {
+  if (obj === null || obj === undefined || !path) return undefined;
+
+  // Normalize array notation `foo[0].bar` -> `foo.0.bar`
+  const normalizedPath = path.replace(/\[(\w+)\]/g, '.$1');
+  const parts = normalizedPath.split('.').filter(Boolean);
+
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * Evaluates a binary condition against an extracted value.
+ *
+ * Supported operators:
+ * - 'equals', '==', 'eq'
+ * - 'notEquals', '!=', 'neq'
+ * - 'contains'
+ * - 'notContains'
+ * - 'greaterThan', '>', 'gt'
+ * - 'greaterThanOrEqual', '>=', 'gte'
+ * - 'lessThan', '<', 'lt'
+ * - 'lessThanOrEqual', '<=', 'lte'
+ * - 'regex', 'matches'
+ * - 'exists'
+ * - 'notExists'
+ *
+ * @param {any} actual
+ * @param {string} operator
+ * @param {any} expected
+ * @returns {boolean}
+ */
+export function evaluateCondition(actual, operator, expected) {
+  const op = String(operator || 'equals').trim().toLowerCase();
+
+  if (op === 'exists') {
+    return actual !== undefined && actual !== null && actual !== '';
+  }
+
+  if (op === 'notexists' || op === 'not_exists') {
+    return actual === undefined || actual === null || actual === '';
+  }
+
+  if (actual === undefined || actual === null) {
+    if (op === 'notequals' || op === '!=' || op === 'neq') {
+      return expected !== undefined && expected !== null;
+    }
+    return false;
+  }
+
+  // Helper: check if value looks like a pure number
+  const isNumeric = (val) => typeof val === 'number' || (typeof val === 'string' && val.trim() !== '' && !Number.isNaN(Number(val)));
+
+  switch (op) {
+    case 'equals':
+    case '==':
+    case 'eq': {
+      if (isNumeric(actual) && isNumeric(expected)) {
+        return Number(actual) === Number(expected);
+      }
+      if (typeof actual === 'boolean' || typeof expected === 'boolean') {
+        return Boolean(actual) === (expected === true || String(expected).toLowerCase() === 'true');
+      }
+      return String(actual).trim().toLowerCase() === String(expected ?? '').trim().toLowerCase();
+    }
+
+    case 'notequals':
+    case '!=':
+    case 'neq': {
+      return !evaluateCondition(actual, 'equals', expected);
+    }
+
+    case 'contains': {
+      if (Array.isArray(actual)) {
+        return actual.some((item) => String(item).toLowerCase().includes(String(expected ?? '').toLowerCase()));
+      }
+      return String(actual).toLowerCase().includes(String(expected ?? '').toLowerCase());
+    }
+
+    case 'notcontains':
+    case 'not_contains': {
+      return !evaluateCondition(actual, 'contains', expected);
+    }
+
+    case 'greaterthan':
+    case '>':
+    case 'gt': {
+      const a = Number(actual);
+      const b = Number(expected);
+      return !Number.isNaN(a) && !Number.isNaN(b) && a > b;
+    }
+
+    case 'greaterthanorequal':
+    case '>=':
+    case 'gte': {
+      const a = Number(actual);
+      const b = Number(expected);
+      return !Number.isNaN(a) && !Number.isNaN(b) && a >= b;
+    }
+
+    case 'lessthan':
+    case '<':
+    case 'lt': {
+      const a = Number(actual);
+      const b = Number(expected);
+      return !Number.isNaN(a) && !Number.isNaN(b) && a < b;
+    }
+
+    case 'lessthanorequal':
+    case '<=':
+    case 'lte': {
+      const a = Number(actual);
+      const b = Number(expected);
+      return !Number.isNaN(a) && !Number.isNaN(b) && a <= b;
+    }
+
+    case 'regex':
+    case 'matches': {
+      try {
+        const re = new RegExp(String(expected ?? ''), 'i');
+        return re.test(String(actual));
+      } catch {
+        return false;
+      }
+    }
+
+    default:
+      return false;
+  }
+}
+
+/**
+ * Sanitizes and validates branch rule configurations.
+ *
+ * @param {Array<Object>|any} rules
+ * @returns {Array<{ field: string, operator: string, value: any, targetTask: string, label?: string }>}
+ */
+export function sanitizeBranchRules(rules) {
+  if (!Array.isArray(rules)) return [];
+
+  const sanitized = [];
+  for (const r of rules) {
+    if (!r || typeof r !== 'object') continue;
+
+    const targetTask = String(r.targetTask || '').trim();
+    const field = String(r.field || '').trim();
+    const operator = String(r.operator || 'equals').trim().toLowerCase();
+
+    if (!targetTask || !field) continue;
+
+    sanitized.push({
+      field,
+      operator,
+      value: r.value !== undefined ? r.value : '',
+      targetTask,
+      label: r.label ? String(r.label).trim() : `[if: ${field} ${operator} ${r.value ?? ''}]`.trim(),
+    });
+  }
+
+  return sanitized;
+}
+
+/**
+ * Evaluates an ordered list of branch rules against the execution context.
+ * Returns the first matching target task, or the fallback elseTask if none match.
+ *
+ * @param {Array<Object>} rules Array of branch rule objects
+ * @param {string|null} [elseTask] Fallback target task ID
+ * @param {Object} context Execution context (outcome, runInfo, task)
+ * @returns {{ matched: boolean, targetTask: string|null, rule?: Object, isElse?: boolean, matchedIndex?: number }}
+ */
+export function evaluateBranchRules(rules, elseTask, context) {
+  const cleanRules = sanitizeBranchRules(rules);
+
+  for (let i = 0; i < cleanRules.length; i++) {
+    const rule = cleanRules[i];
+    const actual = resolveField(context, rule.field);
+    const matched = evaluateCondition(actual, rule.operator, rule.value);
+
+    if (matched) {
+      return {
+        matched: true,
+        targetTask: rule.targetTask,
+        rule,
+        matchedIndex: i,
+        actualValue: actual,
+      };
+    }
+  }
+
+  const cleanElse = elseTask ? String(elseTask).trim() : null;
+  if (cleanElse) {
+    return {
+      matched: false,
+      targetTask: cleanElse,
+      isElse: true,
+    };
+  }
+
+  return {
+    matched: false,
+    targetTask: null,
+  };
+}
+
+/**
+ * Evaluates branch rules on task completion and determines next targets for the scheduler.
+ * Returns null if no branch rules or elseTask are configured (allowing standard onSuccess/onFailure).
+ *
+ * @param {Object} task Current task definition
+ * @param {Object} outcome Task execution outcome
+ * @param {Object} runInfo History run record
+ * @returns {{ targets: string[], decision: Object } | null}
+ */
+export function resolveBranchTargets(task, outcome, runInfo) {
+  if (!task) return null;
+
+  const rules = sanitizeBranchRules(task.branchRules);
+  const elseTask = task.elseTask ? String(task.elseTask).trim() : null;
+
+  if (rules.length === 0 && !elseTask) {
+    return null;
+  }
+
+  const context = {
+    outcome: outcome || {},
+    runInfo: runInfo || {},
+    task,
+    status: outcome?.status || runInfo?.status,
+    exitCode: outcome?.exitCode ?? runInfo?.exitCode,
+    output: outcome?.output ?? runInfo?.output,
+    error: outcome?.error ?? runInfo?.error,
+    stdout: outcome?.stdout ?? runInfo?.stdout,
+    stderr: outcome?.stderr ?? runInfo?.stderr,
+  };
+
+  const decision = evaluateBranchRules(rules, elseTask, context);
+  const targets = decision.targetTask ? [decision.targetTask] : [];
+
+  return {
+    targets,
+    decision,
+  };
+}
+