ocuclaw 1.3.1 → 1.3.3

package/dist/config/runtime-config-session-title-model.test.js

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createRuntimeConfig } from "./runtime-config.ts";
+
+// Minimal valid config: relayToken (pluginConfig) + a gateway auth token
+// (openclawConfig) — createRuntimeConfig throws without a resolvable
+// gatewayUrl/gatewayToken (gatewayUrl defaults to ws://127.0.0.1:18789).
+const base = { relayToken: "tok" };
+const openclawConfig = { gateway: { auth: { token: "gw" } } };
+
+test("absent sessionTitleModel → undefined/empty (zero-config path)", () => {
+  const cfg = createRuntimeConfig({ pluginConfig: { ...base }, openclawConfig });
+  assert.ok(!cfg.sessionTitleModel);
+});
+
+test("sessionTitleModel string is carried through", () => {
+  const cfg = createRuntimeConfig({
+    pluginConfig: { ...base, sessionTitleModel: "openai/gpt-5-mini" },
+    openclawConfig,
+  });
+  assert.equal(cfg.sessionTitleModel, "openai/gpt-5-mini");
+});

package/dist/config/runtime-config.js

@@ -145,7 +145,12 @@ function resolveGlassesUiLive(value) {
     // plugins.entries.ocuclaw.config.glassesUiLive.httpEnabled = true to
     // enable. The dispatcher protection still applies once enabled.
     httpEnabled: parseBool(raw.httpEnabled, false),
-    llmEnabled: parseBool(raw.llmEnabled, true),
+    // llm ticks are agent-influenced model calls on a schedule (token spend +
+    // hallucinated-display risk); the tier is deliberately untaught in the
+    // skill, and an enabled-but-undocumented capability is the worst of both.
+    // Operator opt-in like httpEnabled (user decision 2026-06-10); the L1/L2
+    // agent tier is the sanctioned path to reasoning surfaces when it lands.
+    llmEnabled: parseBool(raw.llmEnabled, false),
     maxConcurrentSurfacesPerHost: parseIntOrDefault(raw.maxConcurrentSurfacesPerHost, 4),
   };
 }
@@ -234,6 +239,7 @@ export function createRuntimeConfig(opts = {}) {
     evenAiDedicatedSessionKey: parseEvenAiDedicatedSessionKey(
       pluginConfig.evenAiDedicatedSessionKey,
     ),
+    sessionTitleModel: pickString(pluginConfig.sessionTitleModel),
     renderGlassesUiTimeoutMs: parseIntOrDefault(
       pluginConfig.renderGlassesUiTimeoutMs,
       30 * 60 * 1000,

package/dist/domain/glasses-display-system-prompt.js

@@ -0,0 +1,52 @@
+import { MESSAGE_EMOJI_ALLOWLIST } from "./message-emoji-allowlist.js";
+
+const ALLOWLIST_LINES = (() => {
+  const rows = [];
+  for (let i = 0; i < MESSAGE_EMOJI_ALLOWLIST.length; i += 20) {
+    rows.push(MESSAGE_EMOJI_ALLOWLIST.slice(i, i + 20).join(" "));
+  }
+  return rows.map((r) => `  ${r}`).join("\n");
+})();
+
+const INTRO =
+  "Your replies render on the user's Even G2 glasses HUD. You can wrap short\n" +
+  "phrases with invisible tags that shape how they display — only the wrapped\n" +
+  "words are shown, never the tags:";
+
+const EMOJI_TAG_LINES =
+  "  <emoji:X>phrase</emoji> — flashes a small status emoji above the message\n" +
+  "                            while the phrase reveals. X must be copied\n" +
+  "                            verbatim from the allowed list below.";
+
+const PACE_TAG_LINES =
+  "  <dwell>phrase</dwell>    — reveals the phrase slower; lets a line land.\n" +
+  "  <skim>phrase</skim>      — reveals the phrase faster; rushes past a recap.";
+
+const SHARED_RULES =
+  "Most messages need NO tags. Use one only where it adds real warmth, surprise,\n" +
+  "care, playfulness, or pacing for a single short phrase. Never tag every\n" +
+  "sentence. Always close a tag you open; don't nest a tag inside itself; tags\n" +
+  "may combine on the same phrase.";
+
+const ALLOWLIST_BLOCK =
+  "Allowed emoji (copy exactly one per span):\n" + ALLOWLIST_LINES;
+
+/**
+ * Compose the Channel-1 consolidated display-tags block.
+ * @param {{emoji: boolean, pace: boolean}} opts - features ENABLED AT SESSION START
+ * @returns {string} the block, or "" when neither feature is enabled
+ */
+export function composeGlassesDisplaySystemPrompt(opts) {
+  const emoji = !!(opts && opts.emoji);
+  const pace = !!(opts && opts.pace);
+  if (!emoji && !pace) return "";
+
+  const tagLines = [];
+  if (emoji) tagLines.push(EMOJI_TAG_LINES);
+  if (pace) tagLines.push(PACE_TAG_LINES);
+
+  const parts = [INTRO, tagLines.join("\n"), SHARED_RULES];
+  if (emoji) parts.push(ALLOWLIST_BLOCK);
+
+  return `<glasses_display>\n${parts.join("\n\n")}\n</glasses_display>`;
+}

package/dist/domain/glasses-display-system-prompt.test.js

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { composeGlassesDisplaySystemPrompt } from "./glasses-display-system-prompt.ts";
+import { MESSAGE_EMOJI_ALLOWLIST } from "./message-emoji-allowlist.ts";
+
+test("neither feature enabled → empty string", () => {
+  assert.equal(
+    composeGlassesDisplaySystemPrompt({ emoji: false, pace: false }),
+    "",
+  );
+});
+
+test("emoji-only includes emoji tag + full allowlist, omits pace tags", () => {
+  const out = composeGlassesDisplaySystemPrompt({ emoji: true, pace: false });
+  assert.match(out, /<emoji:X>/);
+  assert.doesNotMatch(out, /<dwell>/);
+  assert.doesNotMatch(out, /<skim>/);
+  for (const e of MESSAGE_EMOJI_ALLOWLIST) assert.ok(out.includes(e), `missing ${e}`);
+  assert.match(out, /^<glasses_display>/);
+  assert.match(out, /<\/glasses_display>$/);
+});
+
+test("pace-only includes dwell/skim, omits emoji + allowlist", () => {
+  const out = composeGlassesDisplaySystemPrompt({ emoji: false, pace: true });
+  assert.match(out, /<dwell>/);
+  assert.match(out, /<skim>/);
+  assert.doesNotMatch(out, /<emoji:X>/);
+  // allowlist must not leak when emoji is off
+  assert.ok(!out.includes(MESSAGE_EMOJI_ALLOWLIST[0]));
+});
+
+test("both enabled includes all three tags and the allowlist once", () => {
+  const out = composeGlassesDisplaySystemPrompt({ emoji: true, pace: true });
+  assert.match(out, /<emoji:X>/);
+  assert.match(out, /<dwell>/);
+  assert.match(out, /<skim>/);
+  assert.equal(out.match(/<glasses_display>/g).length, 1);
+});
+
+test("output is deterministic (same inputs → identical bytes)", () => {
+  const a = composeGlassesDisplaySystemPrompt({ emoji: true, pace: true });
+  const b = composeGlassesDisplaySystemPrompt({ emoji: true, pace: true });
+  assert.equal(a, b);
+});

package/dist/domain/glasses-ui-system-prompt.js

@@ -1,26 +1,10 @@
 export const GLASSES_UI_NUDGE_SYSTEM_PROMPT = [
-  "On the user's Even G2 glasses, prefer calling the render_glasses_ui tool over",
-  "a multi-line text reply when the answer is a short list of choices the user",
-  "could pick from (use list_surface), a list where each option has a short",
-  "detail the user needs to read before choosing (use list_with_details_surface,",
-  "with a one-to-two-sentence body per item), or a single formatted block they",
-  "should read (use text_surface). The user can double-tap to back up one popup; if a",
-  "tool call returns { result: \"back\" }, they want to revise their previous",
-  "answer — re-render the previous step or pivot.",
-  "",
-  "After the tool call resolves, your NEXT output decides what the glasses show",
-  "next:",
-  "  • another render_glasses_ui call → replaces the current surface (use this",
-  "    for a drill-down or follow-up step in the flow);",
-  "  • a short text reply → the chat screen takes over and the surface",
-  "    disappears, so the user sees your text instead of the now-stale list;",
-  "  • silent run-end (no further output) → the surface lingers on glass until",
-  "    the user dismisses; only do this if you intentionally want the user to",
-  "    keep interacting with the same surface.",
-  "After result \"selected\", default to either a follow-up render (next step in",
-  "the flow) or a brief one-line text ack confirming the choice; avoid ending",
-  "the run silently unless the rendered surface is still the right thing to",
-  "look at.",
+  "When an answer is a short set of pickable choices or one formatted block,",
+  "prefer the render_glasses_ui tool over a long text reply — see its",
+  "description for when and how.",
+  "If render_glasses_ui is not in your current tool list, search your",
+  "available/deferred tools for it (it surfaces under the openclaw namespace)",
+  "before falling back to a text reply.",
 ].join(" ");
 
 export function composeGlassesUiNudgeSystemPrompt() {

package/dist/domain/glasses-ui-system-prompt.test.js

@@ -0,0 +1,13 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { composeGlassesUiNudgeSystemPrompt } from "./glasses-ui-system-prompt.ts";
+
+test("pointer is short and references the tool + 'see its description'", () => {
+  const out = composeGlassesUiNudgeSystemPrompt();
+  assert.match(out, /render_glasses_ui/);
+  assert.match(out, /description/i);
+  // ef8a821e carry: the deferred-tool search hint rides in the pointer so
+  // Codex-harness runs (tool not in the initial list) still find the tool.
+  assert.match(out, /available\/deferred tools/);
+  assert.ok(out.length < 420, `pointer should stay lean, got ${out.length}`);
+});

package/dist/domain/prompt-channel-fragments.js

@@ -0,0 +1,32 @@
+const EMOJI_STOP =
+  "The emoji reactor is off for the rest of this session — do not use " +
+  "<emoji:X>…</emoji> spans, even if earlier replies did.";
+const PACE_STOP =
+  "The pace modulator is off for the rest of this session — do not use " +
+  "<dwell>…</dwell> or <skim>…</skim> spans, even if earlier replies did.";
+const RENDER_GATE =
+  "No glasses display is connected right now; do not call render_glasses_ui.";
+
+/**
+ * Compose the Channel-2 (before_prompt_build → appendSystemContext) fragment.
+ * Returns undefined when nothing needs saying (the common case).
+ *
+ * @param {{startEnabled:{emoji:boolean,pace:boolean},
+ *          currentEnabled:{emoji:boolean,pace:boolean},
+ *          glassesConnected:boolean}} input
+ * @returns {string|undefined}
+ */
+export function composeChannelTwoFragment(input) {
+  const start = (input && input.startEnabled) || { emoji: false, pace: false };
+  const current = (input && input.currentEnabled) || { emoji: false, pace: false };
+  const glassesConnected = !!(input && input.glassesConnected);
+
+  const parts = [];
+  // Stop-notice only when a feature was ENABLED at start and is now OFF.
+  if (start.emoji && !current.emoji) parts.push(EMOJI_STOP);
+  if (start.pace && !current.pace) parts.push(PACE_STOP);
+  if (!glassesConnected) parts.push(RENDER_GATE);
+
+  if (parts.length === 0) return undefined;
+  return parts.join("\n\n");
+}

package/dist/domain/prompt-channel-fragments.test.js

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { composeChannelTwoFragment } from "./prompt-channel-fragments.ts";
+
+const ENABLED_BOTH = { emoji: true, pace: true };
+
+test("no transitions, glasses connected → undefined (no injection)", () => {
+  assert.equal(
+    composeChannelTwoFragment({
+      startEnabled: ENABLED_BOTH,
+      currentEnabled: ENABLED_BOTH,
+      glassesConnected: true,
+    }),
+    undefined,
+  );
+});
+
+test("emoji disabled mid-session → tiny stop-notice mentioning emoji only", () => {
+  const out = composeChannelTwoFragment({
+    startEnabled: ENABLED_BOTH,
+    currentEnabled: { emoji: false, pace: true },
+    glassesConnected: true,
+  });
+  assert.match(out, /emoji/i);
+  assert.doesNotMatch(out, /dwell|skim|pace/i);
+  assert.ok(out.length < 200, "stop-notice must stay tiny");
+});
+
+test("pace disabled mid-session → tiny stop-notice mentioning pace only", () => {
+  const out = composeChannelTwoFragment({
+    startEnabled: ENABLED_BOTH,
+    currentEnabled: { emoji: true, pace: false },
+    glassesConnected: true,
+  });
+  assert.match(out, /dwell|skim|pace/i);
+  assert.doesNotMatch(out, /<emoji/i);
+});
+
+test("enabling a feature that was OFF at start does NOT inject (lands next session)", () => {
+  assert.equal(
+    composeChannelTwoFragment({
+      startEnabled: { emoji: false, pace: false },
+      currentEnabled: { emoji: true, pace: true },
+      glassesConnected: true,
+    }),
+    undefined,
+  );
+});
+
+test("glasses disconnected → render gate fragment", () => {
+  const out = composeChannelTwoFragment({
+    startEnabled: ENABLED_BOTH,
+    currentEnabled: ENABLED_BOTH,
+    glassesConnected: false,
+  });
+  assert.match(out, /render_glasses_ui/);
+  assert.match(out, /not connected|no glasses/i);
+});
+
+test("multiple fragments join with a blank line and stay small", () => {
+  const out = composeChannelTwoFragment({
+    startEnabled: ENABLED_BOTH,
+    currentEnabled: { emoji: false, pace: false },
+    glassesConnected: false,
+  });
+  assert.match(out, /emoji/i);
+  assert.match(out, /dwell|skim|pace/i);
+  assert.match(out, /render_glasses_ui/);
+  assert.ok(out.length < 400);
+});

package/dist/gateway/gateway-timing-ledger.js

@@ -160,6 +160,18 @@ export function createGatewayTimingLedger(opts = {}) {
     clearTimer(ref);
   }
 
+  // Diagnostic timers must never keep the host process alive: a bare
+  // 120s ttlTimer kept `node tests/relay.test.js` idling ~120s after the
+  // suite finished. Injected fake timers (numeric ids) have no unref —
+  // guard for it.
+  function armDiagnosticTimer(fn, delayMs) {
+    const timer = setTimer(fn, delayMs);
+    if (timer && typeof timer.unref === "function") {
+      timer.unref();
+    }
+    return timer;
+  }
+
   function requestContext(request) {
     return {
       requestId: request.requestId,
@@ -183,7 +195,7 @@ export function createGatewayTimingLedger(opts = {}) {
   function scheduleRequestSlowTimer(request) {
     const thresholdMs =
       request.method === "agent" ? AGENT_ACK_SLOW_MS : GATEWAY_REQUEST_SLOW_MS;
-    request.slowTimer = setTimer(() => {
+    request.slowTimer = armDiagnosticTimer(() => {
       if (request.slowEmitted) return;
       request.slowEmitted = true;
       const elapsedMs = Math.max(0, nowMs() - request.sentAtMs);
@@ -213,7 +225,7 @@ export function createGatewayTimingLedger(opts = {}) {
   }
 
   function scheduleAcceptedRunTimers(run) {
-    run.lifecycleWaitTimer = setTimer(() => {
+    run.lifecycleWaitTimer = armDiagnosticTimer(() => {
       if (run.lifecycleSlowEmitted || run.lifecycleStartedAtMs != null) return;
       run.lifecycleSlowEmitted = true;
       const ackToLifecycleMs = Math.max(0, nowMs() - run.acceptedAtMs);
@@ -238,7 +250,7 @@ export function createGatewayTimingLedger(opts = {}) {
         `[openclaw-timing] slow accepted-run runId=${run.runId} messageId=${run.messageId || "none"} ackToLifecycleMs=${ackToLifecycleMs} pendingRequests=${requests.size}`,
       );
     }, AGENT_LIFECYCLE_WAIT_SLOW_MS);
-    run.ttlTimer = setTimer(() => {
+    run.ttlTimer = armDiagnosticTimer(() => {
       const current = acceptedRuns.get(run.runId);
       if (current !== run) return;
       clearTimerRef(run.lifecycleWaitTimer);

package/dist/gateway/openclaw-client.js

@@ -791,6 +791,17 @@ class OpenClawClient extends EventEmitter {
     this._connectNonce = null;
     this._connectSent = false;
     this._connectTimer = null;
+    // --- Socket-generation handshake gate (1008 reconnect-storm fix) ---
+    // Monotonic counter bumped on every _connect(); _handshakeGeneration is the
+    // watermark of the latest generation whose connect handshake has RESOLVED.
+    // A fresh socket is automatically "handshake-incomplete" (its generation is
+    // strictly greater than the watermark) with no extra reset bookkeeping —
+    // mirrors the existing _activeRunGeneration idiom. request() refuses any
+    // non-connect frame on a real ws socket whose generation has not yet
+    // handshaked, which is what enforces the gateway's "first frame must be
+    // connect" invariant across reconnect churn.
+    this._socketGeneration = 0;
+    this._handshakeGeneration = -1;
     this._tickIntervalMs = 30000;
     this._deviceToken = null; // cached from hello-ok
 
@@ -887,9 +898,33 @@ class OpenClawClient extends EventEmitter {
    *   acks (status: "accepted") and resolve only on the final response.
    */
   request(method, params, opts) {
-    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+    // Capture the socket + generation at ENTRY so a reconnect that reassigns
+    // this._ws between entry and the synchronous send can never land this frame
+    // on a successor socket (kills the successor-socket race variant).
+    const ws = this._ws;
+    const gen = this._socketGeneration;
+    if (!ws || ws !== this._ws || ws.readyState !== WebSocket.OPEN) {
+      // PRESERVE this exact literal — relay.test.js asserts it verbatim for the
+      // no-usable-socket case. The handshake gate below uses a DISTINCT message.
       return Promise.reject(new Error("gateway not connected"));
     }
+    // Per-socket handshake gate: a non-connect frame must not be the first frame
+    // on a freshly-OPEN-but-unregistered socket (gateway emits 1008). connect
+    // BYPASSES the gate (it IS the first allowed frame). The gate only applies
+    // to real `ws.WebSocket` sockets — the unit harnesses inject plain-object
+    // fakes ({ readyState: 1, send }) which are intentionally treated as
+    // already-handshaken so their request("agent"/"ping"/"chat.history") still
+    // sends with no harness changes.
+    if (
+      method !== "connect" &&
+      ws instanceof WebSocket &&
+      this._handshakeGeneration !== gen
+    ) {
+      const err = new Error("gateway handshake in flight");
+      err.code = "handshake_pending";
+      err.retryable = true;
+      return Promise.reject(err);
+    }
     const id = crypto.randomUUID();
     const frame = { type: "req", id, method, params };
     const expectFinal = opts && opts.expectFinal === true;
@@ -925,7 +960,7 @@ class OpenClawClient extends EventEmitter {
       diagnostic,
     });
     this.emit("protocol", { direction: "out", frame });
-    this._ws.send(raw);
+    ws.send(raw);
     return promise;
   }
 
@@ -1053,6 +1088,16 @@ class OpenClawClient extends EventEmitter {
       this._ws = null;
     }
 
+    // Clear a stale 750ms connect-fallback timer left armed by a prior
+    // generation that opened then closed before it fired. _connect() resets
+    // _connectSent=false below, so a stale timer firing here would re-enter
+    // _sendConnect() on the NEW socket — harmless (still a connect frame, never
+    // a 1008), but it can produce a redundant connect. Clearing closes the edge.
+    if (this._connectTimer) {
+      clearTimeout(this._connectTimer);
+      this._connectTimer = null;
+    }
+
     const url = this._gatewayUrl;
     this.emit("status", "connecting");
     this._logger.info(`[openclaw] Connecting to ${url}`);
@@ -1060,6 +1105,13 @@ class OpenClawClient extends EventEmitter {
     this._connectNonce = null;
     this._connectSent = false;
 
+    // Bump the socket generation BEFORE constructing the new socket. The
+    // handshake watermark (_handshakeGeneration) intentionally STAYS at the
+    // prior value, so the about-to-be-created socket is automatically
+    // handshake-incomplete (its generation > watermark) until its own connect
+    // resolves. No watermark reset is needed.
+    this._socketGeneration += 1;
+
     // Reset per-connection state
     this._timingLedger.clear("connect_reset");
     this._lastSeq = null;
@@ -1550,7 +1602,16 @@ class OpenClawClient extends EventEmitter {
 
     const poll = () => {
       this._pollHistoryActivity().catch((err) => {
-        if (!err || !err.message || !/gateway not connected/i.test(err.message)) {
+        // Suppress benign transient rejections during reconnect churn: the
+        // no-socket "gateway not connected" case AND the new handshake-gate
+        // reject (handshake_pending / "gateway handshake in flight"), so the
+        // 1008 fix does not emit spurious poll-failed warnings in its own window.
+        const benignTransient =
+          !!err &&
+          (err.code === "handshake_pending" ||
+            (!!err.message &&
+              /gateway (not connected|handshake in flight)/i.test(err.message)));
+        if (!benignTransient) {
           this._logger.warn(
             `[openclaw] Thinking-summary poll failed: ${
               err && err.message ? err.message : String(err)
@@ -1774,6 +1835,12 @@ class OpenClawClient extends EventEmitter {
 
     this._logger.info("[openclaw] Sending connect request...");
 
+    // Capture the generation this connect is being sent for. The resolve below
+    // must only mark THIS generation handshaken — if a disconnect+reconnect
+    // bumped _socketGeneration before the connect resolved, this resolve is
+    // stale and must NOT open the gate for the new in-flight socket.
+    const connectGeneration = this._socketGeneration;
+
     this.request("connect", params)
       .then((helloOk) => {
         this._logger.info(
@@ -1806,6 +1873,16 @@ class OpenClawClient extends EventEmitter {
           this._logger.info("[openclaw] Device token cached");
         }
 
+        // Open the handshake gate for THIS socket's generation BEFORE emitting
+        // "connected" (so refreshUpstreamBootstrap, fired on the connected event,
+        // sees an open gate). Guard against a stale resolve: if a reconnect
+        // already superseded this socket, _socketGeneration has advanced past
+        // connectGeneration and we must NOT mark the new in-flight socket
+        // handshaken — that would re-admit the very 1008 race this fix closes.
+        if (connectGeneration === this._socketGeneration) {
+          this._handshakeGeneration = connectGeneration;
+        }
+
         this.emit("connected", {
           protocol: helloOk.protocol,
           tickIntervalMs: this._tickIntervalMs,

package/dist/index.js

@@ -1,8 +1,10 @@
 import { createOcuClawRelayService } from "./runtime/relay-service.js";
 import { createEvenAiModelHook } from "./even-ai/even-ai-model-hook.js";
+import { createChannelTwoHook } from "./runtime/channel-two-hook.js";
 import { registerGlassesUiTool } from "./tools/glasses-ui-tool.js";
 import { registerSessionTitleTool } from "./tools/session-title-tool.js";
 import { registerDeviceInfoTool } from "./tools/device-info-tool.js";
+import { registerSessionTitleDistiller } from "./runtime/register-session-title-distiller.js";
 
 export default function register(api) {
   if (!api || typeof api.registerService !== "function") {
@@ -27,14 +29,27 @@ export default function register(api) {
         },
       }),
     );
+    api.on(
+      "before_prompt_build",
+      createChannelTwoHook(
+        {
+          getDisplayStartStates: (k) => service.getDisplayStartStates(k),
+          getDisplayCurrentStates: (k) => service.getDisplayCurrentStates(k),
+          hasConnectedAppClient: () => service.hasConnectedAppClient(),
+        },
+        { emitDebug: (...a) => service.emitDebug(...a) },
+      ),
+    );
   }
 
   let glassesUiDispose = null;
   let deviceInfoDispose = null;
+  let distillerDispose = null;
   if (typeof api.registerTool === "function") {
     glassesUiDispose = registerGlassesUiTool(api, service);
     registerSessionTitleTool(api, service);
     deviceInfoDispose = registerDeviceInfoTool(api, service);
+    distillerDispose = registerSessionTitleDistiller(api, service);
   }
 
   api.registerService({
@@ -59,6 +74,13 @@ export default function register(api) {
           /* ignore: dispose is a best-effort cleanup */
         }
       }
+      if (typeof distillerDispose === "function") {
+        try {
+          distillerDispose();
+        } catch (_) {
+          /* ignore: dispose is a best-effort cleanup */
+        }
+      }
       return service.stop({ logger: ctx && ctx.logger });
     },
   });

package/dist/runtime/channel-two-hook.js

@@ -0,0 +1,36 @@
+import { composeChannelTwoFragment } from "../domain/prompt-channel-fragments.js";
+
+/**
+ * Build a before_prompt_build hook that injects the Channel-2 fragment.
+ * @param {{getDisplayStartStates:Function, getDisplayCurrentStates:Function,
+ *          hasConnectedAppClient:Function}} service
+ */
+export function createChannelTwoHook(service, opts = {}) {
+  const emitDebug = typeof opts.emitDebug === "function" ? opts.emitDebug : () => {};
+  return function channelTwoBeforePromptBuild(_event, ctx) {
+    const sessionKey =
+      ctx && typeof ctx.sessionKey === "string" && ctx.sessionKey.trim()
+        ? ctx.sessionKey
+        : null;
+    if (!sessionKey) return undefined;
+    try {
+      const fragment = composeChannelTwoFragment({
+        startEnabled: service.getDisplayStartStates(sessionKey),
+        currentEnabled: service.getDisplayCurrentStates(sessionKey),
+        glassesConnected:
+          typeof service.hasConnectedAppClient === "function"
+            ? service.hasConnectedAppClient()
+            : true,
+      });
+      if (!fragment) return undefined;
+      emitDebug("relay.session", "channel_two_fragment_injected", "debug",
+        { sessionKey }, () => ({ chars: fragment.length }));
+      return { appendSystemContext: fragment };
+    } catch (_err) {
+      // Defensive: any state-read failure yields no injection.
+      return undefined;
+    }
+  };
+}
+
+export default createChannelTwoHook;

package/dist/runtime/container-env.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+
+// Marker files written by the container runtimes themselves: Docker creates
+// /.dockerenv, Podman creates /run/.containerenv. Kubernetes-style runtimes
+// leave neither — detection there would need heuristics too fragile to ship.
+const CONTAINER_MARKER_PATHS = ["/.dockerenv", "/run/.containerenv"];
+
+export function isLoopbackBindAddress(address) {
+  const normalized = typeof address === "string" ? address.trim().toLowerCase() : "";
+  if (!normalized) return false;
+  return (
+    normalized === "localhost" ||
+    normalized === "::1" ||
+    normalized.startsWith("127.")
+  );
+}
+
+export function isContainerEnvironment(deps = {}) {
+  const existsSync = typeof deps.existsSync === "function" ? deps.existsSync : fs.existsSync;
+  const markerPaths = Array.isArray(deps.markerPaths) ? deps.markerPaths : CONTAINER_MARKER_PATHS;
+  for (const markerPath of markerPaths) {
+    try {
+      if (existsSync(markerPath)) return true;
+    } catch {
+      // No filesystem signal beats a startup failure: treat unreadable markers
+      // as "not a container" and keep the relay booting.
+    }
+  }
+  return false;
+}
+
+export function composeContainerLoopbackWarning(wsBind, wsPort) {
+  return (
+    `[ocuclaw] relay is bound to ${wsBind} inside a container — if the OcuClaw app cannot connect, this is likely why. ` +
+    `Connections from outside the container arrive via its network interface, which a loopback bind does not listen on, ` +
+    `so the relay is unreachable even though it reports healthy. ` +
+    `(Containers run with --network host are unaffected and can ignore this warning.) ` +
+    `Fix: openclaw config set plugins.entries.ocuclaw.config.wsBind "0.0.0.0" ` +
+    `and publish the relay port to the host loopback only (-p 127.0.0.1:${wsPort}:${wsPort}), then restart the gateway.`
+  );
+}