openclaw-scheduler 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.4] -- 2026-04-18
+
+### Fixed
+- fix(package): include dispatch/completion.mjs in the published npm tarball so dispatch CLI and watcher startup no longer crash with ERR_MODULE_NOT_FOUND in installed deployments
+
+## [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/dispatch/completion.mjs

@@ -0,0 +1,135 @@
+const GENERIC_COMPLETION_TEXT_RE = /^(?:completed(?:\s*\([^\n)]*\))?|done|ok|okay|success|successful|complete|all set|none|n\/?a)$/i;
+const TRIVIAL_CHATTER_RE = /^(?:hi|hello|hey|yo|sup|thanks|thank you|cool|nice|sure|yep|yeah|k|kk|roger|copy that)[.!?]*$/i;
+
+export function normalizeCompletionText(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+export function isMeaningfulCompletionText(value) {
+  const text = normalizeCompletionText(value);
+  if (!text) return false;
+
+  const normalized = text.toLowerCase().replace(/\s+/g, ' ').trim();
+  if (!normalized) return false;
+  if (GENERIC_COMPLETION_TEXT_RE.test(normalized)) return false;
+  if (TRIVIAL_CHATTER_RE.test(normalized)) return false;
+
+  const words = normalized.split(/\s+/).filter(Boolean);
+  if (words.length === 1) return false;
+
+  return true;
+}
+
+function shortSha(sha) {
+  const text = normalizeCompletionText(sha);
+  if (!text) return null;
+  return /^[0-9a-f]{7,40}$/i.test(text) ? text.slice(0, 7) : text;
+}
+
+function cloneChecklist(checklist) {
+  if (!checklist || typeof checklist !== 'object' || Array.isArray(checklist)) return null;
+  try {
+    return JSON.parse(JSON.stringify(checklist));
+  } catch {
+    return { ...checklist };
+  }
+}
+
+export function synthesizeCompletionReply({ checklist, sha } = {}) {
+  const normalizedChecklist = cloneChecklist(checklist);
+  const short = shortSha(sha);
+  const sentences = [];
+
+  if (normalizedChecklist?.tests_passed === true) {
+    sentences.push('Tests passed.');
+  }
+
+  if (normalizedChecklist?.pushed === true && short) {
+    sentences.push(`Pushed ${short}.`);
+  } else if (normalizedChecklist?.pushed === true) {
+    sentences.push('Changes pushed.');
+  } else if (short) {
+    sentences.push(`Commit ${short}.`);
+  }
+
+  const extraTrueFlags = normalizedChecklist
+    ? Object.entries(normalizedChecklist)
+      .filter(([key, value]) => value === true && !['work_complete', 'tests_passed', 'pushed'].includes(key))
+      .map(([key]) => key.replace(/_/g, ' '))
+    : [];
+
+  if (extraTrueFlags.length > 0) {
+    sentences.push(`Checks: ${extraTrueFlags.slice(0, 3).join(', ')}.`);
+  }
+
+  if (sentences.length === 0) return null;
+  return `Work complete. ${sentences.join(' ')}`.trim();
+}
+
+export function buildTerminalCompletionPayload({ summary, checklist, sha } = {}) {
+  const rawSummary = normalizeCompletionText(summary);
+  const normalizedChecklist = cloneChecklist(checklist);
+  const normalizedSha = normalizeCompletionText(sha);
+  const prose = isMeaningfulCompletionText(rawSummary) ? rawSummary : null;
+  const synthesizedReply = prose
+    ? null
+    : synthesizeCompletionReply({ checklist: normalizedChecklist, sha: normalizedSha });
+  const effectiveSummary = prose || synthesizedReply || rawSummary || null;
+  const deliveryText = prose || synthesizedReply || null;
+
+  return {
+    version: 1,
+    recordedAt: new Date().toISOString(),
+    summary: effectiveSummary,
+    deliveryText,
+    prose,
+    checklist: normalizedChecklist,
+    sha: normalizedSha,
+    debug: {
+      rawSummary,
+      synthesizedReply,
+      deliverySource: prose ? 'summary' : synthesizedReply ? 'synthesized' : 'none',
+    },
+  };
+}
+
+export function resolveCompletionDelivery({ lastReply, completion, fallbackSummary } = {}) {
+  const reply = normalizeCompletionText(lastReply);
+  const completionSummary = normalizeCompletionText(completion?.summary);
+  const completionDelivery = normalizeCompletionText(completion?.deliveryText);
+  const fallback = normalizeCompletionText(fallbackSummary);
+  const preferredSummary = completionSummary || fallback;
+  const meaningfulSummary = [completionSummary, fallback].find(isMeaningfulCompletionText) || null;
+
+  if (isMeaningfulCompletionText(reply)) {
+    return {
+      deliveryText: reply,
+      summary: preferredSummary || reply.slice(0, 500),
+      source: 'lastReply',
+    };
+  }
+
+  if (isMeaningfulCompletionText(completionDelivery)) {
+    return {
+      deliveryText: completionDelivery,
+      summary: completionSummary || completionDelivery,
+      source: completion?.debug?.deliverySource || 'completion',
+    };
+  }
+
+  if (meaningfulSummary) {
+    return {
+      deliveryText: meaningfulSummary,
+      summary: meaningfulSummary,
+      source: completionSummary && meaningfulSummary === completionSummary ? 'completion-summary' : 'summary',
+    };
+  }
+
+  return {
+    deliveryText: null,
+    summary: preferredSummary || null,
+    source: 'none',
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-scheduler",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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",
@@ -37,6 +37,7 @@
   "files": [
     "bin",
     "dispatch/529-recovery.mjs",
+    "dispatch/completion.mjs",
     "dispatch/config.example.json",
     "dispatch/deliver-watcher.sh",
     "dispatch/hooks.mjs",