@newsails/veil-cli 1.0.1

package/infrastructure/database.js

@@ -0,0 +1,563 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const paths = require('../utils/paths');
+const { generateId } = require('../utils/id');
+const { getContextLimit } = require('../utils/models');
+
+let _db = null;
+const CURRENT_SCHEMA_VERSION = 1;
+
+/**
+ * Open (or return cached) the SQLite database.
+ * Runs migrations on every call (idempotent IF NOT EXISTS).
+ * @returns {import('better-sqlite3').Database}
+ */
+function getDb() {
+  if (_db) return _db;
+
+  const dbPath = paths.getDbPath();
+  const dbDir = path.dirname(dbPath);
+  if (!fs.existsSync(dbDir)) fs.mkdirSync(dbDir, { recursive: true });
+
+  const Database = require('better-sqlite3');
+  _db = new Database(dbPath);
+
+  _db.pragma('journal_mode = WAL');
+  _db.pragma('synchronous = NORMAL');
+  _db.pragma('foreign_keys = ON');
+
+  runMigrations(_db);
+  return _db;
+}
+
+/**
+ * Run all migrations. SQL uses IF NOT EXISTS so this is always safe.
+ * @param {import('better-sqlite3').Database} db
+ */
+function runMigrations(db) {
+  // Bootstrap: create schema_version before we can check it
+  db.exec(`CREATE TABLE IF NOT EXISTS schema_version (
+    version    INTEGER PRIMARY KEY,
+    applied_at TEXT NOT NULL
+  )`);
+
+  const migrationsDir = path.join(__dirname, '..', 'migrations');
+  const files = fs.readdirSync(migrationsDir).filter(f => f.endsWith('.sql')).sort();
+
+  for (const file of files) {
+    const versionMatch = file.match(/^(\d+)/);
+    if (!versionMatch) continue;
+    const version = parseInt(versionMatch[1], 10);
+
+    const alreadyApplied = db.prepare(
+      'SELECT version FROM schema_version WHERE version = ?'
+    ).get(version);
+
+    if (!alreadyApplied) {
+      const sql = fs.readFileSync(path.join(migrationsDir, file), 'utf8');
+      try {
+        db.transaction(() => {
+          db.exec(sql);
+          db.prepare('INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)').run(
+            version, new Date().toISOString()
+          );
+        })();
+      } catch (err) {
+        // Table-rename migrations (003, 004) can fail on existing DBs whose schema is
+        // already partially updated. ensureColumn() below is the authoritative patcher
+        // and will add every required column regardless, so we log and continue.
+        console.warn(`[db] Migration ${file} skipped (schema already partially applied): ${err.message}`);
+      }
+    }
+  }
+
+  // Ensure ALL required columns exist (idempotent schema patching for legacy DBs)
+  // Sessions table
+  ensureColumn(db, 'sessions', 'instance_folder', 'TEXT');
+  ensureColumn(db, 'sessions', 'title', 'TEXT');
+  ensureColumn(db, 'sessions', 'message_count', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'sessions', 'total_input_tokens', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'sessions', 'total_output_tokens', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'sessions', 'total_cache_tokens', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'sessions', 'context_size', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'sessions', 'context_size_limit', 'INTEGER');
+  ensureColumn(db, 'sessions', 'cost', 'REAL NOT NULL DEFAULT 0');
+  ensureColumn(db, 'sessions', 'compaction_count', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'sessions', 'model_thinking', 'TEXT');
+
+  // Tasks table
+  ensureColumn(db, 'tasks', 'tags', 'TEXT');
+  ensureColumn(db, 'tasks', 'token_budget', 'INTEGER');
+  ensureColumn(db, 'tasks', 'max_iterations', 'INTEGER');
+  ensureColumn(db, 'tasks', 'max_duration_seconds', 'INTEGER');
+  ensureColumn(db, 'tasks', 'instance_folder', 'TEXT');
+  ensureColumn(db, 'tasks', 'iterations', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'tasks', 'token_input', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'tasks', 'token_output', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'tasks', 'token_cache', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(db, 'tasks', 'started_at', 'TEXT');
+  ensureColumn(db, 'tasks', 'finished_at', 'TEXT');
+
+  // Messages table
+  ensureColumn(db, 'messages', 'tool_calls', 'TEXT');
+  ensureColumn(db, 'messages', 'tool_call_id', 'TEXT');
+  ensureColumn(db, 'messages', 'model_key', 'TEXT');
+  ensureColumn(db, 'messages', 'input_tokens', 'INTEGER');
+  ensureColumn(db, 'messages', 'output_tokens', 'INTEGER');
+  ensureColumn(db, 'messages', 'cache_tokens', 'INTEGER');
+  ensureColumn(db, 'messages', 'cost', 'REAL');
+
+  // Agent messages table
+  ensureColumn(db, 'agent_messages', 'skill', 'TEXT');
+  ensureColumn(db, 'agent_messages', 'correlation_id', 'TEXT');
+  ensureColumn(db, 'agent_messages', 'response', 'TEXT');
+  ensureColumn(db, 'agent_messages', 'delivered_at', 'TEXT');
+}
+
+/**
+ * Add a column if it doesn't exist (SQLite doesn't support IF NOT EXISTS for ALTER TABLE).
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} table
+ * @param {string} column
+ * @param {string} type
+ */
+function ensureColumn(db, table, column, type) {
+  const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+  if (!columns.some(c => c.name === column)) {
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+  }
+}
+
+/**
+ * Close the database (for graceful shutdown).
+ */
+function closeDb() {
+  if (_db) {
+    _db.close();
+    _db = null;
+  }
+}
+
+// ── Session queries ──────────────────────────────────────────────────────────
+
+/**
+ * @param {{ agentName: string, mode: string, instanceFolder: string, model: string }} opts
+ * @returns {string} sessionId
+ */
+function createSession({ agentName, mode, instanceFolder, model, modelThinking }) {
+  const db = getDb();
+  const id = generateId('sess_');
+  const now = new Date().toISOString();
+  const contextSizeLimit = model ? (getContextLimit(model) || null) : null;
+  db.prepare(`
+    INSERT INTO sessions (id, agent_name, mode, instance_folder, status, model, model_thinking, context_size_limit, created_at, updated_at)
+    VALUES (?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)
+  `).run(id, agentName, mode, instanceFolder || null, model || null,
+    modelThinking ? JSON.stringify(modelThinking) : null, contextSizeLimit, now, now);
+  return id;
+}
+
+/**
+ * @param {string} sessionId
+ * @returns {Object|null}
+ */
+function getSession(sessionId) {
+  return getDb().prepare('SELECT * FROM sessions WHERE id = ?').get(sessionId) || null;
+}
+
+/**
+ * @param {{ instanceFolder?: string, agentName?: string, status?: string, limit?: number, cursor?: string }} opts
+ * @returns {Object[]}
+ */
+function listSessions({ instanceFolder, agentName, status, limit = 20, cursor } = {}) {
+  const db = getDb();
+  let query = 'SELECT * FROM sessions WHERE 1=1';
+  const params = [];
+  if (instanceFolder) { query += ' AND instance_folder = ?'; params.push(instanceFolder); }
+  if (agentName) { query += ' AND agent_name = ?'; params.push(agentName); }
+  if (status) { query += ' AND status = ?'; params.push(status); }
+  if (cursor) { query += ' AND id < ?'; params.push(cursor); }
+  query += ' ORDER BY created_at DESC LIMIT ?';
+  params.push(limit);
+  return db.prepare(query).all(...params);
+}
+
+/**
+ * @param {string} sessionId
+ * @param {Object} updates - Partial session fields to update
+ */
+function updateSession(sessionId, updates) {
+  const db = getDb();
+  const fields = Object.keys(updates).map(k => `${camelToSnake(k)} = ?`).join(', ');
+  const values = Object.values(updates);
+  db.prepare(`UPDATE sessions SET ${fields}, updated_at = ? WHERE id = ?`)
+    .run(...values, new Date().toISOString(), sessionId);
+}
+
+/**
+ * @param {string} sessionId
+ */
+function closeSession(sessionId) {
+  updateSession(sessionId, { status: 'closed' });
+}
+
+/**
+ * Hard delete a session and all its messages/todos (via CASCADE).
+ * @param {string} sessionId
+ */
+function deleteSession(sessionId) {
+  getDb().prepare('DELETE FROM sessions WHERE id = ?').run(sessionId);
+}
+
+/**
+ * Reset a session — clear all messages and token counts, keep session metadata.
+ * @param {string} sessionId
+ */
+function resetSession(sessionId) {
+  const db = getDb();
+  db.prepare('DELETE FROM messages WHERE session_id = ?').run(sessionId);
+  db.prepare(`
+    UPDATE sessions
+    SET message_count = 0, total_input_tokens = 0, total_output_tokens = 0, total_cache_tokens = 0,
+        context_size = 0, cost = 0, updated_at = ?
+    WHERE id = ?
+  `).run(new Date().toISOString(), sessionId);
+}
+
+// ── Message queries ──────────────────────────────────────────────────────────
+
+/**
+ * @param {{ sessionId: string, role: string, content?: string, toolCalls?: any[], toolCallId?: string, modelKey?: string, inputTokens?: number, outputTokens?: number, cacheTokens?: number, cost?: number }} msg
+ */
+function addMessage({ sessionId, role, content, toolCalls, toolCallId, modelKey, inputTokens, outputTokens, cacheTokens, cost }) {
+  const db = getDb();
+  const now = new Date().toISOString();
+  const { lastInsertRowid } = db.prepare(`
+    INSERT INTO messages (session_id, role, content, tool_calls, tool_call_id, model_key, input_tokens, output_tokens, cache_tokens, cost, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    sessionId, role,
+    content || null,
+    toolCalls ? JSON.stringify(toolCalls) : null,
+    toolCallId || null,
+    modelKey || null,
+    inputTokens || null,
+    outputTokens || null,
+    cacheTokens || null,
+    cost || null,
+    now
+  );
+  db.prepare('UPDATE sessions SET message_count = message_count + 1, updated_at = ? WHERE id = ?')
+    .run(now, sessionId);
+  return lastInsertRowid;
+}
+
+/**
+ * @param {string} sessionId
+ * @param {{ limit?: number, offset?: number }} opts
+ * @returns {Object[]}
+ */
+function getMessages(sessionId, { limit = 1000, offset = 0 } = {}) {
+  const rows = getDb().prepare(
+    'SELECT * FROM messages WHERE session_id = ? ORDER BY id ASC LIMIT ? OFFSET ?'
+  ).all(sessionId, limit, offset);
+  return rows.map(r => ({
+    ...r,
+    tool_calls: r.tool_calls ? JSON.parse(r.tool_calls) : null,
+  }));
+}
+
+// ── Task queries ─────────────────────────────────────────────────────────────
+
+/**
+ * @param {{ agentName: string, input: string, priority?: string, tags?: string[], maxIterations?: number, maxDurationSeconds?: number, parentTaskId?: string, instanceFolder?: string, sessionId?: string }} opts
+ * @returns {string} taskId
+ */
+function createTask({ agentName, input, priority = 'normal', tags, maxIterations, maxDurationSeconds, tokenBudget, parentTaskId, instanceFolder, sessionId }) {
+  const db = getDb();
+  const id = generateId('task_');
+  const now = new Date().toISOString();
+  db.prepare(`
+    INSERT INTO tasks (id, agent_name, status, priority, parent_task_id, session_id, input, tags, max_iterations, max_duration_seconds, token_budget, instance_folder, created_at, updated_at)
+    VALUES (?, ?, 'pending', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id, agentName, priority, parentTaskId || null, sessionId || null,
+    typeof input === 'string' ? input : JSON.stringify(input),
+    tags ? JSON.stringify(tags) : null,
+    maxIterations || null, maxDurationSeconds || null, tokenBudget || null,
+    instanceFolder || null, now, now
+  );
+  return id;
+}
+
+/**
+ * @param {string} taskId
+ * @returns {Object|null}
+ */
+function getTask(taskId) {
+  const row = getDb().prepare(`
+    SELECT t.*, (SELECT COUNT(*) FROM task_events WHERE task_id = t.id) AS event_count
+    FROM tasks t WHERE t.id = ?
+  `).get(taskId);
+  if (!row) return null;
+  return parseTaskRow(row);
+}
+
+/**
+ * @param {{ instanceFolder?: string, agentName?: string, status?: string, priority?: string, tags?: string, limit?: number, cursor?: string }} opts
+ * @returns {Object[]}
+ */
+function listTasks({ instanceFolder, agentName, status, priority, limit = 20, cursor } = {}) {
+  const db = getDb();
+  let query = 'SELECT * FROM tasks WHERE 1=1';
+  const params = [];
+  if (instanceFolder) { query += ' AND instance_folder = ?'; params.push(instanceFolder); }
+  if (agentName) { query += ' AND agent_name = ?'; params.push(agentName); }
+  if (status) { query += ' AND status = ?'; params.push(status); }
+  if (priority) { query += ' AND priority = ?'; params.push(priority); }
+  if (cursor) { query += ' AND id < ?'; params.push(cursor); }
+  query += ' ORDER BY created_at DESC LIMIT ?';
+  params.push(limit);
+  return db.prepare(query).all(...params).map(parseTaskRow);
+}
+
+/**
+ * @param {string} taskId
+ * @param {Object} updates
+ */
+function updateTask(taskId, updates) {
+  const db = getDb();
+  const snakeUpdates = {};
+  for (const [k, v] of Object.entries(updates)) {
+    snakeUpdates[camelToSnake(k)] = v;
+  }
+  const fields = Object.keys(snakeUpdates).map(k => `${k} = ?`).join(', ');
+  const values = Object.values(snakeUpdates);
+  db.prepare(`UPDATE tasks SET ${fields}, updated_at = ? WHERE id = ?`)
+    .run(...values, new Date().toISOString(), taskId);
+}
+
+/**
+ * Hard-delete a task and all its associated rows (events, context, subscriptions via CASCADE).
+ * @param {string} taskId
+ */
+function deleteTask(taskId) {
+  getDb().prepare('DELETE FROM tasks WHERE id = ?').run(taskId);
+}
+
+// ── Task context (LLM context snapshots for debuggability) ──────────────────────────────────────
+
+/**
+ * Save a snapshot of the LLM context (messages + tools) for a task.
+ * Upserts — always overwrites with the latest snapshot.
+ * @param {string} taskId
+ * @param {{ messages: Object[], tools: string[], iteration: number }} opts
+ */
+function saveTaskContext(taskId, { messages, tools, iteration }) {
+  getDb().prepare(`
+    INSERT INTO task_context (task_id, messages, tools, iteration, updated_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(task_id) DO UPDATE
+    SET messages = excluded.messages, tools = excluded.tools, iteration = excluded.iteration, updated_at = excluded.updated_at
+  `).run(taskId, JSON.stringify(messages), JSON.stringify(tools || []), iteration, new Date().toISOString());
+}
+
+/**
+ * Get the most recent LLM context snapshot for a task.
+ * @param {string} taskId
+ * @returns {Object|null}
+ */
+function getTaskContext(taskId) {
+  const row = getDb().prepare('SELECT * FROM task_context WHERE task_id = ?').get(taskId);
+  if (!row) return null;
+  return {
+    messages: JSON.parse(row.messages),
+    tools: JSON.parse(row.tools || '[]'),
+    iteration: row.iteration,
+    updatedAt: row.updated_at,
+  };
+}
+
+// ── Task events ──────────────────────────────────────────────────────────────────
+
+/**
+ * @param {{ taskId: string, type: string, data?: Object }} opts
+ */
+function addTaskEvent({ taskId, type, data }) {
+  getDb().prepare(
+    'INSERT INTO task_events (task_id, type, data, created_at) VALUES (?, ?, ?, ?)'
+  ).run(taskId, type, data ? JSON.stringify(data) : null, new Date().toISOString());
+}
+
+/**
+ * @param {string} taskId
+ * @returns {Object[]}
+ */
+function getTaskEvents(taskId, { since = 0, limit = 500 } = {}) {
+  return getDb().prepare(
+    'SELECT * FROM task_events WHERE task_id = ? AND id > ? ORDER BY id ASC LIMIT ?'
+  ).all(taskId, since, limit)
+    .map(r => ({ ...r, data: r.data ? JSON.parse(r.data) : null }));
+}
+
+// ── Todos ────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {string} sessionId
+ * @param {Object[]} items
+ */
+function saveTodos(sessionId, items) {
+  const db = getDb();
+  const now = new Date().toISOString();
+  db.prepare(`
+    INSERT INTO todos (session_id, items, updated_at) VALUES (?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET items = excluded.items, updated_at = excluded.updated_at
+  `).run(sessionId, JSON.stringify(items), now);
+}
+
+/**
+ * @param {string} sessionId
+ * @returns {Object[]}
+ */
+function getTodos(sessionId) {
+  const row = getDb().prepare('SELECT items FROM todos WHERE session_id = ?').get(sessionId);
+  return row ? JSON.parse(row.items) : [];
+}
+
+// ── Agent messages ────────────────────────────────────────────────────────────
+
+/**
+ * @param {{ targetAgent: string, targetSessionId?: string, fromAgent: string, content: string, followup?: boolean, skill?: string, correlationId?: string }} opts
+ * @returns {string} messageId
+ */
+function enqueueAgentMessage({ targetAgent, targetSessionId, fromAgent, content, followup = false, skill, correlationId }) {
+  const id = generateId('amsg_');
+  const now = new Date().toISOString();
+  getDb().prepare(`
+    INSERT INTO agent_messages (id, target_agent, target_session_id, from_agent, content, followup, skill, status, correlation_id, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)
+  `).run(id, targetAgent, targetSessionId || null, fromAgent, content, followup ? 1 : 0, skill || null, correlationId || null, now);
+  return id;
+}
+
+/**
+ * @param {string} targetAgent
+ * @returns {Object[]}
+ */
+function getPendingAgentMessages(targetAgent) {
+  return getDb().prepare(
+    "SELECT * FROM agent_messages WHERE target_agent = ? AND status = 'pending' ORDER BY id ASC"
+  ).all(targetAgent);
+}
+
+/**
+ * @param {string} messageId
+ * @param {string} [response]
+ */
+function markAgentMessageDelivered(messageId, response) {
+  getDb().prepare(
+    'UPDATE agent_messages SET status = ?, response = ?, delivered_at = ? WHERE id = ?'
+  ).run('delivered', response || null, new Date().toISOString(), messageId);
+}
+
+// ── Task subscriptions ───────────────────────────────────────────────────────
+
+/**
+ * @param {{ taskId: string, subscriberSessionId: string, subscriberAgent: string }} opts
+ */
+function createTaskSubscription({ taskId, subscriberSessionId, subscriberAgent }) {
+  getDb().prepare(`
+    INSERT INTO task_subscriptions (task_id, subscriber_session_id, subscriber_agent, status, created_at)
+    VALUES (?, ?, ?, 'pending', ?)
+  `).run(taskId, subscriberSessionId, subscriberAgent, new Date().toISOString());
+}
+
+/**
+ * @param {string} taskId
+ * @returns {Object[]}
+ */
+function getPendingSubscriptions(taskId) {
+  return getDb().prepare(
+    "SELECT * FROM task_subscriptions WHERE task_id = ? AND status = 'pending'"
+  ).all(taskId);
+}
+
+/**
+ * @param {number} subscriptionId
+ */
+function markSubscriptionDelivered(subscriptionId) {
+  getDb().prepare(
+    'UPDATE task_subscriptions SET status = ?, delivered_at = ? WHERE id = ?'
+  ).run('delivered', new Date().toISOString(), subscriptionId);
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Convert camelCase to snake_case.
+ * @param {string} str
+ * @returns {string}
+ */
+function camelToSnake(str) {
+  return str.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`);
+}
+
+/**
+ * Parse a task row from the DB, JSON-decoding fields.
+ * @param {Object} row
+ * @returns {Object}
+ */
+function parseTaskRow(row) {
+  return {
+    ...row,
+    tags: row.tags ? JSON.parse(row.tags) : [],
+    input: row.input ? tryJson(row.input) : null,
+    output: row.output || null,
+    error: row.error ? tryJson(row.error) : null,
+    tokenBudget: row.token_budget ?? null,
+    eventCount: row.event_count ?? undefined,
+  };
+}
+
+function tryJson(str) {
+  try { return JSON.parse(str); } catch { return str; }
+}
+
+/**
+ * Mark pending/processing tasks as failed (used on startup recovery).
+ * @param {string} instanceFolder
+ */
+function recoverStaleTasks(instanceFolder) {
+  const db = getDb();
+  const now = new Date().toISOString();
+  db.prepare(`
+    UPDATE tasks SET status = 'failed', error = 'Recovered: server was restarted', finished_at = ?, updated_at = ?
+    WHERE status IN ('processing') AND instance_folder = ?
+  `).run(now, now, instanceFolder);
+}
+
+module.exports = {
+  getDb,
+  closeDb,
+  runMigrations,
+  // Sessions
+  createSession, getSession, listSessions, updateSession, closeSession, deleteSession, resetSession,
+  // Messages
+  addMessage, getMessages,
+  // Tasks
+  createTask, getTask, listTasks, updateTask, deleteTask,
+  // Task context
+  saveTaskContext, getTaskContext,
+  // Task events
+  addTaskEvent, getTaskEvents,
+  // Todos
+  saveTodos, getTodos,
+  // Agent messages
+  enqueueAgentMessage, getPendingAgentMessages, markAgentMessageDelivered,
+  // Subscriptions
+  createTaskSubscription, getPendingSubscriptions, markSubscriptionDelivered,
+  // Startup
+  recoverStaleTasks,
+};

package/infrastructure/scheduler.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const cron = require('node-cron');
+
+/**
+ * Daemon scheduler — manages cron jobs for daemon-mode agents.
+ * State is in-memory, rebuilt from agent.json on restart.
+ */
+
+/**
+ * Create a new scheduler instance.
+ * @returns {Object} Scheduler API
+ */
+function createScheduler() {
+  const _jobs = new Map(); // agentName → { task: CronTask, lastRun: Date|null, status: string }
+
+  /**
+   * Start a daemon cron job for an agent.
+   * @param {{ agentName: string, agent: Object, cwd: string, settings: Object }} opts
+   */
+  function startDaemon({ agentName, agent, cwd, settings }) {
+    if (_jobs.has(agentName)) {
+      stopDaemon(agentName);
+    }
+
+    const cronExpr = agent.modes?.daemon?.cron;
+    if (!cronExpr) {
+      console.warn(`[scheduler] Agent "${agentName}" has no daemon cron schedule`);
+      return;
+    }
+
+    if (!cron.validate(cronExpr)) {
+      console.error(`[scheduler] Invalid cron schedule for "${agentName}": ${cronExpr}`);
+      return;
+    }
+
+    const conflictPolicy = agent.modes?.daemon?.conflictPolicy || 'skip';
+    let isRunning = false;
+
+    const task = cron.schedule(cronExpr, async () => {
+      if (isRunning) {
+        if (conflictPolicy === 'skip') {
+          console.log(`[scheduler] Daemon "${agentName}" tick skipped (still running)`);
+          return;
+        }
+        if (conflictPolicy === 'queue') {
+          // Wait for current run to finish — handled by cron itself
+          return;
+        }
+        // 'restart' — cancel current and start new (not easily doable with node-cron, just skip)
+        return;
+      }
+
+      isRunning = true;
+      const state = _jobs.get(agentName);
+      if (state) {
+        state.lastRun = new Date();
+        state.status = 'running';
+      }
+
+      try {
+        const { runDaemonTick } = require('../core/router');
+        await runDaemonTick({ agentName, cwd, settings });
+        if (state) state.status = 'idle';
+      } catch (err) {
+        console.error(`[scheduler] Daemon "${agentName}" tick error: ${err.message}`);
+        if (state) state.status = 'error';
+      } finally {
+        isRunning = false;
+      }
+    });
+
+    _jobs.set(agentName, {
+      task,
+      cron: cronExpr,
+      lastRun: null,
+      status: 'idle',
+      agentName,
+    });
+
+    console.log(`[scheduler] Daemon "${agentName}" started (cron: ${cronExpr})`);
+  }
+
+  /**
+   * Stop a daemon cron job.
+   * @param {string} agentName
+   */
+  function stopDaemon(agentName) {
+    const job = _jobs.get(agentName);
+    if (job) {
+      job.task.stop();
+      _jobs.delete(agentName);
+      console.log(`[scheduler] Daemon "${agentName}" stopped`);
+    }
+  }
+
+  /**
+   * Stop all daemon cron jobs.
+   */
+  function stopAll() {
+    for (const agentName of _jobs.keys()) {
+      stopDaemon(agentName);
+    }
+  }
+
+  /**
+   * List all active daemons.
+   * @returns {Object[]}
+   */
+  function listDaemons() {
+    return Array.from(_jobs.values()).map(j => ({
+      agentName: j.agentName,
+      cron: j.cron,
+      lastRun: j.lastRun ? j.lastRun.toISOString() : null,
+      status: j.status,
+    }));
+  }
+
+  return { startDaemon, stopDaemon, stopAll, listDaemons };
+}
+
+module.exports = { createScheduler };