openclaw-scheduler 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.5] -- 2026-04-27
+
+### Fixed
+- fix(dispatch): make completion prompts task-aware so `dispatch done` no longer implies `tests_passed:true` / `pushed:true` for tasks that explicitly should not push or do not require tests
+- fix(dispatch): recover completion text conservatively from terminal assistant turns instead of treating arbitrary mid-task chatter as the final delivery payload
+- fix(watcher): surface real missed-`done` final reports as interrupted diagnostics instead of silently timing out without useful delivery context
+- fix(dispatch): prefer structured, human-readable completion summaries and suppress generic/internal completion noise in announce flows
+- fix(dispatch): preserve embedded completion summaries, prefer explicit delivery targets for origin detection, and normalize dispatched completion delivery behavior
+- fix(dispatch): harden literal-safe prompt input handling and watcher SIGTERM handoff during delivery/recovery paths
+
+### Added
+- feat(dispatch): prefer structured human completion summaries in dispatch delivery flows
+- feat(dispatch): add inbox watcher delivery guardrail to catch broken packaged-layout consumer wiring earlier
+
+## [0.2.4] -- 2026-04-18
+
+### Fixed
+- fix(package): include dispatch/completion.mjs in the published npm tarball so dispatch CLI and watcher startup no longer crash with ERR_MODULE_NOT_FOUND in installed deployments
+
 ## [0.2.3] -- 2026-04-16
 
 ### Fixed

package/README.md

@@ -1728,7 +1728,7 @@ npm test
 
 ## Sub-agent Dispatch
 
-The dispatch module (`dispatch/index.mjs`) spawns and steers isolated agent sessions via the OpenClaw Gateway API and tracks them by a human-readable label. Unlike the scheduler's job/run model, dispatch calls the gateway directly -- no scheduler tick delay, no DB write required to start a session. Each session is assigned a unique session key, recorded in a local `labels.json` ledger, and auto-announces its result when the agent calls `done` as its final action. The module also supports symlink-based branding: a wrapper directory (such as `my-brand`) contains a `config.json` with a custom name and a symlink to `dispatch/index.mjs`, giving the same CLI a different identity in notifications and logs.
+The dispatch module (`dispatch/index.mjs`) spawns and steers isolated agent sessions via the OpenClaw Gateway API and tracks them by a human-readable label. Unlike the scheduler's job/run model, dispatch calls the gateway directly -- no scheduler tick delay, no DB write required to start a session. Each session is assigned a unique session key, recorded in a local `labels.json` ledger, and delivered back through a scheduler watcher when the agent calls `done` as its final action. That watcher is the only final-delivery path for dispatched jobs, and it normalizes completions into short human-readable summaries before posting them to chat. The module also supports symlink-based branding: a wrapper directory (such as `my-brand`) contains a `config.json` with a custom name and a symlink to `dispatch/index.mjs`, giving the same CLI a different identity in notifications and logs.
 
 ### Quick Example
 
@@ -1746,25 +1746,35 @@ openclaw-scheduler enqueue \
 # Fallback (if openclaw-scheduler is not in PATH):
 node ~/.openclaw/scheduler/dispatch/index.mjs enqueue \
   --label "fix-deploy-script" --message "..." --deliver-to YOUR_CHAT_ID
+
+# Literal-safe prompt input when the text contains shell metacharacters:
+cat prompt.md | openclaw-scheduler enqueue \
+  --label "fix-deploy-script" \
+  --message-stdin \
+  --deliver-to YOUR_CHAT_ID
 ```
 
+For normal chat-triggered dispatches, always pass `--deliver-to` from the inbound metadata `chat_id`. If you omit `--origin`, dispatch now derives it from that explicit delivery target instead of guessing from whichever session was active most recently. The old active-session lookup is kept only as a manual/local fallback when both values are absent.
+
 ### Flag Reference
 
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--label` | required | Human-readable name for the session. Used for status lookups, reuse, and watchdog tracking. |
 | `--message` | required* | Prompt sent to the agent. |
-| `--message-file` | -- | Path to a file whose contents are used as the prompt. Alternative to `--message`; avoids shell-escaping issues with long prompts. |
+| `--message-file` | -- | Path to a file whose contents are used as the prompt. Use `-` to read from stdin. Safer than inline shell quoting for prompts with backticks, quotes, or markdown. |
+| `--message-env` | -- | Environment variable name whose value is used as the prompt. Useful when the prompt contains shell-significant characters. |
+| `--message-stdin` | -- | Read the prompt from stdin explicitly. If stdin is piped and no explicit prompt source is set, dispatch auto-reads stdin. |
 | `--mode` | `fresh` | `fresh` creates a new session. `reuse` continues the last session recorded for this label. |
 | `--thinking` | -- | Reasoning budget: `low`, `high`, or `xhigh`. |
 | `--model` | -- | Model override, e.g. `anthropic/claude-sonnet-4-6`. |
-| `--deliver-to` | -- | Delivery target (e.g. Telegram chat ID). Registers a scheduler watcher job for reliable at-least-once delivery. |
+| `--deliver-to` | -- | Delivery target (e.g. Telegram chat ID). Registers the scheduler watcher job for durable final delivery. The gateway spawn itself stays fire-and-forget so raw tool output and internal done payloads cannot leak directly to chat. Chat-triggered callers should pass inbound metadata `chat_id` here, especially for group chats. |
 | `--delivery-mode` | `announce` | `announce` delivers only when output is non-empty. `announce-always` delivers unconditionally. `none` suppresses delivery. |
 | `--timeout` | `300` | Session timeout in seconds. |
 | `--monitor` | on | Auto-register a watchdog job that alerts if the session goes silent past the configured threshold. |
 | `--no-monitor` | -- | Disable watchdog registration for this dispatch. |
 
-*Either `--message` or `--message-file` is required.
+*One prompt source is required: `--message`, `--message-file`, `--message-env`, `--message-stdin`, or piped stdin.
 
 ### Subcommand Reference
 
@@ -1775,7 +1785,7 @@ node ~/.openclaw/scheduler/dispatch/index.mjs enqueue \
 | `stuck` | Check all running sessions against the stuck threshold. Exits 1 if genuinely stuck sessions remain after auto-resolving completed ones. |
 | `result` | Retrieve the last assistant reply from a session transcript via `chat.history`. |
 | `sync` | Reconcile `labels.json` with sessions store state. Auto-marks sessions as done or error based on idle time. Supports `--dry-run`. |
-| `done` | Agent-side completion signal. The agent calls this as its final action to mark itself done immediately (push-based; no idle timeout wait). |
+| `done` | Agent-side completion signal. The agent calls this as its final action to mark itself done immediately (push-based; no idle timeout wait). The stored completion payload is normalized for channel-safe delivery, with checklist/sha metadata used as a fallback when the raw summary is generic or noisy. |
 | `send` | Inject a message into a running session for mid-run steering. The agent sees it as a new user turn. |
 | `steer` | Alias for `send`. The name makes steering intent explicit. |
 | `heartbeat` | Check whether a session has been active within the last 10 minutes. Accepts `--label` or `--session-key`. |
@@ -1808,7 +1818,7 @@ openclaw-scheduler enqueue \
   --message "Update the API docs to reflect the new /v2 endpoints" \
   --thinking high --timeout 600 --deliver-to YOUR_CHAT_ID
 
-# Each worker auto-announces its result to the configured channel when done.
+# Each worker gets a watcher-delivered, channel-safe completion summary when done.
 # No polling needed. Watchdog jobs are auto-registered for each.
 ```
 

package/cli.js

@@ -100,8 +100,8 @@ Queue:
   queue prune                        Prune old messages now
 
 Messages:
-  messages send --from <label> [--to <agent>] [--kind <kind>] --body "<text>"
-                                     Send a checkpoint/status message (kind defaults to 'status', to defaults to 'main')
+  messages send --from <label> [--to <agent>] [--kind <kind>] [--channel <channel>] [--delivery-to <target>] --body "<text>"
+                                     Send a checkpoint/status message (kind defaults to 'status', to defaults to 'main'; channel/delivery-to override inbox-consumer defaults)
   msg send <from> <to> <body>        Send a message (positional form)
   msg inbox <agent-id> [limit]       Get inbox (unread)
   msg team-inbox <team-id> [limit] [member-id] [task-id]  Get team mailbox
@@ -610,10 +610,19 @@ switch (command) {
         const mTo   = mFlags.to   || 'main';
         const mKind = mFlags.kind || 'status';
         const mBody = mFlags.body;
+        const mChannel = mFlags.channel || null;
+        const mDeliveryTo = mFlags['delivery-to'] || null;
         if (!mFrom || !mBody) {
-          fail('Usage: messages send --from <label> [--to <agent>] [--kind <kind>] --body "<text>"');
+          fail('Usage: messages send --from <label> [--to <agent>] [--kind <kind>] [--channel <channel>] [--delivery-to <target>] --body "<text>"');
         }
-        const msg = sendMessage({ from_agent: mFrom, to_agent: mTo, kind: mKind, body: mBody });
+        const msg = sendMessage({
+          from_agent: mFrom,
+          to_agent: mTo,
+          kind: mKind,
+          body: mBody,
+          channel: mChannel,
+          delivery_to: mDeliveryTo,
+        });
         emit({ ok: true, message: msg }, `Sent: ${fmt(msg)}`);
         break;
       }

package/dispatch/README.md

@@ -68,27 +68,38 @@ node dispatch/index.mjs enqueue \
   --deliver-to YOUR_CHAT_ID     \
   --deliver-channel telegram        \
   --delivery-mode announce
+
+# Literal-safe prompt input for shell-sensitive text:
+cat prompt.md | node dispatch/index.mjs enqueue \
+  --label "ticket-43" \
+  --message-stdin \
+  --delivery-mode none
 ```
 
 | Flag | Default | Description |
 |---|---|---|
 | `--label` | required | Human name — used for lookup/reuse |
-| `--message` | required | Prompt sent to the agent |
+| `--message` | required* | Prompt sent to the agent |
+| `--message-file` | — | Read prompt text from a file. Use `-` to read from stdin. Safer than inline shell quoting for prompts with backticks, quotes, or markdown. |
+| `--message-env` | — | Read prompt text from an environment variable. |
+| `--message-stdin` | — | Read prompt text from stdin explicitly. If stdin is piped and no explicit source is set, dispatch auto-reads stdin. |
 | `--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-to` | — | Delivery target (chat ID, channel ID, handle, etc.). Enables `deliver:true` on the gateway call. Chat-triggered callers should pass inbound metadata `chat_id` here, especially for group chats. |
 | `--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`) |
+| `--origin` | -- | Dispatch origin (e.g. `telegram:12345`). If omitted but `--deliver-to` is explicit, dispatch derives origin from that target. Active-session auto-detect is fallback for manual/local use only. |
 | `--no-monitor` | false | Skip watcher monitoring |
 | `--monitor-interval` | -- | Watcher cron expression |
 | `--monitor-timeout` | -- | Watcher timeout in minutes |
 | `--verify-cmd` | -- | Post-completion verification command |
 
+*One prompt source is required: `--message`, `--message-file`, `--message-env`, `--message-stdin`, or piped stdin.
+
 ### `status` — session status for a label
 
 ```bash
@@ -151,6 +162,10 @@ Notes:
 node dispatch/index.mjs send \
   --label "ticket-42" \
   --message "Tests still failing on line 42, focus on the edge case"
+
+cat <<'EOF' | node dispatch/index.mjs send --label "ticket-42" --message-stdin
+Use literal `code`, quotes, and $(examples) safely
+EOF
 ```
 
 Sends a message directly into the running session. The agent sees it as a new