ocuclaw 1.3.2 → 1.3.3

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

@@ -11,7 +11,9 @@ import {
   executeLlmRecipe,
   executeSystemStatsRecipe,
 } 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 {
@@ -257,6 +259,82 @@ 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,
+  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.",
+};
+
+// staleAfterMs reservation (roadmap 6b; annotate-only through the soak).
+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,
+};
+
+// 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) {
+    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.",
@@ -374,6 +452,9 @@ export const glassesUiParametersSchema = {
     // 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
@@ -387,6 +468,8 @@ export const glassesUiParametersSchema = {
       ...branch.properties,
       refresh: refreshSchemaForToolParams,
       update: updateSchemaForToolParams,
+      timeoutMs: timeoutMsSchemaForToolParams,
+      staleAfterMs: staleAfterMsSchemaForToolParams,
     },
   })),
 };
@@ -447,6 +530,19 @@ export function isEvenAiAgentSession(sessionKey, dedicatedSessionKey) {
 // 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
@@ -456,6 +552,55 @@ export function createGlassesUiToolHandler(deps) {
   // 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
+    const marker = surfaceStore.markerFor(surfaceId);
+    if (!marker) return;
+    paintFloor.enqueue({ surfaceId, sessionKey, patch: { marker } });
+  }
+
   const newSurfaceId =
     deps && typeof deps.newSurfaceId === "function"
       ? deps.newSurfaceId
@@ -464,8 +609,19 @@ export function createGlassesUiToolHandler(deps) {
   // 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 =
+  // 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
+      : `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.
@@ -490,7 +646,7 @@ export function createGlassesUiToolHandler(deps) {
     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 });
       }
@@ -534,6 +690,10 @@ export function createGlassesUiToolHandler(deps) {
   // 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,
@@ -549,16 +709,52 @@ 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,
+    emitLifecycle,
+    now: typeof deps.now === "function" ? deps.now : Date.now,
+    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,
+    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);
+    // 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",
+      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);
@@ -569,8 +765,33 @@ export function createGlassesUiToolHandler(deps) {
     // 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);
+    // 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),
+          surfaceUuid: receipt.surfaceUuid,
+          eventId: receipt.eventId,
+          result: outcome.result,
+          itemIndex: outcome.selected_index,
+          origin: outcome.origin,
+        });
+      }
+      // PARK → ◌: the queued tap (events.length≥1) derives inflight.
+      emitMarker(sessionKey, msg.surfaceId);
     }
   });
 
@@ -586,10 +807,14 @@ export function createGlassesUiToolHandler(deps) {
       err.code = validation.code;
       throw err;
     }
-    const sessionKey =
+    // 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()
-        : "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,6 +835,21 @@ 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", {
+        surfaceId: null,
+        code: windowFields.code,
+        reason: windowFields.message,
+      });
+      const err = new Error(`${windowFields.code}: ${windowFields.message}`);
+      err.code = windowFields.code;
+      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
@@ -641,12 +881,27 @@ export function createGlassesUiToolHandler(deps) {
     // 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 });
+    // 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,
+      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,
+    });
     // 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
@@ -666,6 +921,12 @@ export function createGlassesUiToolHandler(deps) {
         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:
@@ -678,10 +939,20 @@ export function createGlassesUiToolHandler(deps) {
     // 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,
-      patch: { __render: true, __depth: wireDepth, __spec: validation.spec },
+      // __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
@@ -734,6 +1005,14 @@ export function createGlassesUiToolHandler(deps) {
           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
@@ -741,42 +1020,119 @@ export function createGlassesUiToolHandler(deps) {
             // 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);
+            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 = [];
+
+    // 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) =>
+      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",
+        });
+        // ●→○: 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 = () => {
+        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);
+          }
+        });
+      }
+    }
+
+    // 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 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;
+    // 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 */ }
+      }
+      return outcome;
+    });
   }
 
   // Per-session last-seen depth, used only to distinguish push (depth up) from
@@ -788,7 +1144,8 @@ export function createGlassesUiToolHandler(deps) {
   // parent (Spike B: the plugin owns the resume target).
   const navDepthBySession = new Map(); // sessionKey -> lastSeenDepth
 
-  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);
@@ -821,6 +1178,12 @@ export function createGlassesUiToolHandler(deps) {
     }
     // 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);
+    }
     emitLifecycle("nav_reconcile", "debug", {
       sessionKey,
       evSurfaceId: ev.surfaceId,
@@ -840,7 +1203,8 @@ export function createGlassesUiToolHandler(deps) {
   // 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)
@@ -849,11 +1213,19 @@ export function createGlassesUiToolHandler(deps) {
   }
 
   return {
+    storeId,
     runDynamicUi,
     handleNavEvent,
     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);
+    },
     drainAll(outcome) {
       cronEngine.stopAll(outcome);
       const reaped = surfaceStore.drainAll(outcome);
@@ -863,6 +1235,21 @@ 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);
+    },
     isCronActive(surfaceId) {
       return cronEngine.isActive(surfaceId);
     },
@@ -873,6 +1260,17 @@ 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
+      const top = surfaceStore.topSurfaceId(sessionKey);
+      if (top) emitMarker(sessionKey, top); // emitMarker + surfaceStore are in scope HERE
+    },
     sessionForSurface(surfaceId) {
       return surfaceStore.sessionForSurface(surfaceId);
     },
@@ -888,8 +1286,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 +1297,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",
@@ -933,24 +1335,40 @@ function getSharedDepthMap() {
   return m;
 }
 
-export function registerGlassesUiTool(api, service) {
+// 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 = {}) {
   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 {
@@ -1002,7 +1420,16 @@ export function registerGlassesUiTool(api, service) {
     return "";
   }
 
-  const handler = createGlassesUiToolHandler({
+  // 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;
+
+  const handler = createsHandler ? createGlassesUiToolHandler({
     relay: {
       sendGlassesUiRender: (msg) => service.sendGlassesUiRender(msg),
       sendGlassesUiSurfaceUpdate: (msg) => service.sendGlassesUiSurfaceUpdate(msg),
@@ -1068,49 +1495,68 @@ 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" });
+    // 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)
+        : null,
+    isAgentTurnBusy: (sessionKey) => {
+      try {
+        return typeof service.isAgentTurnBusy === "function"
+          ? !!service.isAgentTurnBusy(sessionKey)
+          : false;
+      } catch (_) {
+        return false;
       }
-    });
-  }
+    },
+  }) : scopeRecord.handler;
 
-  // 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,
-            });
+  if (createsHandler) {
+    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;
+        if (target) {
+          handler.drainSession(target, { result: "glasses_disconnected" });
+        } else {
+          handler.drainAll({ result: "glasses_disconnected" });
+        }
+      });
+    }
+
+    // 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);
+        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
           }
-        } catch (_) {
-          // observability must never break the nav path
+          return;
         }
-        return;
-      }
-      handler.handleNavEvent(sessionKey, ev);
-    });
+        handler.handleNavEvent(sessionKey, ev);
+      });
+    }
   }
 
   function resolveDedicatedEvenAiSessionKey() {
@@ -1140,14 +1586,19 @@ 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 {
+            // 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,
               spec: params,
+              signal,
             });
             return {
               content: [{ type: "text", text: JSON.stringify(outcome) }],
@@ -1164,22 +1615,79 @@ export function registerGlassesUiTool(api, service) {
   );
 
   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;
+      try {
+        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;
-      // 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.
+      // 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) {
-        handler.drainSession(sessionKey, { result: "preempted" });
+        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", {
+              sessionKey: normalizeGlassesSessionKey(sessionKey),
+              stackDepth,
+              settledPending,
+              storeId: handler.storeId,
+            });
+          }
+        } 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() {
+    if (disposedThisContext) return;
+    disposedThisContext = true;
+    scopeRecord.refs -= 1;
+    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];
+    }
   };
 }