nemoris 0.1.0

package/src/runtime/delivery-manager.js

@@ -0,0 +1,807 @@
+import path from "node:path";
+import { ConfigLoader } from "../config/loader.js";
+import { NotificationStore } from "./notification-store.js";
+import { DeliveryStore } from "./delivery-store.js";
+import { ShadowDeliveryAdapter } from "./delivery-adapters/shadow.js";
+import { TelegramDeliveryAdapter } from "./delivery-adapters/telegram.js";
+import { OpenClawCliDeliveryAdapter } from "./delivery-adapters/openclaw-cli.js";
+import { OpenClawPeerDeliveryAdapter } from "./delivery-adapters/openclaw-peer.js";
+import { LocalFileDeliveryAdapter } from "./delivery-adapters/local-file.js";
+import { StandaloneHttpDeliveryAdapter } from "./delivery-adapters/standalone-http.js";
+import { TuiDeliveryAdapter } from "./delivery-adapters/tui.js";
+import { OpenClawShadowBridge } from "../shadow/bridge.js";
+import { PeerRegistry } from "./peer-registry.js";
+import { InteractionNotifier } from "./notifier.js";
+import { classifyNetworkFailure } from "./network.js";
+import { PeerReadinessProbe } from "./peer-readiness.js";
+import { detectInjectionPatterns } from "./input-sanitiser.js";
+import { createHash } from "node:crypto";
+
+const ADAPTERS = new Map([
+  [ShadowDeliveryAdapter.adapterId, ShadowDeliveryAdapter],
+  [TelegramDeliveryAdapter.adapterId, TelegramDeliveryAdapter],
+  [OpenClawCliDeliveryAdapter.adapterId, OpenClawCliDeliveryAdapter],
+  [OpenClawPeerDeliveryAdapter.adapterId, OpenClawPeerDeliveryAdapter],
+  [LocalFileDeliveryAdapter.adapterId, LocalFileDeliveryAdapter],
+  [StandaloneHttpDeliveryAdapter.adapterId, StandaloneHttpDeliveryAdapter],
+  [TuiDeliveryAdapter.adapterId, TuiDeliveryAdapter]
+]);
+
+function buildProfileMap(deliveryConfig) {
+  return deliveryConfig?.profiles || {};
+}
+
+function normalizeProfileName(profileName) {
+  return String(profileName || "").replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function resolveNamedProfile(profiles, profileName) {
+  if (!profileName) return null;
+  return profiles[profileName] || profiles[normalizeProfileName(profileName)] || null;
+}
+
+function normalizeHandoffState(notification) {
+  if (notification.handoffState) return notification.handoffState;
+  if (notification.stage !== "handoff") return null;
+  if (notification.status === "awaiting_choice") return "pending";
+  if (notification.status === "ready" && notification.chosenPeer?.peerId) return "chosen";
+  if (notification.status === "blocked") return "blocked";
+  return null;
+}
+
+function normalizeFollowUpState(notification) {
+  if (notification.followUpState) return notification.followUpState;
+  if (notification.stage !== "follow_up") return null;
+  if (notification.status === "pending") return "pending";
+  if (notification.status === "consumed" || notification.yieldState === "consumed") return "consumed";
+  if (notification.status === "expired") return "expired";
+  if (notification.status === "blocked") return "blocked";
+  return null;
+}
+
+function scanFollowUpPayload(notification) {
+  if (!notification?.payload) return null;
+  const payload = notification.payload;
+  const textParts = [];
+
+  if (typeof payload === "string") {
+    textParts.push(payload);
+  } else if (typeof payload === "object") {
+    for (const value of Object.values(payload)) {
+      if (typeof value === "string") textParts.push(value);
+      else if (typeof value === "object" && value !== null) {
+        for (const inner of Object.values(value)) {
+          if (typeof inner === "string") textParts.push(inner);
+        }
+      }
+    }
+  }
+
+  if (!textParts.length) return null;
+  const combined = textParts.join("\n");
+  return detectInjectionPatterns(combined);
+}
+
+function classifyDeliveryFailure(message) {
+  const failure = classifyNetworkFailure(message, { surface: "delivery" });
+  if (failure?.failureClass === "delivery_timeout") {
+    return "uncertain";
+  }
+  const normalized = String(message || "").toLowerCase();
+  if (!normalized) return "failed";
+  return "failed";
+}
+
+export class DeliveryManager {
+  constructor({ projectRoot, liveRoot, stateRoot, fetchImpl, execFileImpl, stateStore } = {}) {
+    this.loader = new ConfigLoader({ rootDir: path.join(projectRoot, "config") });
+    this.notificationStore = new NotificationStore({ rootDir: path.join(stateRoot, "notifications") });
+    this.deliveryStore = new DeliveryStore({ rootDir: path.join(stateRoot, "deliveries") });
+    this.notifier = new InteractionNotifier({ stateRoot });
+    this.bridge = new OpenClawShadowBridge({ liveRoot });
+    this.peerProbe = new PeerReadinessProbe({ liveRoot });
+    this.liveRoot = liveRoot;
+    this.stateRoot = stateRoot;
+    this.fetchImpl = fetchImpl;
+    this.execFileImpl = execFileImpl;
+    this.stateStore = stateStore || null;
+  }
+
+  isStandaloneMode(runtime = null) {
+    if (process.env.NEMORIS_STANDALONE === "1" || process.env.NEMORIS_STANDALONE === "true") {
+      return true;
+    }
+    return Boolean(runtime?.delivery?.standaloneMode) || !this.liveRoot;
+  }
+
+  createAdapter(adapterId) {
+    const Adapter = ADAPTERS.get(adapterId);
+    if (!Adapter) {
+      throw new Error(`Unknown delivery adapter ${adapterId}`);
+    }
+    return new Adapter({
+      fetchImpl: this.fetchImpl,
+      execFileImpl: this.execFileImpl,
+      stateRoot: this.stateRoot,
+      liveRoot: this.liveRoot
+    });
+  }
+
+  resolveNotificationTarget(notification, runtime) {
+    const peerRegistry = new PeerRegistry(runtime.peers);
+    const standalone = this.isStandaloneMode(runtime);
+    if (notification.target?.mode !== "peer_agent") {
+      return {
+        target: notification.target || null,
+        profileName:
+          notification.deliveryProfile ||
+          (notification.target?.mode === "scheduler_log"
+            ? runtime.delivery?.defaultSchedulerProfile
+            : standalone
+              ? runtime.delivery?.defaultInteractiveProfileStandalone || runtime.delivery?.defaultInteractiveProfile
+              : runtime.delivery?.defaultInteractiveProfile)
+      };
+    }
+
+    const resolved = peerRegistry.resolveTarget(notification.target);
+    return {
+      target: {
+        mode: "peer_agent",
+        peerId: resolved.peerId,
+        sessionKey: resolved.sessionKey,
+        label: resolved.label
+      },
+      profileName:
+        notification.deliveryProfile ||
+        resolved.deliveryProfile ||
+        (standalone
+          ? runtime.delivery?.defaultPeerProfileStandalone || runtime.delivery?.defaultInteractiveProfileStandalone
+          : runtime.delivery?.defaultInteractiveProfile)
+    };
+  }
+
+  resolveProfileEntry(deliveryConfig, profileName) {
+    return resolveNamedProfile(buildProfileMap(deliveryConfig), profileName);
+  }
+
+  async listPending(mode = "shadow", limit = 10, notificationFiles = null) {
+    const notifications = await this.notificationStore.listRecent(limit * 4);
+    const pending = [];
+    const fileFilter = notificationFiles?.length ? new Set(notificationFiles) : null;
+
+    for (const notification of notifications) {
+      if (fileFilter && !fileFilter.has(notification.filePath)) continue;
+      if (notification.stage === "follow_up") continue;
+      if (notification.status === "awaiting_choice" || normalizeHandoffState(notification) === "pending") continue;
+      const existing = await this.deliveryStore.getDeliveryRecord(mode, notification.filePath, notification.dedupeKey || null);
+      if (existing && (existing.status === "delivered" || existing.status === "uncertain" || existing.retryEligible === false)) {
+        continue;
+      }
+      pending.push(notification);
+      if (pending.length >= limit) break;
+    }
+
+    return pending;
+  }
+
+  async deliverPending({ mode = "shadow", limit = 10, notificationFiles = null } = {}) {
+    const runtime = await this.loader.loadAll();
+    this.notificationStore.setRetentionPolicy(runtime.runtime?.retention?.notifications || {});
+    this.deliveryStore.setRetentionPolicy(runtime.runtime?.retention?.deliveries || {});
+    this.notifier.configureRetention(runtime.runtime?.retention?.notifications || {});
+    const profiles = buildProfileMap(runtime.delivery);
+    const pending = await this.listPending(mode, limit, notificationFiles);
+    const results = [];
+    const requestedFiles = notificationFiles?.length ? new Set(notificationFiles) : null;
+
+    if (requestedFiles) {
+      for (const filePath of requestedFiles) {
+        const notification = await this.notificationStore.getNotification(filePath);
+        const existing = await this.deliveryStore.getDeliveryRecord(mode, filePath, notification?.dedupeKey || null);
+        if (!existing) continue;
+        const status =
+          existing.status === "uncertain"
+            ? "delivery_uncertain"
+            : existing.retryEligible === false || existing.status === "delivered"
+              ? "duplicate_prevented"
+              : "previous_attempt";
+        results.push({
+          status,
+          notificationFilePath: filePath,
+          receiptFilePath: existing.receiptFilePath,
+          deliveredAt: existing.deliveredAt,
+          lastError: existing.lastError || null
+        });
+      }
+    }
+
+    for (const notification of pending) {
+      try {
+        if (notification.stage === "handoff" && notification.target?.mode === "peer_agent" && !notification.target?.peerId) {
+          const updated = await this.notificationStore.updateNotification(notification.filePath, {
+            status: "awaiting_choice",
+            handoffState: "pending",
+            updatedAt: new Date().toISOString()
+          });
+          results.push({
+            status: "pending_choice",
+            jobId: notification.jobId,
+            stage: notification.stage,
+            notificationFilePath: updated.filePath
+          });
+          continue;
+        }
+
+        if (notification.stage === "handoff" && !notification.target?.mode && (notification.suggestedPeers || []).length) {
+          const updated = await this.notificationStore.updateNotification(notification.filePath, {
+            status: "awaiting_choice",
+            handoffState: "pending",
+            updatedAt: new Date().toISOString()
+          });
+          results.push({
+            status: "pending_choice",
+            jobId: notification.jobId,
+            stage: notification.stage,
+            suggestedPeers: updated.suggestedPeers?.map((item) => item.peerId) || []
+          });
+          continue;
+        }
+
+        if (notification.stage === "handoff") {
+          const preflight = await this.preflightHandoff(notification, runtime);
+          if (!preflight.ok) {
+            await this.notificationStore.updateNotification(notification.filePath, {
+              status: "blocked",
+              handoffState: "blocked",
+              blockedReason: preflight.reason,
+              updatedAt: new Date().toISOString()
+            });
+            results.push({
+              status: "blocked",
+              jobId: notification.jobId,
+              stage: notification.stage,
+              reason: preflight.reason
+            });
+            continue;
+          }
+        }
+
+        const existing = await this.deliveryStore.getDeliveryRecord(mode, notification.filePath, notification.dedupeKey || null);
+        if (existing?.status === "delivered") {
+          results.push({
+            status: "duplicate_prevented",
+            jobId: notification.jobId,
+            stage: notification.stage,
+            notificationFilePath: notification.filePath,
+            receiptFilePath: existing.receiptFilePath
+          });
+          continue;
+        }
+        if (existing?.status === "uncertain") {
+          results.push({
+            status: "delivery_uncertain",
+            jobId: notification.jobId,
+            stage: notification.stage,
+            notificationFilePath: notification.filePath,
+            receiptFilePath: existing.receiptFilePath,
+            lastError: existing.lastError || null
+          });
+          continue;
+        }
+        if (existing?.status === "failed" && existing.retryEligible === false) {
+          results.push({
+            status: "retry_suppressed",
+            jobId: notification.jobId,
+            stage: notification.stage,
+            notificationFilePath: notification.filePath,
+            receiptFilePath: existing.receiptFilePath,
+            lastError: existing.lastError || null
+          });
+          continue;
+        }
+
+        const resolvedTarget = this.resolveNotificationTarget(notification, runtime);
+        const profileName = resolvedTarget.profileName;
+        const profileConfig = await this.resolveProfileConfig(profileName, resolveNamedProfile(profiles, profileName) || {});
+        const adapterId = mode === "shadow" ? "shadow" : profileConfig.adapter || "shadow";
+        const adapter = this.createAdapter(adapterId);
+        const delivery = await adapter.deliver(notification, {
+          profileName,
+          profileConfig,
+          target: resolvedTarget.target
+        });
+
+        const receipt = {
+          relatedNotificationId: notification.id || null,
+          timestamp: new Date().toISOString(),
+          mode,
+          notificationFilePath: notification.filePath,
+          jobId: notification.jobId,
+          stage: notification.stage,
+          target: resolvedTarget.target || null,
+          deliveryProfile: profileName || null,
+          adapter: adapterId,
+          delivery
+        };
+        const receiptFilePath = await this.deliveryStore.saveReceipt(notification.jobId, receipt);
+        await this.deliveryStore.markDelivered(mode, notification.filePath, receiptFilePath, {
+          dedupeKey: notification.dedupeKey || null
+        });
+        if (notification.stage === "handoff") {
+          await this.notificationStore.updateNotification(notification.filePath, {
+            status: "delivered",
+            handoffState: "delivered",
+            lastReceiptFilePath: receiptFilePath,
+            updatedAt: new Date().toISOString()
+          });
+        }
+
+        results.push({
+          status: "delivered",
+          jobId: notification.jobId,
+          stage: notification.stage,
+          adapter: adapterId,
+          receiptFilePath
+        });
+      } catch (error) {
+        const failureClass = classifyDeliveryFailure(error.message);
+        const receipt = {
+          relatedNotificationId: notification.id || null,
+          timestamp: new Date().toISOString(),
+          mode,
+          notificationFilePath: notification.filePath,
+          jobId: notification.jobId,
+          stage: notification.stage,
+          target: notification.target || null,
+          deliveryProfile: notification.deliveryProfile || null,
+          adapter: null,
+          delivery: {
+            status: failureClass === "uncertain" ? "delivery_uncertain" : "delivery_failed",
+            error: error.message
+          }
+        };
+        const receiptFilePath = await this.deliveryStore.saveReceipt(notification.jobId, receipt);
+        const retryEligible = runtime.runtime?.delivery?.retryOnFailure ?? false;
+        if (failureClass === "uncertain") {
+          await this.deliveryStore.markUncertain(mode, notification.filePath, receiptFilePath, {
+            dedupeKey: notification.dedupeKey || null,
+            error: error.message
+          });
+        } else {
+          await this.deliveryStore.markFailed(mode, notification.filePath, receiptFilePath, {
+            dedupeKey: notification.dedupeKey || null,
+            error: error.message,
+            retryEligible
+          });
+        }
+        if (notification.stage === "handoff") {
+          await this.notificationStore.updateNotification(notification.filePath, {
+            status: failureClass === "uncertain" ? "uncertain" : "blocked",
+            handoffState: failureClass === "uncertain" ? "blocked" : "blocked",
+            blockedReason: error.message,
+            deliveryUncertain: failureClass === "uncertain",
+            updatedAt: new Date().toISOString()
+          });
+        }
+
+        const notifyOnFailure = runtime.runtime?.delivery?.notifyOnFailure ?? true;
+        if (failureClass !== "uncertain" && !retryEligible && notifyOnFailure) {
+          const resolvedTarget = this.resolveNotificationTarget(notification, runtime);
+          const escalationRecord = {
+            event: "delivery_failure",
+            profile: notification.deliveryProfile || resolvedTarget.profileName || null,
+            target: resolvedTarget.target || notification.target || null,
+            error: error.message,
+            escalated: true
+          };
+          await this.notificationStore.saveNotification(notification.jobId, {
+            timestamp: new Date().toISOString(),
+            jobId: notification.jobId,
+            stage: "delivery_failure_escalation",
+            status: "ready",
+            signal: "delivery_failure",
+            deliveryProfile: runtime.runtime?.followUps?.escalationDeliveryProfile || runtime.delivery?.defaultInteractiveProfile || null,
+            target: { mode: "same_thread" },
+            message: `Delivery failed for ${notification.jobId} (stage: ${notification.stage}): ${error.message}`,
+            sourceNotificationFilePath: notification.filePath,
+            escalationRecord
+          });
+        }
+
+        results.push({
+          status: failureClass === "uncertain" ? "delivery_uncertain" : "error",
+          jobId: notification.jobId,
+          stage: notification.stage,
+          error: error.message,
+          receiptFilePath,
+          escalated: failureClass !== "uncertain" && !retryEligible && (runtime.runtime?.delivery?.notifyOnFailure ?? true)
+        });
+      }
+    }
+
+    return {
+      mode,
+      pendingCount: pending.length,
+      results
+    };
+  }
+
+  async resolveProfileConfig(profileName, profileConfig = {}) {
+    if (!profileConfig || !["telegram", "openclaw_cli"].includes(profileConfig.adapter)) {
+      return profileConfig;
+    }
+
+    if (profileConfig.channel && profileConfig.channel !== "telegram") {
+      return profileConfig;
+    }
+
+    const liveConfig = await this.bridge.loadConfig();
+    const accountId = profileConfig.accountId || "default";
+    const liveAccount = liveConfig.channels?.telegram?.accounts?.[accountId] || {};
+    const directIds = Object.keys(liveAccount.direct || {});
+    const allowFrom = liveAccount.allowFrom || liveConfig.channels?.telegram?.allowFrom || [];
+    const fallbackChatId = directIds[0] || String(allowFrom[0] || "").replace(/^tg:/, "") || null;
+
+    return {
+      ...profileConfig,
+      accountId,
+      channel: profileConfig.channel || "telegram",
+      chatId: profileConfig.chatId || fallbackChatId,
+      botTokenEnv: profileConfig.botTokenEnv || liveAccount.botToken?.id || null
+    };
+  }
+
+  async listPendingHandoffs(limit = 10) {
+    const notifications = await this.notificationStore.listRecent(limit * 4);
+    return notifications
+      .filter((item) => item.stage === "handoff" && normalizeHandoffState(item) === "pending")
+      .slice(0, limit);
+  }
+
+  async listPendingFollowUps(limit = 10) {
+    const notifications = await this.notificationStore.listRecent(limit * 4);
+    return notifications
+      .filter((item) => item.stage === "follow_up" && normalizeFollowUpState(item) === "pending")
+      .slice(0, limit);
+  }
+
+  async consumeFollowUp(notificationFilePath, options = {}) {
+    const notification = await this.notificationStore.getNotification(notificationFilePath);
+    if (notification) {
+      const injectionScan = scanFollowUpPayload(notification);
+      if (injectionScan?.flagged) {
+        console.warn(`[Nemoris] security: Follow-up payload for job "${notification.jobId}" contains potential injection patterns: ${injectionScan.patterns.join(", ")}`);
+      }
+    }
+    return this.notifier.consumeFollowUp(notificationFilePath, options);
+  }
+
+  async chooseHandoffPeer(notificationFilePath, peerId, options = {}) {
+    const runtime = await this.loader.loadAll();
+    const notification = await this.notificationStore.getNotification(notificationFilePath);
+    if (!notification) {
+      throw new Error(`Notification not found: ${notificationFilePath}`);
+    }
+    if (notification.stage !== "handoff") {
+      throw new Error("Only handoff notifications can be assigned to a peer.");
+    }
+
+    const peerRegistry = new PeerRegistry(runtime.peers);
+    const resolved = peerRegistry.resolveTarget({
+      mode: "peer_agent",
+      peerId
+    });
+    const profileName = options.deliveryProfile || notification.deliveryProfile || "peer_preview";
+    const profile = this.resolveProfileEntry(runtime.delivery, profileName);
+    if (!profile) {
+      throw new Error(`Unknown delivery profile ${profileName}`);
+    }
+
+    const updated = await this.notificationStore.updateNotification(notificationFilePath, {
+      status: "ready",
+      handoffState: "chosen",
+      target: {
+        mode: "peer_agent",
+        peerId: resolved.peerId,
+        sessionKey: resolved.sessionKey,
+        deliveryProfile: profileName
+      },
+      deliveryProfile: profileName,
+      chosenPeer: {
+        peerId: resolved.peerId,
+        label: resolved.label,
+        sessionKey: resolved.sessionKey
+      },
+      chosenBy: "manual_peer",
+      chosenAt: new Date().toISOString(),
+      blockedReason: null
+    });
+
+    return updated;
+  }
+
+  async chooseTopSuggestedPeer(notificationFilePath, options = {}) {
+    const notification = await this.notificationStore.getNotification(notificationFilePath);
+    if (!notification) {
+      throw new Error(`Notification not found: ${notificationFilePath}`);
+    }
+    if (notification.stage !== "handoff") {
+      throw new Error("Only handoff notifications can promote the top suggested peer.");
+    }
+    if (notification.status !== "awaiting_choice") {
+      throw new Error("Top-suggestion promotion only works for handoffs awaiting choice.");
+    }
+
+    const suggestions = notification.suggestedPeers || [];
+    if (!suggestions.length) {
+      throw new Error("No suggested peers are available for this handoff.");
+    }
+
+    const topSuggestion = suggestions[0];
+    const updated = await this.chooseHandoffPeer(notificationFilePath, topSuggestion.peerId, options);
+    return this.notificationStore.updateNotification(updated.filePath, {
+      chosenBy: "top_suggestion",
+      chosenSuggestionRank: 1,
+      chosenSuggestionReasons: topSuggestion.reasons || [],
+      chosenSuggestionScore: topSuggestion.score ?? null
+    });
+  }
+
+  async preflightHandoff(notification, runtime) {
+    if (notification.stage !== "handoff") {
+      return { ok: true };
+    }
+    if (!notification.target?.mode) {
+      return { ok: false, reason: "handoff_target_missing" };
+    }
+    if (notification.target.mode !== "peer_agent") {
+      return { ok: false, reason: `handoff_target_mode_not_allowed:${notification.target.mode}` };
+    }
+    const profileName = notification.deliveryProfile || runtime.delivery?.defaultPeerProfile || runtime.delivery?.defaultInteractiveProfile;
+    const profile = this.resolveProfileEntry(runtime.delivery, profileName);
+    if (!profile) {
+      return { ok: false, reason: "handoff_peer_delivery_profile_invalid" };
+    }
+    try {
+      const resolved = new PeerRegistry(runtime.peers).resolveTarget(notification.target);
+      if (!resolved.sessionKey) {
+        return { ok: false, reason: "handoff_peer_route_unresolvable" };
+      }
+      const readiness = await this.peerProbe.probe(runtime, resolved.peerId);
+      if (!readiness.deliveryProfileValid) {
+        return { ok: false, reason: "handoff_peer_delivery_profile_invalid" };
+      }
+      if (!readiness.routeResolvable) {
+        return { ok: false, reason: "handoff_peer_route_unresolvable" };
+      }
+      if (!readiness.targetReachable && profile.dryRun !== true) {
+        return { ok: false, reason: "handoff_peer_not_ready" };
+      }
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, reason: error.message };
+    }
+  }
+
+  async sweepPendingHandoffs(options = {}) {
+    const runtime = await this.loader.loadAll();
+    const config = runtime.runtime?.handoffs || {};
+    const timeoutMinutes = Number(options.timeoutMinutes ?? config.pendingTimeoutMinutes ?? 120);
+    const escalateOnExpiry = options.escalateOnExpiry ?? config.escalateOnExpiry ?? true;
+    const escalationDeliveryProfile =
+      options.escalationDeliveryProfile ||
+      config.escalationDeliveryProfile ||
+      runtime.delivery?.defaultInteractiveProfile ||
+      null;
+    const now = new Date(options.now || Date.now());
+    const cutoff = now.getTime() - timeoutMinutes * 60 * 1000;
+    const notifications = await this.notificationStore.listAll();
+    const pending = notifications.filter((item) => item.stage === "handoff" && normalizeHandoffState(item) === "pending");
+    const results = [];
+
+    for (const notification of pending) {
+      const ts = new Date(notification.timestamp || 0).getTime();
+      if (!ts || ts >= cutoff) continue;
+      const expired = await this.notificationStore.updateNotification(notification.filePath, {
+        status: "expired",
+        handoffState: "expired",
+        expiredAt: now.toISOString(),
+        updatedAt: now.toISOString()
+      });
+      let escalationFilePath = null;
+      if (escalateOnExpiry) {
+        escalationFilePath = await this.notificationStore.saveNotification(notification.jobId, {
+          timestamp: now.toISOString(),
+          jobId: notification.jobId,
+          stage: "handoff_escalation",
+          status: "ready",
+          handoffState: "escalated",
+          deliveryProfile: escalationDeliveryProfile,
+          signal: `${notification.signal || "handoff"}_expired`,
+          target: { mode: "same_thread" },
+          message: `Handoff for ${notification.jobId} expired without operator choice.`,
+          sourceNotificationId: notification.id || null,
+          sourceNotificationFilePath: notification.filePath
+        });
+        await this.notificationStore.updateNotification(notification.filePath, {
+          handoffState: "escalated",
+          escalationNotificationFilePath: escalationFilePath,
+          updatedAt: now.toISOString()
+        });
+      }
+      results.push({
+        jobId: notification.jobId,
+        notificationFilePath: expired.filePath,
+        status: escalateOnExpiry ? "escalated" : "expired",
+        escalationNotificationFilePath: escalationFilePath
+      });
+    }
+
+    return {
+      timestamp: now.toISOString(),
+      pendingCount: pending.length,
+      expiredCount: results.length,
+      results
+    };
+  }
+
+  computeFollowUpDepth(notification, allNotifications) {
+    let depth = 0;
+    let current = notification;
+    const seen = new Set();
+    while (current?.sourceFollowUpFilePath) {
+      if (seen.has(current.sourceFollowUpFilePath)) break;
+      seen.add(current.sourceFollowUpFilePath);
+      depth += 1;
+      current = allNotifications.find((n) => n.filePath === current.sourceFollowUpFilePath) || null;
+    }
+    return depth;
+  }
+
+  async sweepPendingFollowUps(options = {}) {
+    const runtime = await this.loader.loadAll();
+    const config = runtime.runtime?.followUps || {};
+    const timeoutMinutes = Number(options.timeoutMinutes ?? config.pendingTimeoutMinutes ?? 120);
+    const maxFollowUpDepth = Number(options.maxFollowUpDepth ?? config.maxFollowUpDepth ?? 5);
+    const escalateOnExpiry = options.escalateOnExpiry ?? config.escalateOnExpiry ?? true;
+    const escalationDeliveryProfile =
+      options.escalationDeliveryProfile ||
+      config.escalationDeliveryProfile ||
+      runtime.delivery?.defaultInteractiveProfile ||
+      null;
+    const now = new Date(options.now || Date.now());
+    const cutoff = now.getTime() - timeoutMinutes * 60 * 1000;
+    const notifications = await this.notificationStore.listAll();
+    const pending = notifications.filter((item) => item.stage === "follow_up" && normalizeFollowUpState(item) === "pending");
+    const results = [];
+
+    for (const notification of pending) {
+      const injectionScan = scanFollowUpPayload(notification);
+      if (injectionScan?.flagged) {
+        console.warn(`[Nemoris] security: Follow-up payload for job "${notification.jobId}" contains potential injection patterns: ${injectionScan.patterns.join(", ")}`);
+      }
+
+      const depth = this.computeFollowUpDepth(notification, notifications);
+      if (depth >= maxFollowUpDepth) {
+        console.warn(`Follow-up chain halted: max depth ${depth} exceeded for job ${notification.jobId}`);
+        await this.notificationStore.updateNotification(notification.filePath, {
+          status: "expired",
+          followUpState: "depth_exceeded",
+          yieldState: notification.yieldState || "pending",
+          expiredAt: now.toISOString(),
+          updatedAt: now.toISOString(),
+          depthExceeded: true,
+          chainDepth: depth,
+          maxFollowUpDepth
+        });
+        results.push({
+          jobId: notification.jobId,
+          notificationFilePath: notification.filePath,
+          status: "depth_exceeded",
+          chainDepth: depth,
+          maxFollowUpDepth
+        });
+        continue;
+      }
+
+      // Scoped idempotency check
+      const followUpIdentifier = notification.followUpId || notification.sourceFollowUpId;
+      if (this.stateStore && notification.parentIdempotencyKey && followUpIdentifier) {
+        const scopedKey = createHash("sha256")
+          .update(`${notification.parentIdempotencyKey}:${followUpIdentifier}`)
+          .digest("hex")
+          .slice(0, 32);
+
+        notification._scopedKey = scopedKey;
+
+        const existing = this.stateStore.getFollowUpCompletion(scopedKey);
+        if (existing?.status === "succeeded") {
+          console.log(`[Nemoris] follow-up ${followUpIdentifier} already completed in this slot, skipping`);
+          results.push({
+            jobId: notification.jobId,
+            notificationFilePath: notification.filePath,
+            status: "idempotent_skip",
+            scopedKey
+          });
+          continue;
+        }
+        if (existing?.status === "failed") {
+          this.stateStore.clearFollowUpCompletion(scopedKey);
+        }
+      }
+
+      const ts = new Date(notification.timestamp || 0).getTime();
+      if (!ts || ts >= cutoff) continue;
+      const expired = await this.notificationStore.updateNotification(notification.filePath, {
+        status: "expired",
+        followUpState: "expired",
+        yieldState: notification.yieldState || "pending",
+        expiredAt: now.toISOString(),
+        updatedAt: now.toISOString()
+      });
+
+      let escalationFilePath = null;
+      if (escalateOnExpiry) {
+        escalationFilePath = await this.notificationStore.saveNotification(notification.jobId, {
+          id: null,
+          timestamp: now.toISOString(),
+          jobId: notification.jobId,
+          stage: "follow_up_escalation",
+          status: "ready",
+          followUpState: "escalated",
+          deliveryProfile: escalationDeliveryProfile,
+          signal: `${notification.signal || "follow_up"}_expired`,
+          target: { mode: "same_thread" },
+          message: `Follow-up for ${notification.jobId} expired before it was consumed.`,
+          sourceNotificationId: notification.id || null,
+          sourceNotificationFilePath: notification.filePath,
+          sourceFollowUpId: notification.followUpId || null
+        });
+        await this.notificationStore.updateNotification(notification.filePath, {
+          followUpState: "escalated",
+          escalationNotificationFilePath: escalationFilePath,
+          updatedAt: now.toISOString()
+        });
+      }
+
+      results.push({
+        jobId: notification.jobId,
+        notificationFilePath: expired.filePath,
+        status: escalateOnExpiry ? "escalated" : "expired",
+        escalationNotificationFilePath: escalationFilePath
+      });
+    }
+
+    return {
+      timestamp: now.toISOString(),
+      pendingCount: pending.length,
+      expiredCount: results.length,
+      results
+    };
+  }
+
+  async sendTestDelivery({ profileName, mode = "shadow", message }) {
+    const runtime = await this.loader.loadAll();
+    const profileConfig = await this.resolveProfileConfig(profileName, this.resolveProfileEntry(runtime.delivery, profileName) || {});
+    if (!profileConfig.adapter) {
+      throw new Error(`Unknown delivery profile ${profileName}`);
+    }
+
+    const adapterId = mode === "shadow" ? "shadow" : profileConfig.adapter;
+    const adapter = this.createAdapter(adapterId);
+    return adapter.deliver(
+      {
+        jobId: "delivery-test",
+        stage: "test",
+        target: {
+          mode: profileConfig.channel || "same_thread"
+        },
+        message
+      },
+      {
+        profileName,
+        profileConfig
+      }
+    );
+  }
+}