ocuclaw 1.3.1 → 1.3.3

package/dist/runtime/relay-service.js

@@ -1,5 +1,10 @@
 import { createRuntimeConfig } from "../config/runtime-config.js";
 import { createPluginOpenclawClient } from "../gateway/openclaw-client.js";
+import {
+  composeContainerLoopbackWarning,
+  isContainerEnvironment,
+  isLoopbackBindAddress,
+} from "./container-env.js";
 import { createRelay as createPluginOwnedRelay } from "./relay-core.js";
 
 function normalizeLogger(logger) {
@@ -158,6 +163,13 @@ export function createOcuClawRelayService(opts = {}) {
       logger.info(
         `[ocuclaw] relay service started on ws://${config.wsBind}:${config.wsPort}`,
       );
+      const containerEnvProbe =
+        typeof opts.isContainerEnvironment === "function"
+          ? opts.isContainerEnvironment
+          : isContainerEnvironment;
+      if (isLoopbackBindAddress(config.wsBind) && containerEnvProbe()) {
+        logger.warn(composeContainerLoopbackWarning(config.wsBind, config.wsPort));
+      }
       return nextRelay;
     } catch (err) {
       clearSharedRelay(nextRelay);
@@ -291,34 +303,128 @@ export function createOcuClawRelayService(opts = {}) {
         trackedThrowawayKeys: [],
       };
     },
+    // These reads back the session-title tool, the distiller gates, and the
+    // Channel-2 before_prompt_build hook — all of which can run in a sibling
+    // plugin-register context whose own `relay` is null. Resolve the live
+    // (possibly shared) relay so they reach the running instance, mirroring
+    // hasConnectedAppClient(); otherwise the distiller skips every run and the
+    // Channel-2 stop-notices never fire.
     getSessionTitle(sessionKey) {
-      if (relay && typeof relay.getSessionTitle === "function") {
-        return relay.getSessionTitle(sessionKey);
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.getSessionTitle === "function") {
+        return liveRelay.getSessionTitle(sessionKey);
       }
       return null;
     },
     hasRecordedUserMessage(sessionKey) {
-      if (relay && typeof relay.hasRecordedUserMessage === "function") {
-        return relay.hasRecordedUserMessage(sessionKey);
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.hasRecordedUserMessage === "function") {
+        return liveRelay.hasRecordedUserMessage(sessionKey);
       }
-      // Fail-closed when the relay isn't running: block titling.
+      // Fail-closed when no relay is running: block titling.
       return false;
     },
     isNeuralSessionNamesEnabled(sessionKey) {
-      if (relay && typeof relay.isNeuralSessionNamesEnabled === "function") {
-        return relay.isNeuralSessionNamesEnabled(sessionKey);
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.isNeuralSessionNamesEnabled === "function") {
+        return liveRelay.isNeuralSessionNamesEnabled(sessionKey);
       }
       return true;
     },
     isSessionUserLocked(sessionKey) {
-      if (relay && typeof relay.isSessionUserLocked === "function") {
-        return relay.isSessionUserLocked(sessionKey);
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.isSessionUserLocked === "function") {
+        return liveRelay.isSessionUserLocked(sessionKey);
       }
       return false;
     },
+    getDisplayStartStates(sessionKey) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.getDisplayStartStates === "function") {
+        return liveRelay.getDisplayStartStates(sessionKey);
+      }
+      return { emoji: false, pace: false };
+    },
+    getDisplayCurrentStates(sessionKey) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.getDisplayCurrentStates === "function") {
+        return liveRelay.getDisplayCurrentStates(sessionKey);
+      }
+      return { emoji: false, pace: false };
+    },
+    // Distiller-sidecar passthroughs. Use the live relay (possibly a sibling
+    // register-context's shared relay) since the distiller may fire from a
+    // context whose own `relay` is null.
+    getSessionTitleRecord(sessionKey) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.getSessionTitleRecord === "function") {
+        return liveRelay.getSessionTitleRecord(sessionKey);
+      }
+      return null;
+    },
+    isEvenAiSessionKey(sessionKey) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.isEvenAiSessionKey === "function") {
+        return liveRelay.isEvenAiSessionKey(sessionKey);
+      }
+      return false;
+    },
+    getRawMessages() {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.getRawMessages === "function") {
+        return liveRelay.getRawMessages();
+      }
+      return [];
+    },
+    getDistillerBudget() {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.getDistillerBudget === "function") {
+        return liveRelay.getDistillerBudget();
+      }
+      return null;
+    },
+    deleteDistillerSession(sessionKey) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.deleteDistillerSession === "function") {
+        return liveRelay.deleteDistillerSession(sessionKey);
+      }
+      return Promise.resolve(null);
+    },
+    getStateDir() {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.getStateDir === "function") {
+        return liveRelay.getStateDir();
+      }
+      return opts.stateDir;
+    },
+    emitDebug(...args) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.emitDebug === "function") {
+        return liveRelay.emitDebug(...args);
+      }
+      return undefined;
+    },
+    gatewayRequest(method, params, requestOpts) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.gatewayRequest === "function") {
+        return liveRelay.gatewayRequest(method, params, requestOpts);
+      }
+      return Promise.reject(new Error("relay_not_running"));
+    },
+    onGatewayEvent(eventName, listener) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.onGatewayEvent === "function") {
+        return liveRelay.onGatewayEvent(eventName, listener);
+      }
+      return () => {};
+    },
     peekSessionKey() {
-      if (relay && typeof relay.peekSessionKey === "function") {
-        return relay.peekSessionKey();
+      // The set_session_title tool reads this before writing; like the adjacent
+      // session-title accessors it must reach the live (possibly shared) relay,
+      // or an explicit rename from a sibling tool context fails no_active_session.
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.peekSessionKey === "function") {
+        return liveRelay.peekSessionKey();
       }
       return null;
     },
@@ -328,8 +434,9 @@ export function createOcuClawRelayService(opts = {}) {
       }
     },
     setSessionTitle(sessionKey, title, opts) {
-      if (relay && typeof relay.setSessionTitle === "function") {
-        return relay.setSessionTitle(sessionKey, title, opts);
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.setSessionTitle === "function") {
+        return liveRelay.setSessionTitle(sessionKey, title, opts);
       }
       return { ok: false, code: "relay_not_running" };
     },
@@ -340,6 +447,38 @@ export function createOcuClawRelayService(opts = {}) {
       }
       return false;
     },
+    isGlassesSendBufferOverHighWater() {
+      // Roadmap 4a: glasses-ui paint-floor shed signal (glasses-ui-tool.ts
+      // already consults this; false = no shedding, the safe default).
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.isGlassesSendBufferOverHighWater === "function") {
+        return liveRelay.isGlassesSendBufferOverHighWater();
+      }
+      return false;
+    },
+    // Tap-to-wake lane + busy signal (roadmap 6f). registerGlassesUiTool
+    // probes these at plugin register() time — BEFORE start() — and wires
+    // dispatchWake to null when the probe fails, so they must exist on the
+    // facade unconditionally and resolve the live (possibly shared) relay at
+    // call time, like every other passthrough above.
+    dispatchGlassesWake(params) {
+      const liveRelay = resolveLiveRelay();
+      if (!liveRelay || typeof liveRelay.dispatchGlassesWake !== "function") {
+        // The wake controller retries once, then parks the wake in its
+        // durable outbox with a warn lifecycle — never silent after the ✓-ack.
+        return Promise.reject(new Error("ocuclaw relay not started"));
+      }
+      return liveRelay.dispatchGlassesWake(params);
+    },
+    isAgentTurnBusy(sessionKey) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.isAgentTurnBusy === "function") {
+        return liveRelay.isAgentTurnBusy(sessionKey);
+      }
+      // Idle, not busy: a missing relay must surface through the dispatch
+      // path's failure handling, never suppress wakes as phantom-busy.
+      return false;
+    },
     start,
     stop,
   };

package/dist/runtime/relay-worker-entry.js

@@ -5,10 +5,36 @@ if (!parentPort) {
   throw new Error("relay worker entry requires parentPort");
 }
 
+function formatLogArgs(args) {
+  return args
+    .map((arg) => {
+      if (typeof arg === "string") return arg;
+      if (arg instanceof Error) return arg.message;
+      try {
+        return JSON.stringify(arg);
+      } catch {
+        return String(arg);
+      }
+    })
+    .join(" ");
+}
+
+function postWorkerLog(level, args) {
+  parentPort.postMessage({ kind: "worker.log", level, message: formatLogArgs(args) });
+}
+
 const transport = createRelayWorkerTransport({
   postToMain(message) {
     parentPort.postMessage(message);
   },
+  // Worker-thread console output never reaches the gateway's log file;
+  // forward log lines to the supervisor, which owns the real plugin logger.
+  logger: {
+    info(...args) { postWorkerLog("info", args); },
+    warn(...args) { postWorkerLog("warn", args); },
+    error(...args) { postWorkerLog("error", args); },
+    debug(...args) { postWorkerLog("debug", args); },
+  },
 });
 
 parentPort.on("message", async (message) => {

package/dist/runtime/relay-worker-supervisor.js

@@ -519,6 +519,16 @@ export function createRelayWorkerSupervisor(options = {}) {
       logger.warn(`[relay-worker] ${message.message || "worker error"}`);
       return;
     }
+    if (message.kind === "worker.log") {
+      // Worker-thread console output never reaches the gateway's structured
+      // log file, so the worker forwards its log lines here instead.
+      const level =
+        message.level === "warn" || message.level === "error" || message.level === "debug"
+          ? message.level
+          : "info";
+      logger[level](typeof message.message === "string" ? message.message : String(message.message));
+      return;
+    }
     if (message.kind === "app.message") {
       if (!handler || typeof handler.handleMessage !== "function") return;
       const processOptions = {};
@@ -581,7 +591,7 @@ export function createRelayWorkerSupervisor(options = {}) {
         clientName: message.clientName || null,
         clientVersion: message.clientVersion || null,
         sessionKey: message.sessionKey || null,
-        readinessSnapshot: message.readinessSnapshot || null,
+        readinessSnapshot: normalizeIngestedReadinessSnapshot(message.readinessSnapshot),
         connectedAtMs: Number.isFinite(message.connectedAtMs)
           ? message.connectedAtMs
           : Date.now(),
@@ -681,7 +691,7 @@ export function createRelayWorkerSupervisor(options = {}) {
     if (message.kind === "client.readinessSnapshot") {
       const entry = clients.get(message.clientId);
       if (entry) {
-        entry.readinessSnapshot = message.readinessSnapshot || null;
+        entry.readinessSnapshot = normalizeIngestedReadinessSnapshot(message.readinessSnapshot);
         entry.updatedAtMs = Number.isFinite(message.updatedAtMs)
           ? message.updatedAtMs
           : Date.now();
@@ -695,6 +705,21 @@ export function createRelayWorkerSupervisor(options = {}) {
       const pending = requestId ? pendingReadinessProbeRequests.get(requestId) : null;
       if (!pending || pending.targetClientId !== message.clientId) return;
       pendingReadinessProbeRequests.delete(requestId);
+      // Probe acks carry the app's CURRENT activeSessionKey — ground truth.
+      // Refresh the registry entry with it: the app's standalone snapshot
+      // republication can race a reconnecting socket and get lost, leaving the
+      // hello-frozen key here until the next app boot (quirk 8's second layer).
+      if (ack && ack.ok !== false && typeof ack.activeSessionKey === "string" && ack.activeSessionKey) {
+        const ackEntry = clients.get(message.clientId);
+        if (ackEntry && ackEntry.readinessSnapshot) {
+          ackEntry.readinessSnapshot = {
+            ...ackEntry.readinessSnapshot,
+            activeSessionKey: ack.activeSessionKey,
+            emittedAtMs: Number.isFinite(ack.emittedAtMs) ? ack.emittedAtMs : Date.now(),
+          };
+          ackEntry.updatedAtMs = Date.now();
+        }
+      }
       const protocol = clients.get(message.clientId) || {};
       const frame =
         handler && typeof handler.formatReadinessProbeAck === "function"
@@ -752,6 +777,14 @@ export function createRelayWorkerSupervisor(options = {}) {
       postMainFrame("unicast", frame, pending.requesterClientId);
       return;
     }
+    if (message.kind === "worker.backpressure") {
+      // Roadmap 4a: heartbeat-cadence send-buffer pressure counts from the
+      // worker transport; relay-core latches them for the glasses paint shed.
+      if (typeof options.onWorkerBackpressure === "function") {
+        options.onWorkerBackpressure(message);
+      }
+      return;
+    }
     if (message.kind === "debug" && typeof options.emitDebug === "function") {
       options.emitDebug(
         message.category || "relay.worker.health",
@@ -911,6 +944,22 @@ export function createRelayWorkerSupervisor(options = {}) {
     });
   }
 
+  // The WebUI's reconnect hello embeds its readiness snapshot WITHOUT
+  // emittedAtMs (toProtocolHelloReadinessSnapshotJson omits it), but the
+  // automation-state gate requires a finite emittedAtMs to count the client
+  // as published. Stamp ingest time so a reconnect hello counts as a
+  // publication — otherwise every relay restart leaves `inspect state`
+  // returning snapshot_unavailable until the sim/app client is cycled.
+  function normalizeIngestedReadinessSnapshot(snapshot) {
+    if (!snapshot || typeof snapshot !== "object") {
+      return null;
+    }
+    if (Number.isFinite(snapshot.emittedAtMs)) {
+      return snapshot;
+    }
+    return { ...snapshot, emittedAtMs: Date.now() };
+  }
+
   function getReadinessSnapshot() {
     const appClients = getConnectedAppEntries();
     const updatedAtMs = appClients.reduce((latest, entry) => {

package/dist/runtime/relay-worker-transport.js

@@ -56,6 +56,36 @@ export function createRelayWorkerTransport(options = {}) {
   let httpServer = null;
   let wss = null;
   let nextClientId = 1;
+  // Invalid-token rejects are the one connection log an internet-facing
+  // misconfiguration could flood, so they are rate-limited per remote address.
+  const TOKEN_REJECT_LOG_WINDOW_MS = 60000;
+  const TOKEN_REJECT_LOG_MAX_ADDRESSES = 100;
+  const tokenRejectLogState = new Map();
+
+  function logTokenReject(remoteAddress) {
+    const at = now();
+    let state = tokenRejectLogState.get(remoteAddress);
+    if (!state) {
+      if (tokenRejectLogState.size >= TOKEN_REJECT_LOG_MAX_ADDRESSES) {
+        tokenRejectLogState.clear();
+      }
+      state = { lastLogAtMs: null, suppressedCount: 0 };
+      tokenRejectLogState.set(remoteAddress, state);
+    }
+    if (state.lastLogAtMs !== null && at - state.lastLogAtMs < TOKEN_REJECT_LOG_WINDOW_MS) {
+      state.suppressedCount += 1;
+      return;
+    }
+    const suffix =
+      state.suppressedCount > 0
+        ? ` (+${state.suppressedCount} more rejected from this address since last log)`
+        : "";
+    state.lastLogAtMs = at;
+    state.suppressedCount = 0;
+    logger.warn(
+      `[ocuclaw] relay rejected connection: invalid token remote=${remoteAddress}${suffix}`,
+    );
+  }
   let expireTimer = null;
   let healthTimer = null;
   let loopDelayMonitor = null;
@@ -894,11 +924,17 @@ export function createRelayWorkerTransport(options = {}) {
     });
     wss.on("connection", (ws, req) => {
       const requestUrl = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
+      const remoteAddress = (req.socket && req.socket.remoteAddress) || "unknown";
       if (requestUrl.searchParams.get("token") !== manifest.relayToken) {
+        logTokenReject(remoteAddress);
         ws.close(4001, "invalid_token");
         return;
       }
       const clientId = `worker-client-${nextClientId++}`;
+      const connectedAtMs = now();
+      logger.info(
+        `[ocuclaw] relay client connected clientId=${clientId} remote=${remoteAddress}`,
+      );
       clients.set(clientId, ws);
       protocolState.set(clientId, {
         protocolVersion: null,
@@ -925,6 +961,11 @@ export function createRelayWorkerTransport(options = {}) {
             : Buffer.isBuffer(reason)
               ? reason.toString("utf8")
               : String(reason);
+        logger.info(
+          `[ocuclaw] relay client disconnected clientId=${clientId} remote=${remoteAddress} code=${
+            Number.isFinite(code) ? code : "none"
+          } lifetimeMs=${Math.max(0, now() - connectedAtMs)}`,
+        );
         postToMain({
           kind: "client.disconnected",
           clientId,
@@ -956,8 +997,17 @@ export function createRelayWorkerTransport(options = {}) {
     }, Math.max(10, Math.min(1000, manifest.queue.messageSendTtlMs)));
     healthTimer = setInterval(() => {
       health.updateLoopLagP95Ms(sampleLoopLagP95Ms());
-      health.updateSendBufferHighWaterClients(countSendBufferHighWaterClients());
+      const sendBufferHighWaterClients = countSendBufferHighWaterClients();
+      health.updateSendBufferHighWaterClients(sendBufferHighWaterClients);
       health.sample();
+      // Roadmap 4a: main holds the glasses paint-floor shed latch; the ws
+      // sockets (and their bufferedAmount) live here in the worker, so the
+      // count crosses on every heartbeat (the latch fail-opens on staleness).
+      postToMain({
+        kind: "worker.backpressure",
+        workerEpoch: manifest.workerEpoch,
+        sendBufferHighWaterClients,
+      });
     }, manifest.health.heartbeatIntervalMs);
     postToMain({ kind: "worker.ready", workerEpoch: manifest.workerEpoch, address: address() });
   }

package/dist/runtime/session-service.js

@@ -1,6 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { stripAllTaggedSpans } from "../domain/tagged-span-strip.js";
+import { createDisplayToggleTracker } from "./display-toggle-states.js";
+import { decideTitleWrite, isUserOrigin } from "./session-title-record.js";
+import { createDistillerBudget } from "./session-title-distiller-budget.js";
 
 const SESSION_FIRST_USER_CACHE_FILE = "session-first-user-cache.json";
 const SESSION_TITLE_CACHE_FILE = "session-title-cache.json";
@@ -168,6 +171,14 @@ export function createSessionService(opts = {}) {
   const sessionTitleByKey = loadSessionTitleCache();
   /** @type {Map<string, boolean>} Per-session Neural Session Names toggle state. */
   const neuralSessionNamesEnabledByKey = new Map();
+  /** Per-session display-feature (emoji/pace) toggle states: frozen start + latest.
+   * The frozen start-state persists to stateDir so a relay restart can't lose it
+   * (the Channel-1 snapshot persists too — see stable-prompt-snapshot). */
+  const displayToggleTracker = createDisplayToggleTracker({ stateDir: opts.stateDir });
+  /** Per-session SKIP-exempt budget for the background title distiller. Owned
+   * here (alongside the title record + toggle tracker) so a logical session
+   * reset clears all per-session distiller state in one place. */
+  const distillerBudget = createDistillerBudget({});
 
   /** Path for session pin metadata cache file. */
   const sessionPinCachePath = resolveSessionPinCachePath(opts.stateDir);
@@ -780,10 +791,17 @@ export function createSessionService(opts = {}) {
   function resolveRowTitle(sessionKey, row) {
     const cached = getSessionTitle(sessionKey);
     if (cached !== null) return cached;
-    // row.displayName: upstream session-row label per
-    // openclaw/docs/reference/session-management-compaction.md §169.
-    if (row && typeof row.displayName === "string") {
-      const trimmed = row.displayName.trim();
+    // Upstream session-row label: `label` on 2026.6.x rows; older hosts
+    // (≤5.27-era docs, session-management-compaction.md §169) used
+    // `displayName` — accept both.
+    const rawLabel =
+      row && typeof row.label === "string"
+        ? row.label
+        : row && typeof row.displayName === "string"
+          ? row.displayName
+          : "";
+    {
+      const trimmed = rawLabel.trim();
       if (trimmed) return trimmed;
     }
     return null;
@@ -977,6 +995,7 @@ export function createSessionService(opts = {}) {
         sessionPinByKey.delete(key);
         sessionTitleByKey.delete(key);
         firstSentUserMessageBySession.delete(key);
+        distillerBudget.clear(key);
         deleted.push(key);
       } catch (err) {
         failed.push({ key, reason: err?.message ?? "unknown" });
@@ -1284,6 +1303,11 @@ export function createSessionService(opts = {}) {
     return entry ? entry.title : null;
   }
 
+  function getSessionTitleRecord(sessionKey) {
+    const entry = sessionTitleByKey.get(sessionKey);
+    return entry ? { ...entry } : null;
+  }
+
   function setSessionTitle(sessionKey, title, opts) {
     if (typeof sessionKey !== "string" || !sessionKey.trim()) {
       return { ok: false, code: "invalid_session_key" };
@@ -1292,19 +1316,26 @@ export function createSessionService(opts = {}) {
       return { ok: false, code: "invalid_title" };
     }
     const trimmed = title.trim();
-    const setByUser = !!(opts && opts.userSet === true);
+    // Back-compat: callers passing { userSet:true } map to the user_tool origin.
+    const origin =
+      opts && typeof opts.origin === "string" && opts.origin
+        ? opts.origin
+        : opts && opts.userSet === true
+          ? "user_tool"
+          : "topic_distiller";
     const previous = sessionTitleByKey.get(sessionKey);
-
-    if (!setByUser && previous && previous.userSet === true) {
-      return { ok: false, code: "session_user_locked" };
+    const decision = decideTitleWrite(previous, origin);
+    if (!decision.allowed) {
+      return { ok: false, code: decision.code };
     }
-
     const replaced = !!previous;
-    const nextUserSet = setByUser || (previous && previous.userSet === true);
+    const nextUserSet = decision.nextUserSet;
+    const setByUser = isUserOrigin(origin);
     sessionTitleByKey.set(sessionKey, {
       title: trimmed,
       setAtMs: Date.now(),
       userSet: !!nextUserSet,
+      origin,
     });
     pruneSessionTitleEntries(sessionTitleByKey);
     persistSessionTitleCache();
@@ -1314,15 +1345,26 @@ export function createSessionService(opts = {}) {
       setByUser ? "session_title_set_by_user" : "session_title_set",
       "info",
       { sessionKey },
-      () => ({ sessionKey, title: trimmed, replaced, userSet: !!nextUserSet }),
+      () => ({ sessionKey, title: trimmed, replaced, userSet: !!nextUserSet, origin }),
     );
     // Fire-and-forget upstream mirror.
+    if (!isUpstreamConnected()) {
+      emitDebug(
+        "relay.session",
+        "session_title_upstream_mirror_skipped",
+        "debug",
+        { sessionKey },
+        () => ({ reason: "upstream_disconnected", origin }),
+      );
+    }
     if (isUpstreamConnected()) {
       resolveSessionCanonicalKey(sessionKey)
         .then((canonicalKey) =>
+          // 2026.6.x strict schema: the session title field is `label`
+          // (5.27-era `displayName` is rejected as an unexpected property).
           gatewayBridge.request("sessions.patch", {
             key: canonicalKey,
-            displayName: trimmed,
+            label: trimmed,
           }),
         )
         .catch((err) => {
@@ -1364,6 +1406,78 @@ export function createSessionService(opts = {}) {
     return cached === undefined ? true : cached;
   }
 
+  function recordDisplayToggleStates(sessionKey, states) {
+    if (typeof sessionKey !== "string" || !sessionKey.trim()) return;
+    displayToggleTracker.record(sessionKey, states);
+  }
+  function getDisplayStartStates(sessionKey) {
+    return displayToggleTracker.getStart(sessionKey);
+  }
+  function getDisplayCurrentStates(sessionKey) {
+    return displayToggleTracker.getCurrent(sessionKey);
+  }
+  function clearDisplayToggleStates(sessionKey) {
+    displayToggleTracker.clear(sessionKey);
+  }
+
+  function getDistillerBudget() {
+    return distillerBudget;
+  }
+  function clearDistillerBudget(sessionKey) {
+    if (typeof sessionKey === "string" && sessionKey.trim()) {
+      distillerBudget.clear(sessionKey);
+    }
+  }
+  // Drop the stored title record for a session AND clear the upstream display
+  // name. setSessionTitle mirrors the title to the upstream session displayName,
+  // and session-list rendering falls back to that displayName when the local
+  // record is gone — so a local-only delete would let the old title reappear on
+  // the next sessions refresh. deleteSessions removes it for genuine deletes;
+  // this is for a reused-key logical reset (/new, /reset).
+  function clearSessionTitle(sessionKey) {
+    if (typeof sessionKey !== "string" || !sessionKey.trim()) return;
+    const hadTitle = sessionTitleByKey.delete(sessionKey);
+    if (!hadTitle) return;
+    persistSessionTitleCache();
+    invalidateSessionsCache();
+    if (isUpstreamConnected()) {
+      resolveSessionCanonicalKey(sessionKey)
+        .then((canonicalKey) =>
+          gatewayBridge.request("sessions.patch", { key: canonicalKey, label: null }),
+        )
+        .catch((err) => {
+          emitDebug(
+            "relay.session",
+            "session_title_upstream_clear_failed",
+            "debug",
+            { sessionKey },
+            () => ({ message: err && err.message ? err.message : String(err) }),
+          );
+        });
+    }
+  }
+
+  // Clear ALL per-session state keyed to a conversation that must not bleed into
+  // a fresh conversation reusing the same session key (/new, /reset). Centralized
+  // so reset paths can't miss a piece (title + upstream name, toggle states,
+  // distiller budget, the first-user-message marker the distiller gate reads, and
+  // the per-session feature toggle).
+  function clearLogicalSessionState(sessionKey) {
+    if (typeof sessionKey !== "string" || !sessionKey.trim()) return;
+    clearSessionTitle(sessionKey);
+    displayToggleTracker.clear(sessionKey);
+    distillerBudget.clear(sessionKey);
+    // Clear BOTH the first-user marker AND the derived preview cache, and persist
+    // the deletion — recordFirstSentUserMessage writes the marker to disk, so a
+    // local-only delete would let a relay/plugin restart reload a stale
+    // "user already spoke" marker for the reused key (the distiller gate reads
+    // this, and the session-list preview reads the derived cache).
+    const hadMarker = firstSentUserMessageBySession.delete(sessionKey);
+    firstUserMessageCache.delete(sessionKey);
+    if (hadMarker) persistFirstSentUserMessageCache();
+    neuralSessionNamesEnabledByKey.delete(sessionKey);
+  }
+
   function isSyntheticSessionStarter(text) {
     if (!text) return false;
     if (
@@ -1645,11 +1759,21 @@ export function createSessionService(opts = {}) {
     clearPendingInitialConfig,
     getSessions,
     getSessionTitle,
+    getSessionTitleRecord,
     getSessionsByExactKeys,
     hasRecordedFirstUserMessage,
     isNeuralSessionNamesEnabled,
+    isEvenAiSessionKey,
     isSessionUserLocked,
     recordNeuralSessionNamesEnabled,
+    recordDisplayToggleStates,
+    getDisplayStartStates,
+    getDisplayCurrentStates,
+    clearDisplayToggleStates,
+    getDistillerBudget,
+    clearDistillerBudget,
+    clearSessionTitle,
+    clearLogicalSessionState,
     setSessionTitle,
     switchToSession,
     newSession,