ocuclaw 1.3.2 → 1.3.4

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

@@ -1,17 +1,15 @@
-// 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 } from "./glasses-ui-surfaces.js";
+import { createPendingRenderMap, createSurfaceStore, isTerminalOutcome, normalizeGlassesSessionKey } from "./glasses-ui-surfaces.js";
+import { createGlassesWakeController } from "./glasses-ui-wake.js";
+import { createGlassesVoicemail } from "./glasses-ui-voicemail.js";
 import { createPaintFloorCoalescer, DEFAULT_PAINT_FLOOR_MS } from "./glasses-ui-paint-floor.js";
 import { GLASSES_UI_LIMITS } from "./glasses-ui-limits.js";
 import {
@@ -20,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 = {
@@ -51,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);
 }
@@ -87,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") {
@@ -102,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;
@@ -134,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}]` };
@@ -145,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" };
@@ -166,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;
@@ -174,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) {
@@ -190,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,
@@ -210,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` };
         }
@@ -257,6 +235,73 @@ const updateSchemaForToolParams = {
     "\"push\": stack a new screen; the parent is retained and its cron pauses.",
 };
 
+const timeoutMsSchemaForToolParams = {
+  type: "integer",
+  minimum: 1000,
+  maximum: 600_000,
+  description:
+    "Optional one-shot interaction window for THIS call, in ms (default 90000, " +
+    "max 600000). Pass 300000-600000 when expecting the user to read or decide; " +
+    "omit for fire-and-forget. Never renewed automatically — re-render to listen again.",
+};
+
+const staleAfterMsSchemaForToolParams = {
+  type: "integer",
+  minimum: 1000,
+  maximum: 86_400_000,
+  description:
+    "Optional per-render staleness window, in ms. A tap parked longer than this " +
+    "is still delivered but annotated stale:true — treat a stale actuating tap " +
+    "as a re-confirm prompt, never an action. Default absent (no annotation).",
+};
+
+export const GLASSES_UI_WINDOW_LIMITS = {
+  timeoutMsMin: timeoutMsSchemaForToolParams.minimum,
+  timeoutMsMax: timeoutMsSchemaForToolParams.maximum,
+  staleAfterMsMin: staleAfterMsSchemaForToolParams.minimum,
+  staleAfterMsMax: staleAfterMsSchemaForToolParams.maximum,
+};
+
+function validateWindowFields(spec) {
+  const out = { ok: true, timeoutMs: undefined, staleAfterMs: undefined };
+  if (spec && spec.timeoutMs !== undefined) {
+    const v = spec.timeoutMs;
+    if (
+      !Number.isFinite(v) ||
+      v < GLASSES_UI_WINDOW_LIMITS.timeoutMsMin ||
+      v > GLASSES_UI_WINDOW_LIMITS.timeoutMsMax
+    ) {
+      return {
+        ok: false,
+        code: "timeout_ms_out_of_bounds",
+        message:
+          `timeoutMs ${JSON.stringify(v)} out of bounds ` +
+          `[${GLASSES_UI_WINDOW_LIMITS.timeoutMsMin}..${GLASSES_UI_WINDOW_LIMITS.timeoutMsMax}]; ` +
+          "pass 300000-600000 when expecting the user to read or decide, omit for fire-and-forget",
+      };
+    }
+    out.timeoutMs = Math.floor(v);
+  }
+  if (spec && spec.staleAfterMs !== undefined) {
+    const v = spec.staleAfterMs;
+    if (
+      !Number.isFinite(v) ||
+      v < GLASSES_UI_WINDOW_LIMITS.staleAfterMsMin ||
+      v > GLASSES_UI_WINDOW_LIMITS.staleAfterMsMax
+    ) {
+      return {
+        ok: false,
+        code: "stale_after_ms_out_of_bounds",
+        message:
+          `staleAfterMs ${JSON.stringify(v)} out of bounds ` +
+          `[${GLASSES_UI_WINDOW_LIMITS.staleAfterMsMin}..${GLASSES_UI_WINDOW_LIMITS.staleAfterMsMax}]`,
+      };
+    }
+    out.staleAfterMs = Math.floor(v);
+  }
+  return out;
+}
+
 const refreshSchemaForToolParams = {
   type: "object",
   description: "Optional periodic refresh policy; turns this surface into a live-updating one.",
@@ -321,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 " +
@@ -364,29 +401,23 @@ 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,
+
+    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: {
       ...branch.properties,
       refresh: refreshSchemaForToolParams,
       update: updateSchemaForToolParams,
+      timeoutMs: timeoutMsSchemaForToolParams,
+      staleAfterMs: staleAfterMsSchemaForToolParams,
     },
   })),
 };
@@ -396,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 {
@@ -415,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";
 
@@ -439,36 +464,59 @@ 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;
 
+export const GATEWAY_DYNAMIC_TOOL_DEFAULT_TIMEOUT_MS = 90_000;
+
+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();
+
+  const TITLE_BUDGET_PX = 540;
+
+  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(" › ");
+
+    while (segments.length > 1 && segments.join(" › ").length > charBudget) {
+      segments.shift();
+    }
+    const joined = segments.join(" › ");
+    if (joined.length <= charBudget) return joined;
+
+    return joined.slice(0, charBudget);
+  }
+
+  function emitMarker(sessionKey, surfaceId) {
+    if (!surfaceId) return;
+    if (surfaceStore.topSurfaceId(sessionKey) !== surfaceId) return;
+    const marker = surfaceStore.markerFor(surfaceId);
+    if (!marker) return;
+    paintFloor.enqueue({ surfaceId, sessionKey, patch: { marker } });
+  }
+
   const newSurfaceId =
     deps && typeof deps.newSurfaceId === "function"
       ? 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.
-  const emitLifecycle =
+  const storeId =
+    typeof deps.storeId === "string" && deps.storeId
+      ? deps.storeId
+      : `st-${Math.random().toString(36).slice(2, 8)}`;
+  const baseEmitLifecycle =
     typeof deps.emitLifecycle === "function" ? deps.emitLifecycle : () => {};
+  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") {
@@ -478,19 +526,12 @@ 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) {
-        deps.relay.sendGlassesUiRender({ sessionKey, surfaceId, depth: patch.__depth, spec: patch.__spec });
+        deps.relay.sendGlassesUiRender({ sessionKey, surfaceId, depth: patch.__depth, spec: patch.__spec, marker: patch.__marker });
       } else {
         deps.relay.sendGlassesUiSurfaceUpdate({ sessionKey, surfaceId, patch });
       }
@@ -502,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}` };
@@ -530,18 +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,
+
+    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);
@@ -549,28 +590,65 @@ export function createGlassesUiToolHandler(deps) {
     mintSurfaceId: newSurfaceId,
   });
 
+  const wakeController = createGlassesWakeController({
+    dispatchWake: typeof deps.dispatchWake === "function" ? deps.dispatchWake : null,
+    isAgentTurnBusy: typeof deps.isAgentTurnBusy === "function" ? deps.isAgentTurnBusy : () => false,
+    emitLifecycle,
+    now: typeof deps.now === "function" ? deps.now : Date.now,
+    wakeCooldownMs: deps.wakeCooldownMs,
+  });
+
+  const voicemail = createGlassesVoicemail({
+    now: typeof deps.now === "function" ? deps.now : Date.now,
+    ttlMs: deps.voicemailTtlMs,
+    drainWakeOutbox: () => wakeController.drainWakeOutbox(),
+    drainDeadLetter: (sessionKey) => surfaceStore.drainDeadLetter(sessionKey),
+    emitLifecycle,
+  });
+
   deps.relay.onGlassesUiResult((msg) => {
     if (!msg || typeof msg.surfaceId !== "string" || !msg.outcome) return;
-    const terminal = isTerminalOutcome(msg.outcome);
+
+    const outcome = {
+      ...msg.outcome,
+      origin: typeof msg.outcome.origin === "string" ? msg.outcome.origin : "gesture",
+      actor: typeof msg.outcome.actor === "string" ? msg.outcome.actor : "wearer",
+    };
+    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 = msg.outcome;
+
+      let merged = outcome;
       capturedCronOutcome.set(msg.surfaceId, (cronOutcome) => { merged = cronOutcome; });
-      cronEngine.stop(msg.surfaceId, msg.outcome);
+      cronEngine.stop(msg.surfaceId, outcome);
       capturedCronOutcome.delete(msg.surfaceId);
       if (!surfaceStore.resolve(msg.surfaceId, merged)) {
         surfaceStore.queueEvent(msg.surfaceId, merged);
       }
       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).
-    if (!surfaceStore.resolve(msg.surfaceId, msg.outcome)) {
-      surfaceStore.queueEvent(msg.surfaceId, msg.outcome);
+
+    const sessionKey = surfaceStore.sessionForSurface(msg.surfaceId);
+    if (surfaceStore.resolve(msg.surfaceId, outcome)) {
+
+      emitMarker(sessionKey, msg.surfaceId);
+    } else {
+      const receipt = surfaceStore.queueEvent(msg.surfaceId, outcome, {
+        origin: outcome.origin,
+        actor: outcome.actor,
+      });
+
+      if (receipt && !receipt.kind) {
+        wakeController.onParkedGesture({
+          sessionKey: surfaceStore.sessionForSurface(msg.surfaceId),
+          surfaceUuid: receipt.surfaceUuid,
+          eventId: receipt.eventId,
+          result: outcome.result,
+          itemIndex: outcome.selected_index,
+          origin: outcome.origin,
+        });
+      }
+
+      emitMarker(sessionKey, msg.surfaceId);
     }
   });
 
@@ -586,10 +664,12 @@ export function createGlassesUiToolHandler(deps) {
       err.code = validation.code;
       throw err;
     }
-    const sessionKey =
+
+    const sessionKey = normalizeGlassesSessionKey(
       typeof params.sessionKey === "string" && params.sessionKey.trim()
         ? params.sessionKey.trim()
-        : "main";
+        : "main",
+    );
     if (typeof deps.isSessionConnected === "function" && !deps.isSessionConnected(sessionKey)) {
       const err = new Error(
         "glasses_not_connected: no Even glasses client connected for this session",
@@ -610,24 +690,24 @@ 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 windowFields = validateWindowFields(params.spec);
+    if (!windowFields.ok) {
+      emitLifecycle("render_rejected", "warn", {
+        surfaceId: null,
+        code: windowFields.code,
+        reason: windowFields.message,
+      });
+      const err = new Error(`${windowFields.code}: ${windowFields.message}`);
+      err.code = windowFields.code;
+      throw err;
+    }
+
     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" });
@@ -637,62 +717,54 @@ 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;
-    const promise = surfaceStore.register(sessionKey, surfaceId, { kind: validation.spec.kind });
-    // 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).
+
+    emitLifecycle("surface_attach", "debug", {
+      surfaceId,
+      sessionKey,
+      mode: applied.mode,
+      requestedUpdate: update,
+      stackDepthBefore: stackDepthBeforeAttach,
+    });
+    const promise = surfaceStore.register(sessionKey, surfaceId, {
+      kind: validation.spec.kind,
+      staleAfterMs: windowFields.staleAfterMs,
+      title: typeof validation.spec.title === "string" ? validation.spec.title : undefined,
+    });
+
     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") {
+
+        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).
+    const breadcrumb = surfaceStore.breadcrumbFor(sessionKey);
+    if (breadcrumb) validation.spec.title = clipBreadcrumb(breadcrumb);
     paintFloor.enqueue({
       surfaceId,
       sessionKey,
-      patch: { __render: true, __depth: wireDepth, __spec: validation.spec },
+
+      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 =
@@ -706,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.
+
           }
         }
       }
@@ -726,77 +797,116 @@ 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)) {
-            // 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, cronOutcome)) {
-              surfaceStore.queueEvent(surfaceId, cronOutcome);
+
+            const stamped = {
+              ...cronOutcome,
+              origin: typeof cronOutcome.origin === "string" ? cronOutcome.origin : "system",
+            };
+
+            if (!surfaceStore.resolve(surfaceId, stamped)) {
+              surfaceStore.queueEvent(surfaceId, stamped);
             }
           }
         },
       });
     }
 
-    // Bound the wait via the existing timeout knob — disabled if cron is
-    // active (cron has its own maxDurationMs cap and the user explicitly
-    // owns the surface lifetime through dismiss).
+    const setTimeoutFn =
+      deps && typeof deps.setTimeout === "function" ? deps.setTimeout : setTimeout;
+    const clearTimeoutFn =
+      deps && typeof deps.clearTimeout === "function" ? deps.clearTimeout : clearTimeout;
+    const cleanups = [];
+
+    const effectiveWindowMs =
+      windowFields.timeoutMs !== undefined
+        ? windowFields.timeoutMs
+        : GATEWAY_DYNAMIC_TOOL_DEFAULT_TIMEOUT_MS;
+
+    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) =>
+      Object.assign(
+        {
+          result: "window_expired",
+          surface_still_live: true,
+          window_ms: effectiveWindowMs,
+          origin: "system",
+          hint: WINDOW_EXPIRED_HINT,
+        },
+        extra,
+      );
+    const wrapUpHandle = setTimeoutFn(() => {
+      if (surfaceStore.resolve(surfaceId, windowExpiredOutcome())) {
+        emitLifecycle("window_expired", "debug", {
+          surfaceId,
+          sessionKey,
+          windowMs: effectiveWindowMs,
+          via: "wrap_up_timer",
+        });
+
+        emitMarker(sessionKey, surfaceId);
+      }
+    }, wrapUpDelayMs);
+    cleanups.push(() => clearTimeoutFn(wrapUpHandle));
+
+    const signal = params.signal;
+    if (signal && typeof signal.addEventListener === "function") {
+      const onAbort = () => {
+        if (surfaceStore.resolve(surfaceId, windowExpiredOutcome({ aborted: true }))) {
+          emitLifecycle("window_expired", "debug", {
+            surfaceId,
+            sessionKey,
+            windowMs: effectiveWindowMs,
+            via: "abort_signal",
+          });
+        }
+      };
+      if (signal.aborted) {
+        onAbort();
+      } else {
+        signal.addEventListener("abort", onAbort, { once: true });
+        cleanups.push(() => {
+          if (typeof signal.removeEventListener === "function") {
+            signal.removeEventListener("abort", onAbort);
+          }
+        });
+      }
+    }
+
     const timeoutMs = Number.isFinite(params.timeoutMs)
       ? params.timeoutMs
       : resolveHandlerTimeoutMs();
     if (!refreshValidated && Number.isFinite(timeoutMs) && timeoutMs > 0) {
-      const setTimeoutFn =
-        deps && typeof deps.setTimeout === "function" ? deps.setTimeout : setTimeout;
-      const clearTimeoutFn =
-        deps && typeof deps.clearTimeout === "function" ? deps.clearTimeout : clearTimeout;
       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 });
+
+        surfaceStore.resolve(surfaceId, { result: "timeout", timeout_ms: timeoutMs, origin: "system" });
       }, timeoutMs);
-      return promise.then((outcome) => {
-        clearTimeoutFn(handle);
-        return outcome;
-      });
+      cleanups.push(() => clearTimeoutFn(handle));
     }
-    // Decoupled lifecycle: the call resolves on the user's action (via
-    // onGlassesUiResult) or the cron's terminal outcome (via onResolve). A
-    // nonterminal selected/back resolves the call WITHOUT stopping the cron —
-    // the surface (and its cron) persists until a terminal or a drain. So the
-    // old "stop the cron after any resolved outcome" tail is gone.
-    return promise;
+
+    return promise.then((outcome) => {
+      for (const fn of cleanups) {
+        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(sessionKey, ev) {
+  function handleNavEvent(rawSessionKey, ev) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
     const newDepth = Number.isFinite(ev.depth) ? Math.max(1, Math.floor(ev.depth)) : 1;
     const lastDepth = navDepthBySession.get(sessionKey) || surfaceStore.stackDepth(sessionKey) || 1;
     const storeDepthBefore = surfaceStore.stackDepth(sessionKey);
     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);
@@ -809,18 +919,14 @@ 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.
+
+    if (popCount > 0 && resumedParent) {
+      emitMarker(sessionKey, resumedParent);
+    }
     emitLifecycle("nav_reconcile", "debug", {
       sessionKey,
       evSurfaceId: ev.surfaceId,
@@ -834,26 +940,26 @@ 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) {
+  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;
   }
 
   return {
+    storeId,
     runDynamicUi,
     handleNavEvent,
     drainSession(sessionKey, outcome) {
       return reapSession(sessionKey, outcome);
     },
+
+    settleSession(sessionKey, outcome) {
+      return surfaceStore.settlePending(sessionKey, outcome);
+    },
     drainAll(outcome) {
       cronEngine.stopAll(outcome);
       const reaped = surfaceStore.drainAll(outcome);
@@ -863,6 +969,17 @@ export function createGlassesUiToolHandler(deps) {
       navDepthBySession.clear();
       return reaped;
     },
+
+    peekWakeOutbox() {
+      return wakeController.peekWakeOutbox();
+    },
+    drainWakeOutbox() {
+      return wakeController.drainWakeOutbox();
+    },
+
+    buildVoicemailInjection(sessionKey) {
+      return voicemail.buildInjection(sessionKey);
+    },
     isCronActive(surfaceId) {
       return cronEngine.isActive(surfaceId);
     },
@@ -873,6 +990,12 @@ export function createGlassesUiToolHandler(deps) {
     surfaceStackDepth(sessionKey) {
       return surfaceStore.stackDepth(sessionKey);
     },
+
+    parkMarkerOnAgentEnd(sessionKey) {
+      surfaceStore.clearAwaitingResponse(sessionKey);
+      const top = surfaceStore.topSurfaceId(sessionKey);
+      if (top) emitMarker(sessionKey, top);
+    },
     sessionForSurface(surfaceId) {
       return surfaceStore.sessionForSurface(surfaceId);
     },
@@ -888,8 +1011,8 @@ export const GLASSES_UI_TOOL_DESCRIPTION = [
   "                              short detail body (≤200 chars) shown as the user",
   "                              scrolls; use when options need a 1-2 sentence",
   "                              compare-before-choosing detail.",
-  "The call blocks until the user selects, dismisses, or backs out. result is one",
-  "of: selected, back, dismissed, timeout, recipe_failed, glasses_disconnected.",
+  "The call carries one one-shot listen window. result is one of: selected,",
+  "back, dismissed, window_expired, timeout, recipe_failed, glasses_disconnected.",
   "",
   "Optional params:",
   "  refresh — make the surface self-update on a timer (e.g. live host stats via",
@@ -899,6 +1022,10 @@ export const GLASSES_UI_TOOL_DESCRIPTION = [
   "            fields; cron keeps ticking), \"replace\" (default; swap content in",
   "            place, no back-target), \"push\" (stack a child screen; the parent",
   "            is retained and its cron pauses, resuming on back).",
+  "  timeoutMs — listen ms (default 90000, max 600000); 300000-600000 when the",
+  "            user must read or decide; omit for fire-and-forget.",
+  "window_expired is NOT an error: the surface stays live; taps park — re-render",
+  "(update:\"patch\") to collect, or end your turn (parked taps wake you).",
   "",
   "Before authoring any refreshing/live surface, per-item detail list, or",
   "multi-screen flow, load the \"glasses-ui\" skill — it is the authoring source",
@@ -916,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];
@@ -933,24 +1053,30 @@ function getSharedDepthMap() {
   return m;
 }
 
-export function registerGlassesUiTool(api, service) {
+const HANDLER_SCOPE_SYMBOL = Symbol.for("ocuclaw.glasses-ui.sharedHandler");
+
+export function registerGlassesUiTool(api, service, opts = {}) {
   if (!api || typeof api.registerTool !== "function") {
     throw new Error("registerGlassesUiTool requires api.registerTool");
   }
   if (!service) {
     throw new Error("registerGlassesUiTool requires the OcuClaw relay service");
   }
+  const scopeHost =
+    opts && opts.scopeHost && typeof opts.scopeHost === "object" ? opts.scopeHost : globalThis;
 
   const depthBySession = getSharedDepthMap();
 
-  function nextDepth(sessionKey) {
+  function nextDepth(rawSessionKey) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
     const prev = depthBySession.get(sessionKey) || 0;
     const next = prev + 1;
     depthBySession.set(sessionKey, next);
     return next;
   }
 
-  function resetDepth(sessionKey) {
+  function resetDepth(rawSessionKey) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
     if (sessionKey) {
       depthBySession.delete(sessionKey);
     } else {
@@ -971,18 +1097,11 @@ export function registerGlassesUiTool(api, service) {
         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) {
@@ -993,8 +1112,7 @@ export function registerGlassesUiTool(api, service) {
   }
   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;
@@ -1002,7 +1120,10 @@ export function registerGlassesUiTool(api, service) {
     return "";
   }
 
-  const handler = createGlassesUiToolHandler({
+  let scopeRecord = scopeHost[HANDLER_SCOPE_SYMBOL];
+  const createsHandler = !scopeRecord || !scopeRecord.handler;
+
+  const handler = createsHandler ? createGlassesUiToolHandler({
     relay: {
       sendGlassesUiRender: (msg) => service.sendGlassesUiRender(msg),
       sendGlassesUiSurfaceUpdate: (msg) => service.sendGlassesUiSurfaceUpdate(msg),
@@ -1014,7 +1135,7 @@ export function registerGlassesUiTool(api, service) {
           service.emitGlassesUiLifecycle(event, severity, data);
         }
       } catch (_) {
-        // observability must never break the tool path
+
       }
     },
     getGlassesUiLiveConfig: () => {
@@ -1028,10 +1149,7 @@ export function registerGlassesUiTool(api, service) {
     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;
@@ -1041,25 +1159,14 @@ export function registerGlassesUiTool(api, service) {
       }
     },
     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()
@@ -1068,49 +1175,56 @@ export function registerGlassesUiTool(api, service) {
         return false;
       }
     },
-  });
 
-  // Wire glasses-disconnect to stop any active crons for the affected
-  // session. drainSession is also called by agent_end below; this path is
-  // distinct because a disconnect may happen mid-run without an agent_end.
-  if (typeof service.onAppClientDisconnect === "function") {
-    service.onAppClientDisconnect(({ sessionKey }) => {
-      const target = sessionKey || null;
-      if (target) {
-        handler.drainSession(target, { result: "glasses_disconnected" });
-      } else {
-        handler.drainAll({ result: "glasses_disconnected" });
+    dispatchWake:
+      typeof service.dispatchGlassesWake === "function"
+        ? (params) => service.dispatchGlassesWake(params)
+        : null,
+    isAgentTurnBusy: (sessionKey) => {
+      try {
+        return typeof service.isAgentTurnBusy === "function"
+          ? !!service.isAgentTurnBusy(sessionKey)
+          : false;
+      } catch (_) {
+        return false;
       }
-    });
-  }
+    },
+  }) : scopeRecord.handler;
+
+  if (createsHandler) {
+    scopeRecord = { handler, refs: 0 };
+    scopeHost[HANDLER_SCOPE_SYMBOL] = scopeRecord;
+
+    if (typeof service.onAppClientDisconnect === "function") {
+      service.onAppClientDisconnect(({ sessionKey }) => {
+        const target = sessionKey || null;
+        if (target) {
+          handler.drainSession(target, { result: "glasses_disconnected" });
+        } else {
+          handler.drainAll({ result: "glasses_disconnected" });
+        }
+      });
+    }
+
+    if (typeof service.onGlassesUiNavEvent === "function") {
+      service.onGlassesUiNavEvent((ev) => {
+        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 (_) {
 
-  // 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). 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);
-      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;
         }
-        return;
-      }
-      handler.handleNavEvent(sessionKey, ev);
-    });
+        handler.handleNavEvent(sessionKey, ev);
+      });
+    }
   }
 
   function resolveDedicatedEvenAiSessionKey() {
@@ -1123,14 +1237,7 @@ export function registerGlassesUiTool(api, service) {
 
   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;
@@ -1140,14 +1247,16 @@ export function registerGlassesUiTool(api, service) {
         name: "render_glasses_ui",
         description: GLASSES_UI_TOOL_DESCRIPTION,
         parameters: glassesUiParametersSchema,
-        async execute(_toolCallId, params) {
-          const resolvedSessionKey = factorySessionKey || "main";
+        async execute(_toolCallId, params, signal) {
+          const resolvedSessionKey = normalizeGlassesSessionKey(factorySessionKey || "main");
           const depth = nextDepth(resolvedSessionKey);
           try {
+
             const outcome = await handler.runDynamicUi({
               sessionKey: resolvedSessionKey,
               depth,
               spec: params,
+              signal,
             });
             return {
               content: [{ type: "text", text: JSON.stringify(outcome) }],
@@ -1164,22 +1273,57 @@ export function registerGlassesUiTool(api, service) {
   );
 
   if (typeof api.on === "function") {
+
+    api.on("before_prompt_build", (_event, ctx) => {
+      const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
+      if (!sessionKey) return undefined;
+      try {
+        const fragment = handler.buildVoicemailInjection(sessionKey);
+        return fragment ? { appendSystemContext: fragment } : undefined;
+      } catch (_) {
+
+        return undefined;
+      }
+    });
+
     api.on("agent_end", (_event, ctx) => {
       const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
-      // Drain any still-pending render for this session before clearing the
-      // depth counter. Normal-completion runs will have already resolved
-      // their tool call; this branch is the safety net for runs torn down
-      // externally (timeout, abort) so the in-memory map doesn't leak
-      // across runs.
+
       if (sessionKey) {
-        handler.drainSession(sessionKey, { result: "preempted" });
+        const stackDepth = handler.surfaceStackDepth(sessionKey);
+        const settledPending = handler.settleSession(sessionKey, { result: "preempted" });
+
+        try {
+          if (typeof service.emitGlassesUiLifecycle === "function") {
+            service.emitGlassesUiLifecycle("agent_end_settle", "debug", {
+              sessionKey: normalizeGlassesSessionKey(sessionKey),
+              stackDepth,
+              settledPending,
+              storeId: handler.storeId,
+            });
+          }
+        } catch (_) {
+
+        }
+
+        handler.parkMarkerOnAgentEnd(sessionKey);
       }
       resetDepth(sessionKey);
     });
   }
 
+  scopeRecord.refs += 1;
+  let disposedThisContext = false;
   return function dispose() {
+    if (disposedThisContext) return;
+    disposedThisContext = true;
+    scopeRecord.refs -= 1;
+    if (scopeRecord.refs > 0) return;
     handler.drainAll({ result: "preempted" });
     depthBySession.clear();
+
+    if (scopeHost[HANDLER_SCOPE_SYMBOL] === scopeRecord) {
+      delete scopeHost[HANDLER_SCOPE_SYMBOL];
+    }
   };
 }