openclaw-topic-shift-reset 0.1.1 → 0.3.0

package/src/index.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import type { OpenClawPluginApi, PluginHookMessageReceivedEvent } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import {
   readJsonFileWithFallback,
   withFileLock,
@@ -11,7 +11,7 @@ import {
 type PresetName = "conservative" | "balanced" | "aggressive";
 type EmbeddingProvider = "auto" | "none" | "openai" | "ollama";
 type HandoffMode = "none" | "summary" | "verbatim_last_n";
-type HandoffPreference = "none" | "summary" | "verbatim";
+type SoftSuspectAction = "none" | "ask";
 
 type EmbeddingConfig = {
   provider?: EmbeddingProvider;
@@ -21,6 +21,24 @@ type EmbeddingConfig = {
   timeoutMs?: number;
 };
 
+type HandoffConfig = {
+  mode?: HandoffMode;
+  lastN?: number;
+  maxChars?: number;
+};
+
+type SoftSuspectConfig = {
+  action?: SoftSuspectAction;
+  prompt?: string;
+  ttlSeconds?: number;
+};
+
+type StripRulesConfig = {
+  dropLinePrefixPatterns?: string[];
+  dropExactLines?: string[];
+  dropFencedBlockAfterHeaderPatterns?: string[];
+};
+
 type TopicShiftResetAdvancedConfig = {
   historyWindow?: number;
   minHistoryMessages?: number;
@@ -29,7 +47,12 @@ type TopicShiftResetAdvancedConfig = {
   minSignalChars?: number;
   minSignalTokenCount?: number;
   minSignalEntropy?: number;
+  minUniqueTokenRatio?: number;
+  shortMessageTokenLimit?: number;
+  embeddingTriggerMargin?: number;
   stripEnvelope?: boolean;
+  stripRules?: StripRulesConfig;
+  handoffTailReadMaxBytes?: number;
   softConsecutiveSignals?: number;
   cooldownMinutes?: number;
   ignoredProviders?: string[];
@@ -39,18 +62,14 @@ type TopicShiftResetAdvancedConfig = {
   hardSimilarityThreshold?: number;
   softNoveltyThreshold?: number;
   hardNoveltyThreshold?: number;
-  handoff?: HandoffPreference | HandoffMode;
-  handoffLastN?: number;
-  handoffMaxChars?: number;
-  embeddings?: EmbeddingProvider;
-  embedding?: EmbeddingConfig;
 };
 
 type TopicShiftResetConfig = {
   enabled?: boolean;
   preset?: PresetName;
-  embeddings?: EmbeddingProvider;
-  handoff?: HandoffPreference;
+  embedding?: EmbeddingConfig;
+  handoff?: HandoffConfig;
+  softSuspect?: SoftSuspectConfig;
   dryRun?: boolean;
   debug?: boolean;
   advanced?: TopicShiftResetAdvancedConfig;
@@ -65,7 +84,16 @@ type ResolvedConfig = {
   minSignalChars: number;
   minSignalTokenCount: number;
   minSignalEntropy: number;
+  minUniqueTokenRatio: number;
+  shortMessageTokenLimit: number;
+  embeddingTriggerMargin: number;
   stripEnvelope: boolean;
+  stripRules: {
+    dropLinePrefixPatterns: RegExp[];
+    dropExactLines: Set<string>;
+    dropFencedBlockAfterHeaderPatterns: RegExp[];
+  };
+  handoffTailReadMaxBytes: number;
   softConsecutiveSignals: number;
   cooldownMinutes: number;
   ignoredProviders: Set<string>;
@@ -75,9 +103,16 @@ type ResolvedConfig = {
   hardSimilarityThreshold: number;
   softNoveltyThreshold: number;
   hardNoveltyThreshold: number;
-  handoffMode: HandoffMode;
-  handoffLastN: number;
-  handoffMaxChars: number;
+  handoff: {
+    mode: HandoffMode;
+    lastN: number;
+    maxChars: number;
+  };
+  softSuspect: {
+    action: SoftSuspectAction;
+    prompt: string;
+    ttlMs: number;
+  };
   embedding: {
     provider: EmbeddingProvider;
     model?: string;
@@ -113,18 +148,55 @@ type SessionState = {
   pendingSoftSignals: number;
   pendingEntries: HistoryEntry[];
   lastResetAt?: number;
+  topicCentroid?: number[];
+  topicCount: number;
+  topicDim?: number;
+  lastSeenAt: number;
+};
+
+type PersistedHistoryEntry = {
+  tokens: string[];
+  at: number;
+  embedding?: number[];
+};
+
+type PersistedSessionState = {
+  history: PersistedHistoryEntry[];
+  pendingSoftSignals: number;
+  pendingEntries: PersistedHistoryEntry[];
+  lastResetAt?: number;
+  topicCentroid?: number[];
+  topicCount: number;
+  topicDim?: number;
   lastSeenAt: number;
 };
 
+type PersistedRuntimeState = {
+  version: number;
+  savedAt: number;
+  sessionStateBySessionKey: Record<string, PersistedSessionState>;
+  recentRotationBySession: Record<string, number>;
+};
+
 type ClassifierMetrics = {
   score: number;
   novelty: number;
   lexicalDistance: number;
+  uniqueTokenRatio: number;
+  entropy: number;
   similarity?: number;
   usedEmbedding: boolean;
   pendingSoftSignals: number;
 };
 
+type LexicalFeatures = {
+  score: number;
+  novelty: number;
+  lexicalDistance: number;
+  uniqueTokenRatio: number;
+  entropy: number;
+};
+
 type ClassificationDecision =
   | { kind: "warmup" | "stable" | "suspect"; metrics: ClassifierMetrics; reason: string }
   | { kind: "rotate-hard" | "rotate-soft"; metrics: ClassifierMetrics; reason: string };
@@ -134,9 +206,9 @@ type EmbeddingBackend = {
   embed: (text: string) => Promise<number[] | null>;
 };
 
-type ResolvedFastSession = {
-  sessionKey: string;
-  routeKind: "direct" | "group" | "thread";
+type FastMessageEventLike = {
+  from?: string;
+  metadata?: Record<string, unknown>;
 };
 
 type TranscriptMessage = {
@@ -207,15 +279,30 @@ const PRESETS = {
 const DEFAULTS = {
   enabled: true,
   preset: "balanced" as PresetName,
-  handoff: "summary" as HandoffPreference,
+  handoffMode: "summary" as HandoffMode,
   handoffLastN: 6,
   handoffMaxChars: 220,
+  softSuspectAction: "ask" as SoftSuspectAction,
+  softSuspectPrompt:
+    "Potential topic shift detected. Ask one short clarification question to confirm the user's new goal before proceeding.",
+  softSuspectTtlSeconds: 120,
   embeddingProvider: "auto" as EmbeddingProvider,
   embeddingTimeoutMs: 7000,
   minSignalChars: 20,
   minSignalTokenCount: 3,
   minSignalEntropy: 1.2,
+  minUniqueTokenRatio: 0.34,
+  shortMessageTokenLimit: 6,
+  embeddingTriggerMargin: 0.08,
   stripEnvelope: true,
+  stripDropLinePrefixPatterns: [
+    "^[A-Za-z][A-Za-z _-]{0,30}:\\s*\\[",
+  ],
+  stripDropExactLines: [] as string[],
+  stripDropFencedBlockAfterHeaderPatterns: [
+    "^[A-Za-z][A-Za-z _-]{0,40}:\\s*\\([^)]*(metadata|context)[^)]*\\):?$",
+  ],
+  handoffTailReadMaxBytes: 512 * 1024,
   dryRun: false,
   debug: false,
 } as const;
@@ -228,7 +315,7 @@ const LOCK_OPTIONS = {
     maxTimeout: 250,
     randomize: true,
   },
-  stale: 45_000,
+  stale: 30 * 60 * 1000,
 } as const;
 
 const MAX_TRACKED_SESSIONS = 10_000;
@@ -236,6 +323,13 @@ const STALE_SESSION_STATE_MS = 4 * 60 * 60 * 1000;
 const MAX_RECENT_FAST_EVENTS = 20_000;
 const FAST_EVENT_TTL_MS = 5 * 60 * 1000;
 const ROTATION_DEDUPE_MS = 25_000;
+const CROSS_PATH_DEDUPE_MS = 15_000;
+const PERSISTENCE_SCHEMA_VERSION = 1;
+const PERSISTENCE_FILE_NAME = "runtime-state.v1.json";
+const PERSISTENCE_FLUSH_DEBOUNCE_MS = 1_200;
+const MAX_TOKENS_PER_PERSISTED_ENTRY = 256;
+const MAX_PERSISTED_EMBEDDING_DIM = 8_192;
+const MAX_PERSISTED_PENDING_ENTRIES = 8;
 
 function clampInt(value: unknown, fallback: number, min: number, max: number): number {
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -264,15 +358,6 @@ function clampFloat(value: unknown, fallback: number, min: number, max: number):
   return value;
 }
 
-function pickDefined<T>(...values: Array<T | undefined>): T | undefined {
-  for (const value of values) {
-    if (value !== undefined) {
-      return value;
-    }
-  }
-  return undefined;
-}
-
 function normalizePreset(value: unknown): PresetName {
   if (typeof value !== "string") {
     return DEFAULTS.preset;
@@ -300,18 +385,268 @@ function normalizeEmbeddingProvider(value: unknown): EmbeddingProvider {
   return DEFAULTS.embeddingProvider;
 }
 
-function normalizeHandoffPreference(value: unknown): HandoffPreference {
+function normalizeHandoffMode(value: unknown): HandoffMode {
+  if (typeof value !== "string") {
+    return DEFAULTS.handoffMode;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "none" || normalized === "summary" || normalized === "verbatim_last_n") {
+    return normalized as HandoffMode;
+  }
+  return DEFAULTS.handoffMode;
+}
+
+function normalizeSoftSuspectAction(value: unknown): SoftSuspectAction {
   if (typeof value !== "string") {
-    return DEFAULTS.handoff;
+    return DEFAULTS.softSuspectAction;
   }
   const normalized = value.trim().toLowerCase();
-  if (normalized === "none" || normalized === "summary") {
+  if (normalized === "none" || normalized === "ask") {
     return normalized;
   }
-  if (normalized === "verbatim" || normalized === "verbatim_last_n") {
-    return "verbatim";
+  return DEFAULTS.softSuspectAction;
+}
+
+function compileRegexList(values: unknown, fallback: readonly string[]): RegExp[] {
+  const source = Array.isArray(values) ? values : fallback;
+  const out: RegExp[] = [];
+  for (const item of source) {
+    if (typeof item !== "string") {
+      continue;
+    }
+    const pattern = item.trim();
+    if (!pattern) {
+      continue;
+    }
+    try {
+      out.push(new RegExp(pattern));
+    } catch {
+      continue;
+    }
+  }
+  return out;
+}
+
+function normalizeStringList(values: unknown, fallback: readonly string[]): string[] {
+  const source = Array.isArray(values) ? values : fallback;
+  return source
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function sanitizeTimestamp(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
+function sanitizeEmbeddingVector(value: unknown): number[] | undefined {
+  if (!Array.isArray(value) || value.length === 0) {
+    return undefined;
+  }
+  const out: number[] = [];
+  for (const item of value) {
+    if (typeof item !== "number" || !Number.isFinite(item)) {
+      continue;
+    }
+    out.push(item);
+    if (out.length >= MAX_PERSISTED_EMBEDDING_DIM) {
+      break;
+    }
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+function normalizeTokenArray(values: unknown): string[] {
+  if (!Array.isArray(values)) {
+    return [];
   }
-  return DEFAULTS.handoff;
+  const out: string[] = [];
+  for (const value of values) {
+    if (typeof value !== "string") {
+      continue;
+    }
+    const token = value.trim();
+    if (!token) {
+      continue;
+    }
+    out.push(token);
+    if (out.length >= MAX_TOKENS_PER_PERSISTED_ENTRY) {
+      break;
+    }
+  }
+  return out;
+}
+
+function serializeHistoryEntry(entry: HistoryEntry, includeEmbedding: boolean): PersistedHistoryEntry {
+  const tokens = [...entry.tokens]
+    .map((token) => token.trim())
+    .filter(Boolean)
+    .slice(0, MAX_TOKENS_PER_PERSISTED_ENTRY);
+  const persisted: PersistedHistoryEntry = {
+    tokens,
+    at: sanitizeTimestamp(entry.at, Date.now()),
+  };
+  if (includeEmbedding && Array.isArray(entry.embedding) && entry.embedding.length > 0) {
+    persisted.embedding = entry.embedding.filter(Number.isFinite).slice(0, MAX_PERSISTED_EMBEDDING_DIM);
+  }
+  return persisted;
+}
+
+function deserializeHistoryEntry(
+  value: unknown,
+  includeEmbedding: boolean,
+): HistoryEntry | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const record = value as Partial<PersistedHistoryEntry>;
+  const tokens = normalizeTokenArray(record.tokens);
+  if (tokens.length === 0) {
+    return null;
+  }
+  const entry: HistoryEntry = {
+    tokens: new Set(tokens),
+    at: sanitizeTimestamp(record.at, Date.now()),
+  };
+  if (includeEmbedding) {
+    entry.embedding = sanitizeEmbeddingVector(record.embedding);
+  }
+  return entry;
+}
+
+function serializeSessionState(state: SessionState): PersistedSessionState {
+  const history = trimHistory(state.history, 40).map((entry) => serializeHistoryEntry(entry, false));
+  const pendingEntries = trimHistory(state.pendingEntries, MAX_PERSISTED_PENDING_ENTRIES).map((entry) =>
+    serializeHistoryEntry(entry, true),
+  );
+  const topicCentroid =
+    Array.isArray(state.topicCentroid) && state.topicCentroid.length > 0
+      ? state.topicCentroid.filter(Number.isFinite).slice(0, MAX_PERSISTED_EMBEDDING_DIM)
+      : undefined;
+
+  return {
+    history,
+    pendingSoftSignals: clampInt(state.pendingSoftSignals, 0, 0, 16),
+    pendingEntries,
+    lastResetAt:
+      typeof state.lastResetAt === "number" && Number.isFinite(state.lastResetAt)
+        ? Math.floor(state.lastResetAt)
+        : undefined,
+    topicCentroid,
+    topicCount: clampInt(state.topicCount, topicCentroid ? 1 : 0, 0, Number.MAX_SAFE_INTEGER),
+    topicDim:
+      typeof state.topicDim === "number" && Number.isFinite(state.topicDim) && state.topicDim > 0
+        ? Math.floor(state.topicDim)
+        : topicCentroid?.length,
+    lastSeenAt: sanitizeTimestamp(state.lastSeenAt, Date.now()),
+  };
+}
+
+function deserializeSessionState(value: unknown, cfg: ResolvedConfig): SessionState | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const record = value as Partial<PersistedSessionState>;
+  const historySource = Array.isArray(record.history) ? record.history : [];
+  const pendingSource = Array.isArray(record.pendingEntries) ? record.pendingEntries : [];
+
+  const history = trimHistory(
+    historySource
+      .map((entry) => deserializeHistoryEntry(entry, false))
+      .filter((entry): entry is HistoryEntry => !!entry),
+    cfg.historyWindow,
+  );
+  const pendingEntries = trimHistory(
+    pendingSource
+      .map((entry) => deserializeHistoryEntry(entry, true))
+      .filter((entry): entry is HistoryEntry => !!entry),
+    Math.max(MAX_PERSISTED_PENDING_ENTRIES, cfg.softConsecutiveSignals),
+  );
+
+  const topicCentroid = sanitizeEmbeddingVector(record.topicCentroid);
+  const topicCount = clampInt(record.topicCount, topicCentroid ? 1 : 0, 0, Number.MAX_SAFE_INTEGER);
+  const topicDim = clampInt(record.topicDim, topicCentroid?.length ?? 0, 0, MAX_PERSISTED_EMBEDDING_DIM);
+
+  return {
+    history,
+    pendingSoftSignals: clampInt(record.pendingSoftSignals, 0, 0, 16),
+    pendingEntries,
+    lastResetAt:
+      typeof record.lastResetAt === "number" && Number.isFinite(record.lastResetAt)
+        ? Math.floor(record.lastResetAt)
+        : undefined,
+    topicCentroid,
+    topicCount,
+    topicDim: topicDim > 0 ? topicDim : topicCentroid?.length,
+    lastSeenAt: sanitizeTimestamp(record.lastSeenAt, Date.now()),
+  };
+}
+
+function normalizeProviderId(raw: string): string {
+  const provider = raw.trim().toLowerCase();
+  if (!provider) {
+    return "";
+  }
+  if (provider === "telegram" || provider.includes("telegram")) {
+    return "telegram";
+  }
+  if (
+    provider === "whatsapp" ||
+    provider.includes("whatsapp") ||
+    provider.includes("baileys")
+  ) {
+    return "whatsapp";
+  }
+  if (provider === "signal" || provider.includes("signal")) {
+    return "signal";
+  }
+  if (provider === "discord" || provider.includes("discord")) {
+    return "discord";
+  }
+  if (provider === "slack" || provider.includes("slack")) {
+    return "slack";
+  }
+  if (provider === "matrix" || provider.includes("matrix")) {
+    return "matrix";
+  }
+  if (provider === "msteams" || provider.includes("teams")) {
+    return "msteams";
+  }
+  if (provider === "imessage" || provider.includes("imessage") || provider.includes("bluebubbles")) {
+    return "imessage";
+  }
+  if (provider === "web" || provider.includes("webchat")) {
+    return "web";
+  }
+  if (provider === "voice" || provider.includes("voice")) {
+    return "voice";
+  }
+  if (provider.includes("openai")) {
+    return "openai";
+  }
+  if (provider.includes("anthropic")) {
+    return "anthropic";
+  }
+  if (provider.includes("ollama")) {
+    return "ollama";
+  }
+  return provider;
+}
+
+function isInternalNonUserProvider(provider: string): boolean {
+  if (!provider) {
+    return false;
+  }
+  return (
+    provider === "heartbeat" ||
+    provider === "exec-event" ||
+    provider.startsWith("cron") ||
+    provider.includes("heartbeat") ||
+    provider.includes("cron")
+  );
 }
 
 function resolveConfig(raw: unknown): ResolvedConfig {
@@ -320,9 +655,17 @@ function resolveConfig(raw: unknown): ResolvedConfig {
     obj.advanced && typeof obj.advanced === "object"
       ? (obj.advanced as TopicShiftResetAdvancedConfig)
       : {};
-  const advancedEmbedding =
-    advanced.embedding && typeof advanced.embedding === "object"
-      ? (advanced.embedding as EmbeddingConfig)
+  const embedding =
+    obj.embedding && typeof obj.embedding === "object" ? (obj.embedding as EmbeddingConfig) : {};
+  const handoff =
+    obj.handoff && typeof obj.handoff === "object" ? (obj.handoff as HandoffConfig) : {};
+  const softSuspect =
+    obj.softSuspect && typeof obj.softSuspect === "object"
+      ? (obj.softSuspect as SoftSuspectConfig)
+      : {};
+  const stripRules =
+    advanced.stripRules && typeof advanced.stripRules === "object"
+      ? (advanced.stripRules as StripRulesConfig)
       : {};
 
   const preset = normalizePreset(obj.preset);
@@ -331,15 +674,13 @@ function resolveConfig(raw: unknown): ResolvedConfig {
   const ignoredProviders = new Set(
     Array.isArray(advanced.ignoredProviders)
       ? advanced.ignoredProviders
-          .map((value) => (typeof value === "string" ? value.trim().toLowerCase() : ""))
+          .map((value) =>
+            typeof value === "string" ? normalizeProviderId(value.trim().toLowerCase()) : "",
+          )
           .filter(Boolean)
       : [],
   );
 
-  const handoffPreference = normalizeHandoffPreference(pickDefined(advanced.handoff, obj.handoff));
-  const handoffMode: HandoffMode =
-    handoffPreference === "verbatim" ? "verbatim_last_n" : handoffPreference;
-
   return {
     enabled: obj.enabled ?? DEFAULTS.enabled,
     historyWindow: clampInt(advanced.historyWindow, presetConfig.historyWindow, 2, 40),
@@ -369,7 +710,44 @@ function resolveConfig(raw: unknown): ResolvedConfig {
       0,
       8,
     ),
+    minUniqueTokenRatio: clampFloat(
+      advanced.minUniqueTokenRatio,
+      DEFAULTS.minUniqueTokenRatio,
+      0,
+      1,
+    ),
+    shortMessageTokenLimit: clampInt(
+      advanced.shortMessageTokenLimit,
+      DEFAULTS.shortMessageTokenLimit,
+      1,
+      40,
+    ),
+    embeddingTriggerMargin: clampFloat(
+      advanced.embeddingTriggerMargin,
+      DEFAULTS.embeddingTriggerMargin,
+      0,
+      0.5,
+    ),
     stripEnvelope: advanced.stripEnvelope ?? DEFAULTS.stripEnvelope,
+    stripRules: {
+      dropLinePrefixPatterns: compileRegexList(
+        stripRules.dropLinePrefixPatterns,
+        DEFAULTS.stripDropLinePrefixPatterns,
+      ),
+      dropExactLines: new Set(
+        normalizeStringList(stripRules.dropExactLines, DEFAULTS.stripDropExactLines),
+      ),
+      dropFencedBlockAfterHeaderPatterns: compileRegexList(
+        stripRules.dropFencedBlockAfterHeaderPatterns,
+        DEFAULTS.stripDropFencedBlockAfterHeaderPatterns,
+      ),
+    },
+    handoffTailReadMaxBytes: clampInt(
+      advanced.handoffTailReadMaxBytes,
+      DEFAULTS.handoffTailReadMaxBytes,
+      64 * 1024,
+      8 * 1024 * 1024,
+    ),
     softConsecutiveSignals: clampInt(
       advanced.softConsecutiveSignals,
       presetConfig.softConsecutiveSignals,
@@ -404,26 +782,34 @@ function resolveConfig(raw: unknown): ResolvedConfig {
       0,
       1,
     ),
-    handoffMode,
-    handoffLastN: clampInt(advanced.handoffLastN, DEFAULTS.handoffLastN, 1, 20),
-    handoffMaxChars: clampInt(advanced.handoffMaxChars, DEFAULTS.handoffMaxChars, 60, 800),
+    handoff: {
+      mode: normalizeHandoffMode(handoff.mode),
+      lastN: clampInt(handoff.lastN, DEFAULTS.handoffLastN, 1, 20),
+      maxChars: clampInt(handoff.maxChars, DEFAULTS.handoffMaxChars, 60, 800),
+    },
+    softSuspect: {
+      action: normalizeSoftSuspectAction(softSuspect.action),
+      prompt:
+        typeof softSuspect.prompt === "string" && softSuspect.prompt.trim()
+          ? softSuspect.prompt.trim()
+          : DEFAULTS.softSuspectPrompt,
+      ttlMs: clampInt(softSuspect.ttlSeconds, DEFAULTS.softSuspectTtlSeconds, 10, 1_800) * 1000,
+    },
     embedding: {
-      provider: normalizeEmbeddingProvider(
-        pickDefined(advanced.embeddings, advancedEmbedding.provider, obj.embeddings),
-      ),
+      provider: normalizeEmbeddingProvider(embedding.provider),
       model: (() => {
-        const rawModel = advancedEmbedding.model;
+        const rawModel = embedding.model;
         return typeof rawModel === "string" ? rawModel.trim() : undefined;
       })(),
       baseUrl: (() => {
-        const rawBaseUrl = advancedEmbedding.baseUrl;
+        const rawBaseUrl = embedding.baseUrl;
         return typeof rawBaseUrl === "string" ? rawBaseUrl.trim() : undefined;
       })(),
       apiKey: (() => {
-        const rawApiKey = advancedEmbedding.apiKey;
+        const rawApiKey = embedding.apiKey;
         return typeof rawApiKey === "string" ? rawApiKey.trim() : undefined;
       })(),
-      timeoutMs: clampInt(advancedEmbedding.timeoutMs, DEFAULTS.embeddingTimeoutMs, 1000, 30_000),
+      timeoutMs: clampInt(embedding.timeoutMs, DEFAULTS.embeddingTimeoutMs, 1000, 30_000),
     },
     dryRun: obj.dryRun ?? DEFAULTS.dryRun,
     debug: obj.debug ?? DEFAULTS.debug,
@@ -484,13 +870,27 @@ function tokenEntropy(tokens: string[]): number {
   return entropy;
 }
 
-function stripClassifierEnvelope(text: string): string {
+function matchesAny(patterns: RegExp[], value: string): boolean {
+  for (const pattern of patterns) {
+    if (pattern.test(value)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function stripClassifierEnvelope(
+  text: string,
+  rules: ResolvedConfig["stripRules"],
+): string {
   const lines = text.replace(/\r\n/g, "\n").split("\n");
   const kept: string[] = [];
   let skipFence = false;
   let expectingMetadataFence = false;
+  let sawSemanticContent = false;
 
-  for (const line of lines) {
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
     const trimmed = line.trim();
     if (skipFence) {
       if (trimmed.startsWith("```")) {
@@ -499,14 +899,17 @@ function stripClassifierEnvelope(text: string): string {
       continue;
     }
 
-    if (
-      trimmed === "Conversation info (untrusted metadata):" ||
-      trimmed === "Replied message (untrusted, for context):"
-    ) {
+    if (matchesAny(rules.dropFencedBlockAfterHeaderPatterns, trimmed)) {
       expectingMetadataFence = true;
       continue;
     }
 
+    // Drop top fenced metadata envelopes even if header wording changes.
+    if (!sawSemanticContent && index < 12 && (trimmed === "```" || trimmed === "```json")) {
+      skipFence = true;
+      continue;
+    }
+
     if (expectingMetadataFence && trimmed.startsWith("```")) {
       skipFence = true;
       expectingMetadataFence = false;
@@ -515,17 +918,14 @@ function stripClassifierEnvelope(text: string): string {
 
     expectingMetadataFence = false;
 
-    if (
-      trimmed.startsWith("System: [") ||
-      trimmed.startsWith("Current time:") ||
-      trimmed.startsWith("Read HEARTBEAT.md if it exists") ||
-      trimmed.startsWith("To send an image back, prefer the message tool") ||
-      trimmed.startsWith("[media attached:")
-    ) {
+    if (rules.dropExactLines.has(trimmed) || matchesAny(rules.dropLinePrefixPatterns, trimmed)) {
       continue;
     }
 
     kept.push(line);
+    if (trimmed) {
+      sawSemanticContent = true;
+    }
   }
 
   return kept.join("\n").replace(/\n{3,}/g, "\n\n").trim();
@@ -592,29 +992,36 @@ function cosineSimilarity(a: number[], b: number[]): number | undefined {
   return dot / (Math.sqrt(normA) * Math.sqrt(normB));
 }
 
-function centroid(vectors: number[][]): number[] | undefined {
-  if (vectors.length === 0) {
-    return undefined;
-  }
-  const dim = vectors[0]?.length ?? 0;
-  if (!dim) {
-    return undefined;
+function seedTopicCentroid(state: SessionState, vector?: number[]): void {
+  if (!Array.isArray(vector) || vector.length === 0) {
+    state.topicCentroid = undefined;
+    state.topicCount = 0;
+    state.topicDim = undefined;
+    return;
   }
-  for (const vector of vectors) {
-    if (vector.length !== dim) {
-      return undefined;
-    }
+  state.topicCentroid = [...vector];
+  state.topicCount = 1;
+  state.topicDim = vector.length;
+}
+
+function updateTopicCentroid(state: SessionState, vector?: number[]): void {
+  if (!Array.isArray(vector) || vector.length === 0) {
+    return;
   }
-  const out = new Array<number>(dim).fill(0);
-  for (const vector of vectors) {
-    for (let i = 0; i < dim; i += 1) {
-      out[i] += vector[i];
-    }
+  if (
+    !Array.isArray(state.topicCentroid) ||
+    state.topicCentroid.length !== vector.length ||
+    !state.topicCount
+  ) {
+    seedTopicCentroid(state, vector);
+    return;
   }
-  for (let i = 0; i < dim; i += 1) {
-    out[i] /= vectors.length;
+  const nextCount = state.topicCount + 1;
+  for (let i = 0; i < vector.length; i += 1) {
+    state.topicCentroid[i] += (vector[i] - state.topicCentroid[i]) / nextCount;
   }
-  return out;
+  state.topicCount = nextCount;
+  state.topicDim = vector.length;
 }
 
 function trimHistory(entries: HistoryEntry[], limit: number): HistoryEntry[] {
@@ -645,7 +1052,10 @@ function looksLikeGroup(value?: string): boolean {
   );
 }
 
-function inferFastPeer(event: PluginHookMessageReceivedEvent, ctx: { conversationId?: string }) {
+function inferFastPeer(
+  event: FastMessageEventLike,
+  ctx: { conversationId?: string },
+): { kind: "direct" | "group" | "channel"; id: string } {
   const from = event.from?.trim() ?? "";
   const conversationId = ctx.conversationId?.trim() || from;
   const metadata = (event.metadata ?? {}) as Record<string, unknown>;
@@ -659,12 +1069,13 @@ function inferFastPeer(event: PluginHookMessageReceivedEvent, ctx: { conversatio
 
   if (threadId) {
     return {
-      kind: "thread" as const,
+      kind: "group",
       id: `${conversationId || from}:thread:${threadId}`,
     };
   }
 
-  const kind = looksLikeGroup(conversationId) || looksLikeGroup(from) ? "group" : "direct";
+  const kind: "group" | "direct" =
+    looksLikeGroup(conversationId) || looksLikeGroup(from) ? "group" : "direct";
   return {
     kind,
     id: conversationId || from || "unknown",
@@ -763,45 +1174,84 @@ function resolveEmbeddingBackend(cfg: ResolvedConfig): EmbeddingBackend | null {
   return createOllamaBackend(cfg);
 }
 
-function classifyMessage(params: {
+function computeLexicalFeatures(params: {
   cfg: ResolvedConfig;
-  state: SessionState;
   entry: HistoryEntry;
-  now: number;
-}): ClassificationDecision {
-  const { cfg, state, entry, now } = params;
-  const baselineEntries = state.history;
-  const baselineTokens = unionTokens(baselineEntries);
-
-  const lexicalSimilarity = jaccardSimilarity(entry.tokens, baselineTokens);
+  tokenList: string[];
+  baselineTokens: Set<string>;
+}): LexicalFeatures {
+  const lexicalSimilarity = jaccardSimilarity(params.entry.tokens, params.baselineTokens);
   const lexicalDistance = 1 - lexicalSimilarity;
-  const novelty = noveltyRatio(entry.tokens, baselineTokens);
+  const novelty = noveltyRatio(params.entry.tokens, params.baselineTokens);
+  const uniqueTokenRatio =
+    params.tokenList.length > 0 ? params.entry.tokens.size / params.tokenList.length : 0;
+  const entropy = tokenEntropy(params.tokenList);
 
-  const baseVectors = baselineEntries
-    .map((item) => item.embedding)
-    .filter((vector): vector is number[] => Array.isArray(vector) && vector.length > 0);
-  const baseCentroid = centroid(baseVectors);
-  const similarity =
-    entry.embedding && baseCentroid ? cosineSimilarity(entry.embedding, baseCentroid) : undefined;
-  const usedEmbedding = typeof similarity === "number";
+  let score = 0.55 * lexicalDistance + 0.45 * novelty;
+  if (uniqueTokenRatio < params.cfg.minUniqueTokenRatio) {
+    score -= (params.cfg.minUniqueTokenRatio - uniqueTokenRatio) * 0.4;
+  }
+  if (params.tokenList.length <= params.cfg.shortMessageTokenLimit && entropy < params.cfg.minSignalEntropy) {
+    score -= (params.cfg.minSignalEntropy - entropy) * 0.06;
+  }
 
-  const score = usedEmbedding
-    ? 0.7 * (1 - similarity) + 0.15 * lexicalDistance + 0.15 * novelty
-    : 0.55 * lexicalDistance + 0.45 * novelty;
+  return {
+    score: Math.max(0, Math.min(1, score)),
+    novelty,
+    lexicalDistance,
+    uniqueTokenRatio,
+    entropy,
+  };
+}
+
+function shouldRequestEmbedding(params: {
+  cfg: ResolvedConfig;
+  backendAvailable: boolean;
+  lexical: LexicalFeatures;
+  warmup: boolean;
+  cooldownActive: boolean;
+}): boolean {
+  if (!params.backendAvailable || params.warmup || params.cooldownActive) {
+    return false;
+  }
+  if (params.lexical.score >= params.cfg.softScoreThreshold - params.cfg.embeddingTriggerMargin) {
+    return true;
+  }
+  return (
+    params.lexical.novelty >= params.cfg.softNoveltyThreshold * 0.9 &&
+    params.lexical.lexicalDistance >= 0.35
+  );
+}
+
+function classifyMessage(params: {
+  cfg: ResolvedConfig;
+  state: SessionState;
+  baselineTokenCount: number;
+  lexical: LexicalFeatures;
+  similarity?: number;
+  usedEmbedding: boolean;
+  now: number;
+}): ClassificationDecision {
+  const { cfg, state, now } = params;
+  const score =
+    params.usedEmbedding && typeof params.similarity === "number"
+      ? 0.7 * (1 - params.similarity) +
+        0.15 * params.lexical.lexicalDistance +
+        0.15 * params.lexical.novelty
+      : params.lexical.score;
 
   const metrics = {
     score,
-    novelty,
-    lexicalDistance,
-    similarity,
-    usedEmbedding,
+    novelty: params.lexical.novelty,
+    lexicalDistance: params.lexical.lexicalDistance,
+    uniqueTokenRatio: params.lexical.uniqueTokenRatio,
+    entropy: params.lexical.entropy,
+    similarity: params.similarity,
+    usedEmbedding: params.usedEmbedding,
     pendingSoftSignals: state.pendingSoftSignals,
   } satisfies ClassifierMetrics;
 
-  if (
-    baselineEntries.length < cfg.minHistoryMessages ||
-    baselineTokens.size < cfg.minMeaningfulTokens
-  ) {
+  if (state.history.length < cfg.minHistoryMessages || params.baselineTokenCount < cfg.minMeaningfulTokens) {
     return { kind: "warmup", metrics, reason: "warmup" };
   }
 
@@ -814,8 +1264,11 @@ function classifyMessage(params: {
 
   const hardSignal =
     score >= cfg.hardScoreThreshold ||
-    ((typeof similarity === "number" ? similarity <= cfg.hardSimilarityThreshold : false) &&
-      novelty >= cfg.hardNoveltyThreshold);
+    (params.usedEmbedding && typeof params.similarity === "number"
+      ? params.similarity <= cfg.hardSimilarityThreshold &&
+        params.lexical.novelty >= cfg.hardNoveltyThreshold
+      : params.lexical.novelty >= cfg.hardNoveltyThreshold &&
+        params.lexical.lexicalDistance >= 0.65);
 
   if (hardSignal) {
     return { kind: "rotate-hard", metrics, reason: "hard-threshold" };
@@ -823,9 +1276,11 @@ function classifyMessage(params: {
 
   const softSignal =
     score >= cfg.softScoreThreshold ||
-    ((typeof similarity === "number" ? similarity <= cfg.softSimilarityThreshold : false) &&
-      novelty >= cfg.softNoveltyThreshold) ||
-    (!usedEmbedding && novelty >= cfg.softNoveltyThreshold && lexicalDistance >= 0.45);
+    (params.usedEmbedding && typeof params.similarity === "number"
+      ? params.similarity <= cfg.softSimilarityThreshold &&
+        params.lexical.novelty >= cfg.softNoveltyThreshold
+      : params.lexical.novelty >= cfg.softNoveltyThreshold &&
+        params.lexical.lexicalDistance >= 0.45);
 
   if (!softSignal) {
     return { kind: "stable", metrics, reason: "stable" };
@@ -885,15 +1340,10 @@ function resolveSessionFilePathFromEntry(params: {
   return path.resolve(sessionsDir, `${sessionId}.jsonl`);
 }
 
-async function readTranscriptTail(params: {
-  sessionFile: string;
-  takeLast: number;
-}): Promise<TranscriptMessage[]> {
-  const raw = await fs.readFile(params.sessionFile, "utf-8");
-  const lines = raw.split("\n");
+function parseTranscriptTailLines(lines: string[], takeLast: number): TranscriptMessage[] {
   const messages: TranscriptMessage[] = [];
-
-  for (const line of lines) {
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i] ?? "";
     const trimmed = line.trim();
     if (!trimmed) {
       continue;
@@ -924,12 +1374,67 @@ async function readTranscriptTail(params: {
       continue;
     }
     messages.push({ role, text });
+    if (messages.length >= takeLast) {
+      break;
+    }
   }
+  messages.reverse();
+  return messages;
+}
 
-  if (messages.length <= params.takeLast) {
-    return messages;
+async function readTranscriptTail(params: {
+  sessionFile: string;
+  takeLast: number;
+  maxBytes: number;
+  onFallbackFullRead?: () => void;
+}): Promise<TranscriptMessage[]> {
+  const fd = await fs.open(params.sessionFile, "r");
+  let fallbackFullRead = false;
+  try {
+    const stat = await fd.stat();
+    if (stat.size <= 0) {
+      return [];
+    }
+
+    let position = stat.size;
+    let bytesReadTotal = 0;
+    const chunks: string[] = [];
+    while (position > 0 && bytesReadTotal < params.maxBytes) {
+      const remainingBudget = params.maxBytes - bytesReadTotal;
+      const toRead = Math.min(64 * 1024, position, remainingBudget);
+      if (toRead <= 0) {
+        break;
+      }
+      const nextPosition = position - toRead;
+      const buffer = Buffer.allocUnsafe(toRead);
+      const result = await fd.read(buffer, 0, toRead, nextPosition);
+      if (result.bytesRead <= 0) {
+        break;
+      }
+      chunks.unshift(buffer.subarray(0, result.bytesRead).toString("utf-8"));
+      position = nextPosition;
+      bytesReadTotal += result.bytesRead;
+      if (chunks.join("").split("\n").length > params.takeLast * 30) {
+        break;
+      }
+    }
+
+    const tail = parseTranscriptTailLines(chunks.join("").split("\n"), params.takeLast);
+    if (tail.length >= params.takeLast || bytesReadTotal >= stat.size) {
+      return tail;
+    }
+    fallbackFullRead = true;
+  } finally {
+    await fd.close();
   }
-  return messages.slice(messages.length - params.takeLast);
+
+  if (!fallbackFullRead) {
+    return [];
+  }
+
+  params.onFallbackFullRead?.();
+  const raw = await fs.readFile(params.sessionFile, "utf-8");
+  return parseTranscriptTailLines(raw.split("\n"), params.takeLast);
 }
 
 function truncateText(text: string, maxChars: number): string {
@@ -968,7 +1473,7 @@ async function buildHandoffEventFromPreviousSession(params: {
   previousEntry?: SessionEntryLike;
   logger: OpenClawPluginApi["logger"];
 }): Promise<string | null> {
-  if (params.cfg.handoffMode === "none") {
+  if (params.cfg.handoff.mode === "none") {
     return null;
   }
   const sessionFile = resolveSessionFilePathFromEntry({
@@ -982,12 +1487,18 @@ async function buildHandoffEventFromPreviousSession(params: {
   try {
     const tail = await readTranscriptTail({
       sessionFile,
-      takeLast: params.cfg.handoffLastN,
+      takeLast: params.cfg.handoff.lastN,
+      maxBytes: params.cfg.handoffTailReadMaxBytes,
+      onFallbackFullRead: () => {
+        params.logger.warn(
+          `topic-shift-reset: handoff tail fallback full-read file=${sessionFile}`,
+        );
+      },
     });
     return formatHandoffEventText({
-      mode: params.cfg.handoffMode,
+      mode: params.cfg.handoff.mode,
       messages: tail,
-      maxChars: params.cfg.handoffMaxChars,
+      maxChars: params.cfg.handoff.maxChars,
     });
   } catch (error) {
     params.logger.warn(
@@ -997,15 +1508,17 @@ async function buildHandoffEventFromPreviousSession(params: {
   }
 }
 
-function pruneStateMaps(stateBySession: Map<string, SessionState>): void {
+function pruneStateMaps(stateBySession: Map<string, SessionState>): boolean {
+  let changed = false;
   const now = Date.now();
   for (const [sessionKey, state] of stateBySession) {
     if (now - state.lastSeenAt > STALE_SESSION_STATE_MS) {
       stateBySession.delete(sessionKey);
+      changed = true;
     }
   }
   if (stateBySession.size <= MAX_TRACKED_SESSIONS) {
-    return;
+    return changed;
   }
   const ordered = [...stateBySession.entries()].sort((a, b) => a[1].lastSeenAt - b[1].lastSeenAt);
   const toDrop = stateBySession.size - MAX_TRACKED_SESSIONS;
@@ -1013,19 +1526,23 @@ function pruneStateMaps(stateBySession: Map<string, SessionState>): void {
     const sessionKey = ordered[i]?.[0];
     if (sessionKey) {
       stateBySession.delete(sessionKey);
+      changed = true;
     }
   }
+  return changed;
 }
 
-function pruneRecentMap(map: Map<string, number>, ttlMs: number, maxSize: number): void {
+function pruneRecentMap(map: Map<string, number>, ttlMs: number, maxSize: number): boolean {
+  let changed = false;
   const now = Date.now();
   for (const [key, ts] of map) {
     if (now - ts > ttlMs) {
       map.delete(key);
+      changed = true;
     }
   }
   if (map.size <= maxSize) {
-    return;
+    return changed;
   }
   const ordered = [...map.entries()].sort((a, b) => a[1] - b[1]);
   const toDrop = map.size - maxSize;
@@ -1033,8 +1550,38 @@ function pruneRecentMap(map: Map<string, number>, ttlMs: number, maxSize: number
     const key = ordered[i]?.[0];
     if (key) {
       map.delete(key);
+      changed = true;
     }
   }
+  return changed;
+}
+
+function pruneRecentClassifiedMap(
+  map: Map<string, { at: number; source: "fast" | "fallback" }>,
+  ttlMs: number,
+  maxSize: number,
+): boolean {
+  let changed = false;
+  const now = Date.now();
+  for (const [key, value] of map) {
+    if (now - value.at > ttlMs) {
+      map.delete(key);
+      changed = true;
+    }
+  }
+  if (map.size <= maxSize) {
+    return changed;
+  }
+  const ordered = [...map.entries()].sort((a, b) => a[1].at - b[1].at);
+  const toDrop = map.size - maxSize;
+  for (let i = 0; i < toDrop; i += 1) {
+    const key = ordered[i]?.[0];
+    if (key) {
+      map.delete(key);
+      changed = true;
+    }
+  }
+  return changed;
 }
 
 async function rotateSessionEntry(params: {
@@ -1054,13 +1601,9 @@ async function rotateSessionEntry(params: {
   });
 
   if (params.cfg.dryRun) {
-    params.state.lastResetAt = Date.now();
-    params.state.pendingSoftSignals = 0;
-    params.state.pendingEntries = [];
-    params.state.history = trimHistory([params.entry], params.cfg.historyWindow);
     params.api.logger.info(
       [
-        `topic-shift-reset: dry-run rotate`,
+        `topic-shift-reset: would-rotate`,
         `source=${params.source}`,
         `reason=${params.reason}`,
         `session=${params.sessionKey}`,
@@ -1129,8 +1672,9 @@ async function rotateSessionEntry(params: {
   params.state.pendingSoftSignals = 0;
   params.state.pendingEntries = [];
   params.state.history = trimHistory([params.entry], params.cfg.historyWindow);
+  seedTopicCentroid(params.state, params.entry.embedding);
 
-  params.api.logger.warn(
+  params.api.logger.info(
     [
       `topic-shift-reset: rotated`,
       `source=${params.source}`,
@@ -1152,6 +1696,185 @@ export default function register(api: OpenClawPluginApi): void {
   const sessionState = new Map<string, SessionState>();
   const recentFastEvents = new Map<string, number>();
   const recentRotationBySession = new Map<string, number>();
+  const pendingSoftSuspectSteeringBySession = new Map<string, number>();
+  const recentClassifiedBySessionHash = new Map<
+    string,
+    { at: number; source: "fast" | "fallback" }
+  >();
+  const sessionWorkQueue = new Map<string, Promise<unknown>>();
+
+  const persistencePath = (() => {
+    try {
+      const stateDir = api.runtime.state.resolveStateDir();
+      return path.join(stateDir, "plugins", api.id, PERSISTENCE_FILE_NAME);
+    } catch (error) {
+      api.logger.warn(`topic-shift-reset: persistence disabled (state path): ${String(error)}`);
+      return null;
+    }
+  })();
+
+  let persistenceDirty = false;
+  let persistenceTimer: NodeJS.Timeout | null = null;
+  let persistenceFlushPromise: Promise<void> | null = null;
+  let persistenceLoadPromise: Promise<void> = Promise.resolve();
+
+  const clearPersistenceTimer = () => {
+    if (!persistenceTimer) {
+      return;
+    }
+    clearTimeout(persistenceTimer);
+    persistenceTimer = null;
+  };
+
+  const flushPersistentState = async (reason: string): Promise<void> => {
+    if (!persistencePath) {
+      return;
+    }
+    await persistenceLoadPromise;
+    if (!persistenceDirty) {
+      return;
+    }
+    if (persistenceFlushPromise) {
+      await persistenceFlushPromise;
+      return;
+    }
+    persistenceFlushPromise = (async () => {
+      const now = Date.now();
+      pruneStateMaps(sessionState);
+      pruneRecentMap(recentRotationBySession, ROTATION_DEDUPE_MS * 3, MAX_RECENT_FAST_EVENTS);
+
+      const payload: PersistedRuntimeState = {
+        version: PERSISTENCE_SCHEMA_VERSION,
+        savedAt: now,
+        sessionStateBySessionKey: {},
+        recentRotationBySession: {},
+      };
+
+      for (const [sessionKey, state] of sessionState) {
+        payload.sessionStateBySessionKey[sessionKey] = serializeSessionState(state);
+      }
+      for (const [rotationKey, ts] of recentRotationBySession) {
+        if (now - ts <= ROTATION_DEDUPE_MS * 3) {
+          payload.recentRotationBySession[rotationKey] = ts;
+        }
+      }
+
+      await withFileLock(persistencePath, LOCK_OPTIONS, async () => {
+        await writeJsonFileAtomically(persistencePath, payload);
+      });
+      persistenceDirty = false;
+      if (cfg.debug) {
+        api.logger.debug(
+          `topic-shift-reset: state-flushed reason=${reason} sessions=${sessionState.size} rotations=${recentRotationBySession.size}`,
+        );
+      }
+    })()
+      .catch((error) => {
+        api.logger.warn(`topic-shift-reset: state flush failed err=${String(error)}`);
+      })
+      .finally(() => {
+        persistenceFlushPromise = null;
+      });
+    await persistenceFlushPromise;
+  };
+
+  const schedulePersistentFlush = (urgent = false) => {
+    if (!persistencePath) {
+      return;
+    }
+    persistenceDirty = true;
+    if (urgent) {
+      void flushPersistentState("urgent");
+      return;
+    }
+    if (persistenceTimer) {
+      return;
+    }
+    persistenceTimer = setTimeout(() => {
+      persistenceTimer = null;
+      void flushPersistentState("scheduled");
+    }, PERSISTENCE_FLUSH_DEBOUNCE_MS);
+    persistenceTimer.unref?.();
+  };
+
+  const runSerializedBySession = async <T>(
+    sessionKey: string,
+    fn: () => Promise<T>,
+  ): Promise<T> => {
+    const previous = sessionWorkQueue.get(sessionKey) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(fn);
+    const tail = current.then(
+      () => undefined,
+      () => undefined,
+    );
+    sessionWorkQueue.set(sessionKey, tail);
+    try {
+      return await current;
+    } finally {
+      if (sessionWorkQueue.get(sessionKey) === tail) {
+        sessionWorkQueue.delete(sessionKey);
+      }
+    }
+  };
+
+  persistenceLoadPromise = (async () => {
+    if (!persistencePath) {
+      return;
+    }
+    try {
+      const loaded = await withFileLock(persistencePath, LOCK_OPTIONS, async () => {
+        return await readJsonFileWithFallback<PersistedRuntimeState | null>(persistencePath, null);
+      });
+      const value = loaded.value;
+      if (!value || typeof value !== "object") {
+        return;
+      }
+      if (value.version !== PERSISTENCE_SCHEMA_VERSION) {
+        api.logger.warn(
+          `topic-shift-reset: state version mismatch expected=${PERSISTENCE_SCHEMA_VERSION} got=${String(value.version)}; ignoring persisted state`,
+        );
+        return;
+      }
+
+      const restoredSessionStateByKey =
+        value.sessionStateBySessionKey && typeof value.sessionStateBySessionKey === "object"
+          ? value.sessionStateBySessionKey
+          : {};
+      for (const [sessionKey, rawState] of Object.entries(restoredSessionStateByKey)) {
+        const trimmedSessionKey = sessionKey.trim();
+        if (!trimmedSessionKey) {
+          continue;
+        }
+        const restored = deserializeSessionState(rawState, cfg);
+        if (!restored) {
+          continue;
+        }
+        sessionState.set(trimmedSessionKey, restored);
+      }
+      pruneStateMaps(sessionState);
+
+      const restoredRotationByKey =
+        value.recentRotationBySession && typeof value.recentRotationBySession === "object"
+          ? value.recentRotationBySession
+          : {};
+      for (const [key, ts] of Object.entries(restoredRotationByKey)) {
+        if (!key.trim()) {
+          continue;
+        }
+        if (typeof ts !== "number" || !Number.isFinite(ts) || ts <= 0) {
+          continue;
+        }
+        recentRotationBySession.set(key, Math.floor(ts));
+      }
+      pruneRecentMap(recentRotationBySession, ROTATION_DEDUPE_MS * 3, MAX_RECENT_FAST_EVENTS);
+
+      api.logger.info(
+        `topic-shift-reset: restored state sessions=${sessionState.size} rotations=${recentRotationBySession.size}`,
+      );
+    } catch (error) {
+      api.logger.warn(`topic-shift-reset: state restore failed err=${String(error)}`);
+    }
+  })();
 
   let embeddingBackend: EmbeddingBackend | null = null;
   let embeddingInitError: string | null = null;
@@ -1164,54 +1887,56 @@ export default function register(api: OpenClawPluginApi): void {
   if (embeddingInitError) {
     api.logger.warn(`topic-shift-reset: embedding backend init failed: ${embeddingInitError}`);
   } else if (!embeddingBackend) {
-    api.logger.warn("topic-shift-reset: embedding backend unavailable, using lexical-only mode");
+    api.logger.info("topic-shift-reset: embedding backend unavailable, using lexical-only mode");
   } else {
     api.logger.info(`topic-shift-reset: embedding backend ${embeddingBackend.name}`);
   }
 
-  const classifyAndMaybeRotate = async (params: {
+  const classifyAndMaybeRotateInner = async (params: {
     source: "fast" | "fallback";
     sessionKey: string;
     text: string;
     messageProvider?: string;
     agentId?: string;
-    dedupeKey?: string;
   }) => {
+    await persistenceLoadPromise;
     if (!cfg.enabled) {
       return;
     }
-    const sessionKey = params.sessionKey.trim();
+    const sessionKey = params.sessionKey;
     if (!sessionKey) {
       return;
     }
 
-    const provider = params.messageProvider?.trim().toLowerCase();
+    const provider = normalizeProviderId(params.messageProvider ?? "");
     if (provider && cfg.ignoredProviders.has(provider)) {
       return;
     }
+    if (isInternalNonUserProvider(provider)) {
+      if (cfg.debug) {
+        api.logger.debug(
+          `topic-shift-reset: skip-internal-provider source=${params.source} provider=${provider} session=${sessionKey}`,
+        );
+      }
+      return;
+    }
 
     const rawText = params.text.trim();
-    const text = cfg.stripEnvelope ? stripClassifierEnvelope(rawText) : rawText;
+    const text = cfg.stripEnvelope ? stripClassifierEnvelope(rawText, cfg.stripRules) : rawText;
     if (!text || text.startsWith("/")) {
       return;
     }
 
     const tokenList = tokenizeList(text, cfg.minTokenLength);
-    const signalEntropy = tokenEntropy(tokenList);
-    if (
-      text.length < cfg.minSignalChars ||
-      tokenList.length < cfg.minSignalTokenCount ||
-      signalEntropy < cfg.minSignalEntropy
-    ) {
+    if (text.length < cfg.minSignalChars || tokenList.length < cfg.minSignalTokenCount) {
       if (cfg.debug) {
-        api.logger.info(
+        api.logger.debug(
           [
             `topic-shift-reset: skip-low-signal`,
             `source=${params.source}`,
             `session=${sessionKey}`,
             `chars=${text.length}`,
             `tokens=${tokenList.length}`,
-            `entropy=${signalEntropy.toFixed(3)}`,
           ].join(" "),
         );
       }
@@ -1219,18 +1944,73 @@ export default function register(api: OpenClawPluginApi): void {
     }
 
     const tokens = new Set(tokenList);
-    if (tokens.size < cfg.minMeaningfulTokens) {
+
+    const now = Date.now();
+    const contentHash = hashString(normalizeTextForHash(text));
+    const classifyDedupeKey = `${sessionKey}:${contentHash}`;
+    const recentCrossSourceClassification = recentClassifiedBySessionHash.get(classifyDedupeKey);
+    if (
+      recentCrossSourceClassification &&
+      recentCrossSourceClassification.source !== params.source &&
+      now - recentCrossSourceClassification.at < CROSS_PATH_DEDUPE_MS
+    ) {
+      if (cfg.debug) {
+        api.logger.debug(
+          [
+            `topic-shift-reset: skip-cross-path-duplicate`,
+            `session=${sessionKey}`,
+            `source=${params.source}`,
+            `prevSource=${recentCrossSourceClassification.source}`,
+          ].join(" "),
+        );
+      }
       return;
     }
+    recentClassifiedBySessionHash.set(classifyDedupeKey, { at: now, source: params.source });
+    pruneRecentClassifiedMap(recentClassifiedBySessionHash, CROSS_PATH_DEDUPE_MS * 3, MAX_RECENT_FAST_EVENTS);
 
-    const contentHash = hashString(normalizeTextForHash(text));
     const lastRotationAt = recentRotationBySession.get(`${sessionKey}:${contentHash}`);
-    if (typeof lastRotationAt === "number" && Date.now() - lastRotationAt < ROTATION_DEDUPE_MS) {
+    if (typeof lastRotationAt === "number" && now - lastRotationAt < ROTATION_DEDUPE_MS) {
       return;
     }
+    const state =
+      sessionState.get(sessionKey) ??
+      ({
+        history: [],
+        pendingSoftSignals: 0,
+        pendingEntries: [],
+        lastResetAt: undefined,
+        topicCentroid: undefined,
+        topicCount: 0,
+        topicDim: undefined,
+        lastSeenAt: now,
+      } satisfies SessionState);
+    state.lastSeenAt = now;
+
+    const baselineTokens = unionTokens(state.history);
+    const lexical = computeLexicalFeatures({
+      cfg,
+      entry: { tokens, at: now },
+      tokenList,
+      baselineTokens,
+    });
+    const warmup =
+      state.history.length < cfg.minHistoryMessages || baselineTokens.size < cfg.minMeaningfulTokens;
+    const cooldownMs = cfg.cooldownMinutes * 60_000;
+    const cooldownActive =
+      cooldownMs > 0 && typeof state.lastResetAt === "number" && now - state.lastResetAt < cooldownMs;
 
     let embedding: number[] | undefined;
-    if (embeddingBackend) {
+    if (
+      shouldRequestEmbedding({
+        cfg,
+        backendAvailable: !!embeddingBackend,
+        lexical,
+        warmup,
+        cooldownActive,
+      }) &&
+      embeddingBackend
+    ) {
       try {
         const vector = await embeddingBackend.embed(text);
         if (Array.isArray(vector) && vector.length > 0) {
@@ -1241,23 +2021,23 @@ export default function register(api: OpenClawPluginApi): void {
       }
     }
 
-    const now = Date.now();
-    const state =
-      sessionState.get(sessionKey) ??
-      ({
-        history: [],
-        pendingSoftSignals: 0,
-        pendingEntries: [],
-        lastResetAt: undefined,
-        lastSeenAt: now,
-      } satisfies SessionState);
-    state.lastSeenAt = now;
-
     const entry: HistoryEntry = { tokens, embedding, at: now };
-    const decision = classifyMessage({ cfg, state, entry, now });
+    const similarity =
+      entry.embedding && state.topicCentroid
+        ? cosineSimilarity(entry.embedding, state.topicCentroid)
+        : undefined;
+    const decision = classifyMessage({
+      cfg,
+      state,
+      baselineTokenCount: baselineTokens.size,
+      lexical,
+      similarity,
+      usedEmbedding: typeof similarity === "number",
+      now,
+    });
 
     if (cfg.debug) {
-      api.logger.info(
+      api.logger.debug(
         [
           `topic-shift-reset: classify`,
           `source=${params.source}`,
@@ -1267,6 +2047,8 @@ export default function register(api: OpenClawPluginApi): void {
           `score=${decision.metrics.score.toFixed(3)}`,
           `novelty=${decision.metrics.novelty.toFixed(3)}`,
           `lex=${decision.metrics.lexicalDistance.toFixed(3)}`,
+          `uniq=${decision.metrics.uniqueTokenRatio.toFixed(3)}`,
+          `entropy=${decision.metrics.entropy.toFixed(3)}`,
           `sim=${typeof decision.metrics.similarity === "number" ? decision.metrics.similarity.toFixed(3) : "n/a"}`,
           `embed=${decision.metrics.usedEmbedding ? "1" : "0"}`,
           `pending=${state.pendingSoftSignals}`,
@@ -1275,29 +2057,46 @@ export default function register(api: OpenClawPluginApi): void {
     }
 
     if (decision.kind === "warmup") {
+      pendingSoftSuspectSteeringBySession.delete(sessionKey);
       state.pendingSoftSignals = 0;
       state.pendingEntries = [];
       state.history = trimHistory([...state.history, entry], cfg.historyWindow);
+      updateTopicCentroid(state, entry.embedding);
       sessionState.set(sessionKey, state);
       pruneStateMaps(sessionState);
+      schedulePersistentFlush(false);
       return;
     }
 
     if (decision.kind === "stable") {
+      pendingSoftSuspectSteeringBySession.delete(sessionKey);
       const merged = [...state.history, ...state.pendingEntries, entry];
+      for (const item of [...state.pendingEntries, entry]) {
+        updateTopicCentroid(state, item.embedding);
+      }
       state.pendingSoftSignals = 0;
       state.pendingEntries = [];
       state.history = trimHistory(merged, cfg.historyWindow);
       sessionState.set(sessionKey, state);
       pruneStateMaps(sessionState);
+      schedulePersistentFlush(false);
       return;
     }
 
     if (decision.kind === "suspect") {
+      if (cfg.softSuspect.action === "ask") {
+        pendingSoftSuspectSteeringBySession.set(sessionKey, now);
+        pruneRecentMap(
+          pendingSoftSuspectSteeringBySession,
+          Math.max(cfg.softSuspect.ttlMs * 2, 60_000),
+          MAX_RECENT_FAST_EVENTS,
+        );
+      }
       state.pendingSoftSignals += 1;
       state.pendingEntries = trimHistory([...state.pendingEntries, entry], cfg.softConsecutiveSignals);
       sessionState.set(sessionKey, state);
       pruneStateMaps(sessionState);
+      schedulePersistentFlush(false);
       return;
     }
 
@@ -1318,12 +2117,42 @@ export default function register(api: OpenClawPluginApi): void {
     });
 
     if (rotated) {
-      recentRotationBySession.set(`${sessionKey}:${contentHash}`, Date.now());
+      pendingSoftSuspectSteeringBySession.delete(sessionKey);
+      if (!cfg.dryRun) {
+        recentRotationBySession.set(`${sessionKey}:${contentHash}`, Date.now());
+      }
+      schedulePersistentFlush(true);
     }
 
     sessionState.set(sessionKey, state);
     pruneStateMaps(sessionState);
-    pruneRecentMap(recentRotationBySession, ROTATION_DEDUPE_MS * 3, MAX_RECENT_FAST_EVENTS);
+    const prunedRotations = pruneRecentMap(
+      recentRotationBySession,
+      ROTATION_DEDUPE_MS * 3,
+      MAX_RECENT_FAST_EVENTS,
+    );
+    if (prunedRotations) {
+      schedulePersistentFlush(false);
+    }
+  };
+
+  const classifyAndMaybeRotate = async (params: {
+    source: "fast" | "fallback";
+    sessionKey: string;
+    text: string;
+    messageProvider?: string;
+    agentId?: string;
+  }) => {
+    const sessionKey = params.sessionKey.trim();
+    if (!sessionKey) {
+      return;
+    }
+    await runSerializedBySession(sessionKey, async () => {
+      await classifyAndMaybeRotateInner({
+        ...params,
+        sessionKey,
+      });
+    });
   };
 
   api.on("message_received", async (event, ctx) => {
@@ -1355,7 +2184,8 @@ export default function register(api: OpenClawPluginApi): void {
     recentFastEvents.set(fastEventKey, Date.now());
     pruneRecentMap(recentFastEvents, FAST_EVENT_TTL_MS, MAX_RECENT_FAST_EVENTS);
 
-    let resolved: ResolvedFastSession | null = null;
+    let resolvedSessionKey = "";
+    let resolvedAgentId: string | undefined;
     try {
       const route = api.runtime.channel.routing.resolveAgentRoute({
         cfg: api.config,
@@ -1363,13 +2193,11 @@ export default function register(api: OpenClawPluginApi): void {
         accountId: ctx.accountId,
         peer,
       });
-      resolved = {
-        sessionKey: route.sessionKey,
-        routeKind: peer.kind,
-      };
+      resolvedSessionKey = route.sessionKey;
+      resolvedAgentId = route.agentId;
     } catch (error) {
       if (cfg.debug) {
-        api.logger.info(
+        api.logger.debug(
           `topic-shift-reset: fast-route-skip channel=${channelId} peer=${maybeJson(peer)} err=${String(error)}`,
         );
       }
@@ -1378,10 +2206,10 @@ export default function register(api: OpenClawPluginApi): void {
 
     await classifyAndMaybeRotate({
       source: "fast",
-      sessionKey: resolved.sessionKey,
+      sessionKey: resolvedSessionKey,
       text,
       messageProvider: channelId,
-      dedupeKey: fastEventKey,
+      agentId: resolvedAgentId,
     });
   });
 
@@ -1402,4 +2230,29 @@ export default function register(api: OpenClawPluginApi): void {
       agentId: ctx.agentId,
     });
   });
+
+  api.on("before_prompt_build", async (_event, ctx) => {
+    if (!cfg.enabled || cfg.softSuspect.action !== "ask") {
+      return;
+    }
+    const sessionKey = ctx.sessionKey?.trim();
+    if (!sessionKey) {
+      return;
+    }
+    const seenAt = pendingSoftSuspectSteeringBySession.get(sessionKey);
+    if (typeof seenAt !== "number") {
+      return;
+    }
+    if (Date.now() - seenAt > cfg.softSuspect.ttlMs) {
+      pendingSoftSuspectSteeringBySession.delete(sessionKey);
+      return;
+    }
+    pendingSoftSuspectSteeringBySession.delete(sessionKey);
+    return { prependContext: cfg.softSuspect.prompt };
+  });
+
+  api.on("gateway_stop", async () => {
+    clearPersistenceTimer();
+    await flushPersistentState("gateway-stop");
+  });
 }