@tloncorp/openclaw 0.2.0 → 0.4.1

package/dist/src/monitor/index.js

@@ -1,22 +1,36 @@
+import { createTypingCallbacks } from "openclaw/plugin-sdk/channel-runtime";
+import { configureGatewayStatus, gatewayStart } from "@tloncorp/api";
 import { format } from "node:util";
+import { getEffectiveOwnerShip, setEffectiveOwnerShip } from "../effective-owner.js";
+import { getGatewayStatusManager, computeLeaseUntil, ACTIVE_WINDOW_SECS, OFFLINE_REPLY_COOLDOWN_SECS, } from "../gateway-status.js";
+import { registerPersistCallback, syncPendingNudgeFromStore, getPendingNudge, clearPendingNudge, setPendingNudge, isNudgeEligible, } from "../pending-nudge.js";
 import { getTlonRuntime } from "../runtime.js";
 import { setSessionRole } from "../session-roles.js";
 import { createSettingsManager } from "../settings.js";
 import { normalizeShip, parseChannelNest } from "../targets.js";
+import { createTlonTelemetry } from "../telemetry.js";
 import { resolveTlonAccount } from "../types.js";
+import { configureTlonApiWithPoke } from "../urbit/api-client.js";
 import { authenticate } from "../urbit/auth.js";
 import { ssrfPolicyFromAllowPrivateNetwork } from "../urbit/context.js";
-import { configureTlonApiWithPoke } from "../urbit/api-client.js";
 import { sendDm, sendChannelPost } from "../urbit/send.js";
-import { markdownToStory } from "../urbit/story.js";
 import { UrbitSSEClient } from "../urbit/sse-client.js";
+import { markdownToStory } from "../urbit/story.js";
 import { createPendingApproval, formatApprovalRequest, formatApprovalConfirmation, findPendingApproval, removePendingApproval, pruneExpired, formatBlockedList, formatPendingList, isExpired, emojiToApprovalAction, normalizeNotificationId, } from "./approval.js";
 import { setBridge, removeBridge } from "./command-bridge.js";
+import { createComputingPresenceTracker } from "./computing-presence.js";
 import { fetchAllChannels, fetchInitData } from "./discovery.js";
-import { cacheMessage, lookupCachedMessage, getChannelHistory, fetchThreadHistory } from "./history.js";
-import { downloadMessageImages } from "./media.js";
+import { cacheMessage, lookupCachedMessage, getChannelHistory, fetchChannelHistory, fetchThreadHistory, } from "./history.js";
+import { downloadMessageImages, parseBlobData, formatBlobAnnotations, downloadBlobAttachments, } from "./media.js";
+import { createNudgeRunner, shouldStartNudgeRunner } from "./nudge-runner.js";
+import { clearShadowsForAccount, getLastNudgeStageShadow, getLastOwnerActivity, ownerActivityFromSettings, setLastNudgeStageShadow, setLastOwnerActivity, } from "./nudge-state.js";
+import { createOwnerReplyPersistenceQueue } from "./owner-reply-persistence.js";
+import { createPendingNudgePersistenceQueue } from "./pending-nudge-persistence.js";
 import { createProcessedMessageTracker } from "./processed-messages.js";
+import { resolveSettingsMirrorSync } from "./settings-sync.js";
 import { extractMessageText, extractCites, formatModelName, isBotMentioned, stripBotMention, isDmAllowed, isSummarizationRequest, sanitizeMessageText, } from "./utils.js";
+/** Refresh stale settings subscription state periodically as a fallback for silently-dead SSE subscriptions. */
+const SETTINGS_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
 /**
  * Extract ship from author field, handling both string (ship) and object (bot-meta) formats.
  */
@@ -123,15 +137,14 @@ export async function monitorTlonProvider(opts = {}) {
     });
     // Configure @tloncorp/api's global client to use the SSE client's poke for all send operations
     configureTlonApiWithPoke(api.poke.bind(api), botShipName, account.url);
+    const computingPresence = createComputingPresenceTracker({ runtime });
     const processedTracker = createProcessedMessageTracker(2000);
     let groupChannels = [];
     const channelToGroup = new Map();
     let botNickname = null;
     let botAvatar = null;
     // Helper to get bot profile for outbound messages
-    const getBotProfile = () => botNickname || botAvatar
-        ? { nickname: botNickname || "", avatar: botAvatar || "" }
-        : undefined;
+    const getBotProfile = () => botNickname || botAvatar ? { nickname: botNickname || "", avatar: botAvatar || "" } : undefined;
     // Settings store manager for hot-reloading config
     const settingsManager = createSettingsManager(api, {
         log: (msg) => runtime.log?.(msg),
@@ -147,8 +160,28 @@ export async function monitorTlonProvider(opts = {}) {
     let effectiveOwnerShip = account.ownerShip
         ? normalizeShip(account.ownerShip)
         : null;
+    setEffectiveOwnerShip(account.accountId, effectiveOwnerShip);
     let pendingApprovals = [];
     let currentSettings = {};
+    // Tracks whether pendingNudge has been successfully rehydrated from the settings
+    // store (or locally set/cleared). While false, refresh is allowed to recover a
+    // persisted pendingNudge that was missed due to a transient startup scry failure.
+    // Once true, the in-memory state is authoritative and refresh cannot clobber it.
+    let pendingNudgeRehydrated = false;
+    /** Set pending nudge and take ownership so refresh cannot clobber. */
+    const setLocalPendingNudge = (accountId, nudge) => {
+        setPendingNudge(accountId, nudge);
+        pendingNudgeRehydrated = true;
+    };
+    /** Clear pending nudge and take ownership so refresh cannot resurrect stale store data. */
+    const clearLocalPendingNudge = (accountId) => {
+        clearPendingNudge(accountId);
+        pendingNudgeRehydrated = true;
+    };
+    const telemetry = createTlonTelemetry({
+        config: account.telemetry,
+        runtime,
+    });
     // Track threads we've participated in (by parentId) - respond without mention requirement
     const participatedThreads = new Set();
     // Track consecutive bot responses per channel/DM for rate limiting
@@ -165,14 +198,15 @@ export async function monitorTlonProvider(opts = {}) {
     // Sanitize nickname to prevent format injection
     function sanitizeNickname(nickname) {
         return nickname
-            .replace(/[\[\]()]/g, "") // Remove format-breaking chars
+            .replace(/[[\]()]/g, "") // Remove format-breaking chars
             .slice(0, 50); // Reasonable length limit
     }
     // Format a ship with nickname if available
     function formatShipWithNickname(ship) {
         const nickname = nicknameCache.get(ship);
-        if (!nickname)
+        if (!nickname) {
             return ship;
+        }
         const sanitized = sanitizeNickname(nickname);
         return sanitized ? `${ship} (${sanitized})` : ship;
     }
@@ -194,7 +228,7 @@ export async function monitorTlonProvider(opts = {}) {
     }
     // Fetch all contacts to populate nickname cache
     try {
-        const allContacts = await api.scry("/contacts/v1/all.json");
+        const allContacts = (await api.scry("/contacts/v1/all.json"));
         if (allContacts && typeof allContacts === "object") {
             for (const [ship, contact] of Object.entries(allContacts)) {
                 const nickname = contact?.nickname?.value ?? contact?.nickname;
@@ -303,11 +337,28 @@ export async function monitorTlonProvider(opts = {}) {
             }
         }
     }
+    // Clear stale in-memory pending-nudge state before settings load.
+    // If load fails during a same-process restart, we should not keep attributing
+    // owner replies against a previous monitor run's record.
+    syncPendingNudgeFromStore(account.accountId, null);
+    // Drop stale per-process shadows from any prior run in the same process.
+    // Mirrors the same-process-restart reasoning as the pending-nudge sync above.
+    clearShadowsForAccount(account.accountId);
     // Load settings from settings store (hot-reloadable config)
     try {
-        currentSettings = await settingsManager.load();
-        // Migrate file config to settings store if not already present
-        await migrateConfigToSettings();
+        const loadResult = await settingsManager.load();
+        currentSettings = loadResult.settings;
+        // Only seed file config into %settings when the startup snapshot is fresh.
+        // On a transient startup scry failure, `load()` preserves the last known
+        // snapshot (or `{}` on first load). Running migration against a stale
+        // snapshot would treat every persisted override as absent and clobber it
+        // with file-backed values once the settings agent recovers.
+        if (loadResult.fresh) {
+            await migrateConfigToSettings();
+        }
+        else {
+            runtime.log?.("[tlon] Skipping config->settings migration on stale startup snapshot");
+        }
         // Apply settings overrides
         // Note: groupChannels from settings store are merged AFTER discovery runs (below)
         if (currentSettings.defaultAuthorizedShips?.length) {
@@ -338,8 +389,21 @@ export async function monitorTlonProvider(opts = {}) {
         }
         if (currentSettings.ownerShip) {
             effectiveOwnerShip = normalizeShip(currentSettings.ownerShip);
+            setEffectiveOwnerShip(account.accountId, effectiveOwnerShip);
             runtime.log?.(`[tlon] Using ownerShip from settings store: ${effectiveOwnerShip}`);
         }
+        // Rehydrate pending nudge from settings store only if the scry returned real data.
+        // On fallback (scry failure), leave pendingNudgeRehydrated false so the refresh
+        // recovery path can still pick up a persisted pendingNudge later.
+        if (loadResult.fresh) {
+            syncPendingNudgeFromStore(account.accountId, currentSettings.pendingNudge ?? null);
+            pendingNudgeRehydrated = true;
+        }
+        // Seed nudge shadows from the loaded settings snapshot. Missing fields
+        // seed the shadow as absent / 0 — the tick short-circuits on null
+        // activity, which is correct for a cold startup with an empty store.
+        setLastOwnerActivity(account.accountId, ownerActivityFromSettings(currentSettings));
+        setLastNudgeStageShadow(account.accountId, currentSettings.lastNudgeStage ?? 0);
         if (currentSettings.pendingApprovals?.length) {
             pendingApprovals = currentSettings.pendingApprovals;
             runtime.log?.(`[tlon] Loaded ${pendingApprovals.length} pending approval(s) from settings`);
@@ -348,6 +412,97 @@ export async function monitorTlonProvider(opts = {}) {
     catch (err) {
         runtime.log?.(`[tlon] Settings store not available, using file config: ${String(err)}`);
     }
+    const pendingNudgePersistence = createPendingNudgePersistenceQueue(async (nudge) => {
+        try {
+            if (nudge) {
+                await api.poke({
+                    app: "settings",
+                    mark: "settings-event",
+                    json: {
+                        "put-entry": {
+                            desk: "moltbot",
+                            "bucket-key": "tlon",
+                            "entry-key": "pendingNudge",
+                            value: JSON.stringify(nudge),
+                        },
+                    },
+                });
+            }
+            else {
+                await api.poke({
+                    app: "settings",
+                    mark: "settings-event",
+                    json: {
+                        "del-entry": {
+                            desk: "moltbot",
+                            "bucket-key": "tlon",
+                            "entry-key": "pendingNudge",
+                        },
+                    },
+                });
+            }
+        }
+        catch (err) {
+            runtime.error?.(nudge
+                ? `[tlon] Failed to persist pendingNudge: ${String(err)}`
+                : `[tlon] Failed to clear pendingNudge: ${String(err)}`);
+        }
+    });
+    // Register per-account persist callback for pending nudge writes.
+    registerPersistCallback(account.accountId, (nudge) => {
+        pendingNudgePersistence.enqueue(nudge);
+    });
+    const ownerReplyPersistence = createOwnerReplyPersistenceQueue(api, {
+        error: (msg) => runtime.error?.(msg),
+    });
+    let nudgeRunner = null;
+    // Clear expired pending nudge on startup (after persist callback is registered so del-entry fires).
+    const rehydratedNudge = getPendingNudge(account.accountId);
+    if (rehydratedNudge && !isNudgeEligible(rehydratedNudge)) {
+        const ageMs = Date.now() - rehydratedNudge.sentAt;
+        clearLocalPendingNudge(account.accountId);
+        runtime.log?.(`[tlon] Cleared expired pending nudge on startup (stage ${rehydratedNudge.stage}, age ${ageMs}ms)`);
+    }
+    // ── Gateway-status: non-blocking background activation ──────
+    // getGatewayStatusManager() returns null when multi-account or zero accounts configured
+    // (see index.ts registration gate).
+    const gsManager = getGatewayStatusManager();
+    if (gsManager && effectiveOwnerShip) {
+        const capturedOwnerShip = effectiveOwnerShip;
+        const signal = opts.abortSignal;
+        // Fire-and-forget: wait for gateway_start signal, then activate.
+        // Does NOT block monitor startup — discovery, subscriptions, etc. proceed immediately.
+        void (async () => {
+            try {
+                const raced = await Promise.race([
+                    gsManager.waitForGatewayStart().then(() => "started"),
+                    ...(signal
+                        ? [
+                            new Promise((r) => signal.addEventListener("abort", () => r("aborted"), { once: true })),
+                        ]
+                        : []),
+                ]);
+                if (raced !== "started" || gsManager.stopped) {
+                    return;
+                }
+                await configureGatewayStatus({
+                    owner: capturedOwnerShip,
+                    activeWindowSecs: ACTIVE_WINDOW_SECS,
+                    offlineReplyCooldownSecs: OFFLINE_REPLY_COOLDOWN_SECS,
+                });
+                await gatewayStart({
+                    bootId: gsManager.bootId,
+                    leaseUntil: computeLeaseUntil(),
+                });
+                gsManager.markActivated();
+                gsManager.startHeartbeat();
+                runtime.log?.(`[gateway-status] activated (bootId=${gsManager.bootId}, owner=${capturedOwnerShip})`);
+            }
+            catch (err) {
+                runtime.error?.(`[gateway-status] start failed: ${String(err)}`);
+            }
+        })();
+    }
     // Run channel discovery AFTER settings are loaded (so settings store value is used)
     if (effectiveAutoDiscoverChannels) {
         try {
@@ -559,10 +714,10 @@ export async function monitorTlonProvider(opts = {}) {
      */
     const SCRY_TIMEOUT_MS = 15_000;
     async function scryBlockedShips() {
-        const blocked = await Promise.race([
+        const blocked = (await Promise.race([
             api.scry("/chat/blocked.json"),
             new Promise((_, reject) => setTimeout(() => reject(new Error("blocked list scry timeout")), SCRY_TIMEOUT_MS)),
-        ]);
+        ]));
         return Array.isArray(blocked) ? blocked : [];
     }
     // Check if a ship is blocked using Tlon's native block list
@@ -591,6 +746,11 @@ export async function monitorTlonProvider(opts = {}) {
     async function unblockShip(ship) {
         const normalizedShip = normalizeShip(ship);
         try {
+            const blocked = await isShipBlocked(normalizedShip);
+            if (!blocked) {
+                runtime.log?.(`[tlon] Ship ${normalizedShip} is not blocked; skipping unblock`);
+                return true;
+            }
             await api.poke({
                 app: "chat",
                 mark: "chat-unblock-ship",
@@ -722,6 +882,7 @@ export async function monitorTlonProvider(opts = {}) {
                             messageContent: approval.originalMessage.messageContent,
                             isGroup: false,
                             timestamp: approval.originalMessage.timestamp,
+                            blobField: approval.originalMessage.blob,
                         });
                     }
                     break;
@@ -743,6 +904,7 @@ export async function monitorTlonProvider(opts = {}) {
                                 timestamp: approval.originalMessage.timestamp,
                                 parentId: approval.originalMessage.parentId,
                                 isThreadReply: approval.originalMessage.isThreadReply,
+                                blobField: approval.originalMessage.blob,
                             });
                         }
                     }
@@ -868,42 +1030,73 @@ export async function monitorTlonProvider(opts = {}) {
         if (isGroup) {
             messageText = stripBotMention(messageText, botShipName);
         }
-        // Track owner interaction timestamp for heartbeat engagement recovery.
-        // Store both epoch ms (for code) and ISO date (for LLM — models can't reliably convert epoch).
+        // Track owner interaction timestamp for the nudge scheduler.
+        // The shadows update synchronously; the durable %settings writes happen
+        // in the background via an ordered queue so the owner-DM hot path never
+        // waits on an Urbit RTT.
         if (isOwner(senderShip)) {
-            const isoDate = new Date(timestamp).toISOString().split("T")[0]; // YYYY-MM-DD
-            Promise.all([
-                api.poke({
-                    app: "settings",
-                    mark: "settings-event",
-                    json: {
-                        "put-entry": {
-                            desk: "moltbot",
-                            "bucket-key": "tlon",
-                            "entry-key": "lastOwnerMessageAt",
-                            value: timestamp,
-                        },
-                    },
-                }),
-                api.poke({
-                    app: "settings",
-                    mark: "settings-event",
-                    json: {
-                        "put-entry": {
-                            desk: "moltbot",
-                            "bucket-key": "tlon",
-                            "entry-key": "lastOwnerMessageDate",
-                            value: isoDate,
-                        },
-                    },
-                }),
-            ])
-                .then(() => {
-                runtime.log?.(`[tlon] Updated lastOwnerMessageAt: ${timestamp} (${isoDate})`);
-            })
-                .catch((err) => {
-                runtime.error?.(`[tlon] Failed to update lastOwnerMessageAt: ${String(err)}`);
+            const isoDate = new Date(timestamp).toISOString().split("T")[0] ?? ""; // YYYY-MM-DD
+            // (1a) Synchronous shadow: owner activity. Updated FIRST so any tick
+            //      that observes both shadows sees "activity-first" ordering.
+            setLastOwnerActivity(account.accountId, { at: timestamp, date: isoDate });
+            // Check for pending nudge re-engagement. Stage is cleared on ANY owner
+            // reply when the stage shadow is non-zero (or pendingNudge is present)
+            // so the next inactivity cycle can send the same stage again. Gating on
+            // `pendingNudge` alone would miss the in-flight-tick race: the scheduler
+            // pokes `lastNudgeStage` and sets the shadow before `sendDm()`, but
+            // only writes `pendingNudge` after the send resolves — so a reply that
+            // lands in that window would otherwise leave the stage stuck.
+            const pending = getPendingNudge(account.accountId);
+            const shadowStage = getLastNudgeStageShadow(account.accountId) ?? 0;
+            const willClearStage = shadowStage > 0 || Boolean(pending);
+            // (1b) Synchronous shadow: stage cleared (only when we'd clear).
+            if (willClearStage) {
+                setLastNudgeStageShadow(account.accountId, 0);
+            }
+            // (2) Enqueue durable writes. The queue awaits the put-entries before
+            //     issuing the del-entry on the wire, closing the crash-consistency
+            //     gap. The handler does NOT await the queue.
+            ownerReplyPersistence.enqueue({
+                at: timestamp,
+                date: isoDate,
+                clearStage: willClearStage,
             });
+            if (pending) {
+                if (isNudgeEligible(pending, timestamp)) {
+                    const reengagedAt = timestamp;
+                    telemetry?.captureHeartbeatReengagement({
+                        ownerShip: pending.ownerShip,
+                        botShip: account.ship ?? "",
+                        nudgeStage: pending.stage,
+                        nudgeSentAt: pending.sentAt,
+                        reengagedAt,
+                        reengagementDelayMs: reengagedAt - pending.sentAt,
+                        channel: "tlon",
+                        accountId: pending.accountId,
+                    });
+                    runtime.log?.(`[tlon] Heartbeat nudge re-engagement: stage ${pending.stage}, delay ${reengagedAt - pending.sentAt}ms`);
+                }
+                else {
+                    runtime.log?.(`[tlon] Pending nudge expired (stage ${pending.stage}, sent ${pending.sentAt})`);
+                }
+                clearLocalPendingNudge(account.accountId);
+            }
+            // Inject reply context for the agent when the reply appears to be a
+            // response to a recent, eligible nudge.
+            //
+            // Restricted to DMs (`!isGroup`). The nudge itself was sent as a DM,
+            // so prefacing a channel/group reply with DM-only context — including
+            // the verbatim nudge `content` — would leak that context into an
+            // unrelated public conversation.
+            if (pending && isNudgeEligible(pending, timestamp) && !isGroup) {
+                const sentIso = new Date(pending.sentAt).toISOString();
+                const contentBlock = pending.content ? `Message content:\n\n${pending.content}\n\n` : "";
+                messageText =
+                    `[Context: You recently sent ${pending.ownerShip} a stage-${pending.stage} ` +
+                        `re-engagement nudge at ${sentIso}. ${contentBlock}` +
+                        `The owner's reply below may be responding to that nudge.]\n\n` +
+                        messageText;
+            }
         }
         // Download any images from the message content
         let attachments = [];
@@ -918,14 +1111,39 @@ export async function monitorTlonProvider(opts = {}) {
                 runtime.log?.(`[tlon] Failed to download images: ${error?.message ?? String(error)}`);
             }
         }
+        // Parse and handle blob attachments (files, voice memos, videos)
+        const blobData = parseBlobData(params.blobField);
+        if (blobData) {
+            // Add text annotations so the agent knows what was attached
+            const blobAnnotations = formatBlobAnnotations(blobData);
+            if (blobAnnotations) {
+                messageText = blobAnnotations + "\n" + messageText;
+                runtime.log?.(`[tlon] Added blob annotations: ${blobAnnotations} attachment(s)`);
+            }
+            // Download blob files as attachments
+            try {
+                const { attachments: blobAttachments, notices: blobDownloadNotices } = await downloadBlobAttachments(blobData);
+                if (blobDownloadNotices.length > 0) {
+                    messageText = blobDownloadNotices.join("\n") + "\n" + messageText;
+                    runtime.log?.(`[tlon] Skipped oversized blob attachment(s): ${blobDownloadNotices.join(" | ")}`);
+                }
+                if (blobAttachments.length > 0) {
+                    attachments = attachments.concat(blobAttachments);
+                    runtime.log?.(`[tlon] Downloaded blob attachment(s) ${JSON.stringify(blobAttachments)}`);
+                }
+            }
+            catch (error) {
+                runtime.log?.(`[tlon] Failed to download blob attachments: ${error?.message ?? String(error)}`);
+            }
+        }
         // Fetch thread context when entering a thread for the first time
         if (isThreadReply && parentId && groupChannel) {
             try {
                 const threadHistory = await fetchThreadHistory(api, groupChannel, parentId, 20, runtime);
                 if (threadHistory.length > 0) {
                     const threadContext = threadHistory
-                        .slice(-10) // Last 10 messages for context
-                        .map((msg) => `${msg.author}: ${sanitizeMessageText(msg.content)}`)
+                        .slice(-20) // Last 20 thread messages for context
+                        .map((msg) => `${formatShipWithNickname(msg.author)}: ${sanitizeMessageText(msg.content)}`)
                         .join("\n");
                     // Prepend thread context to the message
                     // Include note about ongoing conversation for agent judgment
@@ -939,6 +1157,31 @@ export async function monitorTlonProvider(opts = {}) {
                 // Continue without thread context - not critical
             }
         }
+        // Fetch recent channel history on mention (non-thread) so the agent has
+        // context about what the channel has been discussing.
+        if (isGroup && groupChannel && !isThreadReply) {
+            try {
+                const recentHistory = await fetchChannelHistory(api, groupChannel, 20, runtime);
+                if (recentHistory.length > 0) {
+                    // Filter out the current message itself (avoid duplication)
+                    const contextMessages = recentHistory
+                        .filter((msg) => msg.id !== params.messageId)
+                        .slice(0, 20)
+                        .toReversed() // oldest first for natural reading order
+                        .map((msg) => `${formatShipWithNickname(msg.author)}: ${sanitizeMessageText(msg.content)}`)
+                        .join("\n");
+                    if (contextMessages) {
+                        const contextNote = `[Recent channel activity - ${recentHistory.length} messages. Use this context to understand what's being discussed.]`;
+                        messageText = `${contextNote}\n\n${contextMessages}\n\n[Current message (mentioned you)]\n${messageText}`;
+                        runtime?.log?.(`[tlon] Added channel context (${recentHistory.length} messages) to mention in ${groupChannel}`);
+                    }
+                }
+            }
+            catch (error) {
+                runtime?.log?.(`[tlon] Could not fetch channel context: ${error?.message ?? String(error)}`);
+                // Continue without channel context - not critical
+            }
+        }
         if (isGroup && groupChannel && isSummarizationRequest(messageText)) {
             try {
                 const history = await getChannelHistory(api, groupChannel, 50, runtime);
@@ -984,7 +1227,12 @@ export async function monitorTlonProvider(opts = {}) {
                     });
                 }
                 else {
-                    await sendDm({ botProfile: getBotProfile(), fromShip: botShipName, toShip: senderShip, text: errorMsg });
+                    await sendDm({
+                        botProfile: getBotProfile(),
+                        fromShip: botShipName,
+                        toShip: senderShip,
+                        text: errorMsg,
+                    });
                 }
                 return;
             }
@@ -1036,6 +1284,7 @@ export async function monitorTlonProvider(opts = {}) {
         const fromLabel = isGroup
             ? `${senderDisplay} [${senderRole}] in ${channelNest}`
             : `${senderDisplay} [${senderRole}]`;
+        const attachmentCount = attachments.length;
         // Compute command authorization for slash commands (owner-only)
         const shouldComputeAuth = core.channel.commands.shouldComputeCommandAuthorized(messageText, cfg);
         let commandAuthorized = false;
@@ -1074,11 +1323,10 @@ export async function monitorTlonProvider(opts = {}) {
             body: bodyWithAttachments,
         });
         // Use raw text (no thread context) for command detection so "/status" is recognized
-        const commandBody = isGroup
-            ? stripBotMention(rawMessageText, botShipName)
-            : rawMessageText;
+        const commandBody = isGroup ? stripBotMention(rawMessageText, botShipName) : rawMessageText;
         const ctxPayload = core.channel.reply.finalizeInboundContext({
             Body: body,
+            BodyForAgent: bodyWithAttachments,
             RawBody: messageText,
             CommandBody: commandBody,
             From: isGroup ? `tlon:group:${groupChannel}` : `tlon:${senderShip}`,
@@ -1095,86 +1343,196 @@ export async function monitorTlonProvider(opts = {}) {
             Provider: "tlon",
             Surface: "tlon",
             MessageSid: messageId,
-            // Include downloaded media attachments
-            ...(attachments.length > 0 && { Attachments: attachments }),
+            // Include downloaded media attachments (MediaPaths/MediaUrls/MediaTypes for OpenClaw media pipeline)
+            ...(attachments.length > 0 && {
+                MediaPaths: attachments.map((a) => a.path),
+                MediaUrls: attachments.map((a) => a.path),
+                MediaTypes: attachments.map((a) => a.contentType),
+            }),
             OriginatingChannel: "tlon",
             OriginatingTo: `tlon:${isGroup ? groupChannel : senderShip}`,
             // Include thread context for automatic reply routing
             ...(parentId && { MessageThreadId: String(parentId), ReplyToId: String(parentId) }),
         });
         const dispatchStartTime = Date.now();
+        const replyTelemetry = telemetry?.startReply({
+            sessionKey: route.sessionKey,
+            ownerShip: effectiveOwnerShip,
+            botShip: botShipName,
+            chatType: isGroup ? "groupChannel" : "dm",
+            isThreadReply: Boolean(isThreadReply),
+            senderRole,
+            attachmentCount,
+        });
+        let selectedProvider = null;
+        let selectedModel = null;
+        let selectedThinkLevel = null;
+        let deliveredMessageCount = 0;
+        let replyCharCount = 0;
+        let replyWordCount = 0;
+        let replyMediaCount = 0;
         const responsePrefix = core.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId).responsePrefix;
         const humanDelay = core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId);
-        await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-            ctx: ctxPayload,
-            cfg,
-            dispatcherOptions: {
-                responsePrefix,
-                humanDelay,
-                deliver: async (payload) => {
-                    let replyText = payload.text;
-                    if (!replyText) {
-                        return;
-                    }
-                    // Process any block directives in the response (strips them from text)
-                    replyText = await processBlockDirectives(replyText, senderShip);
-                    if (!replyText) {
-                        return;
-                    } // Response was only a directive
-                    // Use settings store value if set, otherwise fall back to file config
-                    const showSignature = effectiveShowModelSig;
-                    if (showSignature) {
-                        const modelCfg = cfg.agents?.defaults?.model;
-                        const modelInfo = payload.metadata?.model ||
-                            payload.model ||
-                            route.model ||
-                            (typeof modelCfg === "string" ? modelCfg : modelCfg?.primary);
-                        replyText = `${replyText}\n\n_[Generated by ${formatModelName(modelInfo)}]_`;
-                    }
-                    // Add addendum if this is the last response before bot rate limit
-                    if (isGroup && groupChannel && knownBotShips.has(senderShip)) {
-                        const count = consecutiveBotMessages.get(groupChannel) ?? 0;
-                        if (maxBotResponses > 0 && count === maxBotResponses) {
-                            const otherBot = formatShipWithNickname(senderShip);
-                            replyText += `\n\n---\n_This is my last response to ${otherBot} for now. To continue our conversation, someone will need to mention me._`;
-                        }
-                    }
-                    if (isGroup && groupChannel) {
-                        // Send to any channel type (chat, heap, diary) using the nest directly
-                        await sendChannelPost({
-                            botProfile: getBotProfile(),
-                            fromShip: botShipName,
-                            nest: groupChannel,
-                            story: markdownToStory(replyText),
-                            replyToId: deliverParentId ?? undefined,
-                        });
-                        // Track thread participation for future replies without mention
-                        if (deliverParentId) {
-                            participatedThreads.add(String(deliverParentId));
-                            runtime.log?.(`[tlon] Now tracking thread for future replies: ${deliverParentId}`);
-                        }
-                    }
-                    else {
-                        await sendDm({
-                            botProfile: getBotProfile(),
-                            fromShip: botShipName,
-                            toShip: senderShip,
-                            text: replyText,
-                            replyToId: deliverParentId ? String(deliverParentId) : undefined,
-                        });
-                    }
+        const presenceConversationId = isGroup ? (groupChannel ?? null) : senderShip;
+        const presenceRunId = String(messageId);
+        const typingCallbacks = presenceConversationId
+            ? createTypingCallbacks({
+                start: async () => {
+                    await computingPresence.refreshRun({
+                        conversationId: presenceConversationId,
+                        runId: presenceRunId,
+                    });
                 },
-                onError: (err, info) => {
-                    const dispatchDuration = Date.now() - dispatchStartTime;
-                    runtime.error?.(`[tlon] ${info.kind} reply failed after ${dispatchDuration}ms: ${String(err)}`);
+                stop: async () => {
+                    await computingPresence.stopRun({
+                        conversationId: presenceConversationId,
+                        runId: presenceRunId,
+                    });
                 },
+                onStartError: (err) => {
+                    runtime.error?.(`[tlon] Failed to start computing presence for ${presenceConversationId}: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+                },
+                onStopError: (err) => {
+                    runtime.error?.(`[tlon] Failed to stop computing presence for ${presenceConversationId}: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+                },
+                keepaliveIntervalMs: 20_000,
+            })
+            : undefined;
+        const replyOptions = {
+            onModelSelected: ({ provider, model, thinkLevel }) => {
+                selectedProvider = provider;
+                selectedModel = model;
+                selectedThinkLevel = thinkLevel ?? null;
             },
-        });
+            ...(presenceConversationId
+                ? {
+                    onAssistantMessageStart: async () => {
+                        await computingPresence.clearToolCalls({
+                            conversationId: presenceConversationId,
+                            runId: presenceRunId,
+                        });
+                    },
+                    onToolStart: async (payload) => {
+                        await computingPresence.addToolCall({
+                            conversationId: presenceConversationId,
+                            runId: presenceRunId,
+                            toolName: payload.name,
+                        });
+                    },
+                }
+                : {}),
+        };
+        let dispatchResult;
+        let dispatchError;
+        try {
+            dispatchResult = await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+                ctx: ctxPayload,
+                cfg,
+                replyOptions,
+                dispatcherOptions: {
+                    responsePrefix,
+                    humanDelay,
+                    typingCallbacks,
+                    deliver: async (payload) => {
+                        let replyText = payload.text;
+                        if (!replyText) {
+                            return;
+                        }
+                        // Process any block directives in the response (strips them from text)
+                        replyText = await processBlockDirectives(replyText, senderShip);
+                        if (!replyText) {
+                            return;
+                        } // Response was only a directive
+                        // Use settings store value if set, otherwise fall back to file config
+                        const showSignature = effectiveShowModelSig;
+                        if (showSignature) {
+                            const modelCfg = cfg.agents?.defaults?.model;
+                            const modelInfo = selectedModel ||
+                                payload.metadata?.model ||
+                                payload.model ||
+                                route.model ||
+                                (typeof modelCfg === "string" ? modelCfg : modelCfg?.primary);
+                            replyText = `${replyText}\n\n_[Generated by ${formatModelName(modelInfo)}]_`;
+                        }
+                        // Add addendum if this is the last response before bot rate limit
+                        if (isGroup && groupChannel && knownBotShips.has(senderShip)) {
+                            const count = consecutiveBotMessages.get(groupChannel) ?? 0;
+                            if (maxBotResponses > 0 && count === maxBotResponses) {
+                                const otherBot = formatShipWithNickname(senderShip);
+                                replyText += `\n\n---\n_This is my last response to ${otherBot} for now. To continue our conversation, someone will need to mention me._`;
+                            }
+                        }
+                        if (isGroup && groupChannel) {
+                            // Send to any channel type (chat, heap, diary) using the nest directly
+                            await sendChannelPost({
+                                botProfile: getBotProfile(),
+                                fromShip: botShipName,
+                                nest: groupChannel,
+                                story: markdownToStory(replyText),
+                                replyToId: deliverParentId ?? undefined,
+                            });
+                            // Track thread participation for future replies without mention
+                            if (deliverParentId) {
+                                participatedThreads.add(String(deliverParentId));
+                                runtime.log?.(`[tlon] Now tracking thread for future replies: ${deliverParentId}`);
+                            }
+                        }
+                        else {
+                            await sendDm({
+                                botProfile: getBotProfile(),
+                                fromShip: botShipName,
+                                toShip: senderShip,
+                                text: replyText,
+                                replyToId: deliverParentId ? String(deliverParentId) : undefined,
+                            });
+                        }
+                        if (presenceConversationId) {
+                            await computingPresence.stopRun({
+                                conversationId: presenceConversationId,
+                                runId: presenceRunId,
+                            });
+                        }
+                        deliveredMessageCount += 1;
+                        replyCharCount += replyText.length;
+                        replyWordCount += replyText.trim() ? replyText.trim().split(/\s+/).length : 0;
+                        replyMediaCount += Array.isArray(payload.mediaUrls)
+                            ? payload.mediaUrls.length
+                            : payload.mediaUrl
+                                ? 1
+                                : 0;
+                    },
+                    onError: (err, info) => {
+                        const dispatchDuration = Date.now() - dispatchStartTime;
+                        runtime.error?.(`[tlon] ${info.kind} reply failed after ${dispatchDuration}ms: ${String(err)}`);
+                    },
+                },
+            });
+        }
+        catch (error) {
+            dispatchError = error;
+            throw error;
+        }
+        finally {
+            await replyTelemetry?.capture({
+                deliveredMessageCount,
+                replyCharCount,
+                replyWordCount,
+                replyMediaCount,
+                dispatchDurationMs: Date.now() - dispatchStartTime,
+                queuedFinal: dispatchResult?.queuedFinal ?? false,
+                queuedFinalCount: dispatchResult?.counts.final ?? 0,
+                queuedBlockCount: dispatchResult?.counts.block ?? 0,
+                provider: selectedProvider,
+                model: selectedModel,
+                thinkLevel: selectedThinkLevel,
+                dispatchError,
+            });
+        }
     };
     // Track which channels we're interested in for filtering firehose events
     const watchedChannels = new Set(groupChannels);
     const _watchedDMs = new Set();
-    // Firehose handler for all channel messages (/v2)
+    // Firehose handler for all channel messages (/v4)
     const handleChannelsFirehose = async (event) => {
         try {
             const nest = event?.nest;
@@ -1206,8 +1564,9 @@ export async function monitorTlonProvider(opts = {}) {
                     : (response?.post?.id ?? "unknown");
                 for (const [reactShip, reactEmoji] of Object.entries(effectiveReacts)) {
                     const ship = normalizeShip(reactShip);
-                    if (!ship || ship === botShipName)
+                    if (!ship || ship === botShipName) {
                         continue;
+                    }
                     try {
                         const route = core.channel.routing.resolveAgentRoute({
                             cfg,
@@ -1220,7 +1579,9 @@ export async function monitorTlonProvider(opts = {}) {
                         const contentSnippet = cached?.content
                             ? ` (message: "${cached.content.substring(0, 200)}${cached.content.length > 200 ? "..." : ""}")`
                             : "";
-                        const authorInfo = cached?.author ? ` (by ${formatShipWithNickname(cached.author)})` : "";
+                        const authorInfo = cached?.author
+                            ? ` (by ${formatShipWithNickname(cached.author)})`
+                            : "";
                         const reactorDisplay = formatShipWithNickname(ship);
                         const eventText = `Tlon reaction in ${nest}: ${reactEmoji} by ${reactorDisplay} on post ${postId}${authorInfo}${contentSnippet}`;
                         runtime.log?.(`[tlon] REACTION: ${eventText}`);
@@ -1230,9 +1591,7 @@ export async function monitorTlonProvider(opts = {}) {
                             // Include context so agent knows what was reacted to, since we're
                             // deliberately omitting thread context (parentId) to avoid the agent
                             // suppressing responses when it sees its own message in thread history.
-                            const reactionParentId = replyReacts
-                                ? (response?.post?.id ?? postId)
-                                : postId;
+                            const reactionParentId = replyReacts ? (response?.post?.id ?? postId) : postId;
                             const reactText = cached?.content
                                 ? `${reactEmoji} (reacting to: "${cached.content}")`
                                 : reactEmoji;
@@ -1266,12 +1625,12 @@ export async function monitorTlonProvider(opts = {}) {
             }
             // Handle post responses (new posts and replies)
             const essay = response?.post?.["r-post"]?.set?.essay;
-            const memo = response?.post?.["r-post"]?.reply?.["r-reply"]?.set?.memo;
-            const content = memo || essay;
+            const replyEssay = response?.post?.["r-post"]?.reply?.["r-reply"]?.set?.["reply-essay"];
+            const content = replyEssay || essay;
             if (!content) {
                 return;
             }
-            const isThreadReply = Boolean(memo);
+            const isThreadReply = Boolean(replyEssay);
             const messageId = isThreadReply ? response?.post?.["r-post"]?.reply?.id : response?.post?.id;
             if (!processedTracker.mark(messageId)) {
                 return;
@@ -1284,7 +1643,8 @@ export async function monitorTlonProvider(opts = {}) {
             const citedContent = await resolveAllCites(content.content);
             const rawText = extractMessageText(content.content);
             const messageText = citedContent + rawText;
-            if (!messageText.trim()) {
+            const hasBlob = Boolean(content?.blob);
+            if (!messageText.trim() && !hasBlob) {
                 return;
             }
             // Cache ALL messages (including bot's own) so reaction lookups have context
@@ -1296,7 +1656,7 @@ export async function monitorTlonProvider(opts = {}) {
             });
             // Check if sender is a bot (BotProfile object has ship, nickname, avatar)
             const authorRaw = content?.author;
-            const isSenderBot = typeof authorRaw === 'object' && authorRaw !== null && 'ship' in authorRaw;
+            const isSenderBot = typeof authorRaw === "object" && authorRaw !== null && "ship" in authorRaw;
             if (isSenderBot) {
                 knownBotShips.add(senderShip);
             }
@@ -1316,11 +1676,15 @@ export async function monitorTlonProvider(opts = {}) {
             // 2. Thread replies where we've participated - respond if relevant (let agent decide)
             const mentioned = isBotMentioned(messageText, botShipName, botNickname ?? undefined);
             const inParticipatedThread = isThreadReply && parentId && participatedThreads.has(String(parentId));
-            if (!mentioned && !inParticipatedThread) {
+            const isOwnerBlob = hasBlob && isOwner(senderShip);
+            if (!mentioned && !inParticipatedThread && !isOwnerBlob) {
                 return;
             }
             // Log why we're responding
-            if (inParticipatedThread && !mentioned) {
+            if (isOwnerBlob && !mentioned && !inParticipatedThread) {
+                runtime.log?.(`[tlon] Responding to owner blob-only message in ${nest}`);
+            }
+            else if (inParticipatedThread && !mentioned) {
                 runtime.log?.(`[tlon] Responding to thread we participated in (no mention): ${parentId}`);
             }
             // Rate limit consecutive bot responses (only in group channels)
@@ -1362,6 +1726,7 @@ export async function monitorTlonProvider(opts = {}) {
                                     timestamp: content.sent || Date.now(),
                                     parentId: parentId ?? undefined,
                                     isThreadReply,
+                                    blob: content.blob ?? undefined,
                                 },
                             }, pendingApprovals.map((a) => a.id));
                             await queueApprovalRequest(approval);
@@ -1379,6 +1744,7 @@ export async function monitorTlonProvider(opts = {}) {
                 senderShip,
                 messageText,
                 messageContent: content.content, // Pass raw content for media extraction
+                blobField: content.blob,
                 isGroup: true,
                 channelNest: nest,
                 hostShip: parsed?.hostShip,
@@ -1392,7 +1758,7 @@ export async function monitorTlonProvider(opts = {}) {
             runtime.error?.(`[tlon] Error handling channel firehose event: ${error?.message ?? String(error)}`);
         }
     };
-    // Firehose handler for all DM messages (/v3)
+    // Firehose handler for all DM messages (/v4)
     // Track which DM invites we've already processed to avoid duplicate accepts
     const processedDmInvites = new Set();
     const handleChatFirehose = async (event) => {
@@ -1525,7 +1891,9 @@ export async function monitorTlonProvider(opts = {}) {
                             const contentSnippet = cached?.content
                                 ? ` (message: "${cached.content.substring(0, 200)}${cached.content.length > 200 ? "..." : ""}")`
                                 : "";
-                            const authorInfo = cached?.author ? ` (by ${formatShipWithNickname(cached.author)})` : "";
+                            const authorInfo = cached?.author
+                                ? ` (by ${formatShipWithNickname(cached.author)})`
+                                : "";
                             const reactorDisplay = formatShipWithNickname(reactAuthor);
                             const eventText = `Tlon DM reaction ${action}: ${reactEmoji} by ${reactorDisplay} on message ${messageId}${authorInfo}${contentSnippet}`;
                             core.system.enqueueSystemEvent(eventText, {
@@ -1541,19 +1909,19 @@ export async function monitorTlonProvider(opts = {}) {
                 }
                 return;
             }
-            // Extract memo from DM thread reply
-            const dmReplyMemo = dmReply?.delta?.add?.memo;
+            // Extract reply-essay from DM thread reply
+            const dmReplyEssay = dmReply?.delta?.add?.["reply-essay"];
             const dmReplyParentId = dmReply ? event.id : undefined;
-            const isDmThreadReply = Boolean(dmReplyMemo);
-            const dmContent = essay || dmReplyMemo;
+            const isDmThreadReply = Boolean(dmReplyEssay);
+            const dmContent = essay || dmReplyEssay;
             // For DM thread replies, extract the reply's own ID (distinct from the parent post ID)
             // The reply ID may be in dmReply.id, or we construct it from author/sent
             let dmReplyOwnId;
             if (isDmThreadReply && dmReply) {
                 dmReplyOwnId = dmReply.id ?? dmReply.delta?.add?.id;
                 // If no explicit reply ID, construct from author/sent (same format as our outbound)
-                if (!dmReplyOwnId && dmReplyMemo?.author && dmReplyMemo?.sent) {
-                    dmReplyOwnId = `${normalizeShip(extractAuthorShip(dmReplyMemo.author))}/${dmReplyMemo.sent}`;
+                if (!dmReplyOwnId && dmReplyEssay?.author && dmReplyEssay?.sent) {
+                    dmReplyOwnId = `${normalizeShip(extractAuthorShip(dmReplyEssay.author))}/${dmReplyEssay.sent}`;
                 }
             }
             if (!dmContent) {
@@ -1564,7 +1932,7 @@ export async function monitorTlonProvider(opts = {}) {
             if (!processedTracker.mark(effectiveMessageId)) {
                 return;
             }
-            const authorShip = normalizeShip(extractAuthorShip(dmContent?.author));
+            const authorShip = normalizeShip(extractAuthorShip(dmContent.author));
             const partnerShip = extractDmPartnerShip(whom);
             const senderShip = partnerShip || authorShip;
             // Cache DM messages (including bot's own) so reaction lookups have context
@@ -1593,7 +1961,8 @@ export async function monitorTlonProvider(opts = {}) {
             const citedContent = await resolveAllCites(dmContent.content);
             const rawText = extractMessageText(dmContent.content);
             const messageText = citedContent + rawText;
-            if (!messageText.trim()) {
+            const hasBlob = Boolean(dmContent?.blob);
+            if (!messageText.trim() && !hasBlob) {
                 return;
             }
             // Owner is always allowed to DM (bypass allowlist)
@@ -1604,6 +1973,7 @@ export async function monitorTlonProvider(opts = {}) {
                     senderShip,
                     messageText,
                     messageContent: dmContent.content,
+                    blobField: dmContent.blob,
                     isGroup: false,
                     timestamp: dmContent.sent || Date.now(),
                     parentId: dmReplyParentId,
@@ -1624,6 +1994,7 @@ export async function monitorTlonProvider(opts = {}) {
                             messageText,
                             messageContent: dmContent.content,
                             timestamp: dmContent.sent || Date.now(),
+                            blob: dmContent.blob ?? undefined,
                         },
                     }, pendingApprovals.map((a) => a.id));
                     await queueApprovalRequest(approval);
@@ -1638,6 +2009,7 @@ export async function monitorTlonProvider(opts = {}) {
                 senderShip,
                 messageText,
                 messageContent: dmContent.content, // Pass raw content for media extraction
+                blobField: dmContent.blob,
                 isGroup: false,
                 timestamp: dmContent.sent || Date.now(),
                 parentId: dmReplyParentId,
@@ -1650,10 +2022,10 @@ export async function monitorTlonProvider(opts = {}) {
     };
     try {
         runtime.log?.("[tlon] Subscribing to firehose updates...");
-        // Subscribe to channels firehose (/v2)
+        // Subscribe to channels firehose (/v4)
         await api.subscribe({
             app: "channels",
-            path: "/v2",
+            path: "/v4",
             event: (data) => handleChannelsFirehose(data),
             err: (error) => {
                 runtime.error?.(`[tlon] Channels firehose error: ${String(error)}`);
@@ -1662,11 +2034,11 @@ export async function monitorTlonProvider(opts = {}) {
                 runtime.log?.("[tlon] Channels firehose quit received, SSE client will resubscribe");
             },
         });
-        runtime.log?.("[tlon] Subscribed to channels firehose (/v2)");
-        // Subscribe to chat/DM firehose (/v3)
+        runtime.log?.("[tlon] Subscribed to channels firehose (/v4)");
+        // Subscribe to chat/DM firehose (/v4)
         await api.subscribe({
             app: "chat",
-            path: "/v3",
+            path: "/v4",
             event: (data) => handleChatFirehose(data),
             err: (error) => {
                 runtime.error?.(`[tlon] Chat firehose error: ${String(error)}`);
@@ -1675,7 +2047,7 @@ export async function monitorTlonProvider(opts = {}) {
                 runtime.log?.("[tlon] Chat firehose quit received, SSE client will resubscribe");
             },
         });
-        runtime.log?.("[tlon] Subscribed to chat firehose (/v3)");
+        runtime.log?.("[tlon] Subscribed to chat firehose (/v4)");
         // Subscribe to contacts updates to track nickname changes
         await api.subscribe({
             app: "contacts",
@@ -1685,7 +2057,8 @@ export async function monitorTlonProvider(opts = {}) {
                     // Look for self profile updates
                     if (event?.self) {
                         const selfUpdate = event.self;
-                        if (selfUpdate?.contact?.nickname?.value !== undefined || selfUpdate?.contact?.avatar?.value !== undefined) {
+                        if (selfUpdate?.contact?.nickname?.value !== undefined ||
+                            selfUpdate?.contact?.avatar?.value !== undefined) {
                             const newNickname = selfUpdate.contact.nickname.value || null;
                             if (newNickname !== botNickname) {
                                 botNickname = newNickname;
@@ -1731,8 +2104,34 @@ export async function monitorTlonProvider(opts = {}) {
         });
         runtime.log?.("[tlon] Subscribed to contacts updates (/v1/news)");
         // Subscribe to settings store for hot-reloading config
-        settingsManager.onChange((newSettings) => {
-            currentSettings = newSettings;
+        const applySettingsSnapshot = (newSettings, source, opts = {}) => {
+            const prevSettings = currentSettings;
+            // If pendingNudge has been rehydrated (startup succeeded or monitor has locally
+            // set/cleared it), the in-memory state is authoritative — refreshes cannot clobber
+            // it or resurrect stale store echoes. If not yet rehydrated (startup scry failed),
+            // allow the store value through so refresh can recover the persisted record.
+            let effectivePendingNudge;
+            if (pendingNudgeRehydrated) {
+                effectivePendingNudge = getPendingNudge(account.accountId) ?? undefined;
+            }
+            else if (newSettings.pendingNudge) {
+                syncPendingNudgeFromStore(account.accountId, newSettings.pendingNudge);
+                pendingNudgeRehydrated = true;
+                effectivePendingNudge = newSettings.pendingNudge;
+                runtime.log?.("[tlon] Settings refresh: recovered persisted pendingNudge after startup failure");
+            }
+            else {
+                effectivePendingNudge = undefined;
+            }
+            const nextRuntimeSettings = {
+                ...newSettings,
+                pendingNudge: effectivePendingNudge,
+            };
+            if (source === "refresh" &&
+                JSON.stringify(prevSettings) === JSON.stringify(nextRuntimeSettings)) {
+                currentSettings = nextRuntimeSettings;
+                return;
+            }
             // Update watched channels if settings changed
             if (newSettings.groupChannels?.length) {
                 const newChannels = newSettings.groupChannels;
@@ -1781,20 +2180,68 @@ export async function monitorTlonProvider(opts = {}) {
                 effectiveAutoDiscoverChannels = newSettings.autoDiscoverChannels;
                 runtime.log?.(`[tlon] Settings: autoDiscoverChannels = ${effectiveAutoDiscoverChannels}`);
             }
-            // Update owner ship
-            if (newSettings.ownerShip !== undefined) {
-                effectiveOwnerShip = newSettings.ownerShip
-                    ? normalizeShip(newSettings.ownerShip)
-                    : account.ownerShip
-                        ? normalizeShip(account.ownerShip)
-                        : null;
+            // ownerShip is applied on both live subscription and refresh.
+            // pendingNudge is only rehydrated from the store during startup load. Once the
+            // monitor is running, the in-memory pending state is authoritative so refreshes
+            // cannot clobber live state or resurrect stale store echoes.
+            const sync = resolveSettingsMirrorSync({
+                prevSettings,
+                newSettings,
+                fileConfigOwnerShip: account.ownerShip ? normalizeShip(account.ownerShip) : null,
+            });
+            if (sync.ownerShipChanged) {
+                effectiveOwnerShip = sync.effectiveOwnerShip;
                 runtime.log?.(`[tlon] Settings: ownerShip = ${effectiveOwnerShip}`);
+                setEffectiveOwnerShip(account.accountId, effectiveOwnerShip);
+            }
+            // Reconcile the scheduler's owner-activity shadow with live settings
+            // changes. Subscription events are authoritative (real-time ship echo
+            // of a poke, admin override, test harness seeding). Refresh updates
+            // are trusted only when `load()` returned `{ fresh: true }` — on
+            // `fresh: false` the manager preserves the last-known snapshot, which
+            // may not yet reflect a locally observed owner reply the ship hasn't
+            // echoed back, so clobbering the shadow from that path would regress
+            // the fix that motivated the shadow in the first place.
+            //
+            // Gating on a prev/new diff means a subscription event for some
+            // unrelated key (e.g. channelRules) cannot reset the shadow via the
+            // snapshot's unchanged owner-activity fields.
+            const shadowReconcileTrusted = source === "subscription" || opts.fresh === true;
+            const ownerActivityChanged = prevSettings.lastOwnerMessageAt !== newSettings.lastOwnerMessageAt ||
+                prevSettings.lastOwnerMessageDate !== newSettings.lastOwnerMessageDate;
+            if (shadowReconcileTrusted && ownerActivityChanged) {
+                setLastOwnerActivity(account.accountId, ownerActivityFromSettings(newSettings));
+                runtime.log?.(`[tlon] nudge: reconciled lastOwnerActivity shadow from ${source} (at=${newSettings.lastOwnerMessageAt ?? "null"})`);
+            }
+            // Reconcile the scheduler's stage shadow with live `lastNudgeStage`
+            // changes for the same trust-and-diff reasons as the activity branch
+            // above. Without this, an external `%settings` clear (or admin
+            // lower) cannot move the in-memory guard down — the runner's
+            // `resolveAuthoritativeStage()` currently uses the shadow as the
+            // authoritative stage, so a stuck-high shadow suppresses later
+            // same-stage nudges.
+            //
+            // Trust gate: subscription events are real-time and only fire when
+            // storage actually transitioned, so they cannot represent a stale
+            // post-poke read. Refresh is trusted only when `load()` returned
+            // `{ fresh: true }`, matching the activity-shadow rule. Scry is
+            // still useful for drift logging, but it is not part of the
+            // runner's stage guard today.
+            const stageChanged = prevSettings.lastNudgeStage !== newSettings.lastNudgeStage;
+            if (shadowReconcileTrusted && stageChanged) {
+                const nextStage = (newSettings.lastNudgeStage ?? 0);
+                setLastNudgeStageShadow(account.accountId, nextStage);
+                runtime.log?.(`[tlon] nudge: reconciled lastNudgeStageShadow from ${source} (stage=${nextStage})`);
             }
             // Update pending approvals
             if (newSettings.pendingApprovals !== undefined) {
                 pendingApprovals = newSettings.pendingApprovals;
                 runtime.log?.(`[tlon] Settings: pendingApprovals updated (${pendingApprovals.length} items)`);
             }
+            currentSettings = nextRuntimeSettings;
+        };
+        settingsManager.onChange((newSettings) => {
+            applySettingsSnapshot(newSettings, "subscription");
         });
         try {
             await settingsManager.startSubscription();
@@ -2106,34 +2553,71 @@ export async function monitorTlonProvider(opts = {}) {
         }, 2 * 60 * 1000);
         // Periodically re-scry settings as a fallback for stale subscriptions.
         // The settings subscription can silently die (SSE quit without reconnect),
-        // leaving the in-memory allowlist permanently stale.
+        // leaving both authorization state and heartbeat telemetry mirrors stale.
         const settingsRefreshInterval = setInterval(async () => {
             if (opts.abortSignal?.aborted) {
                 return;
             }
             try {
-                const refreshed = await settingsManager.load();
-                if (refreshed.dmAllowlist !== undefined) {
-                    const newList = refreshed.dmAllowlist;
-                    if (JSON.stringify(newList) !== JSON.stringify(effectiveDmAllowlist)) {
-                        effectiveDmAllowlist = newList;
-                        runtime.log?.(`[tlon] Settings refresh: dmAllowlist updated to ${effectiveDmAllowlist.join(", ")}`);
-                    }
-                }
-                if (refreshed.defaultAuthorizedShips !== undefined) {
-                    currentSettings = { ...currentSettings, defaultAuthorizedShips: refreshed.defaultAuthorizedShips };
-                }
+                const refreshResult = await settingsManager.load();
+                applySettingsSnapshot(refreshResult.settings, "refresh", { fresh: refreshResult.fresh });
             }
             catch (err) {
                 runtime.error?.(`[tlon] Settings refresh failed: ${String(err)}`);
             }
-        }, 5 * 60 * 1000);
+        }, SETTINGS_REFRESH_INTERVAL_MS);
+        // Plugin-owned re-engagement nudge scheduler. Owns tick lifecycle and
+        // reentrancy; runs independently of LLM heartbeat.
+        //
+        // Gating is computed by the pure `shouldStartNudgeRunner` helper; see
+        // that function for the two invariants (explicit opt-in flag + exactly
+        // one configured Tlon account).
+        //
+        // `TLON_NUDGE_TICK_INTERVAL_MS` exists so the integration harness can
+        // drive ticks on a short cadence without rebuilding the plugin; in
+        // production the default 15-minute interval applies.
+        const nudgeStartDecision = shouldStartNudgeRunner(cfg);
+        if (!nudgeStartDecision.start) {
+            runtime.log?.(`[tlon] nudge: scheduler disabled — ${nudgeStartDecision.detail}`);
+        }
+        else {
+            const intervalEnv = process.env.TLON_NUDGE_TICK_INTERVAL_MS;
+            const intervalMsOverride = intervalEnv ? Number(intervalEnv) : NaN;
+            nudgeRunner = createNudgeRunner({
+                accountId: account.accountId,
+                botShip: botShipName,
+                api,
+                cfg,
+                getSettings: () => currentSettings,
+                getEffectiveOwnerShip,
+                getLastOwnerActivity,
+                getLastNudgeStageShadow,
+                setLastNudgeStageShadow,
+                setLocalPendingNudge,
+                sendDm,
+                getBotProfile,
+                telemetry,
+                runtime,
+                abortSignal: opts.abortSignal,
+                ownerReplyPersistence,
+                ...(Number.isFinite(intervalMsOverride) && intervalMsOverride > 0
+                    ? { intervalMs: intervalMsOverride }
+                    : {}),
+            });
+            nudgeRunner.start();
+        }
         if (opts.abortSignal) {
             const signal = opts.abortSignal;
             await new Promise((resolve) => {
                 signal.addEventListener("abort", () => {
                     clearInterval(pollInterval);
                     clearInterval(settingsRefreshInterval);
+                    // Kick off scheduler shutdown; don't block the event-handler
+                    // callback. The `finally` block awaits the same stop promise
+                    // before draining the persistence queues and closing the
+                    // api, so any in-flight tick is guaranteed to settle first.
+                    void nudgeRunner?.stop();
+                    gsManager?.stopHeartbeat();
                     resolve(null);
                 }, { once: true });
             });
@@ -2144,6 +2628,16 @@ export async function monitorTlonProvider(opts = {}) {
     }
     finally {
         removeBridge(accountKey, commandBridge);
+        // Await the scheduler drain before flushing persistence queues.
+        // `stop()` waits for any in-flight tick to finish so its final
+        // `setLocalPendingNudge` / `enqueueStageClear` / etc. writes land
+        // inside the queues we flush below, rather than leaking into a
+        // half-closed api after cleanup.
+        await nudgeRunner?.stop();
+        await ownerReplyPersistence.flush();
+        await pendingNudgePersistence.flush();
+        clearShadowsForAccount(account.accountId);
+        await telemetry?.close();
         try {
             await api?.close();
         }