ocuclaw 1.3.0 → 1.3.2

package/dist/runtime/relay-core.js

@@ -1,8 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import * as childProcess from "node:child_process";
 import { EventEmitter } from "node:events";
-import { createPluginUpdateService } from "./plugin-update-service.js";
+import { createPluginVersionService } from "./plugin-version-service.js";
 import * as conversationStateModule from "../domain/conversation-state.js";
 import { createDebugStore } from "../domain/debug-store.js";
 import { summarizeGlassesUiContent } from "../domain/glasses-ui-content-summary.js";
@@ -10,6 +9,8 @@ import { composeReadabilitySystemPrompt } from "../domain/readability-system-pro
 import { composeNeuralEmojiReactorSystemPrompt } from "../domain/neural-emoji-reactor-system-prompt.js";
 import { composeNeuralPaceModulatorSystemPrompt } from "../domain/neural-pace-modulator-system-prompt.js";
 import { composeGlassesUiNudgeSystemPrompt } from "../domain/glasses-ui-system-prompt.js";
+import { composeGlassesDisplaySystemPrompt } from "../domain/glasses-display-system-prompt.js";
+import { createStablePromptSnapshotStore } from "./stable-prompt-snapshot.js";
 import { createActivityStatusAdapter } from "../domain/activity-status-adapter.js";
 import { createEvenAiEndpoint } from "../even-ai/even-ai-endpoint.js";
 import { createEvenAiRouter } from "../even-ai/even-ai-router.js";
@@ -22,7 +23,10 @@ import { createOcuClawSettingsStore } from "./ocuclaw-settings-store.js";
 import { createRelayHealthMonitor } from "./relay-health-monitor.js";
 import { createRelayOperationRegistry } from "./relay-operation-registry.js";
 import { createRelayWorkerSupervisor } from "./relay-worker-supervisor.js";
-import { createSessionService } from "./session-service.js";
+import {
+  createSessionService,
+  NEW_SESSION_GREETING_PROMPT,
+} from "./session-service.js";
 import { createUpstreamRuntime } from "./upstream-runtime.js";
 
 const SONIOX_TEMP_KEY_URL = "https://api.soniox.com/v1/auth/temporary-api-key";
@@ -357,7 +361,9 @@ function createRelay(opts) {
   /** Relay-local deterministic simulate-stream run sequence counter. */
   let simulateStreamRunSeq = 0;
   /** Active timers for relay-local deterministic simulate-stream runs. */
-  const simulateStreamTimers = new Set();
+  // timer -> sessionKey, so new-chat//reset/new-session can cancel ONLY the
+  // affected session's pending injections (re-land of a8a29032, session-scoped).
+  const simulateStreamTimers = new Map();
 
   // --- Structured debug state ---
 
@@ -373,6 +379,31 @@ function createRelay(opts) {
   // log lines share an identical ts (downstream reconcilers dedupe on it).
   const debugNow =
     typeof opts.debugNow === "function" ? opts.debugNow : () => Date.now();
+
+  // --- Durable debug-store arm (survives relay/gateway restarts) ---
+  // The capture arm (enabled categories + TTLs) lives only in the in-memory
+  // debug-store, which a restart rebuilds empty. We persist it to debug-arm.json
+  // (via persistDebugArm) and rehydrate it here at construction — read-once,
+  // mirroring liveUiTraceFlagPath below — so a restart no longer silently drops
+  // capture. This path covers process RESTART only: a pure WebUI *reload* does NOT
+  // restart the relay and already preserves + re-advertises the arm via
+  // relay-worker-transport.ts:327-328 (cache.debugConfig re-broadcast to app
+  // clients) — do not add reconnect machinery here.
+  const debugArmStatePath =
+    typeof opts.stateDir === "string" && opts.stateDir
+      ? path.join(opts.stateDir, "debug-arm.json")
+      : null;
+  let initialDebugArm = [];
+  if (debugArmStatePath) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(debugArmStatePath, "utf8"));
+      if (parsed && Array.isArray(parsed.enabled)) {
+        initialDebugArm = parsed.enabled;
+      }
+    } catch {
+      initialDebugArm = [];
+    }
+  }
   const debugStore = createDebugStore({
     categories: debugCategories,
     capacity: opts.debugCapacity,
@@ -383,6 +414,7 @@ function createRelay(opts) {
     dumpMaxLimit: opts.debugDumpMaxLimit,
     now: debugNow,
     noisyPolicies: opts.debugNoisyPolicies,
+    initialEnabled: initialDebugArm,
   });
 
   // --- Live-interface trace-log flag (durable across restarts) ---
@@ -522,7 +554,7 @@ function createRelay(opts) {
     );
   }
 
-  function scheduleSimulateStreamTimer(delayMs, callback) {
+  function scheduleSimulateStreamTimer(delayMs, callback, sessionKey) {
     const timer = setTimeout(() => {
       simulateStreamTimers.delete(timer);
       try {
@@ -531,12 +563,29 @@ function createRelay(opts) {
         logger.error(`[relay] simulate-stream timer failed: ${err.message}`);
       }
     }, delayMs);
-    simulateStreamTimers.add(timer);
+    simulateStreamTimers.set(timer, typeof sessionKey === "string" ? sessionKey : null);
     return timer;
   }
 
+  function clearSimulateStreamTimersForSession(sessionKey) {
+    let cleared = 0;
+    for (const [timer, timerSessionKey] of simulateStreamTimers) {
+      if (timerSessionKey === sessionKey) {
+        clearTimeout(timer);
+        simulateStreamTimers.delete(timer);
+        cleared += 1;
+      }
+    }
+    if (cleared > 0) {
+      logger.info(
+        `[relay] cancelled ${cleared} pending simulate-stream timer(s) for session ${sessionKey}`,
+      );
+    }
+    return cleared;
+  }
+
   function clearSimulateStreamTimers() {
-    for (const timer of simulateStreamTimers) {
+    for (const timer of simulateStreamTimers.keys()) {
       clearTimeout(timer);
     }
     simulateStreamTimers.clear();
@@ -895,37 +944,67 @@ function createRelay(opts) {
       systemPrompt: opts.ocuClawSystemPrompt,
     },
   });
-
-  function currentOcuClawSendOptions(perTurnSignals) {
-    const signals = perTurnSignals || {};
+  const stablePromptSnapshots = createStablePromptSnapshotStore({
+    stateDir: opts.stateDir,
+    emitDebug,
+  });
+  // Hourly TTL sweep for stale stable-prompt snapshots; started in start(),
+  // cleared in stop(). Declared here so both can see it.
+  let stablePromptSweepTimer = null;
+
+  // Channel 1: the per-session-immutable extraSystemPrompt. Computed once from
+  // the feature set AT SESSION START and then served byte-identical for the
+  // session's lifetime (see stable-prompt-snapshot). Mid-session toggles are
+  // bridged by the Channel-2 hook composer, NOT here. The glasses-UI pointer is
+  // always present (its disconnected gate moved to Channel 2); the emoji/pace
+  // blocks are included only when active at session start.
+  function computeStableChannelOne(startSignals) {
     const baseReadability = composeReadabilitySystemPrompt(
       ocuClawSettingsStore.getSnapshot().systemPrompt,
     );
-    const validState = (raw) =>
-      raw === "active" || raw === "recently-disabled" || raw === "inactive"
-        ? raw
-        : "inactive";
-    const reactorState = validState(signals.neuralEmojiReactorState);
-    const paceState = validState(signals.neuralPaceModulatorState);
-    const reactor = composeNeuralEmojiReactorSystemPrompt({ state: reactorState });
-    const pace = composeNeuralPaceModulatorSystemPrompt({ state: paceState });
-    // Only include the glasses-UI nudge when a downstream app client is
-    // connected. Keeps the prompt clean when the agent has nowhere to render
-    // the tool's output, and keeps existing prompt-assembly tests stable
-    // (they exercise the prompt without spinning up an app client).
-    const hasAppClient =
-      server &&
-      typeof server.getConnectedAppCount === "function" &&
-      server.getConnectedAppCount() > 0;
-    const glassesUiNudge = hasAppClient ? composeGlassesUiNudgeSystemPrompt() : "";
+    const display = composeGlassesDisplaySystemPrompt({
+      emoji: startSignals.emoji,
+      pace: startSignals.pace,
+    });
+    const glassesPointer = composeGlassesUiNudgeSystemPrompt();
     const parts = [];
     if (baseReadability) parts.push(baseReadability);
-    if (reactor) parts.push(reactor);
-    if (pace) parts.push(pace);
-    if (glassesUiNudge) parts.push(glassesUiNudge);
-    return {
-      extraSystemPrompt: parts.join("\n\n"),
-    };
+    if (display) parts.push(display);
+    if (glassesPointer) parts.push(glassesPointer);
+    return parts.join("\n\n");
+  }
+
+  function stableSendOptions(resolvedSessionKey, sessionId, perTurnSignals) {
+    const signals = perTurnSignals || {};
+    // "enabled at start" = the client's reported state on the FIRST send of the
+    // session. The 3-state client signal maps to a boolean: only "active" counts.
+    const startEmoji = signals.neuralEmojiReactorState === "active";
+    const startPace = signals.neuralPaceModulatorState === "active";
+    const extraSystemPrompt = stablePromptSnapshots.getOrCreate(
+      resolvedSessionKey,
+      sessionId,
+      () => computeStableChannelOne({ emoji: startEmoji, pace: startPace }),
+    );
+    // Churn guard: if recomputing TODAY would differ from the served snapshot,
+    // something is mutating Channel 1 mid-session (e.g. a toggle flipped the
+    // start-state signals) — the case that used to reset the CLI session.
+    // Surface it loudly; the served prompt stays the frozen snapshot.
+    if (
+      stablePromptSnapshots.wouldChurn(
+        resolvedSessionKey,
+        sessionId,
+        computeStableChannelOne({ emoji: startEmoji, pace: startPace }),
+      )
+    ) {
+      emitDebug(
+        "relay.session",
+        "stable_prompt_churn_detected",
+        "warn",
+        { sessionKey: resolvedSessionKey },
+        () => ({ sessionId: sessionId || null }),
+      );
+    }
+    return { extraSystemPrompt };
   }
 
   function buildOcuClawSendDiagnostic(params = {}) {
@@ -1437,6 +1516,10 @@ function createRelay(opts) {
         resolvedSessionKey,
         clientDisplaySignals.neuralSessionNamesEnabled !== false,
       );
+      sessionService.recordDisplayToggleStates(resolvedSessionKey, {
+        emoji: clientDisplaySignals.neuralEmojiReactorState === "active",
+        pace: clientDisplaySignals.neuralPaceModulatorState === "active",
+      });
     }
     const hasAttachment = !!attachment;
     const sendStartedAt = Date.now();
@@ -1466,7 +1549,16 @@ function createRelay(opts) {
         resolvedSessionKey,
         attachment,
         {
-          ...currentOcuClawSendOptions(clientDisplaySignals),
+          ...stableSendOptions(
+            resolvedSessionKey,
+            // No synchronous OpenClaw sessionId is available at send time
+            // (resolveSessionCanonicalKey is async). Use the sessionKey as the
+            // snapshot's id; the sessionId-mismatch guard is therefore a no-op,
+            // and new-session safety rests on logical-session-end eviction
+            // (onNewSession / onNewChat / onDeleteSessions evict the snapshot).
+            resolvedSessionKey,
+            clientDisplaySignals,
+          ),
           diagnostic: buildOcuClawSendDiagnostic({
             ...params,
             sessionKey: resolvedSessionKey,
@@ -1621,6 +1713,49 @@ function createRelay(opts) {
     return { ok: true, enabled, persisted, persistedPath: liveUiTraceFlagPath };
   }
 
+  // Persist the current debug-store arm to debug-arm.json. Mirrors the
+  // applyTraceLogSet writeFileSync above (plain, non-atomic): a partial/corrupt
+  // write degrades to an empty arm on next boot — acceptable, the nothing-armed
+  // warning catches it. getSnapshot().enabled is already pruned of expired
+  // categories, so the persisted JSON never holds an expired entry. Never throws
+  // into the caller.
+  function persistDebugArm() {
+    if (!debugArmStatePath) return false;
+    try {
+      const enabled = debugStore.getSnapshot().enabled;
+      fs.writeFileSync(debugArmStatePath, JSON.stringify({ enabled }) + "\n");
+      return true;
+    } catch (err) {
+      logger.warn(`[relay] debug arm persist failed: ${err && err.message ? err.message : err}`);
+      return false;
+    }
+  }
+
+  function applyDebugSet(clientId, request) {
+    const result = debugStore.setCategories(request);
+    if (!result.ok) {
+      throw new Error(result.error || "debug-set failed");
+    }
+    // Persist after every successful set — enable AND disable-to-empty — so the
+    // on-disk arm always tracks live state and a deliberately-cleared arm is not
+    // resurrected on the next restart.
+    persistDebugArm();
+    emitDebug(
+      "relay.protocol",
+      "debug_set",
+      "info",
+      { sessionKey: sessionService.ensureSessionKey() },
+      () => ({
+        clientId,
+        enable: result.applied.enable,
+        disable: result.applied.disable,
+        ttlMs: result.ttlMs,
+        enabledCount: result.enabled.length,
+      }),
+    );
+    return result;
+  }
+
   const handler = createDownstreamHandler({
     logger,
     externalDebugToolsEnabled,
@@ -1697,6 +1832,14 @@ function createRelay(opts) {
       return upstreamRuntime.compactActiveSession(sessionKey);
     },
     onDeleteSessions(sessionKeys, kind, switchBeforeDelete) {
+      if (Array.isArray(sessionKeys)) {
+        for (const key of sessionKeys) {
+          if (typeof key === "string" && key.trim()) {
+            stablePromptSnapshots.evict(key);
+            sessionService.clearDisplayToggleStates(key);
+          }
+        }
+      }
       const action = switchBeforeDelete
         ? sessionService.switchAndDeleteSessions(kind, sessionKeys)
         : sessionService.deleteSessions(kind, sessionKeys);
@@ -1833,7 +1976,7 @@ function createRelay(opts) {
               totalChars: text.length,
             }),
           );
-        });
+        }, sessionKey);
       }
 
       const completeDelayMs = startDelayMs + (chunkCount * chunkIntervalMs) + thinkingTailMs;
@@ -1864,7 +2007,7 @@ function createRelay(opts) {
             completeDelayMs,
           }),
         );
-      });
+      }, sessionKey);
 
       return Promise.resolve({
         status: "accepted",
@@ -1891,13 +2034,30 @@ function createRelay(opts) {
       }
       sessionService.invalidateSessionsCache();
       resetActivityStatusAdapter();
+      // Cancel THIS session's pending simulate-stream timers BEFORE clearing —
+      // a deferred addMessage firing after the clear repopulates the fresh chat
+      // (the 2026-05-15 canary-pollution mechanism).
+      clearSimulateStreamTimersForSession(sessionService.ensureSessionKey());
       conversationState.clear();
+      // Logical session end: this key is REUSED for a fresh conversation, so the
+      // Channel-1 snapshot must be dropped or the next send serves a stale prompt,
+      // and ALL other per-session state keyed to it (title + upstream name,
+      // toggles, distiller budget, first-user marker) must be cleared too.
+      const newChatSessionKey = sessionService.ensureSessionKey();
+      stablePromptSnapshots.evict(newChatSessionKey);
+      sessionService.clearLogicalSessionState(newChatSessionKey);
       conversationState.setAgentName(
         (upstreamRuntime ? upstreamRuntime.getAgentName() : null) || "Agent",
       );
       const pages = conversationState.getPages();
       cachePages(pages);
       if (upstreamRuntime && upstreamRuntime.isConnected()) {
+        // NOTE: onNewChat targets the hard-coded "main" key (legacy) without
+        // changing currentSessionKey, so it must NOT elicit a welcome turn here:
+        // the turn's events would carry "main" and be dropped by isCurrentSession()
+        // whenever the active session is an ocuclaw:* key. The welcome restore for
+        // the real glasses paths lives in newSession() (New) and onSlashCommand
+        // "/reset" (Reset). Unifying onNewChat onto newSession() is Phase-2 work.
         gatewayBridge.sendMessage("/new", "main").catch((err) => {
           logger.error(`[relay] Failed to send /new: ${err.message}`);
         });
@@ -1923,7 +2083,20 @@ function createRelay(opts) {
     },
 
     async onNewSession() {
+      // Cancel pending simulate-stream timers scheduled under the outgoing key
+      // BEFORE the new key is minted — a deferred addMessage firing after the
+      // switch would repopulate the fresh session's shared conversation view.
+      clearSimulateStreamTimersForSession(sessionService.ensureSessionKey());
       const result = await sessionService.newSession();
+      // newSession() mints a FRESH key; defensively clear only the NEW key (it
+      // has no snapshot yet). Do NOT touch the previous key: that session stays
+      // resumable via onSwitchSession, and dropping its frozen snapshot would
+      // recompute — and churn — Channel 1 if the user switches back to it. The
+      // previous session's snapshot is released by delete or the TTL sweep.
+      if (result && typeof result.sessionKey === "string" && result.sessionKey.trim()) {
+        stablePromptSnapshots.evict(result.sessionKey);
+        sessionService.clearDisplayToggleStates(result.sessionKey);
+      }
       clearCurrentSessionModelConfigSnapshot("new_session");
       if (upstreamRuntime && typeof upstreamRuntime.clearTyping === "function") {
         upstreamRuntime.clearTyping("new_session");
@@ -2033,6 +2206,7 @@ function createRelay(opts) {
       if (command === "/reset") {
         sessionService.invalidateSessionsCache();
         resetActivityStatusAdapter();
+        clearSimulateStreamTimersForSession(sessionService.ensureSessionKey());
         conversationState.clear();
         if (upstreamRuntime && typeof upstreamRuntime.clearTyping === "function") {
           upstreamRuntime.clearTyping("slash_reset");
@@ -2042,8 +2216,31 @@ function createRelay(opts) {
         );
         broadcastPages();
       }
+      // A user-typed /new or /reset is a logical session reset on the CURRENT
+      // key (distinct from an automatic CLI session reset, which keeps the same
+      // logical session and must survive). Drop the frozen Channel-1 snapshot so
+      // the next real message recomputes it for the fresh conversation; otherwise
+      // the old conversation's prompt + display start-state bleed into the new one.
+      if (command === "/new" || command === "/reset") {
+        const resetKey = sessionService.ensureSessionKey();
+        stablePromptSnapshots.evict(resetKey);
+        // Clear ALL per-session state keyed to the reused key (title + upstream
+        // name, toggles, distiller budget, first-user marker) so nothing from the
+        // old conversation bleeds into the fresh one.
+        sessionService.clearLogicalSessionState(resetKey);
+      }
       if (upstreamRuntime && upstreamRuntime.isConnected()) {
-        return gatewayBridge.sendMessage(command, sessionService.ensureSessionKey());
+        // Bare /reset no longer elicits an agent turn on OpenClaw 2026.6.x
+        // (fast-reset). Append the greeting prompt so Reset gets the same
+        // welcome as New. Other slash commands forward verbatim.
+        const outboundCommand =
+          command === "/reset"
+            ? `/reset ${NEW_SESSION_GREETING_PROMPT}`
+            : command;
+        return gatewayBridge.sendMessage(
+          outboundCommand,
+          sessionService.ensureSessionKey(),
+        );
       }
       return Promise.resolve();
     },
@@ -2102,26 +2299,7 @@ function createRelay(opts) {
     },
 
     onDebugSet(clientId, request) {
-      const result = debugStore.setCategories(request);
-      if (!result.ok) {
-        throw new Error(result.error || "debug-set failed");
-      }
-
-      emitDebug(
-        "relay.protocol",
-        "debug_set",
-        "info",
-        { sessionKey: sessionService.ensureSessionKey() },
-        () => ({
-          clientId,
-          enable: result.applied.enable,
-          disable: result.applied.disable,
-          ttlMs: result.ttlMs,
-          enabledCount: result.enabled.length,
-        }),
-      );
-
-      return result;
+      return applyDebugSet(clientId, request);
     },
 
     onTraceLogSet(clientId, request) {
@@ -2496,18 +2674,12 @@ function createRelay(opts) {
 
   // --- Worker supervisor ---
 
-  const pluginUpdateService = createPluginUpdateService({
-    spawn: childProcess.spawn,
-    logger,
-    nowMs: () => Date.now(),
-    setTimeout: (fn, ms) => setTimeout(fn, ms),
-    clearTimeout: (handle) => clearTimeout(handle),
-  });
+  const pluginVersionService = createPluginVersionService();
 
   server = createRelayWorkerSupervisor({
     pluginId: "ocuclaw",
-    getPluginVersion: () => pluginUpdateService.getPluginVersion(),
-    getRequiresClientVersion: () => pluginUpdateService.getRequiresClientVersion(),
+    getPluginVersion: () => pluginVersionService.getPluginVersion(),
+    getRequiresClientVersion: () => pluginVersionService.getRequiresClientVersion(),
     logger,
     handler,
     operationRegistry: relayOperationRegistry,
@@ -2515,8 +2687,6 @@ function createRelay(opts) {
     port: opts.port,
     token: opts.token,
     externalDebugToolsEnabled,
-    runPluginUpdate: () => pluginUpdateService.runPluginUpdate(),
-    runGatewayRestart: () => pluginUpdateService.runGatewayRestart(),
     evenAiRequestTimeoutMs: opts.evenAiRequestTimeoutMs,
     evenAiMaxBodyBytes: opts.evenAiMaxBodyBytes,
     evenAiMaxResponseBytes: opts.evenAiMaxResponseBytes,
@@ -2953,6 +3123,16 @@ function createRelay(opts) {
      * The downstream server is already listening from construction.
     */
     start() {
+      // Bounded cleanup of stale stable-prompt snapshots (14-day TTL).
+      if (!stablePromptSweepTimer) {
+        stablePromptSweepTimer = setInterval(
+          () => stablePromptSnapshots.sweep(),
+          60 * 60 * 1000, // hourly
+        );
+        if (typeof stablePromptSweepTimer.unref === "function") {
+          stablePromptSweepTimer.unref();
+        }
+      }
       const startGateway = () => Promise.resolve(gatewayBridge.start()).then(() => {
         prefetchSonioxModels("relay_start").catch((err) => {
           logger.warn(`[relay] Soniox models prefetch failed: ${err.message}`);
@@ -2974,6 +3154,10 @@ function createRelay(opts) {
      */
     stop() {
       clearSimulateStreamTimers();
+      if (stablePromptSweepTimer) {
+        clearInterval(stablePromptSweepTimer);
+        stablePromptSweepTimer = null;
+      }
       if (evenAiEndpoint) {
         evenAiEndpoint.close();
       }
@@ -3019,6 +3203,9 @@ function createRelay(opts) {
     __onTraceLogSetForTest(clientId, request) {
       return applyTraceLogSet(clientId, request);
     },
+    __onDebugSetForTest(clientId, request) {
+      return applyDebugSet(clientId, request);
+    },
 
     get operationRegistryForTest() {
       return relayOperationRegistry;
@@ -3050,6 +3237,49 @@ function createRelay(opts) {
       return sessionService.isSessionUserLocked(sessionKey);
     },
 
+    getDisplayStartStates(sessionKey) {
+      return sessionService.getDisplayStartStates(sessionKey);
+    },
+
+    getDisplayCurrentStates(sessionKey) {
+      return sessionService.getDisplayCurrentStates(sessionKey);
+    },
+
+    // Accessors used by the session-title distiller sidecar.
+    getSessionTitleRecord(sessionKey) {
+      return sessionService.getSessionTitleRecord(sessionKey);
+    },
+    isEvenAiSessionKey(sessionKey) {
+      return sessionService.isEvenAiSessionKey(sessionKey);
+    },
+    getRawMessages() {
+      return conversationState.getRawMessages();
+    },
+    getDistillerBudget() {
+      return sessionService.getDistillerBudget();
+    },
+    // Canonical-key cleanup for the distiller's throwaway upstream session.
+    // The native subagent deleteSession passes the bare key straight to
+    // sessions.delete, which the 2026.6.x gateway indexes under the canonical
+    // agent:<id>: form — the bare-key delete silently no-ops and the
+    // excerpt-bearing transcript survives. deleteSessions() resolves the
+    // canonical key via sessions.resolve first.
+    deleteDistillerSession(sessionKey) {
+      return sessionService.deleteSessions("ocuclaw", [sessionKey]);
+    },
+    getStateDir() {
+      return opts.stateDir;
+    },
+    emitDebug(...args) {
+      return emitDebug(...args);
+    },
+    gatewayRequest(method, params, requestOpts) {
+      return gatewayBridge.request(method, params, requestOpts);
+    },
+    onGatewayEvent(eventName, listener) {
+      return gatewayBridge.on(eventName, listener);
+    },
+
     peekSessionKey() {
       return sessionService.peekSessionKey();
     },
@@ -3084,6 +3314,15 @@ function createRelay(opts) {
       return dispatchOcuClawUserSend(params || {});
     },
 
+    /**
+     * Test-only: run the logical-reset state clear (the same call the /new,
+     * /reset, and new-chat paths make) so integration tests can verify all
+     * per-session state is dropped for a reused session key.
+     */
+    _clearLogicalSessionState(sessionKey) {
+      sessionService.clearLogicalSessionState(sessionKey);
+    },
+
     sendGlassesUiRender(params) {
       sendGlassesUiRender(params);
     },