openclaw-scheduler 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.3] -- 2026-04-16
+
+### Fixed
+- fix(cli): harden runtime DB path resolution so installed package layouts prefer `~/.openclaw/scheduler/scheduler.db` instead of a repo-local checkout DB
+- fix(cli): refuse validation-only commands (`jobs validate`, `jobs add --dry-run`) when a source checkout detects an existing runtime DB mismatch
+- test(cli): add installed-package and repo/runtime mismatch coverage for DB path hardening
+
+### Changed
+- docs: bump minimum supported Node.js version from 20 to 22 to match the package engine requirement
+
 ## [0.2.2] -- 2026-04-15
 
 ### Fixed

package/INSTALL-ADDITIONAL-HOST.md

@@ -12,7 +12,7 @@ This guide is for setting up the scheduler on a **second or additional OpenClaw
 | Requirement | Notes |
 |-------------|-------|
 | macOS or Linux | Tested on macOS arm64 |
-| Node.js >= 20 | `node --version` (use full path if needed: `/opt/homebrew/bin/node --version`) |
+| Node.js >= 22 | `node --version` (use full path if needed: `/opt/homebrew/bin/node --version`) |
 | OpenClaw gateway running | With auth token |
 | Git or SCP access | To clone/copy the repo |
 

package/INSTALL-LINUX.md

@@ -12,7 +12,7 @@ Step-by-step guide to deploy the scheduler on a Linux host running OpenClaw.
 
 | Requirement | Notes |
 |-------------|-------|
-| Node.js >= 20 | Install via [nvm](https://github.com/nvm-sh/nvm) or [NodeSource](https://github.com/nodesource/distributions) |
+| Node.js >= 22 | Install via [nvm](https://github.com/nvm-sh/nvm) or [NodeSource](https://github.com/nodesource/distributions) |
 | build-essential | `sudo apt install build-essential python3` — required for `better-sqlite3` native compile |
 | OpenClaw gateway running | With auth token |
 | Git | `sudo apt install git` |

package/INSTALL-WINDOWS.md

@@ -38,7 +38,7 @@ Use this path only if you can't use WSL2 — for example, if OpenClaw itself is
 
 | Requirement | Install |
 |-------------|---------|
-| Node.js >= 20 | [nodejs.org](https://nodejs.org) -- use the LTS installer |
+| Node.js >= 22 | [nodejs.org](https://nodejs.org) -- use the LTS installer |
 | pm2 | `npm install -g pm2` |
 | OpenClaw gateway | Must be running with a valid auth token |
 | Git for Windows | [git-scm.com](https://git-scm.com) or use GitHub Desktop |

package/INSTALL.md

@@ -11,7 +11,7 @@ If you just want the fastest path to a working local install, start with the npm
 | Requirement | Notes |
 |-------------|-------|
 | macOS or Linux | Tested on macOS arm64 |
-| Node.js >= 20 | `node --version` |
+| Node.js >= 22 | `node --version` |
 | OpenClaw gateway running | With auth token |
 | Git or SCP access | To clone/copy the repo |
 

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/amittell/openclaw-scheduler/actions/workflows/ci.yml/badge.svg)](https://github.com/amittell/openclaw-scheduler/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-blue)]()
-[![Node](https://img.shields.io/badge/node-%E2%89%A520-green)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522-green)](https://nodejs.org)
 
 A durable orchestration runtime for [OpenClaw](https://openclaw.ai) agents and shell workflows. Use it when built-in cron and heartbeat stop being enough: jobs fail and disappear into logs, shell scripts depend on gateway uptime, multi-step workflows need retries and approvals, and you want a real audit trail for what ran, what failed, and what triggered what.
 
@@ -11,7 +11,7 @@ It replaces OpenClaw's built-in cron/heartbeat with a SQLite-backed scheduler th
 **Repo:** `github.com/amittell/openclaw-scheduler`
 **Default location:** `~/.openclaw/scheduler/`
 **Service:** `ai.openclaw.scheduler` (macOS launchd: LaunchAgent or LaunchDaemon)
-**Runtime:** Node.js 20+ (ESM), SQLite via `better-sqlite3`, cron parsing via `croner`
+**Runtime:** Node.js 22+ (ESM), SQLite via `better-sqlite3`, cron parsing via `croner`
 **Tests:** run with `npm test` (full suite, in-memory SQLite)
 **Platform:** macOS · Linux · Windows (WSL2)
 
@@ -204,7 +204,7 @@ npm run verify:local                 # full local maintainer gate
 npm run verify:smoke                 # lightweight smoke gate used by GitHub Actions
 ```
 
-GitHub Actions runs the smoke gate plus the in-memory test suite on Linux, macOS, and Windows with Node 20. The full release gate still runs locally via `npm run verify:local` and is enforced again by `prepublishOnly`.
+GitHub Actions runs the smoke gate plus the in-memory test suite on Linux and macOS with Node 22. Publishing uses Node 24 (npm 22+) for OIDC trusted publisher support. The full release gate still runs locally via `npm run verify:local` and is enforced again by `prepublishOnly`.
 
 ### Option C: local npm pack (simulate the published package from source)
 

package/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 // Scheduler CLI -- manage jobs, runs, messages, agents
-import { readFileSync } from 'fs';
-import { initDb, getDb } from './db.js';
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { initDb, getDb, getResolvedDbPath } from './db.js';
 import { createJob, getJob, listJobs, updateJob, deleteJob, cancelJob, runJobNow, validateJobSpec, parseInDuration, AT_JOB_CRON_SENTINEL } from './jobs.js';
 import { getRun, getRunsForJob, getRunningRuns, getStaleRuns, finishRun } from './runs.js';
 import {
@@ -9,14 +11,53 @@ import {
   ackMessage, listMessageReceipts, getTeamMessages,
 } from './messages.js';
 import { upsertAgent, getAgent, listAgents } from './agents.js';
+import { resolveSchedulerHome } from './paths.js';
 import { SCHEDULER_SCHEMAS } from './scheduler-schema.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
 const cliArgs = process.argv.slice(2);
 const jsonFlagIndex = cliArgs.indexOf('--json');
 const jsonMode = jsonFlagIndex >= 0;
 if (jsonFlagIndex >= 0) cliArgs.splice(jsonFlagIndex, 1);
 const [command, sub, ...args] = cliArgs;
 
+function firstNonEmpty(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : '';
+}
+
+function isNodeModulesInstall(moduleDir) {
+  return /[\\/]node_modules[\\/](?:@[^\\/]+[\\/])?openclaw-scheduler(?:[\\/]|$)/.test(moduleDir);
+}
+
+function isValidationOnlyCommand(cmd, subcommand, rest) {
+  return cmd === 'jobs' && (
+    subcommand === 'validate'
+    || (subcommand === 'add' && rest.includes('--dry-run'))
+  );
+}
+
+function getDbPathMismatchNotice(env = process.env) {
+  if (firstNonEmpty(env.SCHEDULER_DB)) return null;
+  if (isNodeModulesInstall(__dirname)) return null;
+
+  const repoDbPath = join(__dirname, 'scheduler.db');
+  const resolvedDbPath = getResolvedDbPath();
+  if (resolvedDbPath !== repoDbPath) return null;
+
+  const runtimeDbPath = join(resolveSchedulerHome(env), 'scheduler.db');
+  if (runtimeDbPath === resolvedDbPath) return null;
+  if (!existsSync(runtimeDbPath)) return null;
+
+  return { resolvedDbPath, runtimeDbPath };
+}
+
+function formatDbPathMismatchNotice({ resolvedDbPath, runtimeDbPath }, { validation = false } = {}) {
+  const prefix = validation ? 'Refusing to run validation.' : 'Warning: source checkout CLI is using a repo-local DB.';
+  return `${prefix} repo-local=${resolvedDbPath} runtime=${runtimeDbPath}. Re-run via the installed package CLI or set SCHEDULER_DB explicitly.`;
+}
+
 function usage() {
   console.log(`
 Usage: openclaw-scheduler <command> [subcommand] [options]
@@ -119,6 +160,14 @@ Capabilities:
 `);
 }
 
+const dbPathMismatchNotice = getDbPathMismatchNotice(process.env);
+if (dbPathMismatchNotice) {
+  if (isValidationOnlyCommand(command, sub, args)) {
+    fail(formatDbPathMismatchNotice(dbPathMismatchNotice, { validation: true }));
+  }
+  process.stderr.write(`${formatDbPathMismatchNotice(dbPathMismatchNotice)}\n`);
+}
+
 await initDb();
 
 function fmt(obj) { return JSON.stringify(obj, null, 2); }
@@ -953,6 +1002,7 @@ switch (command) {
   // -- Status ----------------------------------------------
   case 'status': {
     const db = getDb();
+    const dbPath = getResolvedDbPath();
     const jobs = listJobs();
     const runningRuns = getRunningRuns();
     const stale = getStaleRuns();
@@ -982,6 +1032,7 @@ switch (command) {
       .filter(j => j.enabled && j.next_run_at)
       .sort((a, b) => a.next_run_at.localeCompare(b.next_run_at))[0] || null;
     const payload = {
+      db_path: dbPath,
       jobs_total: jobs.length,
       jobs_enabled: jobs.filter(j => j.enabled).length,
       running_runs: runningRuns.length,
@@ -997,6 +1048,7 @@ switch (command) {
     };
     emit(payload, () => {
       console.log('=== OpenClaw Scheduler Status ===');
+      console.log(`DB:       ${dbPath}`);
       console.log(`Jobs:     ${jobs.length} total, ${jobs.filter(j => j.enabled).length} enabled`);
       console.log(`Running:  ${runningRuns.length}`);
       console.log(`Stale:    ${stale.length}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-scheduler",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "SQLite-backed job scheduler and workflow engine for OpenClaw agents",
   "type": "module",
   "main": "./index.js",
@@ -17,7 +17,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "start": "node dispatcher.js",