dsh-vision-router 2.2.7 → 2.3.0

package/lib/remote-settings-risk-confirmation.js

@@ -1,113 +1,25 @@
 import { htmlHasScriptMarker } from './html-script-marker.js'
+import { REMOTE_SETTINGS_RISK_CLIENT_BOUNDARY_SOURCE } from './remote-settings-risk-client-boundary.js'
 
 const RISK_PRELUDE_MARK = 'data-vision-router-remote-settings-risk-confirmation'
 
 export const REMOTE_SETTINGS_RISK_CLIENT_PRELUDE = String.raw`(function(){
   'use strict';
-  var CHANNEL = '/vision-router-settings';
-  var AUTHORIZE_ENDPOINT = 'authorize';
-  var connectionCache = typeof WeakMap === 'function' ? new WeakMap() : undefined;
-  var rpcCache = typeof WeakMap === 'function' ? new WeakMap() : undefined;
-  var contextCache = typeof WeakMap === 'function' ? new WeakMap() : undefined;
-  var authorizationPromise;
-
-  function chineseLocale() {
-    var lang = '';
-    try {
-      lang = String((document && document.documentElement && document.documentElement.lang) || (navigator && navigator.language) || '').toLowerCase();
-    } catch (_) {}
-    return lang === '' || lang.indexOf('zh') === 0;
-  }
-
-  function riskMessage() {
-    return chineseLocale()
-      ? '启用远程设置？\n\n当前页面通过远程地址访问 DSH。启用后，能够访问此 trusted host 的客户端可以修改 Vision Router 已开放的设置。\n\nDSH trustedHosts 不是身份认证，请仅在你信任当前网络和访问者时继续。API Key、HTTP Provider 凭据、本地 Ollama / LM Studio、产物路径等未列入远程白名单的敏感配置仍不会开放。\n\n确定要允许远程修改设置吗？'
-      : 'Enable remote settings?\n\nThis page is accessing DSH through a remote address. After enabling this, clients that can reach this trusted host can change the Vision Router settings exposed by the remote allow-list.\n\nDSH trustedHosts is not authentication. Continue only if you trust the current network and its users. Sensitive settings outside the remote allow-list, including API keys, HTTP-provider credentials, local Ollama / LM Studio, and artifact paths, remain unavailable remotely.\n\nAllow remote settings?';
-  }
-
-  function isPermissionDisabledDescribe(channel, endpoint, result) {
-    return channel === CHANNEL
-      && endpoint === 'describe'
-      && result && result.ok === true
-      && result.value && result.value.enabled !== true
-      && result.value.reason === 'permission-disabled';
-  }
-
-  async function authorizeAndRefresh(target, call) {
-    if (authorizationPromise) return authorizationPromise;
-    authorizationPromise = (async function(){
-      if (typeof window.confirm !== 'function' || window.confirm(riskMessage()) !== true) return undefined;
-      var authorized = await call.call(target, CHANNEL, AUTHORIZE_ENDPOINT, { acceptedRisk: true });
-      if (!authorized || authorized.ok !== true) {
-        var message = authorized && authorized.error && authorized.error.message
-          ? authorized.error.message
-          : 'Vision Router could not enable remote settings.';
-        try { if (typeof window.alert === 'function') window.alert(message); } catch (_) {}
-        return undefined;
-      }
-      return call.call(target, CHANNEL, 'describe', {});
-    })();
-    try { return await authorizationPromise; }
-    finally { authorizationPromise = undefined; }
-  }
-
-  function wrapRpc(rpc) {
-    if (!rpc || (typeof rpc !== 'object' && typeof rpc !== 'function')) return rpc;
-    if (rpcCache && rpcCache.has(rpc)) return rpcCache.get(rpc);
-    var wrapped = new Proxy(rpc, {
-      get: function(target, property) {
-        if (property === 'call') {
-          var call = Reflect.get(target, property, target);
-          if (typeof call !== 'function') return call;
-          return async function(channel, endpoint) {
-            var result = await call.apply(target, arguments);
-            if (!isPermissionDisabledDescribe(channel, endpoint, result)) return result;
-            var refreshed = await authorizeAndRefresh(target, call);
-            return refreshed || result;
-          };
-        }
-        var value = Reflect.get(target, property, target);
-        return typeof value === 'function' ? value.bind(target) : value;
-      }
-    });
-    if (rpcCache) rpcCache.set(rpc, wrapped);
-    return wrapped;
-  }
-
-  function wrapConnection(connection) {
-    if (!connection || (typeof connection !== 'object' && typeof connection !== 'function')) return connection;
-    if (connectionCache && connectionCache.has(connection)) return connectionCache.get(connection);
-    var wrapped = new Proxy(connection, {
-      get: function(target, property) {
-        if (property === 'rpc') return wrapRpc(Reflect.get(target, property, target));
-        var value = Reflect.get(target, property, target);
-        return typeof value === 'function' ? value.bind(target) : value;
-      }
-    });
-    if (connectionCache) connectionCache.set(connection, wrapped);
-    return wrapped;
-  }
-
-  function wrapContext(ctx) {
-    if (!ctx || typeof ctx !== 'object') return ctx;
-    if (contextCache && contextCache.has(ctx)) return contextCache.get(ctx);
-    var wrapped = new Proxy(ctx, {
-      get: function(target, property) {
-        if (property === 'get') {
-          var get = Reflect.get(target, property, target);
-          if (typeof get !== 'function') return get;
-          return function(name) {
-            var value = get.apply(target, arguments);
-            return name === 'connection' ? wrapConnection(value) : value;
-          };
-        }
-        var value = Reflect.get(target, property, target);
-        return typeof value === 'function' ? value.bind(target) : value;
-      }
-    });
-    if (contextCache) contextCache.set(ctx, wrapped);
-    return wrapped;
-  }
+  ${REMOTE_SETTINGS_RISK_CLIENT_BOUNDARY_SOURCE}
+  var riskBoundary = createRemoteSettingsRiskClientBoundary({
+    confirmImpl: function(message) {
+      return typeof window.confirm === 'function' && window.confirm(message) === true;
+    },
+    alertImpl: function(message) {
+      try { if (typeof window.alert === 'function') window.alert(message); } catch (_) {}
+    },
+    locale: function() {
+      try {
+        return String((document && document.documentElement && document.documentElement.lang)
+          || (navigator && navigator.language) || '');
+      } catch (_) { return ''; }
+    }
+  });
 
   function patchLoader(loader) {
     if (!loader || typeof loader.load !== 'function' || loader.load.__visionRouterRemoteRiskConfirmation) return;
@@ -122,7 +34,7 @@ export const REMOTE_SETTINGS_RISK_CLIENT_PRELUDE = String.raw`(function(){
               var apply = exports.apply;
               var wrappedApply = function(ctx) {
                 var rest = Array.prototype.slice.call(arguments, 1);
-                return apply.apply(exports, [wrapContext(ctx)].concat(rest));
+                return apply.apply(exports, [riskBoundary.wrapContext(ctx)].concat(rest));
               };
               Object.defineProperty(wrappedApply, '__visionRouterRemoteRiskConfirmation', { value: true });
               exports.apply = wrappedApply;

package/lib/runtime-composition.js

@@ -14,6 +14,7 @@ import { contextWithNativeImageCoexistence } from './native-image-coexistence.js
 import { createCoreVisionSurfaceRuntime } from './core-vision-surface.js'
 import { installSessionVisionIndexBoundary } from './session-vision-index.js'
 import { createSessionVisionRuntime } from './session-vision-runtime.js'
+import { runCoreApplyLifecycle } from './core-apply-lifecycle.js'
 import { installLegacyCoreVisionPolicyBridge } from './legacy-core-vision-policy-bridge.js'
 import { installSessionVisionModeBoundary } from './session-vision-mode-boundary.js'
 import { installPiAiBridgeWireCompat } from './pi-ai-bridge-wire-compat.js'
@@ -23,7 +24,6 @@ import { installAdversarialHardening } from './adversarial-hardening.js'
 import { installOllamaColdStartGuard } from './ollama-cold-start.js'
 import { installLocalVisionStabilizer } from './local-vision-stabilizer.js'
 import { installWrapperDirectoryAlias } from './wrapper-directory.js'
-import { installAndroidAttachmentCompat } from './android-attachment-compat.js'
 import { contextWithCoalescedAdapterUpdates } from './adapter-update-coalescer.js'
 import { installTesseractExecFileCompat } from './tesseract-exec-compat.js'
 import { installLocalMutationRouteBoundary } from './web-capability-boundary.js'
@@ -57,7 +57,7 @@ import {
 } from './structured-flow-hardening.js'
 import { installVisionLimitDiagnostics } from './vision-limit-diagnostics.js'
 import {
-  attachmentContextForContract,
+  installDshHostCapabilityDiagnostics,
   createSessionEventReader,
   createSessionEventTailReader,
   createSessionLogReader,
@@ -73,6 +73,7 @@ import {
 } from './web/index.js'
 import { createRuntimeI18nCoreFacade } from './runtime-i18n-core.js'
 import { createRuntimeI18nCoreScope } from './runtime-i18n-core-scope.js'
+import { installVisionMaintenanceRoutes } from './maintenance-routes.js'
 
 function liveVisionSettings(ctx, fallback) {
   try {
@@ -95,7 +96,7 @@ function legacyCoreVisionSettings(ctx, fallback) {
   return { ...current, autoActivateOnImage: false }
 }
 
-export function applyVisionRuntimeComposition(ctx, config = {}, core) {
+function installHostAndSecurityBoundaries(ctx, config, core) {
   // SessionVisionIndex calls planGuardStopShadows before Core.apply. Keep that
   // one helper behind the live-locale facade; the final Core itself still gets
   // the ordinary composition identity and is localized by the scoped context.
@@ -174,10 +175,29 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
         Config: core.Config,
       })
     : ownershipCtx
-  const attachmentCompatCtx = attachmentContextForContract(settingsCtx, logging.logger, {
-    installAndroidAttachmentCompat,
-  })
+  // DVR 2.3 supports DSH from the 0.1.5 train, whose attachment
+  // contract already owns batch persistence. The old no-batch Android wrapper
+  // is therefore unreachable; keep capability diagnostics as an explicit
+  // composition responsibility instead of hiding that side effect in a shim.
+  installDshHostCapabilityDiagnostics(settingsCtx)
+  const attachmentCompatCtx = settingsCtx
+
+  return {
+    attachmentCompatCtx,
+    batchAttachmentHost,
+    capabilityStore,
+    hardenedConfig,
+    hostOwnsOfficialDeepSeek,
+    logging,
+    runtimeConfig,
+    runtimeI18nCore,
+    runtimeI18nCoreScope,
+    runtimePerformanceStore,
+  }
+}
 
+function createRuntimeOwners(host, core) {
+  const { attachmentCompatCtx, logging, runtimeConfig, runtimeI18nCore } = host
   const toolRuntimeCtx = installVisionToolRuntimeBoundary(attachmentCompatCtx, runtimeConfig)
   const nativeImageCompat = contextWithNativeImageCoexistence(toolRuntimeCtx, runtimeConfig)
   const coreVisionSurfaceRuntime = createCoreVisionSurfaceRuntime({
@@ -213,6 +233,17 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
     legacyCoreCompat.config,
   )
 
+  return {
+    coreVisionSurfaceRuntime,
+    nativeImageCompat,
+    sessionVisionModeCompat,
+    sessionVisionRuntime,
+  }
+}
+
+function installRoutingAndHostProducts(host, owners, core) {
+  const { capabilityStore, logging, runtimeConfig, runtimePerformanceStore } = host
+  const { sessionVisionModeCompat } = owners
   // Final structured-flow guard sits closest to core.apply so it sees the
   // actual tool registrations and pre-step listener. The diagnostic observer
   // remains immediately inside it so existing timeout/budget semantics stay
@@ -266,6 +297,19 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
   })
   installPiAiBridgeWireCompat(reconciledCtx, logging.logger)
 
+  return {
+    breakerShadowHealth,
+    liveDiscovery,
+    reconciledCtx,
+    sessionEventTailReader,
+    sessionTurnResolver,
+  }
+}
+
+function installExecutionBoundaries(host, owners, routing, core, providerTransport) {
+  const { capabilityStore, logging, runtimeConfig, runtimeI18nCoreScope, runtimePerformanceStore } = host
+  const { sessionVisionRuntime } = owners
+  const { breakerShadowHealth, liveDiscovery, reconciledCtx } = routing
   const executionCtx = contextWithVisionExecutionPolicy(reconciledCtx, {
     isBridgeEvidence: (provider, model) => liveDiscovery.hasModel(provider, model),
     evidenceSource: (provider, model) => liveDiscovery.evidenceSource?.(provider, model),
@@ -314,11 +358,13 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
     core,
     evidenceSource: (provider, model) => liveDiscovery.evidenceSource?.(provider, model),
     logger: logging.logger,
+    providerTransport,
     finalContextDecorator: runtimeI18nCoreScope.decorate,
   })
   const capabilityBenchmark = installCapabilityBenchmarkService(backendRuntimeCtx, runtimeConfig, core, {
     logger: logging.logger,
     store: capabilityStore,
+    providerTransport,
   })
   attachCapabilityBenchmarkPresentation(capabilityBenchmark, {
     ctx: backendRuntimeCtx,
@@ -338,6 +384,22 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
   })
   const coreRequestAuthorityCtx = contextWithAgentRequestRouteAuthority(backendRuntimeCtx)
 
+  return { coreRequestAuthorityCtx }
+}
+
+function applyMatureCoreBridge(host, owners, routing, execution, core, runtime) {
+  const {
+    attachmentCompatCtx,
+    batchAttachmentHost,
+    hardenedConfig,
+    hostOwnsOfficialDeepSeek,
+    logging,
+    runtimeConfig,
+    runtimeI18nCoreScope,
+  } = host
+  const { coreVisionSurfaceRuntime, sessionVisionModeCompat, sessionVisionRuntime } = owners
+  const { breakerShadowHealth, sessionEventTailReader, sessionTurnResolver } = routing
+  const { coreRequestAuthorityCtx } = execution
   try {
     const c = hardenedConfig && typeof hardenedConfig === 'object' ? hardenedConfig : {}
     const local = c.localOllama && typeof c.localOllama === 'object' ? c.localOllama : {}
@@ -354,8 +416,27 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
     /* diagnostics must never break apply */
   }
 
-  try {
-    const result = runtimeI18nCoreScope.run(() =>
+  let schemaBootstrapFinished = false
+  const finishSchemaBootstrapOnce = () => {
+    if (schemaBootstrapFinished) return
+    schemaBootstrapFinished = true
+    coreVisionSurfaceRuntime.finishSchemaBootstrap()
+  }
+  const installPostCoreRuntime = () => {
+    installVisionMaintenanceRoutes(coreRequestAuthorityCtx, { logger: logging.logger })
+    finishSchemaBootstrapOnce()
+    installWrapperDirectoryAlias(attachmentCompatCtx, runtimeConfig, logging.logger)
+  }
+  const failCoreApply = (error) => {
+    finishSchemaBootstrapOnce()
+    logging.logger.error(
+      'vision-router: plugin apply failed: %s',
+      error && error.stack ? error.stack : error && error.message ? error.message : String(error),
+    )
+  }
+
+  return runCoreApplyLifecycle(
+    () => runtimeI18nCoreScope.run(() =>
       withVisionCircuitBreakerObserver(
         breakerShadowHealth.capture,
         () => core.apply(
@@ -367,28 +448,22 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
             sessionTurnResolver,
             sessionEventTailReader,
             hostOwnsOfficialDeepSeek,
+            providerTransport: runtime?.providerTransport,
           },
         ),
       ),
-    )
-    coreVisionSurfaceRuntime.finishSchemaBootstrap()
-    installWrapperDirectoryAlias(attachmentCompatCtx, runtimeConfig, logging.logger)
-    if (result && typeof result.then === 'function') {
-      return result.catch((error) => {
-        logging.logger.error(
-          'vision-router: plugin apply failed: %s',
-          error && error.stack ? error.stack : error && error.message ? error.message : String(error),
-        )
-        throw error
-      })
-    }
-    return result
-  } catch (error) {
-    coreVisionSurfaceRuntime.finishSchemaBootstrap()
-    logging.logger.error(
-      'vision-router: plugin apply failed: %s',
-      error && error.stack ? error.stack : error && error.message ? error.message : String(error),
-    )
-    throw error
-  }
-}
+    ),
+    {
+      onSuccess: installPostCoreRuntime,
+      onFailure: failCoreApply,
+    },
+  )
+}
+
+export function applyVisionRuntimeComposition(ctx, config = {}, core, runtime = {}) {
+  const host = installHostAndSecurityBoundaries(ctx, config, core)
+  const owners = createRuntimeOwners(host, core)
+  const routing = installRoutingAndHostProducts(host, owners, core)
+  const execution = installExecutionBoundaries(host, owners, routing, core, runtime?.providerTransport)
+  return applyMatureCoreBridge(host, owners, routing, execution, core, runtime)
+}

package/lib/runtime-i18n-boundary.js

@@ -1,6 +1,8 @@
 import { createRuntimeI18n, DEEP_TOOL_MOUNT_STATE } from './runtime-i18n.js'
 import { depthCopyFor } from './depth-guidance.js'
 import { blocksHaveRetainedImage } from './image-offload-compat.js'
+import { captureFetchDelegate, installFetchWrapper } from './fetch-wrapper-lifecycle.js'
+import { visionRouterMessageSource } from './session-message-source-compat.js'
 
 const PLUGIN_NAME = 'dsh-vision-router'
 const DEEP_TOOL_NAMES = new Set([
@@ -432,7 +434,7 @@ function addAutoMountReminder(decision, payload, i18n) {
         : `${Date.now()}-${Math.floor(Math.random() * 1e9)}`
     }`,
     content: [{ type: 'text', text: i18n.t('autoMountReminder') }],
-    source: { kind: 'plugin', plugin: PLUGIN_NAME },
+    source: visionRouterMessageSource(payload?.agent?.session),
   }
   const structuredIndex = base.findIndex((message) =>
     typeof message?.id === 'string' && message.id.startsWith('vision-router-structured-'),
@@ -520,9 +522,9 @@ function localizeRequestBody(value, i18n) {
 function installPromptFetchBoundary(ctx, i18n) {
   if (typeof ctx?.effect !== 'function' || typeof globalThis.fetch !== 'function') return
   ctx.effect(() => {
-    const originalFetch = globalThis.fetch
+    const delegateFetch = captureFetchDelegate()
     const localizedFetch = (input, init) => {
-      if (i18n.language() !== 'en' || typeof init?.body !== 'string') return originalFetch(input, init)
+      if (i18n.language() !== 'en' || typeof init?.body !== 'string') return delegateFetch(input, init)
       const body = init.body
       if (
         !body.includes('请按以下结构识别这张图片') &&
@@ -530,21 +532,18 @@ function installPromptFetchBoundary(ctx, i18n) {
         !body.includes(OCR_FALLBACK_PROMPT_ZH) &&
         !body.includes(LONG_SCREENSHOT_OCR_PROMPT_ZH)
       ) {
-        return originalFetch(input, init)
+        return delegateFetch(input, init)
       }
       try {
         const parsed = JSON.parse(body)
         const localized = localizeRequestBody(parsed, i18n)
-        if (localized === parsed) return originalFetch(input, init)
-        return originalFetch(input, { ...init, body: JSON.stringify(localized) })
+        if (localized === parsed) return delegateFetch(input, init)
+        return delegateFetch(input, { ...init, body: JSON.stringify(localized) })
       } catch {
-        return originalFetch(input, init)
+        return delegateFetch(input, init)
       }
     }
-    globalThis.fetch = localizedFetch
-    return () => {
-      if (globalThis.fetch === localizedFetch) globalThis.fetch = originalFetch
-    }
+    return installFetchWrapper(localizedFetch)
   }, 'vision-router: runtime i18n prompt boundary')
 }
 

package/lib/session-message-source-compat.js

@@ -62,9 +62,13 @@ function normalizeHookResult(event, args, result) {
 
 /**
  * DSH Session V3 requires the historical {kind:'plugin', plugin:...} source,
- * while V4 rejects that wrapper in favor of producer-owned source kinds. Keep
- * every existing DVR message producer unchanged and normalize at the final
- * hook publication boundary using the Session's own durable header version.
+ * while V4 rejects that wrapper in favor of producer-owned source kinds.
+ *
+ * Session-facing DVR producers are responsible for calling
+ * visionRouterMessageSource(session) when they create a message. This final
+ * publication boundary is deliberately defense-in-depth: it protects legacy
+ * or future producers that accidentally reach a hook with the wrong DVR source,
+ * but producer correctness must not depend on this proxy being the sole owner.
  */
 export function installVisionRouterMessageSourceBoundary(ctx) {
   if (!ctx || typeof ctx !== 'object') return ctx

package/lib/session-vision-index.js

@@ -3,6 +3,9 @@ import { sessionSurfaceReplacementIntent } from './session-surface-compat.js'
 import { createSessionVisionStateStore } from './session-vision-state.js'
 
 const MAX_PENDING_REPAIR_EVENTS = 256
+const MAX_REPAIR_OVERFLOW_RANGES = 32
+const MAX_REPAIR_OVERFLOW_INSPECTIONS_PER_PASS = 512
+const MAX_REPAIR_OVERFLOW_READS_PER_PASS = 32
 
 function isObject(value) {
   return value !== null && typeof value === 'object'
@@ -87,6 +90,8 @@ export function createSessionVisionIndex({
   const guardSurfaceScans = new WeakMap()
   const pendingToolRepairEvents = new WeakMap()
   const pendingGuardRepairEvents = new WeakMap()
+  const toolRepairOverflowRanges = new WeakMap()
+  const guardRepairOverflowRanges = new WeakMap()
   const unsupportedSurfaceContracts = new WeakSet()
   const repairReadWarnings = new WeakMap()
   const repairFeedOverflowWarnings = new WeakSet()
@@ -295,7 +300,132 @@ export function createSessionVisionIndex({
     return undefined
   }
 
-  const cachePendingRepairEvent = (pendingBySession, session, event) => {
+  // Feed overflow stores only dropped sequence ranges, never frozen event
+  // objects. Adjacent ranges coalesce; pathological sparse overflow is
+  // conservatively collapsed once the range count reaches a fixed bound. The
+  // recovery loop then advances that range in bounded numeric/read batches and
+  // consults only Host-owned readSessionEvent(), so memory remains bounded
+  // without returning to whole-Session history materialization.
+  const addRepairOverflowSeq = (overflowBySession, session, seq) => {
+    if (!Number.isSafeInteger(seq) || seq < 0 || Object.is(seq, -0)) return
+    let ranges = overflowBySession.get(session)
+    if (!ranges) {
+      ranges = []
+      overflowBySession.set(session, ranges)
+    }
+
+    let start = seq
+    let end = seq
+    let insertAt = 0
+    while (insertAt < ranges.length && ranges[insertAt].end + 1 < start) insertAt += 1
+    while (insertAt < ranges.length && ranges[insertAt].start - 1 <= end) {
+      start = Math.min(start, ranges[insertAt].start)
+      end = Math.max(end, ranges[insertAt].end)
+      ranges.splice(insertAt, 1)
+    }
+    ranges.splice(insertAt, 0, { start, end })
+
+    if (ranges.length > MAX_REPAIR_OVERFLOW_RANGES) {
+      overflowBySession.set(session, [{
+        start: ranges[0].start,
+        end: ranges[ranges.length - 1].end,
+      }])
+    }
+  }
+
+  const advanceRepairOverflowRange = (ranges) => {
+    const range = ranges?.[0]
+    if (!range) return
+    if (range.start >= range.end) ranges.shift()
+    else range.start += 1
+  }
+
+  const recoverRepairOverflowEvents = async (overflowBySession, pendingBySession, session) => {
+    const ranges = overflowBySession.get(session)
+    if (!ranges || ranges.length === 0) return []
+
+    const nodes = surfaceNodes(session)
+    if (!nodes || nodes.length === 0) {
+      overflowBySession.delete(session)
+      repairFeedOverflowWarnings.delete(session)
+      return []
+    }
+    const current = new Set(nodes)
+    const pending = pendingBySession.get(session)
+    const recovered = []
+    let inspections = 0
+    let reads = 0
+
+    while (
+      ranges.length > 0
+      && inspections < MAX_REPAIR_OVERFLOW_INSPECTIONS_PER_PASS
+      && reads < MAX_REPAIR_OVERFLOW_READS_PER_PASS
+    ) {
+      const seq = ranges[0].start
+      inspections += 1
+
+      // A dropped repair that is no longer on the live surface is settled. A
+      // seq still present in the fast-path map will be consumed normally.
+      if (!current.has(seq) || pending?.has(seq)) {
+        advanceRepairOverflowRange(ranges)
+        continue
+      }
+
+      if (typeof readSessionEvent !== 'function') {
+        warnRepairReadFailure(
+          session,
+          seq,
+          new Error('Session event reader is unavailable during feed overflow recovery'),
+        )
+        break
+      }
+
+      let result
+      try {
+        result = await readSessionEvent(session, seq)
+      } catch (error) {
+        warnRepairReadFailure(session, seq, error)
+        break
+      }
+      if (result?.supported !== true) {
+        warnRepairReadFailure(
+          session,
+          seq,
+          result?.supported === false
+            ? new Error('Session event reader is unsupported during feed overflow recovery')
+            : new Error('Session event reader returned an invalid capability result during feed overflow recovery'),
+        )
+        break
+      }
+      const event = result.event
+      if (!event || typeof event !== 'object' || (event.seq !== undefined && event.seq !== seq)) {
+        warnRepairReadFailure(
+          session,
+          seq,
+          new Error(`Session event reader returned no matching event for overflow seq ${seq}`),
+        )
+        break
+      }
+
+      reads += 1
+      advanceRepairOverflowRange(ranges)
+      repairReadWarnings.delete(session)
+      // The live feed may deliver the same committed event while the exact read
+      // is in flight. In that case the fast-path map owns it; do not return a
+      // second copy from recovery.
+      if (!pendingBySession.get(session)?.has(seq) && !isReplacementEvent(event)) {
+        recovered.push({ seq, event })
+      }
+    }
+
+    if (ranges.length === 0) {
+      overflowBySession.delete(session)
+      repairFeedOverflowWarnings.delete(session)
+    }
+    return recovered
+  }
+
+  const cachePendingRepairEvent = (pendingBySession, overflowBySession, session, event) => {
     if (!session || !Number.isSafeInteger(event?.seq) || event.seq < 0 || Object.is(event.seq, -0)) return
     let pending = pendingBySession.get(session)
     if (!pending) {
@@ -304,11 +434,14 @@ export function createSessionVisionIndex({
     }
     if (!pending.has(event.seq) && pending.size >= MAX_PENDING_REPAIR_EVENTS) {
       const oldest = pending.keys().next().value
-      if (oldest !== undefined) pending.delete(oldest)
+      if (oldest !== undefined) {
+        pending.delete(oldest)
+        addRepairOverflowSeq(overflowBySession, session, oldest)
+      }
       if (!repairFeedOverflowWarnings.has(session)) {
         repairFeedOverflowWarnings.add(session)
         logger?.warn?.(
-          'vision-router: session surface repair event feed exceeded %s pending events; dropping oldest entry',
+          'vision-router: session surface repair event feed exceeded %s pending events; scheduling bounded exact-event recovery',
           MAX_PENDING_REPAIR_EVENTS,
         )
       }
@@ -340,10 +473,10 @@ export function createSessionVisionIndex({
           event,
           (events, seqs) => core.planToolResultImageShadows(events, seqs, () => true),
         )
-        if (plans.length > 0) cachePendingRepairEvent(pendingToolRepairEvents, session, event)
+        if (plans.length > 0) cachePendingRepairEvent(pendingToolRepairEvents, toolRepairOverflowRanges, session, event)
       } else if (event.type === 'user/message' && typeof core.planGuardStopShadows === 'function') {
         const plans = planAgainstOneEvent(event, (events, seqs) => core.planGuardStopShadows(events, seqs))
-        if (plans.length > 0) cachePendingRepairEvent(pendingGuardRepairEvents, session, event)
+        if (plans.length > 0) cachePendingRepairEvent(pendingGuardRepairEvents, guardRepairOverflowRanges, session, event)
       }
       repairFeedObserverWarnings.delete(session)
     } catch (error) {
@@ -439,11 +572,17 @@ export function createSessionVisionIndex({
 
   const repairToolResultSurfaceFromFeed = async (session) => {
     if (typeof session?.append !== 'function' || typeof core.planToolResultImageShadows !== 'function') return 0
+    const recovered = await recoverRepairOverflowEvents(
+      toolRepairOverflowRanges,
+      pendingToolRepairEvents,
+      session,
+    )
     const pending = consumePendingRepairEvents(pendingToolRepairEvents, session)
-    if (pending.length === 0) return 0
+    const entries = [...recovered, ...pending]
+    if (entries.length === 0) return 0
     const preserve = keepToolResultImages()
     let repaired = 0
-    for (const { seq, event } of pending) {
+    for (const { seq, event } of entries) {
       const events = { [seq]: event }
       const plans = core.planToolResultImageShadows(events, [seq], () => !preserve)
       for (const plan of plans) {
@@ -470,10 +609,16 @@ export function createSessionVisionIndex({
 
   const repairGuardStopSurfaceFromFeed = async (session) => {
     if (typeof session?.append !== 'function' || typeof core.planGuardStopShadows !== 'function') return 0
+    const recovered = await recoverRepairOverflowEvents(
+      guardRepairOverflowRanges,
+      pendingGuardRepairEvents,
+      session,
+    )
     const pending = consumePendingRepairEvents(pendingGuardRepairEvents, session)
-    if (pending.length === 0) return 0
+    const entries = [...recovered, ...pending]
+    if (entries.length === 0) return 0
     let repaired = 0
-    for (const { seq, event } of pending) {
+    for (const { seq, event } of entries) {
       const events = { [seq]: event }
       const plans = core.planGuardStopShadows(events, [seq])
       for (const plan of plans) {