ocuclaw 1.3.0 → 1.3.2

package/dist/runtime/session-title-distiller.js

@@ -0,0 +1,354 @@
+import * as nodePath from "node:path";
+import {
+  isDistillerSessionKey,
+  sanitizeTitle,
+  buildExcerpt,
+  buildDistillerAgentParams,
+  internalTranscriptFilename,
+  DISTILLER_SESSION_PREFIX,
+  extractAssistantTitleFromMessages,
+  splitModelRef,
+} from "./session-title-distiller-helpers.js";
+import { isUserOrigin } from "./session-title-record.js";
+
+const PROMPT_INSTRUCTION =
+  "You are titling a chat session. Read the recent conversation below and reply " +
+  "with a 2-5 word noun-phrase title (≤55 chars), or exactly SKIP if no concrete " +
+  "topic has emerged yet. Reply with the title only — no quotes, no punctuation, " +
+  "no explanation.\n\n";
+
+/**
+ * Whether an agent.wait result means the run has actually TERMINATED (vs. the
+ * wait itself timing out while the run keeps going). Defensive about the exact
+ * result shape: an unknown/empty result is treated as terminal so cleanup never
+ * loops forever; an explicit wait-timeout / still-running status is non-terminal.
+ */
+export function runWaitTerminal(result) {
+  if (!result || typeof result !== "object") return true;
+  if (result.endedAt != null) return true;
+  if (result.stopReason != null) return true;
+  if (result.timeoutPhase) return false;
+  if (typeof result.status === "string") {
+    return !/^(running|active|pending|in_progress|started|accepted)$/i.test(result.status);
+  }
+  return true;
+}
+
+export function createSessionTitleDistiller(deps) {
+  const {
+    stateDir, getStateDir, nowMs, genId, emitDebug, getSessionTitleModel,
+    conversationState, sessionService, isEvenAiSessionKey,
+    gatewayBridge, fs, budget, subagentRuntime, cleanupDistillerSession,
+  } = deps;
+  const timeoutMs = Number.isFinite(deps.timeoutMs) ? deps.timeoutMs : 30000;
+  const now = typeof nowMs === "function" ? nowMs : () => Date.now();
+  const dbg = typeof emitDebug === "function" ? emitDebug : () => {};
+
+  const inFlight = new Set();
+
+  // Latched on the first dispatch-time subagent failure (request-scoped
+  // runtime on 2026.6.x): later runs go straight to the raw-RPC bridge. A
+  // gateway restart re-probes naturally (fresh distiller instance).
+  let subagentDispatchUnusable = false;
+
+  // Resolve the state dir LAZILY (at cleanup time): the distiller is constructed
+  // during plugin registration, before service.start() receives ctx.stateDir, so
+  // an eagerly-captured value would be undefined and the transcript (containing
+  // the conversation excerpt) would never be deleted from the real state dir.
+  function resolveStateDir() {
+    if (typeof getStateDir === "function") {
+      const dir = getStateDir();
+      if (typeof dir === "string" && dir.trim()) return dir;
+    }
+    return typeof stateDir === "string" && stateDir.trim() ? stateDir : ".";
+  }
+  function transcriptPath(runId) {
+    return nodePath.join(resolveStateDir(), "internal-agent-runs", internalTranscriptFilename(runId));
+  }
+
+  function triggerGatesPass(sessionKey) {
+    if (isDistillerSessionKey(sessionKey)) return false;
+    if (typeof isEvenAiSessionKey === "function" && isEvenAiSessionKey(sessionKey)) return false;
+    if (!sessionService.isNeuralSessionNamesEnabled(sessionKey)) return false;
+    if (!sessionService.hasRecordedUserMessage(sessionKey)) return false;
+    const rec = sessionService.getSessionTitleRecord(sessionKey);
+    if (rec && rec.title) return false; // already has a real OcuClaw title record
+    if (sessionService.isSessionUserLocked(sessionKey)) return false;
+    if (inFlight.has(sessionKey)) return false;
+    if (budget && typeof budget.canRun === "function" && !budget.canRun(sessionKey)) return false;
+    return true;
+  }
+
+  // Subscribe up front and resolve when an assistant `message` arrives whose
+  // runId matches the gateway's ACCEPTED run id. `matchRunId()` returns null
+  // until the agent ack resolves it: the idempotencyKey we send is NOT the run
+  // id the gateway echoes on message events (it returns its own accepted runId
+  // in the ack), so filtering by the idempotencyKey would never match. Mirrors
+  // even-ai-run-waiter, which waits on the ack's runId.
+  function captureAssistantText(matchRunId) {
+    let off = null;
+    let settled = false;
+    let resolveFn = null;
+    const finish = (text) => {
+      if (settled) return;
+      settled = true;
+      if (typeof off === "function") off();
+      clearTimeout(timer);
+      if (typeof resolveFn === "function") resolveFn(text);
+    };
+    const timer = setTimeout(() => finish(null), timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+    const promise = new Promise((resolve) => {
+      resolveFn = resolve;
+    });
+    off = gatewayBridge.on("message", (data) => {
+      const expected = matchRunId();
+      if (!expected || !data || data.runId !== expected) return;
+      if (data.role && data.role !== "assistant") return;
+      const content = data.content;
+      const text = typeof content === "string"
+        ? content
+        : Array.isArray(content)
+          ? content.filter((b) => b && b.type === "text" && typeof b.text === "string").map((b) => b.text).join("")
+          : "";
+      finish(text);
+    });
+    return { promise, dispose: () => finish(null) };
+  }
+
+  function applyDistilledTitle(sessionKey, acceptedRunId, text) {
+    const title = sanitizeTitle(text);
+    if (!title) {
+      dbg("relay.session", "distiller_skip", "debug", { sessionKey, runId: acceptedRunId }, () => ({}));
+      return "skip";
+    }
+    // Apply-time recheck: trigger-time gates are stale by now. Re-check the
+    // feature toggle (the user may have turned automatic titling OFF while the
+    // run was in flight) as well as the title record / lock.
+    const featureOff = !sessionService.isNeuralSessionNamesEnabled(sessionKey);
+    const rec = sessionService.getSessionTitleRecord(sessionKey);
+    const locked = sessionService.isSessionUserLocked(sessionKey);
+    if (featureOff || (rec && rec.title) || locked || (rec && isUserOrigin(rec.origin))) {
+      dbg("relay.session", "stale_discarded", "info", { sessionKey, runId: acceptedRunId }, () => ({ title }));
+      return "skip";
+    }
+    const res = sessionService.setSessionTitle(sessionKey, title, { origin: "topic_distiller" });
+    if (res && res.ok) {
+      dbg("relay.session", "distiller_titled", "info", { sessionKey, runId: acceptedRunId }, () => ({ title }));
+      return "applied";
+    }
+    dbg("relay.session", "distiller_apply_refused", "info", { sessionKey, runId: acceptedRunId },
+      () => ({ code: res && res.code ? res.code : null }));
+    return "skip";
+  }
+
+  function buildDistillerInput(opts) {
+    const idempotencyKey = genId();
+    const distillerKey = `${DISTILLER_SESSION_PREFIX}${idempotencyKey}`;
+    const rawMessages =
+      opts && Array.isArray(opts.messages)
+        ? opts.messages
+        : conversationState && typeof conversationState.getRawMessages === "function"
+          ? conversationState.getRawMessages()
+          : [];
+    const excerpt = buildExcerpt(rawMessages, {});
+    const message = `${PROMPT_INSTRUCTION}${excerpt}`;
+    const model = typeof getSessionTitleModel === "function" ? getSessionTitleModel() : "";
+    return { idempotencyKey, distillerKey, message, model };
+  }
+
+  async function runOnceViaGatewayBridge(sessionKey, opts) {
+    const { idempotencyKey, distillerKey, message, model } = buildDistillerInput(opts);
+    // Prefer the messages captured at agent_end (the completed run's transcript,
+    // snapshotted before this fire-and-forget run defers). Only fall back to the
+    // live conversation state if none were passed — that global state can belong
+    // to a different session by the time this deferred run executes.
+    const params = buildDistillerAgentParams({
+      sessionKey: distillerKey, idempotencyKey, message, model,
+    });
+
+    // The gateway returns its accepted runId in the ack and echoes THAT on the
+    // message stream + names the internal transcript by it. Resolve it before
+    // awaiting the capture; subscribe up front so an early message isn't missed.
+    let acceptedRunId = null;
+    const capture = captureAssistantText(() => acceptedRunId);
+    dbg("relay.session", "distiller_run_started", "debug", { sessionKey }, () => ({ chars: message.length, idempotencyKey, via: "gateway-bridge" }));
+
+    let outcome = "error";
+    try {
+      const ack = await gatewayBridge.request("agent", params, { expectFinal: false });
+      acceptedRunId =
+        ack && typeof ack.runId === "string" && ack.runId.trim()
+          ? ack.runId.trim()
+          : idempotencyKey;
+      const text = await capture.promise;
+      outcome = applyDistilledTitle(sessionKey, acceptedRunId, text);
+    } catch (err) {
+      outcome = "error";
+      dbg("relay.session", "distiller_error", "warn", { sessionKey, runId: acceptedRunId || idempotencyKey },
+        () => ({ message: err && err.message ? err.message : String(err), via: "gateway-bridge" }));
+    } finally {
+      capture.dispose();
+      // The run continues after our local capture (expectFinal:false enqueue), so
+      // wait for it to actually terminate before deleting its transcript —
+      // otherwise a slow run can write the excerpt-bearing transcript AFTER this
+      // cleanup and leave it on disk. Bounded by timeoutMs + best-effort
+      // (unsupported/timeout/error just proceeds to the delete).
+      if (acceptedRunId) {
+        // agent.wait may return a non-terminal timeout while the run keeps
+        // going; deleting then would race the run's own transcript write. Loop
+        // until the wait reports the run terminated, bounded by attempts so a
+        // hung run can't block forever (at the cap we delete best-effort).
+        for (let attempt = 0; attempt < 3; attempt++) {
+          let waitResult;
+          try {
+            waitResult = await gatewayBridge.request(
+              "agent.wait",
+              { runId: acceptedRunId, timeoutMs },
+              { expectFinal: true },
+            );
+          } catch (_e) {
+            break; // error/unsupported — proceed to best-effort delete
+          }
+          if (runWaitTerminal(waitResult)) break;
+        }
+      }
+      // The transcript is keyed by the gateway's accepted runId; fall back to
+      // the idempotencyKey only if the ack never returned one.
+      const cleanupRunId = acceptedRunId || idempotencyKey;
+      try { await fs.rm(transcriptPath(cleanupRunId), { force: true }); } catch (_e) { /* best-effort */ }
+      // 2026.6.x writes runId-derived sidecars next to the transcript
+      // (<id>.jsonl.codex-app-server.json, <id>.trajectory.jsonl,
+      // <id>.trajectory-path.json) — they carry the run content too. Sweep
+      // every "<id>."-prefixed sibling.
+      if (typeof fs.readdir === "function") {
+        try {
+          const dir = nodePath.dirname(transcriptPath(cleanupRunId));
+          const base = internalTranscriptFilename(cleanupRunId).replace(/\.jsonl$/, "");
+          for (const entry of await fs.readdir(dir)) {
+            if (typeof entry === "string" && entry.startsWith(`${base}.`)) {
+              try { await fs.rm(nodePath.join(dir, entry), { force: true }); } catch (_e) { /* best-effort */ }
+            }
+          }
+        } catch (_e) { /* best-effort */ }
+      }
+      if (budget && typeof budget.recordOutcome === "function") budget.recordOutcome(sessionKey, outcome);
+    }
+  }
+
+  async function runOnceViaSubagent(sessionKey, opts) {
+    const { idempotencyKey, distillerKey, message, model } = buildDistillerInput(opts);
+    // Background, non-delivered title run on a throwaway distiller session.
+    const runParams = {
+      sessionKey: distillerKey,
+      message,
+      idempotencyKey,
+      deliver: false,
+      lane: "background",
+      lightContext: true,
+    };
+    const ref = splitModelRef(model);
+    if (ref) {
+      if (ref.provider) runParams.provider = ref.provider;
+      runParams.model = ref.model;
+    }
+    dbg("relay.session", "distiller_run_started", "debug", { sessionKey }, () => ({ chars: message.length, idempotencyKey, via: "subagent" }));
+
+    // Dispatch OUTSIDE the wait/read/cleanup scope: a dispatch-time throw means
+    // no run exists (nothing to wait on, read, or delete). On 2026.6.x the
+    // runtime's methods exist at registration but are request-scoped — they
+    // throw "only available during a gateway request" from this deferred
+    // context. Latch and serve this run (and the rest of the process lifetime)
+    // via the raw-RPC bridge instead; the bridge leg records the outcome.
+    let runRes;
+    try {
+      runRes = await subagentRuntime.run(runParams);
+    } catch (err) {
+      subagentDispatchUnusable = true;
+      dbg("relay.session", "distiller_subagent_unusable", "info", { sessionKey, runId: idempotencyKey },
+        () => ({ message: err && err.message ? err.message : String(err) }));
+      return runOnceViaGatewayBridge(sessionKey, opts);
+    }
+
+    let acceptedRunId =
+      runRes && typeof runRes.runId === "string" && runRes.runId.trim()
+        ? runRes.runId.trim()
+        : idempotencyKey;
+    let outcome = "error";
+    try {
+      const wait = await subagentRuntime.waitForRun({ runId: acceptedRunId, timeoutMs });
+      const waitStatus = wait && typeof wait.status === "string" ? wait.status : "ok";
+      if (waitStatus === "error") {
+        // The background run failed; nothing to read.
+        outcome = "error";
+        dbg("relay.session", "distiller_error", "warn", { sessionKey, runId: acceptedRunId },
+          () => ({ message: wait && wait.error ? wait.error : "subagent run error", via: "subagent", waitStatus }));
+      } else if (waitStatus !== "ok") {
+        // Non-terminal (e.g. "timeout"): the session has no final reply yet — do
+        // NOT read a partial/empty transcript. The budget-bounded retry titles a
+        // later untitled turn.
+        outcome = "skip";
+        dbg("relay.session", "distiller_skip", "debug", { sessionKey, runId: acceptedRunId },
+          () => ({ via: "subagent", waitStatus }));
+      } else {
+        const msgRes = await subagentRuntime.getSessionMessages({ sessionKey: distillerKey, limit: 4 });
+        const text = extractAssistantTitleFromMessages(msgRes && msgRes.messages);
+        outcome = applyDistilledTitle(sessionKey, acceptedRunId, text);
+      }
+    } catch (err) {
+      outcome = "error";
+      dbg("relay.session", "distiller_error", "warn", { sessionKey, runId: acceptedRunId },
+        () => ({ message: err && err.message ? err.message : String(err), via: "subagent" }));
+    } finally {
+      try {
+        await subagentRuntime.deleteSession({ sessionKey: distillerKey, deleteTranscript: true });
+      } catch (_e) { /* best-effort */ }
+      // Canonical-key backstop: on 2026.6.x the native deleteSession resolves
+      // OK even when its bare-key sessions.delete matched nothing, leaving the
+      // excerpt-bearing transcript + index entry behind (observed live). The
+      // relay-side delete resolves the canonical key first; both are
+      // idempotent, so always run it.
+      if (typeof cleanupDistillerSession === "function") {
+        try {
+          const res = await cleanupDistillerSession(distillerKey);
+          const failed = res && Array.isArray(res.failed) ? res.failed : [];
+          if (failed.length) {
+            dbg("relay.session", "distiller_cleanup_failed", "warn", { sessionKey, runId: acceptedRunId },
+              () => ({ distillerKey, reason: failed[0] && failed[0].reason ? failed[0].reason : "unknown" }));
+          }
+        } catch (err) {
+          dbg("relay.session", "distiller_cleanup_failed", "warn", { sessionKey, runId: acceptedRunId },
+            () => ({ distillerKey, reason: err && err.message ? err.message : String(err) }));
+        }
+      }
+      if (budget && typeof budget.recordOutcome === "function") budget.recordOutcome(sessionKey, outcome);
+    }
+  }
+
+  async function runOnce(sessionKey, opts) {
+    if (subagentRuntime && typeof subagentRuntime.run === "function" && !subagentDispatchUnusable) {
+      return runOnceViaSubagent(sessionKey, opts);
+    }
+    return runOnceViaGatewayBridge(sessionKey, opts);
+  }
+
+  return {
+    async maybeRun(sessionKey, opts) {
+      if (typeof sessionKey !== "string" || !sessionKey.trim()) return;
+      if (!triggerGatesPass(sessionKey)) return;
+      // Count only ACTUAL attempts toward the budget ceiling. Recording before
+      // the gates would let recursion-guard / feature-disabled / already-titled
+      // skips exhaust the untitled-turn ceiling and permanently disable titling
+      // (e.g. 25 feature-disabled agent_end events before the user enables it).
+      if (budget && typeof budget.recordTurn === "function") budget.recordTurn(sessionKey);
+      inFlight.add(sessionKey);
+      try {
+        await runOnce(sessionKey, opts);
+      } finally {
+        inFlight.delete(sessionKey);
+      }
+    },
+  };
+}
+
+export default createSessionTitleDistiller;

package/dist/runtime/session-title-record.js

@@ -0,0 +1,21 @@
+const USER_ORIGINS = new Set(["user_ui", "user_tool"]);
+
+export function isUserOrigin(origin) {
+  return typeof origin === "string" && USER_ORIGINS.has(origin);
+}
+
+/**
+ * Decide whether a title write is allowed and whether it sets the lock.
+ * @param {{userSet?: boolean, origin?: string}|null} previous
+ * @param {string} origin - origin of the incoming write
+ * @returns {{allowed: true, nextUserSet: boolean} | {allowed: false, code: string}}
+ */
+export function decideTitleWrite(previous, origin) {
+  const incomingIsUser = isUserOrigin(origin);
+  const prevLocked = !!(previous && previous.userSet === true);
+  if (!incomingIsUser && prevLocked) {
+    return { allowed: false, code: "session_user_locked" };
+  }
+  const nextUserSet = incomingIsUser || prevLocked;
+  return { allowed: true, nextUserSet };
+}

package/dist/runtime/stable-prompt-snapshot.js

@@ -0,0 +1,119 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+
+const STORE_FILENAME = "ocuclaw-stable-prompts.json";
+const DEFAULT_TTL_MS = 14 * 24 * 60 * 60 * 1000; // 14 days
+
+function hashText(text) {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex").slice(0, 16);
+}
+
+/**
+ * Per-session immutable Channel-1 snapshot store.
+ *
+ * @param {{stateDir?: string, nowMs?: () => number, ttlMs?: number,
+ *          emitDebug?: Function}} opts
+ */
+export function createStablePromptSnapshotStore(opts = {}) {
+  const nowMs = typeof opts.nowMs === "function" ? opts.nowMs : () => Date.now();
+  const ttlMs = Number.isFinite(opts.ttlMs) ? opts.ttlMs : DEFAULT_TTL_MS;
+  const emitDebug = typeof opts.emitDebug === "function" ? opts.emitDebug : () => {};
+  const statePath =
+    typeof opts.stateDir === "string" && opts.stateDir.trim()
+      ? path.join(opts.stateDir.trim(), STORE_FILENAME)
+      : null;
+
+  /** @type {Map<string, {sessionId: string, prompt: string, hash: string, touchedMs: number}>} */
+  const byKey = new Map();
+
+  function load() {
+    if (!statePath) return;
+    try {
+      const raw = fs.readFileSync(statePath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && parsed.entries && typeof parsed.entries === "object") {
+        for (const [k, v] of Object.entries(parsed.entries)) {
+          if (v && typeof v.prompt === "string" && typeof v.sessionId === "string") {
+            byKey.set(k, {
+              sessionId: v.sessionId,
+              prompt: v.prompt,
+              hash: typeof v.hash === "string" ? v.hash : hashText(v.prompt),
+              touchedMs: Number.isFinite(v.touchedMs) ? v.touchedMs : nowMs(),
+            });
+          }
+        }
+      }
+    } catch (_err) {
+      // Missing/corrupt store is non-fatal: start empty.
+    }
+  }
+
+  function persist() {
+    if (!statePath) return;
+    try {
+      const entries = {};
+      for (const [k, v] of byKey.entries()) entries[k] = v;
+      const tmp = `${statePath}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify({ version: 1, entries }), { mode: 0o600 });
+      fs.renameSync(tmp, statePath);
+    } catch (err) {
+      emitDebug("relay.session", "stable_prompt_persist_failed", "warn", {}, () => ({
+        message: err && err.message ? err.message : String(err),
+      }));
+    }
+  }
+
+  function normSessionId(sessionId) {
+    return typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : "";
+  }
+
+  load();
+
+  return {
+    /**
+     * Return the stored prompt for (sessionKey, sessionId), computing+storing
+     * it exactly once. A differing stored sessionId forces a recompute.
+     */
+    getOrCreate(sessionKey, sessionId, computeFn) {
+      const sid = normSessionId(sessionId);
+      const existing = byKey.get(sessionKey);
+      if (existing && existing.sessionId === sid) {
+        existing.touchedMs = nowMs();
+        return existing.prompt;
+      }
+      const prompt = String(computeFn());
+      const record = { sessionId: sid, prompt, hash: hashText(prompt), touchedMs: nowMs() };
+      byKey.set(sessionKey, record);
+      persist();
+      emitDebug("relay.session", "stable_prompt_resolved", "info", { sessionKey }, () => ({
+        sessionId: sid, chars: prompt.length, hash: record.hash,
+      }));
+      return prompt;
+    },
+
+    /** True if `candidate` differs from the stored stable prompt for this session. */
+    wouldChurn(sessionKey, sessionId, candidate) {
+      const existing = byKey.get(sessionKey);
+      if (!existing || existing.sessionId !== normSessionId(sessionId)) return false;
+      return existing.hash !== hashText(String(candidate));
+    },
+
+    evict(sessionKey) {
+      if (byKey.delete(sessionKey)) persist();
+    },
+
+    sweep() {
+      const cutoff = nowMs() - ttlMs;
+      let changed = false;
+      for (const [k, v] of byKey.entries()) {
+        if (v.touchedMs < cutoff) { byKey.delete(k); changed = true; }
+      }
+      if (changed) persist();
+    },
+
+    _size() { return byKey.size; },
+  };
+}
+
+export default createStablePromptSnapshotStore;

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

@@ -85,7 +85,7 @@ export function createGlassesUiCronEngine(deps) {
     return Object.assign({}, outcome, extra);
   }
 
-  function resolveAndClean(state, extra) {
+  function resolveAndClean(state, extra, opts) {
     if (state.resolved) return;
     state.resolved = true;
     if (state.nextTickTimer) clearTimeoutFn(state.nextTickTimer);
@@ -93,6 +93,12 @@ export function createGlassesUiCronEngine(deps) {
     state.nextTickTimer = null;
     state.maxDurationTimer = null;
     active.delete(state.surfaceId);
+    // silent: tear down timers/state WITHOUT firing onResolve. Used when the
+    // cron slot is being RECYCLED (a replace render swapping the surface's
+    // content in place) — a synthesized outcome here would reach
+    // surfaceStore.resolve with no pending call and LATCH a bogus exit that
+    // discards the very render doing the replacing (B7, found 2026-06-11).
+    if (opts && opts.silent === true) return;
     try {
       state.onResolve(makeOutcome(state, extra));
     } catch (_) {
@@ -326,10 +332,10 @@ export function createGlassesUiCronEngine(deps) {
         });
       });
     },
-    stop(surfaceId, outcome) {
+    stop(surfaceId, outcome, opts) {
       const state = active.get(surfaceId);
       if (!state) return false;
-      resolveAndClean(state, outcome || { result: "preempted" });
+      resolveAndClean(state, outcome || { result: "preempted" }, opts);
       return true;
     },
     stopAllForSession(sessionKey, outcome) {

package/dist/tools/glasses-ui-paint-floor.js

@@ -2,15 +2,22 @@
 //
 // Governs ALL plugin->glass sends (initial RebuildPageContainer render and
 // every surface_update patch). Collapses bursts to last-write-wins per field
-// and emits at most one frame per paintFloorMs (default 150ms, Spike D), with
-// a leading-edge send + a trailing send carrying the final merged patch.
+// and emits at most one frame per paintFloorMs, with a leading-edge send + a
+// trailing send carrying the final merged patch.
 //
 // There is NO glass-side paint-ack: the only backpressure signal is
 // relay/BLE transport-side (see the isUnderBackpressure shed in Task 13).
 // Local fake-list textContainerUpgrade scroll-swaps are client-side and never
 // reach this coalescer.
+//
+// 250 is the unconditionally hardware-proven floor. Spike D approved lowering
+// to 150 ONLY once the backpressure shed has a live signal; the shed's
+// isGlassesSendBufferOverHighWater query is implemented nowhere yet, so the
+// shed is inert and 150 would run without its safety condition. Restore 150
+// when the relay-service bridge lands and is validated on hardware
+// (roadmap step 4, docs/superpowers/plans/2026-06-10-glasses-ui-state-reset-and-roadmap.md).
 
-export const DEFAULT_PAINT_FLOOR_MS = 150;
+export const DEFAULT_PAINT_FLOOR_MS = 250;
 
 export function createPaintFloorCoalescer(deps) {
   const paintFloorMs = Number.isFinite(deps.paintFloorMs) ? deps.paintFloorMs : DEFAULT_PAINT_FLOOR_MS;