openclaw-scheduler 0.2.4 → 0.2.5

package/dispatch/index.mjs

@@ -32,8 +32,17 @@ import { randomUUID } from 'crypto';
 import { execFileSync } from 'child_process';
 import { homedir } from 'os';
 import Database from 'better-sqlite3';
-import { buildTerminalCompletionPayload } from './completion.mjs';
+import {
+  buildCompletionSignalInstructions,
+  buildTerminalCompletionPayload,
+  extractLastMeaningfulAssistantReplyFromEntries,
+  extractTerminalAssistantReplyFromEntries,
+  hasCompletionSignal,
+  taskRequiresGitSha,
+} from './completion.mjs';
 import { onStarted, onFinished, onStuck } from './hooks.mjs';
+import { resolveMessageInput } from './message-input.mjs';
+import { buildDispatchDeliverySurface } from '../scripts/dispatch-cli-utils.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOME_DIR = process.env.HOME || homedir();
@@ -110,6 +119,15 @@ function sleep(ms) {
   return new Promise(r => setTimeout(r, ms));
 }
 
+function toTimestampMs(value) {
+  if (value == null) return null;
+  if (typeof value === 'number') {
+    return value < 1e12 ? value * 1000 : value;
+  }
+  const parsed = new Date(value).getTime();
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
 /** Parse --flag value pairs from argv (supports both --flag value and --flag=value) */
 function parseFlags(argv) {
   const flags = {};
@@ -131,21 +149,6 @@ function parseFlags(argv) {
   return flags;
 }
 
-function taskRequiresGitSha(taskPrompt) {
-  if (!taskPrompt || typeof taskPrompt !== 'string') return false;
-
-  const commandPattern = /\bgit\s+(push|rebase|cherry-pick)\b|(?:^|\s)--force-with-lease\b|(?:^|\s)--force-push\b/ig;
-  let match;
-  while ((match = commandPattern.exec(taskPrompt)) !== null) {
-    const before = taskPrompt.slice(Math.max(0, match.index - 40), match.index);
-    const negatedContext = /\b(?:do\s+not|don't|dont|never)\s+(?:use|run|call|invoke)?\s*$/i.test(before)
-      || /\bavoid\s+(?:using\s+)?$/i.test(before)
-      || /\bwithout\s+(?:using\s+)?$/i.test(before);
-    if (!negatedContext) return true;
-  }
-  return false;
-}
-
 // -- Labels Ledger --------------------------------------------
 
 function getLabelsSignature() {
@@ -247,23 +250,16 @@ function gatewayCall(method, params = {}, opts = {}) {
 // -- Gateway Error Log Check ----------------------------------
 
 /**
- * Check the gateway error log for 529/FailoverError/overload errors
+ * Check the gateway error log for the most recent diagnostic lane task error
  * matching a specific session key.
  *
  * Scans the last N bytes of gateway.err.log for diagnostic lane task errors
- * that reference the session key and match overload patterns.
+ * that reference the session key and returns the newest error line.
  *
  * @param {string} sessionKey - The session key to check
  * @returns {{ found: boolean, error: string|null, timestamp: string|null }}
  */
-function check529InGatewayLog(sessionKey) {
-  const OVERLOAD_PATTERNS = [
-    /529/i,
-    /failover\s*error/i,
-    /overload/i,
-    /temporarily\s+overloaded/i,
-  ];
-
+function getGatewayLaneTaskError(sessionKey) {
   try {
     const logPath = join(HOME_DIR, '.openclaw', 'logs', 'gateway.err.log');
     if (!existsSync(logPath)) return { found: false, error: null, timestamp: null };
@@ -285,20 +281,15 @@ function check529InGatewayLog(sessionKey) {
       if (!line.includes(sessionKey)) continue;
       if (!line.includes('lane task error')) continue;
 
-      // Extract the error message
       const errorMatch = line.match(/error="([^"]+)"/);
       if (!errorMatch) continue;
 
-      const errorMsg = errorMatch[1];
-      if (OVERLOAD_PATTERNS.some(p => p.test(errorMsg))) {
-        // Extract timestamp
-        const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)/);
-        return {
-          found: true,
-          error: `FailoverError (529): ${errorMsg}`,
-          timestamp: tsMatch ? tsMatch[1] : null,
-        };
-      }
+      const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)/);
+      return {
+        found: true,
+        error: errorMatch[1],
+        timestamp: tsMatch ? tsMatch[1] : null,
+      };
     }
 
     return { found: false, error: null, timestamp: null };
@@ -307,6 +298,32 @@ function check529InGatewayLog(sessionKey) {
   }
 }
 
+/**
+ * Check the gateway error log for 529/FailoverError/overload errors
+ * matching a specific session key.
+ *
+ * @param {string} sessionKey - The session key to check
+ * @returns {{ found: boolean, error: string|null, timestamp: string|null }}
+ */
+function check529InGatewayLog(sessionKey) {
+  const OVERLOAD_PATTERNS = [
+    /529/i,
+    /failover\s*error/i,
+    /overload/i,
+    /temporarily\s+overloaded/i,
+  ];
+
+  const laneError = getGatewayLaneTaskError(sessionKey);
+  if (!laneError.found || !laneError.error) return { found: false, error: null, timestamp: null };
+  if (!OVERLOAD_PATTERNS.some(p => p.test(laneError.error))) return { found: false, error: null, timestamp: null };
+
+  return {
+    found: true,
+    error: `FailoverError (529): ${laneError.error}`,
+    timestamp: laneError.timestamp,
+  };
+}
+
 // -- Sessions Store (Direct Read) -----------------------------
 
 /**
@@ -328,6 +345,104 @@ function readSessionsStore(agent = 'main') {
   }
 }
 
+function getSessionJsonlPath(agent = 'main', sessionId) {
+  if (!sessionId) return null;
+  return join(HOME_DIR, '.openclaw', 'agents', agent, 'sessions', `${sessionId}.jsonl`);
+}
+
+function inspectSessionActivitySignal(sessionKey, sessionsStore) {
+  if (!sessionKey || !sessionsStore?.[sessionKey]) {
+    return { found: false, hasActivitySignal: false, messageCount: null, jsonlExists: false, hasTokens: false, updatedAtMs: null };
+  }
+
+  const agent = agentFromSessionKey(sessionKey) || 'main';
+  const entry = sessionsStore[sessionKey];
+  const jsonlPath = getSessionJsonlPath(agent, entry.sessionId);
+  const jsonlExists = jsonlPath ? existsSync(jsonlPath) : false;
+  const hasTokens = typeof entry.totalTokens === 'number' && entry.totalTokens > 0;
+  let messageCount = null;
+
+  try {
+    const history = gatewayCall('chat.history', { sessionKey }, { timeout: 8000 });
+    if (Array.isArray(history?.messages)) {
+      messageCount = history.messages.length;
+    }
+  } catch {}
+
+  return {
+    found: true,
+    hasActivitySignal: jsonlExists || hasTokens || (typeof messageCount === 'number' && messageCount > 0),
+    messageCount,
+    jsonlExists,
+    hasTokens,
+    updatedAtMs: toTimestampMs(entry.updatedAt),
+  };
+}
+
+function inspectSessionBootstrapFailure(sessionKey, sessionsStore, spawnedAtMs, startupGraceMs) {
+  if (!sessionKey || !sessionsStore?.[sessionKey]) {
+    return { shouldResolve: false, reason: null, errorMsg: null };
+  }
+
+  const ageMs = spawnedAtMs ? Date.now() - spawnedAtMs : Infinity;
+  if (ageMs < startupGraceMs || ageMs > startupGraceMs * 2) {
+    return { shouldResolve: false, reason: null, errorMsg: null };
+  }
+
+  const signal = inspectSessionActivitySignal(sessionKey, sessionsStore);
+  if (signal.hasActivitySignal) {
+    return { shouldResolve: false, reason: null, errorMsg: null };
+  }
+
+  const laneError = getGatewayLaneTaskError(sessionKey);
+  if (laneError.found && laneError.error) {
+    return {
+      shouldResolve: true,
+      reason: `diagnostic lane error: ${laneError.error}`,
+      errorMsg: `spawn-failure: ${laneError.error}`,
+    };
+  }
+
+  if (signal.messageCount === 0) {
+    return {
+      shouldResolve: true,
+      reason: 'session entered sessions store but never wrote transcript/history',
+      errorMsg: 'spawn-failure: session entered sessions store but never wrote transcript/history',
+    };
+  }
+
+  if (signal.updatedAtMs !== null && spawnedAtMs && signal.updatedAtMs <= spawnedAtMs + 5000) {
+    return {
+      shouldResolve: true,
+      reason: 'session entered sessions store but never showed any activity',
+      errorMsg: 'spawn-failure: session entered sessions store but never showed any activity',
+    };
+  }
+
+  return { shouldResolve: false, reason: null, errorMsg: null };
+}
+
+function readJsonlTailEntries(sessionId, agent = 'main', maxLines = 200) {
+  if (!sessionId) return null;
+  try {
+    const jsonlPath = join(HOME_DIR, '.openclaw', 'agents', agent, 'sessions', `${sessionId}.jsonl`);
+    return readFileSync(jsonlPath, 'utf-8')
+      .split('\n')
+      .filter(line => line.trim())
+      .slice(-maxLines)
+      .map(line => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Auto-detect the originating channel from the most recently active main session.
  * Reads sessions.json, finds sessions active within the last 10 minutes,
@@ -348,6 +463,17 @@ function inferChatType(key, session) {
   return "";
 }
 
+function parseOriginTarget(origin) {
+  const match = /^([^:]+):(.+)$/.exec(origin || '');
+  if (!match) return { channel: null, target: null };
+  return { channel: match[1], target: match[2] };
+}
+
+function originFromDeliveryTarget(deliverTo, deliverChannel = 'telegram') {
+  if (!deliverTo) return null;
+  return `${deliverChannel || 'telegram'}:${deliverTo}`;
+}
+
 function getActiveOriginFromSessions() {
   const store = readSessionsStore("main");
   if (!store) return null;
@@ -551,6 +677,65 @@ function disarmWatchdog(label) {
   }
 }
 
+
+function quoteForSingleQuotedShell(value) {
+  return String(value).replace(/'/g, "'\"'\"'");
+}
+
+/**
+ * Schedule a one-shot delivery watcher shell job for a dispatch label.
+ * Used both for the initial watcher registration and SIGTERM handoffs.
+ */
+function scheduleDeliveryWatcherJob({
+  label,
+  deliverTo,
+  deliverChannel = 'telegram',
+  timeoutSeconds = 300,
+  idleThresholdSeconds = 300,
+  origin = 'system',
+  agentBrand = BRAND,
+  nameSuffix = '',
+}) {
+  if (!label) throw new Error('label is required');
+  if (!deliverTo) throw new Error('deliverTo is required');
+
+  const schedulerCli = join(__dirname, '..', 'cli.js');
+  const watcherPath = join(__dirname, 'watcher.mjs');
+  const watcherTimeoutS = Number(timeoutSeconds) + 120;
+  const idleThresholdS = Number(idleThresholdSeconds) || 300;
+  const sq = quoteForSingleQuotedShell;
+  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 = {
+    name:                     `${agentBrand}-deliver:${label}${nameSuffix}`,
+    schedule_kind:            'at',
+    schedule_at:              nowUtc,
+    session_target:           'shell',
+    payload_kind:             'shellCommand',
+    payload_message:          watcherCmd,
+    delivery_mode:            'announce-always',
+    delivery_channel:         deliverChannel,
+    delivery_to:              deliverTo,
+    delivery_guarantee:       'at-least-once',
+    ttl_hours:                config.deliver_watcher_ttl_hours ?? 48,
+    overlap_policy:           'skip',
+    run_timeout_ms:           Math.max(watcherTimeoutS, 4 * 3600) * 1000
+                              + 420 * 1000,
+    delete_after_run:         1,
+    origin:                   origin || 'system',
+  };
+
+  const raw = execFileSync(process.execPath, [schedulerCli, '--json', 'jobs', 'add', JSON.stringify(jobSpec)], {
+    encoding: 'utf-8',
+    timeout:  10000,
+    stdio:    ['pipe', 'pipe', 'pipe'],
+  });
+
+  const parsed = JSON.parse(raw.trim());
+  return parsed?.job || null;
+}
+
 // -- Session Helpers ------------------------------------------
 
 /** Build a unique session key for a new subagent session. */
@@ -565,12 +750,19 @@ function makeSessionKey(agentId) {
  *
  * Flags:
  *   --label <string>         Required. Human-readable name
- *   --message <string>       Required. Prompt sent to the agent
+ *   --message <string>       Prompt sent to the agent
+ *   --message-file <path>    Read prompt text from a file (`-` = stdin)
+ *   --message-env <VAR>      Read prompt text from an environment variable
+ *   --message-stdin          Read prompt text from stdin explicitly
+ *                            (stdin is also auto-read when piped and no other message source is set)
  *   --agent <string>         Agent ID (default: main)
  *   --thinking <string>      Reasoning level: low|high|xhigh (default: not set)
  *   --timeout <seconds>      Run timeout in seconds (default: 300)
- *   --origin <origin>        Required. Where the job was dispatched from (e.g. "telegram:<your-user-id>", "system")
- *   --deliver-to <target>    Delivery target (e.g. Telegram chat ID). Enables deliver:true on the gateway call.
+ *   --origin <origin>        Explicit dispatch origin for audit/retries (e.g. "telegram:<chat_id>", "system")
+ *                            If omitted but --deliver-to is explicit, dispatch derives origin from that target.
+ *                            Active-session auto-detect is preserved only as a manual/local fallback when both are absent.
+ *   --deliver-to <target>    Delivery target (e.g. Telegram chat ID). Registers the scheduler watcher for durable final delivery.
+ *                            Chat-triggered callers should pass inbound metadata chat_id here, especially for group chats.
  *                            Defaults to origin chat ID when --origin is a "telegram:<id>" string.
  *   --deliver-channel <ch>   Delivery channel for --deliver-to (default: telegram)
  *   --delivery-mode <mode>   announce|announce-always|none (default: announce)
@@ -581,18 +773,23 @@ function makeSessionKey(agentId) {
  *   --model <string>         Model override (e.g. anthropic/claude-sonnet-4-6)
  */
 async function cmdEnqueue(flags) {
-  const label   = flags.label;
-  let   message = flags.message;
+  const label = flags.label;
   if (!label) die('--label is required', 2);
-  // Support --message-file for multiline prompts without shell escaping issues
-  if (!message && flags['message-file']) {
-    try {
-      message = readFileSync(flags['message-file'], 'utf-8').trim();
-    } catch (err) {
-      die(`--message-file: could not read file: ${err.message}`, 2);
-    }
+
+  let message = null;
+  try {
+    message = await resolveMessageInput({
+      message: flags.message,
+      messageFile: flags['message-file'],
+      messageEnv: flags['message-env'],
+      messageStdin: flags['message-stdin'],
+    });
+  } catch (err) {
+    die(err.message, 2);
+  }
+  if (message === null || message.length === 0) {
+    die('--message, --message-file, --message-env, --message-stdin, or piped stdin is required', 2);
   }
-  if (!message) die('--message or --message-file is required', 2);
 
   const agent       = flags.agent            || 'main';
   const thinking    = flags.thinking         || null;
@@ -605,30 +802,44 @@ async function cmdEnqueue(flags) {
     process.stderr.write(`[${BRAND}] WARNING: --timeout not specified, defaulting to 300s. ` +
       `Pass --timeout explicitly (≥1200 for thinking=high tasks) to avoid premature watcher kills.\n`);
   }
-  let origin = flags.origin || null;
+  const explicitOrigin = flags.origin || null;
+  const explicitDeliverTo = flags['deliver-to'] || null;
+  const explicitDeliverChannel = flags['deliver-channel'] || null;
+  let origin = explicitOrigin;
+
+  // Contract: chat-triggered callers should pass --deliver-to from inbound
+  // metadata chat_id. If they omit --origin, derive it from that explicit
+  // delivery target so dispatch never falls back to whichever session happened
+  // to be active most recently.
+  if (!origin && explicitDeliverTo) {
+    origin = originFromDeliveryTarget(explicitDeliverTo, explicitDeliverChannel || 'telegram');
+  }
 
-  // Auto-detect origin from active sessions if not explicitly provided
-  if (!origin) {
+  // Preserve active-session inference only as a manual/local fallback when the
+  // caller truly omitted both origin and delivery target.
+  if (!origin && !explicitDeliverTo) {
     origin = getActiveOriginFromSessions();
     if (origin) {
       process.stderr.write(`[${BRAND}] auto-detected origin from active session: ${origin}\n`);
+      process.stderr.write(`[${BRAND}] NOTE: active-session origin detection is a manual/local fallback. ` +
+        `Chat-triggered callers should pass --deliver-to from inbound metadata chat_id.\n`);
     }
   }
 
   // -- Auto-derive deliver-to from origin ---------------------------------
   // If origin is "telegram:<id>", use <id> as the default deliver-to target.
   let defaultDeliverTo   = null;
-  let defaultDeliverCh   = 'telegram';
+  let defaultDeliverCh   = explicitDeliverChannel || 'telegram';
   if (origin) {
-    const originMatch = /^([^:]+):(.+)$/.exec(origin);
-    if (originMatch) {
-      defaultDeliverCh  = originMatch[1];
-      defaultDeliverTo  = originMatch[2];
+    const { channel, target } = parseOriginTarget(origin);
+    if (channel && target) {
+      if (!explicitDeliverChannel) defaultDeliverCh = channel;
+      defaultDeliverTo = target;
     }
   }
 
-  const deliverTo      = flags['deliver-to']       || defaultDeliverTo;
-  const deliverChannel = flags['deliver-channel']   || defaultDeliverCh || 'telegram';
+  const deliverTo      = explicitDeliverTo         || defaultDeliverTo;
+  const deliverChannel = explicitDeliverChannel     || defaultDeliverCh || 'telegram';
   const deliverMode    = flags['delivery-mode']     || 'announce';
   const mode        = flags.mode             || 'fresh';
 
@@ -645,6 +856,9 @@ async function cmdEnqueue(flags) {
 
   // -- Watchdog monitoring flags -----------------------------
   const noMonitorRaw    = flags['no-monitor'];
+  const noMonitorReason = typeof noMonitorRaw === 'string' && noMonitorRaw.trim()
+    ? noMonitorRaw.trim()
+    : null;
   const noMonitor       = !!noMonitorRaw;
   const monitorEnabled  = !noMonitor && flags.monitor !== 'false';
   const monitorInterval = flags['monitor-interval'] || config.watchdogIntervalCron || '*/15 * * * *';
@@ -659,6 +873,7 @@ async function cmdEnqueue(flags) {
       "REJECTED: --deliver-to is required for dispatch jobs.\n" +
       "Pass --deliver-to <chat_id> (e.g. --deliver-to -100200000000 for a group, " +
       "or --deliver-to 123456789 for a DM).\n" +
+      "Chat-triggered callers should pass inbound metadata chat_id here, especially for group chats.\n" +
       "Alternatively, pass --origin telegram:<chat_id> to auto-derive the delivery target.\n" +
       "Pass --no-monitor \"<reason>\" only if you explicitly want to skip delivery (audit trail required).",
       2
@@ -769,26 +984,11 @@ async function cmdEnqueue(flags) {
   const doneScriptPath = join(__dirname, 'index.mjs');
   parts.push(``);
   parts.push(`---`);
-  parts.push(`COMPLETION SIGNAL -- READ CAREFULLY:`);
-  parts.push(``);
-  parts.push(`Only call this command after ALL of the following are true:`);
-  parts.push(`  1. All file edits are saved`);
-  parts.push(`  2. All commits are pushed (git push completed successfully)`);
-  parts.push(`  3. All API calls (e.g. GitHub comment replies) are done`);
-  parts.push(`  4. You have verified the work is complete`);
-  parts.push(``);
-  parts.push(`Call this as your ABSOLUTE FINAL action -- nothing else runs after this:`);
-  parts.push(`  node '${doneScriptPath}' done --label '${label.replace(/'/g, "'\\''")}' \\`);
-  parts.push(`    --summary "<what you actually did>" \\`);
-  parts.push(`    --checklist '{"work_complete":true,"tests_passed":true,"pushed":true}' \\`);
-  parts.push(`    [--sha "<git commit SHA if applicable>"]`);
-  parts.push(``);
-  parts.push(`Checklist rules:`);
-  parts.push(`  - work_complete MUST be true -- you are asserting you have finished ALL assigned work`);
-  parts.push(`  - If tests failed or push failed, do NOT set tests_passed:true or pushed:true -- instead continue working`);
-  parts.push(`  - Only include tests_passed/pushed if they apply to your task`);
-  parts.push(`If your task involved git commits, --sha is required and must be the actual SHA of your pushed commit. The done script will reject invented or placeholder SHAs.`);
-  parts.push(`Do NOT call done while planning, reading files, or mid-task. If you have not yet pushed a commit, you are not done.`);
+  parts.push(buildCompletionSignalInstructions({
+    label,
+    taskPrompt: message,
+    doneScriptPath,
+  }));
   parts.push(`---`);
   parts.push(``);
   parts.push(`---`);
@@ -802,15 +1002,16 @@ async function cmdEnqueue(flags) {
   const taskMessage = parts.join('\n');
 
   // -- Call gateway agent method -------------------------------
-  // Gateway deliver is used as a fast-path secondary. The scheduler watcher
-  // (created below) is the primary delivery path with retry + audit trail.
-  // Both may fire -- at-least-once semantics, duplicates acceptable.
+  // Final user delivery belongs to the scheduler watcher below.
+  // Keep the gateway spawn fire-and-forget so raw tool output or internal
+  // done payloads cannot leak directly to the chat ahead of the durable
+  // post-office delivery path.
   try {
     const response = gatewayCall('agent', {
       message:        taskMessage,
       sessionKey,
       idempotencyKey: idem,
-      deliver:        !!deliverTo,
+      deliver:        false,
       lane:           'subagent',
       timeout:        timeoutS,
       label:          label,
@@ -822,6 +1023,11 @@ async function cmdEnqueue(flags) {
       } : {}),
     }, { timeout: 15000 });
 
+    const deliveryDisabled = !deliverTo && noMonitor;
+    const deliveryDisabledReason = deliveryDisabled
+      ? (noMonitorReason || 'explicit opt-out via --no-monitor')
+      : null;
+
     // Update ledger
     setLabel(label, {
       sessionKey,
@@ -834,9 +1040,12 @@ async function cmdEnqueue(flags) {
       deliverTo:      deliverTo || null,
       deliverChannel: deliverChannel || null,
       deliveryMode:   deliverMode || null,
+      deliveryDisabled,
+      deliveryDisabledReason,
       verifyCmd:      verifyCmd || null,
       spawnedAt:      new Date().toISOString(),
       timeoutSeconds: timeoutS,
+      idleThresholdSeconds: parseInt(flags['idle-threshold'] || '300', 10),
       // Fix 4: Store timeout so cmdDone threshold logic can use it correctly.
       timeout:        timeoutS,
       status:         'running',
@@ -882,48 +1091,25 @@ async function cmdEnqueue(flags) {
     // Creates a one-shot shell job that runs watcher.mjs (blocks until session
     // completes, outputs result). The scheduler's handleDelivery delivers with
     // retry, alias resolution, and audit trail in scheduler.db.
-    // Gateway deliver:true is kept as a fast-path secondary (see deliver flag above).
+    // The watcher is the only final-delivery path for dispatched jobs.
     const sq = s => String(s).replace(/'/g, "'\\''");
     let schedulerWatcherOk = false;
     if (deliverTo && deliverMode !== 'none') {
       try {
-        const watcherPath = join(__dirname, 'watcher.mjs');
-        // Watcher timeout = session timeout + 120s buffer for startup/polling
-        const watcherTimeoutS = timeoutS + 120;
-        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({
-          name:                     `${agentBrand}-deliver:${label}`,
-          schedule_kind:            'at',
-          schedule_at:              nowUtc,
-          session_target:           'shell',
-          payload_kind:             'shellCommand',
-          payload_message:          watcherCmd,
-          delivery_mode:            'announce-always',
-          delivery_channel:         deliverChannel,
-          delivery_to:              deliverTo,
-          delivery_guarantee:       'at-least-once',
-          ttl_hours:                config.deliver_watcher_ttl_hours ?? 48,  // configurable TTL (deliver_watcher_ttl_hours); default 48h
-          overlap_policy:           'skip',
-          // Shell ceiling = max(initial timeout, rolling extension cap) + headroom.
-          // The watcher can extend its deadline up to MAX_DEADLINE_EXTENSION (4h) on
-          // activity (token growth / JSONL mtime). Headroom covers 2*FLAT_WINDOW + slop.
-          // Watcher constants: FLAT_WINDOW_MS=180s, MAX_DEADLINE_EXTENSION=4h.
-          run_timeout_ms:           Math.max(watcherTimeoutS, 4 * 3600) * 1000
-                                    + 420 * 1000,  // +7min headroom (2*FLAT_WINDOW + 1min slop)
-          delete_after_run:         1,             // auto-delete after watcher completes
-          origin:                   origin || 'system',
-        });
-        const schedulerCli = join(__dirname, '..', 'cli.js');
-        execFileSync(process.execPath, [schedulerCli, 'jobs', 'add', jobSpec], {
-          encoding: 'utf-8',
-          timeout:  10000,
-          stdio:    ['pipe', 'pipe', 'pipe'],
+        const watcherJob = scheduleDeliveryWatcherJob({
+          label,
+          deliverTo,
+          deliverChannel,
+          timeoutSeconds: timeoutS,
+          idleThresholdSeconds: flags['idle-threshold'] || '300',
+          origin: origin || 'system',
+          agentBrand,
         });
         schedulerWatcherOk = true;
-        process.stderr.write(`[${agentBrand}] scheduler watcher registered: ${agentBrand}-deliver:${label}\n`);
+        process.stderr.write(
+          `[${agentBrand}] scheduler watcher registered: ${agentBrand}-deliver:${label}` +
+          `${watcherJob?.id ? ` (${watcherJob.id})` : ''}\n`
+        );
       } catch (err) {
         process.stderr.write(`[${agentBrand}] scheduler watcher FAILED (gateway fallback active): ${err.message}\n`);
       }
@@ -934,7 +1120,7 @@ async function cmdEnqueue(flags) {
     let watchdogJobId = null;
     if (monitorEnabled && deliverTo) {
       try {
-        const checkCmd = `'${sq(process.execPath)}' '${sq(join(__dirname, 'index.mjs'))}' stuck --label '${sq(label)}' --threshold-min ${monitorTimeout}`;
+        const checkCmd = `'${sq(process.execPath)}' '${sq(join(__dirname, 'index.mjs'))}' result --label '${sq(label)}'`;
         const alertChannel = deliverChannel || 'telegram';
         const alertTarget  = deliverTo;
         const watchdogSpec = JSON.stringify({
@@ -979,6 +1165,18 @@ async function cmdEnqueue(flags) {
       }
     }
 
+    const delivery = buildDispatchDeliverySurface({
+      deliverTo,
+      deliverChannel,
+      deliveryMode: deliverMode,
+      deliveryDisabled,
+      deliveryDisabledReason,
+      ...(deliverTo ? {
+        scheduler: schedulerWatcherOk,
+        gateway: true,
+      } : {}),
+    });
+
     out({
       ok:         true,
       label,
@@ -987,12 +1185,7 @@ async function cmdEnqueue(flags) {
       mode:       isFresh ? 'fresh' : 'reuse',
       agent,
       status:     'accepted',
-      delivery:   deliverTo ? {
-        scheduler: schedulerWatcherOk,
-        gateway:   !!deliverTo,
-        target:    deliverTo,
-        channel:   deliverChannel,
-      } : null,
+      delivery,
       watchdog:   monitorEnabled ? {
         enabled:  watchdogJobOk,
         jobId:    watchdogJobId,
@@ -1000,11 +1193,13 @@ async function cmdEnqueue(flags) {
         timeout:  monitorTimeout,
         ...(monitorEnabled && !deliverTo ? { skipped: true, reason: 'no --deliver-to target' } : {}),
       } : null,
-      message:    schedulerWatcherOk
-        ? 'Session spawned. Delivery via scheduler (primary) + gateway (secondary).'
-        : deliverTo
-          ? 'Session spawned. Delivery via gateway only (scheduler watcher failed).'
-          : 'Session spawned via gateway. Agent is running.',
+      message:    delivery.status === 'disabled'
+        ? `Session spawned. Delivery intentionally disabled${delivery.reason ? ` (${delivery.reason}).` : '.'}`
+        : schedulerWatcherOk
+          ? 'Session spawned. Delivery via scheduler (primary) + gateway (secondary).'
+          : deliverTo
+            ? 'Session spawned. Delivery via gateway only (scheduler watcher failed).'
+            : 'Session spawned. Delivery target missing or not recorded.',
     });
 
     // -- Post-spawn verification (Fix 3) --------------------------------
@@ -1018,17 +1213,25 @@ async function cmdEnqueue(flags) {
     for (let spawnPoll = 0; spawnPoll < SPAWN_POLL_MAX; spawnPoll++) {
       await sleep(SPAWN_POLL_DELAY_MS);
       const spawnStore = readSessionsStore(agent);
-      if (spawnStore && sessionKey in spawnStore) {
+      const signal = inspectSessionActivitySignal(sessionKey, spawnStore);
+      if (signal.hasActivitySignal) {
         spawnConfirmed = true;
         break;
       }
     }
     if (!spawnConfirmed) {
-      process.stderr.write(
-        `[${agentBrand}] WARNING: session ${sessionKey} did not appear in gateway after ` +
-        `${(SPAWN_POLL_MAX * SPAWN_POLL_DELAY_MS) / 1000}s -- spawn may have failed\n`
-      );
-      setLabel(label, { status: 'spawn-warning' });
+      const laneError = getGatewayLaneTaskError(sessionKey);
+      const spawnError = laneError.found && laneError.error
+        ? `spawn-failure: ${laneError.error}`
+        : `spawn-failure: session ${sessionKey} never produced transcript/history within ` +
+          `${(SPAWN_POLL_MAX * SPAWN_POLL_DELAY_MS) / 1000}s`;
+      process.stderr.write(`[${agentBrand}] WARNING: ${spawnError}\n`);
+      setLabel(label, {
+        status: 'error',
+        error: spawnError,
+        summary: spawnError,
+      });
+      disarmWatchdog(label);
     }
   } catch (err) {
     die(`gateway agent call failed: ${err.message}`);
@@ -1065,62 +1268,80 @@ function cmdStatus(flags) {
     const ageMs = Date.now() - spawnedAtMs;
     const STARTUP_GRACE_MS = config.startupGraceMs ?? 300_000;
 
-    // -- Heartbeat-based liveness guard ----------------------------------
-    // The watcher process writes lastPing every 60s while the session is live.
-    // If the ping is fresh, the watcher is alive and working -- defer auto-resolve
-    // to avoid killing sessions during slow tool calls, docker builds, etc.
-    //
-    // PING_STALE_MS:   3x the 60s ping interval -- if we haven't heard from the
-    //                  watcher in 3 min, it's probably dead; fall through to check.
-    // hardCeilingMs:   job timeout * 1.5 -- absolute max regardless of ping age.
-    //                  Catches zombie watchers (watcher alive but session is stuck).
-    // idleThresholdMs: max(job timeout, 10 min) -- replaces the old hardcoded 10-min
-    //                  threshold so longer jobs aren't killed at exactly 10 min.
-    const PING_STALE_MS  = 3 * 60 * 1000;
-    const idleThresholdMs = Math.max((entry.timeoutSeconds || 600) * 1000, 10 * 60 * 1000);
-    // hardCeilingMs must be >= idleThresholdMs to avoid the ceiling undercutting the
-    // idle floor (e.g. timeoutSeconds=300 -> ceiling=7.5 min < idle=10 min would force
-    // zombie-guard threshold for sessions that should still use idleThresholdMs).
-    const hardCeilingMs  = Math.max((entry.timeoutSeconds || 600) * 1000 * 1.5, idleThresholdMs * 1.5);
-
-    let check;
-    if (ageMs < STARTUP_GRACE_MS) {
-      // Within startup grace -- never auto-resolve
-      check = { shouldResolve: false };
-    } else if (entry.lastPing) {
-      const pingAgeMs = Date.now() - new Date(entry.lastPing).getTime();
-      if (pingAgeMs < PING_STALE_MS && ageMs < hardCeilingMs) {
-        // Watcher alive and within job ceiling -- defer auto-resolve
+    const bootstrapFailure = !entry.lastPing
+      ? inspectSessionBootstrapFailure(
+          entry.sessionKey,
+          sessionsStore,
+          spawnedAtMs,
+          STARTUP_GRACE_MS,
+        )
+      : { shouldResolve: false, reason: null, errorMsg: null };
+    if (bootstrapFailure.shouldResolve) {
+      setLabel(label, {
+        status:  'error',
+        error:   bootstrapFailure.errorMsg,
+        summary: `Auto-resolved as spawn failure: ${bootstrapFailure.reason}`,
+      });
+      syncAction = `auto-resolved as spawn failure: ${bootstrapFailure.reason}`;
+      disarmWatchdog(label);
+    } else {
+      // -- Heartbeat-based liveness guard ----------------------------------
+      // The watcher process writes lastPing every 60s while the session is live.
+      // If the ping is fresh, the watcher is alive and working -- defer auto-resolve
+      // to avoid killing sessions during slow tool calls, docker builds, etc.
+      //
+      // PING_STALE_MS:   3x the 60s ping interval -- if we haven't heard from the
+      //                  watcher in 3 min, it's probably dead; fall through to check.
+      // hardCeilingMs:   job timeout * 1.5 -- absolute max regardless of ping age.
+      //                  Catches zombie watchers (watcher alive but session is stuck).
+      // idleThresholdMs: max(job timeout, 10 min) -- replaces the old hardcoded 10-min
+      //                  threshold so longer jobs aren't killed at exactly 10 min.
+      const PING_STALE_MS  = 3 * 60 * 1000;
+      const idleThresholdMs = Math.max((entry.timeoutSeconds || 600) * 1000, 10 * 60 * 1000);
+      // hardCeilingMs must be >= idleThresholdMs to avoid the ceiling undercutting the
+      // idle floor (e.g. timeoutSeconds=300 -> ceiling=7.5 min < idle=10 min would force
+      // zombie-guard threshold for sessions that should still use idleThresholdMs).
+      const hardCeilingMs  = Math.max((entry.timeoutSeconds || 600) * 1000 * 1.5, idleThresholdMs * 1.5);
+
+      let check;
+      if (ageMs < STARTUP_GRACE_MS) {
+        // Within startup grace -- never auto-resolve
         check = { shouldResolve: false };
+      } else if (entry.lastPing) {
+        const pingAgeMs = Date.now() - new Date(entry.lastPing).getTime();
+        if (pingAgeMs < PING_STALE_MS && ageMs < hardCeilingMs) {
+          // Watcher alive and within job ceiling -- defer auto-resolve
+          check = { shouldResolve: false };
+        } else {
+          // Ping stale OR past hard ceiling: fall through to session store check
+          const thresh = ageMs >= hardCeilingMs ? 2 * 60 * 1000 : idleThresholdMs;
+          check = checkSessionDone(entry.sessionKey, sessionsStore, thresh, true, spawnedAtMs);
+        }
       } else {
-        // Ping stale OR past hard ceiling: fall through to session store check
+        // No lastPing -- backward compat (sessions dispatched before heartbeat feature).
+        // Use idleThresholdMs (job-aware) instead of the old hardcoded 10 min.
         const thresh = ageMs >= hardCeilingMs ? 2 * 60 * 1000 : idleThresholdMs;
         check = checkSessionDone(entry.sessionKey, sessionsStore, thresh, true, spawnedAtMs);
       }
-    } else {
-      // No lastPing -- backward compat (sessions dispatched before heartbeat feature).
-      // Use idleThresholdMs (job-aware) instead of the old hardcoded 10 min.
-      const thresh = ageMs >= hardCeilingMs ? 2 * 60 * 1000 : idleThresholdMs;
-      check = checkSessionDone(entry.sessionKey, sessionsStore, thresh, true, spawnedAtMs);
-    }
 
-    if (check.shouldResolve) {
-      if (check.is529) {
-        setLabel(label, {
-          status:  'error',
-          error:   check.errorMsg || `529/overload: ${check.reason}`,
-          summary: `Auto-resolved as error: ${check.reason}`,
-        });
-        syncAction = `auto-resolved as 529 error: ${check.reason}`;
-      } else {
-        setLabel(label, {
-          status:  'interrupted',
-          summary: `Auto-resolved: session went idle without calling done. Work may be incomplete. (${check.reason})`,
-        });
-        syncAction = `auto-resolved as interrupted: ${check.reason}`;
+      if (check.shouldResolve) {
+        if (check.is529) {
+          setLabel(label, {
+            status:  'error',
+            error:   check.errorMsg || `529/overload: ${check.reason}`,
+            summary: `Auto-resolved as error: ${check.reason}`,
+          });
+          syncAction = `auto-resolved as 529 error: ${check.reason}`;
+        } else {
+          setLabel(label, {
+            status:  'interrupted',
+            summary: `Auto-resolved: session went idle without calling done. Work may be incomplete. (${check.reason})`,
+          });
+          syncAction = `auto-resolved as interrupted: ${check.reason}`;
+        }
+        // Disarm watchdog when session is auto-resolved
+        disarmWatchdog(label);
       }
-      // Disarm watchdog when session is auto-resolved
-      disarmWatchdog(label);
     }
   }
 
@@ -1128,6 +1349,9 @@ function cmdStatus(flags) {
   if (entry.sessionKey && sessionsStore) {
     const sessionEntry = sessionsStore[entry.sessionKey];
     if (sessionEntry) {
+      if (sessionEntry.sessionId && entry.sessionId !== sessionEntry.sessionId) {
+        setLabel(label, { sessionId: sessionEntry.sessionId });
+      }
       liveness = {
         updatedAt: sessionEntry.updatedAt,
         ageMs:     sessionEntry.updatedAt
@@ -1159,6 +1383,7 @@ function cmdStatus(flags) {
     updatedAt:  current.updatedAt,
     summary:    current.summary || null,
     completion: current.completion || null,
+    delivery:   buildDispatchDeliverySurface(current),
     error:      current.error || null,
     liveness,
     ...(syncAction ? { syncAction } : {}),
@@ -1192,7 +1417,7 @@ function hasActiveWatcher(label) {
           r.status = 'running'
           OR (r.status = 'pending' AND r.started_at > datetime('now','-5 minutes'))
         )
-    `).get(`%-deliver:${label}`);
+    `).get(`%-deliver:${label}%`);
     return (row?.c || 0) > 0;
   } catch {
     return false;
@@ -1346,6 +1571,28 @@ function cmdSync(flags) {
     const syncStore = getSyncStore(entry);
     const spawnedAtMs = entry.spawnedAt ? new Date(entry.spawnedAt).getTime() : 0;
     const elapsedMs   = Date.now() - spawnedAtMs;
+    const STARTUP_GRACE_MS_SYNC = config.startupGraceMs ?? 300_000;
+
+    const bootstrapFailure = !entry.lastPing
+      ? inspectSessionBootstrapFailure(
+          entry.sessionKey,
+          syncStore,
+          spawnedAtMs,
+          STARTUP_GRACE_MS_SYNC,
+        )
+      : { shouldResolve: false, reason: null, errorMsg: null };
+    if (bootstrapFailure.shouldResolve) {
+      changes.push({ label: name, from: 'running', to: 'error', reason: bootstrapFailure.reason });
+      if (!dryRun) {
+        setLabel(name, {
+          status: 'error',
+          error: bootstrapFailure.errorMsg,
+          summary: `Synced as spawn failure: ${bootstrapFailure.reason}`,
+        });
+        disarmWatchdog(name);
+      }
+      continue;
+    }
 
     // -- Heartbeat-based liveness guard (mirrors cmdStatus logic) ---------
     // Skip auto-resolve when the watcher's lastPing heartbeat is fresh.
@@ -1412,32 +1659,62 @@ function cmdResult(flags) {
     return;
   }
 
-  // Try to get the session transcript to find last assistant message
+  // Conservative transcript recovery:
+  // - lastReply is ONLY populated from a terminal JSONL-scoped assistant reply
+  // - diagnosticReply captures the last meaningful assistant text for timeout reporting
   let lastReply = null;
+  let diagnosticReply = null;
+  let recoverySource = null;
+  let recoverySessionId = entry.sessionId || null;
+  const resultAgent = entry.agent || agentFromSessionKey(entry.sessionKey) || 'main';
+  const resultStore = entry.sessionKey ? readSessionsStore(resultAgent) : null;
+  const resultSessionEntry = entry.sessionKey && resultStore ? resultStore[entry.sessionKey] : null;
+
+  if (resultSessionEntry?.sessionId) {
+    recoverySessionId = resultSessionEntry.sessionId;
+    if (entry.sessionId !== recoverySessionId) {
+      setLabel(label, { sessionId: recoverySessionId });
+    }
+  }
+
+  if (recoverySessionId) {
+    const jsonlEntries = readJsonlTailEntries(recoverySessionId, resultAgent, 200);
+    const terminalReply = extractTerminalAssistantReplyFromEntries(jsonlEntries);
+    const jsonlDiagnostic = extractLastMeaningfulAssistantReplyFromEntries(jsonlEntries);
+
+    if (terminalReply) {
+      lastReply = terminalReply;
+      recoverySource = 'jsonl-terminal';
+    }
+    if (jsonlDiagnostic) {
+      diagnosticReply = jsonlDiagnostic;
+      if (!recoverySource) recoverySource = 'jsonl-diagnostic';
+    }
+  }
+
   if (entry.sessionKey) {
     try {
       const result = gatewayCall('chat.history', {
         sessionKey: entry.sessionKey,
       }, { timeout: 10000 });
 
-      if (result?.messages?.length) {
-        for (let i = result.messages.length - 1; i >= 0; i--) {
-          const e = result.messages[i];
-          if (e.role === 'assistant' && e.content) {
-            lastReply = typeof e.content === 'string'
-              ? e.content
-              : Array.isArray(e.content)
-                ? e.content.map(c => c.text || '').join('')
-                : JSON.stringify(e.content);
-            break;
-          }
+      if (result?.messages?.length && !diagnosticReply) {
+        diagnosticReply = extractLastMeaningfulAssistantReplyFromEntries(result.messages);
+        if (diagnosticReply && !recoverySource) recoverySource = 'history-diagnostic';
+      }
+
+      if (!lastReply && result?.messages?.length) {
+        const historyTerminal = extractTerminalAssistantReplyFromEntries(result.messages);
+        if (historyTerminal) {
+          lastReply = historyTerminal;
+          recoverySource = 'history-terminal';
         }
       }
     } catch {}
   }
 
   // -- Watchdog cleanup: disable watchdog job when result is available --
-  if (lastReply && entry.watchdogJobId) {
+  if ((lastReply || hasCompletionSignal(entry.completion)) && entry.watchdogJobId) {
     disarmWatchdog(label);
   }
 
@@ -1449,11 +1726,64 @@ function cmdResult(flags) {
     spawnedAt:  entry.spawnedAt,
     summary:    entry.summary || (lastReply ? lastReply.slice(0, 500) : null),
     completion: entry.completion || null,
+    delivery:   buildDispatchDeliverySurface(entry),
     lastReply:  lastReply || null,
+    diagnosticReply: diagnosticReply || lastReply || null,
+    recovery: recoverySource || recoverySessionId ? {
+      source: recoverySource || null,
+      sessionId: recoverySessionId || null,
+    } : null,
     error:      entry.error || null,
   });
 }
 
+
+function cmdWatcherHandoff(flags) {
+  const label = flags.label;
+  const reason = flags.reason || null;
+  if (!label) die('--label is required', 2);
+
+  const entry = getLabel(label);
+  if (!entry) {
+    out({ ok: false, scheduled: false, label, message: 'No session found for this label' });
+    return;
+  }
+
+  if (entry.status && entry.status !== 'running') {
+    out({ ok: true, scheduled: false, label, reason: 'label already terminal', status: entry.status });
+    return;
+  }
+
+  if (!entry.deliverTo || entry.deliveryMode === 'none') {
+    out({ ok: true, scheduled: false, label, reason: 'delivery disabled for this label' });
+    return;
+  }
+
+  const agentBrand = config.agents?.[entry.agent || 'main']?.name
+    || (entry.agent && entry.agent !== 'main' ? entry.agent : null)
+    || config.name
+    || BRAND;
+
+  const watcherJob = scheduleDeliveryWatcherJob({
+    label,
+    deliverTo: entry.deliverTo,
+    deliverChannel: entry.deliverChannel || 'telegram',
+    timeoutSeconds: Number(entry.timeoutSeconds ?? entry.timeout) || 300,
+    idleThresholdSeconds: Number(entry.idleThresholdSeconds) || 300,
+    origin: entry.origin || 'system',
+    agentBrand,
+    nameSuffix: `:handoff:${Date.now()}`,
+  });
+
+  out({
+    ok: true,
+    scheduled: true,
+    label,
+    jobId: watcherJob?.id || null,
+    reason,
+  });
+}
+
 /**
  * done -- agent-side completion signal (push-based).
  * Called by the subagent itself as its LAST action when fully complete.
@@ -1518,15 +1848,15 @@ async function cmdDone(flags) {
     }
   }
 
-  // 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.
+  // Persist a first-class completion payload with deterministic delivery text
+  // so the watcher/post-office path never depends solely on transcript recovery
+  // or on whatever raw blob the model chose to print at the end.
   const completion = buildTerminalCompletionPayload({
     summary: rawSummary,
     checklist,
     sha,
   });
-  const summary = completion.summary || rawSummary;
+  const summary = completion.summary || null;
 
   const existing = getLabel(label);
 
@@ -1659,6 +1989,7 @@ async function cmdDone(flags) {
         duration_ms: 0,
         session_key: null,
         summary,
+        completion,
         deliverTo,
         deliveryChannel,
       }).catch(() => {});
@@ -1690,6 +2021,8 @@ async function cmdDone(flags) {
     status:      'ok',
     duration_ms: Date.now() - spawnedAtMs,
     session_key: existing.sessionKey || null,
+    summary,
+    completion,
   }).catch(() => {});
 
   out({ ok: true, label, status: 'done', summary, completion, message: 'Label marked done via agent signal.' });
@@ -1699,16 +2032,31 @@ async function cmdDone(flags) {
  * send / steer -- send a message into a running session.
  *
  * Flags:
- *   --label <string>     Required (unless --session-key)
- *   --message <string>   Required. Message to send
- *   --session-key <key>  Optional. Direct session key (bypasses label lookup)
+ *   --label <string>      Required (unless --session-key)
+ *   --message <string>    Message to send
+ *   --message-file <path> Read message text from a file (`-` = stdin)
+ *   --message-env <VAR>   Read message text from an environment variable
+ *   --message-stdin       Read message text from stdin explicitly
+ *                         (stdin is also auto-read when piped and no other message source is set)
+ *   --session-key <key>   Optional. Direct session key (bypasses label lookup)
  */
 async function cmdSend(flags) {
-  const label     = flags.label;
-  const message   = flags.message;
+  const label = flags.label;
   const directKey = flags['session-key'];
+  let message = null;
 
-  if (!message) die('--message is required', 2);
+  try {
+    message = await resolveMessageInput({
+      message: flags.message,
+      messageFile: flags['message-file'],
+      messageEnv: flags['message-env'],
+      messageStdin: flags['message-stdin'],
+    });
+  } catch (err) {
+    die(err.message, 2);
+  }
+
+  if (message === null || message.length === 0) die('--message, --message-file, --message-env, --message-stdin, or piped stdin is required', 2);
   if (!label && !directKey) die('--label or --session-key is required', 2);
 
   let sessionKey = directKey;
@@ -1807,6 +2155,7 @@ function cmdList(flags) {
   let entries = Object.entries(labels).map(([name, data]) => ({
     label: name,
     ...data,
+    delivery: buildDispatchDeliverySurface(data),
   }));
 
   if (filterStatus) {
@@ -1833,13 +2182,15 @@ ${BRAND} -- sub-agent dispatch CLI (native gateway API)
 Usage: openclaw-scheduler <subcommand> [flags]
 
 Subcommands:
-  enqueue  --label <l> --message <m>|--message-file <f> [--agent <a>] [--thinking <t>]
-           [--timeout <s>] [--mode fresh|reuse] [--model <m>]
-           [--origin <o>]  (auto-detected from active session; override with e.g. "telegram:<your-group-id>")
+  enqueue  --label <l> [--message <m>|--message-file <f>|--message-env <VAR>|--message-stdin]
+           [--agent <a>] [--thinking <t>] [--timeout <s>] [--mode fresh|reuse] [--model <m>]
+           [--origin <o>]  (recommended explicit value, e.g. "telegram:<chat_id>" or "system")
            [--deliver-to <id>] [--deliver-channel <ch>] [--delivery-mode <m>]
-           (--deliver-to defaults to origin chat ID when --origin is "telegram:<id>")
+           (--deliver-to should come from inbound metadata chat_id; explicit --deliver-to becomes origin when --origin is omitted)
+           (active-session auto-detect is preserved only as a manual/local fallback)
            [--no-monitor] [--monitor-interval <cron>] [--monitor-timeout <min>]
            [--verify-cmd <shell_cmd>]
+           (stdin is auto-read when piped and no explicit message source is set)
 
   status   --label <l>
 
@@ -1847,9 +2198,13 @@ Subcommands:
 
   result   --label <l>
 
-  send     --label <l> --message <m> [--session-key <k>]
+  watcher-handoff --label <l> [--reason <text>]
+
+  send     --label <l> [--message <m>|--message-file <f>|--message-env <VAR>|--message-stdin]
+           [--session-key <k>]
 
-  steer    --label <l> --message <m>  (alias for send)
+  steer    --label <l> [--message <m>|--message-file <f>|--message-env <VAR>|--message-stdin]
+           (alias for send)
 
   heartbeat --label <l>  OR  --session-key <k>
 
@@ -1871,6 +2226,7 @@ switch (subcommand) {
   case 'status':    cmdStatus(flags);          break;
   case 'stuck':     await cmdStuck(flags);     break;
   case 'result':    cmdResult(flags);          break;
+  case 'watcher-handoff': cmdWatcherHandoff(flags); break;
   case 'send':      await cmdSend(flags);      break;
   case 'steer':     await cmdSend(flags);      break;
   case 'heartbeat': cmdHeartbeat(flags);       break;