@karmaniverous/jeeves-runner 0.1.2 → 0.2.1

package/dist/cli/jeeves-runner/index.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-import { mkdirSync, readFileSync } from 'node:fs';
+import { mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { dirname, extname, resolve } from 'node:path';
 import { Command } from 'commander';
+import { Cron, CronPattern } from 'croner';
 import { DatabaseSync } from 'node:sqlite';
 import { pino } from 'pino';
 import Fastify from 'fastify';
+import { request as request$1 } from 'node:http';
 import { request } from 'node:https';
 import { spawn } from 'node:child_process';
-import { Cron } from 'croner';
 import { z } from 'zod';
 
 /**
@@ -102,9 +103,76 @@ CREATE TABLE IF NOT EXISTS queues (
 
 CREATE INDEX IF NOT EXISTS idx_queues_poll ON queues(queue, status, priority DESC, created_at);
 `;
+/** Migration 002: Rename queues → queue_items, create queues definition table, add dedup support. */
+const MIGRATION_002 = `
+-- Drop old index first (references 'queue' column)
+DROP INDEX IF EXISTS idx_queues_poll;
+
+-- Rename existing queues table to queue_items
+ALTER TABLE queues RENAME TO queue_items;
+
+-- Create new queues definition table
+CREATE TABLE queues (
+  id              TEXT PRIMARY KEY,
+  name            TEXT NOT NULL,
+  description     TEXT,
+  dedup_expr      TEXT,
+  dedup_scope     TEXT DEFAULT 'pending',
+  max_attempts    INTEGER DEFAULT 1,
+  retention_days  INTEGER DEFAULT 7,
+  created_at      TEXT DEFAULT (datetime('now'))
+);
+
+-- Add new columns to queue_items
+ALTER TABLE queue_items ADD COLUMN queue_id TEXT;
+ALTER TABLE queue_items ADD COLUMN dedup_key TEXT;
+
+-- Migrate existing queue column to queue_id
+UPDATE queue_items SET queue_id = queue;
+
+-- Drop old queue column
+ALTER TABLE queue_items DROP COLUMN queue;
+
+-- Create dedup lookup index
+CREATE INDEX idx_queue_items_dedup ON queue_items(queue_id, dedup_key, status);
+
+-- Create new poll index
+CREATE INDEX idx_queue_items_poll ON queue_items(queue_id, status, priority DESC, created_at);
+
+-- Seed queue definitions
+INSERT INTO queues (id, name, description, dedup_expr, dedup_scope, max_attempts, retention_days) VALUES
+  ('email-updates', 'Email Update Queue', NULL, NULL, NULL, 1, 7),
+  ('email-pending', 'Email Pending', NULL, '$.threadId', 'pending', 1, 7),
+  ('x-posts', 'X Post Queue', NULL, '$.id', 'pending', 1, 7),
+  ('gh-collabs', 'GH Collab Queue', NULL, '$.full_name', 'pending', 1, 7);
+`;
+/** Migration 003: Rename cursors → state, add state_items table for collection state. */
+const MIGRATION_003 = `
+-- Rename cursors → state
+ALTER TABLE cursors RENAME TO state;
+
+-- Rename index
+DROP INDEX IF EXISTS idx_cursors_expires;
+CREATE INDEX idx_state_expires ON state(expires_at) WHERE expires_at IS NOT NULL;
+
+-- Create state_items table
+CREATE TABLE state_items (
+    namespace   TEXT NOT NULL,
+    key         TEXT NOT NULL,
+    item_key    TEXT NOT NULL,
+    value       TEXT,
+    created_at  TEXT DEFAULT (datetime('now')),
+    updated_at  TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (namespace, key, item_key),
+    FOREIGN KEY (namespace, key) REFERENCES state(namespace, key)
+);
+CREATE INDEX idx_state_items_ns_key ON state_items(namespace, key);
+`;
 /** Registry of all migrations keyed by version number. */
 const MIGRATIONS = {
     1: MIGRATION_001,
+    2: MIGRATION_002,
+    3: MIGRATION_003,
 };
 /**
  * Run all pending migrations. Creates schema_version table if needed, applies migrations in order.
@@ -143,7 +211,11 @@ function registerRoutes(app, deps) {
     const { db, scheduler } = deps;
     /** GET /health — Health check. */
     app.get('/health', () => {
-        return { ok: true, uptime: process.uptime() };
+        return {
+            ok: true,
+            uptime: process.uptime(),
+            failedRegistrations: scheduler.getFailedRegistrations().length,
+        };
     });
     /** GET /jobs — List all jobs with last run status. */
     app.get('/jobs', () => {
@@ -194,6 +266,7 @@ function registerRoutes(app, deps) {
             reply.code(404);
             return { error: 'Job not found' };
         }
+        scheduler.reconcileNow();
         return { ok: true };
     });
     /** POST /jobs/:id/disable — Disable a job. */
@@ -205,6 +278,7 @@ function registerRoutes(app, deps) {
             reply.code(404);
             return { error: 'Job not found' };
         }
+        scheduler.reconcileNow();
         return { ok: true };
     });
     /** GET /stats — Aggregate job statistics. */
@@ -213,6 +287,7 @@ function registerRoutes(app, deps) {
             .prepare('SELECT COUNT(*) as count FROM jobs')
             .get();
         const runningCount = scheduler.getRunningJobs().length;
+        const failedCount = scheduler.getFailedRegistrations().length;
         const okLastHour = db
             .prepare(`SELECT COUNT(*) as count FROM runs 
          WHERE status = 'ok' AND started_at > datetime('now', '-1 hour')`)
@@ -224,6 +299,7 @@ function registerRoutes(app, deps) {
         return {
             totalJobs: totalJobs.count,
             running: runningCount,
+            failedRegistrations: failedCount,
             okLastHour: okLastHour.count,
             errorsLastHour: errorsLastHour.count,
         };
@@ -236,19 +312,21 @@ function registerRoutes(app, deps) {
 /**
  * Create and configure the Fastify server. Routes are registered but server is not started.
  */
-function createServer(config, deps) {
+function createServer(deps) {
     const app = Fastify({
-        logger: {
-            level: config.log.level,
-            ...(config.log.file
-                ? {
-                    transport: {
-                        target: 'pino/file',
-                        options: { destination: config.log.file },
-                    },
-                }
-                : {}),
-        },
+        logger: deps.loggerConfig
+            ? {
+                level: deps.loggerConfig.level,
+                ...(deps.loggerConfig.file
+                    ? {
+                        transport: {
+                            target: 'pino/file',
+                            options: { destination: deps.loggerConfig.file },
+                        },
+                    }
+                    : {}),
+            }
+            : false,
     });
     registerRoutes(app, deps);
     return app;
@@ -259,20 +337,36 @@ function createServer(config, deps) {
  */
 /** Delete runs older than the configured retention period. */
 function pruneOldRuns(db, days, logger) {
+    const cutoffDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
     const result = db
-        .prepare(`DELETE FROM runs WHERE started_at < datetime('now', '-${String(days)} days')`)
-        .run();
+        .prepare(`DELETE FROM runs WHERE started_at < ?`)
+        .run(cutoffDate);
     if (result.changes > 0) {
         logger.info({ deleted: result.changes }, 'Pruned old runs');
     }
 }
-/** Delete expired cursor entries. */
+/** Delete expired state entries. */
 function cleanExpiredCursors(db, logger) {
     const result = db
-        .prepare(`DELETE FROM cursors WHERE expires_at IS NOT NULL AND expires_at < datetime('now')`)
+        .prepare(`DELETE FROM state WHERE expires_at IS NOT NULL AND expires_at < datetime('now')`)
         .run();
     if (result.changes > 0) {
-        logger.info({ deleted: result.changes }, 'Cleaned expired cursors');
+        logger.info({ deleted: result.changes }, 'Cleaned expired state entries');
+    }
+}
+/** Prune old queue items based on per-queue retention settings. */
+function pruneOldQueueItems(db, logger) {
+    const result = db
+        .prepare(`DELETE FROM queue_items 
+       WHERE status IN ('done', 'failed') 
+       AND finished_at < datetime('now', '-' || 
+         COALESCE(
+           (SELECT retention_days FROM queues WHERE queues.id = queue_items.queue_id),
+           7
+         ) || ' days')`)
+        .run();
+    if (result.changes > 0) {
+        logger.info({ deleted: result.changes }, 'Pruned old queue items');
     }
 }
 /**
@@ -283,6 +377,7 @@ function createMaintenance(db, config, logger) {
     function runAll() {
         pruneOldRuns(db, config.runRetentionDays, logger);
         cleanExpiredCursors(db, logger);
+        pruneOldQueueItems(db, logger);
     }
     return {
         start() {
@@ -304,38 +399,128 @@ function createMaintenance(db, config, logger) {
 }
 
 /**
- * Slack notification module. Sends job completion/failure messages via Slack Web API (chat.postMessage). Falls back gracefully if no token.
+ * Shared HTTP utility for making POST requests.
  */
-/** Post a message to Slack via chat.postMessage API. */
-function postToSlack(token, channel, text) {
+/** Make an HTTP/HTTPS POST request. Returns the parsed JSON response body. */
+function httpPost(url, headers, body, timeoutMs = 30000) {
     return new Promise((resolve, reject) => {
-        const payload = JSON.stringify({ channel, text });
-        const req = request('https://slack.com/api/chat.postMessage', {
+        const parsedUrl = new URL(url);
+        const isHttps = parsedUrl.protocol === 'https:';
+        const requestFn = isHttps ? request : request$1;
+        const req = requestFn({
+            hostname: parsedUrl.hostname,
+            port: parsedUrl.port,
+            path: parsedUrl.pathname + parsedUrl.search,
             method: 'POST',
             headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${token}`,
-                'Content-Length': Buffer.byteLength(payload),
+                ...headers,
+                'Content-Length': Buffer.byteLength(body),
             },
+            timeout: timeoutMs,
         }, (res) => {
-            let body = '';
+            let responseBody = '';
             res.on('data', (chunk) => {
-                body += chunk.toString();
+                responseBody += chunk.toString();
             });
             res.on('end', () => {
-                if (res.statusCode === 200) {
-                    resolve();
+                if (res.statusCode !== 200) {
+                    reject(new Error(`HTTP ${String(res.statusCode)}: ${responseBody}`));
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(responseBody));
                 }
-                else {
-                    reject(new Error(`Slack API returned ${String(res.statusCode)}: ${body}`));
+                catch {
+                    reject(new Error(`Failed to parse JSON response: ${responseBody}`));
                 }
             });
         });
         req.on('error', reject);
-        req.write(payload);
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error('Request timed out'));
+        });
+        req.write(body);
         req.end();
     });
 }
+
+/**
+ * OpenClaw Gateway HTTP client for spawning and monitoring sessions.
+ */
+/** Make an HTTP POST request to the Gateway /tools/invoke endpoint. */
+function invokeGateway(url, token, tool, args, timeoutMs = 30000) {
+    const payload = JSON.stringify({ tool, args });
+    return httpPost(`${url}/tools/invoke`, {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+    }, payload, timeoutMs);
+}
+/** Create a Gateway client. */
+function createGatewayClient(options) {
+    const { url, token, timeoutMs = 30000 } = options;
+    return {
+        async spawnSession(task, opts) {
+            const response = (await invokeGateway(url, token, 'sessions_spawn', {
+                task,
+                label: opts?.label,
+                thinking: opts?.thinking,
+                runTimeoutSeconds: opts?.runTimeoutSeconds,
+            }, timeoutMs));
+            if (!response.ok) {
+                throw new Error('Failed to spawn session');
+            }
+            return {
+                sessionKey: response.result.details.childSessionKey,
+                runId: response.result.details.runId,
+            };
+        },
+        async getSessionHistory(sessionKey, limit = 3) {
+            const response = (await invokeGateway(url, token, 'sessions_history', { sessionKey, limit, includeTools: false }, timeoutMs));
+            if (!response.ok) {
+                throw new Error('Failed to get session history');
+            }
+            return response.result;
+        },
+        async getSessionInfo(sessionKey) {
+            // Note: sessions_list doesn't support filtering by key, so we fetch recent sessions
+            // and search client-side. Consider using sessions_history with limit 1 as alternative,
+            // or request a sessions_get tool from Gateway for more efficient single-session lookup.
+            const response = (await invokeGateway(url, token, 'sessions_list', { activeMinutes: 120, limit: 500 }, // Increased from 100 to reduce false negatives
+            timeoutMs));
+            if (!response.ok) {
+                throw new Error('Failed to list sessions');
+            }
+            const session = response.result.find((s) => s.sessionKey === sessionKey);
+            if (!session)
+                return null;
+            return {
+                totalTokens: session.totalTokens,
+                model: session.model,
+                transcriptPath: session.transcriptPath,
+            };
+        },
+        async isSessionComplete(sessionKey) {
+            const history = await this.getSessionHistory(sessionKey, 3);
+            if (history.length === 0)
+                return false;
+            const lastMessage = history[history.length - 1];
+            return (lastMessage.role === 'assistant' && lastMessage.stopReason !== undefined);
+        },
+    };
+}
+
+/**
+ * Slack notification module. Sends job completion/failure messages via Slack Web API (chat.postMessage). Falls back gracefully if no token.
+ */
+/** Post a message to Slack via chat.postMessage API. */
+async function postToSlack(token, channel, text) {
+    const payload = JSON.stringify({ channel, text });
+    await httpPost('https://slack.com/api/chat.postMessage', {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+    }, payload);
+}
 /**
  * Create a notifier that sends Slack messages for job events. If no token, logs warning and returns silently.
  */
@@ -427,12 +612,14 @@ function resolveCommand(script) {
  * Execute a job script as a child process. Captures output, parses metadata, enforces timeout.
  */
 function executeJob(options) {
-    const { script, dbPath, jobId, runId, timeoutMs } = options;
+    const { script, dbPath, jobId, runId, timeoutMs, commandResolver } = options;
     const startTime = Date.now();
     return new Promise((resolve) => {
         const stdoutBuffer = new RingBuffer(100);
         const stderrBuffer = new RingBuffer(100);
-        const { command, args } = resolveCommand(script);
+        const { command, args } = commandResolver
+            ? commandResolver(script)
+            : resolveCommand(script);
         const child = spawn(command, args, {
             env: {
                 ...process.env,
@@ -527,66 +714,289 @@ function executeJob(options) {
     });
 }
 
+/**
+ * Cron registration and reconciliation utilities.
+ */
+function createCronRegistry(deps) {
+    const { db, logger, onScheduledRun } = deps;
+    const crons = new Map();
+    const cronSchedules = new Map();
+    const failedRegistrations = new Set();
+    function registerCron(job) {
+        try {
+            const jobId = job.id;
+            const cron = new Cron(job.schedule, () => {
+                // Re-read job from DB to get current configuration
+                const currentJob = db
+                    .prepare('SELECT * FROM jobs WHERE id = ? AND enabled = 1')
+                    .get(jobId);
+                if (!currentJob) {
+                    logger.warn({ jobId }, 'Job no longer exists or disabled, skipping');
+                    return;
+                }
+                onScheduledRun(currentJob);
+            });
+            crons.set(job.id, cron);
+            cronSchedules.set(job.id, job.schedule);
+            failedRegistrations.delete(job.id);
+            logger.info({ jobId: job.id, schedule: job.schedule }, 'Scheduled job');
+            return true;
+        }
+        catch (err) {
+            logger.error({ jobId: job.id, err }, 'Failed to schedule job');
+            failedRegistrations.add(job.id);
+            return false;
+        }
+    }
+    function reconcile() {
+        const enabledJobs = db
+            .prepare('SELECT * FROM jobs WHERE enabled = 1')
+            .all();
+        const enabledById = new Map(enabledJobs.map((j) => [j.id, j]));
+        // Remove disabled/deleted jobs
+        for (const [jobId, cron] of crons.entries()) {
+            if (!enabledById.has(jobId)) {
+                cron.stop();
+                crons.delete(jobId);
+                cronSchedules.delete(jobId);
+            }
+        }
+        const failedIds = [];
+        // Add or update enabled jobs
+        for (const job of enabledJobs) {
+            const existingCron = crons.get(job.id);
+            const existingSchedule = cronSchedules.get(job.id);
+            if (!existingCron) {
+                if (!registerCron(job))
+                    failedIds.push(job.id);
+                continue;
+            }
+            if (existingSchedule !== job.schedule) {
+                existingCron.stop();
+                crons.delete(job.id);
+                cronSchedules.delete(job.id);
+                if (!registerCron(job))
+                    failedIds.push(job.id);
+            }
+        }
+        return { totalEnabled: enabledJobs.length, failedIds };
+    }
+    function stopAll() {
+        for (const cron of crons.values()) {
+            cron.stop();
+        }
+        crons.clear();
+        cronSchedules.clear();
+    }
+    return {
+        reconcile,
+        stopAll,
+        getFailedRegistrations() {
+            return Array.from(failedRegistrations);
+        },
+    };
+}
+
+/**
+ * Notification dispatch helper for job completion events.
+ */
+/** Dispatch notification based on execution result and job configuration. */
+async function dispatchNotification(result, jobName, onSuccess, onFailure, notifier, logger) {
+    if (result.status === 'ok' && onSuccess) {
+        await notifier
+            .notifySuccess(jobName, result.durationMs, onSuccess)
+            .catch((err) => {
+            logger.error({ jobName, err }, 'Success notification failed');
+        });
+    }
+    else if (result.status !== 'ok' && onFailure) {
+        await notifier
+            .notifyFailure(jobName, result.durationMs, result.error, onFailure)
+            .catch((err) => {
+            logger.error({ jobName, err }, 'Failure notification failed');
+        });
+    }
+}
+
+/**
+ * Run record repository for managing job execution records.
+ */
+/** Create a run repository for the given database connection. */
+function createRunRepository(db) {
+    return {
+        createRun(jobId, trigger) {
+            const result = db
+                .prepare(`INSERT INTO runs (job_id, status, started_at, trigger) 
+           VALUES (?, 'running', datetime('now'), ?)`)
+                .run(jobId, trigger);
+            return result.lastInsertRowid;
+        },
+        finishRun(runId, execResult) {
+            db.prepare(`UPDATE runs SET status = ?, finished_at = datetime('now'), duration_ms = ?, 
+         exit_code = ?, tokens = ?, result_meta = ?, error = ?, stdout_tail = ?, stderr_tail = ?
+         WHERE id = ?`).run(execResult.status, execResult.durationMs, execResult.exitCode, execResult.tokens, execResult.resultMeta, execResult.error, execResult.stdoutTail, execResult.stderrTail, runId);
+        },
+    };
+}
+
+/**
+ * Session executor for job type='session'. Spawns OpenClaw Gateway sessions and polls for completion.
+ */
+/** File extensions that indicate a script rather than a prompt. */
+const SCRIPT_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ps1', '.cmd', '.bat'];
+/** Resolve task prompt from script field: read file if .md/.txt, return raw text otherwise. */
+function resolveTaskPrompt(script) {
+    const ext = extname(script).toLowerCase();
+    // If script extension, caller should fall back to script executor
+    if (SCRIPT_EXTENSIONS.includes(ext)) {
+        return null;
+    }
+    // If .md or .txt, read file contents
+    if (ext === '.md' || ext === '.txt') {
+        if (!existsSync(script)) {
+            throw new Error(`Prompt file not found: ${script}`);
+        }
+        return readFileSync(script, 'utf-8');
+    }
+    // Otherwise, treat script as raw prompt text
+    return script;
+}
+/** Poll for session completion with exponential backoff (capped). */
+async function pollCompletion(gatewayClient, sessionKey, timeoutMs, initialIntervalMs = 5000) {
+    const startTime = Date.now();
+    let interval = initialIntervalMs;
+    const maxInterval = 15000;
+    while (Date.now() - startTime < timeoutMs) {
+        const isComplete = await gatewayClient.isSessionComplete(sessionKey);
+        if (isComplete)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, interval));
+        interval = Math.min(interval * 1.2, maxInterval); // Exponential backoff capped
+    }
+    throw new Error(`Session timed out after ${String(timeoutMs)}ms`);
+}
+/**
+ * Execute a session job: spawn a Gateway session, poll for completion, fetch token usage.
+ */
+async function executeSession(options) {
+    const { script, jobId, timeoutMs = 300000, gatewayClient, pollIntervalMs, } = options;
+    const startTime = Date.now();
+    try {
+        // Resolve task prompt
+        const taskPrompt = resolveTaskPrompt(script);
+        if (taskPrompt === null) {
+            throw new Error('Session job script has script extension; expected prompt text or .md/.txt file');
+        }
+        // Spawn session
+        const { sessionKey } = await gatewayClient.spawnSession(taskPrompt, {
+            label: jobId,
+            thinking: 'low',
+            runTimeoutSeconds: Math.floor(timeoutMs / 1000),
+        });
+        // Poll for completion
+        await pollCompletion(gatewayClient, sessionKey, timeoutMs, pollIntervalMs);
+        // Fetch session info for token count
+        const sessionInfo = await gatewayClient.getSessionInfo(sessionKey);
+        const tokens = sessionInfo?.totalTokens ?? null;
+        const durationMs = Date.now() - startTime;
+        return {
+            status: 'ok',
+            exitCode: null,
+            durationMs,
+            tokens,
+            resultMeta: sessionKey,
+            stdoutTail: `Session completed: ${sessionKey}`,
+            stderrTail: '',
+            error: null,
+        };
+    }
+    catch (err) {
+        const durationMs = Date.now() - startTime;
+        const errorMessage = err instanceof Error ? err.message : 'Unknown session error';
+        // Check if timeout
+        if (errorMessage.includes('timed out')) {
+            return {
+                status: 'timeout',
+                exitCode: null,
+                durationMs,
+                tokens: null,
+                resultMeta: null,
+                stdoutTail: '',
+                stderrTail: errorMessage,
+                error: errorMessage,
+            };
+        }
+        return {
+            status: 'error',
+            exitCode: null,
+            durationMs,
+            tokens: null,
+            resultMeta: null,
+            stdoutTail: '',
+            stderrTail: errorMessage,
+            error: errorMessage,
+        };
+    }
+}
+
 /**
  * Croner-based job scheduler. Loads enabled jobs, creates cron instances, manages execution, respects overlap policies and concurrency limits.
  */
+// JobRow is imported from cron-registry
 /**
  * Create the job scheduler. Manages cron schedules, job execution, overlap policies, and notifications.
  */
 function createScheduler(deps) {
-    const { db, executor, notifier, config, logger } = deps;
-    const crons = new Map();
+    const { db, executor, notifier, config, logger, gatewayClient } = deps;
     const runningJobs = new Set();
-    /** Insert a run record and return its ID. */
-    function createRun(jobId, trigger) {
-        const result = db
-            .prepare(`INSERT INTO runs (job_id, status, started_at, trigger) 
-         VALUES (?, 'running', datetime('now'), ?)`)
-            .run(jobId, trigger);
-        return result.lastInsertRowid;
-    }
-    /** Update run record with completion data. */
-    function finishRun(runId, execResult) {
-        db.prepare(`UPDATE runs SET status = ?, finished_at = datetime('now'), duration_ms = ?, 
-       exit_code = ?, tokens = ?, result_meta = ?, error = ?, stdout_tail = ?, stderr_tail = ?
-       WHERE id = ?`).run(execResult.status, execResult.durationMs, execResult.exitCode, execResult.tokens, execResult.resultMeta, execResult.error, execResult.stdoutTail, execResult.stderrTail, runId);
-    }
+    const cronRegistry = createCronRegistry({
+        db,
+        logger,
+        onScheduledRun: (job) => {
+            void onScheduledRun(job);
+        },
+    });
+    const runRepository = createRunRepository(db);
+    let reconcileInterval = null;
     /** Execute a job: create run record, run script, update record, send notifications. */
     async function runJob(job, trigger) {
-        const { id, name, script, timeout_ms, on_success, on_failure } = job;
+        const { id, name, script, type, timeout_ms, on_success, on_failure } = job;
         // Check concurrency limit
         if (runningJobs.size >= config.maxConcurrency) {
             logger.warn({ jobId: id }, 'Max concurrency reached, skipping job');
             throw new Error('Max concurrency reached');
         }
         runningJobs.add(id);
-        const runId = createRun(id, trigger);
-        logger.info({ jobId: id, runId, trigger }, 'Starting job');
+        const runId = runRepository.createRun(id, trigger);
+        logger.info({ jobId: id, runId, trigger, type }, 'Starting job');
         try {
-            const result = await executor({
-                script,
-                dbPath: config.dbPath,
-                jobId: id,
-                runId,
-                timeoutMs: timeout_ms ?? undefined,
-            });
-            finishRun(runId, result);
-            logger.info({ jobId: id, runId, status: result.status }, 'Job finished');
-            // Send notifications
-            if (result.status === 'ok' && on_success) {
-                await notifier
-                    .notifySuccess(name, result.durationMs, on_success)
-                    .catch((err) => {
-                    logger.error({ jobId: id, err }, 'Notification failed');
+            let result;
+            // Route based on job type
+            if (type === 'session') {
+                if (!gatewayClient) {
+                    throw new Error('Session job requires Gateway client (gateway.tokenPath not configured)');
+                }
+                result = await executeSession({
+                    script,
+                    jobId: id,
+                    timeoutMs: timeout_ms ?? undefined,
+                    gatewayClient,
                 });
             }
-            else if (result.status !== 'ok' && on_failure) {
-                await notifier
-                    .notifyFailure(name, result.durationMs, result.error, on_failure)
-                    .catch((err) => {
-                    logger.error({ jobId: id, err }, 'Notification failed');
+            else {
+                // Default to script executor
+                result = await executor({
+                    script,
+                    dbPath: config.dbPath,
+                    jobId: id,
+                    runId,
+                    timeoutMs: timeout_ms ?? undefined,
                 });
             }
+            runRepository.finishRun(runId, result);
+            logger.info({ jobId: id, runId, status: result.status }, 'Job finished');
+            // Send notifications
+            await dispatchNotification(result, name, on_success, on_failure, notifier, logger);
             return result;
         }
         finally {
@@ -602,63 +1012,53 @@ function createScheduler(deps) {
                 logger.info({ jobId: id }, 'Job already running, skipping (overlap_policy=skip)');
                 return;
             }
-            else if (overlap_policy === 'queue') {
-                logger.info({ jobId: id }, 'Job already running, queueing (overlap_policy=queue)');
-                // In a real implementation, we'd queue this. For now, just skip.
-                return;
-            }
             // 'allow' policy: proceed
         }
         await runJob(job, 'schedule').catch((err) => {
             logger.error({ jobId: id, err }, 'Job execution failed');
         });
     }
+    // Cron registration and reconciliation are handled by cronRegistry.
     return {
         start() {
-            // Load all enabled jobs
-            const jobs = db
-                .prepare('SELECT * FROM jobs WHERE enabled = 1')
-                .all();
-            logger.info({ count: jobs.length }, 'Loading jobs');
-            for (const job of jobs) {
-                try {
-                    const jobId = job.id;
-                    const cron = new Cron(job.schedule, () => {
-                        // Re-read job from DB to get current configuration
-                        const currentJob = db
-                            .prepare('SELECT * FROM jobs WHERE id = ? AND enabled = 1')
-                            .get(jobId);
-                        if (!currentJob) {
-                            logger.warn({ jobId }, 'Job no longer exists or disabled, skipping');
-                            return;
-                        }
-                        void onScheduledRun(currentJob);
-                    });
-                    crons.set(job.id, cron);
-                    logger.info({ jobId: job.id, schedule: job.schedule }, 'Scheduled job');
-                }
-                catch (err) {
-                    logger.error({ jobId: job.id, err }, 'Failed to schedule job');
+            const { totalEnabled, failedIds } = cronRegistry.reconcile();
+            logger.info({ count: totalEnabled }, 'Loading jobs');
+            if (failedIds.length > 0) {
+                const ok = totalEnabled - failedIds.length;
+                logger.warn({ failed: failedIds.length, total: totalEnabled }, `${String(failedIds.length)} of ${String(totalEnabled)} jobs failed to register`);
+                const message = `⚠️ jeeves-runner started: ${String(ok)}/${String(totalEnabled)} jobs scheduled, ${String(failedIds.length)} failed: ${failedIds.join(', ')}`;
+                const channel = config.notifications.defaultOnFailure;
+                if (channel) {
+                    void notifier.notifyFailure('jeeves-runner', 0, message, channel);
                 }
             }
+            if (reconcileInterval === null && config.reconcileIntervalMs > 0) {
+                reconcileInterval = setInterval(() => {
+                    try {
+                        cronRegistry.reconcile();
+                    }
+                    catch (err) {
+                        logger.error({ err }, 'Reconciliation failed');
+                    }
+                }, config.reconcileIntervalMs);
+            }
         },
-        stop() {
+        async stop() {
             logger.info('Stopping scheduler');
-            // Stop all crons
-            for (const cron of crons.values()) {
-                cron.stop();
+            if (reconcileInterval) {
+                clearInterval(reconcileInterval);
+                reconcileInterval = null;
             }
-            crons.clear();
-            // Wait for running jobs (simple poll with timeout)
+            // Stop all crons
+            cronRegistry.stopAll();
+            // Wait for running jobs (with timeout)
             const deadline = Date.now() + config.shutdownGraceMs;
-            const checkInterval = setInterval(() => {
-                if (runningJobs.size === 0 || Date.now() > deadline) {
-                    clearInterval(checkInterval);
-                    if (runningJobs.size > 0) {
-                        logger.warn({ count: runningJobs.size }, 'Forced shutdown with running jobs');
-                    }
-                }
-            }, 100);
+            while (runningJobs.size > 0 && Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+            if (runningJobs.size > 0) {
+                logger.warn({ count: runningJobs.size }, 'Forced shutdown with running jobs');
+            }
         },
         async triggerJob(jobId) {
             const job = db.prepare('SELECT * FROM jobs WHERE id = ?').get(jobId);
@@ -666,9 +1066,15 @@ function createScheduler(deps) {
                 throw new Error(`Job not found: ${jobId}`);
             return runJob(job, 'manual');
         },
+        reconcileNow() {
+            cronRegistry.reconcile();
+        },
         getRunningJobs() {
             return Array.from(runningJobs);
         },
+        getFailedRegistrations() {
+            return cronRegistry.getFailedRegistrations();
+        },
     };
 }
 
@@ -678,22 +1084,22 @@ function createScheduler(deps) {
 /**
  * Create the runner. Initializes database, scheduler, API server, and sets up graceful shutdown.
  */
-function createRunner(config) {
+function createRunner(config, deps) {
     let db = null;
     let scheduler = null;
     let server = null;
     let maintenance = null;
     const logger = pino({
-        level: config.log.level,
-        ...(config.log.file
-            ? {
-                transport: {
-                    target: 'pino/file',
-                    options: { destination: config.log.file },
-                },
-            }
-            : {}),
-    });
+            level: config.log.level,
+            ...(config.log.file
+                ? {
+                    transport: {
+                        target: 'pino/file',
+                        options: { destination: config.log.file },
+                    },
+                }
+                : {}),
+        });
     return {
         async start() {
             logger.info('Starting runner');
@@ -706,6 +1112,19 @@ function createRunner(config) {
                 ? readFileSync(config.notifications.slackTokenPath, 'utf-8').trim()
                 : null;
             const notifier = createNotifier({ slackToken });
+            // Gateway client (optional, for session-type jobs)
+            const gatewayToken = config.gateway.tokenPath
+                ? readFileSync(config.gateway.tokenPath, 'utf-8').trim()
+                : (process.env.OPENCLAW_GATEWAY_TOKEN ?? null);
+            const gatewayClient = gatewayToken && config.gateway.url
+                ? createGatewayClient({
+                    url: config.gateway.url,
+                    token: gatewayToken,
+                })
+                : undefined;
+            if (gatewayClient) {
+                logger.info('Gateway client initialized');
+            }
             // Maintenance (run retention pruning + cursor cleanup)
             maintenance = createMaintenance(db, {
                 runRetentionDays: config.runRetentionDays,
@@ -720,11 +1139,16 @@ function createRunner(config) {
                 notifier,
                 config,
                 logger,
+                gatewayClient,
             });
             scheduler.start();
             logger.info('Scheduler started');
             // API server
-            server = createServer(config, { db, scheduler });
+            server = createServer({
+                db,
+                scheduler,
+                loggerConfig: { level: config.log.level, file: config.log.file },
+            });
             await server.listen({ port: config.port, host: '127.0.0.1' });
             logger.info({ port: config.port }, 'API server listening');
             // Graceful shutdown
@@ -747,7 +1171,7 @@ function createRunner(config) {
                 logger.info('Maintenance stopped');
             }
             if (scheduler) {
-                scheduler.stop();
+                await scheduler.stop();
                 logger.info('Scheduler stopped');
             }
             if (server) {
@@ -769,30 +1193,54 @@ function createRunner(config) {
  */
 /** Notification configuration sub-schema. */
 const notificationsSchema = z.object({
+    /** Path to Slack bot token file. */
     slackTokenPath: z.string().optional(),
+    /** Default Slack channel ID for failure notifications. */
     defaultOnFailure: z.string().nullable().default(null),
+    /** Default Slack channel ID for success notifications. */
     defaultOnSuccess: z.string().nullable().default(null),
 });
 /** Log configuration sub-schema. */
 const logSchema = z.object({
+    /** Log level threshold (trace, debug, info, warn, error, fatal). */
     level: z
         .enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal'])
         .default('info'),
+    /** Optional log file path. */
     file: z.string().optional(),
 });
+/** Gateway configuration sub-schema. */
+const gatewaySchema = z.object({
+    /** OpenClaw Gateway URL. */
+    url: z.string().default('http://127.0.0.1:18789'),
+    /** Path to file containing Gateway auth token. */
+    tokenPath: z.string().optional(),
+});
 /** Full runner configuration schema. Validates and provides defaults. */
 const runnerConfigSchema = z.object({
-    port: z.number().default(3100),
+    /** HTTP server port for the runner API. */
+    port: z.number().default(1937),
+    /** Path to SQLite database file. */
     dbPath: z.string().default('./data/runner.sqlite'),
+    /** Maximum number of concurrent job executions. */
     maxConcurrency: z.number().default(4),
+    /** Number of days to retain completed run records. */
     runRetentionDays: z.number().default(30),
+    /** Interval in milliseconds for cursor cleanup task. */
     cursorCleanupIntervalMs: z.number().default(3600000),
+    /** Grace period in milliseconds for shutdown completion. */
     shutdownGraceMs: z.number().default(30000),
+    /** Interval in milliseconds for job reconciliation checks. */
+    reconcileIntervalMs: z.number().default(60000),
+    /** Notification configuration for job completion events. */
     notifications: notificationsSchema.default({
         defaultOnFailure: null,
         defaultOnSuccess: null,
     }),
+    /** Logging configuration. */
     log: logSchema.default({ level: 'info' }),
+    /** Gateway configuration for session-type jobs. */
+    gateway: gatewaySchema.default({ url: 'http://127.0.0.1:18789' }),
 });
 
 /**
@@ -850,12 +1298,30 @@ program
     .option('-t, --type <type>', 'Job type (script|session)', 'script')
     .option('-d, --description <desc>', 'Job description')
     .option('--timeout <ms>', 'Timeout in ms')
-    .option('--overlap <policy>', 'Overlap policy (skip|queue|allow)', 'skip')
+    .option('--overlap <policy>', 'Overlap policy (skip|allow)', 'skip')
     .option('--on-failure <channel>', 'Slack channel for failure alerts')
     .option('--on-success <channel>', 'Slack channel for success alerts')
     .option('-c, --config <path>', 'Path to config file')
     .action((options) => {
     const config = loadConfig(options.config);
+    // Validate schedule expression before inserting
+    try {
+        new CronPattern(options.schedule);
+    }
+    catch (err) {
+        console.error(`Invalid schedule expression: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    // Validate overlap_policy
+    if (!['skip', 'allow'].includes(options.overlap)) {
+        console.error(`Invalid overlap policy '${options.overlap}'. Supported values: skip, allow`);
+        process.exit(1);
+    }
+    // Validate job type
+    if (!['script', 'session'].includes(options.type)) {
+        console.error(`Invalid job type '${options.type}'. Supported values: script, session`);
+        process.exit(1);
+    }
     const db = createConnection(config.dbPath);
     runMigrations(db);
     db.prepare(`INSERT INTO jobs (id, name, schedule, script, type, description, timeout_ms, overlap_policy, on_failure, on_success)