@karmaniverous/jeeves-runner 0.2.1 → 0.3.1

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, extname, resolve } from 'node:path';
 import { Command } from 'commander';
 import { Cron, CronPattern } from 'croner';
@@ -27,6 +27,9 @@ function createConnection(dbPath) {
     // Enable WAL mode for better concurrency
     db.exec('PRAGMA journal_mode = WAL;');
     db.exec('PRAGMA foreign_keys = ON;');
+    // Wait up to 5s for write lock instead of failing immediately (SQLITE_BUSY).
+    // Multiple runner child processes share this DB file concurrently.
+    db.exec('PRAGMA busy_timeout = 5000;');
     return db;
 }
 /**
@@ -139,6 +142,9 @@ 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);
 
+-- NOTE: These queue definitions are deployment-specific seeds. New installations
+-- should define queues via the seed script or API, not here. These remain in the
+-- migration for backward compatibility with existing databases.
 -- 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),
@@ -333,7 +339,7 @@ function createServer(deps) {
 }
 
 /**
- * Database maintenance tasks: run retention pruning and expired cursor cleanup.
+ * Database maintenance tasks: run retention pruning and expired state cleanup.
  */
 /** Delete runs older than the configured retention period. */
 function pruneOldRuns(db, days, logger) {
@@ -346,7 +352,7 @@ function pruneOldRuns(db, days, logger) {
     }
 }
 /** Delete expired state entries. */
-function cleanExpiredCursors(db, logger) {
+function cleanExpiredState(db, logger) {
     const result = db
         .prepare(`DELETE FROM state WHERE expires_at IS NOT NULL AND expires_at < datetime('now')`)
         .run();
@@ -376,7 +382,7 @@ function createMaintenance(db, config, logger) {
     let interval = null;
     function runAll() {
         pruneOldRuns(db, config.runRetentionDays, logger);
-        cleanExpiredCursors(db, logger);
+        cleanExpiredState(db, logger);
         pruneOldQueueItems(db, logger);
     }
     return {
@@ -384,7 +390,7 @@ function createMaintenance(db, config, logger) {
             // Run immediately on startup
             runAll();
             // Then run periodically
-            interval = setInterval(runAll, config.cursorCleanupIntervalMs);
+            interval = setInterval(runAll, config.stateCleanupIntervalMs);
         },
         stop() {
             if (interval) {
@@ -483,7 +489,8 @@ function createGatewayClient(options) {
             return response.result;
         },
         async getSessionInfo(sessionKey) {
-            // Note: sessions_list doesn't support filtering by key, so we fetch recent sessions
+            // TODO: Replace with a direct session lookup when Gateway adds sessions_get.
+            // Currently fetches up to 500 sessions and searches client-side � O(n) and
             // 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
@@ -529,23 +536,35 @@ function createNotifier(config) {
     return {
         async notifySuccess(jobName, durationMs, channel) {
             if (!slackToken) {
-                console.warn(`No Slack token configured — skipping success notification for ${jobName}`);
+                console.warn(`No Slack token configured � skipping success notification for ${jobName}`);
                 return;
             }
             const durationSec = (durationMs / 1000).toFixed(1);
-            const text = `✅ *${jobName}* completed (${durationSec}s)`;
+            const text = `?? *${jobName}* completed (${durationSec}s)`;
             await postToSlack(slackToken, channel, text);
         },
         async notifyFailure(jobName, durationMs, error, channel) {
             if (!slackToken) {
-                console.warn(`No Slack token configured — skipping failure notification for ${jobName}`);
+                console.warn(`No Slack token configured � skipping failure notification for ${jobName}`);
                 return;
             }
             const durationSec = (durationMs / 1000).toFixed(1);
             const errorMsg = error ? `: ${error}` : '';
-            const text = `⚠️ *${jobName}* failed (${durationSec}s)${errorMsg}`;
+            const text = `?? *${jobName}* failed (${durationSec}s)${errorMsg}`;
             await postToSlack(slackToken, channel, text);
         },
+        async dispatchResult(result, jobName, onSuccess, onFailure, logger) {
+            if (result.status === 'ok' && onSuccess) {
+                await this.notifySuccess(jobName, result.durationMs, onSuccess).catch((err) => {
+                    logger.error({ jobName, err }, 'Success notification failed');
+                });
+            }
+            else if (result.status !== 'ok' && onFailure) {
+                await this.notifyFailure(jobName, result.durationMs, result.error, onFailure).catch((err) => {
+                    logger.error({ jobName, err }, 'Failure notification failed');
+                });
+            }
+        },
     };
 }
 
@@ -797,27 +816,6 @@ function createCronRegistry(deps) {
     };
 }
 
-/**
- * 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.
  */
@@ -996,7 +994,7 @@ function createScheduler(deps) {
             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);
+            await notifier.dispatchResult(result, name, on_success, on_failure, logger);
             return result;
         }
         finally {
@@ -1125,10 +1123,10 @@ function createRunner(config, deps) {
             if (gatewayClient) {
                 logger.info('Gateway client initialized');
             }
-            // Maintenance (run retention pruning + cursor cleanup)
+            // Maintenance (run retention pruning + state cleanup)
             maintenance = createMaintenance(db, {
                 runRetentionDays: config.runRetentionDays,
-                cursorCleanupIntervalMs: config.cursorCleanupIntervalMs,
+                stateCleanupIntervalMs: config.stateCleanupIntervalMs,
             }, logger);
             maintenance.start();
             logger.info('Maintenance tasks started');
@@ -1226,8 +1224,8 @@ const runnerConfigSchema = z.object({
     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),
+    /** Interval in milliseconds for expired state cleanup task. */
+    stateCleanupIntervalMs: z.number().default(3600000),
     /** Grace period in milliseconds for shutdown completion. */
     shutdownGraceMs: z.number().default(30000),
     /** Interval in milliseconds for job reconciliation checks. */
@@ -1243,6 +1241,227 @@ const runnerConfigSchema = z.object({
     gateway: gatewaySchema.default({ url: 'http://127.0.0.1:18789' }),
 });
 
+/**
+ * @module commands/config
+ *
+ * CLI commands: validate, init, config show.
+ */
+/** Minimal starter config template. */
+const INIT_CONFIG_TEMPLATE = {
+    port: 1937,
+    dbPath: './data/runner.sqlite',
+    maxConcurrency: 4,
+    runRetentionDays: 30,
+    log: {
+        level: 'info',
+    },
+    notifications: {
+        slackTokenPath: '',
+        defaultOnFailure: null,
+        defaultOnSuccess: null,
+    },
+    gateway: {
+        url: 'http://127.0.0.1:18789',
+        tokenPath: '',
+    },
+};
+/** Register config-related commands on the CLI. */
+function registerConfigCommands(cli) {
+    cli
+        .command('validate')
+        .description('Validate a configuration file against the schema')
+        .requiredOption('-c, --config <path>', 'Path to configuration file')
+        .action((options) => {
+        try {
+            const raw = readFileSync(resolve(options.config), 'utf-8');
+            const parsed = JSON.parse(raw);
+            const config = runnerConfigSchema.parse(parsed);
+            console.log('✅ Config valid');
+            console.log(`  Port: ${String(config.port)}`);
+            console.log(`  Database: ${config.dbPath}`);
+            console.log(`  Max concurrency: ${String(config.maxConcurrency)}`);
+            console.log(`  Run retention: ${String(config.runRetentionDays)} days`);
+            console.log(`  Log level: ${config.log.level}`);
+            if (config.log.file) {
+                console.log(`  Log file: ${config.log.file}`);
+            }
+            if (config.notifications.slackTokenPath) {
+                console.log(`  Slack notifications: ${config.notifications.defaultOnFailure ? 'configured' : 'token set, no default channel'}`);
+            }
+            if (config.gateway.tokenPath) {
+                console.log(`  Gateway: ${config.gateway.url}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                console.error(`❌ Invalid JSON: ${error.message}`);
+            }
+            else {
+                console.error('❌ Config invalid:', error);
+            }
+            process.exit(1);
+        }
+    });
+    cli
+        .command('init')
+        .description('Generate a starter configuration file')
+        .option('-o, --output <path>', 'Output config file path', 'jeeves-runner.config.json')
+        .action((options) => {
+        const outputPath = resolve(options.output);
+        try {
+            readFileSync(outputPath);
+            console.error(`❌ File already exists: ${outputPath}`);
+            console.error('   Remove it first or choose a different path with -o');
+            process.exit(1);
+        }
+        catch {
+            // File doesn't exist, good
+        }
+        writeFileSync(outputPath, JSON.stringify(INIT_CONFIG_TEMPLATE, null, 2) + '\n');
+        console.log(`✅ Wrote ${outputPath}`);
+        console.log();
+        console.log('Next steps:');
+        console.log('  1. Edit the config file to set your paths and preferences');
+        console.log('  2. Validate: jeeves-runner validate -c ' + options.output);
+        console.log('  3. Start: jeeves-runner start -c ' + options.output);
+    });
+    cli
+        .command('config-show')
+        .description('Show the resolved configuration (defaults applied, secrets redacted)')
+        .requiredOption('-c, --config <path>', 'Path to configuration file')
+        .action((options) => {
+        try {
+            const raw = readFileSync(resolve(options.config), 'utf-8');
+            const parsed = JSON.parse(raw);
+            const config = runnerConfigSchema.parse(parsed);
+            // Redact sensitive paths
+            const redacted = {
+                ...config,
+                notifications: {
+                    ...config.notifications,
+                    slackTokenPath: config.notifications.slackTokenPath
+                        ? '***'
+                        : undefined,
+                },
+                gateway: {
+                    ...config.gateway,
+                    tokenPath: config.gateway.tokenPath ? '***' : undefined,
+                },
+            };
+            console.log(JSON.stringify(redacted, null, 2));
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                console.error(`❌ Invalid JSON: ${error.message}`);
+            }
+            else {
+                console.error('❌ Config invalid:', error);
+            }
+            process.exit(1);
+        }
+    });
+}
+
+/**
+ * @module commands/service
+ *
+ * CLI command: service install/uninstall.
+ * Prints platform-appropriate service registration instructions.
+ */
+/** Register the `service` command group on the CLI. */
+function registerServiceCommand(cli) {
+    const service = cli
+        .command('service')
+        .description('Generate service install/uninstall instructions');
+    service.addCommand(new Command('install')
+        .description('Print install instructions for a system service')
+        .option('-c, --config <path>', 'Path to configuration file')
+        .option('-n, --name <name>', 'Service name', 'jeeves-runner')
+        .action((options) => {
+        const { name } = options;
+        const configFlag = options.config ? ` -c "${options.config}"` : '';
+        if (process.platform === 'win32') {
+            console.log('# NSSM install (Windows)');
+            console.log(`  nssm install ${name} node "%APPDATA%\\npm\\node_modules\\@karmaniverous\\jeeves-runner\\dist\\cli\\jeeves-runner\\index.js" start${configFlag}`);
+            console.log(`  nssm set ${name} AppDirectory "%CD%"`);
+            console.log(`  nssm set ${name} DisplayName "Jeeves Runner"`);
+            console.log(`  nssm set ${name} Description "Job execution engine with SQLite state"`);
+            console.log(`  nssm set ${name} Start SERVICE_AUTO_START`);
+            console.log(`  nssm start ${name}`);
+            return;
+        }
+        if (process.platform === 'darwin') {
+            const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.jeeves.runner</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/jeeves-runner</string>
+    <string>start</string>${options.config ? `\n    <string>-c</string>\n    <string>${options.config}</string>` : ''}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>/tmp/${name}.stdout.log</string>
+  <key>StandardErrorPath</key><string>/tmp/${name}.stderr.log</string>
+</dict>
+</plist>`;
+            console.log('# launchd plist (macOS)');
+            console.log(`# ~/Library/LaunchAgents/com.jeeves.runner.plist`);
+            console.log(plist);
+            console.log();
+            console.log('# install');
+            console.log(`  launchctl load ~/Library/LaunchAgents/com.jeeves.runner.plist`);
+            return;
+        }
+        // Linux (systemd)
+        const unit = [
+            '[Unit]',
+            'Description=Jeeves Runner - Job Execution Engine',
+            'After=network.target',
+            '',
+            '[Service]',
+            'Type=simple',
+            'WorkingDirectory=%h',
+            `ExecStart=/usr/bin/env jeeves-runner start${configFlag}`,
+            'Restart=on-failure',
+            '',
+            '[Install]',
+            'WantedBy=default.target',
+        ].join('\n');
+        console.log('# systemd unit file (Linux)');
+        console.log(`# ~/.config/systemd/user/${name}.service`);
+        console.log(unit);
+        console.log();
+        console.log('# install');
+        console.log(`  systemctl --user daemon-reload`);
+        console.log(`  systemctl --user enable --now ${name}.service`);
+    }));
+    service.addCommand(new Command('uninstall')
+        .description('Print uninstall instructions for a system service')
+        .option('-n, --name <name>', 'Service name', 'jeeves-runner')
+        .action((options) => {
+        const { name } = options;
+        if (process.platform === 'win32') {
+            console.log('# NSSM uninstall (Windows)');
+            console.log(`  nssm stop ${name}`);
+            console.log(`  nssm remove ${name} confirm`);
+            return;
+        }
+        if (process.platform === 'darwin') {
+            console.log('# launchd uninstall (macOS)');
+            console.log(`  launchctl unload ~/Library/LaunchAgents/com.jeeves.runner.plist`);
+            console.log(`  rm ~/Library/LaunchAgents/com.jeeves.runner.plist`);
+            return;
+        }
+        console.log('# systemd uninstall (Linux)');
+        console.log(`  systemctl --user disable --now ${name}.service`);
+        console.log(`# rm ~/.config/systemd/user/${name}.service`);
+        console.log(`  systemctl --user daemon-reload`);
+    }));
+}
+
 /**
  * CLI entry point for jeeves-runner.
  *
@@ -1370,4 +1589,6 @@ program
         }
     })();
 });
+registerConfigCommands(program);
+registerServiceCommand(program);
 program.parse();

package/dist/index.d.ts

@@ -14,7 +14,7 @@ declare const runnerConfigSchema: z.ZodObject<{
     dbPath: z.ZodDefault<z.ZodString>;
     maxConcurrency: z.ZodDefault<z.ZodNumber>;
     runRetentionDays: z.ZodDefault<z.ZodNumber>;
-    cursorCleanupIntervalMs: z.ZodDefault<z.ZodNumber>;
+    stateCleanupIntervalMs: z.ZodDefault<z.ZodNumber>;
     shutdownGraceMs: z.ZodDefault<z.ZodNumber>;
     reconcileIntervalMs: z.ZodDefault<z.ZodNumber>;
     notifications: z.ZodDefault<z.ZodObject<{
@@ -102,8 +102,8 @@ type Queue = z.infer<typeof queueSchema>;
 
 /** Run status enumeration schema (pending, running, ok, error, timeout, skipped). */
 declare const runStatusSchema: z.ZodEnum<{
-    error: "error";
     pending: "pending";
+    error: "error";
     running: "running";
     ok: "ok";
     timeout: "timeout";
@@ -120,8 +120,8 @@ declare const runSchema: z.ZodObject<{
     id: z.ZodNumber;
     jobId: z.ZodString;
     status: z.ZodEnum<{
-        error: "error";
         pending: "pending";
+        error: "error";
         running: "running";
         ok: "ok";
         timeout: "timeout";
@@ -183,26 +183,18 @@ interface QueueItem {
 }
 
 /**
- * Job client library for runner jobs. Provides cursor (state) and queue operations. Opens its own DB connection via JR_DB_PATH env var.
+ * Job client library for runner jobs. Provides state and queue operations. Opens its own DB connection via JR_DB_PATH env var.
  */
 
 /** Client interface for job scripts to interact with runner state and queues. */
 interface RunnerClient {
-    /** Retrieve a cursor value by namespace and key. Returns null if not found or expired. */
-    getCursor(namespace: string, key: string): string | null;
-    /** Set or update a cursor value with optional TTL (e.g., '30d', '24h', '60m'). */
-    setCursor(namespace: string, key: string, value: string, options?: {
-        ttl?: string;
-    }): void;
-    /** Delete a cursor by namespace and key. */
-    deleteCursor(namespace: string, key: string): void;
-    /** Retrieve a state value by namespace and key (alias for getCursor). Returns null if not found or expired. */
+    /** Retrieve a state value by namespace and key. Returns null if not found or expired. */
     getState(namespace: string, key: string): string | null;
-    /** Set or update a state value with optional TTL (alias for setCursor). */
+    /** Set or update a state value with optional TTL (e.g., '30d', '24h', '60m'). */
     setState(namespace: string, key: string, value: string, options?: {
         ttl?: string;
     }): void;
-    /** Delete a state value by namespace and key (alias for deleteCursor). */
+    /** Delete a state value by namespace and key. */
     deleteState(namespace: string, key: string): void;
     /** Check if a state item exists in a collection. */
     hasItem(namespace: string, key: string, itemKey: string): boolean;
@@ -359,12 +351,23 @@ interface NotifyConfig {
     /** Slack bot token for posting messages (null if not configured). */
     slackToken: string | null;
 }
+/** Logger subset used by the notifier. */
+interface NotifyLogger {
+    /** Log an error with structured context. */
+    error(obj: Record<string, unknown>, msg: string): void;
+}
 /** Notifier interface for job completion events. */
 interface Notifier {
     /** Send a success notification to a Slack channel. */
     notifySuccess(jobName: string, durationMs: number, channel: string): Promise<void>;
     /** Send a failure notification to a Slack channel. */
     notifyFailure(jobName: string, durationMs: number, error: string | null, channel: string): Promise<void>;
+    /** Dispatch notification based on execution result and per-job channel config. */
+    dispatchResult(result: {
+        status: string;
+        durationMs: number;
+        error: string | null;
+    }, jobName: string, onSuccess: string | null, onFailure: string | null, logger: NotifyLogger): Promise<void>;
 }
 /**
  * Create a notifier that sends Slack messages for job events. If no token, logs warning and returns silently.
@@ -447,7 +450,7 @@ declare function createConnection(dbPath: string): DatabaseSync;
 declare function closeConnection(db: DatabaseSync): void;
 
 /**
- * Database maintenance tasks: run retention pruning and expired cursor cleanup.
+ * Database maintenance tasks: run retention pruning and expired state cleanup.
  */
 
 /** Configuration for maintenance tasks. */
@@ -455,7 +458,7 @@ interface MaintenanceConfig {
     /** Number of days to retain completed run records before pruning. */
     runRetentionDays: number;
     /** Interval in milliseconds between maintenance task runs. */
-    cursorCleanupIntervalMs: number;
+    stateCleanupIntervalMs: number;
 }
 /** Maintenance controller with start/stop lifecycle. */
 interface Maintenance {
@@ -481,4 +484,4 @@ declare function createMaintenance(db: DatabaseSync, config: MaintenanceConfig,
 declare function runMigrations(db: DatabaseSync): void;
 
 export { closeConnection, createClient, createConnection, createGatewayClient, createMaintenance, createNotifier, createRunner, createScheduler, executeJob, executeSession, jobSchema, queueSchema, runMigrations, runSchema, runStatusSchema, runTriggerSchema, runnerConfigSchema };
-export type { ExecutionOptions, ExecutionResult, GatewayClient, GatewayClientOptions, Job, Maintenance, MaintenanceConfig, Notifier, NotifyConfig, Queue, QueueItem, Run, RunStatus, RunTrigger, Runner, RunnerClient, RunnerConfig, Scheduler, SchedulerDeps, SessionExecutionOptions, SessionInfo, SessionMessage, SpawnSessionOptions, SpawnSessionResult };
+export type { ExecutionOptions, ExecutionResult, GatewayClient, GatewayClientOptions, Job, Maintenance, MaintenanceConfig, Notifier, NotifyConfig, NotifyLogger, Queue, QueueItem, ResolvedCommand, Run, RunStatus, RunTrigger, Runner, RunnerClient, RunnerConfig, RunnerDeps, Scheduler, SchedulerDeps, SessionExecutionOptions, SessionInfo, SessionMessage, SpawnSessionOptions, SpawnSessionResult };

package/dist/mjs/index.js

@@ -50,8 +50,8 @@ const runnerConfigSchema = z.object({
     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),
+    /** Interval in milliseconds for expired state cleanup task. */
+    stateCleanupIntervalMs: z.number().default(3600000),
     /** Grace period in milliseconds for shutdown completion. */
     shutdownGraceMs: z.number().default(30000),
     /** Interval in milliseconds for job reconciliation checks. */
@@ -316,6 +316,9 @@ function createConnection(dbPath) {
     // Enable WAL mode for better concurrency
     db.exec('PRAGMA journal_mode = WAL;');
     db.exec('PRAGMA foreign_keys = ON;');
+    // Wait up to 5s for write lock instead of failing immediately (SQLITE_BUSY).
+    // Multiple runner child processes share this DB file concurrently.
+    db.exec('PRAGMA busy_timeout = 5000;');
     return db;
 }
 /**
@@ -326,7 +329,7 @@ function closeConnection(db) {
 }
 
 /**
- * Database maintenance tasks: run retention pruning and expired cursor cleanup.
+ * Database maintenance tasks: run retention pruning and expired state cleanup.
  */
 /** Delete runs older than the configured retention period. */
 function pruneOldRuns(db, days, logger) {
@@ -339,7 +342,7 @@ function pruneOldRuns(db, days, logger) {
     }
 }
 /** Delete expired state entries. */
-function cleanExpiredCursors(db, logger) {
+function cleanExpiredState(db, logger) {
     const result = db
         .prepare(`DELETE FROM state WHERE expires_at IS NOT NULL AND expires_at < datetime('now')`)
         .run();
@@ -369,7 +372,7 @@ function createMaintenance(db, config, logger) {
     let interval = null;
     function runAll() {
         pruneOldRuns(db, config.runRetentionDays, logger);
-        cleanExpiredCursors(db, logger);
+        cleanExpiredState(db, logger);
         pruneOldQueueItems(db, logger);
     }
     return {
@@ -377,7 +380,7 @@ function createMaintenance(db, config, logger) {
             // Run immediately on startup
             runAll();
             // Then run periodically
-            interval = setInterval(runAll, config.cursorCleanupIntervalMs);
+            interval = setInterval(runAll, config.stateCleanupIntervalMs);
         },
         stop() {
             if (interval) {
@@ -494,6 +497,9 @@ 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);
 
+-- NOTE: These queue definitions are deployment-specific seeds. New installations
+-- should define queues via the seed script or API, not here. These remain in the
+-- migration for backward compatibility with existing databases.
 -- 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),
@@ -641,7 +647,8 @@ function createGatewayClient(options) {
             return response.result;
         },
         async getSessionInfo(sessionKey) {
-            // Note: sessions_list doesn't support filtering by key, so we fetch recent sessions
+            // TODO: Replace with a direct session lookup when Gateway adds sessions_get.
+            // Currently fetches up to 500 sessions and searches client-side � O(n) and
             // 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
@@ -687,23 +694,35 @@ function createNotifier(config) {
     return {
         async notifySuccess(jobName, durationMs, channel) {
             if (!slackToken) {
-                console.warn(`No Slack token configured — skipping success notification for ${jobName}`);
+                console.warn(`No Slack token configured � skipping success notification for ${jobName}`);
                 return;
             }
             const durationSec = (durationMs / 1000).toFixed(1);
-            const text = `✅ *${jobName}* completed (${durationSec}s)`;
+            const text = `?? *${jobName}* completed (${durationSec}s)`;
             await postToSlack(slackToken, channel, text);
         },
         async notifyFailure(jobName, durationMs, error, channel) {
             if (!slackToken) {
-                console.warn(`No Slack token configured — skipping failure notification for ${jobName}`);
+                console.warn(`No Slack token configured � skipping failure notification for ${jobName}`);
                 return;
             }
             const durationSec = (durationMs / 1000).toFixed(1);
             const errorMsg = error ? `: ${error}` : '';
-            const text = `⚠️ *${jobName}* failed (${durationSec}s)${errorMsg}`;
+            const text = `?? *${jobName}* failed (${durationSec}s)${errorMsg}`;
             await postToSlack(slackToken, channel, text);
         },
+        async dispatchResult(result, jobName, onSuccess, onFailure, logger) {
+            if (result.status === 'ok' && onSuccess) {
+                await this.notifySuccess(jobName, result.durationMs, onSuccess).catch((err) => {
+                    logger.error({ jobName, err }, 'Success notification failed');
+                });
+            }
+            else if (result.status !== 'ok' && onFailure) {
+                await this.notifyFailure(jobName, result.durationMs, result.error, onFailure).catch((err) => {
+                    logger.error({ jobName, err }, 'Failure notification failed');
+                });
+            }
+        },
     };
 }
 
@@ -955,27 +974,6 @@ function createCronRegistry(deps) {
     };
 }
 
-/**
- * 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.
  */
@@ -1154,7 +1152,7 @@ function createScheduler(deps) {
             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);
+            await notifier.dispatchResult(result, name, on_success, on_failure, logger);
             return result;
         }
         finally {
@@ -1284,10 +1282,10 @@ function createRunner(config, deps) {
             if (gatewayClient) {
                 logger.info('Gateway client initialized');
             }
-            // Maintenance (run retention pruning + cursor cleanup)
+            // Maintenance (run retention pruning + state cleanup)
             maintenance = createMaintenance(db, {
                 runRetentionDays: config.runRetentionDays,
-                cursorCleanupIntervalMs: config.cursorCleanupIntervalMs,
+                stateCleanupIntervalMs: config.stateCleanupIntervalMs,
             }, logger);
             maintenance.start();
             logger.info('Maintenance tasks started');
@@ -1479,7 +1477,7 @@ function parseTtl(ttl) {
 /** Create state operations for the given database connection. */
 function createStateOps(db) {
     return {
-        getCursor(namespace, key) {
+        getState(namespace, key) {
             const row = db
                 .prepare(`SELECT value FROM state 
            WHERE namespace = ? AND key = ? 
@@ -1487,7 +1485,7 @@ function createStateOps(db) {
                 .get(namespace, key);
             return row?.value ?? null;
         },
-        setCursor(namespace, key, value, options) {
+        setState(namespace, key, value, options) {
             const expiresAt = options?.ttl ? parseTtl(options.ttl) : null;
             if (expiresAt) {
                 db.prepare(`INSERT INTO state (namespace, key, value, expires_at) VALUES (?, ?, ?, ?)
@@ -1498,17 +1496,8 @@ function createStateOps(db) {
            ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value, updated_at = datetime('now')`).run(namespace, key, value);
             }
         },
-        deleteCursor(namespace, key) {
-            db.prepare('DELETE FROM state WHERE namespace = ? AND key = ?').run(namespace, key);
-        },
-        getState(namespace, key) {
-            return this.getCursor(namespace, key);
-        },
-        setState(namespace, key, value, options) {
-            this.setCursor(namespace, key, value, options);
-        },
         deleteState(namespace, key) {
-            this.deleteCursor(namespace, key);
+            db.prepare('DELETE FROM state WHERE namespace = ? AND key = ?').run(namespace, key);
         },
     };
 }
@@ -1562,7 +1551,7 @@ function createCollectionOps(db) {
 }
 
 /**
- * Job client library for runner jobs. Provides cursor (state) and queue operations. Opens its own DB connection via JR_DB_PATH env var.
+ * Job client library for runner jobs. Provides state and queue operations. Opens its own DB connection via JR_DB_PATH env var.
  */
 /**
  * Create a runner client for job scripts. Opens its own DB connection.

package/package.json

@@ -1,17 +1,50 @@
 {
+  "name": "@karmaniverous/jeeves-runner",
+  "version": "0.3.1",
   "author": "Jason Williscroft",
+  "description": "Graph-aware job execution engine with SQLite state. Part of the Jeeves platform.",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "module": "dist/mjs/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
     "jeeves-runner": "./dist/cli/jeeves-runner/index.js"
   },
-  "auto-changelog": {
-    "output": "CHANGELOG.md",
-    "unreleased": true,
-    "commitLimit": false,
-    "hideCredit": true
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/mjs/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karmaniverous/jeeves-runner.git",
+    "directory": "packages/service"
   },
   "bugs": {
     "url": "https://github.com/karmaniverous/jeeves-runner/issues"
   },
+  "homepage": "https://github.com/karmaniverous/jeeves-runner#readme",
+  "keywords": [
+    "jeeves",
+    "job-scheduler",
+    "cron",
+    "sqlite",
+    "workflow",
+    "automation",
+    "graph",
+    "fastify",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "commander": "^14.0.3",
     "croner": "^10.0.1",
@@ -20,78 +53,50 @@
     "pino": "^10.3.1",
     "zod": "^4.3.6"
   },
-  "description": "Graph-aware job execution engine with SQLite state. Part of the Jeeves platform.",
   "devDependencies": {
     "@dotenvx/dotenvx": "^1.52.0",
-    "@eslint/js": "^9.39.3",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.3.3",
     "@vitest/coverage-v8": "^4.0.18",
-    "@vitest/eslint-plugin": "^1.6.9",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",
-    "eslint": "^9.39.3",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.5",
-    "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-tsdoc": "^0.5.0",
     "fs-extra": "^11.3.3",
     "happy-dom": "^20.7.0",
-    "knip": "^5.85.0",
-    "lefthook": "^2.1.1",
-    "prettier": "^3.8.1",
     "release-it": "^19.2.4",
-    "rimraf": "^6.1.3",
     "rollup": "^4.59.0",
     "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-dts": "^6.3.0",
     "tslib": "^2.8.1",
-    "typedoc": "^0.28.17",
-    "typedoc-plugin-mdn-links": "^5.1.1",
-    "typedoc-plugin-replace-text": "^4.2.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1",
     "vitest": "^4.0.18"
   },
-  "engines": {
-    "node": ">=20"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/mjs/index.js"
-    }
+  "scripts": {
+    "build": "rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "changelog": "auto-changelog",
+    "diagrams": "cd diagrams && plantuml -tpng -o ../assets -r .",
+    "knip": "knip",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "release": "dotenvx run -f .env.local -- release-it",
+    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
+    "test": "vitest run",
+    "typecheck": "tsc"
   },
-  "files": [
-    "dist"
-  ],
-  "homepage": "https://github.com/karmaniverous/jeeves-runner#readme",
-  "keywords": [
-    "jeeves",
-    "job-scheduler",
-    "cron",
-    "sqlite",
-    "workflow",
-    "automation",
-    "graph",
-    "fastify",
-    "typescript"
-  ],
-  "license": "BSD-3-Clause",
-  "module": "dist/mjs/index.js",
-  "name": "@karmaniverous/jeeves-runner",
-  "publishConfig": {
-    "access": "public"
+  "auto-changelog": {
+    "output": "CHANGELOG.md",
+    "unreleased": true,
+    "commitLimit": false,
+    "hideCredit": true
   },
   "release-it": {
     "git": {
       "changelog": "npx auto-changelog --unreleased-only --stdout --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
-      "commitMessage": "chore: release v${version}",
+      "commitMessage": "chore: release @karmaniverous/jeeves-runner v${version}",
+      "tagName": "service/${version}",
       "requireBranch": "main"
     },
     "github": {
@@ -106,37 +111,16 @@
       ],
       "before:npm:release": [
         "npx auto-changelog -p",
-        "npm run docs",
         "git add -A"
       ],
       "after:release": [
-        "git switch -c release/${version}",
-        "git push -u origin release/${version}",
+        "git switch -c release/service/${version}",
+        "git push -u origin release/service/${version}",
         "git switch ${branchName}"
       ]
     },
     "npm": {
       "publish": true
     }
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/karmaniverous/jeeves-runner.git"
-  },
-  "scripts": {
-    "build": "rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
-    "changelog": "auto-changelog",
-    "diagrams": "cd diagrams/src && plantuml -tpng -o ../out -r .",
-    "docs": "typedoc",
-    "knip": "knip",
-    "lint": "eslint .",
-    "lint:fix": "eslint --fix .",
-    "release": "dotenvx run -f .env.local -- release-it",
-    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
-    "test": "vitest run",
-    "typecheck": "tsc"
-  },
-  "type": "module",
-  "types": "dist/index.d.ts",
-  "version": "0.2.1"
+  }
 }

package/LICENSE

@@ -1,28 +0,0 @@
-BSD 3-Clause License
-
-Copyright (c) 2025, Jason Williscroft
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,401 +0,0 @@
-# jeeves-runner
-
-[![npm version](https://img.shields.io/npm/v/@karmaniverous/jeeves-runner.svg)](https://www.npmjs.com/package/@karmaniverous/jeeves-runner)
-![Node Current](https://img.shields.io/node/v/@karmaniverous/jeeves-runner)
-[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://github.com/karmaniverous/jeeves-runner/tree/main/LICENSE.md)
-
-Graph-aware job execution engine with SQLite state. Part of the [Jeeves platform](#the-jeeves-platform).
-
-## What It Does
-
-jeeves-runner schedules and executes jobs, tracks their state in SQLite, and exposes status via a REST API. It replaces both n8n and Windows Task Scheduler as the substrate for data flow automation.
-
-**Key properties:**
-
-- **Domain-agnostic.** The runner knows graph primitives (source, sink, datastore, queue, process, auth), not business concepts. "Email polling" and "meeting extraction" are just jobs with scripts.
-- **SQLite-native.** Job definitions, run history, cursors, and queues live in a single SQLite file. No external database, no Redis.
-- **Zero new infrastructure.** One Node.js process, one SQLite file. Runs as a system service via NSSM (Windows) or systemd (Linux).
-- **Scripts as config.** Job scripts live outside the runner repo at configurable absolute paths. The runner is generic; the scripts are instance-specific.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────┐
-│                  jeeves-runner                   │
-│                                                  │
-│  ┌───────────┐  ┌──────────┐  ┌──────────────┐  │
-│  │ Scheduler │──│ Executor │──│  Notifier    │  │
-│  │  (croner) │  │ (spawn)  │  │  (Slack)     │  │
-│  └───────────┘  └──────────┘  └──────────────┘  │
-│                                                  │
-│  ┌───────────┐  ┌──────────┐  ┌──────────────┐  │
-│  │  SQLite   │  │ REST API │  │ Maintenance  │  │
-│  │   (DB)    │  │(Fastify) │  │ (pruning)    │  │
-│  └───────────┘  └──────────┘  └──────────────┘  │
-└─────────────────────────────────────────────────┘
-         │                │
-         ▼                ▼
-   runner.sqlite    localhost:3100
-```
-
-### Stack
-
-| Component | Technology |
-|-----------|-----------|
-| Runtime | Node.js v24+ (uses built-in `node:sqlite`) |
-| Scheduler | [croner](https://www.npmjs.com/package/croner) |
-| Database | SQLite via `node:sqlite` |
-| Process isolation | `child_process.spawn` |
-| HTTP API | [Fastify](https://fastify.dev/) |
-| Logging | [pino](https://getpino.io/) |
-| Config validation | [Zod](https://zod.dev/) |
-
-## Installation
-
-```bash
-npm install @karmaniverous/jeeves-runner
-```
-
-Requires Node.js 24+ for `node:sqlite` support.
-
-## Quick Start
-
-### 1. Create a config file
-
-```json
-{
-  "port": 3100,
-  "dbPath": "./data/runner.sqlite",
-  "maxConcurrency": 4,
-  "runRetentionDays": 30,
-  "cursorCleanupIntervalMs": 3600000,
-  "shutdownGraceMs": 30000,
-  "notifications": {
-    "slackTokenPath": "./credentials/slack-bot-token",
-    "defaultOnFailure": "YOUR_SLACK_CHANNEL_ID",
-    "defaultOnSuccess": null
-  },
-  "log": {
-    "level": "info",
-    "file": "./data/runner.log"
-  }
-}
-```
-
-### 2. Start the runner
-
-```bash
-npx jeeves-runner start --config ./config.json
-```
-
-### 3. Add a job
-
-```bash
-npx jeeves-runner add-job \
-  --id my-job \
-  --name "My Job" \
-  --schedule "*/5 * * * *" \
-  --script /absolute/path/to/script.js \
-  --config ./config.json
-```
-
-### 4. Check status
-
-```bash
-npx jeeves-runner status --config ./config.json
-npx jeeves-runner list-jobs --config ./config.json
-```
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `start` | Start the runner daemon |
-| `status` | Show runner stats (queries the HTTP API) |
-| `list-jobs` | List all configured jobs |
-| `add-job` | Add a new job to the database |
-| `trigger` | Manually trigger a job run (queries the HTTP API) |
-
-All commands accept `--config <path>` to specify the config file.
-
-## HTTP API
-
-The runner exposes a REST API on `localhost` (not externally accessible by default).
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/health` | Health check |
-| `GET` | `/jobs` | List all jobs with last run status |
-| `GET` | `/jobs/:id` | Single job detail |
-| `GET` | `/jobs/:id/runs` | Run history (paginated via `?limit=N`) |
-| `POST` | `/jobs/:id/run` | Trigger manual run |
-| `POST` | `/jobs/:id/enable` | Enable a job |
-| `POST` | `/jobs/:id/disable` | Disable a job |
-| `GET` | `/stats` | Aggregate stats (jobs ok/error/running counts) |
-
-### Example response
-
-```json
-// GET /jobs
-{
-  "jobs": [
-    {
-      "id": "email-poll",
-      "name": "Poll Email",
-      "schedule": "*/11 * * * *",
-      "enabled": 1,
-      "last_status": "ok",
-      "last_run": "2026-02-24T10:30:00"
-    }
-  ]
-}
-```
-
-## SQLite Schema
-
-Four tables manage all runner state:
-
-### `jobs` — Job Definitions
-
-Each job has an ID, name, cron schedule, script path, and behavioral configuration.
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `id` | TEXT PK | Job identifier (e.g. `email-poll`) |
-| `name` | TEXT | Human-readable name |
-| `schedule` | TEXT | Cron expression |
-| `script` | TEXT | Absolute path to script |
-| `type` | TEXT | `script` or `session` (LLM dispatcher) |
-| `enabled` | INTEGER | 1 = active, 0 = paused |
-| `timeout_ms` | INTEGER | Kill after this duration (null = no limit) |
-| `overlap_policy` | TEXT | `skip` (default), `queue`, or `allow` |
-| `on_failure` | TEXT | Slack channel ID for failure alerts |
-| `on_success` | TEXT | Slack channel ID for success alerts |
-
-### `runs` — Run History
-
-Every execution is recorded with status, timing, output capture, and optional token tracking.
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `id` | INTEGER PK | Auto-incrementing run ID |
-| `job_id` | TEXT FK | References `jobs.id` |
-| `status` | TEXT | `pending`, `running`, `ok`, `error`, `timeout`, `skipped` |
-| `duration_ms` | INTEGER | Wall-clock execution time |
-| `exit_code` | INTEGER | Process exit code |
-| `tokens` | INTEGER | LLM token count (session jobs only) |
-| `result_meta` | TEXT | JSON from `JR_RESULT:{json}` stdout lines |
-| `stdout_tail` | TEXT | Last 100 lines of stdout |
-| `stderr_tail` | TEXT | Last 100 lines of stderr |
-| `trigger` | TEXT | `schedule`, `manual`, or `retry` |
-
-Runs older than `runRetentionDays` are automatically pruned.
-
-### `cursors` — Key-Value State
-
-General-purpose key-value store with optional TTL. Replaces JSONL registry files.
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `namespace` | TEXT | Logical grouping (typically job ID) |
-| `key` | TEXT | State key |
-| `value` | TEXT | State value (string or JSON) |
-| `expires_at` | TEXT | Optional TTL (ISO timestamp, auto-cleaned) |
-
-### `queues` — Work Queues
-
-Priority-ordered work queues with claim semantics. SQLite's serialized writes prevent double-claims.
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `id` | INTEGER PK | Auto-incrementing item ID |
-| `queue` | TEXT | Queue name |
-| `payload` | TEXT | JSON blob |
-| `status` | TEXT | `pending`, `claimed`, `done`, `error` |
-| `priority` | INTEGER | Higher = more urgent |
-| `attempts` | INTEGER | Delivery attempt count |
-| `max_attempts` | INTEGER | Maximum retries |
-
-## Job Scripts
-
-Jobs are plain Node.js scripts executed as child processes. The runner passes context via environment variables:
-
-| Variable | Description |
-|----------|-------------|
-| `JR_DB_PATH` | Path to the runner SQLite database |
-| `JR_JOB_ID` | ID of the current job |
-| `JR_RUN_ID` | ID of the current run |
-
-### Structured output
-
-Scripts can emit structured results by writing a line to stdout:
-
-```
-JR_RESULT:{"tokens":1500,"meta":"processed 42 items"}
-```
-
-The runner parses this and stores the data in the `runs` table.
-
-### Client library
-
-Job scripts can import the runner client for cursor and queue operations:
-
-```typescript
-import { createClient } from '@karmaniverous/jeeves-runner';
-
-const jr = createClient(); // reads JR_DB_PATH from env
-
-// Cursors (key-value state)
-const lastId = jr.getCursor('email-poll', 'last_history_id');
-jr.setCursor('email-poll', 'last_history_id', newId);
-jr.setCursor('email-poll', `seen:${threadId}`, '1', { ttl: '30d' });
-jr.deleteCursor('email-poll', 'old_key');
-
-// Queues
-jr.enqueue('email-updates', { threadId, action: 'label' });
-const items = jr.dequeue('email-updates', 10); // claim up to 10
-jr.done(items[0].id);
-jr.fail(items[1].id, 'API error');
-
-jr.close();
-```
-
-## Job Lifecycle
-
-```
-Cron fires
-  → Check overlap policy (skip if running & policy = 'skip')
-  → INSERT run (status = 'running')
-  → spawn('node', [script], { env: JR_* })
-  → Capture stdout/stderr (ring buffer, last 100 lines)
-  → Parse JR_RESULT lines → extract tokens + result_meta
-  → On timeout: kill process, status = 'timeout', notify
-  → On exit 0: status = 'ok', notify if on_success configured
-  → On exit ≠ 0: status = 'error', notify if on_failure configured
-```
-
-### Overlap policies
-
-| Policy | Behavior |
-|--------|----------|
-| `skip` | Don't start if already running (default) |
-| `queue` | Wait for current run to finish, then start |
-| `allow` | Run concurrently |
-
-### Concurrency
-
-A global semaphore limits concurrent jobs (default: 4, configurable via `maxConcurrency`). When the limit is hit, behavior follows the job's overlap policy.
-
-### Notifications
-
-Slack notifications are sent via direct HTTP POST to `chat.postMessage` (no SDK dependency):
-
-- **Failure:** `⚠️ *Job Name* failed (12.3s): error message`
-- **Success:** `✅ *Job Name* completed (3.4s)`
-
-Notifications require a Slack bot token (file path in config). Each job can override the default notification channels.
-
-## Maintenance
-
-The runner automatically performs periodic maintenance:
-
-- **Run pruning:** Deletes run records older than `runRetentionDays` (default: 30).
-- **Cursor cleanup:** Deletes expired cursor entries (runs every `cursorCleanupIntervalMs`, default: 1 hour).
-
-Both tasks run on startup and at the configured interval.
-
-## Programmatic Usage
-
-```typescript
-import { createRunner, runnerConfigSchema } from '@karmaniverous/jeeves-runner';
-
-const config = runnerConfigSchema.parse({
-  port: 3100,
-  dbPath: './data/runner.sqlite',
-});
-
-const runner = createRunner(config);
-await runner.start();
-
-// Graceful shutdown
-process.on('SIGTERM', () => runner.stop());
-```
-
-## Configuration Reference
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `port` | number | `3100` | HTTP API port |
-| `dbPath` | string | `./data/runner.sqlite` | SQLite database path |
-| `maxConcurrency` | number | `4` | Max concurrent jobs |
-| `runRetentionDays` | number | `30` | Days to keep run history |
-| `cursorCleanupIntervalMs` | number | `3600000` | Cursor cleanup interval (ms) |
-| `shutdownGraceMs` | number | `30000` | Grace period for running jobs on shutdown |
-| `notifications.slackTokenPath` | string | — | Path to Slack bot token file |
-| `notifications.defaultOnFailure` | string \| null | `null` | Default Slack channel for failures |
-| `notifications.defaultOnSuccess` | string \| null | `null` | Default Slack channel for successes |
-| `log.level` | string | `info` | Log level (trace/debug/info/warn/error/fatal) |
-| `log.file` | string | — | Log file path (stdout if omitted) |
-
-## The Jeeves Platform
-
-jeeves-runner is one component of a four-part platform:
-
-| Component | Role | Status |
-|-----------|------|--------|
-| **jeeves-runner** | Execute: run processes, move data through the graph | This package |
-| **[jeeves-watcher](https://github.com/karmaniverous/jeeves-watcher)** | Index: observe file-backed datastores, embed in Qdrant | Shipped |
-| **jeeves-server** | Present: UI, API, file serving, search, dashboards | Shipped |
-| **Jeeves skill** | Converse: configure, operate, and query via chat | Planned |
-
-## Project Status
-
-**Phase 1** (current): Replicate existing job scheduling and status reporting. Replace n8n and the Notion Process Dashboard.
-
-### What's built
-
-- ✅ SQLite schema (jobs, runs, cursors, queues)
-- ✅ Cron scheduler with overlap policies and concurrency limits
-- ✅ Job executor with output capture, timeout enforcement, and `JR_RESULT` parsing
-- ✅ Client library for cursor/queue operations from job scripts
-- ✅ Slack notifications for job success/failure
-- ✅ REST API (Fastify) for job management and monitoring
-- ✅ CLI for daemon management and job operations
-- ✅ Maintenance tasks (run pruning, cursor cleanup)
-- ✅ Zod-validated configuration
-- ✅ Seed script for 27 existing n8n workflows
-- ✅ 75 passing tests
-
-### What's next (Phase 1 remaining)
-
-- [ ] NSSM service setup
-- [ ] jeeves-server dashboard page (`/runner`)
-- [ ] Migrate jobs from n8n one by one
-- [ ] Retire n8n
-
-### Future phases
-
-| Feature | Phase |
-|---------|-------|
-| Graph topology (nodes/edges schema) | 2 |
-| Credential/auth management | 2 |
-| REST API for graph mutations | 2 |
-| OpenClaw plugin & Jeeves skill | 3 |
-| Container packaging | 3 |
-
-## Development
-
-```bash
-npm install
-npx lefthook install
-
-npm run lint        # ESLint + Prettier
-npm run test        # Vitest
-npm run knip        # Unused code detection
-npm run build       # Rollup (ESM + types + CLI)
-npm run typecheck   # TypeScript (noEmit)
-```
-
-## License
-
-BSD-3-Clause