openclaw-scheduler 0.2.8 → 0.2.10

package/CHANGELOG.md

@@ -75,6 +75,7 @@ All notable changes to this project will be documented in this file.
 - feat: x-openclaw-env-inject header for agent task credentials (PR #5)
 - feat: [IMAGE:path] marker protocol for shell job image attachments
 - feat: auto-delete watcher and watchdog jobs after completion (delete_after_run)
+- feat(jobs): add durable payload_model_fallback/auth_profile_fallback fields with same-run fallback retry
 - feat: enforce delivery_to as required field on job INSERT
 - feat: multi-platform CI (Linux, macOS, Windows)
 - docs: trust architecture, multi-agent gateway routing, agent adoption files

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 >= 22 | `node --version` (use full path if needed: `/opt/homebrew/bin/node --version`) |
+| Node.js 22 LTS, 24 LTS, or 26 Current | `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 >= 22 | Install via [nvm](https://github.com/nvm-sh/nvm) or [NodeSource](https://github.com/nodesource/distributions) |
+| Node.js 22 LTS, 24 LTS, or 26 Current | 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 >= 22 | [nodejs.org](https://nodejs.org) -- use the LTS installer |
+| Node.js 22 LTS, 24 LTS, or 26 Current | [nodejs.org](https://nodejs.org) -- use an installer for one of the supported versions |
 | 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 >= 22 | `node --version` |
+| Node.js 22 LTS, 24 LTS, or 26 Current | `node --version` |
 | OpenClaw gateway running | With auth token |
 | Git or SCP access | To clone/copy the repo |
 

package/JOB-QUICK-REF.md

@@ -196,6 +196,8 @@ openclaw-scheduler jobs reject <id> "not ready yet"
 | `payload_kind` | string | yes | `shellCommand`, `systemEvent`, or `agentTurn` |
 | `payload_message` | string | yes | Shell command or agent prompt |
 | `payload_model` | string | no | Model override for agent tasks |
+| `payload_model_fallback` | string | no | Optional fallback model override for same-run retry after primary selection failure |
+| `auth_profile_fallback` | string | no | Optional fallback auth profile for same-run retry after primary selection failure |
 | `run_timeout_ms` | integer | yes | Max run duration in ms (no default) |
 | `delivery_mode` | string | no | `none`, `announce`, `announce-always` |
 | `delivery_channel` | string | no | Channel name (telegram, discord, etc.) |

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%A522-green)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-22%20%7C%2024%20%7C%2026-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 22+ (ESM), SQLite via `better-sqlite3`, cron parsing via `croner`
+**Runtime:** Node.js 22 LTS, 24 LTS, or 26 Current (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 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`.
+GitHub Actions runs the smoke gate plus the in-memory test suite on Linux and macOS with the supported Node.js lines: Node 22, Node 24, and Node 26. Publishing uses Node 24 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)
 
@@ -1255,14 +1255,14 @@ openclaw-scheduler agents register <id> [name]
 ```
 id, name, enabled, schedule_kind, schedule_cron, schedule_at, schedule_tz,
 session_target, agent_id, payload_kind, payload_message,
-payload_model, payload_thinking, execution_intent, execution_read_only,
+payload_model, payload_model_fallback, payload_thinking, execution_intent, execution_read_only,
 overlap_policy, run_timeout_ms, max_queued_dispatches, max_pending_approvals,
 max_trigger_fanout, output_store_limit_bytes, output_excerpt_limit_bytes,
 output_summary_limit_bytes, output_offload_threshold_bytes,
 max_retries, delivery_mode, delivery_channel,
 delivery_to, delivery_guarantee, delete_after_run, ttl_hours,
 parent_id, trigger_on, trigger_delay_s, trigger_condition,
-resource_pool, auth_profile,
+resource_pool, auth_profile, auth_profile_fallback,
 approval_required, approval_timeout_s, approval_auto,
 context_retrieval, context_retrieval_limit,
 preferred_session_key, job_type, watchdog_target_label,

package/cli.js

@@ -271,19 +271,23 @@ switch (command) {
         const isWatchdog = args.includes('--watchdog');
         const profileIdx = args.indexOf('--profile');
         const profileValue = profileIdx >= 0 ? args[profileIdx + 1] : undefined;
+        const fallbackProfileIdx = args.indexOf('--fallback-profile');
+        const fallbackProfileValue = fallbackProfileIdx >= 0 ? args[fallbackProfileIdx + 1] : undefined;
         const atIdx = args.indexOf('--at');
         const atValue = atIdx >= 0 ? args[atIdx + 1] : undefined;
         const inIdx = args.indexOf('--in');
         const inValue = inIdx >= 0 ? args[inIdx + 1] : undefined;
         const skipArgs = new Set(['--dry-run', '--watchdog']);
         if (profileIdx >= 0) { skipArgs.add(args[profileIdx]); skipArgs.add(args[profileIdx + 1]); }
+        if (fallbackProfileIdx >= 0) { skipArgs.add(args[fallbackProfileIdx]); skipArgs.add(args[fallbackProfileIdx + 1]); }
         if (atIdx >= 0) { skipArgs.add(args[atIdx]); skipArgs.add(args[atIdx + 1]); }
         if (inIdx >= 0) { skipArgs.add(args[inIdx]); skipArgs.add(args[inIdx + 1]); }
         const payload = args.find(a => !skipArgs.has(a));
-        if (!payload) fail('Usage: jobs add <json> [--dry-run] [--watchdog] [--at <datetime>] [--in <duration>] [--profile <id>]');
+        if (!payload) fail('Usage: jobs add <json> [--dry-run] [--watchdog] [--at <datetime>] [--in <duration>] [--profile <id>] [--fallback-profile <id>]');
         let spec;
         try { spec = JSON.parse(payload); } catch { fail('Invalid JSON. Usage: jobs add \'{"name":"..."}\''); }
         if (profileValue !== undefined) spec.auth_profile = profileValue;
+        if (fallbackProfileValue !== undefined) spec.auth_profile_fallback = fallbackProfileValue;
 
         // One-shot scheduling via --at or --in
         if (atValue || inValue) {
@@ -351,14 +355,18 @@ switch (command) {
         const dryRun = args.includes('--dry-run');
         const updateProfileIdx = args.indexOf('--profile');
         const updateProfileValue = updateProfileIdx >= 0 ? args[updateProfileIdx + 1] : undefined;
+        const updateFallbackProfileIdx = args.indexOf('--fallback-profile');
+        const updateFallbackProfileValue = updateFallbackProfileIdx >= 0 ? args[updateFallbackProfileIdx + 1] : undefined;
         const updateFilterArgs = new Set(['--dry-run']);
         if (updateProfileIdx >= 0) { updateFilterArgs.add(args[updateProfileIdx]); updateFilterArgs.add(args[updateProfileIdx + 1]); }
+        if (updateFallbackProfileIdx >= 0) { updateFilterArgs.add(args[updateFallbackProfileIdx]); updateFilterArgs.add(args[updateFallbackProfileIdx + 1]); }
         const updateArgs = args.filter(a => !updateFilterArgs.has(a));
         const current = getJob(updateArgs[0]);
         if (!current) fail(`Job not found: ${updateArgs[0]}`);
         let patch;
         try { patch = JSON.parse(updateArgs[1]); } catch { fail('Invalid JSON. Usage: jobs update <id> \'{"key":"value"}\''); }
         if (updateProfileValue !== undefined) patch.auth_profile = updateProfileValue;
+        if (updateFallbackProfileValue !== undefined) patch.auth_profile_fallback = updateFallbackProfileValue;
         const normalized = validateJobSpec(patch, current, 'update');
         if (dryRun) {
           emit({ ok: true, dry_run: true, valid: true, normalized });

package/dispatch/529-recovery.mjs

@@ -19,13 +19,15 @@
  *   1 -- error
  */
 
-import { readFileSync, writeFileSync, renameSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs';
 import { execFileSync } from 'child_process';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { homedir } from 'os';
 import { resolveLabelsPath } from './paths.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const HOME_DIR = process.env.HOME || homedir();
 const LABELS_PATH = resolveLabelsPath({ legacyCandidates: [join(__dirname, 'labels.json')] });
 const INDEX_PATH  = process.env.DISPATCH_INDEX_PATH  || join(__dirname, 'index.mjs');
 
@@ -64,9 +66,26 @@ function saveLabels(labels) {
   renameSync(tmp, LABELS_PATH);
 }
 
+function resolveSchedulerCliPath() {
+  const candidates = [
+    process.env.OPENCLAW_SCHEDULER_CLI,
+    process.env.SCHEDULER_CLI,
+    join(__dirname, '..', 'cli.js'),
+    join(HOME_DIR, '.openclaw', 'packages', 'openclaw-scheduler', 'node_modules', 'openclaw-scheduler', 'cli.js'),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    try {
+      if (existsSync(candidate)) return candidate;
+    } catch {}
+  }
+
+  return join(__dirname, '..', 'cli.js');
+}
+
 function notify(message) {
   try {
-    const cliPath = join(__dirname, '..', 'cli.js');
+    const cliPath = resolveSchedulerCliPath();
     execFileSync(process.execPath, [cliPath, 'msg', 'send', 'scheduler', 'main', message], {
       encoding: 'utf-8',
       timeout: 10000,

package/dispatch/completion.mjs

@@ -39,6 +39,7 @@ const HUMAN_SUMMARY_SECTION_RE = /(?:^|\n)\s*(?:Human-readable summary|Human sum
 const TECHNICAL_DETAILS_SECTION_RE = /(?:^|\n)\s*(?:Technical details?|Details(?:_technical)?)\s*:\s*/i;
 const HUMAN_SUMMARY_LABEL_RE = /^(?:human-readable summary|human summary)\s*:\s*/i;
 const TECHNICAL_DETAILS_LABEL_RE = /^(?:technical details?|details(?:_technical)?)\s*:\s*/i;
+const FORMATTER_META_SUMMARY_RE = /^Final completion updates now (?:start with a short plain-English summary|arrive as one clean plain-English summary)\./i;
 const FINAL_REPORT_HEADING_RE = /^(?:#{1,6}\s*)?(?:root cause|files? changed|changes|validation|tests?(?: run| passed)?|sacrificial(?: delivery)?(?: result)?|deployment(?:\/live-runtime)?(?: step)?|live-runtime(?: step)?|result|results|summary|highlights?|notes?|follow[- ]ups?|next steps?|blockers?|implementation|what changed|verification)\s*:?$/i;
 const FINAL_REPORT_CUE_RE = /\b(?:root cause|files? changed|tests? run|validation|sacrificial(?: delivery)?(?: result)?|deployment(?:\/live-runtime)?(?: step)?|live-runtime(?: step)?|final report|human-readable report|files changed|tests passed)\b/i;
 
@@ -751,6 +752,42 @@ function buildCompletionLeadFromThemes(themes) {
   return truncateText(sentences.join(' '), MAX_DELIVERY_CHARS);
 }
 
+function looksLikeFormatterMetaSummary(text) {
+  const normalized = normalizeCompletionText(text);
+  return Boolean(normalized && FORMATTER_META_SUMMARY_RE.test(normalized));
+}
+
+function getCompletionRawSummary(completion) {
+  const details = getCompletionTechnicalDetails(completion);
+  if (!details || typeof details !== 'object') return null;
+  return normalizeCompletionText(details.raw_summary ?? details.rawSummary);
+}
+
+function looksLikeCompletionFormatterImplementation(text) {
+  const normalized = normalizeCompletionText(text);
+  if (!normalized) return false;
+
+  const fragments = extractTechnicalFragments(normalized);
+  const themes = detectTechnicalThemes(normalized, fragments);
+  if (!themes.completionFlow) return false;
+
+  return TECHNICAL_COMMIT_PREFIX_RE.test(cleanMarkdown(normalized).replace(/\s+/g, ' ').trim())
+    || /\b(?:completion|deliveryText|summary_human|summaryHuman|details_technical|resolveCompletionDelivery|buildTerminalCompletionPayload|payload-precedence|watcher path|completion watcher|final completion updates?)\b/i.test(normalized);
+}
+
+function getRawSummaryOverrideForFormatterMeta(completion, structuredTexts) {
+  if (!structuredTexts.some(looksLikeFormatterMetaSummary)) return null;
+
+  const rawSummary = getCompletionRawSummary(completion);
+  if (!rawSummary) return null;
+  if (isGenericOrTrivial(rawSummary)) return null;
+  if (isInternalTransportNoiseText(rawSummary)) return null;
+  if (looksLikeRawPayloadText(rawSummary)) return null;
+  if (looksLikeCompletionFormatterImplementation(rawSummary)) return null;
+
+  return truncateText(rawSummary, MAX_DELIVERY_CHARS);
+}
+
 function buildHumanizedTechnicalSummary(rawText, fallbackSummary) {
   const cleanedRaw = normalizeCompletionText(rawText);
   const fallback = normalizeCompletionText(fallbackSummary);
@@ -1306,6 +1343,18 @@ export function resolveCompletionDelivery({ lastReply, completion, fallbackSumma
   const authoritativeStructuredSummary = completionDeliverySource && completionDeliverySource !== 'technical-synthesis'
     ? preferredSummary
     : null;
+  const rawSummaryOverride = getRawSummaryOverrideForFormatterMeta(completion, [
+    rawCompletionSummaryHuman,
+    rawCompletionSummary,
+    rawCompletionDelivery,
+  ]);
+  if (rawSummaryOverride) {
+    return {
+      deliveryText: rawSummaryOverride,
+      summary: rawSummaryOverride,
+      source: 'raw-summary',
+    };
+  }
   const noisyTexts = [
     rawReply,
     rawCompletionSummaryHuman,

package/dispatch/index.mjs

@@ -123,6 +123,86 @@ function sleep(ms) {
   return new Promise(r => setTimeout(r, ms));
 }
 
+function deployedSchedulerDispatchPath(fileName) {
+  return join(
+    HOME_DIR,
+    '.openclaw',
+    'packages',
+    'openclaw-scheduler',
+    'node_modules',
+    'openclaw-scheduler',
+    'dispatch',
+    fileName,
+  );
+}
+
+function resolveSchedulerCliPath() {
+  const candidates = [
+    process.env.OPENCLAW_SCHEDULER_CLI,
+    process.env.SCHEDULER_CLI,
+    join(__dirname, '..', 'cli.js'),
+    join(HOME_DIR, '.openclaw', 'packages', 'openclaw-scheduler', 'node_modules', 'openclaw-scheduler', 'cli.js'),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    try {
+      if (existsSync(candidate)) return candidate;
+    } catch {}
+  }
+
+  return join(__dirname, '..', 'cli.js');
+}
+
+function currentDirLooksLikeBrandWrapper() {
+  return !existsSync(join(__dirname, '..', 'cli.js'));
+}
+
+function resolveDispatchScriptPath(fileName) {
+  const localPath = join(__dirname, fileName);
+  const deployedPath = deployedSchedulerDispatchPath(fileName);
+  const preferDeployed = currentDirLooksLikeBrandWrapper();
+  const candidates = [
+    fileName === 'index.mjs' ? process.env.DISPATCH_INDEX_PATH : null,
+    preferDeployed ? deployedPath : localPath,
+    preferDeployed ? localPath : deployedPath,
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    try {
+      if (existsSync(candidate)) return candidate;
+    } catch {}
+  }
+
+  return localPath;
+}
+
+function resolvePersistentNodePath() {
+  const explicit = process.env.OPENCLAW_NODE_PATH ||
+    process.env.OPENCLAW_NODE ||
+    process.env.NODE_BINARY;
+  if (explicit) return explicit;
+
+  const execPath = process.execPath || 'node';
+  const homebrewNode = execPath.startsWith('/opt/homebrew/')
+    ? '/opt/homebrew/bin/node'
+    : execPath.startsWith('/usr/local/')
+      ? '/usr/local/bin/node'
+      : null;
+  const isVersionedHomebrewPath = /\/(?:Cellar|opt)\/node(?:@[^/]+)?\//.test(execPath);
+
+  if (homebrewNode && isVersionedHomebrewPath) {
+    try {
+      if (existsSync(homebrewNode)) return homebrewNode;
+    } catch {}
+  }
+
+  return execPath;
+}
+
+function dispatchConfigDirForChild() {
+  return process.env.DISPATCH_CONFIG_DIR || INVOKE_DIR;
+}
+
 function toTimestampMs(value) {
   if (value == null) return null;
   if (typeof value === 'number') {
@@ -559,6 +639,62 @@ function agentFromSessionKey(sessionKey) {
   return 'main';
 }
 
+function getSessionJsonlMtimeMs(agent, sessionId) {
+  const jsonlPath = getSessionJsonlPath(agent, sessionId);
+  if (!jsonlPath) return null;
+  try {
+    return statSync(jsonlPath).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function getJsonlPendingToolReason(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  const last = entries[entries.length - 1];
+
+  if (last?.role === 'assistant') {
+    const content = Array.isArray(last.content) ? last.content : [];
+    const toolUse = content.find(c => c?.type === 'tool_use');
+    if (toolUse) {
+      return `last assistant entry has tool_use (${toolUse.name || 'unknown'}) -- awaiting tool result`;
+    }
+    if (last.type === 'tool_use') {
+      return `last entry is tool_use (${last.name || 'unknown'}) -- awaiting tool result`;
+    }
+  }
+
+  if (last?.role === 'user') {
+    const content = Array.isArray(last.content) ? last.content : [];
+    if (content.some(c => c?.type === 'tool_result')) {
+      return 'last entry is tool_result (tool executed, awaiting assistant reply)';
+    }
+  }
+
+  if (last?.type === 'tool_result') {
+    return 'last entry is tool_result (tool executed, awaiting assistant reply)';
+  }
+
+  return null;
+}
+
+function getJsonlTerminalReplyReason(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  const terminalReply = extractTerminalAssistantReplyFromEntries(entries);
+  if (!terminalReply) return null;
+
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry?.role === 'assistant') {
+      return entry.stop_reason === 'end_turn'
+        ? 'terminal assistant reply observed in JSONL'
+        : null;
+    }
+  }
+
+  return null;
+}
+
 // -- Gateway Session State Check ------------------------------
 
 /**
@@ -647,9 +783,35 @@ function checkSessionDone(sessionKey, sessionsStore, thresholdMs, sessionEverFou
   }
 
   // 2. Session exists in store, check idle time.
-  const entry        = sessionsStore[sessionKey];
-  const lastActivity = entry.updatedAt || 0;
-  const silenceMs    = Date.now() - lastActivity;
+  const entry = sessionsStore[sessionKey];
+  const agent = agentFromSessionKey(sessionKey) || 'main';
+  const updatedAtMs = toTimestampMs(entry.updatedAt);
+  const lastActivityAtMs = toTimestampMs(entry.lastActivityAt);
+  const jsonlMtimeMs = getSessionJsonlMtimeMs(agent, entry.sessionId);
+  const activityTimes = [updatedAtMs, lastActivityAtMs, jsonlMtimeMs].filter(t => typeof t === 'number');
+  const lastActivity = activityTimes.length ? Math.max(...activityTimes) : null;
+  const silenceMs = lastActivity === null ? Infinity : Date.now() - lastActivity;
+
+  if (entry.sessionId) {
+    const entries = readJsonlTailEntries(entry.sessionId, agent, 20);
+    const pendingToolReason = getJsonlPendingToolReason(entries);
+    if (pendingToolReason) {
+      return {
+        shouldResolve: false,
+        reason:       `session JSONL shows pending work: ${pendingToolReason}`,
+        lastActivity,
+      };
+    }
+
+    const terminalReplyReason = getJsonlTerminalReplyReason(entries);
+    if (terminalReplyReason) {
+      return {
+        shouldResolve: false,
+        reason:       `${terminalReplyReason}; watcher/result path should deliver completion`,
+        lastActivity,
+      };
+    }
+  }
 
   if (silenceMs >= thresholdMs) {
     return {
@@ -681,7 +843,7 @@ function disarmWatchdog(label) {
   const entry = getLabel(label);
   if (!entry?.watchdogJobId) return;
   try {
-    const schedulerCli = join(__dirname, '..', 'cli.js');
+    const schedulerCli = resolveSchedulerCliPath();
     execFileSync(process.execPath, [schedulerCli, 'jobs', 'delete', entry.watchdogJobId], {
       encoding: 'utf-8',
       timeout:  5000,
@@ -715,15 +877,18 @@ function scheduleDeliveryWatcherJob({
   if (!label) throw new Error('label is required');
   if (!deliverTo) throw new Error('deliverTo is required');
 
-  const schedulerCli = join(__dirname, '..', 'cli.js');
-  const watcherPath = join(__dirname, 'watcher.mjs');
+  const schedulerCli = resolveSchedulerCliPath();
+  const watcherPath = resolveDispatchScriptPath('watcher.mjs');
+  const dispatchIndexPath = resolveDispatchScriptPath('index.mjs');
+  const nodePath = resolvePersistentNodePath();
   const watcherTimeoutS = Number(timeoutSeconds) + 120;
   const idleThresholdS = Number(idleThresholdSeconds) || 300;
   const sq = quoteForSingleQuotedShell;
   const watcherCmd =
+    `DISPATCH_CONFIG_DIR='${sq(dispatchConfigDirForChild())}' ` +
     `DISPATCH_LABELS_PATH='${sq(LABELS_PATH)}' ` +
-    `DISPATCH_INDEX_PATH='${sq(join(__dirname, 'index.mjs'))}' ` +
-    `'${sq(process.execPath)}' '${sq(watcherPath)}' ` +
+    `DISPATCH_INDEX_PATH='${sq(dispatchIndexPath)}' ` +
+    `'${sq(nodePath)}' '${sq(watcherPath)}' ` +
     `--label '${sq(label)}' --timeout ${watcherTimeoutS} ` +
     `--poll-interval 20 --idle-threshold ${idleThresholdS} --once`;
 
@@ -962,7 +1127,7 @@ async function cmdEnqueue(flags) {
   // -- Checkpoint notify command (mid-run status messages) -----
   // Agents can call this command at logical checkpoints to send status updates
   // that will be delivered to the inbox consumer (and ultimately Telegram).
-  const schedulerCliPath = join(__dirname, '..', 'cli.js');
+  const schedulerCliPath = resolveSchedulerCliPath();
   const checkpointNotifyCmd = `node '${schedulerCliPath}' messages send --from '${label.replace(/'/g, "'\\''")}' --to main --kind status --body`;
   // TODO: Inject CHECKPOINT_NOTIFY_CMD as an env var into the agent session so
   // agents can discover the checkpoint command programmatically (not just from
@@ -1142,7 +1307,10 @@ async function cmdEnqueue(flags) {
     let watchdogJobId = null;
     if (monitorEnabled && deliverTo) {
       try {
-        const checkCmd = `'${sq(process.execPath)}' '${sq(join(__dirname, 'index.mjs'))}' result --label '${sq(label)}'`;
+        const checkCmd =
+          `DISPATCH_CONFIG_DIR='${sq(dispatchConfigDirForChild())}' ` +
+          `DISPATCH_LABELS_PATH='${sq(LABELS_PATH)}' ` +
+          `'${sq(resolvePersistentNodePath())}' '${sq(resolveDispatchScriptPath('index.mjs'))}' result --label '${sq(label)}'`;
         const alertChannel = deliverChannel || 'telegram';
         const alertTarget  = deliverTo;
         const watchdogSpec = JSON.stringify({
@@ -1164,7 +1332,7 @@ async function cmdEnqueue(flags) {
           delete_after_run:         1,             // auto-delete after watchdog fires
           origin:                   origin || 'system',
         });
-        const schedulerCli = join(__dirname, '..', 'cli.js');
+        const schedulerCli = resolveSchedulerCliPath();
         const addResult = execFileSync(process.execPath, [schedulerCli, 'jobs', 'add', watchdogSpec, '--watchdog', '--json'], {
           encoding: 'utf-8',
           timeout:  10000,

package/dispatch/paths.mjs

@@ -0,0 +1,36 @@
+import { copyFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join, resolve as pathResolve } from 'path';
+import { homedir } from 'os';
+
+function schedulerHome() {
+  return process.env.OPENCLAW_SCHEDULER_HOME ||
+    join(process.env.HOME || homedir(), '.openclaw', 'scheduler');
+}
+
+export function resolveDispatchStateDir() {
+  return process.env.DISPATCH_STATE_DIR ||
+    join(schedulerHome(), 'dispatch');
+}
+
+export function resolveLabelsPath({ legacyCandidates = [] } = {}) {
+  if (process.env.DISPATCH_LABELS_PATH) {
+    mkdirSync(dirname(process.env.DISPATCH_LABELS_PATH), { recursive: true });
+    return process.env.DISPATCH_LABELS_PATH;
+  }
+
+  const labelsPath = join(resolveDispatchStateDir(), 'labels.json');
+  mkdirSync(dirname(labelsPath), { recursive: true });
+
+  if (!existsSync(labelsPath)) {
+    const normalizedTarget = pathResolve(labelsPath);
+    const legacyPath = legacyCandidates
+      .filter(Boolean)
+      .map((candidate) => pathResolve(candidate))
+      .find((candidate) => candidate !== normalizedTarget && existsSync(candidate));
+    if (legacyPath) {
+      copyFileSync(legacyPath, labelsPath);
+    }
+  }
+
+  return labelsPath;
+}