ocuclaw 1.3.3 → 1.3.4

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

@@ -1,15 +1,11 @@
-// Glasses UI tool: lets the agent paint an interactive surface on the user's
-// Even G2 glasses HUD instead of replying with text. Plain JSON Schema is used
-// for the tool parameters because the plugin build is a regex-based emitter
-// that has no access to typebox at runtime; OpenClaw consumes JSON Schema
-// directly anyway.
-
 import { validateTemplate } from "./glasses-ui-template.js";
 import { createGlassesUiCronEngine } from "./glasses-ui-cron.js";
 import {
   executeHttpRecipe,
   executeLlmRecipe,
   executeSystemStatsRecipe,
+  normalizeHttpAllowHosts,
+  isHttpHostAllowed,
 } from "./glasses-ui-recipes.js";
 import { createPendingRenderMap, createSurfaceStore, isTerminalOutcome, normalizeGlassesSessionKey } from "./glasses-ui-surfaces.js";
 import { createGlassesWakeController } from "./glasses-ui-wake.js";
@@ -22,14 +18,6 @@ import {
   buildOneOfBranches,
 } from "./glasses-ui-descriptors.js";
 
-// Re-exported so existing consumers/tests that import these from this module
-// keep working after the extractions (spec §Changes A — extraction is behavior-
-// preserving). Canonical homes: createPendingRenderMap/createSurfaceStore ->
-// ./glasses-ui-surfaces.js, GLASSES_UI_LIMITS -> ./glasses-ui-limits.js. Kept as
-// ONE bare `export {}` statement because the CJS emitter (scripts/build.mjs)
-// strips only the first such statement — a second would survive into the .cjs
-// as invalid syntax. createPendingRenderMap is the Phase-1 alias of the single
-// createSurfaceStore (see glasses-ui-surfaces.ts).
 export { createPendingRenderMap, createSurfaceStore, GLASSES_UI_LIMITS };
 
 export const GLASSES_UI_REFRESH_LIMITS = {
@@ -53,21 +41,15 @@ export const GLASSES_UI_REFRESH_LIMITS = {
   maxOutputTokensMin: 16,
   maxOutputTokensMax: 1000,
   maxOutputTokensDefault: 200,
-  // Cap on a single template string (body or one items entry). The
-  // substituted OUTPUT is clamped to bodyMax/itemMax at runtime, but a huge
-  // template itself is wasted work — 4KB is generous for any HUD line.
+
   templateMaxChars: 4096,
-  // L0' system-stats: bounds on the optional CPU-sample window (ms).
+
   systemStatsWindowMsMin: 50,
   systemStatsWindowMsMax: 1000,
 };
 
 const ON_ERROR_VALUES = new Set(["keep_last", "show_error", "stop"]);
 
-// The effective per-tick interval floor is the larger of the tier minimum and
-// the paint-floor coalescer's cadence (Spike D, 150ms) — no tick may schedule
-// faster than the glass can paint. Today every tier min already exceeds 150ms,
-// so this only guards the floor from ever relaxing below the coalescer cadence.
 function effectiveIntervalFloorMs(tierMinMs) {
   return Math.max(tierMinMs, DEFAULT_PAINT_FLOOR_MS);
 }
@@ -89,14 +71,11 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
   if (kind !== "http" && kind !== "llm" && kind !== "system-stats") {
     return { ok: false, code: "refresh_invalid_recipe", message: `recipe.kind must be http/llm/system-stats, got ${JSON.stringify(kind)}` };
   }
-  // Sanitize the recipe — clamp/reject agent-supplied timeoutMs / outputCapBytes
-  // / maxOutputTokens to declared bounds, copy known fields only. The returned
-  // `refresh.recipe` is this sanitized version, never the raw input — so the
-  // executors at run-time see vetted values.
+
   const sanitizedRecipe = { kind };
   const bounded = (raw, min, max) => {
     if (!Number.isFinite(raw)) return null;
-    if (raw < min || raw > max) return undefined; // signal out-of-range
+    if (raw < min || raw > max) return undefined;
     return Math.floor(raw);
   };
   if (kind === "http") {
@@ -104,6 +83,13 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     if (typeof recipe.url !== "string" || !recipe.url.trim()) {
       return { ok: false, code: "refresh_invalid_recipe", message: "http recipe requires url (non-empty string)" };
     }
+
+    const allowHosts = normalizeHttpAllowHosts(cfg.httpAllowHosts);
+    let recipeHost = "";
+    try { recipeHost = new URL(recipe.url).hostname; } catch (_) {}
+    if (!isHttpHostAllowed(recipeHost, allowHosts)) {
+      return { ok: false, code: "refresh_host_not_allowed", message: `http recipe host not in allowlist: ${recipeHost || recipe.url.trim()}` };
+    }
     sanitizedRecipe.url = recipe.url;
     if (typeof recipe.method === "string") sanitizedRecipe.method = recipe.method;
     if (recipe.headers && typeof recipe.headers === "object") sanitizedRecipe.headers = recipe.headers;
@@ -136,10 +122,7 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
       if (v !== null) sanitizedRecipe.maxOutputTokens = v;
     }
   } else if (kind === "system-stats") {
-    // Built-in tier: host RAM/CPU via the in-process structured reader. NOT gated
-    // by httpEnabled/llmEnabled — it touches no network, no shell, no
-    // model. Only the master `enabled` switch (checked above) governs it. Do NOT
-    // add a cfg.*Enabled gate here (intentional — Phase 3 design).
+
     if (recipe.sampleWindowMs !== undefined) {
       const v = bounded(recipe.sampleWindowMs, GLASSES_UI_REFRESH_LIMITS.systemStatsWindowMsMin, GLASSES_UI_REFRESH_LIMITS.systemStatsWindowMsMax);
       if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `system-stats.sampleWindowMs ${recipe.sampleWindowMs} out of bounds [${GLASSES_UI_REFRESH_LIMITS.systemStatsWindowMsMin}..${GLASSES_UI_REFRESH_LIMITS.systemStatsWindowMsMax}]` };
@@ -147,7 +130,6 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     }
   }
 
-  // Interval bounds.
   const intervalMs = refresh.intervalMs;
   if (!Number.isFinite(intervalMs)) {
     return { ok: false, code: "refresh_invalid_recipe", message: "refresh.intervalMs is required" };
@@ -168,7 +150,6 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     return { ok: false, code: "refresh_interval_too_high", message: `intervalMs ${intervalMs} above max ${GLASSES_UI_REFRESH_LIMITS.intervalMsMax}` };
   }
 
-  // Duration.
   const maxDurationMs = Number.isFinite(refresh.maxDurationMs)
     ? refresh.maxDurationMs
     : GLASSES_UI_REFRESH_LIMITS.maxDurationMsDefault;
@@ -176,13 +157,11 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     return { ok: false, code: "refresh_duration_too_high", message: `maxDurationMs ${maxDurationMs} out of bounds` };
   }
 
-  // onError.
   const onError = typeof refresh.onError === "string" ? refresh.onError : "keep_last";
   if (!ON_ERROR_VALUES.has(onError)) {
     return { ok: false, code: "refresh_invalid_recipe", message: `onError must be keep_last/show_error/stop` };
   }
 
-  // Templates.
   const targets = refresh.targets && typeof refresh.targets === "object" ? refresh.targets : {};
   if (typeof targets.body === "string") {
     if (targets.body.length > GLASSES_UI_REFRESH_LIMITS.templateMaxChars) {
@@ -192,10 +171,7 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     if (!v.ok) return v;
   }
   if (Array.isArray(targets.items)) {
-    // Cap array length — only the first maxItems survive the runtime slice,
-    // so a 100k-entry array would burn CPU substituting templates that are
-    // immediately discarded. Reject (rather than truncate) so the agent gets
-    // clear feedback that it over-supplied.
+
     if (targets.items.length > GLASSES_UI_LIMITS.maxItems) {
       return {
         ok: false,
@@ -212,7 +188,7 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
         const v = validateTemplate(item);
         if (!v.ok) return v;
       } else if (item && typeof item === "object" && !Array.isArray(item)) {
-        // {label, body?} per-item templates (list_with_details detail bodies).
+
         if (typeof item.label !== "string") {
           return { ok: false, code: "refresh_template_invalid", message: `targets.items[${i}].label must be a string template` };
         }
@@ -259,10 +235,6 @@ const updateSchemaForToolParams = {
     "\"push\": stack a new screen; the parent is retained and its cron pauses.",
 };
 
-// Roadmap 6b (§2.6 interaction-window contract). The gateway's dynamic-tool
-// watchdog reads call.arguments.timeoutMs (clamp ceiling 600000ms); this
-// schema entry legitimizes that knob and steers its use. One-shot by design:
-// the listen window is never renewed — the agent re-renders to listen again.
 const timeoutMsSchemaForToolParams = {
   type: "integer",
   minimum: 1000,
@@ -273,7 +245,6 @@ const timeoutMsSchemaForToolParams = {
     "omit for fire-and-forget. Never renewed automatically — re-render to listen again.",
 };
 
-// staleAfterMs reservation (roadmap 6b; annotate-only through the soak).
 const staleAfterMsSchemaForToolParams = {
   type: "integer",
   minimum: 1000,
@@ -291,10 +262,6 @@ export const GLASSES_UI_WINDOW_LIMITS = {
   staleAfterMsMax: staleAfterMsSchemaForToolParams.maximum,
 };
 
-// Cross-kind window fields (like `update`/`refresh`, these live at the tool
-// layer — the kind descriptors rebuild a whitelisted canonical spec, which is
-// also what keeps both fields OFF the wire). Reject (never clamp) so the agent
-// gets explicit feedback instead of a silently different window.
 function validateWindowFields(spec) {
   const out = { ok: true, timeoutMs: undefined, staleAfterMs: undefined };
   if (spec && spec.timeoutMs !== undefined) {
@@ -399,21 +366,13 @@ const refreshSchemaForToolParams = {
   },
 };
 
-// Top-level `properties` lists every field a valid spec may carry across all
-// `kind`s. OpenClaw's Anthropic provider strips `oneOf` when building
-// `input_schema` (it keeps only top-level `properties` + `required`), so
-// without this flat union the model would see `properties: {}` and have to
-// guess the shape from the tool description alone. Per-kind shape constraints
-// are still enforced by `validateGlassesUiSpec` and the JSON Schema `oneOf`
-// below for clients that honor it.
 export const glassesUiParametersSchema = {
   type: "object",
   required: ["kind"],
   properties: {
     kind: {
       type: "string",
-      // Enum derived from the descriptor registry (enum order). Adding a kind
-      // is one descriptor with no edit here (spec §Modularity).
+
       enum: listKindStrings(),
       description:
         "Surface kind. Each kind expects a different items/body shape — see " +
@@ -442,26 +401,15 @@ export const glassesUiParametersSchema = {
         "[{\"label\": \"Monday\", \"body\": \"Cloudy 14C, light rain pm\"}, " +
         "{\"label\": \"Tuesday\", \"body\": \"Sunny 19C\"}]. Up to 20 items.",
     },
-    // refresh must be top-level too — the Anthropic provider strips `oneOf`
-    // (see the block comment above), so a refresh entry that lives only in
-    // the oneOf branches is invisible on that path and the live-refresh
-    // feature becomes unreachable. The per-branch copies below stay for
-    // clients that honor oneOf.
+
     refresh: refreshSchemaForToolParams,
-    // update is the render-vs-current-surface move (patch/replace/push,
-    // default replace). Top-level for the same Anthropic-strips-oneOf reason as
-    // refresh; mirrored into every oneOf branch below.
+
     update: updateSchemaForToolParams,
-    // Window fields (roadmap 6b) — same top-level + per-branch mirroring.
+
     timeoutMs: timeoutMsSchemaForToolParams,
     staleAfterMs: staleAfterMsSchemaForToolParams,
   },
-  // oneOf is assembled from the descriptor registry (one branch per kind, in
-  // enum order). Each branch's `refresh` slot — declared `undefined` in the
-  // descriptor's schemaBranch — is filled here with the shared refresh schema
-  // so the per-branch shape matches today's hand-written one (the tool owns
-  // refreshSchemaForToolParams; the descriptor only declares the slot). `update`
-  // is mirrored into every branch the same way.
+
   oneOf: buildOneOfBranches().map((branch) => ({
     ...branch,
     properties: {
@@ -479,10 +427,7 @@ export function validateGlassesUiSpec(input) {
     return { ok: false, code: "invalid_kind", message: "spec must be an object" };
   }
   const obj = input;
-  // Dispatch by kind STRING through the descriptor registry. "No descriptor for
-  // kind" reproduces today's invalid_kind. Per-kind validation (incl. the
-  // shared title check, which each descriptor runs first) lives in the
-  // descriptor's validateSpec, so behavior is identical to the old switch.
+
   const descriptor = getKindDescriptor(obj.kind);
   if (!descriptor) {
     return {
@@ -498,9 +443,6 @@ export function validateGlassesUiSpec(input) {
 
 import { randomUUID } from "node:crypto";
 
-// Mirror of even-ai-model-hook's session classifier. Inlined to avoid a
-// cross-file CJS dependency (even-ai-model-hook is ESM-only in dist).
-// Keep these constants in sync with even-ai-model-hook.ts.
 const EVEN_AI_THROWAWAY_SESSION_PREFIX = "ocuclaw:even-ai:";
 const EVEN_AI_DEFAULT_DEDICATED_SESSION_KEY = "ocuclaw:even-ai";
 
@@ -522,80 +464,40 @@ export function isEvenAiAgentSession(sessionKey, dedicatedSessionKey) {
   return !!normalizedDedicated && normalized === normalizedDedicated;
 }
 
-// Default timeout when no per-call or per-handler timeout is provided.
-// Bounds the orphan-tool_use corruption window (see Family 2 in the OpenClaw
-// task-runs zombies / orphan tool_use memory): if a render_glasses_ui call
-// stays unresolved this long, the plugin returns { result: "timeout" } so
-// the agent's runtime persists a matching tool_result and the next turn's
-// session replay won't 400 on an unmatched tool_use block.
 export const DEFAULT_RENDER_GLASSES_UI_TIMEOUT_MS = 30 * 60 * 1000;
 
-// The gateway's dynamic-tool watchdog default (resolveDynamicToolCallTimeoutMs
-// in the installed 2026.6.1 dist; agent-suppliable via the 6b timeoutMs field,
-// clamped there to <=600000). UNDOCUMENTED upstream — re-audit on any host
-// upgrade (§5c upstream ask (v) tracks getting it documented).
 export const GATEWAY_DYNAMIC_TOOL_DEFAULT_TIMEOUT_MS = 90_000;
 
-// Self-teaching wrap-up payload (roadmap 6c): window_expired is a listen
-// timeout, never an error and never a paint event — the surface stays live.
 const WINDOW_EXPIRED_HINT =
   "The listen window closed; the surface is still live on glass and keeps " +
   "updating. New taps park - re-render this surface (e.g. update:\"patch\") " +
   "to collect them in this run, or end your turn and they ride the next one.";
 
 export function createGlassesUiToolHandler(deps) {
-  // The single live surface store is constructed below (after the cron engine,
-  // which it delegates pause/resume/stop to). There is never a separate pending
-  // map alongside it (spec §Core model — one store).
-  // Short-lived per-surface capture used to read the cron's merged outcome
-  // (ticks{}, lastBody, lastItems, ...extra) when runDynamicUi stops the
-  // cron after a user dismissal (pending already resolved with a user-only
-  // outcome that lacks ticks). Cleared immediately after stop returns.
+
   const capturedCronOutcome = new Map();
 
-  // Breadcrumb title clip (roadmap 7a). The DynamicUiScreen title band is
-  // BODY_W = MARKER_X = 548px on the client and the client does NOT clip
-  // DynamicUiScreen titles — so the plugin must pre-clip the composed
-  // breadcrumb or it overflows the band. Conservative pixel-safe char clip
-  // (NOT font_measure: the plugin runtime has no require of
-  // vendor/pretext-patched/dist/font_measure.js, and a cross-package require
-  // from the installed plugin is fragile). Assume a worst-case 20px per char
-  // (the probed uniform full-cell ceiling) so floor(budget/20) chars never
-  // overflow — it over-clips slightly, never under. 540 = 548 minus an 8px
-  // safety margin.
   const TITLE_BUDGET_PX = 540;
-  // clipBreadcrumb keeps the rightmost (current) segment and drops
-  // oldest-ancestor-first until the rejoined "A › B › C" fits the char budget;
-  // if a single segment still overflows, it hard-truncates that last segment.
-  // reserveText is kept defaulted-empty for future suffix callers (7a has
-  // none — the (stale) suffix was dropped per Path D).
+
   function clipBreadcrumb(s, reserveText = "") {
     if (typeof s !== "string" || s.length === 0) return s;
     const charBudget = Math.floor((TITLE_BUDGET_PX - reserveText.length * 20) / 20);
     if (charBudget <= 0) return "";
     if (s.length <= charBudget) return s;
     const segments = s.split(" › ");
-    // Drop leading (oldest-ancestor) segments until the rejoin fits, always
-    // keeping at least the rightmost segment.
+
     while (segments.length > 1 && segments.join(" › ").length > charBudget) {
       segments.shift();
     }
     const joined = segments.join(" › ");
     if (joined.length <= charBudget) return joined;
-    // One segment remains and still overflows → hard-truncate it to the budget.
+
     return joined.slice(0, charBudget);
   }
 
-  // Marker-only emit on the content-less presence transitions (roadmap 7a). A
-  // live resolve, a parked tap, a window_expired wrap-up, and a popBack resume
-  // change the surface's derived presence marker without changing its content —
-  // so ship a marker-only surface_update (no title/body/items) through the same
-  // paint-floor chokepoint. Gated to the session's TOP surface so a transition
-  // on a backgrounded surface stays quiet; an off-enum/absent marker is a no-op.
-  // (surfaceStore/paintFloor are defined further down but only read at call time.)
   function emitMarker(sessionKey, surfaceId) {
     if (!surfaceId) return;
-    if (surfaceStore.topSurfaceId(sessionKey) !== surfaceId) return; // only the active surface
+    if (surfaceStore.topSurfaceId(sessionKey) !== surfaceId) return;
     const marker = surfaceStore.markerFor(surfaceId);
     if (!marker) return;
     paintFloor.enqueue({ surfaceId, sessionKey, patch: { marker } });
@@ -606,14 +508,6 @@ export function createGlassesUiToolHandler(deps) {
       ? deps.newSurfaceId
       : () => `ui-${randomUUID().slice(0, 8)}`;
 
-  // Permanent glasses.lifecycle observability (nav reconcile + cron pause/
-  // resume/tick). No-op when the dep is absent (tests) or the debug category is
-  // disabled. See docs/superpowers/findings/2026-05-30-glasses-ui-phase4-hardware.md.
-  // Every event is stamped with the owning store's id: OpenClaw loads the
-  // plugin register() in multiple isolated contexts, each with its own handler
-  // + store, and only the storeId makes a cross-context divergence visible in
-  // traces (drift #3, 2026-06-12: a queued wake run's collect rendered against
-  // a sibling context's empty store and minted a phantom root).
   const storeId =
     typeof deps.storeId === "string" && deps.storeId
       ? deps.storeId
@@ -623,8 +517,6 @@ export function createGlassesUiToolHandler(deps) {
   const emitLifecycle = (event, severity, data) =>
     baseEmitLifecycle(event, severity, { storeId, ...(data || {}) });
 
-  // Resolve the handler-wide default timeout. Per-call timeouts may still
-  // override this via params.timeoutMs.
   function resolveHandlerTimeoutMs() {
     if (!deps || deps.timeoutMs === undefined) return DEFAULT_RENDER_GLASSES_UI_TIMEOUT_MS;
     if (typeof deps.timeoutMs === "function") {
@@ -634,15 +526,8 @@ export function createGlassesUiToolHandler(deps) {
     return Number.isFinite(deps.timeoutMs) ? deps.timeoutMs : DEFAULT_RENDER_GLASSES_UI_TIMEOUT_MS;
   }
 
-  // The single plugin->glass send chokepoint (Spike D). EVERY send — the
-  // initial render frame and every cron surface_update — routes through this
-  // trailing-edge coalescer so bursts collapse to ≤1 frame per 150ms and shed
-  // under BLE backpressure. A { __render } sentinel is a full container
-  // rebuild; a plain field patch is a surface_update.
   const paintFloor = createPaintFloorCoalescer({
-    // Tests may inject paintFloorMs: 0 to disable coalescing (every enqueue is
-    // a leading-edge send) so synchronous send-ordering assertions hold;
-    // production uses the 150ms Spike-D cadence.
+
     paintFloorMs: Number.isFinite(deps.paintFloorMs) ? deps.paintFloorMs : DEFAULT_PAINT_FLOOR_MS,
     send: ({ surfaceId, sessionKey, patch }) => {
       if (patch && patch.__render) {
@@ -658,7 +543,11 @@ export function createGlassesUiToolHandler(deps) {
     emitLifecycle,
     monotonicNowMs: () => performance.now(),
     executeRecipe: async (recipe, ctx) => {
-      if (recipe.kind === "http") return executeHttpRecipe(recipe);
+      if (recipe.kind === "http") {
+
+        const cfg = deps.getGlassesUiLiveConfig ? deps.getGlassesUiLiveConfig() : {};
+        return executeHttpRecipe(recipe, { allowHosts: normalizeHttpAllowHosts(cfg.httpAllowHosts) });
+      }
       if (recipe.kind === "system-stats") return executeSystemStatsRecipe(recipe);
       if (recipe.kind === "llm") return executeLlmRecipe(recipe, ctx);
       return { error: `unknown recipe kind: ${recipe.kind}` };
@@ -686,22 +575,14 @@ export function createGlassesUiToolHandler(deps) {
     },
   });
 
-  // The SINGLE live surface store (spec §Core model). Constructed after the
-  // cron engine so it can delegate pause/resume/stop; id minting reuses the
-  // handler's minter. Replaces the Phase-1 pending map — never a second store.
   const surfaceStore = createSurfaceStore({
     storeId,
     emitLifecycle,
-    // Injectable clock for parked-event age math (queuedAtMs/parkedForMs/stale).
+
     now: typeof deps.now === "function" ? deps.now : undefined,
     pauseCron: (id) => cronEngine.pause(id),
     resumeCron: (id) => cronEngine.resume(id),
-    // stopCron fires on every surface teardown (replace swap, popBack child,
-    // exit, drain). Dispose the paint-floor coalescer entry too so an armed
-    // trailing flush can't paint a stale surface_update onto the now-visible
-    // 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, opts) => {
       cronEngine.stop(id, { result: "preempted" }, opts);
       paintFloor.dispose(id);
@@ -709,12 +590,6 @@ export function createGlassesUiToolHandler(deps) {
     mintSurfaceId: newSurfaceId,
   });
 
-  // Tap-to-wake (roadmap 6f): a parked GESTURE nonterminal buys one agent
-  // turn via the relay's gateway client. The controller owns the arbitration
-  // (origin gate, voice-absorbs-wake, in-flight coalescing, cooldown, retry/
-  // outbox); the lane and busy signal are injected from the relay facade by
-  // registerGlassesUiTool. Without a lane (legacy host) the controller
-  // no-ops and parked taps keep their collect-on-next-render semantics.
   const wakeController = createGlassesWakeController({
     dispatchWake: typeof deps.dispatchWake === "function" ? deps.dispatchWake : null,
     isAgentTurnBusy: typeof deps.isAgentTurnBusy === "function" ? deps.isAgentTurnBusy : () => false,
@@ -723,12 +598,6 @@ export function createGlassesUiToolHandler(deps) {
     wakeCooldownMs: deps.wakeCooldownMs,
   });
 
-  // Voicemail (roadmap 7b): parked events whose wake was unavailable/failed
-  // (wake outbox) or whose surface was destructively reaped (dead-letter)
-  // are delivered to the session's NEXT genuine turn as a refs-only
-  // system-context fragment. Lives on the handler so the shared-handler
-  // hoist gives every load context's before_prompt_build hook the same
-  // pending state (first hook to fire drains; duplicates see nothing).
   const voicemail = createGlassesVoicemail({
     now: typeof deps.now === "function" ? deps.now : Date.now,
     ttlMs: deps.voicemailTtlMs,
@@ -739,9 +608,7 @@ export function createGlassesUiToolHandler(deps) {
 
   deps.relay.onGlassesUiResult((msg) => {
     if (!msg || typeof msg.surfaceId !== "string" || !msg.outcome) return;
-    // Provenance stamp at the client boundary (roadmap 6b): everything arriving
-    // on this channel is a wearer gesture. The actor slot is present-and-
-    // ignorable today (policy stays single-wearer at launch).
+
     const outcome = {
       ...msg.outcome,
       origin: typeof msg.outcome.origin === "string" ? msg.outcome.origin : "gesture",
@@ -749,9 +616,7 @@ export function createGlassesUiToolHandler(deps) {
     };
     const terminal = isTerminalOutcome(outcome);
     if (terminal && cronEngine.isActive(msg.surfaceId)) {
-      // Terminal with a live cron: stop the cron, merging its tick stats into
-      // the outcome via capturedCronOutcome, then settle the in-flight call (or
-      // queue the terminal so the next render discards-for-exit).
+
       let merged = outcome;
       capturedCronOutcome.set(msg.surfaceId, (cronOutcome) => { merged = cronOutcome; });
       cronEngine.stop(msg.surfaceId, outcome);
@@ -761,25 +626,17 @@ export function createGlassesUiToolHandler(deps) {
       }
       return;
     }
-    // Nonterminal (selected/back): settle the call if one is pending; otherwise
-    // the surface is in visible_awaiting_agent — queue last-wins so the agent's
-    // next render delivers the latest event (spec §Tool-call accounting). A
-    // terminal with no live cron also lands here (queue → next render tears down).
-    // Capture the session up front: a live resolve moves the surface to
-    // visible_awaiting_agent (●→◌); a parked tap queues (◌). Both are
-    // content-less marker transitions on the active surface (roadmap 7a).
+
     const sessionKey = surfaceStore.sessionForSurface(msg.surfaceId);
     if (surfaceStore.resolve(msg.surfaceId, outcome)) {
-      // LIVE tap on the open window → the agent is now responding → ●→◌.
+
       emitMarker(sessionKey, msg.surfaceId);
     } else {
       const receipt = surfaceStore.queueEvent(msg.surfaceId, outcome, {
         origin: outcome.origin,
         actor: outcome.actor,
       });
-      // Wake only on a REAL parked gesture: a truthy NONTERMINAL receipt
-      // (terminal latches carry no actionable intent — the next render tears
-      // down anyway; a latched-exit drop returns falsy and must never wake).
+
       if (receipt && !receipt.kind) {
         wakeController.onParkedGesture({
           sessionKey: surfaceStore.sessionForSurface(msg.surfaceId),
@@ -790,7 +647,7 @@ export function createGlassesUiToolHandler(deps) {
           origin: outcome.origin,
         });
       }
-      // PARK → ◌: the queued tap (events.length≥1) derives inflight.
+
       emitMarker(sessionKey, msg.surfaceId);
     }
   });
@@ -807,9 +664,7 @@ export function createGlassesUiToolHandler(deps) {
       err.code = validation.code;
       throw err;
     }
-    // Normalize at the handler boundary so the canonical agent ctx form and
-    // the stripped relay form address the same session everywhere downstream
-    // (store, nav-depth map, cron sessionKey, wake refs, lifecycle events).
+
     const sessionKey = normalizeGlassesSessionKey(
       typeof params.sessionKey === "string" && params.sessionKey.trim()
         ? params.sessionKey.trim()
@@ -835,9 +690,6 @@ export function createGlassesUiToolHandler(deps) {
       refreshValidated = v.refresh;
     }
 
-    // Cross-kind window fields (roadmap 6b). Validated here — the kind
-    // descriptors rebuild a whitelisted canonical spec, so neither field can
-    // reach the wire; staleAfterMs is handed to the store per render.
     const windowFields = validateWindowFields(params.spec);
     if (!windowFields.ok) {
       emitLifecycle("render_rejected", "warn", {
@@ -850,24 +702,12 @@ export function createGlassesUiToolHandler(deps) {
       throw err;
     }
 
-    // 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" });
@@ -877,19 +717,14 @@ export function createGlassesUiToolHandler(deps) {
         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
-    // first render mints a root. This is the single place a surfaceId is bound.
+
     const stackDepthBeforeAttach = surfaceStore.stackDepth(sessionKey);
     const applied = surfaceStore.applyRender(sessionKey, {
       update,
       kind: validation.spec.kind,
     });
     const surfaceId = applied.surfaceId;
-    // Attach-path observability: requestedUpdate "patch"/"replace" with mode
-    // "root" means a collect render did NOT find the surface it references —
-    // the drift-#3 phantom-root signature. Permanent tripwire.
+
     emitLifecycle("surface_attach", "debug", {
       surfaceId,
       sessionKey,
@@ -902,68 +737,34 @@ export function createGlassesUiToolHandler(deps) {
       staleAfterMs: windowFields.staleAfterMs,
       title: typeof validation.spec.title === "string" ? validation.spec.title : undefined,
     });
-    // Re-attach flush (last-wins queue / latched exit): only for a patch/replace
-    // onto an already-attached surface (the visible_awaiting_agent window can
-    // only exist on a surface that previously resolved a call). A fresh
-    // root/push has an empty queue and stays visible_pending. onReattached
-    // delivers any queued nonterminal against the call we just established, or —
-    // if an exit was latched — returns "discarded_for_exit" so this render is
-    // dropped and the surface tears down (spec §Tool-call accounting). This is
-    // move-independent: replace (the schema default) carries the prior entry's
-    // latched exit / queued event forward (Task 8 makeEntry).
+
     if (applied.mode === "patch" || applied.mode === "replace") {
       const reattach = surfaceStore.onReattached(surfaceId);
       if (reattach === "discarded_for_exit") {
-        // onReattached already resolved THIS render's pending call with the
-        // latched terminal outcome (so `promise` is settled). Tear down instead
-        // of painting the discarded render.
+
         if (cronEngine.isActive(surfaceId)) cronEngine.stop(surfaceId, { result: "dismissed" });
         surfaceStore.exit(sessionKey);
         return promise;
       }
       if (reattach === "reattached_stale_latch_dropped") {
-        // 6d generation gate: a system-origin terminal (stale cron tick-
-        // summary) queued under a prior call was dropped instead of consuming
-        // this fresh call's window. Observable for ride forensics.
+
         emitLifecycle("stale_cron_summary_dropped", "debug", { surfaceId, sessionKey });
       }
     }
 
-    // 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
-    // this surface; see glasses-ui-paint-floor mergePatch).
-    // Compose the depth breadcrumb into the spec title BEFORE the enqueue
-    // (roadmap 7a). The store retains each surface's own title at register, so
-    // breadcrumbFor joins the live stack's titles ("System stats › CPU"); the
-    // conservative pixel-safe clip keeps it inside the client's title band.
     const breadcrumb = surfaceStore.breadcrumbFor(sessionKey);
     if (breadcrumb) validation.spec.title = clipBreadcrumb(breadcrumb);
     paintFloor.enqueue({
       surfaceId,
       sessionKey,
-      // __marker rides the render frame: "listening" for a plain render with an
-      // open window, "inflight" for a collect that just delivered a parked tap
-      // via onReattached (the enqueue runs AFTER onReattached, so markerFor
-      // reads true post-collect state).
+
       patch: { __render: true, __depth: wireDepth, __spec: validation.spec, __marker: surfaceStore.markerFor(surfaceId) },
     });
 
-    // Live-refresh path: kick off the cron in parallel. A `patch` onto an
-    // already-ticking surface leaves its cron alone (spec: "cron keeps
-    // ticking"); every other move (replace/push/root) starts a cron for the new
-    // content when this render carries a refresh.
     if (refreshValidated && !(update === "patch" && cronEngine.isActive(surfaceId))) {
-      // Pre-warm the LLM API key cache so tick 1 doesn't see an empty key
-      // and fail the smoke test. For non-LLM recipes this is a no-op. All llm
-      // backends are HTTP API backends that resolve a key via host modelAuth;
-      // a missing key degrades to a graceful recipe_failed on tick 1.
+
       if (refreshValidated.recipe.kind === "llm" && typeof deps.prewarmLlmApiKey === "function") {
         const cfg = deps.getGlassesUiLiveConfig ? deps.getGlassesUiLiveConfig() : {};
         const agentModel =
@@ -977,8 +778,7 @@ export function createGlassesUiToolHandler(deps) {
           try {
             await deps.prewarmLlmApiKey(prewarmModel);
           } catch (_) {
-            // Cache stays empty; tick 1 will fail and the cron resolves
-            // recipe_failed with a useful error from the backend.
+
           }
         }
       }
@@ -997,29 +797,16 @@ export function createGlassesUiToolHandler(deps) {
             )
           : undefined,
         onResolve: (cronOutcome) => {
-          // The cron-produced outcome (with ticks + lastBody) becomes the tool
-          // result. capturedCronOutcome lets the terminal-via-user path read
-          // the merged outcome. Only the cron's OWN terminal outcomes resolve
-          // the pending call here (recipe_failed / timeout / external stop);
-          // user-action results resolve via onGlassesUiResult above.
+
           const capture = capturedCronOutcome.get(surfaceId);
           if (capture) capture(cronOutcome);
           if (isTerminalOutcome(cronOutcome)) {
-            // The cron's OWN terminal is plugin-initiated, not a wearer
-            // gesture — origin "system" (roadmap 6b). A user-action terminal
-            // routed through cron stop carries its gesture stamp in `extra`
-            // and wins the merge, so this fallback never overwrites it.
+
             const stamped = {
               ...cronOutcome,
               origin: typeof cronOutcome.origin === "string" ? cronOutcome.origin : "system",
             };
-            // Settle the in-flight call; if none is pending (the surface is in
-            // visible_awaiting_agent after a nonterminal user action and the
-            // cron then hit its own terminal — recipe_failed / maxDuration
-            // timeout), QUEUE the terminal so the agent's next render's
-            // onReattached returns discarded_for_exit and tears the surface
-            // down. Without this fallback the dead-cron surface would persist.
-            // Symmetric with the onGlassesUiResult terminal path.
+
             if (!surfaceStore.resolve(surfaceId, stamped)) {
               surfaceStore.queueEvent(surfaceId, stamped);
             }
@@ -1034,21 +821,11 @@ export function createGlassesUiToolHandler(deps) {
       deps && typeof deps.clearTimeout === "function" ? deps.clearTimeout : clearTimeout;
     const cleanups = [];
 
-    // 6c wrap-up: a NON-terminal pre-deadline resolve beats the gateway
-    // watchdog (default 90s; agent-suppliable via the 6b timeoutMs schema
-    // field) so the agent gets a useful, self-teaching result instead of a
-    // bare timeout string — and the pending resolver is FREED, so subsequent
-    // taps PARK in the 6a event log. Armed on EVERY render, including cron/
-    // refresh surfaces: pre-6c the only timer here was the terminal janitor
-    // below, gated !refreshValidated, so cron surfaces had no plugin-side
-    // deadline at all and their calls died only at the watchdog cliff.
     const effectiveWindowMs =
       windowFields.timeoutMs !== undefined
         ? windowFields.timeoutMs
         : GATEWAY_DYNAMIC_TOOL_DEFAULT_TIMEOUT_MS;
-    // Fire 2-5s (5% clamped) before the watchdog; for tiny windows where the
-    // margin doesn't fit, fall back to half the window — the wrap-up must
-    // ALWAYS beat the gateway or it delivers into an abandoned call.
+
     const wrapUpMarginMs = Math.min(5000, Math.max(2000, Math.floor(effectiveWindowMs * 0.05)));
     const wrapUpDelayMs = Math.max(effectiveWindowMs - wrapUpMarginMs, Math.floor(effectiveWindowMs / 2));
     const windowExpiredOutcome = (extra) =>
@@ -1070,18 +847,12 @@ export function createGlassesUiToolHandler(deps) {
           windowMs: effectiveWindowMs,
           via: "wrap_up_timer",
         });
-        // ●→○: the window closed with no wearer gesture (origin:"system"), so
-        // awaitingAgentResponse stays false and markerFor derives parked (7a).
+
         emitMarker(sessionKey, surfaceId);
       }
     }, wrapUpDelayMs);
     cleanups.push(() => clearTimeoutFn(wrapUpHandle));
 
-    // 6c abort: the gateway delivers its watchdog/run-abort AbortSignal as
-    // execute()'s third argument — and ALSO aborts it after NORMAL completion,
-    // so releasing here must tolerate abort-after-resolve (surfaceStore.resolve
-    // no-ops once settled). Releasing the orphaned resolver is what turns the
-    // first post-cliff tap from resolved-into-the-void into a parked event.
     const signal = params.signal;
     if (signal && typeof signal.addEventListener === "function") {
       const onAbort = () => {
@@ -1106,43 +877,26 @@ export function createGlassesUiToolHandler(deps) {
       }
     }
 
-    // Terminal janitor (pre-6c behavior, unchanged semantics): bounds the
-    // orphan-tool_use corruption window on non-refresh surfaces via the
-    // 30-min default knob. Cron surfaces keep relying on maxDurationMs.
     const timeoutMs = Number.isFinite(params.timeoutMs)
       ? params.timeoutMs
       : resolveHandlerTimeoutMs();
     if (!refreshValidated && Number.isFinite(timeoutMs) && timeoutMs > 0) {
       const handle = setTimeoutFn(() => {
-        // Resolves only if the entry is still pending; surfaceStore.resolve is a
-        // no-op when the client already produced a real outcome. timeout is
-        // terminal, so it also moves the surface to `exiting`.
+
         surfaceStore.resolve(surfaceId, { result: "timeout", timeout_ms: timeoutMs, origin: "system" });
       }, timeoutMs);
       cleanups.push(() => clearTimeoutFn(handle));
     }
 
-    // Decoupled lifecycle: the call resolves on the user's action (via
-    // onGlassesUiResult), the cron's terminal outcome (via onResolve), the
-    // wrap-up timer, or the abort release. A nonterminal resolve (selected/
-    // back/window_expired) does NOT stop the cron — the surface persists
-    // until a terminal or a drain. Per-call timers/listeners die with the call.
     return promise.then((outcome) => {
       for (const fn of cleanups) {
-        try { fn(); } catch (_) { /* cleanup must never mask the outcome */ }
+        try { fn(); } catch (_) {  }
       }
       return outcome;
     });
   }
 
-  // Per-session last-seen depth, used only to distinguish push (depth up) from
-  // pop (depth down) on the client nav-event. The surfaceIds + pause/resume
-  // live in surfaceStore (the single source of truth) — there is NO second
-  // stack here. On push the parent cron was already paused by applyRender
-  // during the agent's push render, so push is idempotent here; on pop we drive
-  // surfaceStore.popBack, which stops the child cron and staleness-resumes the
-  // parent (Spike B: the plugin owns the resume target).
-  const navDepthBySession = new Map(); // sessionKey -> lastSeenDepth
+  const navDepthBySession = new Map();
 
   function handleNavEvent(rawSessionKey, ev) {
     const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
@@ -1152,8 +906,7 @@ export function createGlassesUiToolHandler(deps) {
     let popCount = 0;
     let resumedParent = null;
     if (newDepth < lastDepth) {
-      // Pop(s): the client popped locally. Reconcile the store to the reported
-      // depth — each popBack stops the child cron + resumes the new parent.
+
       let guard = 0;
       while (surfaceStore.stackDepth(sessionKey) > newDepth && guard < 64) {
         resumedParent = surfaceStore.popBack(sessionKey);
@@ -1166,21 +919,11 @@ export function createGlassesUiToolHandler(deps) {
       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.
-    // Resume re-asserts the restored parent's presence marker (7a): a pop
-    // brings the parent back as the top surface, so emit its current marker
-    // (emitMarker self-gates to the session top — resumedParent is now it).
+
     if (popCount > 0 && resumedParent) {
       emitMarker(sessionKey, resumedParent);
     }
@@ -1197,18 +940,12 @@ 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(rawSessionKey, outcome) {
     const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
     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)
+    surfaceStore.exit(sessionKey);
+    navDepthBySession.delete(sessionKey);
     return reaped;
   }
 
@@ -1219,10 +956,7 @@ export function createGlassesUiToolHandler(deps) {
     drainSession(sessionKey, outcome) {
       return reapSession(sessionKey, outcome);
     },
-    // Run-teardown safety net (agent_end): settle leaked pending calls but
-    // PRESERVE surfaces, parked events, crons and the stack — surfaces are
-    // designed to outlive runs (drift #3: the old unconditional reap here
-    // destroyed parked wearer intent whenever it fired in the owning context).
+
     settleSession(sessionKey, outcome) {
       return surfaceStore.settlePending(sessionKey, outcome);
     },
@@ -1235,18 +969,14 @@ export function createGlassesUiToolHandler(deps) {
       navDepthBySession.clear();
       return reaped;
     },
-    // Failed-wake outbox (roadmap 6f). The 7b voicemail (buildVoicemailInjection
-    // below) is the production consumer — an external drain steals owed
-    // voicemail, so these passthroughs are debug/ops surfaces only.
+
     peekWakeOutbox() {
       return wakeController.peekWakeOutbox();
     },
     drainWakeOutbox() {
       return wakeController.drainWakeOutbox();
     },
-    // Voicemail injection (roadmap 7b): refs-only fragment for the session's
-    // next genuine turn, or null when nothing is owed. Consumed by the
-    // before_prompt_build hook in registerGlassesUiTool.
+
     buildVoicemailInjection(sessionKey) {
       return voicemail.buildInjection(sessionKey);
     },
@@ -1260,16 +990,11 @@ export function createGlassesUiToolHandler(deps) {
     surfaceStackDepth(sessionKey) {
       return surfaceStore.stackDepth(sessionKey);
     },
-    // Run-teardown marker (7a): a silent agent_end (the agent never re-rendered
-    // after a wearer tap) must flip the surface inflight→parked. settleSession
-    // already cleared any leaked pending call; clearing awaitingResponse drops
-    // the last "agent is responding" fact so markerFor derives parked. Routed
-    // through the handler closure because surfaceStore/emitMarker are NOT in
-    // scope at the agent_end hook site (Codex finding).
+
     parkMarkerOnAgentEnd(sessionKey) {
-      surfaceStore.clearAwaitingResponse(sessionKey); // inflight → parked if the agent ended silently
+      surfaceStore.clearAwaitingResponse(sessionKey);
       const top = surfaceStore.topSurfaceId(sessionKey);
-      if (top) emitMarker(sessionKey, top); // emitMarker + surfaceStore are in scope HERE
+      if (top) emitMarker(sessionKey, top);
     },
     sessionForSurface(surfaceId) {
       return surfaceStore.sessionForSurface(surfaceId);
@@ -1318,13 +1043,6 @@ export const GLASSES_UI_TOOL_DESCRIPTION = [
   "\"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)
-// in multiple isolated contexts (gateway startup, per-agent-run tool discovery)
-// and each call to registerGlassesUiTool would otherwise close over its own
-// Map. execute() runs in the per-run context's closure while api.on("agent_end",
-// ...) fires from an earlier global-context closure, so reset-on-end would miss
-// the live counter. Stashing the map on globalThis under a stable Symbol gives
-// every load context the same Map to read and mutate.
 const DEPTH_MAP_SYMBOL = Symbol.for("ocuclaw.glasses-ui.depthBySession");
 function getSharedDepthMap() {
   let m = globalThis[DEPTH_MAP_SYMBOL];
@@ -1335,16 +1053,6 @@ function getSharedDepthMap() {
   return m;
 }
 
-// Shared handler record, same multi-context reasoning as the depth map but for
-// ALL of the tool's mutable state: surface store + dead-letter, cron engine,
-// paint-floor coalescer and the 6f wake controller/outbox. The 2026-06-12
-// live census (drift #3) proved tool execution and agent_end hooks land in
-// DIFFERENT load contexts, and a QUEUED run's execution resolves to the
-// non-owning context ~3/4 of the time — with per-context stores that minted a
-// phantom root and stranded the parked tap. One shared handler makes every
-// context's execute/hook/relay-callback address the same state, so which
-// registry the gateway picks per run stops mattering. Tests inject an
-// isolated `opts.scopeHost` ({}); production omits it and shares globalThis.
 const HANDLER_SCOPE_SYMBOL = Symbol.for("ocuclaw.glasses-ui.sharedHandler");
 
 export function registerGlassesUiTool(api, service, opts = {}) {
@@ -1389,18 +1097,11 @@ export function registerGlassesUiTool(api, service, opts = {}) {
         return typeof key === "string" ? key : "";
       }
     } catch (_) {
-      /* fall through */
+
     }
     return "";
   }
 
-  // Inline resolution: the cron engine asks for the API key once per tick
-  // for the current model. We cache the last-resolved model→key pair across
-  // ticks since model rarely changes within a cron. runDynamicUi awaits
-  // prewarmLlmApiKey before starting the cron, so tick 1 sees the resolved
-  // key. resolveLlmApiKeySync is only called after the prewarm has populated
-  // the cache; if it ever runs uncached it returns "" and the backend
-  // reports a useful error (cron resolves recipe_failed via the breaker).
   let lastModel = null;
   let lastKey = "";
   async function prewarmLlmApiKey(modelRef) {
@@ -1411,8 +1112,7 @@ export function registerGlassesUiTool(api, service, opts = {}) {
   }
   function resolveLlmApiKeySync(modelRef) {
     if (modelRef === lastModel) return lastKey;
-    // Fallback: prewarm wasn't called (or model changed mid-cron). Kick
-    // off async resolution but return empty for this tick.
+
     resolveLlmApiKey(modelRef).then((key) => {
       lastModel = modelRef;
       lastKey = key;
@@ -1420,12 +1120,6 @@ export function registerGlassesUiTool(api, service, opts = {}) {
     return "";
   }
 
-  // Get-or-create the shared handler. Only the CREATING context builds the
-  // handler and wires the relay-singleton callbacks (disconnect drain, nav
-  // reconcile) — a second wiring against the same shared relay would
-  // double-handle every nav event / disconnect on the now-shared store.
-  // Boot order makes the creator the gateway-startup full registry, whose
-  // api/service carry the complete runtime surface.
   let scopeRecord = scopeHost[HANDLER_SCOPE_SYMBOL];
   const createsHandler = !scopeRecord || !scopeRecord.handler;
 
@@ -1441,7 +1135,7 @@ export function registerGlassesUiTool(api, service, opts = {}) {
           service.emitGlassesUiLifecycle(event, severity, data);
         }
       } catch (_) {
-        // observability must never break the tool path
+
       }
     },
     getGlassesUiLiveConfig: () => {
@@ -1455,10 +1149,7 @@ export function registerGlassesUiTool(api, service, opts = {}) {
     resolveLlmApiKey: resolveLlmApiKeySync,
     prewarmLlmApiKey,
     timeoutMs: () => {
-      // Live-read so config hot-reloads (`openclawctl config set …`) take
-      // effect on the next render without a gateway restart. A non-finite
-      // or <=0 value disables the timeout (infinite wait — the pre-2026-05-23
-      // behaviour, kept available as an escape hatch).
+
       try {
         const cfg = service.getRuntimeConfig && service.getRuntimeConfig();
         const v = cfg && cfg.renderGlassesUiTimeoutMs;
@@ -1468,25 +1159,14 @@ export function registerGlassesUiTool(api, service, opts = {}) {
       }
     },
     isSessionConnected: () => {
-      // Consult the shared relay singleton (works across plugin-load
-      // contexts) for any connected downstream client. Per-session
-      // connection tracking would need deeper plumbing; the global check
-      // catches the common failure mode where the tool is invoked with no
-      // glasses client at all, which is what produced the indefinite hangs
-      // before this gate existed.
+
       if (typeof service.hasConnectedAppClient === "function") {
         return service.hasConnectedAppClient();
       }
       return false;
     },
     isUnderBackpressure: () => {
-      // The paint-floor coalescer sheds the trailing send while the relay/BLE
-      // send buffer is over its high-water mark (Spike D — there is no
-      // glass-side paint-ack, so transport pressure is the only signal). The
-      // signal source is relay-health-monitor's send-buffer high-water; until
-      // relay-service surfaces it as isGlassesSendBufferOverHighWater this
-      // returns false (safe default — no shedding). Completing this query is
-      // part of the BLE-backpressure hardening validated on hardware (Task 20).
+
       try {
         return typeof service.isGlassesSendBufferOverHighWater === "function"
           ? service.isGlassesSendBufferOverHighWater()
@@ -1495,9 +1175,7 @@ export function registerGlassesUiTool(api, service, opts = {}) {
         return false;
       }
     },
-    // Tap-to-wake lane + busy signal (roadmap 6f). Absent on a relay that
-    // predates them — the wake controller then no-ops (parked taps keep
-    // their collect-on-next-render semantics).
+
     dispatchWake:
       typeof service.dispatchGlassesWake === "function"
         ? (params) => service.dispatchGlassesWake(params)
@@ -1517,10 +1195,6 @@ export function registerGlassesUiTool(api, service, opts = {}) {
     scopeRecord = { handler, refs: 0 };
     scopeHost[HANDLER_SCOPE_SYMBOL] = scopeRecord;
 
-    // Wire glasses-disconnect to stop any active crons for the affected
-    // session. The agent_end hook below only SETTLES pending calls; this path
-    // is the real teardown — the glasses are gone, so surfaces, parked events
-    // and crons all drain (dead-lettering undelivered nonterminals).
     if (typeof service.onAppClientDisconnect === "function") {
       service.onAppClientDisconnect(({ sessionKey }) => {
         const target = sessionKey || null;
@@ -1532,12 +1206,6 @@ export function registerGlassesUiTool(api, service, opts = {}) {
       });
     }
 
-    // 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). With the shared handler
-    // this wiring exists ONCE per process; the foreign-surface no-op guard
-    // stays for surfaces the store genuinely does not know (B2).
     if (typeof service.onGlassesUiNavEvent === "function") {
       service.onGlassesUiNavEvent((ev) => {
         const sessionKey = handler.sessionForSurface(ev.surfaceId);
@@ -1550,7 +1218,7 @@ export function registerGlassesUiTool(api, service, opts = {}) {
               });
             }
           } catch (_) {
-            // observability must never break the nav path
+
           }
           return;
         }
@@ -1569,14 +1237,7 @@ export function registerGlassesUiTool(api, service, opts = {}) {
 
   api.registerTool(
     (ctx) => {
-      // Hide the tool from Even AI quick-action runs (dedicated or throwaway
-      // sessions). Those runs' responses go back to the Even Realities native
-      // app — not the OcuClaw chat surface — so a glasses popup wouldn't be
-      // reachable for the user. The tool stays visible to:
-      //   • the normal OcuClaw chat path (ocuclaw:<timestamp> sessions)
-      //   • the Even AI listen-mode path (which intercepts the HTTP
-      //     request and routes it through the active OcuClaw session, so
-      //     the sessionKey is an ocuclaw:<timestamp>, not ocuclaw:even-ai*).
+
       const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : "";
       if (isEvenAiAgentSession(sessionKey, resolveDedicatedEvenAiSessionKey())) {
         return null;
@@ -1590,10 +1251,7 @@ export function registerGlassesUiTool(api, service, opts = {}) {
           const resolvedSessionKey = normalizeGlassesSessionKey(factorySessionKey || "main");
           const depth = nextDepth(resolvedSessionKey);
           try {
-            // The gateway delivers its watchdog AbortSignal as the third
-            // argument (execute(toolCallId, args, signal, onUpdate) — verified
-            // against the installed 2026.6.1 dist). runDynamicUi releases the
-            // pending resolver on abort so post-cliff taps park (roadmap 6c).
+
             const outcome = await handler.runDynamicUi({
               sessionKey: resolvedSessionKey,
               depth,
@@ -1615,12 +1273,7 @@ export function registerGlassesUiTool(api, service, opts = {}) {
   );
 
   if (typeof api.on === "function") {
-    // Voicemail delivery (roadmap 7b): owed parked events ride the next
-    // genuine turn's prompt as appended system context (Channel-2 class —
-    // gateway hooks.ts concatenates appendSystemContext across handlers, so
-    // this composes with the channel-two fragment). Registered per load
-    // context; the shared handler's pending state makes duplicate firings
-    // drain-once.
+
     api.on("before_prompt_build", (_event, ctx) => {
       const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
       if (!sessionKey) return undefined;
@@ -1628,27 +1281,18 @@ export function registerGlassesUiTool(api, service, opts = {}) {
         const fragment = handler.buildVoicemailInjection(sessionKey);
         return fragment ? { appendSystemContext: fragment } : undefined;
       } catch (_) {
-        // Defensive: voicemail must never break prompt building.
+
         return undefined;
       }
     });
 
     api.on("agent_end", (_event, ctx) => {
       const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
-      // Settle any still-pending render for this session before clearing the
-      // depth counter — the safety net for runs torn down externally (timeout,
-      // abort) so no pending call leaks across runs / corrupts tool_use
-      // bookkeeping. SETTLE ONLY: surfaces, parked events, crons and the
-      // stack persist (surfaces are designed to outlive runs; the old
-      // unconditional drain here destroyed parked wearer intent whenever it
-      // fired in the store-owning context — drift #3). With the shared
-      // handler this hook fires from every load context against ONE store;
-      // settlePending is idempotent so the duplicate firings are harmless.
+
       if (sessionKey) {
         const stackDepth = handler.surfaceStackDepth(sessionKey);
         const settledPending = handler.settleSession(sessionKey, { result: "preempted" });
-        // Run-end observability (drift #3): this hook was silent, so WHERE it
-        // fired (which context's store, against what stack) was invisible.
+
         try {
           if (typeof service.emitGlassesUiLifecycle === "function") {
             service.emitGlassesUiLifecycle("agent_end_settle", "debug", {
@@ -1659,22 +1303,15 @@ export function registerGlassesUiTool(api, service, opts = {}) {
             });
           }
         } catch (_) {
-          // observability must never break the hook path
+
         }
-        // 7a: a silent agent_end (no re-render after a wearer tap) parks the
-        // surface marker — clears awaiting-response so markerFor derives parked.
+
         handler.parkMarkerOnAgentEnd(sessionKey);
       }
       resetDepth(sessionKey);
     });
   }
 
-  // Refcounted teardown (review P1): every register context holds a reference
-  // to the shared handler. Only the LAST live context's dispose drains it —
-  // a secondary context disposing mid-flight (e.g. an ephemeral registry
-  // being torn down) must not preempt live surfaces, clear the shared depth
-  // map, or delete the record (which would let a later register mint a second
-  // store and reintroduce the drift-#3 context split).
   scopeRecord.refs += 1;
   let disposedThisContext = false;
   return function dispose() {
@@ -1684,8 +1321,7 @@ export function registerGlassesUiTool(api, service, opts = {}) {
     if (scopeRecord.refs > 0) return;
     handler.drainAll({ result: "preempted" });
     depthBySession.clear();
-    // Drop the shared record so a post-dispose register builds fresh state
-    // (real teardown happens once, at gateway service stop).
+
     if (scopeHost[HANDLER_SCOPE_SYMBOL] === scopeRecord) {
       delete scopeHost[HANDLER_SCOPE_SYMBOL];
     }