openclaw-topic-shift-reset 0.2.0 → 0.3.0

package/README.md

@@ -11,6 +11,7 @@ This plugin tries to prevent that by detecting topic shifts and rotating to a ne
 - fewer prompt tokens per turn after a shift
 - less stale context bleeding into new questions
 - lower chance of overflow/compaction churn on long chats
+- classifier state persisted across gateway restarts (no cold start after reboot)
 
 Does it deliver? Yes for clear topic changes, especially with embeddings enabled and sane defaults. It is not a core patch, so behavior is best-effort: subtle/short messages can be ambiguous, and hook timing means the triggering turn cannot be guaranteed to become the very first persisted message of the new session in every path.
 
@@ -42,6 +43,10 @@ Add this plugin entry in `~/.openclaw/openclaw.json` (or merge into your existin
             "lastN": 6,
             "maxChars": 220
           },
+          "softSuspect": {
+            "action": "ask",
+            "ttlSeconds": 120
+          },
           "dryRun": false,
           "debug": false
         }
@@ -101,6 +106,24 @@ Provider options:
 - `ollama`
 - `none` (lexical only)
 
+## Soft suspect clarification
+
+When the classifier sees a soft topic-shift signal (`suspect`) but not enough confidence to rotate yet, the plugin can inject one-turn steer context so the model asks a brief clarification question before continuing.
+
+```json
+{
+  "softSuspect": {
+    "action": "ask",
+    "prompt": "Potential topic shift detected. Ask one short clarification question to confirm the user's new goal before proceeding.",
+    "ttlSeconds": 120
+  }
+}
+```
+
+- `action`: `ask` (default) or `none`.
+- `prompt`: optional custom steer text.
+- `ttlSeconds`: max age before a pending steer expires.
+
 ## Logs
 
 ```bash

package/docs/configuration.md

@@ -17,6 +17,10 @@ This plugin now accepts one canonical key per concept:
     "lastN": 6,
     "maxChars": 220
   },
+  "softSuspect": {
+    "action": "ask",
+    "ttlSeconds": 120
+  },
   "dryRun": false,
   "debug": false
 }
@@ -34,6 +38,9 @@ This plugin now accepts one canonical key per concept:
 - `handoff.mode`: `none | summary | verbatim_last_n`.
 - `handoff.lastN`: number of transcript messages to include in handoff.
 - `handoff.maxChars`: per-message truncation cap in handoff text.
+- `softSuspect.action`: `ask | none`.
+- `softSuspect.prompt`: optional steer text injected on soft-suspect.
+- `softSuspect.ttlSeconds`: expiry for pending soft-suspect steer.
 - `dryRun`: logs would-rotate events without session resets.
 - `debug`: emits per-message classifier diagnostics.
 
@@ -61,6 +68,8 @@ This plugin now accepts one canonical key per concept:
 - `handoff.mode`: `summary`
 - `handoff.lastN`: `6`
 - `handoff.maxChars`: `220`
+- `softSuspect.action`: `ask`
+- `softSuspect.ttlSeconds`: `120`
 - `advanced.minSignalChars`: `20`
 - `advanced.minSignalTokenCount`: `3`
 - `advanced.minSignalEntropy`: `1.2`
@@ -131,6 +140,14 @@ Legacy alias keys are not supported in this release. Config validation fails if
 - `advanced.embedding`, `advanced.embeddings`, `advanced.handoff*`
 - previous top-level tuning keys
 
+## Runtime persistence
+
+Classifier runtime state is persisted automatically under the OpenClaw state directory (`plugins/<plugin-id>/runtime-state.v1.json`).
+
+- Persisted: per-session topic history, pending soft-signal windows, topic centroid, rotation dedupe map.
+- Not persisted: transient fast-event dedupe cache.
+- No extra config is required.
+
 ## Log interpretation
 
 Classifier logs look like:
@@ -150,3 +167,4 @@ Other lines:
 - `skip-low-signal`: message skipped by hard signal floor (`minSignalChars`/`minSignalTokenCount`).
 - `would-rotate`: `dryRun=true` synthetic rotate event (no reset mutation).
 - `rotated`: actual session rotation happened.
+- `classify` / `skip-low-signal` / `skip-cross-path-duplicate`: debug-level diagnostics (`debug=true`).

package/openclaw.plugin.json

@@ -64,6 +64,27 @@
           }
         }
       },
+      "softSuspect": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["none", "ask"],
+            "default": "ask"
+          },
+          "prompt": {
+            "type": "string",
+            "default": "Potential topic shift detected. Ask one short clarification question to confirm the user's new goal before proceeding."
+          },
+          "ttlSeconds": {
+            "type": "integer",
+            "minimum": 10,
+            "maximum": 1800,
+            "default": 120
+          }
+        }
+      },
       "dryRun": {
         "type": "boolean",
         "default": false
@@ -245,6 +266,10 @@
       "label": "Context Handoff",
       "help": "mode=summary is the safest default; verbatim_last_n copies recent transcript lines."
     },
+    "softSuspect": {
+      "label": "Soft-Suspect Clarification",
+      "help": "When a soft topic-shift signal appears, optionally steer the model to ask one clarification question before proceeding."
+    },
     "dryRun": {
       "label": "Dry Run",
       "help": "Only log decisions; do not rotate sessions."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-topic-shift-reset",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenClaw plugin that detects topic shifts and starts a fresh session automatically.",
   "type": "module",
   "main": "./src/index.ts",
@@ -17,6 +17,8 @@
   "scripts": {
     "build": "echo 'No build required. OpenClaw loads src/index.ts via jiti.'",
     "dev": "echo 'No watch build required.'",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepack": "npm run build"
   },
   "keywords": [
@@ -32,6 +34,10 @@
   "peerDependencies": {
     "openclaw": ">=2026.2.18"
   },
+  "devDependencies": {
+    "@types/node": "^22.13.8",
+    "vitest": "^3.0.7"
+  },
   "openclaw": {
     "extensions": [
       "./src/index.ts"

package/src/index.ts

@@ -11,6 +11,7 @@ import {
 type PresetName = "conservative" | "balanced" | "aggressive";
 type EmbeddingProvider = "auto" | "none" | "openai" | "ollama";
 type HandoffMode = "none" | "summary" | "verbatim_last_n";
+type SoftSuspectAction = "none" | "ask";
 
 type EmbeddingConfig = {
   provider?: EmbeddingProvider;
@@ -26,6 +27,12 @@ type HandoffConfig = {
   maxChars?: number;
 };
 
+type SoftSuspectConfig = {
+  action?: SoftSuspectAction;
+  prompt?: string;
+  ttlSeconds?: number;
+};
+
 type StripRulesConfig = {
   dropLinePrefixPatterns?: string[];
   dropExactLines?: string[];
@@ -62,6 +69,7 @@ type TopicShiftResetConfig = {
   preset?: PresetName;
   embedding?: EmbeddingConfig;
   handoff?: HandoffConfig;
+  softSuspect?: SoftSuspectConfig;
   dryRun?: boolean;
   debug?: boolean;
   advanced?: TopicShiftResetAdvancedConfig;
@@ -100,6 +108,11 @@ type ResolvedConfig = {
     lastN: number;
     maxChars: number;
   };
+  softSuspect: {
+    action: SoftSuspectAction;
+    prompt: string;
+    ttlMs: number;
+  };
   embedding: {
     provider: EmbeddingProvider;
     model?: string;
@@ -141,6 +154,30 @@ type SessionState = {
   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;
@@ -245,6 +282,10 @@ const DEFAULTS = {
   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,
@@ -274,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;
@@ -282,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)) {
@@ -348,6 +396,17 @@ function normalizeHandoffMode(value: unknown): HandoffMode {
   return DEFAULTS.handoffMode;
 }
 
+function normalizeSoftSuspectAction(value: unknown): SoftSuspectAction {
+  if (typeof value !== "string") {
+    return DEFAULTS.softSuspectAction;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "none" || normalized === "ask") {
+    return normalized;
+  }
+  return DEFAULTS.softSuspectAction;
+}
+
 function compileRegexList(values: unknown, fallback: readonly string[]): RegExp[] {
   const source = Array.isArray(values) ? values : fallback;
   const out: RegExp[] = [];
@@ -376,6 +435,156 @@ function normalizeStringList(values: unknown, fallback: readonly string[]): stri
     .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 [];
+  }
+  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) {
@@ -427,6 +636,19 @@ function normalizeProviderId(raw: string): string {
   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 {
   const obj = raw && typeof raw === "object" ? (raw as TopicShiftResetConfig) : {};
   const advanced =
@@ -437,6 +659,10 @@ function resolveConfig(raw: unknown): ResolvedConfig {
     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)
@@ -561,6 +787,14 @@ function resolveConfig(raw: unknown): ResolvedConfig {
       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(embedding.provider),
       model: (() => {
@@ -1274,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;
@@ -1290,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;
@@ -1310,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: {
@@ -1426,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;
@@ -1443,17 +1892,18 @@ export default function register(api: OpenClawPluginApi): void {
     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;
   }) => {
+    await persistenceLoadPromise;
     if (!cfg.enabled) {
       return;
     }
-    const sessionKey = params.sessionKey.trim();
+    const sessionKey = params.sessionKey;
     if (!sessionKey) {
       return;
     }
@@ -1462,6 +1912,14 @@ export default function register(api: OpenClawPluginApi): void {
     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, cfg.stripRules) : rawText;
@@ -1472,7 +1930,7 @@ export default function register(api: OpenClawPluginApi): void {
     const tokenList = tokenizeList(text, cfg.minTokenLength);
     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}`,
@@ -1487,13 +1945,34 @@ export default function register(api: OpenClawPluginApi): void {
 
     const tokens = new Set(tokenList);
 
+    const now = Date.now();
     const contentHash = hashString(normalizeTextForHash(text));
-    const lastRotationAt = recentRotationBySession.get(`${sessionKey}:${contentHash}`);
-    if (typeof lastRotationAt === "number" && Date.now() - lastRotationAt < ROTATION_DEDUPE_MS) {
+    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 now = Date.now();
+    const lastRotationAt = recentRotationBySession.get(`${sessionKey}:${contentHash}`);
+    if (typeof lastRotationAt === "number" && now - lastRotationAt < ROTATION_DEDUPE_MS) {
+      return;
+    }
     const state =
       sessionState.get(sessionKey) ??
       ({
@@ -1558,7 +2037,7 @@ export default function register(api: OpenClawPluginApi): void {
     });
 
     if (cfg.debug) {
-      api.logger.info(
+      api.logger.debug(
         [
           `topic-shift-reset: classify`,
           `source=${params.source}`,
@@ -1578,16 +2057,19 @@ 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);
@@ -1597,14 +2079,24 @@ export default function register(api: OpenClawPluginApi): void {
       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;
     }
 
@@ -1625,14 +2117,42 @@ export default function register(api: OpenClawPluginApi): void {
     });
 
     if (rotated) {
+      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) => {
@@ -1665,6 +2185,7 @@ export default function register(api: OpenClawPluginApi): void {
     pruneRecentMap(recentFastEvents, FAST_EVENT_TTL_MS, MAX_RECENT_FAST_EVENTS);
 
     let resolvedSessionKey = "";
+    let resolvedAgentId: string | undefined;
     try {
       const route = api.runtime.channel.routing.resolveAgentRoute({
         cfg: api.config,
@@ -1673,9 +2194,10 @@ export default function register(api: OpenClawPluginApi): void {
         peer,
       });
       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)}`,
         );
       }
@@ -1687,6 +2209,7 @@ export default function register(api: OpenClawPluginApi): void {
       sessionKey: resolvedSessionKey,
       text,
       messageProvider: channelId,
+      agentId: resolvedAgentId,
     });
   });
 
@@ -1707,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");
+  });
 }