openclaw-scheduler 0.2.1 → 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,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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

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.' });
 }
 
 /**

package/dispatch/watcher.mjs

@@ -31,6 +31,7 @@ import { readFileSync, writeFileSync, renameSync, statSync } from 'fs';
 import { dirname, join } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
+import { resolveCompletionDelivery } from './completion.mjs';
 import { sendMessage } from '../messages.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -53,6 +54,7 @@ const ACTIVITY_POLL_MS = 30_000;
  *  so PING_INTERVAL_MS must stay well below PING_STALE_MS (3 * 60_000). */
 const PING_INTERVAL_MS = 60_000; // 60 seconds
 
+
 function getGatewayToken() {
   if (process.env.OPENCLAW_GATEWAY_TOKEN) return process.env.OPENCLAW_GATEWAY_TOKEN;
   try {
@@ -656,6 +658,49 @@ function getJsonlMidTurnReason(sessionId, agentDir = 'main') {
   return null; // Last assistant entry appears to be a complete text reply -- safe to proceed
 }
 
+/**
+ * Read the last assistant entry's stop_reason from the session JSONL.
+ * Returns the stop_reason string (e.g. 'end_turn', 'tool_use') or null if unavailable.
+ *
+ * Uses readJsonlLastLines with n=10 to scan enough history to find the last
+ * assistant message even if several tool_result entries follow it.
+ *
+ * @param {string} sessionId - Internal session UUID
+ * @param {string} agentDir - Agent directory (default: 'main')
+ * @returns {string|null} stop_reason string or null
+ */
+function getSessionStopReason(sessionId, agentDir = 'main') {
+  const lastLines = readJsonlLastLines(sessionId, agentDir, 10);
+  if (!lastLines) return null;
+  // Walk backwards to find last role=assistant entry
+  for (let i = lastLines.length - 1; i >= 0; i--) {
+    const entry = lastLines[i];
+    if (entry?.role === 'assistant') {
+      return entry?.stop_reason ?? null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns true if the session has cleanly finished with stop_reason=end_turn.
+ * Requires:
+ *   - stop_reason === 'end_turn' on the last assistant entry
+ *   - getJsonlMidTurnReason() returns null (no in-flight tool calls or pending results)
+ *
+ * Used for Path 2a early delivery: skip FLAT_WINDOW_MS wait when session is
+ * verifiably done via JSONL stop_reason signal.
+ *
+ * @param {string} sessionId - Internal session UUID
+ * @param {string} agentDir - Agent directory (default: 'main')
+ * @returns {boolean}
+ */
+function isSessionCleanlyFinished(sessionId, agentDir = 'main') {
+  if (getJsonlMidTurnReason(sessionId, agentDir) !== null) return false;
+  const stopReason = getSessionStopReason(sessionId, agentDir);
+  return stopReason === 'end_turn';
+}
+
 /**
  * Update labels.json to mark the watched label as done (best-effort, atomic write).
  * Called before exit to ensure labels.json is reconciled even if sync fails.
@@ -698,7 +743,7 @@ function markLabelError(label, errorSummary) {
  * If the verify command exits non-zero, the job is marked as error and
  * an alert is written to stdout (delivery target receives the failure notice).
  */
-function deliverResult(label, lastReply, fallbackSummary) {
+function deliverResult(label, lastReply, fallbackSummary, completionPayload = null) {
   // -- verify-cmd check -----------------------------------------------------
   // Run the stored verify-cmd (if any) before declaring the job done.
   // A non-zero exit flips the job to error state and sends an alert instead.
@@ -732,20 +777,21 @@ function deliverResult(label, lastReply, fallbackSummary) {
   }
 
   // Update labels.json before exiting -- prevents stuck detector false positives
-  const summary = fallbackSummary || (lastReply ? lastReply.slice(0, 500) : null);
-  markLabelDone(label, summary);
+  const completion = resolveCompletionDelivery({
+    lastReply,
+    completion: completionPayload,
+    fallbackSummary,
+  });
+  markLabelDone(label, completion.summary);
 
-  if (lastReply) {
+  if (completion.deliveryText) {
     const maxLen = 3500;
-    const reply = lastReply.length > maxLen
-      ? lastReply.slice(0, maxLen) + '\n\n..[truncated]'
-      : lastReply;
+    const reply = completion.deliveryText.length > maxLen
+      ? completion.deliveryText.slice(0, maxLen) + '\n\n..[truncated]'
+      : completion.deliveryText;
     process.stdout.write(`🌶️ *dispatch* [${label}] completed:\n\n${reply}\n`);
   } else {
-    process.stdout.write(
-      `🌶️ *dispatch* [${label}] completed (no reply captured)\n` +
-      `Summary: ${fallbackSummary || 'none'}\n`
-    );
+    process.stderr.write(`[watcher] [${label}] completion delivery suppressed (no meaningful reply or summary)\n`);
   }
   process.exit(0);
 }
@@ -821,6 +867,7 @@ let recoverySessionKey = null;  // captured during polling for steer/kill
 
 // Module-level state accessible by SIGTERM handler
 let lastKnownReply = null;
+let lastKnownCompletion = null;
 
 // -- SIGTERM handler (scheduler kills watcher with SIGTERM before SIGKILL) --
 // Ensures labels.json is updated and a delivery attempt is made even when killed.
@@ -830,9 +877,10 @@ process.on('SIGTERM', () => {
   try {
     const result = dispatch('result', ['--label', label]);
     if (result?.lastReply) lastKnownReply = result.lastReply;
+    if (result?.completion) lastKnownCompletion = result.completion;
   } catch {}
   // deliverResult calls process.exit(0) internally
-  deliverResult(label, lastKnownReply, 'interrupted by watcher timeout');
+  deliverResult(label, lastKnownReply, 'interrupted by watcher timeout', lastKnownCompletion);
 });
 
 // -- Rolling deadline vars ------------------------------------
@@ -1007,7 +1055,7 @@ while (Date.now() < deadline) {
     // If the session DID produce a lastReply before being killed, deliver it normally.
     if (sessionEverFound && isGatewayRestartKill(status.summary)) {
       const gwCheckResult = dispatch('result', ['--label', label]);
-      if (!gwCheckResult?.lastReply) {
+      if (!gwCheckResult?.lastReply && !gwCheckResult?.completion?.deliveryText) {
         // No result captured -- session was killed before completing
         const retryCount = getGwRestartRetryCount(label);
         if (retryCount >= MAX_GW_RESTART_RETRIES) {
@@ -1046,7 +1094,7 @@ while (Date.now() < deadline) {
           process.exit(1);
         }
       }
-      // lastReply present -- session completed before/during kill; fall through to normal delivery
+      // lastReply or completion payload present -- session completed before/during kill; fall through to normal delivery
     }
 
     // Reset gw-restart retry count on successful completion
@@ -1082,7 +1130,23 @@ while (Date.now() < deadline) {
       }
     }
     const result = dispatch('result', ['--label', label]);
-    deliverResult(label, result?.lastReply, status.summary);
+    deliverResult(label, result?.lastReply, status.summary, result?.completion || status?.completion || null);
+  }
+
+  // -- Path 2a: stop_reason early delivery (clean end_turn) --
+  // If the last assistant message has stop_reason=end_turn and no tool calls
+  // are in flight, deliver immediately without waiting for FLAT_WINDOW_MS.
+  // This is the fast path for sessions that write stop_reason to JSONL.
+  if (status.sessionKey) {
+    const _e2a = getSessionStoreEntry(status.sessionKey);
+    const _sid2a = _e2a?.sessionId || null;
+    const _adir2a = (status.sessionKey.split(':')[1]) || 'main';
+    if (_sid2a && isSessionCleanlyFinished(_sid2a, _adir2a)) {
+      process.stderr.write(`[watcher] stop_reason=end_turn detected -- delivering early\n`);
+      const result = dispatch('result', ['--label', label]);
+      deliverResult(label, result?.lastReply, 'completed (stop_reason=end_turn)', result?.completion || null);
+      // deliverResult exits
+    }
   }
 
   // -- Path 2: status says 'running' but session may be idle -
@@ -1094,8 +1158,8 @@ while (Date.now() < deadline) {
   const ageMs = status.liveness?.ageMs;
   if (ageMs != null && ageMs >= IDLE_RESULT_CHECK_MS) {
     const result = dispatch('result', ['--label', label]);
-    if (result?.lastReply) {
-      deliverResult(label, result.lastReply, null);
+    if (result?.lastReply || result?.completion?.deliveryText) {
+      deliverResult(label, result?.lastReply || null, null, result?.completion || null);
     }
   }
 
@@ -1106,16 +1170,15 @@ while (Date.now() < deadline) {
 // Timed out -- try one last result check
 const finalResult = dispatch('result', ['--label', label]);
 const finalStatus = dispatch('status', ['--label', label]);
-if (finalResult?.lastReply) {
+if (finalStatus?.status === 'done') {
   const rc = getRetryCount(label);
   if (rc > 0) setRetryCount(label, 0);
-  deliverResult(label, finalResult.lastReply, finalStatus?.summary || null);
-}
-// If status is explicitly done, exit cleanly even without lastReply
-if (finalStatus?.status === 'done') {
-  markDoneSync(finalStatus?.summary || 'completed');
-  process.stdout.write(`✅ dispatch [${label}] completed (status=done, no lastReply captured)\n`);
-  process.exit(0);
+  deliverResult(
+    label,
+    finalResult?.lastReply || null,
+    finalStatus?.summary || null,
+    finalResult?.completion || finalStatus?.completion || null,
+  );
 }
 // If status is interrupted (auto-resolved as incomplete), exit non-zero
 if (finalStatus?.status === 'interrupted') {
@@ -1174,9 +1237,9 @@ if (sessionInternalId) {
 // If the session already completed (gateway pruned it -> null tokens), exit cleanly.
 if (statusAtDeadline?.status === 'done' || baselineTokens === null) {
   const r = dispatch('result', ['--label', label]);
-  if (r?.lastReply) {
+  if (r?.lastReply || r?.completion?.deliveryText) {
     // deliverResult calls process.exit(0) internally
-    deliverResult(label, r.lastReply, statusAtDeadline?.summary || null);
+    deliverResult(label, r?.lastReply || null, statusAtDeadline?.summary || null, r?.completion || null);
   }
   // Status is explicitly done -- exit cleanly, no timeout noise
   if (statusAtDeadline?.status === 'done') {
@@ -1211,12 +1274,12 @@ while (Date.now() - flatSince < FLAT_WINDOW_MS) {
   if (st?.status === 'done') {
     const r = dispatch('result', ['--label', label]);
     // deliverResult calls process.exit(0) internally
-    deliverResult(label, r?.lastReply, st.summary);
+    deliverResult(label, r?.lastReply || null, st.summary, r?.completion || st?.completion || null);
   }
   const r2 = dispatch('result', ['--label', label]);
-  if (r2?.lastReply) {
+  if (r2?.lastReply || r2?.completion?.deliveryText) {
     // deliverResult calls process.exit(0) internally
-    deliverResult(label, r2.lastReply, null);
+    deliverResult(label, r2?.lastReply || null, null, r2?.completion || null);
   }
 
   // Token growth?
@@ -1305,12 +1368,12 @@ if (sessionInternalId) {
       if (stExt?.status === 'done') {
         const rExt = dispatch('result', ['--label', label]);
         // deliverResult calls process.exit(0) internally
-        deliverResult(label, rExt?.lastReply, stExt.summary);
+        deliverResult(label, rExt?.lastReply || null, stExt.summary, rExt?.completion || stExt?.completion || null);
       }
       const rExt2 = dispatch('result', ['--label', label]);
-      if (rExt2?.lastReply) {
+      if (rExt2?.lastReply || rExt2?.completion?.deliveryText) {
         // deliverResult calls process.exit(0) internally
-        deliverResult(label, rExt2.lastReply, null);
+        deliverResult(label, rExt2?.lastReply || null, null, rExt2?.completion || null);
       }
 
       // JSONL mtime check during extended wait
@@ -1362,12 +1425,12 @@ for (const round of steerRounds) {
   if (st2?.status === 'done') {
     const r3 = dispatch('result', ['--label', label]);
     // deliverResult calls process.exit(0) internally
-    deliverResult(label, r3?.lastReply, st2.summary);
+    deliverResult(label, r3?.lastReply || null, st2.summary, r3?.completion || st2?.completion || null);
   }
   const r3 = dispatch('result', ['--label', label]);
-  if (r3?.lastReply) {
+  if (r3?.lastReply || r3?.completion?.deliveryText) {
     // deliverResult calls process.exit(0) internally
-    deliverResult(label, r3.lastReply, null);
+    deliverResult(label, r3?.lastReply || null, null, r3?.completion || null);
   }
 
   if (!round.msg && steerSessionKey) {
@@ -1380,8 +1443,8 @@ for (const round of steerRounds) {
       if (st3?.status === 'done') {
         // Check if a result was captured before marking as error
         const r4 = dispatch('result', ['--label', label]);
-        if (r4?.lastReply) {
-          deliverResult(label, r4.lastReply, st3.summary); // deliverResult calls process.exit(0)
+        if (r4?.lastReply || r4?.completion?.deliveryText) {
+          deliverResult(label, r4?.lastReply || null, st3.summary, r4?.completion || st3?.completion || null); // deliverResult calls process.exit(0)
         }
         markLabelError(label, 'timed out -- killed after steer attempts (no result captured)');
         process.stdout.write(`⏱ dispatch [${label}] killed after steer attempts -- no result captured\n`);

package/dispatcher-strategies.js

@@ -1083,7 +1083,10 @@ export async function executeAgent(job, ctx, deps) {
   // the warm session. This avoids full agent bootstrap on every dispatch --
   // memory search, plugin init, and context loading only happen on the first
   // run. Later runs get a pre-warmed session with context already loaded.
-  const sessionKey = job.preferred_session_key || `scheduler:${job.id}`;
+  const requestedSessionKey = job.preferred_session_key || `scheduler:${job.id}`;
+  const sessionKey = requestedSessionKey.startsWith('agent:')
+    ? requestedSessionKey
+    : `agent:${job.agent_id || 'main'}:${requestedSessionKey}`;
   updateRunSession(ctx.run.id, sessionKey, null);
 
   // Mark agent as busy
@@ -1119,6 +1122,37 @@ export async function executeAgent(job, ctx, deps) {
     }
   }
 
+  // Always sync the live auth store to the agent's auth-profiles.json BEFORE
+  // every agent turn. This ensures sessions that reuse a stable key (scheduler:<jobId>)
+  // always have fresh credentials -- token refreshes, order changes, and new
+  // profiles are picked up automatically without requiring an explicit auth_profile
+  // on every job.
+  const { syncAuthStoreToSession: syncAuth } = deps;
+  if (typeof syncAuth === 'function') {
+    const syncResult = syncAuth(job.agent_id || 'main');
+    if (syncResult.ok) {
+      log('debug', `Synced live auth store to agent '${job.agent_id || 'main'}'`, { jobId: job.id });
+    } else {
+      log('warn', `Failed to sync auth store: ${syncResult.error}`, { jobId: job.id });
+    }
+  }
+
+  // Apply auth profile to session store BEFORE the agent turn.
+  // The x-openclaw-auth-profile HTTP header is not read by the gateway (dead header).
+  // Writing authProfileOverride directly to sessions.json is the effective mechanism
+  // for auth profile propagation to isolated/embedded sessions.
+  if (resolvedAuthProfile && resolvedAuthProfile !== 'inherit') {
+    const { applyAuthProfileToSessionStore: applyAuthProfile } = deps;
+    if (typeof applyAuthProfile === 'function') {
+      const applyResult = applyAuthProfile(sessionKey, resolvedAuthProfile, job.agent_id || 'main');
+      if (applyResult.ok) {
+        log('debug', `Applied auth profile '${resolvedAuthProfile}' to session store for ${sessionKey}`, { jobId: job.id });
+      } else {
+        log('warn', `Failed to apply auth profile to session store: ${applyResult.error}`, { jobId: job.id, sessionKey });
+      }
+    }
+  }
+
   const turnResult = await runAgentTurnWithActivityTimeout({
     message: prompt,
     agentId: job.agent_id || 'main',

package/dispatcher.js

@@ -53,6 +53,8 @@ import { upsertAgent, setAgentStatus } from './agents.js';
 import {
   runAgentTurnWithActivityTimeout, sendSystemEvent, getAllSubAgentSessions, listSessions,
   deliverMessage, checkGatewayHealth, waitForGateway, resolveDeliveryAlias,
+  applyAuthProfileToSessionStore,
+  syncAuthStoreToSession,
 } from './gateway.js';
 import { normalizeShellResult } from './shell-result.js';
 import {
@@ -307,6 +309,8 @@ function buildDispatchDeps() {
     updateContextSummary, releaseIdempotencyKey,
     matchesSentinel, detectTransientError,
     listSessions,
+    applyAuthProfileToSessionStore,
+    syncAuthStoreToSession,
     // Finalize
     updateIdempotencyResultHash,
     shouldRetry, scheduleRetry,
@@ -378,11 +382,22 @@ function buildJobPrompt(job, run) {
     );
   }
 
-  // Include any pending messages for this agent
+  // Include any pending messages for this agent.
+  // getInbox() without includeDelivered already filters to status='pending' only,
+  // but we add an explicit guard here to log and skip any message that slipped
+  // through with status='delivered' or 'read' -- re-displaying such messages
+  // would cause duplicate notifications when the inbox-consumer later picks them up.
   const inbox = getInbox(job.agent_id || 'main', { limit: 5 });
-  if (inbox.length > 0) {
+  const injectableMessages = inbox.filter(msg => {
+    if (msg.status && msg.status !== 'pending') {
+      log('warn', `buildJobPrompt: skipping non-pending message ${msg.id} (status=${msg.status}) for agent ${job.agent_id || 'main'}`);
+      return false;
+    }
+    return true;
+  });
+  if (injectableMessages.length > 0) {
     parts.push('\n--- Pending Messages ---');
-    for (const msg of inbox) {
+    for (const msg of injectableMessages) {
       const kindLabel = msg.kind && !['text', 'result', 'status', 'system', 'spawn'].includes(msg.kind)
         ? `[${msg.kind}]${msg.owner ? ` (owner: ${msg.owner})` : ''} `
         : '';
@@ -402,7 +417,7 @@ function buildJobPrompt(job, run) {
 
   // Collect context metadata
   const contextMeta = {
-    messages_injected: inbox.length,
+    messages_injected: injectableMessages.length,
     scope: job.payload_scope || 'own',
     job_class: job.job_class || 'standard',
     delivery_guarantee: job.delivery_guarantee || 'at-most-once',

package/gateway.js

@@ -1,6 +1,6 @@
 // Gateway API client -- independent dispatch via chat completions + system events
 import { execFileSync } from 'child_process';
-import { readFileSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { getDb } from './db.js';
@@ -471,3 +471,119 @@ export async function waitForGateway(timeoutMs = 30000, intervalMs = 2000) {
   }
   return false;
 }
+
+/**
+ * Write authProfileOverride directly to the gateway's sessions.json store.
+ *
+ * The gateway reads sessions.json on each agent turn (with mtime-based cache
+ * invalidation), so writing here before dispatch ensures the embedded runner
+ * picks up the correct auth profile.
+ *
+ * The x-openclaw-auth-profile HTTP header sent by runAgentTurnWithActivityTimeout
+ * is NOT read by the gateway (dead header). This direct store write is the
+ * effective mechanism for auth profile propagation to isolated sessions.
+ *
+ * @param {string} sessionKey - Session key as used in the HTTP request (e.g. 'scheduler:<jobId>')
+ * @param {string} authProfile - Auth profile ID (e.g. 'anthropic:gmail')
+ * @param {string} [agentId='main'] - Agent ID for store path resolution
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function applyAuthProfileToSessionStore(sessionKey, authProfile, agentId = 'main') {
+  if (!sessionKey || !authProfile) {
+    return { ok: false, error: 'sessionKey and authProfile are required' };
+  }
+
+  // The gateway may persist session state under either the canonical agent-scoped
+  // key or the flat transport key, depending on which path created the session.
+  // Keep both aliases in sync so isolated scheduler jobs cannot miss the override.
+  const canonicalMatch = sessionKey.match(/^agent:[^:]+:(.+)$/);
+  const canonicalKey = sessionKey.startsWith('agent:')
+    ? sessionKey
+    : `agent:${agentId}:${sessionKey}`;
+  const flatSessionKey = canonicalMatch?.[1] || sessionKey;
+  const keyAliases = Array.from(new Set([canonicalKey, flatSessionKey]));
+  const sessionsPath = join(HOME_DIR, '.openclaw', 'agents', agentId, 'sessions', 'sessions.json');
+
+  try {
+    if (!existsSync(sessionsPath)) {
+      return { ok: false, error: `sessions.json not found at ${sessionsPath}` };
+    }
+
+    const raw = readFileSync(sessionsPath, 'utf-8');
+    const store = JSON.parse(raw);
+
+    const now = Date.now();
+    let changed = false;
+
+    for (const key of keyAliases) {
+      const entry = store[key];
+      if (!entry) {
+        // Session doesn't exist yet -- create a minimal entry.
+        // The gateway will populate the rest on the first agent turn.
+        store[key] = {
+          updatedAt: now,
+          authProfileOverride: authProfile,
+          authProfileOverrideSource: 'user',
+        };
+        changed = true;
+        continue;
+      }
+
+      if (entry.authProfileOverride !== authProfile || entry.authProfileOverrideSource !== 'user') {
+        // Update existing entry
+        entry.authProfileOverride = authProfile;
+        entry.authProfileOverrideSource = 'user';
+        entry.updatedAt = now;
+        // Clear compaction count so the override sticks across compactions
+        delete entry.authProfileOverrideCompactionCount;
+        changed = true;
+      }
+    }
+
+    if (!changed) {
+      return { ok: true };
+    }
+
+    writeFileSync(sessionsPath, JSON.stringify(store), 'utf-8');
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: `Failed to update sessions.json: ${err.message}` };
+  }
+}
+
+/**
+ * Sync the live auth-profiles.json from ~/.openclaw/credentials/ to the agent's
+ * auth store at ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.
+ *
+ * This ensures scheduler sessions always use fresh credentials (tokens, order,
+ * default profile) even when no explicit auth_profile is set on the job.
+ * Without this, sessions created from a stable session key inherit a stale
+ * copy of the auth store that was snapshotted when the session was first created.
+ *
+ * This is a fast file-copy operation (~1ms) and is safe to call before every
+ * agent turn.
+ *
+ * @param {string} [agentId='main'] - Agent ID for store path resolution
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function syncAuthStoreToSession(agentId = 'main') {
+  const livePath = join(HOME_DIR, '.openclaw', 'credentials', 'auth-profiles.json');
+  const agentStorePath = join(HOME_DIR, '.openclaw', 'agents', agentId, 'agent', 'auth-profiles.json');
+
+  try {
+    if (!existsSync(livePath)) {
+      return { ok: false, error: `Live auth store not found at ${livePath}` };
+    }
+
+    // Ensure the agent directory exists
+    const agentDir = join(HOME_DIR, '.openclaw', 'agents', agentId, 'agent');
+    if (!existsSync(agentDir)) {
+      mkdirSync(agentDir, { recursive: true });
+    }
+
+    copyFileSync(livePath, agentStorePath);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: `Failed to sync auth store: ${err.message}` };
+  }
+}

package/jobs.js

@@ -324,7 +324,7 @@ export function validateJobSpec(opts, currentJob = null, mode = 'create') {
     if (!_isExempt && (!merged.delivery_to || String(merged.delivery_to).trim() === '')) {
       throw new Error(
         'delivery_to is required on job insert. Set it to the origin chat_id ' +
-        '(e.g. -5240776892 for AI Assisted Degeneracy, or 484946046 for Alex DM).'
+        '(e.g. -1001234567890 for a group chat, or 987654321 for a personal DM).'
       );
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-scheduler",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "SQLite-backed job scheduler and workflow engine for OpenClaw agents",
   "type": "module",
   "main": "./index.js",
@@ -70,6 +70,7 @@
     "migrate.js",
     "migrate-consolidate.js",
     "paths.js",
+    "provider-registry.js",
     "prompt-context.js",
     "retrieval.js",
     "runs.js",

package/provider-registry.js

@@ -0,0 +1,94 @@
+import { readdir, stat as fsStat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const identityProviders = new Map();
+const authorizationProviders = new Map();
+const proofVerifiers = new Map();
+
+/**
+ * Load provider plugins from a directory. Every *.js file is imported and
+ * its default export registered by type (identity / authorization / proof-verifier).
+ *
+ * TRUST BOUNDARY: This directory is dynamically imported at startup. Only
+ * point SCHEDULER_PROVIDER_PATH at operator-controlled directories. The loader
+ * refuses world-writable directories as a minimal safety net, but the
+ * primary defense is correct deployment configuration.
+ */
+export async function loadProviders(dirPath) {
+  if (!dirPath) return;
+  const absPath = resolve(dirPath);
+
+  // Trust boundary: provider plugins run arbitrary code in the scheduler process.
+  // Refuse to load from world-writable directories to prevent code injection.
+  try {
+    const dirStat = await fsStat(absPath);
+    if ((dirStat.mode & 0o002) !== 0) {
+      console.error(`[provider-registry] REFUSING to load providers: ${absPath} is world-writable (mode 0${(dirStat.mode & 0o777).toString(8)}). Fix permissions or use a trusted directory.`);
+      return;
+    }
+  } catch (err) {
+    console.error(`[provider-registry] Cannot stat provider directory ${absPath}: ${err.message}`);
+    return;
+  }
+
+  const files = await readdir(absPath);
+  const jsFiles = files.filter(f => f.endsWith('.js'));
+
+  for (const file of jsFiles) {
+    const filePath = join(absPath, file);
+    try {
+      const mod = await import(pathToFileURL(filePath).href);
+      const provider = mod.default;
+      if (!provider || !provider.name || !provider.type) {
+        console.warn(`[provider-registry] Skipping ${file}: missing name or type`);
+        continue;
+      }
+      if (provider.type === 'identity') {
+        identityProviders.set(provider.name, provider);
+      } else if (provider.type === 'authorization') {
+        authorizationProviders.set(provider.name, provider);
+      } else if (provider.type === 'proof-verifier') {
+        proofVerifiers.set(provider.name, provider);
+      } else {
+        console.warn(`[provider-registry] Skipping ${file}: unknown type "${provider.type}"`);
+      }
+    } catch (err) {
+      console.error(`[provider-registry] Failed to load ${file}: ${err.message}`);
+    }
+  }
+
+  const total = identityProviders.size + authorizationProviders.size + proofVerifiers.size;
+  console.log(`[provider-registry] Loaded ${total} provider(s) from ${absPath}`);
+}
+
+export function getIdentityProvider(name) {
+  return identityProviders.get(name) || null;
+}
+
+export function getAuthorizationProvider(name) {
+  return authorizationProviders.get(name) || null;
+}
+
+export function getProofVerifier(name) {
+  return proofVerifiers.get(name) || null;
+}
+
+export function hasProvider(name) {
+  return identityProviders.has(name) || authorizationProviders.has(name) || proofVerifiers.has(name);
+}
+
+export function listProviders() {
+  const result = [];
+  for (const [name, p] of identityProviders) result.push({ name, type: p.type });
+  for (const [name, p] of authorizationProviders) result.push({ name, type: p.type });
+  for (const [name, p] of proofVerifiers) result.push({ name, type: p.type });
+  return result;
+}
+
+// For testing: reset all registries
+export function _resetForTesting() {
+  identityProviders.clear();
+  authorizationProviders.clear();
+  proofVerifiers.clear();
+}

package/scripts/inbox-consumer.mjs

@@ -137,12 +137,17 @@ function _formatMessagesDebug(msgs, agentId) {
 }
 
 function selectPendingMessages(db, agentId, limit) {
+  // Only fetch 'pending' messages for user-facing delivery.
+  // Messages with status='delivered' have already been injected into an AI
+  // agent's context prompt (by buildJobPrompt/markDelivered in dispatcher.js)
+  // and must NOT be re-delivered to the user via Telegram — doing so causes
+  // duplicate notifications on every inbox-consumer run.
   return db.prepare(`
     SELECT id, from_agent, to_agent, subject, body, kind, created_at, priority,
            delivery_to, channel
     FROM messages
     WHERE (to_agent = ? OR to_agent = 'broadcast')
-      AND status IN ('pending', 'delivered')
+      AND status = 'pending'
     ORDER BY
       CASE kind
         WHEN 'constraint' THEN 0
@@ -273,8 +278,30 @@ try {
     }, 250);
   });
 
+  // Periodic poll fallback — catches messages that slip through WAL checkpoints.
+  // When SQLite checkpoints the WAL (merges it back into the main DB), the WAL
+  // file is reset and the watcher may miss a subsequent write. This belt-and-
+  // suspenders poll ensures delivery within at most INBOX_POLL_INTERVAL_MS.
+  const pollIntervalMs = parsePositiveInt(process.env.INBOX_POLL_INTERVAL_MS, 60000);
+  const pollInterval = setInterval(async () => {
+    if (draining) return;
+    draining = true;
+    try {
+      const n = await drainOnce(db, { to: deliveryTo, channel, agentId, limit, brand });
+      if (n > 0) {
+        process.stdout.write(`[inbox-consumer] poll fallback delivered ${n} pending message(s)\n`);
+      }
+    } catch (err) {
+      process.stderr.write(`[inbox-consumer] poll fallback error: ${err.message}\n`);
+    } finally {
+      draining = false;
+    }
+  }, pollIntervalMs);
+  process.stdout.write(`[inbox-consumer] poll fallback enabled (interval=${pollIntervalMs}ms)\n`);
+
   const shutdown = (signal) => {
     if (timer) clearTimeout(timer);
+    clearInterval(pollInterval);
     watcher.close();
     process.stdout.write(`[inbox-consumer] ${signal}; exiting\n`);
     process.exit(0);