openclaw-scheduler 0.2.0 → 0.2.2

package/AGENTS.md

@@ -27,6 +27,27 @@ For manifest authoring, validation, and identity/authorization profiles, use
 - Shell jobs (`session_target: "shell"`) run without the gateway. Agent jobs
   (`session_target: "isolated"` or `"main"`) require a running gateway.
 
+## Checking Job Status — Always Poll, Never Infer
+
+When reporting on whether a dispatched job is running, done, or stuck, **always call the status command directly** — never infer from check-in messages or notifications that appeared in your conversation.
+
+Check-in messages are delivered asynchronously. By the time they appear, the job may already be finished, failed, or on a later step. Conversation messages are stale by definition.
+
+```bash
+# For chilisaus-dispatched jobs:
+node ~/.openclaw/chilisaus/index.mjs status --label <label>
+
+# For scheduler jobs:
+openclaw-scheduler runs list <job-id> --json
+openclaw-scheduler runs running --json
+```
+
+The `status` output gives authoritative `status` (`accepted` / `running` / `done` / `error`), `updatedAt` timestamp, and final `summary`. Use that.
+
+**Rule: if you haven't polled status, you don't know the status.**
+
+---
+
 ## Error Handling
 
 CLI errors exit non-zero. In plain-text mode, the message goes to stderr. With

package/BEST-PRACTICES.md

@@ -134,7 +134,7 @@ Use `isolated` when:
 
 | Rule | Bad | Good |
 |------|-----|------|
-| Be imperative and specific | "check kubernetes" | "Check k8s pods in requesthub-prod and requesthub-dev. List any non-Running pods." |
+| Be imperative and specific | "check kubernetes" | "Check k8s pods in myapp-prod and myapp-staging. List any non-Running pods." |
 | Include a success signal | *(nothing)* | "If all pods Running, reply with exactly: HEARTBEAT_OK" |
 | Specify output format | *(nothing)* | "Format issues as: ⚠️ \<namespace\>/\<pod\>: \<status\>" |
 | State available resources | *(implicit)* | "Your memory files are in ~/.openclaw/workspace/memory/" |
@@ -147,7 +147,7 @@ Check everything and let me know if anything is wrong
 
 **Good prompt:**
 ```
-Check k8s pod health across requesthub-prod and requesthub-dev namespaces.
+Check k8s pod health across myapp-prod and myapp-staging namespaces.
 List any non-Running pods. If all pods are Running, reply with exactly: HEARTBEAT_OK
 Format any issues as: ⚠️ <namespace>/<pod>: <status>
 ```
@@ -282,7 +282,7 @@ When the dispatcher fires an isolated job, the agent receives a message structur
 From: scheduler | result | Previous backup: 3 files committed, pushed to origin
 ---
 
-Check k8s pod health across requesthub-prod and requesthub-dev.
+Check k8s pod health across myapp-prod and myapp-staging.
 If all pods are Running, reply with exactly: HEARTBEAT_OK
 Format any issues as: ⚠️ <namespace>/<pod>: <status>
 ```
@@ -360,6 +360,23 @@ The dispatcher picks this up on its next tick (within 15s) and creates and immed
 
 ---
 
+### Checking Job Status — Always Poll, Never Infer
+
+When reporting on whether a dispatched job is running, done, or stuck, **always call `status` directly** — never infer from check-in messages that appeared in the conversation.
+
+Check-in messages (from `agent-checkin.mjs` or similar) are delivered asynchronously via the scheduler inbox. By the time they appear in your conversation, the job may have already finished, failed, or moved on to a later step. Treating them as real-time signals produces stale or incorrect status reports.
+
+```bash
+# Always do this before reporting job status:
+node ~/.openclaw/chilisaus/index.mjs status --label <label>
+```
+
+The `status` output gives you the authoritative `status` field (`accepted` / `running` / `done` / `error`), the last `updatedAt` timestamp, and the final `summary`. Use that — not the most recent check-in message.
+
+**Rule: if you haven't polled `status`, you don't know the status.**
+
+---
+
 ### Communicating Between Jobs
 
 Jobs can pass data to each other using the inter-agent message queue. Messages injected into a job's context appear in the `--- Pending Messages ---` block at the top of the prompt.

package/CHANGELOG.md

@@ -2,21 +2,58 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [0.2.2] -- 2026-04-15
+
+### Fixed
+- fix(dispatch): make completion delivery deterministic
+- fix(dispatch): suppress junk completion fallbacks
+- fix(package): include provider registry in npm tarball
+- fix(scheduler): canonicalize isolated session auth overrides
+- fix(dispatch): delete watchdog jobs on disarm instead of disable to prevent accumulation
+
+### Added
+- feat(watcher): add stop_reason-based early delivery (Path 2a)
+- feat(dispatch): auto-inject ORIGIN_CHAT_ID from deliverTo into prompt
+- fix(dispatch): prefer group sessions over DM in auto-detected origin
+
+### Changed
+- ci: upgrade checkout and setup-node actions to v5
+- docs: align packaged runtime path with host layout
+- docs: document local npm pack install and upgrade flow
+- test: remove dead locals in watcher coverage
+
+## [0.2.1] -- 2026-04-01
 
 ### Fixed
 - fix(watcher): exit cleanly when session status=done (PR #1)
 - fix(watchdog): prevent auto-resolving active sessions with heartbeat + hard ceiling (PR #2)
 - fix(gateway): reset idle timer while fetch is in flight (PR #3)
 - fix(watcher): prevent premature kill of active subagent sessions with JSONL activity signal (PR #7)
+- fix(db): add SQLite busy_timeout (5s) to prevent SQLITE_BUSY on CLI + dispatcher contention
+- fix(approvals): prevent double-dispatch race on auto-approved jobs
+- fix(watcher): cap deadline extension at min(timeout, 4h) to prevent zombie watchers
+- fix(runs): preserve empty string summary/error_message (use ?? instead of ||)
+- fix(runs): guard getTimedOutRuns against NULL run_timeout_ms on legacy rows
+- fix(gateway): use byte length for Telegram message chunking (4096-byte limit)
+- fix(jobs): validate schedule_tz as real IANA timezone via Intl.DateTimeFormat
+- fix(dispatcher): wrap delete_after_run cleanup in transaction
+- fix(dispatch): remove 4000-char truncation in formatMessageForDelivery
+- fix(dispatch): add retry exception path delivery announcement
+- fix(dispatch): fix dispatch CLI subcommand routing in bin wrapper
 
 ### Added
 - feat: v0.2 runtime with identity/trust/authorization/evidence/credential handoff (PR #4)
 - 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: 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
+- docs: AGENTS.md, CONTEXT.md, JOB-QUICK-REF.md for agent adoption
 
 ### Changed
 - chore: replace non-ASCII characters with ASCII equivalents (PR #6)
+- chore: bump output_excerpt_limit and output_summary_limit defaults to 64KB
 
 ## [0.2.0] -- 2026-03-11
 

package/INSTALL.md

@@ -39,6 +39,21 @@ npm exec --prefix ~/.openclaw/scheduler openclaw-scheduler -- help
 
 Runtime state for npm installs defaults to `~/.openclaw/scheduler/`, not the package directory under `node_modules/`.
 
+To test the published package layout from local source before publishing, build a tarball and install it into a separate runtime prefix:
+
+```bash
+git clone https://github.com/amittell/openclaw-scheduler /tmp/openclaw-scheduler
+cd /tmp/openclaw-scheduler
+npm ci
+npm run verify:local
+npm pack
+
+mkdir -p ~/.openclaw/packages/openclaw-scheduler
+npm install --prefix ~/.openclaw/packages/openclaw-scheduler --omit=dev --no-package-lock ./openclaw-scheduler-*.tgz
+```
+
+In that setup, run the service from `~/.openclaw/packages/openclaw-scheduler/node_modules/openclaw-scheduler/dispatcher.js` and keep mutable state in `~/.openclaw/scheduler` via `SCHEDULER_HOME` and `SCHEDULER_DB`.
+
 ---
 
 ## Step 2: Install Dependencies
@@ -223,6 +238,14 @@ npm exec --prefix ~/.openclaw/scheduler openclaw-scheduler -- setup --service-mo
 npm exec --prefix ~/.openclaw/scheduler openclaw-scheduler -- setup --service-mode daemon
 ```
 
+If you installed from a locally packed tarball:
+
+```bash
+npm exec --prefix ~/.openclaw/packages/openclaw-scheduler openclaw-scheduler -- setup --service-mode agent
+# or:
+npm exec --prefix ~/.openclaw/packages/openclaw-scheduler openclaw-scheduler -- setup --service-mode daemon
+```
+
 What each mode does:
 
 - `agent` writes `~/Library/LaunchAgents/ai.openclaw.scheduler.plist` and bootstraps `gui/$UID/ai.openclaw.scheduler`

package/README.md

@@ -206,6 +206,23 @@ npm run verify:smoke                 # lightweight smoke gate used by GitHub Act
 
 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`.
 
+### Option C: local npm pack (simulate the published package from source)
+
+Use this when you want to test the exact package layout end users get from npm without publishing to npmjs.org yet.
+
+```bash
+git clone https://github.com/amittell/openclaw-scheduler /tmp/openclaw-scheduler
+cd /tmp/openclaw-scheduler
+npm ci
+npm run verify:local
+npm pack
+
+mkdir -p ~/.openclaw/packages/openclaw-scheduler
+npm install --prefix ~/.openclaw/packages/openclaw-scheduler --omit=dev --no-package-lock ./openclaw-scheduler-*.tgz
+```
+
+Point your service at `~/.openclaw/packages/openclaw-scheduler/node_modules/openclaw-scheduler/dispatcher.js`, and keep mutable state in `~/.openclaw/scheduler` via `SCHEDULER_HOME` and `SCHEDULER_DB`.
+
 The package also exports a small safe programmatic API surface for tooling:
 
 ```js
@@ -1140,18 +1157,13 @@ Use this when you want scripts to enqueue only actionable signals, then a single
 # 1) Enqueue a signal
 openclaw-scheduler msg send monitor-agent main "Found 3 critical errors in prod logs"
 
-# 2) Add a consumer shell job (every 5 minutes)
-openclaw-scheduler jobs add '{
-  "name": "Inbox Consumer",
-  "schedule_cron": "*/5 * * * *",
-  "session_target": "shell",
-  "payload_message": "npm exec --prefix ~/.openclaw/scheduler openclaw-inbox-consumer -- --to YOUR_CHAT_ID",
-  "delivery_mode": "announce",
-  "delivery_channel": "telegram",
-  "delivery_to": "YOUR_CHAT_ID",
-  "run_timeout_ms": 60000,
-  "origin": "system"
-}'
+# 2) Run the inbox consumer daemon (event-driven, watches SQLite WAL)
+#    Delivers within ~250ms of a message landing in the DB.
+#    No polling cron needed — the daemon watches for WAL changes.
+node scripts/inbox-consumer.mjs --watch --to YOUR_CHAT_ID --channel telegram
+
+# Or as a one-shot drain (useful for testing):
+node scripts/inbox-consumer.mjs --to YOUR_CHAT_ID --channel telegram
 ```
 
 ---

package/UPGRADING.md

@@ -105,6 +105,24 @@ npm install --prefix ~/.openclaw/scheduler openclaw-scheduler@latest
 npm install --prefix $env:USERPROFILE\.openclaw\scheduler openclaw-scheduler@latest
 ```
 
+### Local source tarball upgrade (`npm pack`)
+
+Use this when you want to upgrade a host to a locally built package before publishing to npmjs.org.
+
+```bash
+git clone https://github.com/amittell/openclaw-scheduler /tmp/openclaw-scheduler
+cd /tmp/openclaw-scheduler
+git pull
+npm ci
+npm run verify:local
+npm pack
+
+mkdir -p ~/.openclaw/packages/openclaw-scheduler
+npm install --prefix ~/.openclaw/packages/openclaw-scheduler --omit=dev --no-package-lock ./openclaw-scheduler-*.tgz
+```
+
+Keep `SCHEDULER_HOME=~/.openclaw/scheduler` and `SCHEDULER_DB=~/.openclaw/scheduler/scheduler.db`, and point the service at `~/.openclaw/packages/openclaw-scheduler/node_modules/openclaw-scheduler/dispatcher.js`.
+
 ---
 
 ## Step 2: Install Dependencies
@@ -277,6 +295,19 @@ sleep 3
 ssh $HOST "tail -5 /tmp/openclaw-scheduler.log && cd ~/.openclaw/scheduler && node cli.js status"
 ```
 
+#### macOS host over SSH using a local tarball
+
+```bash
+HOST=youruser@your-mac-host.lan
+TARBALL=./openclaw-scheduler-*.tgz
+
+scp $TARBALL $HOST:~/.openclaw/
+ssh $HOST "mkdir -p ~/.openclaw/packages/openclaw-scheduler && npm install --prefix ~/.openclaw/packages/openclaw-scheduler --omit=dev --no-package-lock ~/.openclaw/$(basename $TARBALL)"
+ssh $HOST "launchctl kickstart -k gui/\$(id -u)/ai.openclaw.scheduler"
+sleep 3
+ssh $HOST "tail -5 /tmp/openclaw-scheduler.log && launchctl print gui/\$(id -u)/ai.openclaw.scheduler | sed -n '1,20p'"
+```
+
 #### Linux / Windows WSL2 host over SSH
 
 ```bash

package/dispatch/index.mjs

@@ -32,6 +32,7 @@ import { randomUUID } from 'crypto';
 import { execFileSync } from 'child_process';
 import { homedir } from 'os';
 import Database from 'better-sqlite3';
+import { buildTerminalCompletionPayload } from './completion.mjs';
 import { onStarted, onFinished, onStuck } from './hooks.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -334,14 +335,28 @@ function readSessionsStore(agent = 'main') {
  *
  * @returns {string|null} - e.g. "telegram:-100200000000", or null if not found
  */
+/**
+ * Infer the chat type ("group" | "direct" | "") from a session object and its key.
+ * Checks session.chatType first, then falls back to key pattern matching.
+ * Key patterns:  agent:main:<channel>:group:<id>   → group
+ *                agent:main:<channel>:direct:<id>  → direct
+ */
+function inferChatType(key, session) {
+  if (session.chatType) return session.chatType;
+  if (key.includes(":group:")) return "group";
+  if (key.includes(":direct:")) return "direct";
+  return "";
+}
+
 function getActiveOriginFromSessions() {
   const store = readSessionsStore("main");
   if (!store) return null;
 
-  let best = null;
-  let bestTime = 0;
   const TEN_MIN_MS = 10 * 60 * 1000;
 
+  /** @type {Array<{origin: string, updatedAt: number, chatType: string}>} */
+  const candidates = [];
+
   for (const [key, session] of Object.entries(store)) {
     // Only consider main sessions, not subagents
     // Pattern: agent:main:<channel>:<type>:<id>  but NOT agent:main:subagent:*
@@ -357,19 +372,37 @@ function getActiveOriginFromSessions() {
     // Must be recently active
     if (Date.now() - updatedAt > TEN_MIN_MS) continue;
 
-    if (updatedAt > bestTime) {
-      // Prefer deliveryContext.to if available
-      const deliveryTo = session.deliveryContext?.to || null;
-      if (deliveryTo) {
-        bestTime = updatedAt;
-        // deliveryContext.to format: "telegram:-100200000000"
-        // Convert to origin format: "telegram:-100200000000"
-        best = deliveryTo;
-      }
-    }
+    // Prefer deliveryContext.to if available
+    const deliveryTo = session.deliveryContext?.to || null;
+    if (!deliveryTo) continue;
+
+    candidates.push({
+      origin: deliveryTo,
+      updatedAt,
+      chatType: inferChatType(key, session),
+    });
   }
 
-  return best;
+  if (candidates.length === 0) return null;
+
+  // Tiebreaker: prefer group sessions over direct/DM sessions.
+  // When both a DM and a group session are recently active, the DM session
+  // often has a more recent updatedAt (agent just replied there), but the
+  // triggering context was the group chat.  Within the same chat type, prefer
+  // the most recently updated session.
+  const typeScore = (chatType) => {
+    if (chatType === "group")  return 2;
+    if (chatType === "direct") return 0;
+    return 1; // unknown / other
+  };
+
+  candidates.sort((a, b) => {
+    const scoreDiff = typeScore(b.chatType) - typeScore(a.chatType);
+    if (scoreDiff !== 0) return scoreDiff;
+    return b.updatedAt - a.updatedAt;
+  });
+
+  return candidates[0].origin;
 }
 
 /**
@@ -507,12 +540,12 @@ function disarmWatchdog(label) {
   if (!entry?.watchdogJobId) return;
   try {
     const schedulerCli = join(__dirname, '..', 'cli.js');
-    execFileSync(process.execPath, [schedulerCli, 'jobs', 'disable', entry.watchdogJobId], {
+    execFileSync(process.execPath, [schedulerCli, 'jobs', 'delete', entry.watchdogJobId], {
       encoding: 'utf-8',
       timeout:  5000,
       stdio:    ['pipe', 'pipe', 'pipe'],
     });
-    process.stderr.write(`[${BRAND}] watchdog disarmed for ${label}\n`);
+    process.stderr.write(`[${BRAND}] watchdog deleted for ${label}\n`);
   } catch (err) {
     process.stderr.write(`[${BRAND}] watchdog disarm failed for ${label}: ${err.message}\n`);
   }
@@ -599,6 +632,14 @@ async function cmdEnqueue(flags) {
   const deliverMode    = flags['delivery-mode']     || 'announce';
   const mode        = flags.mode             || 'fresh';
 
+  // -- Auto-inject ORIGIN_CHAT_ID into prompt message ---------
+  // Ensures the spawned agent always knows where to send message tool calls,
+  // matching the delivery target. Skip if already present (caller is explicit)
+  // or if there's no delivery target.
+  if (deliverTo && !message.includes('ORIGIN_CHAT_ID:')) {
+    message = `ORIGIN_CHAT_ID: ${deliverTo}\n\n${message}`;
+  }
+
   // -- Verify command flag -----------------------------------
   const verifyCmd       = flags['verify-cmd'] || null;
 
@@ -849,7 +890,8 @@ async function cmdEnqueue(flags) {
         const watcherPath = join(__dirname, 'watcher.mjs');
         // Watcher timeout = session timeout + 120s buffer for startup/polling
         const watcherTimeoutS = timeoutS + 120;
-        const watcherCmd = `DISPATCH_LABELS_PATH='${sq(LABELS_PATH)}' '${sq(process.execPath)}' '${sq(watcherPath)}' --label '${sq(label)}' --timeout ${watcherTimeoutS} --poll-interval 20`;
+        const idleThresholdS = flags['idle-threshold'] || '300';
+        const watcherCmd = `DISPATCH_LABELS_PATH='${sq(LABELS_PATH)}' '${sq(process.execPath)}' '${sq(watcherPath)}' --label '${sq(label)}' --timeout ${watcherTimeoutS} --poll-interval 20 --idle-threshold ${idleThresholdS}`;
 
         const nowUtc = new Date().toISOString().replace('T', ' ').slice(0, 19);
         const jobSpec = JSON.stringify({
@@ -1116,6 +1158,7 @@ function cmdStatus(flags) {
     spawnedAt:  current.spawnedAt,
     updatedAt:  current.updatedAt,
     summary:    current.summary || null,
+    completion: current.completion || null,
     error:      current.error || null,
     liveness,
     ...(syncAction ? { syncAction } : {}),
@@ -1405,6 +1448,7 @@ function cmdResult(flags) {
     status:     entry.status,
     spawnedAt:  entry.spawnedAt,
     summary:    entry.summary || (lastReply ? lastReply.slice(0, 500) : null),
+    completion: entry.completion || null,
     lastReply:  lastReply || null,
     error:      entry.error || null,
   });
@@ -1474,15 +1518,15 @@ async function cmdDone(flags) {
     }
   }
 
-  // Bug 1 fix: truncate summary to 300 chars (delivery path silently truncates at 500)
-  const MAX_SUMMARY = 300;
-  let summary = rawSummary;
-  if (rawSummary.length > MAX_SUMMARY) {
-    process.stderr.write(
-      `[${BRAND}] warn: --summary truncated from ${rawSummary.length} chars to ${MAX_SUMMARY} chars\n`,
-    );
-    summary = rawSummary.slice(0, MAX_SUMMARY);
-  }
+  // Summary passes through as-is for raw diagnostics, but we also persist a
+  // first-class completion payload with deterministic delivery text so the
+  // watcher/post-office path never depends solely on transcript recovery.
+  const completion = buildTerminalCompletionPayload({
+    summary: rawSummary,
+    checklist,
+    sha,
+  });
+  const summary = completion.summary || rawSummary;
 
   const existing = getLabel(label);
 
@@ -1598,7 +1642,7 @@ async function cmdDone(flags) {
     // Label was never registered (e.g. direct subagent spawn, not via enqueue).
     // This is not an error -- the work completed, the label just wasn't tracked.
     process.stderr.write(`[${BRAND}] warn: no session found for label "${label}" -- registering as done\n`);
-    setLabel(label, { status: 'done', summary, ...(sha ? { sha } : {}) });
+    setLabel(label, { status: 'done', summary, completion, ...(sha ? { sha } : {}) });
 
     // No watcher is polling for this label, so actively notify via the gateway
     // post office using delivery config from config.json as fallback target.
@@ -1622,13 +1666,14 @@ async function cmdDone(flags) {
       process.stderr.write(`[${BRAND}] warn: no deliverTo in config -- completion not delivered for "${label}"\n`);
     }
 
-    out({ ok: true, label, status: 'done', summary, message: 'Label not previously registered; marked done.' });
+    out({ ok: true, label, status: 'done', summary, completion, message: 'Label not previously registered; marked done.' });
     return;
   }
 
   setLabel(label, {
     status:  'done',
     summary,
+    completion,
     ...(sha ? { sha } : {}),
   });
 
@@ -1647,7 +1692,7 @@ async function cmdDone(flags) {
     session_key: existing.sessionKey || null,
   }).catch(() => {});
 
-  out({ ok: true, label, status: 'done', summary, message: 'Label marked done via agent signal.' });
+  out({ ok: true, label, status: 'done', summary, completion, message: 'Label marked done via agent signal.' });
 }
 
 /**