ultra-builder-pro-cli 0.5.0

package/mcp-server/tests/telemetry.test.cjs

@@ -0,0 +1,205 @@
+'use strict';
+
+// Phase 6.2 — Telemetry collectors:
+//   • appendTelemetry writes to state.db.telemetry AND .ultra/telemetry/
+//     {YYYY-MM-DD}.jsonl (double-write; jsonl keeps full payload the table
+//     can't hold).
+//   • computeCost(runtime, model, ti, to) returns USD from 2026-04 pricing.
+//   • aggregateTelemetryByRuntime / byTask / bySession drive /ultra-status.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { initStateDb, closeStateDb } = require('../lib/state-db.cjs');
+const ops = require('../lib/state-ops.cjs');
+const telemetry = require('../lib/telemetry.cjs');
+const pricing = require('../lib/pricing.cjs');
+
+function freshFixture() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-tele-'));
+  const file = path.join(dir, '.ultra', 'state.db');
+  const init = initStateDb(file);
+  return { dir, db: init.db };
+}
+
+function teardown(dir, db) {
+  try { closeStateDb(db); } catch (_) { /* ignore */ }
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+}
+
+function seedSession(db, { sid = 's-1', task_id = 't-1', runtime = 'claude' } = {}) {
+  ops.createTask(db, { id: task_id, title: 'tele target', type: 'feature', priority: 'P1' });
+  ops.createSession(db, {
+    sid, task_id, runtime, pid: null,
+    worktree_path: `/tmp/${sid}/wt`,
+    artifact_dir: `/tmp/${sid}/art`,
+  });
+  return { sid, task_id, runtime };
+}
+
+// ─── pricing ──────────────────────────────────────────────────────────────
+
+test('computeCost: claude opus produces non-zero USD for realistic tokens', () => {
+  const cost = pricing.computeCost('claude', 'claude-opus-4-7', 1000, 500);
+  assert.ok(cost > 0 && cost < 1, `expected reasonable cost, got ${cost}`);
+});
+
+test('computeCost: unknown runtime → null', () => {
+  assert.equal(pricing.computeCost('madeup', 'model-x', 100, 100), null);
+});
+
+test('computeCost: zero tokens → zero', () => {
+  assert.equal(pricing.computeCost('claude', 'claude-sonnet-4-6', 0, 0), 0);
+});
+
+// ─── appendTelemetry ─────────────────────────────────────────────────────
+
+test('appendTelemetry writes to telemetry table', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedSession(db, { sid: 's-t1' });
+    const out = telemetry.appendTelemetry(db, {
+      event_type: 'tool_call',
+      tool_name: 'task.list',
+      session_id: 's-t1',
+      rootDir: dir,
+    });
+    assert.ok(out.id > 0);
+    const row = db.prepare('SELECT * FROM telemetry WHERE id = ?').get(out.id);
+    assert.equal(row.event_type, 'tool_call');
+    assert.equal(row.tool_name, 'task.list');
+    assert.equal(row.session_id, 's-t1');
+  } finally { teardown(dir, db); }
+});
+
+test('appendTelemetry writes a jsonl line under .ultra/telemetry/YYYY-MM-DD.jsonl', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedSession(db, { sid: 's-t2' });
+    telemetry.appendTelemetry(db, {
+      event_type: 'tool_call',
+      tool_name: 'task.create',
+      session_id: 's-t2',
+      rootDir: dir,
+      payload: { duration_ms: 42 },
+    });
+    const today = new Date().toISOString().slice(0, 10);
+    const jsonl = path.join(dir, '.ultra', 'telemetry', `${today}.jsonl`);
+    assert.ok(fs.existsSync(jsonl), `expected jsonl at ${jsonl}`);
+    const lines = fs.readFileSync(jsonl, 'utf8').trim().split('\n');
+    assert.equal(lines.length, 1);
+    const parsed = JSON.parse(lines[0]);
+    assert.equal(parsed.tool_name, 'task.create');
+    assert.equal(parsed.payload.duration_ms, 42);
+  } finally { teardown(dir, db); }
+});
+
+test('appendTelemetry auto-computes cost_usd when runtime + tokens supplied', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedSession(db, { sid: 's-t3' });
+    const out = telemetry.appendTelemetry(db, {
+      event_type: 'token_usage',
+      tool_name: 'session.close',
+      session_id: 's-t3',
+      runtime: 'claude',
+      tokens_input: 2000,
+      tokens_output: 500,
+      rootDir: dir,
+      payload: { model: 'claude-sonnet-4-6' },
+    });
+    const row = db.prepare('SELECT cost_usd FROM telemetry WHERE id = ?').get(out.id);
+    assert.ok(row.cost_usd > 0, 'cost should be computed from tokens');
+  } finally { teardown(dir, db); }
+});
+
+test('appendTelemetry tolerates null session_id (pre-session CLI calls)', () => {
+  const { dir, db } = freshFixture();
+  try {
+    const out = telemetry.appendTelemetry(db, {
+      event_type: 'tool_call',
+      tool_name: 'cli.task.list',
+      session_id: null,
+      rootDir: dir,
+    });
+    const row = db.prepare('SELECT * FROM telemetry WHERE id = ?').get(out.id);
+    assert.equal(row.session_id, null);
+  } finally { teardown(dir, db); }
+});
+
+test('appendTelemetry event_type constraint: invalid value rejected', () => {
+  const { dir, db } = freshFixture();
+  try {
+    assert.throws(
+      () => telemetry.appendTelemetry(db, { event_type: 'bogus', rootDir: dir }),
+      /CHECK|constraint|event_type/,
+    );
+  } finally { teardown(dir, db); }
+});
+
+// ─── aggregation ─────────────────────────────────────────────────────────
+
+test('aggregateTelemetryByRuntime: groups calls + sums tokens/cost', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedSession(db, { sid: 's-a1', task_id: 't-a1', runtime: 'claude' });
+    seedSession(db, { sid: 's-a2', task_id: 't-a2', runtime: 'codex' });
+    telemetry.appendTelemetry(db, { event_type: 'token_usage', tool_name: 'x', session_id: 's-a1', runtime: 'claude', tokens_input: 1000, tokens_output: 200, rootDir: dir, payload: { model: 'claude-sonnet-4-6' } });
+    telemetry.appendTelemetry(db, { event_type: 'token_usage', tool_name: 'y', session_id: 's-a1', runtime: 'claude', tokens_input: 500, tokens_output: 100, rootDir: dir, payload: { model: 'claude-sonnet-4-6' } });
+    telemetry.appendTelemetry(db, { event_type: 'token_usage', tool_name: 'z', session_id: 's-a2', runtime: 'codex', tokens_input: 800, tokens_output: 300, rootDir: dir, payload: { model: 'gpt-5.4' } });
+
+    const summary = ops.aggregateTelemetryByRuntime(db);
+    const byRuntime = Object.fromEntries(summary.map((r) => [r.runtime, r]));
+    assert.equal(byRuntime.claude.calls, 2);
+    assert.equal(byRuntime.codex.calls, 1);
+    assert.equal(byRuntime.claude.tokens_in, 1500);
+    assert.equal(byRuntime.codex.tokens_in, 800);
+    assert.ok(byRuntime.claude.cost_usd > 0);
+  } finally { teardown(dir, db); }
+});
+
+test('aggregateTelemetryByTask: top N tasks by cost', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedSession(db, { sid: 's-b1', task_id: 't-cheap', runtime: 'claude' });
+    seedSession(db, { sid: 's-b2', task_id: 't-expensive', runtime: 'claude' });
+    telemetry.appendTelemetry(db, { event_type: 'token_usage', tool_name: 'x', session_id: 's-b1', runtime: 'claude', tokens_input: 100, tokens_output: 50, rootDir: dir, payload: { model: 'claude-sonnet-4-6' } });
+    telemetry.appendTelemetry(db, { event_type: 'token_usage', tool_name: 'y', session_id: 's-b2', runtime: 'claude', tokens_input: 10000, tokens_output: 5000, rootDir: dir, payload: { model: 'claude-opus-4-7' } });
+
+    const top = ops.aggregateTelemetryByTask(db, { limit: 1 });
+    assert.equal(top.length, 1);
+    assert.equal(top[0].task_id, 't-expensive');
+    assert.ok(top[0].cost_usd > 0);
+  } finally { teardown(dir, db); }
+});
+
+test('aggregateTelemetryBySession: per-session roll-up', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedSession(db, { sid: 's-c1', task_id: 't-c1', runtime: 'claude' });
+    telemetry.appendTelemetry(db, { event_type: 'tool_call', tool_name: 'task.list', session_id: 's-c1', rootDir: dir });
+    telemetry.appendTelemetry(db, { event_type: 'tool_call', tool_name: 'task.get', session_id: 's-c1', rootDir: dir });
+    telemetry.appendTelemetry(db, { event_type: 'token_usage', tool_name: 'session.close', session_id: 's-c1', runtime: 'claude', tokens_input: 500, tokens_output: 100, rootDir: dir, payload: { model: 'claude-haiku-4-5' } });
+
+    const summary = ops.aggregateTelemetryBySession(db, 's-c1');
+    assert.equal(summary.tool_calls, 3);
+    assert.equal(summary.tokens_in, 500);
+    assert.equal(summary.tokens_out, 100);
+    assert.ok(summary.cost_usd > 0);
+  } finally { teardown(dir, db); }
+});
+
+test('aggregate filter: since cutoff excludes older rows', () => {
+  const { dir, db } = freshFixture();
+  try {
+    seedSession(db, { sid: 's-d1', task_id: 't-d1', runtime: 'claude' });
+    // Insert one row; then a cutoff in the future filters it out.
+    telemetry.appendTelemetry(db, { event_type: 'tool_call', tool_name: 'x', session_id: 's-d1', rootDir: dir });
+    const futureCutoff = new Date(Date.now() + 60 * 1000).toISOString();
+    const summary = ops.aggregateTelemetryByRuntime(db, { since: futureCutoff });
+    assert.equal(summary.length, 0);
+  } finally { teardown(dir, db); }
+});

package/orchestrator/auto-merge.cjs

@@ -0,0 +1,109 @@
+'use strict';
+
+// Phase 8B.4 — Auto-merge session worktree back onto baseBranch.
+//
+// Called by session-runner.closeSession when autoMerge=true. Three outcomes:
+//   1. session HEAD === base HEAD            → { merged:false, reason:'no_changes' }
+//   2. git merge --no-ff clean                → { merged:true }  + merged_back event
+//   3. conflict                               → { merged:false, reason:'conflict',
+//                                                conflict_paths[] } + merge_conflict event
+//      (caller keeps the worktree so a human can resolve)
+//
+// Note: git worktree add --detach shares the .git dir, so the session commit
+// is already reachable from the repo root. No fetch / push is needed.
+
+const { execFileSync } = require('node:child_process');
+
+const ops = require('../mcp-server/lib/state-ops.cjs');
+
+function runGit(args, opts = {}) {
+  return execFileSync('git', args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    ...opts,
+  }).trim();
+}
+
+function listConflictPaths(repoRoot) {
+  try {
+    const out = execFileSync('git', ['diff', '--name-only', '--diff-filter=U'], {
+      cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+    });
+    return out.split('\n').filter(Boolean);
+  } catch (err) {
+    process.stderr.write(`auto-merge: listConflictPaths failed: ${err.message}\n`);
+    return [];
+  }
+}
+
+function autoMerge({ repoRoot, worktreePath, baseBranch = 'main', sid, task_id = null, db = null }) {
+  if (!repoRoot) throw new Error('autoMerge: repoRoot required');
+  if (!worktreePath) throw new Error('autoMerge: worktreePath required');
+
+  let sessionSha;
+  let baseSha;
+  try {
+    sessionSha = runGit(['rev-parse', 'HEAD'], { cwd: worktreePath });
+    baseSha = runGit(['rev-parse', baseBranch], { cwd: repoRoot });
+  } catch (err) {
+    // Base branch missing or worktree malformed — surface but don't throw.
+    process.stderr.write(`auto-merge: rev-parse failed: ${err.message}\n`);
+    return { merged: false, reason: 'rev_parse_failed', session_sha: null, base_sha: null };
+  }
+
+  if (sessionSha === baseSha) {
+    return { merged: false, reason: 'no_changes', session_sha: sessionSha, base_sha: baseSha };
+  }
+
+  // Make sure repoRoot is checked out on baseBranch before we merge into it.
+  try { runGit(['checkout', baseBranch], { cwd: repoRoot }); }
+  catch (err) {
+    process.stderr.write(`auto-merge: checkout ${baseBranch} failed: ${err.message}\n`);
+    return { merged: false, reason: 'checkout_failed', session_sha: sessionSha, base_sha: baseSha };
+  }
+
+  try {
+    runGit(
+      ['merge', '--no-ff', '-m', `ubp: merge session ${sid}`, sessionSha],
+      { cwd: repoRoot },
+    );
+    if (db) {
+      ops.appendEvent(db, {
+        type: 'merged_back',
+        task_id,
+        session_id: sid,
+        payload: { session_sha: sessionSha, base_sha: baseSha, base_branch: baseBranch },
+      });
+    }
+    return { merged: true, session_sha: sessionSha, base_sha: baseSha };
+  } catch (err) {
+    // Collect conflict info BEFORE aborting — abort resets the index.
+    const conflictPaths = listConflictPaths(repoRoot);
+    try { runGit(['merge', '--abort'], { cwd: repoRoot }); }
+    catch (abortErr) {
+      process.stderr.write(`auto-merge: merge --abort failed: ${abortErr.message}\n`);
+    }
+    if (db) {
+      ops.appendEvent(db, {
+        type: 'merge_conflict',
+        task_id,
+        session_id: sid,
+        payload: {
+          session_sha: sessionSha,
+          base_sha: baseSha,
+          base_branch: baseBranch,
+          conflict_paths: conflictPaths,
+        },
+      });
+    }
+    return {
+      merged: false,
+      reason: 'conflict',
+      session_sha: sessionSha,
+      base_sha: baseSha,
+      conflict_paths: conflictPaths,
+    };
+  }
+}
+
+module.exports = { autoMerge };

package/orchestrator/code-graph-watcher.cjs

@@ -0,0 +1,121 @@
+'use strict';
+
+// Phase 6.4 — code-review-graph live watcher.
+//
+// fs-watch the project's source tree, debounce bursts of editor saves, and
+// hand batches off to an onBatch callback. Callers wire the callback to
+// whatever keeps the graph fresh (e.g. the external code-review-graph MCP
+// server's build_or_update_graph_tool). Keeping the glue in callers means
+// this module has no MCP-client dependency and is trivial to unit-test.
+//
+// PLAN D24: real-time feedback beats startup rebuilds; agents learn about
+// impact radius immediately after save, not after the next phase boot.
+
+const chokidar = require('chokidar');
+
+const DEFAULT_INCLUDE_EXT = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+  '.py', '.go', '.rs', '.java', '.rb', '.php',
+  '.c', '.cc', '.cpp', '.h', '.hpp',
+  '.swift', '.kt', '.scala',
+]);
+
+const DEFAULT_EXCLUDE_GLOBS = Object.freeze([
+  '**/node_modules/**',
+  '**/.git/**',
+  '**/.ultra/**',
+  '**/.code-review-graph/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/coverage/**',
+  '**/.next/**',
+]);
+
+function hasCodeExt(p, includeExt) {
+  const idx = p.lastIndexOf('.');
+  if (idx < 0) return false;
+  return includeExt.has(p.slice(idx).toLowerCase());
+}
+
+function startWatcher({
+  repoRoot,
+  debounceMs = 500,
+  includeExt = DEFAULT_INCLUDE_EXT,
+  excludeGlobs = DEFAULT_EXCLUDE_GLOBS,
+  largeBatchThreshold = 50,
+  onBatch,
+} = {}) {
+  if (!repoRoot) throw new Error('startWatcher: repoRoot required');
+  if (typeof onBatch !== 'function') throw new Error('startWatcher: onBatch required');
+
+  let stopped = false;
+  let ready = false;
+  let timer = null;
+  // kind → latest kind; path → {kind, ts} so rapid edit+add collapses cleanly.
+  const pending = new Map();
+
+  const w = chokidar.watch(repoRoot, {
+    ignored: excludeGlobs,
+    ignoreInitial: true,
+    persistent: true,
+    awaitWriteFinish: { stabilityThreshold: 20, pollInterval: 10 },
+  });
+
+  const readyPromise = new Promise((resolve) => {
+    w.once('ready', () => { ready = true; resolve(); });
+  });
+
+  function record(kind, p) {
+    // Drop events fired during chokidar's initial scan — ignoreInitial=true
+    // mostly handles this but awaitWriteFinish can still surface add events
+    // from files that existed when the watcher started.
+    if (stopped || !ready) return;
+    if (!hasCodeExt(p, includeExt)) return;
+    pending.set(p, { kind, ts: Date.now() });
+    schedule();
+  }
+
+  function schedule() {
+    if (timer) return;
+    timer = setTimeout(flush, debounceMs);
+  }
+
+  function flush() {
+    timer = null;
+    if (pending.size === 0) return;
+    const changes = Array.from(pending.entries()).map(([p, meta]) => ({ path: p, kind: meta.kind, ts: meta.ts }));
+    pending.clear();
+    const batch = {
+      changes,
+      large_batch: changes.length >= largeBatchThreshold,
+      ts: new Date().toISOString(),
+    };
+    try { onBatch(batch); }
+    catch (err) { process.stderr.write(`code-graph-watcher onBatch error: ${err.message}\n`); }
+  }
+
+  w.on('add', (p) => record('add', p));
+  w.on('change', (p) => record('change', p));
+  w.on('unlink', (p) => record('unlink', p));
+  w.on('error', (err) => process.stderr.write(`watcher error: ${err.message}\n`));
+
+  return {
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      timer = null;
+      w.close().catch(() => { /* ignore close errors */ });
+    },
+    ready() { return readyPromise; },
+    get running() { return !stopped; },
+    get pendingCount() { return pending.size; },
+    flushNow: flush,
+  };
+}
+
+module.exports = {
+  startWatcher,
+  DEFAULT_INCLUDE_EXT,
+  DEFAULT_EXCLUDE_GLOBS,
+};

package/orchestrator/daemon.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+// Phase 5.4 — Orchestrator daemon.
+//
+// Polls state.db for pending tasks, runs admission + routing, and spawns
+// session-runner children. This is *not* Phase 8B dispatch rules — just the
+// simplest "pick a runtime, spawn one session per pending task" loop. The
+// daemon never picks a task while admission says blocked_by_breaker; the
+// circuit breaker (5.2) is the only gate above routing.
+//
+// opt-in lives in bin/orchestrator.js which reads settings.json before
+// calling runDaemon — the runtime layer itself has no opt-in concept.
+
+const ops = require('../mcp-server/lib/state-ops.cjs');
+const runner = require('./session-runner.cjs');
+const { evaluate, DEFAULT_RULES, ROUTE_PREFERENCES } = require('./dispatch-rules.cjs');
+
+// Phase 8B.1 — routeTask is now a thin wrapper over evaluate() so Phase 5.4
+// callers see identical behavior while the parallel orchestrator (8B.2) can
+// feed richer ctx (wave, deps_ready) to the same rule engine.
+function routeTask(task, availableRuntimes) {
+  const d = evaluate({
+    task: task || {},
+    deps_ready: true,
+    available_runtimes: Array.isArray(availableRuntimes) ? availableRuntimes : [],
+    breaker_state: 'ok',
+    wave: null,
+  }, DEFAULT_RULES);
+  return d.action === 'spawn_agent' ? d.runtime : null;
+}
+
+function runDaemon({
+  db,
+  repoRoot,
+  runtimes,
+  pollMs = 1000,
+  command = null,
+  commandArgs = [],
+  onError = null,
+  branchScoped = false,
+} = {}) {
+  if (!db) throw new Error('runDaemon: db required');
+  if (!repoRoot) throw new Error('runDaemon: repoRoot required');
+  if (!Array.isArray(runtimes) || runtimes.length === 0) {
+    throw new Error('runDaemon: runtimes array required');
+  }
+
+  let stopped = false;
+  const children = [];
+
+  function tick() {
+    if (stopped) return;
+    let pending;
+    try {
+      const filter = { status: 'pending' };
+      if (branchScoped) {
+        const tag = ops.deriveBranchTag(repoRoot);
+        if (tag) filter.tag = tag;
+      }
+      pending = ops.listTasks(db, filter);
+    } catch (err) {
+      if (onError) onError(err); else throw err;
+      return;
+    }
+    for (const task of pending) {
+      if (stopped) return;
+      // admissionCheck catches both live-session conflicts and tripped breakers.
+      let verdict;
+      try { verdict = ops.admissionCheck(db, task.id); }
+      catch (err) { if (onError) onError(err); continue; }
+      if (!verdict.can_spawn) continue;
+
+      const runtime = routeTask(task, runtimes);
+      if (!runtime) continue;
+
+      try {
+        const handle = runner.spawnSession({
+          db, repoRoot,
+          task_id: task.id,
+          runtime,
+          command,
+          args: commandArgs,
+        });
+        children.push(handle);
+      } catch (err) {
+        if (onError) onError(err);
+        // Don't throw — one bad task shouldn't stop the loop.
+      }
+    }
+  }
+
+  const timer = setInterval(tick, pollMs);
+  if (typeof timer.unref === 'function') timer.unref();
+  // Fire one tick immediately so tests don't need to wait pollMs.
+  setImmediate(tick);
+
+  return {
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+    },
+    get running() { return !stopped; },
+    get children() { return children.slice(); },
+  };
+}
+
+module.exports = {
+  runDaemon,
+  routeTask,
+  ROUTE_PREFERENCES,
+};

package/orchestrator/dispatch-rules.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+// Phase 8B.1 — Declarative dispatch rules (GSD-2 pattern).
+//
+// evaluate(ctx, rules) walks a priority-sorted rule array and returns the
+// first matching { rule_id, action, runtime }. Actions:
+//   • spawn_agent — orchestrator should spawn a session with `runtime`
+//   • defer       — leave task pending, revisit next tick (deps/wave wait)
+//   • block       — terminal: don't spawn (breaker, no runtimes, etc.)
+//
+// Phase 5.4 ROUTE_PREFERENCES lives here now. daemon.cjs's `routeTask` is a
+// thin wrapper around evaluate() so Phase 5.4 tests stay green while the
+// parallel orchestrator (8B.2) gets a richer decision surface: wave state,
+// deps readiness, and custom rule injection.
+
+const ROUTE_PREFERENCES = Object.freeze({
+  haiku:  ['opencode', 'gemini', 'claude', 'codex'],
+  sonnet: ['claude', 'codex', 'opencode', 'gemini'],
+  opus:   ['claude', 'codex'],
+});
+
+function resolveByPreference(ctx) {
+  const hint = ctx.task && ctx.task.complexity_hint;
+  const pref = hint ? ROUTE_PREFERENCES[hint] : null;
+  if (pref) {
+    for (const r of pref) if (ctx.available_runtimes.includes(r)) return r;
+  }
+  return ctx.available_runtimes[0];
+}
+
+const DEFAULT_RULES = Object.freeze([
+  {
+    id: 'breaker-blocked',
+    priority: 100,
+    when: (ctx) => ctx.breaker_state === 'tripped',
+    action: 'block',
+  },
+  {
+    id: 'deps-not-ready',
+    priority: 90,
+    when: (ctx) => ctx.deps_ready === false,
+    action: 'defer',
+  },
+  {
+    id: 'no-runtimes',
+    priority: 80,
+    when: (ctx) => !Array.isArray(ctx.available_runtimes) || ctx.available_runtimes.length === 0,
+    action: 'block',
+  },
+  {
+    id: 'wave-conflict',
+    priority: 70,
+    when: (ctx) => !!(ctx.wave && ctx.wave.parallel === false && (ctx.wave.running_count || 0) > 0),
+    action: 'defer',
+  },
+  {
+    id: 'by-preference',
+    priority: 10,
+    when: (ctx) => {
+      const hint = ctx.task && ctx.task.complexity_hint;
+      return !!(hint && ROUTE_PREFERENCES[hint]);
+    },
+    action: 'spawn_agent',
+    resolve: resolveByPreference,
+  },
+  {
+    id: 'fallback-first-available',
+    priority: 0,
+    when: () => true,
+    action: 'spawn_agent',
+    resolve: (ctx) => ctx.available_runtimes[0],
+  },
+]);
+
+function evaluate(ctx, rules = DEFAULT_RULES) {
+  const sorted = [...rules].sort((a, b) => (b.priority || 0) - (a.priority || 0));
+  for (const rule of sorted) {
+    if (rule.when(ctx)) {
+      let runtime = null;
+      if (rule.action === 'spawn_agent') {
+        runtime = rule.resolve ? rule.resolve(ctx) : (rule.runtime || null);
+      }
+      return { rule_id: rule.id, action: rule.action, runtime };
+    }
+  }
+  return { rule_id: null, action: 'block', runtime: null };
+}
+
+module.exports = {
+  evaluate,
+  DEFAULT_RULES,
+  ROUTE_PREFERENCES,
+};