openclaw-scheduler 0.2.4 → 0.2.6

package/dispatcher-strategies.js

@@ -2,6 +2,8 @@
 // Strategy pattern for dispatchJob: each execution target returns a DispatchResult,
 // and finalizeDispatch processes it uniformly.
 
+import { fileURLToPath } from 'url';
+
 /**
  * DispatchResult shape (returned by every strategy):
  * {
@@ -50,6 +52,103 @@ function safeParse(str) {
   }
 }
 
+function shellSingleQuote(value) {
+  return "'" + String(value ?? '').replaceAll("'", "'\\''") + "'";
+}
+
+function parseStructuredWatchdogPayload(text) {
+  const direct = safeParse(text);
+  if (direct && typeof direct === 'object' && !Array.isArray(direct)) return direct;
+
+  const firstBrace = text.indexOf('{');
+  const lastBrace = text.lastIndexOf('}');
+  if (firstBrace === -1 || lastBrace <= firstBrace) return null;
+
+  const candidate = text.slice(firstBrace, lastBrace + 1);
+  const parsed = safeParse(candidate);
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+}
+
+const TERMINAL_WATCHDOG_STATUSES = new Set(['done', 'error', 'interrupted', 'spawn-warning']);
+
+function normalizeWatchdogText(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+function firstWatchdogText(...values) {
+  for (const value of values) {
+    const text = normalizeWatchdogText(value);
+    if (text) return text;
+  }
+  return null;
+}
+
+function resolveWatchdogTerminalPayload(stdout) {
+  const text = normalizeWatchdogText(stdout);
+  if (!text) return null;
+
+  const parsed = parseStructuredWatchdogPayload(text);
+  if (!parsed) return null;
+
+  const status = typeof parsed.status === 'string' ? parsed.status : null;
+  const terminal = parsed.terminal === true || (status ? TERMINAL_WATCHDOG_STATUSES.has(status) : false);
+  if (!terminal) return null;
+
+  const detail = firstWatchdogText(
+    parsed.deliveryText,
+    parsed.lastReply,
+    parsed.error,
+    parsed.summary,
+    parsed.completion?.deliveryText,
+    parsed.completion?.summary,
+  );
+
+  if (status && status !== 'done') {
+    return {
+      kind: 'failed',
+      detail: detail || `Task ended with status ${status}.`,
+    };
+  }
+
+  return {
+    kind: 'completed',
+    detail: detail || `Task reported terminal status ${status || 'done'}.`,
+  };
+}
+
+function buildFireAndForgetDeliveryInstruction(job) {
+  if (!job.delivery_mode || job.delivery_mode === 'none' || !job.delivery_channel || !job.delivery_to) {
+    return '';
+  }
+
+  const schedulerCliPath = fileURLToPath(new URL('./cli.js', import.meta.url));
+  const fromLabel = `scheduler-fire-and-forget:${job.id || job.name || 'job'}`;
+  const baseCmd = [
+    'node',
+    shellSingleQuote(schedulerCliPath),
+    'messages',
+    'send',
+    '--from', shellSingleQuote(fromLabel),
+    '--to', 'main',
+    '--channel', shellSingleQuote(job.delivery_channel),
+    '--delivery-to', shellSingleQuote(job.delivery_to),
+  ].join(' ');
+
+  return [
+    '\n[SYSTEM NOTE -- delivery]',
+    'When you have completed this task, queue the result through the scheduler post office.',
+    `Final result: ${baseCmd} --kind result --body "<final result>"`,
+    `Progress update: ${baseCmd} --kind status --body "<brief progress update>"`,
+    'Do NOT use the message tool, sessions_send, or any direct chat delivery.',
+    'The inbox consumer will deliver queued messages durably to the configured target.',
+    'Keep queued updates concise and actionable.',
+    'If there is nothing noteworthy to report, do not queue a message.',
+    '[END SYSTEM NOTE]\n',
+  ].join('\n');
+}
+
 function getIdentityTrustLevel(identity) {
   if (!identity || typeof identity !== 'object') return null;
   return identity.trust_level
@@ -850,16 +949,29 @@ export async function executeWatchdog(job, ctx, deps) {
     if (elapsedMin >= job.watchdog_timeout_min) timedOut = true;
   }
 
+  const terminalPayload = resolveWatchdogTerminalPayload(stdout);
+
   if (exitCode === 2) {
     result.summary = `Watchdog check failed (transient): ${stderr || stdout}`;
     result.skipDelivery = true;
     log('debug', `Watchdog check transient failure: ${job.name}`, { exitCode, stderr: stderr.slice(0, 200) });
 
-  } else if (exitCode === 0 && stdout) {
-    const completionMsg = `\u2705 [watchdog] Task "${job.watchdog_target_label}" completed -- watchdog disarmed`;
+  } else if (exitCode === 0 && terminalPayload) {
+    const completionMsg = terminalPayload.kind === 'failed'
+      ? [
+        `⚠️ [watchdog] Task "${job.watchdog_target_label}" ended with failure -- watchdog disarmed`,
+        terminalPayload.detail ? `Details: ${terminalPayload.detail}` : null,
+      ].filter(Boolean).join('\n')
+      : [
+        `\u2705 [watchdog] Task "${job.watchdog_target_label}" completed -- watchdog disarmed`,
+        terminalPayload.detail || null,
+      ].filter(Boolean).join('\n\n');
     result.summary = completionMsg;
     result.content = completionMsg;
-    log('info', `Watchdog: target completed: ${job.watchdog_target_label}`, { jobId: job.id });
+    log(terminalPayload.kind === 'failed' ? 'warn' : 'info', `Watchdog: target terminal: ${job.watchdog_target_label}`, {
+      jobId: job.id,
+      terminalKind: terminalPayload.kind,
+    });
 
     if (job.watchdog_alert_channel && job.watchdog_alert_target) {
       await handleDelivery({
@@ -909,10 +1021,12 @@ export async function executeWatchdog(job, ctx, deps) {
     result.skipDelivery = true;
 
   } else if (exitCode === 0) {
-    result.summary = `Watchdog check: target still running (${elapsedMin}min elapsed)`;
+    result.summary = stdout
+      ? `Watchdog check returned non-terminal output; target still running (${elapsedMin}min elapsed)`
+      : `Watchdog check: target still running (${elapsedMin}min elapsed)`;
     result.skipDelivery = true;
     log('debug', `Watchdog: target still running: ${job.watchdog_target_label}`, {
-      jobId: job.id, elapsedMin,
+      jobId: job.id, elapsedMin, sawStdout: Boolean(stdout),
     });
   } else {
     result.summary = `Watchdog check command returned unexpected exit code ${exitCode}`;
@@ -963,27 +1077,14 @@ export async function executeMain(job, ctx, deps) {
     ? `[SYSTEM NOTE -- model policy]\nPrefer reasoning depth: ${job.payload_thinking}.\n[END SYSTEM NOTE]\n\n`
     : '';
 
-  // Build the delivery reply-to instruction so the agent can send results
-  // back through the scheduler post office when it finishes processing.
-  let deliveryInstruction = '';
-  if (job.delivery_mode && job.delivery_mode !== 'none' && job.delivery_channel && job.delivery_to) {
-    deliveryInstruction = [
-      '\n[SYSTEM NOTE -- delivery]',
-      `When you have completed this task, send your results using the message tool.`,
-      `Channel: ${job.delivery_channel}`,
-      `Target: ${job.delivery_to}`,
-      `Keep the message concise and actionable.`,
-      `If there is nothing noteworthy to report, do not send a message.`,
-      '[END SYSTEM NOTE]\n',
-    ].join('\n');
-  }
+  const deliveryInstruction = buildFireAndForgetDeliveryInstruction(job);
 
   const prompt = `${executionNote ? `${executionNote}\n\n` : ''}${modelNote}${deliveryInstruction}${job.payload_message}`;
   await sendSystemEvent(prompt, 'now');
 
   result.summary = 'System event dispatched (fire-and-forget)';
   result.content = job.payload_message;
-  result.skipDelivery = true; // Agent handles delivery via message tool
+  result.skipDelivery = true; // Async completion is queued through the scheduler post office
   result.skipChildren = true;
   result.skipDequeue = true;
 
@@ -994,6 +1095,25 @@ export async function executeMain(job, ctx, deps) {
 
 // -- Strategy: Shell -----------------------------------------
 
+function isCompletionDeliveryWatcherJob(job) {
+  return /^(?:dispatch|chilisaus)-deliver:/.test(String(job?.name || ''));
+}
+
+function isCompletionWatcherPendingTick(shellResult) {
+  return !(shellResult.stdout || '').trim()
+    && /\bWATCHER_PENDING\b/.test(shellResult.stderr || '');
+}
+
+function buildCompletionWatcherNoPayloadMessage(job, shellResult) {
+  const statusLabel = shellResult.status === 'ok'
+    ? 'completed without a deliverable result'
+    : `failed before producing a deliverable result${shellResult.errorMessage ? ` (${shellResult.errorMessage})` : ''}`;
+  return [
+    `⚠️ Completion delivery watcher for ${job.name} ${statusLabel}.`,
+    'No internal diagnostics were delivered as the completion message; check the scheduler run logs for stderr/details.',
+  ].join('\n');
+}
+
 export async function executeShell(job, ctx, deps) {
   const { runShellCommand, normalizeShellResult, log } = deps;
   const result = makeDefaultResult();
@@ -1028,18 +1148,61 @@ export async function executeShell(job, ctx, deps) {
     shell_stderr_bytes: shellResult.stderrBytes,
   };
 
-  // Shell delivery logic: announce-always sends on all results, announce sends on error only
-  const announcePayload = shellResult.deliveryText.trim() ? shellResult.deliveryText : shellResult.errorMessage;
-  if (job.delivery_mode === 'announce-always' && announcePayload) {
-    const prefix = shellResult.status === 'ok' ? '' : `\u26a0\ufe0f Shell job failed: ${job.name}\n\n`;
-    result.deliveryOverride = `${prefix}${announcePayload}`;
-  } else if (job.delivery_mode === 'announce' && shellResult.status !== 'ok' && announcePayload) {
-    result.deliveryOverride = announcePayload;
+  if (isCompletionDeliveryWatcherJob(job)) {
+    const watcherStdout = (shellResult.stdout || '').trim();
+    const watcherStderr = (shellResult.stderr || '').trim();
+
+    if (isCompletionWatcherPendingTick(shellResult)) {
+      result.status = 'skipped';
+      result.summary = 'Completion delivery watcher pending; target session is still running';
+      result.content = '';
+      result.errorMessage = null;
+      result.idemAction = 'release';
+      result.skipDelivery = true;
+    } else if (watcherStdout) {
+      // Completion watcher stdout is the only user-facing contract.  Stderr is
+      // diagnostics-only and must never be repackaged as a "successful" final
+      // completion if the watcher suppressed the real payload.
+      result.summary = watcherStdout;
+      result.content = watcherStdout;
+      if (['announce', 'announce-always'].includes(job.delivery_mode)) {
+        result.deliveryOverride = watcherStdout;
+      } else {
+        result.skipDelivery = true;
+      }
+    } else {
+      const noPayloadMessage = buildCompletionWatcherNoPayloadMessage(job, shellResult);
+      result.status = 'error';
+      result.summary = noPayloadMessage;
+      result.errorMessage = 'Completion delivery watcher produced no user-facing stdout payload';
+      result.content = noPayloadMessage;
+      if (['announce', 'announce-always'].includes(job.delivery_mode)) {
+        result.deliveryOverride = noPayloadMessage;
+      } else {
+        result.skipDelivery = true;
+      }
+      log('warn', `Completion watcher produced no deliverable stdout: ${job.name}`, {
+        runId: ctx.run.id,
+        shellStatus: shellResult.status,
+        exitCode: shellResult.exitCode,
+        stderrExcerpt: watcherStderr.slice(0, 500),
+        skippedOrDisabled: /\b(?:skipped|disabled)\b/i.test(watcherStderr),
+      });
+    }
   } else {
-    result.skipDelivery = true;
+    // Shell delivery logic: announce-always sends on all results, announce sends on error only
+    const announcePayload = shellResult.deliveryText.trim() ? shellResult.deliveryText : shellResult.errorMessage;
+    if (job.delivery_mode === 'announce-always' && announcePayload) {
+      const prefix = shellResult.status === 'ok' ? '' : `\u26a0\ufe0f Shell job failed: ${job.name}\n\n`;
+      result.deliveryOverride = `${prefix}${announcePayload}`;
+    } else if (job.delivery_mode === 'announce' && shellResult.status !== 'ok' && announcePayload) {
+      result.deliveryOverride = announcePayload;
+    } else {
+      result.skipDelivery = true;
+    }
   }
 
-  log('info', `Shell ${shellResult.status}: ${job.name}`, {
+  log('info', `Shell ${result.status}: ${job.name}`, {
     runId: ctx.run.id,
     exitCode: shellResult.exitCode,
     signal: shellResult.signal,
@@ -1055,11 +1218,16 @@ export async function executeAgent(job, ctx, deps) {
   const {
     waitForGateway, updateRunSession, setAgentStatus,
     buildJobPrompt, runAgentTurnWithActivityTimeout,
+    // Sanctioned isolated dispatch primitive. Falls back to the activity-aware
+    // runner when callers (e.g. tests) wire only the older name -- both helpers
+    // share the same HTTP-only contract, no subprocess spawn.
+    runIsolatedAgentTurn,
     updateContextSummary, releaseDispatch, releaseIdempotencyKey,
     updateJob, matchesSentinel, detectTransientError,
     listSessions,
     sqliteNow, log,
   } = deps;
+  const dispatchAgentTurn = runIsolatedAgentTurn || runAgentTurnWithActivityTimeout;
   const result = makeDefaultResult();
 
   // Gateway health check
@@ -1153,7 +1321,12 @@ export async function executeAgent(job, ctx, deps) {
     }
   }
 
-  const turnResult = await runAgentTurnWithActivityTimeout({
+  // Isolated dispatch primitive: HTTP-only chat completions call. The
+  // scheduler must never fork a sibling `openclaw` process to spawn an
+  // isolated session -- that variant has historically SIGTERM'd the
+  // launchd-tracked gateway parent and orphaned a node process on port
+  // 18789 (see ISOLATED_DISPATCH_PRIMITIVE in gateway.js).
+  const turnResult = await dispatchAgentTurn({
     message: prompt,
     agentId: job.agent_id || 'main',
     sessionKey,

package/dispatcher.js

@@ -51,7 +51,8 @@ import {
 import { buildRetrievalContext } from './retrieval.js';
 import { upsertAgent, setAgentStatus } from './agents.js';
 import {
-  runAgentTurnWithActivityTimeout, sendSystemEvent, getAllSubAgentSessions, listSessions,
+  runAgentTurnWithActivityTimeout, runIsolatedAgentTurn,
+  sendSystemEvent, getAllSubAgentSessions, listSessions,
   deliverMessage, checkGatewayHealth, waitForGateway, resolveDeliveryAlias,
   applyAuthProfileToSessionStore,
   syncAuthStoreToSession,
@@ -306,6 +307,10 @@ function buildDispatchDeps() {
     // Agent
     waitForGateway, updateRunSession, setAgentStatus,
     buildJobPrompt, runAgentTurnWithActivityTimeout,
+    // Isolated cron-dispatch primitive: HTTP-only wrapper around the
+    // chat-completions API; never forks a sibling openclaw process that
+    // could SIGTERM the launchd-tracked gateway parent.
+    runIsolatedAgentTurn,
     updateContextSummary, releaseIdempotencyKey,
     matchesSentinel, detectTransientError,
     listSessions,

package/gateway.js

@@ -9,6 +9,22 @@ const GATEWAY_URL = process.env.OPENCLAW_GATEWAY_URL || 'http://127.0.0.1:18789'
 const HOME_DIR = process.env.HOME || homedir();
 export const TELEGRAM_MAX_MESSAGE_LENGTH = 4096;
 
+// -- Isolated dispatch primitive contract --------------------
+//
+// Cron jobs with session_target=isolated must reach the gateway via the
+// public HTTP API only. Forking a sibling `openclaw` process to spawn the
+// session is rejected: in production that primitive has SIGTERM'd the
+// launchd-tracked gateway parent (the child inherits the parent's listening
+// socket on port 18789 and the parent dies), leaving an orphan node process
+// holding the port. See rh-bot.lan zombie-cascade incident report.
+//
+// runIsolatedAgentTurn is the only sanctioned dispatch primitive for
+// session_target=isolated cron jobs. It MUST NOT spawn, fork, or exec any
+// child process. Any future change that needs subprocess execution belongs
+// behind a different, explicitly-named helper so reviewers can keep this
+// contract intact.
+export const ISOLATED_DISPATCH_PRIMITIVE = 'http-chat-completions';
+
 let _cachedToken;
 let _tokenLoaded = false;
 
@@ -246,6 +262,29 @@ export async function runAgentTurnWithActivityTimeout(opts) {
   }
 }
 
+// -- Isolated dispatch primitive -----------------------------
+
+/**
+ * Sanctioned dispatch primitive for session_target=isolated cron jobs.
+ *
+ * This is a thin wrapper around runAgentTurnWithActivityTimeout that names
+ * the contract: HTTP-only request to the gateway, no child process spawn.
+ * The scheduler routes every session_target=isolated job through this
+ * helper so the no-fork invariant is reviewable at one call site and
+ * testable in isolation (see the no-subprocess regression test in test.js).
+ *
+ * Why a named wrapper instead of calling runAgentTurnWithActivityTimeout
+ * directly: the dispatch primitive is the load-bearing surface that the
+ * rh-bot.lan zombie-on-port outage cascaded through. A named entry point
+ * gives operators and reviewers a single grep target ("runIsolatedAgentTurn")
+ * to audit the no-spawn invariant.
+ *
+ * Accepts the same options as runAgentTurnWithActivityTimeout.
+ */
+export async function runIsolatedAgentTurn(opts) {
+  return await runAgentTurnWithActivityTimeout(opts);
+}
+
 // -- System Events (main session) ----------------------------
 
 /**
@@ -388,19 +427,43 @@ export function splitMessageForChannel(channel, message) {
   return [String(message ?? '')];
 }
 
-/**
- * Send a message to a Telegram/channel target via message tool.
- * Automatically resolves delivery aliases (e.g. '@team_room', 'owner_dm').
- */
-export async function deliverMessage(channel, target, message) {
-  let resolvedChannel = channel;
+export function normalizeDeliveryTarget(channel, target) {
+  let resolvedChannel = channel || null;
   let resolvedTarget = target;
 
-  // Strip channel prefix from target if present (e.g., "telegram/123456789" -> "123456789")
-  // Some jobs store the channel in the delivery_to field as "channel/id".
+  const normalizedTarget = typeof resolvedTarget === 'string' ? resolvedTarget.trim() : resolvedTarget;
+  if (!normalizedTarget) {
+    return { channel: resolvedChannel, target: normalizedTarget || null };
+  }
+
+  const prefixedMatch = normalizedTarget.match(/^([a-z0-9_-]+)([:/])(.*)$/i);
+  if (prefixedMatch) {
+    const [, prefix,, rest] = prefixedMatch;
+    if (!resolvedChannel || resolvedChannel === prefix) {
+      resolvedChannel = prefix;
+      resolvedTarget = rest;
+    }
+  }
+
   if (resolvedTarget && resolvedChannel && resolvedTarget.startsWith(resolvedChannel + '/')) {
     resolvedTarget = resolvedTarget.slice(resolvedChannel.length + 1);
   }
+  if (resolvedTarget && resolvedChannel && resolvedTarget.startsWith(resolvedChannel + ':')) {
+    resolvedTarget = resolvedTarget.slice(resolvedChannel.length + 1);
+  }
+
+  return {
+    channel: resolvedChannel,
+    target: typeof resolvedTarget === 'string' ? resolvedTarget.trim() : resolvedTarget,
+  };
+}
+
+/**
+ * Send a message to a Telegram/channel target via message tool.
+ * Automatically resolves delivery aliases (e.g. '@team_room', 'owner_dm').
+ */
+export async function deliverMessage(channel, target, message) {
+  let { channel: resolvedChannel, target: resolvedTarget } = normalizeDeliveryTarget(channel, target);
 
   // Resolve alias: try '@name' strip and bare name lookup
   if (resolvedTarget) {

package/index.d.ts

@@ -620,6 +620,7 @@ export const gateway: {
   listSessions(opts?: { activeMinutes?: number; limit?: number; kinds?: string[] }): Promise<Record<string, unknown>>;
   getAllSubAgentSessions(activeMinutes?: number): Promise<Array<Record<string, unknown>>>;
   splitMessageForChannel(channel: string, message: string): string[];
+  normalizeDeliveryTarget(channel: string | null, target: string | null): { channel: string | null; target: string | null };
   resolveDeliveryAlias(rawTarget: string): { channel: string; target: string } | null;
   deliverMessage(channel: string, target: string, message: string): Promise<DeliveryResult>;
   checkGatewayHealth(): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-scheduler",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "SQLite-backed job scheduler and workflow engine for OpenClaw agents",
   "type": "module",
   "main": "./index.js",
@@ -42,10 +42,12 @@
     "dispatch/deliver-watcher.sh",
     "dispatch/hooks.mjs",
     "dispatch/index.mjs",
+    "dispatch/message-input.mjs",
     "dispatch/README.md",
     "dispatch/watcher.mjs",
     "scripts/dispatch-cli-utils.mjs",
     "scripts/inbox-consumer.mjs",
+    "scripts/inbox-watcher-guardrail.mjs",
     "scripts/stuck-run-detector.mjs",
     "scripts/stuck-detector.sh",
     "scripts/telegram-webhook-check.mjs",

package/scripts/dispatch-cli-utils.mjs

@@ -63,3 +63,56 @@ export function resolveDispatchLabel(jobName, labels = {}) {
   }
   return null;
 }
+
+function normalizeOptionalString(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+/**
+ * Build a human-clear, machine-usable delivery surface for dispatch CLI output.
+ * Distinguishes between enabled delivery, intentional disablement, and missing/legacy state.
+ */
+export function buildDispatchDeliverySurface(record = {}) {
+  const deliverTo = normalizeOptionalString(record.deliverTo ?? record.delivery_to);
+  const deliverChannel = normalizeOptionalString(record.deliverChannel ?? record.delivery_channel);
+  const deliveryMode = normalizeOptionalString(record.deliveryMode ?? record.delivery_mode);
+  const explicitReason = normalizeOptionalString(
+    record.deliveryDisabledReason
+      ?? record.delivery_opt_out_reason
+      ?? record.reason
+  );
+  const deliveryDisabled = record.deliveryDisabled === true
+    || (record.delivery_mode === 'none' && !deliverTo)
+    || (record.deliveryMode === 'none' && !deliverTo);
+
+  if (deliverTo) {
+    return {
+      status: 'enabled',
+      mode: deliveryMode || 'announce',
+      channel: deliverChannel,
+      target: deliverTo,
+      ...(typeof record.scheduler === 'boolean' ? { scheduler: record.scheduler } : {}),
+      ...(typeof record.gateway === 'boolean' ? { gateway: record.gateway } : {}),
+    };
+  }
+
+  if (deliveryDisabled || explicitReason) {
+    return {
+      status: 'disabled',
+      mode: deliveryMode || null,
+      channel: null,
+      target: null,
+      reason: explicitReason || 'explicit opt-out',
+    };
+  }
+
+  return {
+    status: 'missing',
+    mode: deliveryMode || null,
+    channel: null,
+    target: null,
+    reason: 'delivery target missing or not recorded',
+  };
+}