openclaw-scheduler 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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
+- fix(dispatch): clarify that completion markers must run in the originating local dispatch shell, and allow watcher delivery from clean terminal `stop_reason=end_turn` replies without broadening plain `lastReply` success detection
+- fix(watcher): use the fatal idle threshold for stalled-session errors while keeping quiet high-thinking sessions pending at the probe threshold
+
 ## [0.2.5] -- 2026-04-27
 
 ### 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/dispatch/completion.mjs

@@ -1134,6 +1134,7 @@ export function buildCompletionSignalInstructions({ label, taskPrompt, doneScrip
   readinessChecks.forEach((line, idx) => lines.push(`  ${idx + 1}. ${line}`));
   lines.push('');
   lines.push('Call this as your ABSOLUTE FINAL action -- nothing else runs after this:');
+  lines.push('  IMPORTANT: run this command in the dispatch session shell on this host. Do not run it inside ssh, docker, tmux, or any remote shell; remote label stores cannot mark this dispatch complete.');
   lines.push(`  node '${doneScriptPath}' done --label '${escapedLabel}' \\`);
   lines.push('    --summary "<human-readable summary of what you actually did>" \\');
   lines.push(`    --checklist '${checklistExample}' \\`);

package/dispatch/watcher.mjs

@@ -1052,6 +1052,22 @@ function hasStructuredCompletion(result) {
   return hasCompletionSignal(result?.completion);
 }
 
+function getCleanTerminalReply(status) {
+  if (!status?.sessionKey) return null;
+  const entry = getSessionStoreEntry(status.sessionKey);
+  const sessionId = entry?.sessionId || null;
+  const sessionAgent = status.sessionKey.split(':')[1] || 'main';
+  const terminalJsonlReply = sessionId ? getSessionTerminalReply(sessionId, sessionAgent) : null;
+  if (!sessionId || !terminalJsonlReply) return null;
+  return isSessionCleanlyFinished(sessionId, sessionAgent) ? terminalJsonlReply : null;
+}
+
+function getStrictTerminalReply(result, status) {
+  const terminalJsonlReply = getCleanTerminalReply(status);
+  if (!terminalJsonlReply) return null;
+  return result?.lastReply || terminalJsonlReply;
+}
+
 if (!label) {
   process.stderr.write('[watcher] --label is required\n');
   process.exit(2);
@@ -1159,16 +1175,13 @@ function runOnceAndExit() {
   }
 
   if (status.sessionKey) {
-    const entry = getSessionStoreEntry(status.sessionKey);
-    const sessionId = entry?.sessionId || null;
-    const sessionAgent = status.sessionKey.split(':')[1] || 'main';
-    const terminalJsonlReply = sessionId ? getSessionTerminalReply(sessionId, sessionAgent) : null;
-    if (sessionId && terminalJsonlReply && isSessionCleanlyFinished(sessionId, sessionAgent)) {
+    const terminalJsonlReply = getCleanTerminalReply(status);
+    if (terminalJsonlReply) {
       const result = dispatch('result', ['--label', label]);
       if (hasStructuredCompletion(result)) {
         deliverResult(label, result?.lastReply || terminalJsonlReply, 'completed (stop_reason=end_turn)', result?.completion || null);
       }
-      process.stderr.write(`[watcher] stop_reason=end_turn observed without completion signal -- continuing to monitor\n`);
+      deliverResult(label, terminalJsonlReply, 'completed (stop_reason=end_turn)', null);
     }
   }
 
@@ -1181,6 +1194,10 @@ function runOnceAndExit() {
     if (hasStructuredCompletion(result)) {
       deliverResult(label, result?.lastReply || null, null, result?.completion || null);
     }
+    const terminalReply = getStrictTerminalReply(result, status);
+    if (terminalReply) {
+      deliverResult(label, terminalReply, 'completed (stop_reason=end_turn)', null);
+    }
 
     const stallReason = ageMs >= idleFailureMs
       ? getRunningSessionStallReason(status, idleFailureMs)
@@ -1550,7 +1567,7 @@ while (Date.now() < deadline) {
         deliverResult(label, result?.lastReply || terminalJsonlReply, 'completed (stop_reason=end_turn)', result?.completion || null);
         // deliverResult exits
       }
-      process.stderr.write(`[watcher] stop_reason=end_turn observed without completion signal -- continuing to monitor\n`);
+      deliverResult(label, terminalJsonlReply, 'completed (stop_reason=end_turn)', null);
     }
   }
 
@@ -1569,6 +1586,10 @@ while (Date.now() < deadline) {
     if (hasStructuredCompletion(result)) {
       deliverResult(label, result?.lastReply || null, null, result?.completion || null);
     }
+    const terminalReply = getStrictTerminalReply(result, status);
+    if (terminalReply) {
+      deliverResult(label, terminalReply, 'completed (stop_reason=end_turn)', null);
+    }
 
     const stallReason = ageMs >= idleFailureMs
       ? getRunningSessionStallReason(status, idleFailureMs)

package/package.json

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