openclaw-scheduler 0.2.0

package/db.js

@@ -0,0 +1,122 @@
+// Database layer -- SQLite via better-sqlite3
+import Database from 'better-sqlite3';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { ensureSchedulerDbParent, resolveSchedulerDbPath } from './paths.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+let _db;
+let _dbPath;
+
+/**
+ * Override the DB path at runtime (must be called before getDb/initDb).
+ * Pass ':memory:' for in-memory test databases.
+ */
+export function setDbPath(path) {
+  if (_db) { _db.close(); _db = null; }
+  _dbPath = path;
+}
+
+export function getDb() {
+  if (!_db) {
+    const dbPath = _dbPath || resolveSchedulerDbPath({ env: process.env });
+    if (dbPath !== ':memory:') ensureSchedulerDbParent(dbPath);
+    _db = new Database(dbPath);
+    if (dbPath !== ':memory:') _db.pragma('journal_mode = WAL');
+    _db.pragma('busy_timeout = 5000');
+    _db.pragma('foreign_keys = ON');
+  }
+  return _db;
+}
+
+export function getResolvedDbPath() {
+  return _dbPath || resolveSchedulerDbPath({ env: process.env });
+}
+
+export async function initDb() {
+  const db = getDb();
+  const schema = readFileSync(join(__dirname, 'schema.sql'), 'utf8');
+  const hasUserTables = (db.prepare(`
+    SELECT COUNT(*) AS cnt
+    FROM sqlite_master
+    WHERE type = 'table'
+      AND name NOT LIKE 'sqlite_%'
+  `).get()?.cnt ?? 0) > 0;
+  const applySchema = (label) => {
+    try {
+      db.exec(schema);
+      return true;
+    } catch (err) {
+      process.stderr.write(`${new Date().toISOString()} [db] ${label}: ${err.message}\n`);
+      return false;
+    }
+  };
+  const runConsolidate = async () => {
+    try {
+      const { default: consolidate } = await import('./migrate-consolidate.js');
+      const applied = consolidate();
+      if (applied) {
+        process.stderr.write(`${new Date().toISOString()} [db] Consolidation migration applied\n`);
+      }
+    } catch (err) {
+      process.stderr.write(`${new Date().toISOString()} [db] migrate-consolidate error: ${err.message}\n`);
+    }
+  };
+
+  if (hasUserTables) {
+    // Existing installs: normalize via migration first so schema re-apply doesn't
+    // trip over legacy partial tables/indexes.
+    await runConsolidate();
+    applySchema('Schema apply warning');
+    return db;
+  }
+
+  // Net-new installs: create the baseline schema, then run consolidation in case
+  // a package upgrade adds idempotent backfills the base schema doesn't need.
+  applySchema('Initial schema apply warning');
+  await runConsolidate();
+
+  // Re-apply schema so indexes/table defs are fully aligned after consolidation.
+  applySchema('Schema re-apply warning');
+
+  return db;
+}
+
+/**
+ * Checkpoint WAL to main DB file. Call periodically to minimize
+ * data loss window on crash/SIGKILL. Returns checkpoint stats.
+ */
+export function checkpointWal() {
+  if (!_db) return null;
+  try {
+    const result = _db.pragma('wal_checkpoint(PASSIVE)');
+    return result?.[0] || null;
+  } catch (err) {
+    const ts = new Date().toISOString();
+    process.stderr.write(`${ts} [db] WAL checkpoint error: ${err.message}\n`);
+    return null;
+  }
+}
+
+export function closeDb() {
+  if (_db) {
+    try {
+      // Checkpoint WAL to main DB before closing to prevent data loss
+      const result = _db.pragma('wal_checkpoint(TRUNCATE)');
+      const ts = new Date().toISOString();
+      if (result && result[0]) {
+        const r = result[0];
+        process.stderr.write(`${ts} [db] WAL checkpoint on close: busy=${r.busy}, checkpointed=${r.checkpointed}, log=${r.log}\n`);
+      } else {
+        process.stderr.write(`${ts} [db] WAL checkpoint on close: ok\n`);
+      }
+    } catch (err) {
+      const ts = new Date().toISOString();
+      process.stderr.write(`${ts} [db] WAL checkpoint failed on close: ${err.message}\n`);
+    }
+    _db.close();
+    _db = null;
+  }
+}

package/dispatch/529-recovery.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * dispatch 529 recovery -- scheduler safety net for 529/overload errors.
+ *
+ * Scans labels.json for sessions in 'error' state with 529/overload patterns.
+ * If retryCount < MAX_RETRIES and the watcher hasn't already handled it,
+ * re-enqueues the session.
+ *
+ * Idempotency:
+ *   - Checks retryCount + lastRetryAt to avoid double-retrying if the watcher
+ *     already handled it (watcher updates retryCount and status immediately).
+ *   - If status is already 'running', skip (watcher handled it).
+ *   - If retryCount >= MAX, skip (already exhausted).
+ *
+ * Run by scheduler every 10 minutes as a safety net.
+ *
+ * Exit codes:
+ *   0 -- all good (nothing to retry, or retries dispatched)
+ *   1 -- error
+ */
+
+import { readFileSync, writeFileSync, renameSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LABELS_PATH = process.env.DISPATCH_LABELS_PATH || join(__dirname, 'labels.json');
+const INDEX_PATH  = process.env.DISPATCH_INDEX_PATH  || join(__dirname, 'index.mjs');
+
+const MAX_RETRIES = 3;
+// Only recover errors that happened within the last 60 minutes
+// (don't revive ancient failures)
+const MAX_ERROR_AGE_MS = 60 * 60 * 1000;
+// Minimum time since last retry before the safety net triggers
+// (give the watcher time to handle it first -- 5 minutes)
+const MIN_SINCE_LAST_UPDATE_MS = 5 * 60 * 1000;
+
+const OVERLOAD_PATTERNS = [
+  /529/i,
+  /failover\s*error/i,
+  /overload/i,
+  /temporarily\s+overloaded/i,
+  /service.*overloaded/i,
+];
+
+function is529Error(errorMsg) {
+  if (!errorMsg || typeof errorMsg !== 'string') return false;
+  return OVERLOAD_PATTERNS.some(p => p.test(errorMsg));
+}
+
+function loadLabels() {
+  try {
+    return JSON.parse(readFileSync(LABELS_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveLabels(labels) {
+  const tmp = LABELS_PATH + '.tmp.' + process.pid;
+  writeFileSync(tmp, JSON.stringify(labels, null, 2) + '\n');
+  renameSync(tmp, LABELS_PATH);
+}
+
+function notify(message) {
+  try {
+    const cliPath = join(__dirname, '..', 'cli.js');
+    execFileSync(process.execPath, [cliPath, 'msg', 'send', 'scheduler', 'main', message], {
+      encoding: 'utf-8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch {}
+}
+
+function respawnSession(label, entry) {
+  const continuationMsg = `[Auto-retry after 529 overload -- scheduler safety net] This is an automatic retry. Please continue your previous task from where you left off.`;
+
+  // Try send (reuse session) first
+  try {
+    execFileSync(process.execPath, [
+      INDEX_PATH, 'send',
+      '--label', label,
+      '--message', continuationMsg,
+    ], {
+      encoding: 'utf-8',
+      timeout: 30000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return 'send';
+  } catch {}
+
+  // Fallback: fresh enqueue
+  try {
+    const args = [
+      INDEX_PATH, 'enqueue',
+      '--label', label,
+      '--message', continuationMsg,
+      '--mode', 'fresh',
+    ];
+    if (entry?.model) args.push('--model', entry.model);
+    if (entry?.thinking) args.push('--thinking', entry.thinking);
+    if (entry?.origin) args.push('--origin', entry.origin);
+    if (entry?.deliverTo) {
+      args.push('--deliver-to', entry.deliverTo);
+      if (entry?.deliveryMode) args.push('--delivery-mode', entry.deliveryMode);
+      if (entry?.deliverChannel) args.push('--deliver-channel', entry.deliverChannel);
+    }
+
+    execFileSync(process.execPath, args, {
+      encoding: 'utf-8',
+      timeout: 30000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return 'fresh';
+  } catch {
+    return null;
+  }
+}
+
+// -- Main ----------------------------------------------------
+
+const labels = loadLabels();
+const now = Date.now();
+const results = [];
+for (const [name, entry] of Object.entries(labels)) {
+  // Only look at error-state sessions
+  if (entry.status !== 'error') continue;
+
+  const errorMsg = entry.error || '';
+  if (!is529Error(errorMsg)) continue;
+
+  // Check age -- don't retry very old errors
+  const updatedAt = entry.updatedAt ? new Date(entry.updatedAt).getTime() : 0;
+  const errorAge = now - updatedAt;
+  if (errorAge > MAX_ERROR_AGE_MS) {
+    results.push({ label: name, action: 'skip', reason: `error too old (${Math.round(errorAge / 60000)}min)` });
+    continue;
+  }
+
+  // Check if watcher already handled it (updated recently)
+  if (errorAge < MIN_SINCE_LAST_UPDATE_MS) {
+    results.push({ label: name, action: 'skip', reason: `updated ${Math.round(errorAge / 1000)}s ago (watcher may be handling)` });
+    continue;
+  }
+
+  // Check retry count
+  const retryCount = entry.retryCount || 0;
+  if (retryCount >= MAX_RETRIES) {
+    results.push({ label: name, action: 'skip', reason: `max retries exhausted (${retryCount}/${MAX_RETRIES})` });
+    continue;
+  }
+
+  // Attempt retry
+  const newRetryCount = retryCount + 1;
+  process.stderr.write(`[529-recovery] retrying [${name}] (attempt ${newRetryCount}/${MAX_RETRIES})\n`);
+
+  // Update labels.json first (claim the retry)
+  const freshLabels = loadLabels();
+  if (freshLabels[name]) {
+    freshLabels[name].retryCount = newRetryCount;
+    freshLabels[name].updatedAt = new Date().toISOString();
+    saveLabels(freshLabels);
+  }
+
+  const method = respawnSession(name, entry);
+  if (method) {
+    // Mark as running
+    const updated = loadLabels();
+    if (updated[name]) {
+      updated[name].status = 'running';
+      updated[name].error = null;
+      updated[name].updatedAt = new Date().toISOString();
+      saveLabels(updated);
+    }
+    notify(`🌶️ Dispatch 529 recovery: [${name}] retried (${newRetryCount}/${MAX_RETRIES}) via ${method}`);
+    results.push({ label: name, action: 'retried', method, retryCount: newRetryCount });
+  } else {
+    notify(`🌶️ Dispatch 529 recovery: [${name}] retry FAILED (${newRetryCount}/${MAX_RETRIES})`);
+    results.push({ label: name, action: 'retry_failed', retryCount: newRetryCount });
+  }
+}
+
+// Output summary -- scheduler delivers stdout if non-empty and delivery_mode=announce
+if (results.length > 0) {
+  const retried = results.filter(r => r.action === 'retried');
+  const skipped = results.filter(r => r.action === 'skip');
+  const failed = results.filter(r => r.action === 'retry_failed');
+
+  const lines = [];
+  if (retried.length) lines.push(`✅ Retried: ${retried.map(r => r.label).join(', ')}`);
+  if (failed.length) lines.push(`❌ Failed: ${failed.map(r => r.label).join(', ')}`);
+  if (skipped.length) lines.push(`⏭️ Skipped: ${skipped.map(r => `${r.label} (${r.reason})`).join(', ')}`);
+
+  // Only produce stdout (which triggers delivery) if we actually retried or failed something
+  if (retried.length || failed.length) {
+    process.stdout.write(`🌶️ 529 Recovery:\n${lines.join('\n')}\n`);
+  } else {
+    process.stderr.write(`[529-recovery] scan complete: ${skipped.length} skipped\n`);
+  }
+} else {
+  process.stderr.write('[529-recovery] scan complete: no 529 errors found\n');
+}

package/dispatch/README.md

@@ -0,0 +1,372 @@
+# dispatch
+
+**Sub-agent dispatch CLI for OpenClaw — native gateway API edition.**
+
+dispatch spawns and steers isolated agent sessions directly via the OpenClaw
+Gateway API. It tracks label→session mappings in a local JSON ledger, giving
+you a simple CLI to dispatch work, check on it, steer it mid-run, and get
+results back.
+
+No scheduler DB dependency. No dispatcher tick delay. Sessions start instantly.
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `index.mjs` | CLI entry point — 10 subcommands |
+| `hooks.mjs` | Lifecycle event emitter (Loki + optional HTTP webhook) |
+| `watcher.mjs` | Delivery monitoring process |
+| `529-recovery.mjs` | Transient error recovery |
+| `deliver-watcher.sh` | Shell wrapper for result retrieval |
+| `chilisaus.mjs` | Branded wrapper |
+| `config.example.json` | Example config |
+| `test-done-postoffice.mjs` | Done handler test |
+| `labels.json` | Local label→session ledger (gitignored) |
+| `README.md` | This file |
+
+---
+
+## How it works
+
+dispatch calls the OpenClaw Gateway RPC API directly:
+
+1. **`sessions.patch`** — configure the session (model, thinking level, spawn depth)
+2. **`agent`** — send a message into the session (spawning it if new)
+3. **`sessions.list`** — query session status and liveness
+4. **`chat.history`** — read session transcripts for results
+
+```
+Orchestrator calls:
+  dispatch enqueue --label ticket-42 --message "Fix the deploy script"
+
+  → Creates session key: agent:main:subagent:<uuid>
+  → Patches session with model/thinking/spawnDepth
+  → Calls gateway `agent` method with the task
+  → Session starts immediately (no scheduler tick delay)
+  → Tracks label→sessionKey in labels.json
+  → Agent auto-announces results on completion
+  → hooks.mjs fires dispatch.started to Loki
+```
+
+---
+
+## Subcommands
+
+### `enqueue` — spawn a new session
+
+```bash
+node dispatch/index.mjs enqueue \
+  --label   "ticket-42"             \
+  --message "Fix the deploy script" \
+  --mode    fresh                   \   # fresh | reuse
+  --agent   main                    \
+  --model   anthropic/claude-sonnet-4-6 \
+  --thinking high                   \
+  --timeout  300                    \
+  --deliver-to YOUR_CHAT_ID     \
+  --deliver-channel telegram        \
+  --delivery-mode announce
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--label` | required | Human name — used for lookup/reuse |
+| `--message` | required | Prompt sent to the agent |
+| `--mode` | `fresh` | `fresh` = new session; `reuse` = continue last session for this label |
+| `--session-key` | — | Explicit session key (bypasses ledger lookup) |
+| `--agent` | `main` | Agent ID |
+| `--model` | — | Model override (e.g. `anthropic/claude-sonnet-4-6`) |
+| `--thinking` | — | Reasoning level: `low`, `high`, `xhigh` |
+| `--timeout` | `300` | Seconds before run times out |
+| `--deliver-to` | — | Delivery target (chat ID, channel ID, handle, etc.). Enables `deliver:true` on the gateway call |
+| `--deliver-channel` | `telegram` | Delivery channel for `--deliver-to` (telegram, slack, etc.) |
+| `--delivery-mode` | `announce` | `announce`, `announce-always`, `none` |
+| `--origin` | -- | Dispatch origin (e.g. `telegram:12345`) |
+| `--no-monitor` | false | Skip watcher monitoring |
+| `--monitor-interval` | -- | Watcher cron expression |
+| `--monitor-timeout` | -- | Watcher timeout in minutes |
+| `--verify-cmd` | -- | Post-completion verification command |
+
+### `status` — session status for a label
+
+```bash
+node dispatch/index.mjs status --label "ticket-42"
+```
+
+Returns ledger info + live session data from gateway (model, age, token usage).
+
+### `stuck` — find stuck running sessions
+
+```bash
+node dispatch/index.mjs stuck --threshold-min 15
+```
+
+Exit 0 = nothing stuck (silent).
+Exit 1 = stuck sessions found (triggers announce delivery).
+
+Checks labels.json for sessions marked `running`, cross-references gateway
+session store for last activity timestamp.
+
+### `result` — last assistant reply from a session
+
+```bash
+node dispatch/index.mjs result --label "ticket-42"
+```
+
+Reads the session transcript via `chat.history` and returns the last assistant
+message.
+
+### `done` — mark a tracked session complete
+
+```bash
+node dispatch/index.mjs done \
+  --label "ticket-42" \
+  --summary "Work complete" \
+  --checklist '{"work_complete":true}'
+```
+
+Marks the label as `done` immediately so the watcher can resolve the run without
+waiting for timeout polling.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--label` | required | Label to mark complete |
+| `--summary` | `completed (agent signal)` | One-line completion summary |
+| `--checklist` | required | JSON object. Must include `work_complete:true`; optional fields like `tests_passed` and `pushed` may not be `false` |
+| `--sha` | — | Required when the stored task prompt includes real git commands like `git push`, `git rebase`, `git cherry-pick`, `--force-with-lease`, or `--force-push` |
+| `--force-done` | false | Override the minimum-runtime guard for legitimate short tasks |
+| `--reason` | — | Required with `--force-done`; records why an unusually short session is still valid |
+| `--skip-activity-check` | false | Bypass the gateway message-count heuristic when that check is too strict for the task |
+
+Notes:
+- The minimum runtime guard rejects very short sessions unless `--force-done --reason ...` is provided.
+- Older labels created before `taskPrompt` storage will warn and skip the git-SHA gate.
+- Gateway activity checks fail open: if the session API is unavailable, `done` logs a warning and continues.
+
+### `send` — message a running session
+
+```bash
+node dispatch/index.mjs send \
+  --label "ticket-42" \
+  --message "Tests still failing on line 42, focus on the edge case"
+```
+
+Sends a message directly into the running session. The agent sees it as a new
+user turn and continues working. This is the **mid-session steering superpower**.
+
+### `steer` — alias for send
+
+```bash
+node dispatch/index.mjs steer \
+  --label "ticket-42" \
+  --message "Change approach: use the new API instead"
+```
+
+Identical to `send`. The name makes intent explicit.
+
+### `heartbeat` — check session liveness
+
+```bash
+node dispatch/index.mjs heartbeat --label "ticket-42"
+# or:
+node dispatch/index.mjs heartbeat --session-key "agent:main:subagent:..."
+```
+
+Returns whether the session is alive (updated within the last 10 minutes),
+plus session metadata.
+
+### `list` — list all tracked labels
+
+```bash
+node dispatch/index.mjs list [--status running] [--limit 10]
+```
+
+Shows all labels in the ledger, sorted by most recent. Filter by status.
+
+### `sync` -- reconcile labels with sessions store
+
+```bash
+node dispatch/index.mjs sync
+```
+
+Reconciles `labels.json` with the gateway sessions store. Sessions that no
+longer exist on the gateway are marked stale, and sessions present on the
+gateway but missing from the ledger are imported. Useful after gateway restarts
+or manual session cleanup.
+
+---
+
+## Session Reuse
+
+`--mode reuse` looks up the last session key for this label in `labels.json`
+and sends the new message into that existing session. The agent picks up where
+it left off with full conversation history.
+
+```bash
+# First run — fresh session
+node dispatch/index.mjs enqueue --label "daily-report" --message "Generate today's report"
+
+# Later — continue in the same session
+node dispatch/index.mjs enqueue --label "daily-report" --message "Add the Q4 numbers" --mode reuse
+```
+
+---
+
+## Labels Ledger (`labels.json`)
+
+Local JSON file mapping labels to session keys:
+
+```json
+{
+  "ticket-42": {
+    "sessionKey": "agent:main:subagent:9131309b-...",
+    "runId": "46030a3d-...",
+    "agent": "main",
+    "mode": "fresh",
+    "model": null,
+    "thinking": null,
+    "spawnedAt": "2026-03-01T04:27:52.181Z",
+    "status": "running",
+    "summary": null,
+    "error": null,
+    "updatedAt": "2026-03-01T04:27:52.182Z"
+  }
+}
+```
+
+Gitignored by default. Session-local, not shared.
+
+---
+
+## Lifecycle Hooks (`hooks.mjs`)
+
+Fires structured events to Loki and/or an HTTP webhook:
+
+| Event | When |
+|---|---|
+| `dispatch.started` | Session spawned |
+| `dispatch.finished` | Session completed |
+| `dispatch.stuck` | `stuck` subcommand found stuck sessions |
+
+**Configuration:**
+
+```bash
+export LOKI_PUSH_URL=http://your-loki-host/loki/api/v1/push
+export DISPATCH_WEBHOOK_URL=https://your-endpoint.example.com/hook
+export DISPATCH_HOST=my-agent-host
+```
+
+---
+
+## Gateway Auth
+
+dispatch reads the gateway token from:
+1. `OPENCLAW_GATEWAY_TOKEN` environment variable
+2. `~/.openclaw/openclaw.json` → `gateway.auth.token`
+
+No manual token configuration needed on a standard OpenClaw install.
+
+---
+
+## Delivery
+
+### How it works
+
+When `--deliver-to` is set, dispatch registers a **scheduler watcher job**
+after dispatching the session. The watcher polls the session result every
+minute until the agent produces a reply, then delivers via the scheduler's
+`handleDelivery` pipeline.
+
+```
+dispatch enqueue --deliver-to <telegram-user-id>
+  -> gateway agent call (deliver: false, fire-and-forget)
+  -> scheduler job: <brand>-deliver:<label> (run_now: true, shell, one-shot)
+  -> watcher.mjs: long-running blocking process polls session status
+  -> on success (exit 0): scheduler delivers output to telegram/<telegram-user-id>
+  -> job auto-prunes via ttl_hours (default 48h)
+```
+
+**Why scheduler instead of gateway `deliver:true`?**
+- Retry / at-least-once delivery guarantee
+- Delivery aliases (scheduler resolves `@team_room` → channel/target)
+- Audit trail (runs table records every attempt)
+- Chain triggers (completion can fire child jobs)
+- Resilient to gateway restarts mid-run
+
+### Watcher script
+
+`deliver-watcher.sh` checks the session result. Exit 0 with output = deliver.
+Exit 1 with no output = retry on next cron tick (no spam — `announce-always`
+only delivers when `output.trim()` is truthy).
+
+### Progress check-ins from subagent sessions
+
+Subagent sessions run without PATH access to the `openclaw` CLI, so
+`openclaw system event` silently fails. For mid-task progress updates,
+use the gateway HTTP API via curl:
+
+```bash
+GW_TOKEN=$(python3 -c "import json, os; print(json.load(open(os.path.expanduser('~/.openclaw/openclaw.json')))['gateway']['auth']['token'])")
+curl -s -X POST http://127.0.0.1:18789/tools/invoke \
+  -H 'Content-Type: application/json' \
+  -H "Authorization: Bearer $GW_TOKEN" \
+  -d '{"tool":"message","args":{"action":"send","channel":"telegram","target":"<telegram-user-id>","message":"<label>: <progress update>"},"sessionKey":"main"}'
+```
+---
+
+## Architecture: Before & After
+
+### Before (scheduler DB dispatch)
+```
+dispatch enqueue → creates job in scheduler DB → dispatcher picks up on tick
+→ runs as isolated session → announces result → hooks fire
+```
+
+### After (native gateway API)
+```
+dispatch enqueue → calls gateway API directly → session starts immediately
+→ tracks in labels.json → announces result → hooks fire
+```
+
+Key improvements:
+- **Instant dispatch** — no scheduler tick delay (was up to 10s)
+- **Mid-session steering** — `send`/`steer` inject messages into running sessions
+- **No DB dependency** — labels.json is a simple JSON file
+- **Session reuse** — `--mode reuse` continues conversations
+- **Simpler** -- lightweight multi-file CLI vs full DB schema + dispatcher integration
+
+---
+
+## Stuck Run Detector (cron job)
+
+```bash
+openclaw-scheduler jobs add '{
+  "name": "Stuck Session Detector",
+  "schedule_cron": "*/10 * * * *",
+  "session_target": "shell",
+  "payload_message": "node ~/.openclaw/scheduler/dispatch/index.mjs stuck --threshold-min 15",
+  "delivery_mode": "announce",
+  "delivery_channel": "telegram",
+  "delivery_to": "YOUR_CHAT_ID"
+}'
+```
+
+---
+
+## Migration from Scheduler-DB Version
+
+If upgrading from the scheduler-DB version:
+
+1. Replace `index.mjs` (this file replaces it)
+2. `hooks.mjs` is unchanged (no DB imports)
+3. `labels.json` is created automatically on first `enqueue`
+4. Old scheduler jobs for dispatch tasks can be removed
+5. The scheduler DB is no longer needed for dispatch
+
+The CLI flags are identical — existing scripts/agents calling dispatch
+don't need changes (except `--mode auto` is gone; use `fresh` or `reuse`).
+
+New additions: `steer` subcommand (alias for `send`), `list` subcommand,
+`--model` flag on `enqueue`.