ocuclaw 1.3.1 → 1.3.2

package/dist/tools/glasses-ui-paint-floor.js

@@ -2,15 +2,22 @@
 //
 // Governs ALL plugin->glass sends (initial RebuildPageContainer render and
 // every surface_update patch). Collapses bursts to last-write-wins per field
-// and emits at most one frame per paintFloorMs (default 150ms, Spike D), with
-// a leading-edge send + a trailing send carrying the final merged patch.
+// and emits at most one frame per paintFloorMs, with a leading-edge send + a
+// trailing send carrying the final merged patch.
 //
 // There is NO glass-side paint-ack: the only backpressure signal is
 // relay/BLE transport-side (see the isUnderBackpressure shed in Task 13).
 // Local fake-list textContainerUpgrade scroll-swaps are client-side and never
 // reach this coalescer.
+//
+// 250 is the unconditionally hardware-proven floor. Spike D approved lowering
+// to 150 ONLY once the backpressure shed has a live signal; the shed's
+// isGlassesSendBufferOverHighWater query is implemented nowhere yet, so the
+// shed is inert and 150 would run without its safety condition. Restore 150
+// when the relay-service bridge lands and is validated on hardware
+// (roadmap step 4, docs/superpowers/plans/2026-06-10-glasses-ui-state-reset-and-roadmap.md).
 
-export const DEFAULT_PAINT_FLOOR_MS = 150;
+export const DEFAULT_PAINT_FLOOR_MS = 250;
 
 export function createPaintFloorCoalescer(deps) {
   const paintFloorMs = Number.isFinite(deps.paintFloorMs) ? deps.paintFloorMs : DEFAULT_PAINT_FLOOR_MS;

package/dist/tools/glasses-ui-surfaces.js

@@ -236,7 +236,14 @@ export function createSurfaceStore(deps = {}) {
     // be move-independent (replace, the schema DEFAULT, must behave like
     // patch here, not silently drop a latched exit).
     const priorTop = bySurface.get(top);
-    stopCron(top);
+    // SILENT stop: this is slot recycling for the incoming replace render, not
+    // a real outcome. A non-silent stop fires the cron's onResolve with a
+    // synthesized `preempted`, which (with no pending call at this instant)
+    // latches a bogus exit onto the prior entry — carried into makeEntry below,
+    // it makes the very render we are applying discard-for-exit on re-attach
+    // ("fresh render instantly dismissed", B7 — the real B3 contamination
+    // mechanism, found 2026-06-11).
+    stopCron(top, { silent: true });
     bySurface.set(top, makeEntry(sessionKey, params && params.kind, priorTop));
     return { mode: "replace", surfaceId: top };
   }

package/dist/tools/glasses-ui-tool-description.test.js

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { GLASSES_UI_TOOL_DESCRIPTION } from "./glasses-ui-tool.ts";
+
+test("description now carries the follow-up + back/selected usage rules", () => {
+  const d = GLASSES_UI_TOOL_DESCRIPTION;
+  assert.match(d, /text_surface/);
+  assert.match(d, /list_surface/);
+  assert.match(d, /list_with_details_surface/);
+  // Channel-3 additions (moved from the old nudge):
+  assert.match(d, /NEXT output|next output/);
+  assert.match(d, /back/i);
+  assert.match(d, /selected/i);
+  // Skill pointer retained:
+  assert.match(d, /glasses-ui/);
+});

package/dist/tools/glasses-ui-tool.js

@@ -542,8 +542,8 @@ export function createGlassesUiToolHandler(deps) {
     // parent/chat after a back/pop, and the per-surface coalescer state doesn't
     // leak across a long push/replace session. (pauseCron on push does NOT
     // dispose — the parent resumes.)
-    stopCron: (id) => {
-      cronEngine.stop(id, { result: "preempted" });
+    stopCron: (id, opts) => {
+      cronEngine.stop(id, { result: "preempted" }, opts);
       paintFloor.dispose(id);
     },
     mintSurfaceId: newSurfaceId,
@@ -610,11 +610,33 @@ export function createGlassesUiToolHandler(deps) {
       refreshValidated = v.refresh;
     }
 
+    // params.depth is the execute-level RUN-CALL ordinal (resets at agent_end).
+    // It is used ONLY as the "first render of this run" signal for stale-stack
+    // reaping below — it must NEVER reach the wire. The wire depth is derived
+    // from the store's true stack depth after applyRender (B6: ordinals never
+    // decrement on Back, so they drift past entry counts and break both the
+    // plugin pop reconciliation and the client's clear-vs-append decision).
     const depth = Number.isFinite(params.depth) ? Math.max(1, Math.floor(params.depth)) : 1;
     const update =
       params.spec && (params.spec.update === "patch" || params.spec.update === "push")
         ? params.spec.update
         : "replace";
+    // Stale-stack reaping (B3 safety net): a depth-1 render means NEW ROOT — a
+    // session stack still holding PUSHED children at that moment is orphan
+    // residue from an earlier run (e.g. a client that bailed to chat without
+    // popping). Reap it before registering so a stale child can't swallow this
+    // render's events or forward a stale latched exit. A SINGLE root entry is
+    // NOT stale — that's the designed patch/replace re-attach path
+    // (visible_awaiting_agent), which must keep its latch/queue semantics.
+    if (depth <= 1 && surfaceStore.stackDepth(sessionKey) > 1) {
+      const stackDepthBefore = surfaceStore.stackDepth(sessionKey);
+      const reapedPending = reapSession(sessionKey, { result: "preempted" });
+      emitLifecycle("stale_stack_reaped", "warn", {
+        sessionKey,
+        stackDepthBefore,
+        reapedPending,
+      });
+    }
     // The plugin owns surfaceIds (spec §Core model). applyRender derives the
     // target from the session's current top: patch/replace reuse the top id
     // (re-attach in place), push mints a child + pauses the parent cron, the
@@ -646,6 +668,12 @@ export function createGlassesUiToolHandler(deps) {
       }
     }
 
+    // The wire depth is the TRUE stack depth (entry count) after applyRender:
+    // root=1, push=parent+1, replace/patch=unchanged. The client keys its
+    // clear-vs-append-vs-swap decision and Back classification on this value,
+    // and handleNavEvent's pop loop compares it against the same entry counts.
+    const wireDepth = Math.max(1, surfaceStore.stackDepth(sessionKey));
+
     // Initial render uses the agent's seed (instant). Routed through the
     // paint-floor coalescer as a leading-edge render sentinel so it shares the
     // single send chokepoint (a render supersedes any queued field patch for
@@ -653,7 +681,7 @@ export function createGlassesUiToolHandler(deps) {
     paintFloor.enqueue({
       surfaceId,
       sessionKey,
-      patch: { __render: true, __depth: depth, __spec: validation.spec },
+      patch: { __render: true, __depth: wireDepth, __spec: validation.spec },
     });
 
     // Live-refresh path: kick off the cron in parallel. A `patch` onto an
@@ -776,6 +804,21 @@ export function createGlassesUiToolHandler(deps) {
         guard += 1;
       }
     }
+    if (
+      popCount === 0 &&
+      storeDepthBefore > 1 &&
+      surfaceStore.topSurfaceId(sessionKey) === ev.surfaceId
+    ) {
+      // Surface-match fallback (B6): a Back event reports the surfaceId being
+      // backed OUT OF — the store top. If the depth comparison said no-op
+      // (drifted ordinals from an older client, or any depth desync) but the
+      // reported surface IS the top with a parent beneath, pop exactly one
+      // level. Push events carry the PARENT surfaceId — never the top after a
+      // push — so this cannot misfire on a push report; and a duplicate Back
+      // delivery is idempotent (after the pop the top no longer matches).
+      resumedParent = surfaceStore.popBack(sessionKey);
+      popCount += 1;
+    }
     // Push (newDepth > lastDepth) is already reflected in the store by the
     // agent's push render (applyRender), so it is intentionally a no-op here.
     emitLifecycle("nav_reconcile", "debug", {
@@ -791,19 +834,25 @@ export function createGlassesUiToolHandler(deps) {
     navDepthBySession.set(sessionKey, newDepth);
   }
 
+  // Stop crons, resolve pending calls with `outcome`, clear the session stack.
+  // Resolve pending + delete entries FIRST (so pending calls settle with
+  // `outcome`), THEN clear the per-session stack. exit() deletes entries
+  // without resolving, so it must NOT run before the drain or the pending
+  // promises would hang. Shared by the public drainSession (agent_end /
+  // disconnect) and the stale-stack reap in runDynamicUi (B3).
+  function reapSession(sessionKey, outcome) {
+    cronEngine.stopAllForSession(sessionKey, outcome);
+    const reaped = surfaceStore.drainSession(sessionKey, outcome);
+    surfaceStore.exit(sessionKey); // clear the stack (crons already stopped)
+    navDepthBySession.delete(sessionKey); // drop stale nav depth (stack is now 0)
+    return reaped;
+  }
+
   return {
     runDynamicUi,
     handleNavEvent,
     drainSession(sessionKey, outcome) {
-      cronEngine.stopAllForSession(sessionKey, outcome);
-      // Resolve pending + delete entries FIRST (so pending calls settle with
-      // `outcome`), THEN clear the per-session stack. exit() deletes entries
-      // without resolving, so it must NOT run before the drain or the pending
-      // promises would hang.
-      const reaped = surfaceStore.drainSession(sessionKey, outcome);
-      surfaceStore.exit(sessionKey); // clear the stack (crons already stopped)
-      navDepthBySession.delete(sessionKey); // drop stale nav depth (stack is now 0)
-      return reaped;
+      return reapSession(sessionKey, outcome);
     },
     drainAll(outcome) {
       cronEngine.stopAll(outcome);
@@ -858,6 +907,13 @@ export const GLASSES_UI_TOOL_DESCRIPTION = [
   "exit-to-chat policy, the {{path|filter}} template + per-item {label,body}",
   "reference, and worked examples (including a live system-stats",
   "list_with_details surface). Keep this description lean; depth lives in the skill.",
+  "",
+  "After the call resolves, your NEXT output decides the glasses: another",
+  "render_glasses_ui replaces the surface (drill-down / next step); a short text",
+  "reply hands the screen back to chat (the surface disappears); a silent run-end",
+  "leaves the surface up until the user dismisses it. A \"back\" result means the",
+  "user wants to revise their previous answer — re-render it or pivot; after a",
+  "\"selected\" result, follow up with another render or a brief one-line ack.",
 ].join("\n");
 
 // Shared per-session depth counter. OpenClaw loads the plugin's register(api)
@@ -1031,10 +1087,28 @@ export function registerGlassesUiTool(api, service) {
   // Reconcile client nav-events with the SINGLE store stack (Task 16). On pop
   // the client reports the surfaceId now back on top + the post-pop depth; the
   // store knows it. The relay frame carries no sessionKey, so resolve it from
-  // the surface's store entry (sessionForSurface), falling back to "main".
+  // the surface's store entry (sessionForSurface). Every plugin-load context
+  // registers one of these handlers on the SHARED relay, so each nav-event
+  // fans out to N contexts but at most one context's store knows the surface —
+  // a context that cannot resolve it must NO-OP. (The old "main" fallback made
+  // the sibling contexts reconcile an empty store carrying stale cross-session
+  // lastDepth: the 3-4x duplicate nav_reconcile on hardware, bug B2.)
   if (typeof service.onGlassesUiNavEvent === "function") {
     service.onGlassesUiNavEvent((ev) => {
-      const sessionKey = handler.sessionForSurface(ev.surfaceId) || "main";
+      const sessionKey = handler.sessionForSurface(ev.surfaceId);
+      if (!sessionKey) {
+        try {
+          if (typeof service.emitGlassesUiLifecycle === "function") {
+            service.emitGlassesUiLifecycle("nav_event_skipped_foreign_surface", "debug", {
+              evSurfaceId: ev.surfaceId,
+              evDepth: ev.depth,
+            });
+          }
+        } catch (_) {
+          // observability must never break the nav path
+        }
+        return;
+      }
       handler.handleNavEvent(sessionKey, ev);
     });
   }

package/dist/tools/session-title-tool.js

@@ -51,21 +51,12 @@ function isEvenAiDedicatedKey(sessionKey) {
 }
 
 function gateReason(sessionKey, deps) {
-  if (typeof deps.isSessionUserLocked === "function" && deps.isSessionUserLocked(sessionKey)) {
-    return "session_user_locked";
-  }
-  if (
-    typeof deps.isNeuralSessionNamesEnabled === "function" &&
-    !deps.isNeuralSessionNamesEnabled(sessionKey)
-  ) {
-    return "feature_disabled";
-  }
-  // Hard guard against the agent titling a session before the user has sent
-  // their first real message. The synthetic session-starter prompt the agent
-  // sees on /new + the proactive prompt-hook nudge can otherwise tempt the
-  // model into titling from a non-user input (observed: titles like "New
-  // session"). Real user sends are recorded via dispatchOcuClawUserSend ->
-  // sessionService.recordFirstSentUserMessage; the synthetic starter never is.
+  // Explicit-rename-only: the Neural Session Names toggle governs AUTOMATIC
+  // titling (the distiller), not user-requested renames, so feature_disabled is
+  // gone. session_user_locked is gone too — a user who already named a session
+  // must be able to rename it again (the lock only blocks the distiller).
+  // The structural no_active_session / EvenAI-renamable guards live in the
+  // handler body. Only the no-user-message guard remains here.
   if (
     typeof deps.hasRecordedUserMessage === "function" &&
     !deps.hasRecordedUserMessage(sessionKey)
@@ -104,7 +95,9 @@ export function createSessionTitleToolHandler(deps) {
       err.code = blockedReason;
       throw err;
     }
-    const result = await deps.setSessionTitle(sessionKey, validation.spec.title);
+    const result = await deps.setSessionTitle(sessionKey, validation.spec.title, {
+      origin: "user_tool",
+    });
     if (result && result.ok === false) {
       const err = new Error(`${result.code}: ${result.message || "set rejected"}`);
       err.code = result.code;
@@ -115,60 +108,15 @@ export function createSessionTitleToolHandler(deps) {
   return { setSessionTitle };
 }
 
-const TOOL_DESCRIPTION = [
-  "Set a short title for the current chat session (shown in the user's glasses session list).",
+export const TOOL_DESCRIPTION = [
+  "Rename the current chat session (shown in the user's glasses session list).",
   "",
-  "When: first user turn that names any concrete topic — call eagerly. Later, only when the topic has clearly shifted. Skip greetings, acknowledgments, and no-topic messages.",
+  "Call ONLY when the user explicitly asks to rename or retitle the session.",
+  "Automatic titling is handled elsewhere — do not call this proactively.",
   "",
-  "Title: 2-5 word noun phrase, ≤55 chars, no trailing punctuation or surrounding quotes.",
-  "",
-  "Do not announce the rename unless the user explicitly asked to retitle.",
+  "Title: 2-5 word noun phrase, ≤55 chars, no trailing punctuation or quotes.",
 ].join("\n");
 
-export function createSessionTitlePromptHook(deps) {
-  return function sessionTitleBeforePromptBuild(_event, ctx) {
-    const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
-    if (!sessionKey) return undefined;
-    const title = typeof deps.getSessionTitle === "function" ? deps.getSessionTitle(sessionKey) : null;
-    const userLocked =
-      typeof deps.isSessionUserLocked === "function" && deps.isSessionUserLocked(sessionKey);
-    const featureEnabled =
-      typeof deps.isNeuralSessionNamesEnabled === "function"
-        ? deps.isNeuralSessionNamesEnabled(sessionKey)
-        : true;
-
-    const fragments = [];
-    if (title) {
-      fragments.push(`Current session title: "${title}".`);
-    }
-    if (userLocked) {
-      fragments.push(
-        "The user has set a custom title; do not call set_session_title.",
-      );
-    } else if (!featureEnabled) {
-      fragments.push(
-        "Neural Topic Distiller is disabled; do not call set_session_title.",
-      );
-    } else if (title) {
-      fragments.push(
-        "Call set_session_title only if the topic has clearly shifted.",
-      );
-    } else {
-      const hasUserMessage =
-        typeof deps.hasRecordedUserMessage !== "function" ||
-        deps.hasRecordedUserMessage(sessionKey);
-      if (hasUserMessage) {
-        fragments.push(
-          "No session title is set yet. Call set_session_title now if the user's latest message names any concrete topic.",
-        );
-      }
-    }
-
-    if (fragments.length === 0) return undefined;
-    return { appendSystemContext: fragments.join(" ") };
-  };
-}
-
 export function registerSessionTitleTool(api, service) {
   if (!api || typeof api.registerTool !== "function") {
     throw new Error("registerSessionTitleTool requires api.registerTool");
@@ -196,14 +144,4 @@ export function registerSessionTitleTool(api, service) {
       };
     },
   });
-
-  if (typeof api.on === "function") {
-    const hook = createSessionTitlePromptHook({
-      getSessionTitle: (sessionKey) => service.getSessionTitle(sessionKey),
-      isSessionUserLocked: (sessionKey) => service.isSessionUserLocked(sessionKey),
-      isNeuralSessionNamesEnabled: (sessionKey) => service.isNeuralSessionNamesEnabled(sessionKey),
-      hasRecordedUserMessage: (sessionKey) => service.hasRecordedUserMessage(sessionKey),
-    });
-    api.on("before_prompt_build", hook);
-  }
 }

package/dist/tools/session-title-tool.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSessionTitleToolHandler, TOOL_DESCRIPTION } from "./session-title-tool.ts";
+
+function deps(over = {}) {
+  const calls = [];
+  return {
+    calls,
+    peekSessionKey: () => "ocuclaw:123",
+    setSessionTitle: (k, t, o) => { calls.push({ k, t, o }); return { ok: true }; },
+    ...over,
+  };
+}
+
+test("description is explicit-rename-only", () => {
+  assert.match(TOOL_DESCRIPTION, /explicitly asks to rename|user explicitly/i);
+});
+
+test("explicit rename passes origin user_tool", async () => {
+  const d = deps();
+  const h = createSessionTitleToolHandler(d);
+  await h.setSessionTitle({ title: "Trip Planning" });
+  assert.equal(d.calls[0].o.origin, "user_tool");
+});
+
+test("a user-locked session can STILL be renamed via the tool", async () => {
+  const d = deps({
+    setSessionTitle: (k, t, o) => {
+      // service-layer would allow user_tool over a lock; tool must not pre-block
+      return { ok: true };
+    },
+  });
+  const h = createSessionTitleToolHandler(d);
+  const r = await h.setSessionTitle({ title: "New Name" });
+  assert.deepEqual(r, { ok: true });
+});
+
+test("feature-disabled does NOT block an explicit rename", async () => {
+  const d = deps({ isNeuralSessionNamesEnabled: () => false });
+  const h = createSessionTitleToolHandler(d);
+  const r = await h.setSessionTitle({ title: "Anything" });
+  assert.deepEqual(r, { ok: true });
+});
+
+test("still rejects an empty title", async () => {
+  const h = createSessionTitleToolHandler(deps());
+  await assert.rejects(() => h.setSessionTitle({ title: "   " }), /title_empty/);
+});
+
+test("still rejects when no active session", async () => {
+  const h = createSessionTitleToolHandler(deps({ peekSessionKey: () => "" }));
+  await assert.rejects(() => h.setSessionTitle({ title: "X" }), /no_active_session/);
+});

package/dist/version.js

@@ -1,2 +1,2 @@
-export const PLUGIN_VERSION = "1.3.1";
-export const REQUIRES_CLIENT_VERSION = "1.3.1";
+export const PLUGIN_VERSION = "1.3.2";
+export const REQUIRES_CLIENT_VERSION = "1.3.2";

package/openclaw.plugin.json

@@ -43,6 +43,11 @@
       "help": "Optional extra system prompt appended to Even AI runs only.",
       "advanced": true
     },
+    "sessionTitleModel": {
+      "label": "Session-title model",
+      "help": "Optional model override (\"provider/model\") for the background session-title distiller. Leave blank to use your normal model.",
+      "advanced": true
+    },
     "evenAiRoutingMode": {
       "label": "Even AI routing mode",
       "help": "active = current session; background = dedicated background session; background_new = fresh background session per request.",
@@ -226,6 +231,10 @@
         "maximum": 8000,
         "default": 5000,
         "description": "How long (ms) a fresh agent summary stays preferred over a tool label in the glasses activity status. Clamped 3000-8000."
+      },
+      "sessionTitleModel": {
+        "type": "string",
+        "description": "Optional model override (\"provider/model\") for the background session-title distiller. When absent, the user's normal model is used."
       }
     },
     "if": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ocuclaw",
-  "version": "1.3.1",
-  "requiresClientVersion": "1.3.1",
+  "version": "1.3.2",
+  "requiresClientVersion": "1.3.2",
   "description": "OcuClaw for Even Realities G2 smart glasses.",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,6 +40,7 @@
   },
   "scripts": {
     "build": "node ./scripts/build.mjs",
-    "prepare": "node ./scripts/build.mjs"
+    "prepare": "node ./scripts/build.mjs",
+    "test:unit": "node --import ./scripts/test-loader.mjs --test --test-force-exit \"src/**/*.test.ts\""
   }
 }

package/skills/glasses-ui/SKILL.md

@@ -8,6 +8,13 @@ user-invocable: false
 
 `render_glasses_ui` paints an interactive surface on the user's Even G2 HUD instead of a text reply. The call blocks until the user selects, dismisses, or backs out. This skill is the source of truth for **authoring** surfaces; the tool description is deliberately lean.
 
+## Before you author: is the tool loaded?
+
+`render_glasses_ui` is a plugin tool, and depending on the host runtime it may not sit in your initial tool list:
+
+1. **Not listed but searchable** — some runtimes (e.g. the Codex harness) defer OpenClaw dynamic tools behind tool search. Search your available/deferred tools for `render_glasses_ui` (it surfaces under the `openclaw` namespace), load it, and proceed.
+2. **Not findable at all** — the host's tool policy is filtering plugin tools. Newer OpenClaw versions (2026.6+) default `tools.profile` to `"coding"`, a base allowlist that strips plugin-owned tools; skills are not policy-filtered, which is why you can read this guide for a tool you cannot call. Don't improvise a workaround: tell the user to run `openclaw config set tools.alsoAllow '["ocuclaw"]' --strict-json` (merging `"ocuclaw"` into any existing `alsoAllow` list rather than overwriting) and restart the gateway, then try again.
+
 ## Surface kinds
 
 | kind | use it for | caps |