mixdog 1.4.0 → 1.4.2

package/src/runtime/agent/orchestrator/session/cache-warm.mjs

@@ -1,6 +1,6 @@
 // cache-warm.mjs — keeps a session's prompt cache readable for its next turn
 // — every session, Lead, bot or sub-agent, while warming is on
-// (`promptCacheWarming`, default on) — one interval at a time while the
+// (`promptCacheWarming`, default off) — one interval at a time while the
 // session idles, as far as the session's own history of returns says it
 // pays. A warm re-sends the session's last real request
 // (side-question-store.mjs) through the provider's cache-warm mode
@@ -36,7 +36,11 @@
 // warm counts as cache use for the idle auto-clear (sessionActivityTimestamp
 // in idle-auto-clear-gate.mjs), so its deadline moves with each one.
 // Any fact the rule needs that is not known (written tier, prices, prompt
-// size, the account holding the entry) means no warm. The chain stops on a
+// size, the account holding the entry) means no warm. A warm never goes into
+// an entry past its lifetime (counted from the last confirmed read or write,
+// checked at the refresh point and again right before dispatch), and a
+// session whose warm missed inside the lifetime gets no further chain until
+// its cached prefix is dropped. The chain stops on a
 // miss, a failure, a late timer, a turn in flight, a new real request
 // (side-question-store.mjs cancels), a compaction, a clear, a close, or a
 // delete; the auto-clear then runs from the last real or successful warm
@@ -54,6 +58,7 @@
 // /btw side questions, memory recap, prewarms, warms). The planner counts
 // idle time from the same anchor. Each session learns from its own gaps. A gap still open at the idle window is recorded as
 // censored there.
+import { loadConfig } from '../config.mjs';
 import { ACCOUNT_PROVIDERS } from '../../../shared/provider-accounts.mjs';
 import { setCacheWarmUseSource } from '../../../shared/idle-auto-clear-gate.mjs';
 import {
@@ -97,9 +102,9 @@ export const IDLE_RETURN_LOOKBACK_MS = 7 * 24 * 60 * 60 * 1000;
 const WILSON_Z_95 = 1.959963984540054;
 
 /** Whether prompt-cache warming is on (config `promptCacheWarming`, default
- *  on; config.mjs migrates the earlier target list). */
+ *  off; config.mjs migrates the earlier target list). */
 export function cacheWarmingEnabled(config) {
-  return config?.promptCacheWarming !== false;
+  return config?.promptCacheWarming === true;
 }
 
 /** The lower bound of the 95% Wilson score interval of `hits` in `n`
@@ -134,6 +139,26 @@ export function sessionReturnChance(gaps, elapsedMs, withinMs) {
   return { idle, returns, p: wilsonLowerBound(returns, idle) };
 }
 
+// A write below this many tokens is prompt growth, never a rewrite: 4096 is
+// the largest minimum cacheable prompt length of the supported models.
+export const CACHE_WARM_REWRITE_FLOOR_TOKENS = 4096;
+
+/** Whether a warm's `usage` shows a substantial rewrite with poor read
+ *  coverage: the write reaches the floor and the read covers less than half
+ *  of read + write. A read of most of the prompt plus the new tail is a hit. */
+export function warmRewrote(usage) {
+  const read = Number(usage?.cachedTokens) || 0;
+  const write = Number(usage?.cacheWriteTokens) || 0;
+  return write >= CACHE_WARM_REWRITE_FLOOR_TOKENS && read < write;
+}
+
+/** Whether an entry last used at `touchAt` and living `ttlMs` will have
+ *  expired by the time a warm sent at `now` reaches the provider (`latencyMs`
+ *  later): a warm into an expired entry rewrites the whole prompt. */
+export function cacheEntryLapsed(touchAt, ttlMs, now, latencyMs = null) {
+  return touchAt + ttlMs - now <= (Number(latencyMs) || 0);
+}
+
 /** When a warm goes out after the last cache use of an entry living `ttlMs`. */
 export function cacheWarmDelayMs(ttlMs) {
   return Math.max(1, ttlMs - CACHE_WARM_LEAD_MS);
@@ -223,7 +248,7 @@ export function planCacheWarm({ now, touchAt, ttlMs, lastCallAt, gaps, promptTok
   // fires at or after the refresh point, TTL − lead, so the lead itself cannot
   // be the floor; the chain's measured warm latency (none before the first
   // warm) is.
-  if (touchAt + ttlMs - now <= (Number(latencyMs) || 0)) return { stop: 'late timer' };
+  if (cacheEntryLapsed(touchAt, ttlMs, now, latencyMs)) return { stop: 'late timer' };
   const economics = cacheWarmEconomics(promptTokens, prices);
   if (!economics) return { stop: 'prompt size or cache prices unknown' };
   const interval = cacheWarmDelayMs(ttlMs);
@@ -238,11 +263,35 @@ export function planCacheWarm({ now, touchAt, ttlMs, lastCallAt, gaps, promptTok
 
 // Defaults of the injectable dependencies.
 
-async function defaultEnabled() {
-  const { loadConfig } = await import('../config.mjs');
+// The synchronous on/off state `armCacheWarm` and the restart re-arm gate on.
+// It is always definite: the first call reads the config (synchronous, from
+// disk in a fresh process, where it is authoritative) and caches the value;
+// from then on only the setting call (noteCacheWarmingEnabled) writes it.
+// Refresh-point reads (`deps.enabled`) never do, so a stale read cannot
+// switch warming off globally.
+let warmingOn = null;
+
+function enabledNow() {
+  warmingOn ??= deps.readConfigEnabled();
+  return warmingOn;
+}
+
+/** The setting changed (settings-builtin-tools-api.mjs
+ *  setCacheWarmingEnabled): authoritative; off cancels every armed chain. */
+export function noteCacheWarmingEnabled(enabled) {
+  warmingOn = enabled === true;
+  if (warmingOn) return;
+  for (const sessionId of [...chains.keys()]) cancelCacheWarm(sessionId);
+}
+
+function defaultReadConfigEnabled() {
   return cacheWarmingEnabled(loadConfig({ secrets: false }));
 }
 
+async function defaultEnabled() {
+  return defaultReadConfigEnabled();
+}
+
 // Per-token dollars of a cache read, a cache write of `ttlMs`'s tier and an
 // output token for the request's model, from the pricing catalog (null when
 // unpriced), at the rates of a prompt of `promptTokens`: a model priced by
@@ -351,6 +400,7 @@ const DEFAULT_DEPS = Object.freeze({
   now: () => Date.now(),
   timers: globalThis,
   enabled: defaultEnabled,
+  readConfigEnabled: defaultReadConfigEnabled,
   turnInFlight: (sessionId) => isTurnInFlight(runtimeState.get(sessionId)),
   lastSentRequest: defaultLastSentRequest,
   providersReady: defaultProvidersReady,
@@ -366,12 +416,15 @@ let deps = DEFAULT_DEPS;
 
 // The idle auto-clear measures idleness from the last cache use, a
 // successful warm included (durable in the touch store).
-setCacheWarmUseSource((sessionId) => (sessionId ? deps.touches().lastWarmUse(sessionId) : 0));
+// The record names the route and account the warm read, so only a request
+// on that same prefix counts it as fresh cache (compact-policy.mjs).
+setCacheWarmUseSource((sessionId) => (sessionId ? deps.touches().warmUse(sessionId) : null));
 
 // A session deleted for good drops everything it learned and touched.
 registerSessionPurgeHook((sessionId) => {
   cancelCacheWarm(sessionId);
   turns.delete(sessionId);
+  missedSessions.delete(sessionId);
   deps.touches().forget(sessionId);
   deps.touches().forgetWarmUse(sessionId);
   deps.gaps().forget(sessionId);
@@ -411,6 +464,8 @@ async function planFor(sessionId, chain, at) {
 /** Test seam: replace some dependencies; call with no argument to restore. */
 export function _setCacheWarmDepsForTest(overrides = null) {
   for (const sessionId of [...chains.keys()]) cancelCacheWarm(sessionId);
+  missedSessions.clear();
+  warmingOn = null;
   deps = overrides ? { ...DEFAULT_DEPS, ...overrides } : DEFAULT_DEPS;
 }
 
@@ -418,6 +473,13 @@ export function _setCacheWarmDepsForTest(overrides = null) {
 // accountId, latencyMs, refreshAt, timer, controller }.
 const chains = new Map();
 
+// Sessions whose warm read little of what it rewrote while the entry was
+// still inside its lifetime: the warm does not match what the real requests
+// cache, so no later chain of the session is armed (each would rewrite the
+// prompt once more) until its cached prefix is dropped (forgetCacheWarm) or
+// the session is deleted.
+const missedSessions = new Set();
+
 /** The armed chain of `sessionId` (tests and diagnostics). */
 export function cacheWarmChain(sessionId) {
   return chains.get(sessionId) || null;
@@ -596,6 +658,7 @@ export function cancelCacheWarm(sessionId) {
 export function forgetCacheWarm(sessionId) {
   cancelCacheWarm(sessionId);
   if (!sessionId) return;
+  missedSessions.delete(sessionId);
   deps.touches().forget(sessionId);
   deps.touches().forgetWarmUse(sessionId);
 }
@@ -648,7 +711,8 @@ function warmTarget(chain) {
 /**
  * Arm the session's warm chain from a real request that settled with
  * `response`, and record the confirmed touch durably; replaces any chain.
- * Nothing is armed — and the durable touch is dropped — for an ineligible
+ * Nothing is armed while warming is off (enabledNow). Nothing is armed
+ * — and the durable touch is dropped — for an ineligible
  * request, one without a send time, or a response that does not prove the
  * tier it wrote or the prompt size.
  */
@@ -663,7 +727,17 @@ export function armCacheWarm(sessionId, request, response) {
   if (sessionId && request && realActivity(sessionId, request)) {
     deps.gaps().open(sessionId, Number(request.sentAt));
   }
+  // Warming off: no chain, no timer and no durable touch (the idle gap above
+  // is still learned); the touch of an earlier cache use no longer holds.
+  if (!enabledNow()) {
+    if (sessionId) deps.touches().forget(sessionId);
+    return;
+  }
   if (!sessionId || !request || cacheWarmIneligibility(request)) return;
+  if (missedSessions.has(sessionId)) {
+    deps.touches().forget(sessionId);
+    return;
+  }
   const usage = response?.usage || {};
   const touchAt = Number(request.sentAt);
   const ttlMs = writtenCacheTtlMs(usage, request.opts.cacheStrategy);
@@ -695,7 +769,7 @@ export function armCacheWarm(sessionId, request, response) {
  * many chains were armed.
  */
 export async function rearmCacheWarmsAfterRestart() {
-  if (!(await deps.enabled())) return 0;
+  if (!enabledNow()) return 0;
   const candidates = [];
   for (const sessionId of deps.touches().ids()) {
     if (chains.has(sessionId)) continue;
@@ -711,12 +785,16 @@ export async function rearmCacheWarmsAfterRestart() {
   await deps.providersReady();
   let armed = 0;
   for (const [sessionId, touch] of candidates) {
+    // Re-checked after every await: a setter that turned warming off since
+    // has cancelled the chains and nothing more may start.
+    if (!enabledNow()) return armed;
     let request = null;
     try {
       request = await deps.lastSentRequest(sessionId);
     } catch (error) {
       deps.log(`${sessionId}: restart re-arm skipped (${error?.message || error})`);
     }
+    if (!enabledNow()) return armed;
     if (!request || cacheWarmIneligibility(request) || chains.has(sessionId)) continue;
     startChain(sessionId, {
       request,
@@ -758,7 +836,12 @@ async function fireWarm(sessionId, chain) {
   // Last check before dispatch, after the final await: a turn that began
   // during the lookups has the cache to itself.
   if (deps.turnInFlight(sessionId)) return stopChain(sessionId, chain, 'turn in flight');
+  // The lookups above took time: the entry must still live when the warm goes
+  // out, counted from its last confirmed read or write.
   const sentAt = deps.now();
+  if (cacheEntryLapsed(chain.touchAt, chain.ttlMs, sentAt, chain.latencyMs)) {
+    return stopChain(sessionId, chain, 'entry expired before dispatch');
+  }
   let usage = null;
   let reportedAt = null;
   let failure = null;
@@ -779,14 +862,21 @@ async function fireWarm(sessionId, chain) {
   }
   if (chains.get(sessionId) !== chain) return;
   if (failure) return stopChain(sessionId, chain, `warm failed: ${failure?.message || failure}`);
-  if (!(Number(usage?.cachedTokens) > 0) || Number(usage?.cacheWriteTokens) > 0) {
+  const read = Number(usage?.cachedTokens) || 0;
+  const rewrite = warmRewrote(usage);
+  if (!(read > 0) || rewrite) {
     deps.touches().forget(sessionId);
+    if (rewrite) missedSessions.add(sessionId);
     return stopChain(sessionId, chain, 'warm missed the cache');
   }
   chain.touchAt = sentAt;
   chain.latencyMs = (reportedAt ?? deps.now()) - sentAt;
   recordTouch(sessionId, chain);
   // A read without a write is cache use: the idle auto-clear counts from it.
-  deps.touches().recordWarmUse(sessionId, sentAt);
+  deps.touches().recordWarmUse(sessionId, sentAt, {
+    provider: chain.request.provider.name,
+    model: chain.request.model,
+    accountId: target.accountId,
+  });
   scheduleWarm(sessionId, chain);
 }

package/src/runtime/agent/orchestrator/session/catalog-db/schema.mjs

@@ -11,7 +11,7 @@ import { createHash } from 'node:crypto';
 
 /** Bumped whenever the table layout or a codec changes: the DB is then
  *  dropped and backfilled again from the JSON catalog. */
-export const SCHEMA_VERSION = 10;
+export const SCHEMA_VERSION = 11;
 /** PRAGMA application_id ('MXSC'): a file without it is not this catalog. */
 export const APPLICATION_ID = 0x4d585343;
 
@@ -68,6 +68,9 @@ const FIELDS = [
   // Places of the incoming messages with text among the counted ones, for the
   // unread count of a bot home / room log; absent otherwise (schema 10).
   ['incomingTail', 'incoming_tail', 'optjson'],
+  // Compactions the session has had: the epoch of its message numbering;
+  // absent for a row written before schema 11.
+  ['compactCount', 'compact_count', 'optjson'],
 ];
 
 const COLUMN_TYPES = { text: 'TEXT', real: 'REAL', int: 'INTEGER', bool: 'INTEGER', json: 'TEXT', optjson: 'TEXT' };

package/src/runtime/agent/orchestrator/session/compact/execution-tail.mjs

@@ -9,6 +9,7 @@ import {
   isProtectedContextAckMessage,
   latestActualUserInstructionIndex,
   pendingTaskNotificationIndexes,
+  requestStart,
 } from './messages.mjs';
 import { staleObservations, supersedeObservation } from './observation-supersession.mjs';
 import { carryMessageId, withoutMessageIdsReplacer } from '../message-ids.mjs';
@@ -101,14 +102,6 @@ export function executionTokens(messages) {
   );
 }
 
-function requestStart(messages, index) {
-  for (let i = index; i >= 0; i -= 1) {
-    if (!isActualUserInstructionMessage(messages[i])) continue;
-    if (messages[i]?.meta?.source !== 'steering') return i;
-  }
-  return latestActualUserInstructionIndex(messages.slice(0, index + 1));
-}
-
 // Each assistant tool-call turn with the tool results that directly follow it.
 function executionGroups(messages) {
   const groups = [];

package/src/runtime/agent/orchestrator/session/compact/messages.mjs

@@ -43,6 +43,29 @@ export function latestActualUserInstructionIndex(messages) {
   return -1;
 }
 
+// The user instruction that began the request `index` belongs to; a steering
+// message continues the request instead of starting one.
+export function requestStart(messages, index) {
+  for (let i = index; i >= 0; i -= 1) {
+    if (!isActualUserInstructionMessage(messages[i])) continue;
+    if (messages[i]?.meta?.source !== 'steering') return i;
+  }
+  return latestActualUserInstructionIndex(messages.slice(0, index + 1));
+}
+
+// A tool call's arguments as an object, whether stored parsed or as JSON text.
+export function callArguments(call) {
+  let args = call?.arguments;
+  if (typeof args === 'string') {
+    try {
+      args = JSON.parse(args);
+    } catch {
+      return {};
+    }
+  }
+  return args && typeof args === 'object' ? args : {};
+}
+
 export function latestActualUserInstructionMessage(messages) {
   const index = latestActualUserInstructionIndex(messages);
   return index >= 0 ? { ...messages[index] } : null;

package/src/runtime/agent/orchestrator/session/compact/observation-supersession.mjs

@@ -1,9 +1,12 @@
-// Observations that a later one of the same browser page or desktop window
-// replaced. Such a result's refs have expired, and its element list and pixels
-// describe a state that no longer exists. Only compaction drops them: between
-// compactions the transcript stays append-only so the provider cache prefix
-// holds, and compaction rewrites that prefix anyway. The execution archive
-// keeps every original.
+// Observations that a later one of the same browser page, desktop window,
+// visualize tab (inspect / check) or image file replaced. Such a result's refs
+// have expired, and its element list and pixels describe a state that no
+// longer exists. Only compaction drops them: between compactions the
+// transcript stays append-only so the provider cache prefix holds, and
+// compaction rewrites that prefix anyway. The execution archive keeps every
+// original.
+import { callArguments, requestStart } from './messages.mjs';
+
 const BROWSER_TOOLS = new Set(['browser', 'browser_devtools']);
 const SNAPSHOT_LINE = /(?:^|\n)Snapshot:\s+((p\d+)-s\d+)\b/;
 const TERMINAL_LINE = /(?:^|\n)Terminal:\s+(session-terminal:\S+)/;
@@ -52,13 +55,40 @@ function containsRun(newer, older) {
   return false;
 }
 
-// What one tool result observed, keyed by the page or window it describes.
-function observationOf(message, toolName) {
+const VISUALIZE_READS = new Set(['inspect', 'check']);
+const IMAGE_FILE = /\.(?:png|jpe?g|gif|webp)$/i;
+// What a superseded computer frame keeps besides its reference.
+const FRAME_OUTCOME_KEYS = ['ok', 'action', 'actions', 'status', 'error', 'window_id'];
+
+// A visualize read-out is the same observation only for the same tab, kind of
+// read, viewport and scope: a mobile inspect does not replace a desktop one.
+function visualizeKey(args) {
+  const input = args.input && typeof args.input === 'object' ? args.input : {};
+  if (!VISUALIZE_READS.has(args.action) || typeof input.tab !== 'string' || !input.tab) return null;
+  const scope = args.action === 'inspect' ? `:${JSON.stringify(input.viewport ?? null)}:${input.selector ?? ''}` : '';
+  return { key: `visualize:${args.action}:${input.tab}${scope}`, action: args.action, tab: input.tab };
+}
+
+// What one tool result observed, keyed by the page, window, tab or file it
+// describes.
+function observationOf(message, call) {
   if (message?.role !== 'tool' || message.toolKind === 'error') return null;
+  const toolName = String(call?.name || '');
   const parts = contentParts(message.content);
+  if (toolName === 'read') {
+    const args = callArguments(call);
+    const path = typeof args.path === 'string' ? args.path : args.file_path;
+    if (typeof path !== 'string' || !IMAGE_FILE.test(path) || !parts.some(isImagePart)) return null;
+    return { key: `image:${path.replace(/\\/g, '/')}`, imagePath: path, requestScoped: true };
+  }
   const textIndex = parts.findIndex((part) => part?.type === 'text' && !isImagePart(part));
   if (textIndex < 0) return null;
   const text = String(parts[textIndex].text);
+  if (toolName === 'visualize') {
+    if (/^\[Visualize \w+ of tab \S+ superseded:/.test(text)) return null;
+    const read = visualizeKey(callArguments(call));
+    return read ? { key: read.key, parts, textIndex, visualize: read, requestScoped: true } : null;
+  }
   if (BROWSER_TOOLS.has(toolName)) {
     const snapshot = SNAPSHOT_LINE.exec(text);
     return snapshot ? { key: `browser:${snapshot[2]}`, parts, textIndex, text, snapshot } : null;
@@ -82,40 +112,90 @@ function observationOf(message, toolName) {
   const frame = value?.observation && typeof value.observation === 'object' ? value.observation : value;
   const windowId = frame?.window_id || value?.window_id;
   const observed = Array.isArray(frame?.elements) || frame?.ocr !== undefined || parts.some(isImagePart);
-  return windowId && observed ? { key: `computer:${windowId}`, parts, textIndex, value, frame } : null;
+  if (windowId && observed) return { key: `computer:${windowId}`, parts, textIndex, value, frame };
+  // A stub an earlier compaction wrote in the fuller format.
+  const slim =
+    typeof frame?.superseded === 'string' &&
+    Object.keys(frame).some((name) => name !== 'superseded' && !FRAME_OUTCOME_KEYS.includes(name));
+  return slim ? { stub: true, parts, textIndex, value, frame, reference: frame.superseded } : null;
 }
 
-/** Tool results that a later observation of the same page or window
- *  replaced, keyed by transcript index. */
+// Transcript indices whose results are still in use and must stay verbatim:
+// the latest tool-call group (the batch the session continues from, which
+// compaction always retains) and any group with a call that has no result yet.
+function protectedObservationIndices(messages) {
+  const protectedIndices = new Set();
+  const protect = (from, to) => {
+    for (let index = from; index < to; index += 1) protectedIndices.add(index);
+  };
+  let latest = null;
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index];
+    if (message?.role !== 'assistant' || !message.toolCalls?.length) continue;
+    const start = index;
+    const answered = new Set();
+    while (messages[index + 1]?.role === 'tool') {
+      index += 1;
+      answered.add(messages[index].toolCallId);
+    }
+    latest = [start, index + 1];
+    if (message.toolCalls.some((call) => !answered.has(call?.id))) protect(...latest);
+  }
+  if (latest) protect(...latest);
+  return protectedIndices;
+}
+
+/** Tool results that a later observation of the same page, window, tab or
+ *  file replaced, keyed by transcript index. Protected results are never
+ *  listed, though they still count as the newer observation of what they
+ *  describe. An image file read or visualize read-out is also kept for the
+ *  whole active request (everything since the last user instruction), since
+ *  the request may compare it with a later one; once a newer user message
+ *  exists it is replaceable. */
 export function staleObservations(messages) {
-  const toolNames = new Map();
+  const protectedIndices = protectedObservationIndices(messages);
+  const activeRequest = Math.max(requestStart(messages, messages.length - 1), 0);
+  const calls = new Map();
   for (const message of messages) {
     if (message?.role !== 'assistant' || !Array.isArray(message.toolCalls)) continue;
-    for (const call of message.toolCalls) if (call?.id) toolNames.set(call.id, String(call.name || ''));
+    for (const call of message.toolCalls) if (call?.id) calls.set(call.id, call);
   }
   const newest = new Set();
   const terminalReads = new Map();
   const stale = new Map();
   for (let index = messages.length - 1; index >= 0; index -= 1) {
-    const found = observationOf(messages[index], toolNames.get(messages[index]?.toolCallId));
+    const found = observationOf(messages[index], calls.get(messages[index]?.toolCallId));
     if (!found) continue;
-    if (found.body) {
+    const replaceable = !protectedIndices.has(index) && !(found.requestScoped && index >= activeRequest);
+    if (found.stub) {
+      if (replaceable) stale.set(index, found);
+    } else if (found.body) {
       const newer = terminalReads.get(found.key) ?? [];
-      if (newer.some((body) => containsRun(body, found.body))) stale.set(index, found);
+      if (replaceable && newer.some((body) => containsRun(body, found.body))) stale.set(index, found);
       newer.push(found.body);
       terminalReads.set(found.key, newer);
-    } else if (newest.has(found.key)) stale.set(index, found);
-    else newest.add(found.key);
+    } else if (newest.has(found.key)) {
+      if (replaceable) stale.set(index, found);
+    } else newest.add(found.key);
   }
   return stale;
 }
 
 /** The result without its replaced observation. A browser result keeps what
  *  precedes its snapshot (effect notes, a script's value) and a computer
- *  result its action outcome; neither keeps elements, OCR text or pixels. */
+ *  result its action outcome plus a reference; none keeps elements, OCR text,
+ *  frame metadata or pixels. A visualize read-out or image file read becomes a
+ *  one-line placeholder naming what it was and how to get it again. */
 export function supersedeObservation(message, found, origin) {
   let text;
-  if (found.terminal) {
+  if (found.imagePath) {
+    text = `[Image read of ${found.imagePath} superseded: a newer read of this file follows. Read the file again to view it. ${origin}]`;
+    return { ...message, content: withParts(message.content, [{ type: 'text', text }]) };
+  }
+  if (found.visualize) {
+    const { action, tab } = found.visualize;
+    text = `[Visualize ${action} of tab ${tab} superseded: a newer ${action} of this tab follows. Run visualize ${action} on the tab again to get it. ${origin}]`;
+  } else if (found.terminal) {
     text = `[Terminal ${found.terminal} read superseded: a newer read of this tab follows. ${origin}]`;
   } else if (found.snapshot) {
     const { snapshot } = found;
@@ -126,9 +206,9 @@ export function supersedeObservation(message, found, origin) {
     const note = `[Snapshot ${snapshot[1]} superseded: a newer snapshot of this page follows. ${origin}]`;
     text = before ? `${before}\n\n${note}` : note;
   } else {
-    const frame = { ...found.frame, superseded: `a newer observation of this window follows. ${origin}` };
-    delete frame.elements;
-    delete frame.ocr;
+    const frame = {};
+    for (const name of FRAME_OUTCOME_KEYS) if (found.frame[name] !== undefined) frame[name] = found.frame[name];
+    frame.superseded = found.reference ?? `a newer observation of this window follows. ${origin}`;
     text = JSON.stringify(found.frame === found.value ? frame : { ...found.value, observation: frame });
   }
   const parts = found.parts.flatMap((part, index) => {