openclaw-scheduler 0.2.11 → 0.2.12

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.12] -- 2026-06-23
+
+### Changed
+- docs(dispatch): document that `dispatch done` must run from the originating local dispatch shell and that terminal-output watcher fallback requires strict clean completion evidence
+
 ## [0.2.11] -- 2026-06-23
 
 ### 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 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.
+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 the originating host's local `labels.json` ledger, and delivered back through a scheduler watcher when the agent calls `done` from that same local dispatch shell as its final action. Do not run the completion marker from inside `ssh`, Docker, tmux, or another nested shell, because that can update a different label store. The watcher normalizes completions into short human-readable summaries before posting them to chat, and it only falls back to terminal assistant output when the transcript contains strict clean completion evidence. 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
 
@@ -1785,7 +1785,7 @@ For normal chat-triggered dispatches, always pass `--deliver-to` from the inboun
 | `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). 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. |
+| `done` | Agent-side completion signal. The agent calls this as its final action from the originating local dispatch shell to mark itself done immediately (push-based; no idle timeout wait). Do not call it from inside a remote or nested shell, because the label lookup is local to the dispatch host. 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`. |

package/dispatch/README.md

@@ -139,7 +139,10 @@ node dispatch/index.mjs done \
 ```
 
 Marks the label as `done` immediately so the watcher can resolve the run without
-waiting for timeout polling.
+waiting for timeout polling. Run this command from the same local dispatch shell
+that created the label. Do not run it from inside `ssh`, Docker, tmux, or another
+nested shell unless that shell intentionally points at the originating dispatch
+host and `labels.json`; otherwise it can update a different label store.
 
 | Flag | Default | Description |
 |---|---|---|
@@ -291,8 +294,11 @@ No manual token configuration needed on a standard OpenClaw install.
 
 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 sends the structured `done` completion signal, then
-delivers via the scheduler's `handleDelivery` pipeline.
+minute until the agent sends the structured local `done` completion signal, then
+delivers via the scheduler's `handleDelivery` pipeline. If the structured signal
+is missed but the transcript has strict clean terminal completion evidence, the
+watcher may deliver that terminal assistant report; arbitrary mid-task replies
+remain diagnostics.
 
 ```
 dispatch enqueue --deliver-to <telegram-user-id>
@@ -325,10 +331,12 @@ gateway/session liveness fails open to "still monitoring" until the hard timeout
 window or a clear terminal error.
 
 While a label is still `running`, a plain assistant reply is diagnostic only.
-Successful final delivery requires the agent-side `done` signal and its
-structured completion payload. If an older watcher records an error and the
-worker later sends a valid `done`, the later completion is authoritative and the
-stale error is cleared from the label.
+Successful final delivery prefers the agent-side local `done` signal and its
+structured completion payload. The terminal-assistant fallback is intentionally
+narrow: it requires clean completion evidence from the transcript, not just the
+latest assistant text. If an older watcher records an error and the worker later
+sends a valid local `done`, the later completion is authoritative and the stale
+error is cleared from the label.
 
 ### Progress check-ins from subagent sessions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-scheduler",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "SQLite-backed job scheduler and workflow engine for OpenClaw agents",
   "type": "module",
   "main": "./index.js",