ocuclaw 1.3.0 → 1.3.2

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

@@ -1,53 +1,17 @@
-// Recipe executors for glasses_ui_refresh. Three kinds: shell (spawn bash),
-// http (in-process fetch), and llm (added in Task 3 — four backends behind
-// one dispatcher). All return either { output } or { error: <string> }.
+// Recipe executors for glasses_ui_refresh. Kinds: http (in-process fetch),
+// llm (two HTTP API backends behind one dispatcher), and system-stats
+// (in-process node:os reads). All return either { output } or
+// { error: <string> }. The shell (spawn bash) and llm claude-cli
+// (spawn claude) backends were removed to drop the plugin's last
+// child_process spawn — see the backends comment in config/runtime-config.ts.
 //
 // output is `string` for plain text and `object` for JSON. The cron engine
 // hands `output` to the template engine which handles both shapes.
 
-import { spawn } from "node:child_process";
-import { tmpdir, totalmem, freemem, loadavg, cpus } from "node:os";
+import { totalmem, freemem, loadavg, cpus } from "node:os";
 import * as dns from "node:dns";
 import { Agent } from "undici";
 
-// Env vars allowed to cross into the spawned Claude CLI subprocess.
-// Everything else is stripped — Claude reads its own auth from ~/.claude/
-// (reachable via HOME), so cloud-provider keys (AWS_*, GOOGLE_*,
-// ANTHROPIC_API_KEY, OPENAI_API_KEY, *_SECRET, *_TOKEN) and database URLs
-// must never reach the agent the CLI is running. Operators who want an
-// API key in the LLM-tick path use the *-api backends, which read the key
-// via the host's modelAuth resolver — not from spawn env.
-const CLI_SPAWN_ENV_ALLOWLIST = [
-  "PATH",
-  "HOME",
-  "USER",
-  "LOGNAME",
-  "SHELL",
-  "TERM",
-  "LANG",
-  "TZ",
-  "XDG_CONFIG_HOME",
-  "XDG_CACHE_HOME",
-  "XDG_DATA_HOME",
-  "XDG_RUNTIME_DIR",
-  "NODE_OPTIONS",
-];
-const CLI_SPAWN_ENV_ALLOWLIST_PREFIXES = ["LC_"];
-
-function buildScopedSpawnEnv() {
-  const sourceEnv = process.env || {};
-  const out = {};
-  for (const k of CLI_SPAWN_ENV_ALLOWLIST) {
-    if (typeof sourceEnv[k] === "string") out[k] = sourceEnv[k];
-  }
-  for (const k of Object.keys(sourceEnv)) {
-    if (CLI_SPAWN_ENV_ALLOWLIST_PREFIXES.some((p) => k.startsWith(p))) {
-      out[k] = sourceEnv[k];
-    }
-  }
-  return out;
-}
-
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_OUTPUT_CAP_BYTES = 64 * 1024;
 
@@ -71,77 +35,6 @@ function parseJsonIfPossible(text) {
   }
 }
 
-export async function executeShellRecipe(params) {
-  const command = params && typeof params.command === "string" ? params.command : "";
-  if (!command) {
-    return { error: "shell recipe missing command" };
-  }
-  const timeoutMs = Number.isFinite(params && params.timeoutMs)
-    ? params.timeoutMs
-    : DEFAULT_TIMEOUT_MS;
-  const outputCapBytes = Number.isFinite(params && params.outputCapBytes)
-    ? params.outputCapBytes
-    : DEFAULT_OUTPUT_CAP_BYTES;
-
-  return new Promise((resolve) => {
-    const child = spawn("bash", ["-c", command], {
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    const chunks = [];
-    const errChunks = [];
-    let bytes = 0;
-    let truncated = false;
-    let done = false;
-
-    const finish = (result) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      try { child.kill("SIGKILL"); } catch (_) { /* already exited */ }
-      resolve(result);
-    };
-
-    const timer = setTimeout(() => {
-      finish({ error: `shell recipe timeout after ${timeoutMs}ms` });
-    }, timeoutMs);
-
-    child.stdout.on("data", (chunk) => {
-      if (bytes + chunk.length > outputCapBytes) {
-        const remaining = outputCapBytes - bytes;
-        if (remaining > 0) chunks.push(chunk.slice(0, remaining));
-        bytes = outputCapBytes;
-        truncated = true;
-        try { child.kill("SIGTERM"); } catch (_) {}
-      } else {
-        chunks.push(chunk);
-        bytes += chunk.length;
-      }
-    });
-
-    child.stderr.on("data", (chunk) => {
-      if (errChunks.length < 32) errChunks.push(chunk);
-    });
-
-    child.on("error", (err) => {
-      finish({ error: `shell recipe spawn error: ${err && err.message ? err.message : err}` });
-    });
-
-    child.on("close", (code, signal) => {
-      const stdout = Buffer.concat(chunks).toString("utf8");
-      if (code !== 0 && !truncated) {
-        const stderr = Buffer.concat(errChunks).toString("utf8").trim();
-        finish({
-          error: signal
-            ? `shell recipe killed by ${signal}`
-            : `shell recipe exit code ${code}${stderr ? ": " + stderr.slice(0, 200) : ""}`,
-        });
-        return;
-      }
-      finish({ output: parseJsonIfPossible(stdout) });
-    });
-  });
-}
-
 function checkIpv4Tuple(a, b) {
   if (a === 127) return "loopback IPv4 blocked";
   if (a === 10) return "RFC1918 IPv4 blocked";
@@ -504,67 +397,11 @@ function stripModelProviderPrefix(modelRef) {
   return idx === -1 ? modelRef : modelRef.slice(idx + 1);
 }
 
-async function runClaudeCli(params, deps) {
-  const spawnFn = deps && deps.spawn ? deps.spawn : spawn;
-  const promptText =
-    (params.systemPrompt ? params.systemPrompt + "\n\n" : "") + params.prompt;
-  const model = stripModelProviderPrefix(params.model);
-  // Lock the spawned Claude CLI to plan-mode with an empty toolset so the
-  // tick prompt can't drive file/shell/web tools to exfil. --bare disables
-  // hooks, plugin sync, CLAUDE.md auto-discovery, and keychain reads — the
-  // CLI runs as a pure text-in/text-out worker.
-  const args = [
-    "-p", promptText,
-    "--output-format", "text",
-    "--permission-mode", "plan",
-    "--tools", "",
-    "--bare",
-  ];
-  if (model) args.push("--model", model);
-  const timeoutMs = Number.isFinite(params.timeoutMs) ? params.timeoutMs : 60_000;
-
-  return new Promise((resolve) => {
-    const child = spawnFn("claude", args, {
-      stdio: ["ignore", "pipe", "pipe"],
-      cwd: tmpdir(),
-      env: buildScopedSpawnEnv(),
-    });
-    const chunks = [];
-    const errChunks = [];
-    let done = false;
-    const finish = (result) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      try { child.kill && child.kill("SIGKILL"); } catch (_) {}
-      resolve(result);
-    };
-    const timer = setTimeout(
-      () => finish({ error: `claude-cli timeout after ${timeoutMs}ms` }),
-      timeoutMs,
-    );
-    child.stdout.on("data", (c) => chunks.push(c));
-    child.stderr.on("data", (c) => errChunks.push(c));
-    child.on("error", (err) => finish({ error: `claude-cli spawn error: ${err.message}` }));
-    child.on("close", (code) => {
-      if (code !== 0) {
-        const stderr = Buffer.concat(errChunks).toString("utf8").trim();
-        finish({ error: `claude-cli exit code ${code}${stderr ? ": " + stderr.slice(0, 200) : ""}` });
-        return;
-      }
-      finish({ output: Buffer.concat(chunks).toString("utf8") });
-    });
-  });
-}
-
-// codex-cli backend removed (round-5 autoreview): Codex's `read-only`
-// sandbox blocks writes and exec but still permits filesystem reads, so
-// an agent prompt could drive the spawned process to read ~/.aws/credentials,
-// ~/.ssh/*, etc. and emit them through stdout → glasses body. Claude CLI
-// is structurally safe because --tools "" disables every tool including
-// Read; Codex has no equivalent flag. Operators who want Codex point an
-// openai-compat backend at https://api.openai.com (or wherever Codex is
-// served) — that path has no tool surface at all.
+// Both CLI-spawn backends (codex-cli, claude-cli) were removed to eliminate
+// the plugin's last child_process spawn — see the backends comment in
+// config/runtime-config.ts for the rationale and the deferred native-delegation
+// track. Operators who want those providers point an *-api backend at the
+// provider endpoint (key resolved via the host modelAuth, tool-less).
 
 async function runAnthropicApi(params, deps) {
   const fetchFn = deps && deps.fetch ? deps.fetch : fetch;
@@ -666,8 +503,6 @@ export async function executeLlmRecipeWithDeps(recipe, ctx, deps) {
   };
   if (!baseParams.prompt) return { error: "llm recipe missing prompt" };
   switch (backend) {
-    case "claude-cli":
-      return runClaudeCli(baseParams, deps || {});
     case "anthropic-api":
       return runAnthropicApi(baseParams, deps || {});
     case "openai-compat":
@@ -743,4 +578,4 @@ export async function executeSystemStatsRecipe(params, opts) {
   }
 }
 
-export default { executeShellRecipe, executeHttpRecipe, executeLlmRecipe, executeLlmRecipeWithDeps, executeSystemStatsRecipe, computeCpuPct };
+export default { executeHttpRecipe, executeLlmRecipe, executeLlmRecipeWithDeps, executeSystemStatsRecipe, computeCpuPct };

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

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

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

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

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

@@ -7,7 +7,6 @@
 import { validateTemplate } from "./glasses-ui-template.js";
 import { createGlassesUiCronEngine } from "./glasses-ui-cron.js";
 import {
-  executeShellRecipe,
   executeHttpRecipe,
   executeLlmRecipe,
   executeSystemStatsRecipe,
@@ -32,7 +31,7 @@ import {
 export { createPendingRenderMap, createSurfaceStore, GLASSES_UI_LIMITS };
 
 export const GLASSES_UI_REFRESH_LIMITS = {
-  intervalMsMin: { shell: 1000, http: 1000, "system-stats": 1000, "llm-cli": 60_000, "llm-api": 30_000 },
+  intervalMsMin: { http: 1000, "system-stats": 1000, "llm-api": 30_000 },
   intervalMsMax: 3_600_000,
   maxDurationMsMin: 10_000,
   maxDurationMsMax: 7_200_000,
@@ -63,13 +62,6 @@ export const GLASSES_UI_REFRESH_LIMITS = {
 
 const ON_ERROR_VALUES = new Set(["keep_last", "show_error", "stop"]);
 
-function llmIntervalMinForBackend(backend) {
-  if (backend === "claude-cli") {
-    return GLASSES_UI_REFRESH_LIMITS.intervalMsMin["llm-cli"];
-  }
-  return GLASSES_UI_REFRESH_LIMITS.intervalMsMin["llm-api"];
-}
-
 // 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,
@@ -92,8 +84,8 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     return { ok: false, code: "refresh_invalid_recipe", message: "refresh.recipe is required" };
   }
   const kind = recipe.kind;
-  if (kind !== "shell" && kind !== "http" && kind !== "llm" && kind !== "system-stats") {
-    return { ok: false, code: "refresh_invalid_recipe", message: `recipe.kind must be shell/http/llm/system-stats, got ${JSON.stringify(kind)}` };
+  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
@@ -105,23 +97,7 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     if (raw < min || raw > max) return undefined; // signal out-of-range
     return Math.floor(raw);
   };
-  if (kind === "shell") {
-    if (cfg.shellEnabled === false) return { ok: false, code: "refresh_disabled", message: "shell recipes disabled" };
-    if (typeof recipe.command !== "string" || !recipe.command.trim()) {
-      return { ok: false, code: "refresh_invalid_recipe", message: "shell recipe requires command (non-empty string)" };
-    }
-    sanitizedRecipe.command = recipe.command;
-    if (recipe.timeoutMs !== undefined) {
-      const v = bounded(recipe.timeoutMs, GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMin, GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMax);
-      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `shell.timeoutMs ${recipe.timeoutMs} out of bounds [${GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMin}..${GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMax}]` };
-      if (v !== null) sanitizedRecipe.timeoutMs = v;
-    }
-    if (recipe.outputCapBytes !== undefined) {
-      const v = bounded(recipe.outputCapBytes, GLASSES_UI_REFRESH_LIMITS.outputCapBytesMin, GLASSES_UI_REFRESH_LIMITS.outputCapBytesMax);
-      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `shell.outputCapBytes ${recipe.outputCapBytes} out of bounds` };
-      if (v !== null) sanitizedRecipe.outputCapBytes = v;
-    }
-  } else if (kind === "http") {
+  if (kind === "http") {
     if (cfg.httpEnabled === false) return { ok: false, code: "refresh_disabled", message: "http recipes disabled" };
     if (typeof recipe.url !== "string" || !recipe.url.trim()) {
       return { ok: false, code: "refresh_invalid_recipe", message: "http recipe requires url (non-empty string)" };
@@ -159,7 +135,7 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     }
   } else if (kind === "system-stats") {
     // Built-in tier: host RAM/CPU via the in-process structured reader. NOT gated
-    // by httpEnabled/shellEnabled/llmEnabled — it touches no network, no shell, no
+    // 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) {
@@ -176,7 +152,7 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
   }
   const minForKind =
     kind === "llm"
-      ? llmIntervalMinForBackend(cfg.tickBackend)
+      ? GLASSES_UI_REFRESH_LIMITS.intervalMsMin["llm-api"]
       : GLASSES_UI_REFRESH_LIMITS.intervalMsMin[kind];
   const minEffective = effectiveIntervalFloorMs(minForKind);
   if (intervalMs < minEffective) {
@@ -307,16 +283,6 @@ const refreshSchemaForToolParams = {
     },
     recipe: {
       oneOf: [
-        {
-          type: "object",
-          required: ["kind", "command"],
-          properties: {
-            kind: { const: "shell" },
-            command: { type: "string" },
-            timeoutMs: { type: "integer" },
-            outputCapBytes: { type: "integer" },
-          },
-        },
         {
           type: "object",
           required: ["kind", "url"],
@@ -536,7 +502,6 @@ export function createGlassesUiToolHandler(deps) {
     emitLifecycle,
     monotonicNowMs: () => performance.now(),
     executeRecipe: async (recipe, ctx) => {
-      if (recipe.kind === "shell") return executeShellRecipe(recipe);
       if (recipe.kind === "http") return executeHttpRecipe(recipe);
       if (recipe.kind === "system-stats") return executeSystemStatsRecipe(recipe);
       if (recipe.kind === "llm") return executeLlmRecipe(recipe, ctx);
@@ -555,7 +520,7 @@ export function createGlassesUiToolHandler(deps) {
         ? Math.min(state.recipe.maxOutputTokens, cfg.tickMaxOutputTokens || 200)
         : (cfg.tickMaxOutputTokens || 200);
       return {
-        backend: cfg.tickBackend || "claude-cli",
+        backend: cfg.tickBackend || "anthropic-api",
         model,
         baseUrl: cfg.tickApiBaseUrl || "",
         apiKey: deps.resolveLlmApiKey ? deps.resolveLlmApiKey(model) : "",
@@ -577,8 +542,8 @@ export function createGlassesUiToolHandler(deps) {
     // parent/chat after a back/pop, and the per-surface coalescer state doesn't
     // leak across a long push/replace session. (pauseCron on push does NOT
     // dispose — the parent resumes.)
-    stopCron: (id) => {
-      cronEngine.stop(id, { result: "preempted" });
+    stopCron: (id, opts) => {
+      cronEngine.stop(id, { result: "preempted" }, opts);
       paintFloor.dispose(id);
     },
     mintSurfaceId: newSurfaceId,
@@ -645,11 +610,33 @@ export function createGlassesUiToolHandler(deps) {
       refreshValidated = v.refresh;
     }
 
+    // params.depth is the execute-level RUN-CALL ordinal (resets at agent_end).
+    // It is used ONLY as the "first render of this run" signal for stale-stack
+    // reaping below — it must NEVER reach the wire. The wire depth is derived
+    // from the store's true stack depth after applyRender (B6: ordinals never
+    // decrement on Back, so they drift past entry counts and break both the
+    // plugin pop reconciliation and the client's clear-vs-append decision).
     const depth = Number.isFinite(params.depth) ? Math.max(1, Math.floor(params.depth)) : 1;
     const update =
       params.spec && (params.spec.update === "patch" || params.spec.update === "push")
         ? params.spec.update
         : "replace";
+    // Stale-stack reaping (B3 safety net): a depth-1 render means NEW ROOT — a
+    // session stack still holding PUSHED children at that moment is orphan
+    // residue from an earlier run (e.g. a client that bailed to chat without
+    // popping). Reap it before registering so a stale child can't swallow this
+    // render's events or forward a stale latched exit. A SINGLE root entry is
+    // NOT stale — that's the designed patch/replace re-attach path
+    // (visible_awaiting_agent), which must keep its latch/queue semantics.
+    if (depth <= 1 && surfaceStore.stackDepth(sessionKey) > 1) {
+      const stackDepthBefore = surfaceStore.stackDepth(sessionKey);
+      const reapedPending = reapSession(sessionKey, { result: "preempted" });
+      emitLifecycle("stale_stack_reaped", "warn", {
+        sessionKey,
+        stackDepthBefore,
+        reapedPending,
+      });
+    }
     // The plugin owns surfaceIds (spec §Core model). applyRender derives the
     // target from the session's current top: patch/replace reuse the top id
     // (re-attach in place), push mints a child + pauses the parent cron, the
@@ -681,6 +668,12 @@ export function createGlassesUiToolHandler(deps) {
       }
     }
 
+    // The wire depth is the TRUE stack depth (entry count) after applyRender:
+    // root=1, push=parent+1, replace/patch=unchanged. The client keys its
+    // clear-vs-append-vs-swap decision and Back classification on this value,
+    // and handleNavEvent's pop loop compares it against the same entry counts.
+    const wireDepth = Math.max(1, surfaceStore.stackDepth(sessionKey));
+
     // Initial render uses the agent's seed (instant). Routed through the
     // paint-floor coalescer as a leading-edge render sentinel so it shares the
     // single send chokepoint (a render supersedes any queued field patch for
@@ -688,7 +681,7 @@ export function createGlassesUiToolHandler(deps) {
     paintFloor.enqueue({
       surfaceId,
       sessionKey,
-      patch: { __render: true, __depth: depth, __spec: validation.spec },
+      patch: { __render: true, __depth: wireDepth, __spec: validation.spec },
     });
 
     // Live-refresh path: kick off the cron in parallel. A `patch` onto an
@@ -697,10 +690,9 @@ export function createGlassesUiToolHandler(deps) {
     // 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.
-      // For the claude-cli backend the resolved key is "" and not consumed
-      // (the CLI auths via its own login), so the prewarm is a harmless
-      // no-op there.
+      // 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 =
@@ -812,6 +804,21 @@ export function createGlassesUiToolHandler(deps) {
         guard += 1;
       }
     }
+    if (
+      popCount === 0 &&
+      storeDepthBefore > 1 &&
+      surfaceStore.topSurfaceId(sessionKey) === ev.surfaceId
+    ) {
+      // Surface-match fallback (B6): a Back event reports the surfaceId being
+      // backed OUT OF — the store top. If the depth comparison said no-op
+      // (drifted ordinals from an older client, or any depth desync) but the
+      // reported surface IS the top with a parent beneath, pop exactly one
+      // level. Push events carry the PARENT surfaceId — never the top after a
+      // push — so this cannot misfire on a push report; and a duplicate Back
+      // delivery is idempotent (after the pop the top no longer matches).
+      resumedParent = surfaceStore.popBack(sessionKey);
+      popCount += 1;
+    }
     // Push (newDepth > lastDepth) is already reflected in the store by the
     // agent's push render (applyRender), so it is intentionally a no-op here.
     emitLifecycle("nav_reconcile", "debug", {
@@ -827,19 +834,25 @@ export function createGlassesUiToolHandler(deps) {
     navDepthBySession.set(sessionKey, newDepth);
   }
 
+  // Stop crons, resolve pending calls with `outcome`, clear the session stack.
+  // Resolve pending + delete entries FIRST (so pending calls settle with
+  // `outcome`), THEN clear the per-session stack. exit() deletes entries
+  // without resolving, so it must NOT run before the drain or the pending
+  // promises would hang. Shared by the public drainSession (agent_end /
+  // disconnect) and the stale-stack reap in runDynamicUi (B3).
+  function reapSession(sessionKey, outcome) {
+    cronEngine.stopAllForSession(sessionKey, outcome);
+    const reaped = surfaceStore.drainSession(sessionKey, outcome);
+    surfaceStore.exit(sessionKey); // clear the stack (crons already stopped)
+    navDepthBySession.delete(sessionKey); // drop stale nav depth (stack is now 0)
+    return reaped;
+  }
+
   return {
     runDynamicUi,
     handleNavEvent,
     drainSession(sessionKey, outcome) {
-      cronEngine.stopAllForSession(sessionKey, outcome);
-      // Resolve pending + delete entries FIRST (so pending calls settle with
-      // `outcome`), THEN clear the per-session stack. exit() deletes entries
-      // without resolving, so it must NOT run before the drain or the pending
-      // promises would hang.
-      const reaped = surfaceStore.drainSession(sessionKey, outcome);
-      surfaceStore.exit(sessionKey); // clear the stack (crons already stopped)
-      navDepthBySession.delete(sessionKey); // drop stale nav depth (stack is now 0)
-      return reaped;
+      return reapSession(sessionKey, outcome);
     },
     drainAll(outcome) {
       cronEngine.stopAll(outcome);
@@ -894,6 +907,13 @@ export const GLASSES_UI_TOOL_DESCRIPTION = [
   "exit-to-chat policy, the {{path|filter}} template + per-item {label,body}",
   "reference, and worked examples (including a live system-stats",
   "list_with_details surface). Keep this description lean; depth lives in the skill.",
+  "",
+  "After the call resolves, your NEXT output decides the glasses: another",
+  "render_glasses_ui replaces the surface (drill-down / next step); a short text",
+  "reply hands the screen back to chat (the surface disappears); a silent run-end",
+  "leaves the surface up until the user dismisses it. A \"back\" result means the",
+  "user wants to revise their previous answer — re-render it or pivot; after a",
+  "\"selected\" result, follow up with another render or a brief one-line ack.",
 ].join("\n");
 
 // Shared per-session depth counter. OpenClaw loads the plugin's register(api)
@@ -1067,10 +1087,28 @@ export function registerGlassesUiTool(api, service) {
   // Reconcile client nav-events with the SINGLE store stack (Task 16). On pop
   // the client reports the surfaceId now back on top + the post-pop depth; the
   // store knows it. The relay frame carries no sessionKey, so resolve it from
-  // the surface's store entry (sessionForSurface), falling back to "main".
+  // the surface's store entry (sessionForSurface). Every plugin-load context
+  // registers one of these handlers on the SHARED relay, so each nav-event
+  // fans out to N contexts but at most one context's store knows the surface —
+  // a context that cannot resolve it must NO-OP. (The old "main" fallback made
+  // the sibling contexts reconcile an empty store carrying stale cross-session
+  // lastDepth: the 3-4x duplicate nav_reconcile on hardware, bug B2.)
   if (typeof service.onGlassesUiNavEvent === "function") {
     service.onGlassesUiNavEvent((ev) => {
-      const sessionKey = handler.sessionForSurface(ev.surfaceId) || "main";
+      const sessionKey = handler.sessionForSurface(ev.surfaceId);
+      if (!sessionKey) {
+        try {
+          if (typeof service.emitGlassesUiLifecycle === "function") {
+            service.emitGlassesUiLifecycle("nav_event_skipped_foreign_surface", "debug", {
+              evSurfaceId: ev.surfaceId,
+              evDepth: ev.depth,
+            });
+          }
+        } catch (_) {
+          // observability must never break the nav path
+        }
+        return;
+      }
       handler.handleNavEvent(sessionKey, ev);
     });
   }