ocuclaw 1.3.2 → 1.3.3

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

@@ -0,0 +1,299 @@
+// Voicemail delivery for parked glasses events (roadmap 7b, §2.6 W+P+L).
+//
+// A parked, ✓-acked event whose wake could not run (no dispatch lane, or the
+// dispatch failed past its retry — the 6f wake outbox) or whose surface was
+// destructively reaped (the 6a per-session dead-letter) must not wait in
+// silence for the wearer to speak first. This module drains both sources into
+// a refs-only system-context fragment for the session's NEXT genuine turn —
+// the before_prompt_build hook registered by registerGlassesUiTool calls
+// buildInjection(sessionKey) and returns {appendSystemContext} (Channel-2
+// class: hash-exempt, per-turn).
+//
+// Locked rules carried over from the 6f security review (§2.6 amendments):
+// - REFS ONLY: surfaceUuid is pattern-validated against the plugin-mint shape
+//   and REPLACED WHOLESALE when off-pattern; result is enum-allowlisted; ints
+//   are Number.isFinite-coerced. Outcome/label text (selected_text etc.)
+//   NEVER reaches the prompt — tapped content arrives only through a surface
+//   collect, as tool-result data.
+// - Explicit non-wearer provenance header.
+// - Idempotency: an entry injects at most once (keyed on the wake
+//   idempotencyKey / a minted voicemail key), so re-entering entries and
+//   double-firing hooks cannot duplicate a delivery.
+// - TTL: stale voicemail drops LOUDLY (voicemail_expired lifecycle), never
+//   silently; dead-letter staleAfterMs (6b) additionally flags entries the
+//   agent should re-confirm before acting on.
+//
+// Leaf module (CJS emitter constraint): all state injected, no runtime deps.
+
+import { sanitizeWakeToken } from "./glasses-ui-wake.js";
+import { normalizeGlassesSessionKey } from "./glasses-ui-surfaces.js";
+
+export const DEFAULT_VOICEMAIL_TTL_MS = 30 * 60_000;
+export const VOICEMAIL_MAX_ENTRIES_PER_INJECTION = 8;
+// Bound on a session's buffered (not-yet-prompting) entries — a rotated or
+// disconnected session that never speaks again must not grow memory forever
+// (review P3). Newest kept, eviction is loud.
+export const VOICEMAIL_PENDING_CAP_PER_SESSION = 32;
+const DELIVERED_KEY_CAP = 256;
+
+const RESULT_ENUM = new Set(["selected", "back"]);
+// Store reap reasons (glasses-ui-surfaces deadLetterEntryEvents call sites).
+const REAP_REASON_ENUM = new Set(["drain_session", "drain_all", "exit", "pop_back"]);
+
+function coerceInt(value) {
+  return Number.isFinite(value) ? Math.floor(value) : null;
+}
+
+function sanitizeResult(value) {
+  return RESULT_ENUM.has(value) ? value : "event";
+}
+
+// idempotencyKey reaches the prompt verbatim-ish; constrain to the same safe
+// charset family as the minted forms and replace wholesale when off-pattern.
+const IDEMPOTENCY_KEY_PATTERN = /^[a-z0-9:._-]{1,80}$/i;
+function sanitizeIdempotencyKey(value) {
+  const raw = String(value == null ? "" : value);
+  return IDEMPOTENCY_KEY_PATTERN.test(raw) ? raw : "invalid";
+}
+
+export function createGlassesVoicemail(deps = {}) {
+  const now = typeof deps.now === "function" ? deps.now : Date.now;
+  const ttlMs = Number.isFinite(deps.ttlMs) ? deps.ttlMs : DEFAULT_VOICEMAIL_TTL_MS;
+  const maxEntries = Number.isFinite(deps.maxEntriesPerInjection)
+    ? deps.maxEntriesPerInjection
+    : VOICEMAIL_MAX_ENTRIES_PER_INJECTION;
+  const drainWakeOutbox =
+    typeof deps.drainWakeOutbox === "function" ? deps.drainWakeOutbox : () => [];
+  const drainDeadLetter =
+    typeof deps.drainDeadLetter === "function" ? deps.drainDeadLetter : () => [];
+  const emitLifecycle =
+    typeof deps.emitLifecycle === "function" ? deps.emitLifecycle : () => {};
+
+  // Outbox entries arrive for ALL sessions on each drain; buffer the
+  // non-target sessions' entries here so one session's prompt build never
+  // destroys another session's owed voicemail. Bounded per session and
+  // TTL-checked AT INGESTION (review P3) — buckets for silent sessions
+  // cannot grow without bound, and empty buckets are deleted.
+  const pendingBySession = new Map(); // normalized sessionKey -> [entry]
+  // Injected-once guard (bounded FIFO), keyed on the CANONICAL per-event key
+  // (surfaceUuid:eventId) so the same parked tap arriving via BOTH the wake
+  // outbox and the dead-letter injects exactly once (review P2).
+  const deliveredKeys = new Set();
+
+  function rememberDelivered(key) {
+    deliveredKeys.add(key);
+    if (deliveredKeys.size > DELIVERED_KEY_CAP) {
+      const oldest = deliveredKeys.values().next().value;
+      deliveredKeys.delete(oldest);
+    }
+  }
+
+  function dedupeKeyOf(entry) {
+    return `${entry.surfaceUuid}:${entry.eventId === null ? 0 : entry.eventId}`;
+  }
+
+  // Route a batch of normalized entries into their sessions' pending buffers:
+  // TTL-expired entries drop here (loudly), and each bucket trims to the cap
+  // (newest kept, loudly). One emit per session per batch.
+  function ingest(entries, nowMs) {
+    const bySession = new Map();
+    for (const entry of entries) {
+      if (!entry.sessionKey) continue;
+      let batch = bySession.get(entry.sessionKey);
+      if (!batch) { batch = []; bySession.set(entry.sessionKey, batch); }
+      batch.push(entry);
+    }
+    for (const [sessionKey, batch] of bySession) {
+      let expired = 0;
+      const fresh = [];
+      for (const entry of batch) {
+        const basisMs = Number.isFinite(entry.owedSinceMs) ? entry.owedSinceMs : nowMs;
+        if (nowMs - basisMs > ttlMs) { expired += 1; continue; }
+        fresh.push(entry);
+      }
+      if (expired > 0) {
+        emitLifecycle("voicemail_expired", "warn", { sessionKey, dropped: expired, ttlMs });
+      }
+      if (fresh.length === 0) continue;
+      const list = pendingBySession.get(sessionKey) || [];
+      list.push(...fresh);
+      if (list.length > VOICEMAIL_PENDING_CAP_PER_SESSION) {
+        const evicted = list.splice(0, list.length - VOICEMAIL_PENDING_CAP_PER_SESSION);
+        emitLifecycle("voicemail_evicted", "warn", { sessionKey, evicted: evicted.length });
+      }
+      pendingBySession.set(sessionKey, list);
+    }
+  }
+
+  // Normalize an owed wake (outbox shape) into the voicemail entry form.
+  function fromOutbox(record) {
+    const surfaceUuid = sanitizeWakeToken(record && record.surfaceUuid);
+    const eventId = coerceInt(record && record.eventId);
+    return {
+      sessionKey: normalizeGlassesSessionKey(record && record.sessionKey) || null,
+      surfaceUuid,
+      eventId,
+      result: sanitizeResult(record && record.result),
+      itemIndex: coerceInt(record && record.itemIndex),
+      queuedAtMs: coerceInt(record && record.queuedAtMs),
+      owedSinceMs: coerceInt(record && record.failedAtMs) ?? coerceInt(record && record.queuedAtMs),
+      idempotencyKey: sanitizeIdempotencyKey(record && record.idempotencyKey),
+      via: record && record.error === "no_dispatch_lane" ? "wake_unavailable" : "wake_failed",
+      staleAfterMs: null,
+      surfaceLive: true,
+    };
+  }
+
+  // Normalize a dead-letter record's events (store shape) into entries.
+  function fromDeadLetter(sessionKey, record) {
+    const surfaceUuid = sanitizeWakeToken(record && record.surfaceUuid);
+    const reason =
+      record && REAP_REASON_ENUM.has(record.reason) ? `reaped:${record.reason}` : "reaped";
+    const staleAfterMs = record && Number.isFinite(record.staleAfterMs) ? record.staleAfterMs : null;
+    const events = record && Array.isArray(record.events) ? record.events : [];
+    return events.map((ev) => {
+      const eventId = coerceInt(ev && ev.eventId);
+      return {
+        sessionKey,
+        surfaceUuid,
+        eventId,
+        result: sanitizeResult(ev && ev.outcome && ev.outcome.result),
+        itemIndex: coerceInt(ev && ev.outcome && ev.outcome.selected_index),
+        queuedAtMs: coerceInt(ev && ev.queuedAtMs),
+        owedSinceMs: coerceInt(ev && ev.queuedAtMs) ?? coerceInt(record && record.reapedAtMs),
+        idempotencyKey: `glasses-voicemail:${surfaceUuid}:${eventId === null ? 0 : eventId}`,
+        via: reason,
+        staleAfterMs,
+        surfaceLive: false,
+      };
+    });
+  }
+
+  function formatEntry(entry, nowMs) {
+    const ageMs = Number.isFinite(entry.queuedAtMs) ? Math.max(0, nowMs - entry.queuedAtMs) : null;
+    const stale =
+      Number.isFinite(entry.staleAfterMs) && ageMs !== null && ageMs > entry.staleAfterMs;
+    const parts = [
+      `- surfaceUuid=${entry.surfaceUuid}`,
+      `eventId=${entry.eventId}`,
+      `result=${entry.result}`,
+      `itemIndex=${entry.itemIndex}`,
+      `queuedAtMs=${entry.queuedAtMs}`,
+      `ageMs=${ageMs}`,
+      `via=${entry.via}`,
+      `idempotencyKey=${entry.idempotencyKey}`,
+    ];
+    if (stale) parts.push("stale=true");
+    parts.push(
+      entry.surfaceLive
+        ? '(surface may still be live: re-render it with update:"patch" to collect)'
+        : "(surface no longer live: treat the refs as the wearer's parked answer to that surface; re-confirm before acting if stale)",
+    );
+    return parts.join(" ");
+  }
+
+  // Sweep ALL buffered buckets for TTL expiry on every build (review round 2):
+  // session keys rotate on relay restarts/reconnects, so abandoned sessions
+  // are a recurring shape — without this, their buckets (each capped, but
+  // unbounded in NUMBER) would outlive them forever. After a sweep, total
+  // buffered memory is bounded by sessions active within one TTL window.
+  function sweepExpired(nowMs) {
+    for (const [key, list] of pendingBySession) {
+      const fresh = list.filter((entry) => {
+        const basisMs = Number.isFinite(entry.owedSinceMs) ? entry.owedSinceMs : nowMs;
+        return nowMs - basisMs <= ttlMs;
+      });
+      const dropped = list.length - fresh.length;
+      if (dropped > 0) {
+        emitLifecycle("voicemail_expired", "warn", { sessionKey: key, dropped, ttlMs });
+      }
+      if (fresh.length === 0) {
+        pendingBySession.delete(key);
+      } else if (dropped > 0) {
+        pendingBySession.set(key, fresh);
+      }
+    }
+  }
+
+  function pendingSessionCount() {
+    return pendingBySession.size;
+  }
+
+  function buildInjection(rawSessionKey) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
+    if (typeof sessionKey !== "string" || !sessionKey) return null;
+    const nowMs = now();
+    sweepExpired(nowMs);
+
+    // Pull both sources through the bounded ingest. The outbox drain returns
+    // every session's entries — non-target ones land in their own buffers.
+    ingest(
+      [
+        ...drainWakeOutbox().map((record) => fromOutbox(record)),
+        ...(drainDeadLetter(sessionKey) || []).flatMap((r) => fromDeadLetter(sessionKey, r)),
+      ],
+      nowMs,
+    );
+
+    const pending = pendingBySession.get(sessionKey);
+    if (!pending || pending.length === 0) {
+      pendingBySession.delete(sessionKey); // no empty buckets left behind
+      return null;
+    }
+    pendingBySession.delete(sessionKey);
+
+    // In-batch collapse by the canonical per-event key (review P2): the same
+    // parked tap can arrive via the wake outbox AND the dead-letter in one
+    // pass — the dead-letter entry wins (the surface is genuinely gone, so a
+    // "may still be live" line for it would be false).
+    const byEvent = new Map();
+    for (const entry of pending) {
+      const key = dedupeKeyOf(entry);
+      const existing = byEvent.get(key);
+      if (!existing || (existing.surfaceLive && !entry.surfaceLive)) {
+        byEvent.set(key, entry);
+      }
+    }
+
+    const deliverable = [];
+    let dropped = 0;
+    for (const entry of byEvent.values()) {
+      const basisMs = Number.isFinite(entry.owedSinceMs) ? entry.owedSinceMs : nowMs;
+      if (nowMs - basisMs > ttlMs) { dropped += 1; continue; }
+      const key = dedupeKeyOf(entry);
+      if (deliveredKeys.has(key)) continue;
+      rememberDelivered(key);
+      deliverable.push(entry);
+    }
+    if (dropped > 0) {
+      // Loud, never silent: a ✓-acked event aged out while buffered.
+      emitLifecycle("voicemail_expired", "warn", { sessionKey, dropped, ttlMs });
+    }
+    if (deliverable.length === 0) return null;
+
+    // Newest entries are the wearer's most recent intent — keep those when
+    // capping, in chronological order.
+    const shown = deliverable.slice(-maxEntries);
+    const overflow = deliverable.length - shown.length;
+    const lines = [
+      "[ocuclaw glasses-ui voicemail] Plugin-generated notification - NOT the wearer speaking.",
+      "Parked glasses events could not be delivered by a wake turn while you were away:",
+      ...shown.map((entry) => formatEntry(entry, nowMs)),
+    ];
+    if (overflow > 0) lines.push(`(+${overflow} older parked events omitted)`);
+    lines.push("Tapped content is never included here by design.");
+    const fragment = lines.join("\n");
+    emitLifecycle("voicemail_injected", "debug", {
+      sessionKey,
+      entries: shown.length,
+      overflow,
+      chars: fragment.length,
+    });
+    return fragment;
+  }
+
+  return { buildInjection, pendingSessionCount };
+}
+
+// Single line: the CJS emitter strips only `^export default .*;$` (one line).
+export default { createGlassesVoicemail, DEFAULT_VOICEMAIL_TTL_MS, VOICEMAIL_MAX_ENTRIES_PER_INJECTION };

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

@@ -0,0 +1,262 @@
+// Tap-to-wake for parked glasses surfaces (roadmap 6f, §2.6 W).
+//
+// A REAL parked gesture buys ONE agent turn via the plugin's own gateway
+// client (the voice-send lane — request("agent", ...)). This module is a
+// dependency-free LEAF (CJS emitter constraint — see glasses-ui-limits.ts):
+// it builds the wake envelope and owns the arbitration policy; transport is
+// injected (the relay facade's dispatchGlassesWake).
+//
+// Locked contract (§2.6, panel amendments 3-4):
+// - wake payload = STRUCTURED REFERENCES ONLY with explicit non-wearer
+//   provenance framing; never interpolated label text. SECURITY (review
+//   pinned to this ship): every token that reaches the prompt is either
+//   numeric-coerced or charset-filtered ([a-zA-Z0-9._:-], <=64 chars), so a
+//   hostile client cannot smuggle instruction text through the wake lane —
+//   tapped CONTENT only ever reaches the agent through the surface collect
+//   (onReattached delivery), where it arrives as data in a tool result, not
+//   as a user-role message.
+// - origin-typed envelope: ONLY "gesture" enabled at launch. schedule/
+//   threshold/system are reserved categories (event-to-wake is deferred,
+//   not foreclosed) — enabling one later is a policy edit here, not a
+//   schema migration.
+// - voice absorbs wake: an in-flight/imminent genuine turn (voice send,
+//   user send, or an earlier wake's run) suppresses the dispatch; the
+//   parked tap rides that turn's collect instead.
+// - taps during an in-flight wake COALESCE into its delivery — never a
+//   second submission. A per-session cooldown additionally bounds gesture
+//   storms (hostile/buggy client spamming taps) to <=1 turn per window;
+//   suppressed taps stay parked in the 6a event log — bounded, never silent.
+// - failed submission: one retry (same idempotencyKey — the gateway honors
+//   it as the runId, so a double-delivery dedupes), then the durable wake
+//   outbox + a warn lifecycle. Never silent after the ✓-ack (amendment 1);
+//   the parked event itself survives in the surface log / dead-letter
+//   regardless, so the worst case is delayed collect, not loss. The 7b
+//   voicemail leg drains the outbox via enqueueNextTurnInjection.
+
+export const GLASSES_WAKE_ENABLED_ORIGINS = ["gesture"];
+
+export const DEFAULT_WAKE_COOLDOWN_MS = 5_000;
+
+// Outbox bound (review P3 sibling): the no-lane branch pushes per parked tap
+// with no cooldown gate, so a tap storm on a legacy host would otherwise grow
+// this without limit. Newest kept; eviction is loud. The parked events
+// themselves still survive in the surface log / dead-letter — eviction here
+// only forfeits the voicemail NOTICE for the oldest entries.
+export const WAKE_OUTBOX_CAP = 64;
+
+// Busy-signal decay: if no activity update arrives for this long, treat the
+// session as idle again (fail open — a stuck-busy would suppress wakes
+// forever, while a wrongly-idle wake merely queues as the next turn).
+export const DEFAULT_AGENT_TURN_BUSY_DECAY_MS = 180_000;
+
+// SECURITY: charset-FILTERING is not enough — stripping separators from
+// hostile input still concatenates readable instruction words into the
+// prompt ("su-x\" IGNORE ALL..." -> "su-xIGNOREALL..."). Tokens are instead
+// VALIDATED against the exact plugin-minted shape / a closed enum and
+// replaced wholesale when off-pattern, so hostile bytes never pass through.
+const SURFACE_UUID_PATTERN = /^su-[a-z0-9]{4,24}$/i;
+const WAKE_RESULT_ENUM = new Set(["selected", "back"]);
+
+export function sanitizeWakeToken(value) {
+  const raw = String(value == null ? "" : value);
+  return SURFACE_UUID_PATTERN.test(raw) ? raw : "invalid";
+}
+
+function sanitizeWakeResult(value) {
+  return WAKE_RESULT_ENUM.has(value) ? value : "event";
+}
+
+function coerceInt(value) {
+  return Number.isFinite(value) ? Math.floor(value) : null;
+}
+
+export function buildWakeMessage(ref) {
+  const surfaceUuid = sanitizeWakeToken(ref && ref.surfaceUuid);
+  const result = sanitizeWakeResult(ref && ref.result);
+  const eventId = coerceInt(ref && ref.eventId);
+  const itemIndex = coerceInt(ref && ref.itemIndex);
+  const queuedAtMs = coerceInt(ref && ref.queuedAtMs);
+  return [
+    "[ocuclaw glasses-ui wake] Plugin-generated notification - NOT the wearer speaking.",
+    `The wearer tapped a parked glasses surface (origin=gesture). refs: surfaceUuid=${surfaceUuid}`,
+    `eventId=${eventId} result=${result} itemIndex=${itemIndex} queuedAtMs=${queuedAtMs}.`,
+    "Tapped content is not included here by design: re-render that surface",
+    "(update:\"patch\") to collect the parked event(s), then respond as appropriate.",
+  ].join(" ");
+}
+
+// Per-session "an agent turn is in flight or imminent" signal. Fed by the
+// relay: markBusy on every dispatched send (voice/user/wake) and onActivity
+// from the gateway activity stream (normalized phase: start/update = busy
+// refresh, end = idle). Lives here (leaf) so it is unit-testable and shared
+// with the relay without a runtime-module cycle.
+export function createAgentTurnTracker(deps = {}) {
+  const now = typeof deps.now === "function" ? deps.now : Date.now;
+  const busyDecayMs = Number.isFinite(deps.busyDecayMs)
+    ? deps.busyDecayMs
+    : DEFAULT_AGENT_TURN_BUSY_DECAY_MS;
+  const lastSeenBySession = new Map(); // normalized sessionKey -> lastSeenMs
+
+  // One session arrives under TWO key forms: the relay send path marks busy
+  // with the stripped relay key ("ocuclaw:<ts>") while the surface store /
+  // gateway hook contexts use the canonical "agent:<id>:<key>". Normalize so
+  // both name the same busy slot — without this, a tap in the send→run-start
+  // window dispatches a second agent submission during an in-flight genuine
+  // turn (live-proven, 2026-06-12 Wave-1 e2e leg 3a).
+  function normalizeKey(sessionKey) {
+    return sessionKey.replace(/^agent:[^:]+:/, "");
+  }
+
+  function markBusy(sessionKey) {
+    if (typeof sessionKey !== "string" || !sessionKey) return;
+    lastSeenBySession.set(normalizeKey(sessionKey), now());
+  }
+
+  function onActivity(sessionKey, phase) {
+    if (typeof sessionKey !== "string" || !sessionKey) return;
+    if (phase === "end") {
+      lastSeenBySession.delete(normalizeKey(sessionKey));
+      return;
+    }
+    lastSeenBySession.set(normalizeKey(sessionKey), now());
+  }
+
+  function isBusy(sessionKey) {
+    if (typeof sessionKey !== "string" || !sessionKey) return false;
+    const key = normalizeKey(sessionKey);
+    const lastSeen = lastSeenBySession.get(key);
+    if (!Number.isFinite(lastSeen)) return false;
+    if (now() - lastSeen >= busyDecayMs) {
+      lastSeenBySession.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  return { markBusy, onActivity, isBusy };
+}
+
+export function createGlassesWakeController(deps = {}) {
+  const dispatchWake = typeof deps.dispatchWake === "function" ? deps.dispatchWake : null;
+  const isAgentTurnBusy =
+    typeof deps.isAgentTurnBusy === "function" ? deps.isAgentTurnBusy : () => false;
+  const emitLifecycle =
+    typeof deps.emitLifecycle === "function" ? deps.emitLifecycle : () => {};
+  const now = typeof deps.now === "function" ? deps.now : Date.now;
+  const wakeCooldownMs = Number.isFinite(deps.wakeCooldownMs)
+    ? deps.wakeCooldownMs
+    : DEFAULT_WAKE_COOLDOWN_MS;
+
+  const inFlightBySession = new Map(); // sessionKey -> promise
+  const lastWakeAtBySession = new Map(); // sessionKey -> ms
+  const outbox = []; // failed/unavailable wakes owed to the 7b voicemail leg
+
+  function pushOutbox(entry) {
+    outbox.push(entry);
+    if (outbox.length > WAKE_OUTBOX_CAP) {
+      const evicted = outbox.splice(0, outbox.length - WAKE_OUTBOX_CAP);
+      emitLifecycle("wake_outbox_evicted", "warn", { evicted: evicted.length });
+    }
+  }
+
+  function refsOnly(ref) {
+    return {
+      sessionKey: typeof ref.sessionKey === "string" ? ref.sessionKey : null,
+      surfaceUuid: sanitizeWakeToken(ref.surfaceUuid),
+      eventId: coerceInt(ref.eventId),
+      result: sanitizeWakeResult(ref.result),
+      itemIndex: coerceInt(ref.itemIndex),
+      // The origin gate below compares against the enum, so a non-enum
+      // origin can never dispatch; keep the raw string for the gate.
+      origin: typeof ref.origin === "string" ? ref.origin : "gesture",
+      queuedAtMs: coerceInt(ref.queuedAtMs),
+    };
+  }
+
+  function suppress(reason, refs) {
+    emitLifecycle("wake_suppressed", "debug", { reason, ...refs });
+    return { dispatched: false, reason };
+  }
+
+  function onParkedGesture(ref) {
+    const refs = refsOnly(ref || {});
+    if (!dispatchWake) {
+      // Wake disabled (legacy host without the relay lane): the parked tap
+      // keeps its collect-on-next-render semantics AND is owed to the 7b
+      // voicemail leg so the next genuine turn hears about it — no longer a
+      // silent early-return. Same gates as a dispatch: enabled origin + a
+      // session to deliver to.
+      if (GLASSES_WAKE_ENABLED_ORIGINS.includes(refs.origin) && refs.sessionKey) {
+        if (refs.queuedAtMs === null) refs.queuedAtMs = now();
+        const idempotencyKey = `glasses-wake:${refs.surfaceUuid}:${refs.eventId === null ? 0 : refs.eventId}`;
+        pushOutbox({
+          ...refs,
+          idempotencyKey,
+          failedAtMs: now(),
+          error: "no_dispatch_lane",
+        });
+        emitLifecycle("wake_unavailable_outboxed", "debug", { ...refs, idempotencyKey });
+      }
+      return { dispatched: false, reason: "no_dispatch_lane" };
+    }
+    if (!GLASSES_WAKE_ENABLED_ORIGINS.includes(refs.origin)) {
+      return suppress("origin_disabled", refs);
+    }
+    const sessionKey = refs.sessionKey;
+    if (!sessionKey) return suppress("no_session", refs);
+    if (isAgentTurnBusy(sessionKey)) {
+      // Voice absorbs wake (§2.6c): the parked event rides the active turn's
+      // collect render or the next genuine turn — no second submission.
+      return suppress("absorbed_by_active_turn", refs);
+    }
+    if (inFlightBySession.has(sessionKey)) {
+      emitLifecycle("wake_coalesced", "debug", refs);
+      return { dispatched: false, reason: "coalesced_into_inflight_wake" };
+    }
+    const lastWakeAt = lastWakeAtBySession.get(sessionKey);
+    if (Number.isFinite(lastWakeAt) && now() - lastWakeAt < wakeCooldownMs) {
+      return suppress("cooldown", refs);
+    }
+
+    if (refs.queuedAtMs === null) refs.queuedAtMs = now();
+    const message = buildWakeMessage(refs);
+    const idempotencyKey = `glasses-wake:${refs.surfaceUuid}:${refs.eventId === null ? 0 : refs.eventId}`;
+    const payload = { sessionKey, message, idempotencyKey };
+    lastWakeAtBySession.set(sessionKey, now());
+    const attempt = () => Promise.resolve(dispatchWake(payload));
+    const flight = attempt()
+      .catch(() => attempt()) // one retry; same idempotencyKey dedupes upstream
+      .then(() => {
+        emitLifecycle("wake_dispatched", "debug", { ...refs, idempotencyKey });
+      })
+      .catch((err) => {
+        // Never silent after the ✓-ack: the owed wake lands in the durable
+        // outbox for the 7b voicemail leg, loudly.
+        pushOutbox({
+          ...refs,
+          idempotencyKey,
+          failedAtMs: now(),
+          error: String((err && err.message) || err),
+        });
+        emitLifecycle("wake_dispatch_failed", "warn", { ...refs, idempotencyKey });
+      })
+      .finally(() => {
+        inFlightBySession.delete(sessionKey);
+      });
+    inFlightBySession.set(sessionKey, flight);
+    return { dispatched: true, idempotencyKey };
+  }
+
+  function peekWakeOutbox() {
+    return outbox.map((r) => ({ ...r }));
+  }
+
+  function drainWakeOutbox() {
+    return outbox.splice(0, outbox.length);
+  }
+
+  return { onParkedGesture, peekWakeOutbox, drainWakeOutbox };
+}
+
+// Single line: the CJS emitter strips only `^export default .*;$` (one line).
+export default { createGlassesWakeController, createAgentTurnTracker, buildWakeMessage, sanitizeWakeToken, GLASSES_WAKE_ENABLED_ORIGINS };

package/dist/version.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ocuclaw",
-  "version": "1.3.2",
-  "requiresClientVersion": "1.3.2",
+  "version": "1.3.3",
+  "requiresClientVersion": "1.3.3",
   "description": "OcuClaw for Even Realities G2 smart glasses.",
   "type": "module",
   "main": "./dist/index.js",

package/skills/glasses-ui/SKILL.md

@@ -6,7 +6,7 @@ user-invocable: false
 
 # Authoring glasses surfaces with `render_glasses_ui`
 
-`render_glasses_ui` paints an interactive surface on the user's Even G2 HUD instead of a text reply. The call blocks until the user selects, dismisses, or backs out. This skill is the source of truth for **authoring** surfaces; the tool description is deliberately lean.
+`render_glasses_ui` paints an interactive surface on the user's Even G2 HUD instead of a text reply. Think in two verbs: the render **paints** (the surface lives on glass, ticking, until the user exits or its refresh budget ends) and the call carries **one one-shot listen** (a bounded window in which a tap resolves your call live). The paint outlives the listen by design. This skill is the source of truth for **authoring** surfaces; the tool description is deliberately lean.
 
 ## Before you author: is the tool loaded?
 
@@ -142,6 +142,20 @@ render_glasses_ui({
 })
 ```
 
+## The interaction window (the listen)
+
+Every call carries **one one-shot listen**: the host waits **90 seconds by default** for the user to act, **up to 600000 ms (10 min) via the optional `timeoutMs` param**. Pass `timeoutMs: 300000–600000` when you expect the user to read or decide; omit it for fire-and-forget paints; never go below 60000 for anything interactive. The listen is **never renewed automatically** — re-rendering opens a fresh one.
+
+When the listen ends without a tap you get a **non-terminal** `{ result: "window_expired", surface_still_live: true }`. **This is not an error and not a paint event** — the surface stays on glass and keeps ticking. From there:
+
+- Taps now **park** (the user sees their tap acknowledged; nothing is lost). Re-render the same surface (`update: "patch"`) to collect parked taps in this run — chain a couple of these listens if you are actively waiting, then stop.
+- Or simply **end your turn** — parked taps **wake you** (one agent turn per real parked gesture, delivered as a refs-only plugin notification; re-render to collect) or ride your next turn. Ending your turn with a surface parked is a normal, cheap state, not an abandonment.
+- **Silence-as-consent**: the window doubles as a default-action deadline. Put the deadline in the body copy ("Merging in 5 min unless you stop me"), give it a matching `timeoutMs`, and treat `window_expired` as consent.
+
+Parked deliveries arrive annotated: `surfaceUuid`, `eventId`, `origin`, `actor`, `queuedAtMs`, `parkedForMs`. For taps that **actuate** something (sell/approve/unlock), declare `staleAfterMs` per render — a tap parked longer arrives with `stale: true`: treat it as a re-confirm prompt, **never** execute it as-is.
+
+(The `await`/listen-without-repaint verb namespace is reserved for a future version — don't repurpose those words in surface copy or tooling.)
+
 ## Outcomes (the `result` you get back)
 
 | result | meaning |
@@ -149,15 +163,17 @@ render_glasses_ui({
 | `selected` | user picked a list item; `selected_index` + `selected_text` returned |
 | `back` | user double-tapped above the root; they want to revise — re-render the previous step or pivot |
 | `dismissed` | dismissed at root, or no selection made |
-| `timeout` | no interaction within the window (non-refresh default 30 min; refresh ends at `maxDurationMs`) |
+| `window_expired` | **non-terminal** — the listen ended, the surface is still live; taps park (see the interaction-window section) |
+| `timeout` | terminal hygiene cap (rare); a refresh surface ends at `maxDurationMs` |
 | `recipe_failed` | refresh only — initial smoke tick failed, the consecutive-failure breaker fired, or `onError:stop`; `failureReason` carries the last error |
 | `glasses_disconnected` | refresh only — the glasses client dropped mid-cron |
 
-Refresh results also carry: `ticks: { count, succeeded, failed, lastSuccessAt, lastFailureAt? }`, `lastBody`, `lastItems`, and `failureReason` (on `recipe_failed`).
+Every delivery carries the surface's durable `surfaceUuid` plus `origin` (`gesture` for wearer actions, `system` for plugin-initiated outcomes) and an `actor` slot. Refresh results also carry: `ticks: { count, succeeded, failed, lastSuccessAt, lastFailureAt? }`, `lastBody`, `lastItems`, and `failureReason` (on `recipe_failed`).
 
 ## Quick reference
 
 - Pick the **lowest tier**: host metrics → `system-stats`; pure data API → `http` (not enabled yet). Needs interpretation → render once from your turn.
 - `update` default is `replace` (in-place). Use `push` to drill in without losing the parent; `patch` to edit fields while the cron keeps ticking.
+- The listen is one-shot: default 90 s, `timeoutMs` up to 600000 (use 300000–600000 for read-or-decide). `window_expired` ≠ error — re-render to collect parked taps, or end your turn (they wake you / ride the next turn).
 - `intervalMs` ≥ 1000. Read `failureReason` on `recipe_failed` and fix the recipe.
 - After a surface resolves, a short text reply exits to chat; another render replaces; silence lets it linger.