dsh-vision-router 2.2.0 → 2.2.1

package/README.md

@@ -17,7 +17,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v2.2.0"><img src="https://img.shields.io/badge/release-v2.2.0-5B4CF0?style=flat-square" alt="Release v2.2.0" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v2.2.1"><img src="https://img.shields.io/badge/release-v2.2.1-5B4CF0?style=flat-square" alt="Release v2.2.1" /></a>
   <a href="tests"><img src="https://img.shields.io/badge/verified-Node%2022%20%2B%2024-2EA44F?style=flat-square" alt="Verified: Node 22 + 24" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="License: MIT" /></a>
   <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js >=22" /></a>
@@ -39,9 +39,9 @@
 <p align="center">💬 <strong>QQ community group: 1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **Announcement (v2.2.0)**
+> 📌 **Announcement (v2.2.1)**
 >
-> **v2.2.0:** Lands Vision Quality Round 2 with adaptive local OCR, bounded degraded-evidence work, stable artifact handoff, successful-evidence convergence, and stronger DSH/session compatibility — without raising the rc.8 Host floor. [What’s new →](docs/releases/v2.2.0.md)
+> **v2.2.1:** Stability hotfix for large-session repair, accessor-based fetch composition, non-divisible pixel-diff bounds, and local Ollama answer-budget preservation — without raising the rc.8 Host floor. [What’s new →](docs/releases/v2.2.1.md)
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="Demo: paste an image, the agent locates the send button with vision_ground / vision_crop / vision_pixel_diff and answers with coordinates" />

package/README.zh.md

@@ -17,7 +17,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v2.2.0"><img src="https://img.shields.io/badge/release-v2.2.0-5B4CF0?style=flat-square" alt="Release v2.2.0" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v2.2.1"><img src="https://img.shields.io/badge/release-v2.2.1-5B4CF0?style=flat-square" alt="Release v2.2.1" /></a>
   <a href="tests"><img src="https://img.shields.io/badge/verified-Node%2022%20%2B%2024-2EA44F?style=flat-square" alt="已验证 Node 22 + 24" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="MIT 许可证" /></a>
   <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js >=22" /></a>
@@ -39,9 +39,9 @@
 <p align="center">💬 <strong>QQ 用户交流群：1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **公告（v2.2.0）**
+> 📌 **公告（v2.2.1）**
 >
-> **v2.2.0：Vision Quality Round 2 正式落地——自适应本地OCR、失败证据有界收敛、稳定artifact handoff、成功证据停止重复调用，并进一步收敛DSH/Session兼容；公开最低Host仍保持 `0.1.0-rc.8`。** [查看完整更新 →](docs/releases/v2.2.0.md)
+> **v2.2.1：稳定性热修——修复大型 Session repair 卡死、accessor fetch 组合、非整除 pixel diff 边界与本地 Ollama 推理占满答案预算；公开最低 Host 仍保持 `0.1.0-rc.8`。** [查看完整更新 →](docs/releases/v2.2.1.md)
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="演示：粘贴图片，Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />

package/docs/releases/v2.2.1.md

@@ -0,0 +1,22 @@
+# v2.2.1
+
+DSH Vision Router 2.2.1 is a focused stability and compatibility hotfix for the 2.2.0 line.
+
+## Highlights
+
+- Fixes the large-session repair regressions in #524 and #532. On supported DSH Hosts, production tool-result and guard-stop repair now consumes bounded post-commit `session/event` entries and performs zero live Session-history reads: no `sessionQuery.readEvent()`, no `observeSession.events` materialization, and no new `eventAt()` / `snapshotEvents()` dependency. This removes the original full-clone amplification and the later `Unable to deserialize cloned data` / Windows Node 24 native-crash path.
+- Fixes global `fetch` compatibility composition with accessor-based Host/plugin pipelines (#519), preventing wrapper cycles while preserving live Host middleware authority.
+- Fixes `vision_pixel_diff` worst-region bounds on non-divisible image/grid dimensions (#520).
+- Fixes the confirmed Ollama portion of #526 by disabling hidden reasoning for generated local Ollama vision providers on the OpenAI-compatible Chat Completions path, preserving the bounded token budget for visible answer text.
+- Completes the release-channel canary fixture so stable/latest and preview/alpha validate the same Session publication family before Host contract smoke.
+
+## Compatibility
+
+- Node 22 and Node 24 remain supported.
+- Windows, macOS, and Linux remain gated.
+- The public minimum DSH Host remains `0.1.0-rc.8`.
+- Existing 2.2.0 settings require no migration.
+
+## Known follow-ups
+
+- #526 remains open for the LM Studio reasoning/budget path; 2.2.1 does not send Ollama-specific `reasoning_effort` to LM Studio without a documented LM Studio wire contract.

package/lib/core-primitives.js

@@ -1858,6 +1858,10 @@ export function localOllamaProvidersOf(config) {
       model,
       apiKeyEnv: '',
       maxTokens: 2048,
+      // Ollama's OpenAI-compatible Chat Completions endpoint supports
+      // reasoning_effort='none'. Vision extraction should spend the bounded
+      // completion budget on observable answer text rather than hidden thought.
+      reasoningEffort: 'none',
       // 仅显式选择 anthropic 格式时携带（默认 openai 路径保持字节不变）。
       ...(local.format === 'anthropic' ? { format: 'anthropic' } : {}),
       // 建议值透传：温度/top_p 只在显式配置时携带（callOpenAICompatible
@@ -1978,6 +1982,9 @@ export async function callLocalBackend(provider, messages, options = {}) {
     ...(typeof options.resolveCredential === 'function'
       ? { resolveCredential: options.resolveCredential }
       : {}),
+    ...(typeof provider.reasoningEffort === 'string'
+      ? { reasoningEffort: provider.reasoningEffort }
+      : {}),
     ...sampling,
   })
 }
@@ -2121,6 +2128,7 @@ export async function callOpenAICompatible(provider, messages, options = {}) {
     if (resolvedApiKey === '') throw new Error(`http provider "${provider.name}": ${apiKeyEnv} is not set`)
     headers.authorization = `Bearer ${resolvedApiKey}`
   }
+  const reasoningEffort = options.reasoningEffort ?? provider.reasoningEffort
   const body = {
     model: provider.model,
     messages,
@@ -2130,6 +2138,9 @@ export async function callOpenAICompatible(provider, messages, options = {}) {
     // never pass them, so the wire body stays byte-identical for main paths.
     ...(typeof options.temperature === 'number' ? { temperature: options.temperature } : {}),
     ...(typeof options.top_p === 'number' ? { top_p: options.top_p } : {}),
+    ...(['none', 'low', 'medium', 'high', 'max'].includes(reasoningEffort)
+      ? { reasoning_effort: reasoningEffort }
+      : {}),
   }
   const url = `${provider.baseURL.replace(/\/$/, '')}/chat/completions`
   const request = () =>

package/lib/dsh-contract-compat.js

@@ -192,17 +192,40 @@ export function createSessionEventTailReader(ctx) {
 
 
 /**
- * Build the narrow asynchronous Session-log reader used only for cold
- * canonical attachment recovery after the bounded cache evicts a ref.
- * Supported Hosts own replay validation through `sessionQuery.readSession()`;
- * callers receive detached events and never touch synchronous Session history.
+ * Build the asynchronous Session-log reader used by cold attachment recovery
+ * and batched surface repair. Prefer SessionQuery's observation lease when it
+ * exists: one exact live cut materializes at most one immutable event snapshot,
+ * rather than cloning the whole live corpus once per requested event (#524).
+ * Hosts without that capability retain the released readSession() contract.
  */
 export function createSessionLogReader(ctx) {
   return async function readSessionLog(session) {
     const sessionId = session?.id
     if (sessionId === undefined || sessionId === null) return { supported: false }
     const query = sessionQueryOf(ctx)
-    if (!query || typeof query.readSession !== 'function') return { supported: false }
+    if (!query) return { supported: false }
+
+    if (typeof query.observeSession === 'function') {
+      let observation
+      try {
+        observation = await query.observeSession(sessionId, { projectionMode: 'none' })
+        if (!observation || !Array.isArray(observation.events)) {
+          throw new Error('sessionQuery.observeSession returned no event log')
+        }
+        const observedId = observation.header?.id
+        if (observedId !== undefined && observedId !== sessionId) {
+          throw new Error(
+            `sessionQuery.observeSession returned session ${String(observedId)} for requested ${String(sessionId)}`,
+          )
+        }
+        return { supported: true, events: observation.events }
+      } finally {
+        const dispose = observation?.[Symbol.dispose]
+        if (typeof dispose === 'function') dispose.call(observation)
+      }
+    }
+
+    if (typeof query.readSession !== 'function') return { supported: false }
     const snapshot = await query.readSession(sessionId)
     if (!snapshot || !Array.isArray(snapshot.events)) {
       throw new Error('sessionQuery.readSession returned no event log')

package/lib/fetch-wrapper-lifecycle.js

@@ -0,0 +1,56 @@
+// Lifecycle metadata only: no native fetch snapshot, dispatcher, or egress
+// policy is retained here. Weak keys let abandoned wrapper chains be collected.
+const installations = new WeakMap()
+
+function livePreviousDescriptor(descriptor) {
+  let previous = descriptor
+  while (previous && Object.hasOwn(previous, 'value')) {
+    const installation = installations.get(previous.value)
+    if (!installation?.disposed) break
+    previous = installation.previous
+  }
+  return previous
+}
+
+/** Preserve a live accessor-owned pipeline, including middleware recomposition. */
+export function captureFetchDelegate(target = globalThis) {
+  const descriptor = Object.getOwnPropertyDescriptor(target, 'fetch')
+  const current = target.fetch
+  if (typeof current !== 'function' || typeof descriptor?.get !== 'function') return current
+  return (input, init) => Reflect.apply(Reflect.apply(descriptor.get, target, []), target, [input, init])
+}
+
+/**
+ * Publish an already constructed fetch wrapper without calling a foreign
+ * accessor setter. Assignment is unsafe: a pipeline getter may return a
+ * function whose setter adopts our wrapper as its own delegate (#519).
+ *
+ * The caller captures the CURRENT Host chain at installation, never at module
+ * load, and disables its own behavior before restoring. Later Host replacements
+ * remain authoritative. Restore the exact previous descriptor only while our
+ * data property still owns the surface; never feed a wrapper back to a setter.
+ * Non-configurable accessors cannot be composed this way and fail before any
+ * mutation rather than silently bypassing a Host policy or explicit proxy.
+ */
+export function installFetchWrapper(wrapped, target = globalThis) {
+  if (typeof wrapped !== 'function') throw new TypeError('fetch wrapper must be a function')
+  const previous = Object.getOwnPropertyDescriptor(target, 'fetch')
+  if (previous && Object.hasOwn(previous, 'value') && previous.value === wrapped) return () => {}
+  const installed = previous && Object.hasOwn(previous, 'value')
+    ? { ...previous, value: wrapped }
+    : { configurable: true, enumerable: previous?.enumerable ?? true, writable: true, value: wrapped }
+  Object.defineProperty(target, 'fetch', installed)
+  const installation = { previous, disposed: false }
+  installations.set(wrapped, installation)
+  return () => {
+    if (installation.disposed) return
+    installation.disposed = true
+    const current = Object.getOwnPropertyDescriptor(target, 'fetch')
+    if (!current || !Object.hasOwn(current, 'value') || current.value !== wrapped ||
+        current.configurable !== installed.configurable ||
+        current.enumerable !== installed.enumerable || current.writable !== installed.writable) return
+    const restore = livePreviousDescriptor(previous)
+    if (restore) Object.defineProperty(target, 'fetch', restore)
+    else delete target.fetch
+  }
+}

package/lib/legacy-global-proxy-boundary.js

@@ -1,3 +1,4 @@
+import { captureFetchDelegate, installFetchWrapper } from './fetch-wrapper-lifecycle.js'
 // H2: retain the legacy Host-owned proxy override as a scoped compatibility
 // transport, not as process-wide routing authority. The wrapper is always
 // transparent unless one DVR-owned visual adapter call is active (or the
@@ -184,7 +185,7 @@ function proxyHostsOf(config) {
  * the narrow legacy direct whole-turn fallback above.
  */
 export function installLegacyGlobalProxyBoundary(ctx, config = {}, options = {}) {
-  const originalFetch = typeof options.originalFetch === 'function' ? options.originalFetch : globalThis.fetch
+  const originalFetch = typeof options.originalFetch === 'function' ? options.originalFetch : captureFetchDelegate()
   const importUndici = typeof options.importUndici === 'function' ? options.importUndici : () => import('undici')
   if (typeof originalFetch !== 'function') return () => {}
 
@@ -227,14 +228,14 @@ export function installLegacyGlobalProxyBoundary(ctx, config = {}, options = {})
     })
   }
 
-  globalThis.fetch = scopedFetch
+  const restoreFetch = installFetchWrapper(scopedFetch)
   let disposed = false
   const dispose = () => {
     if (disposed) return
     disposed = true
     active = false
     void dispatcherPool.dispose()
-    if (globalThis.fetch === scopedFetch) globalThis.fetch = originalFetch
+    restoreFetch()
   }
   if (typeof ctx?.effect === 'function') {
     try {

package/lib/pi-ai-bridge-wire-compat.js

@@ -1,3 +1,4 @@
+import { captureFetchDelegate, installFetchWrapper } from './fetch-wrapper-lifecycle.js'
 import { currentVisionSessionAffinityId } from './session-affinity-runtime.js'
 import { isOfficialOpenCodeGoUrl, openCodeSessionAffinityHeaderForUrl } from './session-affinity.js'
 
@@ -283,7 +284,7 @@ export function applyPiAiBridgeWireFacts(init, body, facts) {
  * wrapper even if another later patch sits above it in the fetch chain.
  */
 export function installPiAiBridgeWireCompat(ctx, logger) {
-  const original = globalThis.fetch
+  const original = captureFetchDelegate()
   if (typeof original !== 'function') return () => {}
   let active = true
   const wrapped = async (input, init) => {
@@ -334,10 +335,10 @@ export function installPiAiBridgeWireCompat(ctx, logger) {
     }
     return Reflect.apply(original, globalThis, [input, patchedInit])
   }
-  globalThis.fetch = wrapped
+  const restoreFetch = installFetchWrapper(wrapped)
   const cleanup = () => {
     active = false
-    if (globalThis.fetch === wrapped) globalThis.fetch = original
+    restoreFetch()
   }
   try {
     ctx?.effect?.(() => cleanup, 'vision-router: pi-ai bridge wire compatibility')

package/lib/pixel-diff-stream.js

@@ -37,12 +37,18 @@ class AsyncByteReader {
 function cellBounds(index, width, height, cols, rows) {
   const cx = index % cols
   const cy = Math.floor(index / cols)
-  const cw = Math.ceil(width / cols)
-  const ch = Math.ceil(height / rows)
-  const x1 = cx * cw
-  const y1 = cy * ch
-  const x2 = Math.min((cx + 1) * cw, width)
-  const y2 = Math.min((cy + 1) * ch, height)
+  // Uniform boundaries mirror the counting map floor(x * cells / extent)
+  // exactly: with cells <= extent (the grid clamp above guarantees it),
+  // ceil(c * extent / cells) rises by at least 1 per cell, so every cell is
+  // non-empty and every pixel lands inside the cell the counters credited
+  // it to. The previous ceil-stride bounds drifted from that map whenever
+  // extent was not a multiple of cells, shifting worst-region boxes and, on
+  // tiny extents, dropping counted pixels from cells whose bounds collapsed
+  // to zero width.
+  const x1 = Math.ceil((cx * width) / cols)
+  const y1 = Math.ceil((cy * height) / rows)
+  const x2 = Math.ceil(((cx + 1) * width) / cols)
+  const y2 = Math.ceil(((cy + 1) * height) / rows)
   return { x1, y1, x2, y2, total: Math.max(0, x2 - x1) * Math.max(0, y2 - y1) }
 }
 

package/lib/session-vision-index.js

@@ -2,6 +2,8 @@ import { currentSessionSurfacePolicy } from './session-surface-policy.js'
 import { sessionSurfaceReplacementIntent } from './session-surface-compat.js'
 import { createSessionVisionStateStore } from './session-vision-state.js'
 
+const MAX_PENDING_REPAIR_EVENTS = 256
+
 function isObject(value) {
   return value !== null && typeof value === 'object'
 }
@@ -39,13 +41,23 @@ function boundedMessage(error) {
   return String(text ?? '').slice(0, 400)
 }
 
+function isReplacementEvent(event) {
+  const op = event?.surfaceOp
+  return !!op && typeof op === 'object' && !Array.isArray(op) && op.op === 'replace'
+}
+
 /**
  * Session visual data-plane index.
  *
  * SessionVisionStateStore remains the bounded storage owner. This object owns
- * target-only durable attachment recovery after bounded-cache eviction,
- * bounded Host-backed tool-result image surface repair and expired structured
- * guard-stop surface repair.
+ * target-only durable attachment recovery, event-feed-backed tool-result image
+ * surface repair and expired structured guard-stop surface repair.
+ *
+ * Supported DSH Hosts expose the post-commit `session/event` feed. Production
+ * surface repair consumes only the exact frozen events observed on that feed;
+ * it never asks SessionQuery to materialize or clone the live Session history.
+ * The older reader path remains only for isolated/partial callers that do not
+ * install the event feed boundary.
  *
  * The index never replaces stateStore.lookupAttachment(). Cache lookup stays
  * synchronous through lookupAttachment(); cold durable recovery is requested
@@ -73,16 +85,20 @@ export function createSessionVisionIndex({
     : undefined
   const toolSurfaceScans = new WeakMap()
   const guardSurfaceScans = new WeakMap()
+  const pendingToolRepairEvents = new WeakMap()
+  const pendingGuardRepairEvents = new WeakMap()
   const unsupportedSurfaceContracts = new WeakSet()
   const repairReadWarnings = new WeakMap()
+  const repairFeedOverflowWarnings = new WeakSet()
+  const repairFeedObserverWarnings = new WeakMap()
   const attachmentRecoveryWarnings = new WeakMap()
+  let surfaceEventFeedActive = false
 
   const recordAttachments = (session, refs) => {
     if (!session || !Array.isArray(refs) || refs.length === 0) return
     store.recordAttachments(session, refs)
   }
 
-
   // Synchronous lookup is cache-only. Projected short handles first warm this
   // cache from current derived messages and must not trigger historical I/O.
   const lookupAttachment = (session, id) => {
@@ -217,13 +233,47 @@ export function createSessionVisionIndex({
     }
 
     // Isolated/partial Hosts that do not expose SessionQuery retain the released
-    // Session-local compatibility path. Supported production Hosts use the
-    // bounded async reader above and never silently fall back after a read error.
+    // Session-local compatibility path. Supported production Hosts install the
+    // event feed and never enter this compatibility reader.
     const events = legacySessionEvents(session)
     if (!events) return { readable: false }
     return { readable: true, event: events[seq] }
   }
 
+  const surfaceRepairSnapshot = async (session, seq) => {
+    if (typeof readSessionLog !== 'function') return undefined
+    let result
+    try {
+      result = await readSessionLog(session)
+    } catch (error) {
+      warnRepairReadFailure(session, seq, error)
+      return { readable: false }
+    }
+    if (result?.supported === true) {
+      if (!Array.isArray(result.events)) {
+        warnRepairReadFailure(session, seq, new Error('Session log reader returned no event log'))
+        return { readable: false }
+      }
+      repairReadWarnings.delete(session)
+      return { readable: true, events: result.events }
+    }
+    if (result?.supported !== false) {
+      warnRepairReadFailure(session, seq, new Error('Session log reader returned an invalid capability result'))
+      return { readable: false }
+    }
+    return undefined
+  }
+
+  const eventFromRepairSnapshot = (session, events, seq) => {
+    const event = events?.[seq]
+    if (!event || typeof event !== 'object' || (event.seq !== undefined && event.seq !== seq)) {
+      warnRepairReadFailure(session, seq, new Error(`Session repair snapshot has no event at seq ${seq}`))
+      return { readable: false }
+    }
+    repairReadWarnings.delete(session)
+    return { readable: true, event }
+  }
+
   const keepToolResultImages = () => {
     const policy = currentSessionSurfacePolicy(
       typeof config === 'function' ? config() : config,
@@ -244,14 +294,165 @@ export function createSessionVisionIndex({
     return undefined
   }
 
+  const cachePendingRepairEvent = (pendingBySession, session, event) => {
+    if (!session || !Number.isSafeInteger(event?.seq) || event.seq < 0 || Object.is(event.seq, -0)) return
+    let pending = pendingBySession.get(session)
+    if (!pending) {
+      pending = new Map()
+      pendingBySession.set(session, pending)
+    }
+    if (!pending.has(event.seq) && pending.size >= MAX_PENDING_REPAIR_EVENTS) {
+      const oldest = pending.keys().next().value
+      if (oldest !== undefined) pending.delete(oldest)
+      if (!repairFeedOverflowWarnings.has(session)) {
+        repairFeedOverflowWarnings.add(session)
+        logger?.warn?.(
+          'vision-router: session surface repair event feed exceeded %s pending events; dropping oldest entry',
+          MAX_PENDING_REPAIR_EVENTS,
+        )
+      }
+    }
+    pending.set(event.seq, event)
+  }
+
+  const planAgainstOneEvent = (event, planner) => {
+    if (!Number.isSafeInteger(event?.seq) || event.seq < 0 || Object.is(event.seq, -0)) return []
+    const events = { [event.seq]: event }
+    return planner(events, [event.seq])
+  }
+
+  const recordSessionEvent = (session, event) => {
+    if (!session || !event || typeof event !== 'object') return
+    try {
+      if (typeof core.collectEventAttachmentRefs === 'function') {
+        const refs = core.collectEventAttachmentRefs([event])
+        if (Array.isArray(refs) && refs.length > 0) recordAttachments(session, refs)
+      }
+
+      // Replacement events are consequences of this repair path and must never
+      // be re-enqueued, otherwise a guard-stop replacement would shadow itself
+      // forever because its stable plugin-owned id is intentionally preserved.
+      if (isReplacementEvent(event)) return
+
+      if (event.type === 'tool/result' && typeof core.planToolResultImageShadows === 'function') {
+        const plans = planAgainstOneEvent(
+          event,
+          (events, seqs) => core.planToolResultImageShadows(events, seqs, () => true),
+        )
+        if (plans.length > 0) cachePendingRepairEvent(pendingToolRepairEvents, 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)
+      }
+      repairFeedObserverWarnings.delete(session)
+    } catch (error) {
+      const message = boundedMessage(error)
+      if (repairFeedObserverWarnings.get(session) === message) return
+      repairFeedObserverWarnings.set(session, message)
+      logger?.warn?.('vision-router: session event feed observation failed error=%s', message)
+    }
+  }
+
+  const activateSurfaceEventFeed = () => {
+    surfaceEventFeedActive = true
+  }
+
+  const consumePendingRepairEvents = (pendingBySession, session) => {
+    const pending = pendingBySession.get(session)
+    if (!pending || pending.size === 0) return []
+    const nodes = surfaceNodes(session)
+    if (!nodes || nodes.length === 0) {
+      pending.clear()
+      return []
+    }
+    const current = new Set(nodes)
+    for (const seq of pending.keys()) {
+      if (!current.has(seq)) pending.delete(seq)
+    }
+    const entries = []
+    for (const seq of nodes) {
+      const event = pending.get(seq)
+      if (event === undefined) continue
+      pending.delete(seq)
+      entries.push({ seq, event })
+    }
+    return entries
+  }
+
+  const repairToolResultSurfaceFromFeed = async (session) => {
+    if (typeof session?.append !== 'function' || typeof core.planToolResultImageShadows !== 'function') return 0
+    const pending = consumePendingRepairEvents(pendingToolRepairEvents, session)
+    if (pending.length === 0) return 0
+    const preserve = keepToolResultImages()
+    let repaired = 0
+    for (const { seq, event } of pending) {
+      const events = { [seq]: event }
+      const plans = core.planToolResultImageShadows(events, [seq], () => !preserve)
+      for (const plan of plans) {
+        try {
+          const intent = replacementIntent(session, plan.seq)
+          if (intent === undefined) continue
+          await session.append(
+            'tool/result',
+            { ...plan.event.data, message: plan.message },
+            intent,
+          )
+          repaired += 1
+        } catch (error) {
+          logger?.warn?.(
+            'vision-router: session tool-result surface repair failed seq=%s error=%s',
+            plan.seq,
+            boundedMessage(error),
+          )
+        }
+      }
+    }
+    return repaired
+  }
+
+  const repairGuardStopSurfaceFromFeed = async (session) => {
+    if (typeof session?.append !== 'function' || typeof core.planGuardStopShadows !== 'function') return 0
+    const pending = consumePendingRepairEvents(pendingGuardRepairEvents, session)
+    if (pending.length === 0) return 0
+    let repaired = 0
+    for (const { seq, event } of pending) {
+      const events = { [seq]: event }
+      const plans = core.planGuardStopShadows(events, [seq])
+      for (const plan of plans) {
+        try {
+          const intent = replacementIntent(session, plan.seq)
+          if (intent === undefined) continue
+          await session.append(
+            'user/message',
+            plan.data,
+            intent,
+          )
+          repaired += 1
+        } catch (error) {
+          logger?.warn?.(
+            'vision-router: session guard-stop surface repair failed seq=%s error=%s',
+            plan.seq,
+            boundedMessage(error),
+          )
+        }
+      }
+    }
+    return repaired
+  }
+
   const repairToolResultSurface = async (session) => {
+    if (surfaceEventFeedActive) return repairToolResultSurfaceFromFeed(session)
     if (typeof session?.append !== 'function') return 0
     const scan = pendingSurfaceScan(toolSurfaceScans, session)
     if (!scan || typeof core.planToolResultImageShadows !== 'function') return 0
     const preserve = keepToolResultImages()
+    const snapshot = await surfaceRepairSnapshot(session, scan.seqs[0])
+    if (snapshot?.readable === false) return 0
     let repaired = 0
     for (const seq of scan.seqs) {
-      const read = await eventForSurfaceRepair(session, seq)
+      const read = snapshot?.readable === true
+        ? eventFromRepairSnapshot(session, snapshot.events, seq)
+        : await eventForSurfaceRepair(session, seq)
       if (!read.readable) break
       // A readable node is settled for this repair pass even when it needs no
       // replacement or append later fails; only an unread node remains pending.
@@ -282,12 +483,17 @@ export function createSessionVisionIndex({
   }
 
   const repairGuardStopSurface = async (session) => {
+    if (surfaceEventFeedActive) return repairGuardStopSurfaceFromFeed(session)
     if (typeof session?.append !== 'function') return 0
     const scan = pendingSurfaceScan(guardSurfaceScans, session)
     if (!scan || typeof core.planGuardStopShadows !== 'function') return 0
+    const snapshot = await surfaceRepairSnapshot(session, scan.seqs[0])
+    if (snapshot?.readable === false) return 0
     let repaired = 0
     for (const seq of scan.seqs) {
-      const read = await eventForSurfaceRepair(session, seq)
+      const read = snapshot?.readable === true
+        ? eventFromRepairSnapshot(session, snapshot.events, seq)
+        : await eventForSurfaceRepair(session, seq)
       if (!read.readable) break
       scan.advance()
       const events = []
@@ -333,6 +539,8 @@ export function createSessionVisionIndex({
 
   return Object.freeze({
     recordAttachments,
+    recordSessionEvent,
+    activateSurfaceEventFeed,
     lookupAttachment,
     resolveAttachment,
     resolveAttachments,
@@ -344,8 +552,9 @@ export function createSessionVisionIndex({
 
 /**
  * Intercept core's pre-step registration and decorate only its downstream
- * `next()` result. Production passes `options.index`; direct/test callers get
- * an isolated index/store unless they explicitly provide `options.stateStore`.
+ * `next()` result. Production also subscribes the index to DSH's post-commit
+ * `session/event` feed before activating feed-backed surface repair. Direct/test
+ * callers without a usable event feed retain the compatibility reader path.
  */
 export function installSessionVisionIndexBoundary(ctx, config, core, options = {}) {
   if (!isObject(ctx)) return ctx
@@ -363,6 +572,25 @@ export function installSessionVisionIndexBoundary(ctx, config, core, options = {
     logger: options.logger,
   })
 
+  try {
+    const on = Reflect.get(ctx, 'on', ctx)
+    if (
+      typeof on === 'function'
+      && typeof index.recordSessionEvent === 'function'
+      && typeof index.activateSurfaceEventFeed === 'function'
+    ) {
+      on.call(ctx, 'session/event', (session, event) => {
+        index.recordSessionEvent(session, event)
+      })
+      index.activateSurfaceEventFeed()
+    }
+  } catch (error) {
+    options.logger?.warn?.(
+      'vision-router: session event feed unavailable; retaining compatibility surface reader error=%s',
+      boundedMessage(error),
+    )
+  }
+
   return new Proxy(ctx, {
     get(target, property) {
       if (property === 'on') {

package/lib/vision-breaker-shadow-health.js

@@ -3,7 +3,17 @@ import { createSessionTurnResolver } from './session-turn-resolver.js'
 
 function legacyTurnNumberOf(session) {
   try {
-    const events = session?.events
+    // dsh 0.1.2-alpha.4 removed the bare `session.events` array in favor of
+    // `session.snapshotEvents()`; mirror legacySessionEvents
+    // (session-vision-index.js), which prefers the snapshot when both surfaces
+    // exist — transitional Hosts keep the bare array but leave it stale, so a
+    // bare-array-first read would resolve a stale turn on them.
+    let events
+    if (typeof session?.snapshotEvents === 'function') {
+      events = session.snapshotEvents()
+    } else {
+      events = session?.events
+    }
     if (!Array.isArray(events)) return 0
     const last = events.findLast((event) => event && event.type === 'turn/start')
     return last && Number.isInteger(last.data?.turn) ? last.data.turn : 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vision-router",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Eyes for text-only DeepSeek Harness agents: built-in free vision chain (no key) + pixel-level vision tools (Q&A, grounding, crop, pixel diff, colors, OCR, SVG trace, cutout, screenshots). One-command install, no Python, image turns work like ordinary tool-calling turns.",
   "license": "MIT",
   "repository": {
@@ -70,12 +70,12 @@
     "sharp": "^0.35.4"
   },
   "scripts": {
-    "test": "node --test tests/index-modularization.test.js tests/adapter-prepare-call-compat.test.js tests/core.test.js tests/issue-374-delegated-call-config.test.js tests/grounding-coordinate-frame.test.js tests/grounding-coordinate-runtime.test.js tests/capability-advisory.test.js tests/vision-execution-policy.test.js tests/vision-backend-diagnostics.test.js tests/live-model-discovery.test.js tests/live-model-credential-resolution.test.js tests/vision-model-registry.test.js tests/live-model-client-stability.test.js tests/providers-persistence.test.js tests/provider-directory-fallback.test.js tests/model-catalog-policy.test.js tests/settings-ia-client-prelude.test.js tests/settings-ia-fj.test.js tests/settings-ia-acceptance-regression.test.js tests/settings-migration.test.js tests/settings-section-order.test.js tests/attachment-admission-policy.test.js tests/vision-resilience.test.js tests/degraded-local-evidence.test.js tests/vision-resilience-lifecycle.test.js tests/vision-breaker-readonly.test.js tests/alpha1-browser-lifecycle-integration.test.js tests/issue-367-remote-session-inject.test.js tests/vision-mode-toggle-injection.test.js tests/client.test.js tests/issue-307-regression.test.js tests/issue-284-vision-mode-toggle.test.js tests/issue-284-vision-mode-hardening.test.js tests/issue-284-attachment-id-hint.test.js tests/issue-284-model-visibility.test.js tests/issue-284-vision-selection-effort.test.js tests/client-presentation-boundary.test.js tests/clipboard-image-paste-compat.test.js tests/remote-settings-bridge.test.js tests/remote-settings-v2-contract.test.js tests/remote-settings-risk-confirmation.test.js tests/local-remote-settings-permission.test.js tests/rc6-real-settings-persistence.test.js tests/artifact-path-security.test.js tests/http-compat.test.js tests/catalog-corrections.test.js tests/update-check.test.js tests/update-check-signal-lifecycle.test.js tests/self-update.test.js tests/doctor.test.js tests/doctor-cli.test.js tests/legacy-session-repair.test.js tests/profile-pnpm-diagnostics.test.js tests/doctor-v2.test.js tests/doctor-cli-v2.test.js tests/doctor-runtime.test.js tests/dsh-host-capabilities.test.js tests/doctor-host-capabilities.test.js tests/session-repair-v2.test.js tests/bundle-defaults.test.js tests/file-logger.test.js tests/official-deepseek-catalog.test.js tests/replay-delegation.test.js tests/twin-image-capability-fallback.test.js tests/twin-image-custom-wrapper.test.js tests/adversarial-hardening.test.js tests/vision-adversarial-hardening-v2.test.js tests/vision-capability-benchmark-visual-proof.test.js tests/wrapper-directory.test.js tests/logging-ui.test.js tests/manifest-dependencies.test.js tests/structured-bootstrap.test.js tests/structured-bootstrap-gate.test.js tests/vision-model-guidance-contract.test.js tests/local-ollama.test.js tests/ollama-cold-start.test.js tests/ollama-cold-start-loaded.test.js tests/zero-regression-gate.test.js tests/runtime-e2e.test.js tests/local-vision-stabilizer.test.js tests/local-connection-probe.test.js tests/repetition-guard.test.js tests/guide-scroll-gate.test.js tests/settings-scroll-jank-regression.test.js tests/android-attachment-compat.test.js tests/free-cloud-first.test.js tests/rc6-rc7-compat.test.js tests/native-image-coexistence.test.js tests/issue-276-session-image-ownership.test.js tests/issue-276-entry-policy-bridge.test.js tests/issue-276-policy-hardening.test.js tests/issue-289-native-nonintervention.test.js tests/issue-512-tool-restriction.test.js tests/pi-ai-bridge-wire-compat.test.js tests/mixed-router.test.js tests/depth-tier.test.js tests/depth-quota-behavior.test.js tests/structured-flow-hardening.test.js tests/structured-flow-adversarial.test.js tests/vision-budget-activation.test.js tests/runtime-boundary-fixes.test.js tests/security-resource-boundaries.test.js tests/security-property-fuzz.test.js tests/security-adversarial-fuzz-contract.test.js tests/runtime-i18n.test.js tests/tesseract-adaptive-ocr.test.js tests/tesseract-node24-boot.test.js tests/session-vision-state.test.js tests/session-vision-state-integration.test.js tests/image-resource-governor.test.js tests/resource-retention-lifecycle.test.js tests/pixel-diff-stream.test.js tests/large-image-resource-integration.test.js tests/structured-guard-idempotency.test.js tests/vision-routing-product.test.js tests/vision-runtime-performance.test.js tests/vision-routing-settings-prelude.test.js tests/v2-settings-ia-integration.test.js tests/vision-capability-router.test.js tests/vision-capability-reference.test.js tests/vision-capability-benchmark.test.js tests/vision-capability-grounding-proof-contract.test.js tests/vision-capability-probe.test.js tests/vision-capability-axis-freshness.test.js tests/vision-capability-shadow-health.test.js tests/vision-capability-benchmark-service.test.js tests/vision-capability-preflight-hardening.test.js tests/vision-capability-benchmark-contract.test.js tests/vision-capability-benchmark-client.test.js tests/vision-capability-benchmark-client-productization.test.js tests/vision-capability-adapter-route.test.js tests/vision-background-benchmark.test.js tests/vision-background-lifecycle.test.js tests/vision-background-benchmark-productization.test.js tests/vision-capability-benchmark-budget.test.js tests/vision-image-input-verdict.test.js tests/vision-capability-failure-classification.test.js tests/vision-capability-gate-client.test.js tests/v2-product-review-fixes.test.js tests/qa-top5-reliability.test.js tests/qa-screenshot-runtime.test.js tests/qa-runtime-identity.test.js tests/qa-turn-budget-cancellation.test.js tests/qa-cancellation-publication.test.js tests/qa-reliability-tail.test.js tests/qa-endpoint-route-alias.test.js tests/settings-native-card-semantics.test.js tests/settings-native-card-lazy-data.test.js tests/settings-invalid-staged-dirty.test.js tests/vision-toggle-root-hardening.test.js && node --test tests/vision-backend-runtime-policy.test.js",
+    "test": "node --test tests/index-modularization.test.js tests/adapter-prepare-call-compat.test.js tests/core.test.js tests/issue-374-delegated-call-config.test.js tests/grounding-coordinate-frame.test.js tests/grounding-coordinate-runtime.test.js tests/capability-advisory.test.js tests/vision-execution-policy.test.js tests/vision-backend-diagnostics.test.js tests/live-model-discovery.test.js tests/live-model-credential-resolution.test.js tests/vision-model-registry.test.js tests/live-model-client-stability.test.js tests/providers-persistence.test.js tests/provider-directory-fallback.test.js tests/model-catalog-policy.test.js tests/settings-ia-client-prelude.test.js tests/settings-ia-fj.test.js tests/settings-ia-acceptance-regression.test.js tests/settings-migration.test.js tests/settings-section-order.test.js tests/attachment-admission-policy.test.js tests/vision-resilience.test.js tests/degraded-local-evidence.test.js tests/vision-resilience-lifecycle.test.js tests/vision-breaker-readonly.test.js tests/alpha1-browser-lifecycle-integration.test.js tests/issue-367-remote-session-inject.test.js tests/vision-mode-toggle-injection.test.js tests/client.test.js tests/issue-307-regression.test.js tests/issue-284-vision-mode-toggle.test.js tests/issue-284-vision-mode-hardening.test.js tests/issue-284-attachment-id-hint.test.js tests/issue-284-model-visibility.test.js tests/issue-284-vision-selection-effort.test.js tests/client-presentation-boundary.test.js tests/clipboard-image-paste-compat.test.js tests/remote-settings-bridge.test.js tests/remote-settings-v2-contract.test.js tests/remote-settings-risk-confirmation.test.js tests/local-remote-settings-permission.test.js tests/rc6-real-settings-persistence.test.js tests/artifact-path-security.test.js tests/http-compat.test.js tests/catalog-corrections.test.js tests/update-check.test.js tests/update-check-signal-lifecycle.test.js tests/self-update.test.js tests/doctor.test.js tests/doctor-cli.test.js tests/legacy-session-repair.test.js tests/profile-pnpm-diagnostics.test.js tests/doctor-v2.test.js tests/doctor-cli-v2.test.js tests/doctor-runtime.test.js tests/dsh-host-capabilities.test.js tests/doctor-host-capabilities.test.js tests/session-repair-v2.test.js tests/bundle-defaults.test.js tests/file-logger.test.js tests/official-deepseek-catalog.test.js tests/replay-delegation.test.js tests/twin-image-capability-fallback.test.js tests/twin-image-custom-wrapper.test.js tests/adversarial-hardening.test.js tests/vision-adversarial-hardening-v2.test.js tests/vision-capability-benchmark-visual-proof.test.js tests/wrapper-directory.test.js tests/logging-ui.test.js tests/manifest-dependencies.test.js tests/structured-bootstrap.test.js tests/structured-bootstrap-gate.test.js tests/vision-model-guidance-contract.test.js tests/local-ollama.test.js tests/ollama-cold-start.test.js tests/ollama-cold-start-loaded.test.js tests/zero-regression-gate.test.js tests/runtime-e2e.test.js tests/local-vision-stabilizer.test.js tests/local-connection-probe.test.js tests/repetition-guard.test.js tests/guide-scroll-gate.test.js tests/settings-scroll-jank-regression.test.js tests/android-attachment-compat.test.js tests/free-cloud-first.test.js tests/rc6-rc7-compat.test.js tests/native-image-coexistence.test.js tests/issue-276-session-image-ownership.test.js tests/issue-276-entry-policy-bridge.test.js tests/issue-276-policy-hardening.test.js tests/issue-289-native-nonintervention.test.js tests/issue-512-tool-restriction.test.js tests/pi-ai-bridge-wire-compat.test.js tests/fetch-wrapper-lifecycle.test.js tests/fetch-wrapper-composition.test.js tests/mixed-router.test.js tests/depth-tier.test.js tests/depth-quota-behavior.test.js tests/structured-flow-hardening.test.js tests/structured-flow-adversarial.test.js tests/vision-budget-activation.test.js tests/runtime-boundary-fixes.test.js tests/security-resource-boundaries.test.js tests/security-property-fuzz.test.js tests/security-adversarial-fuzz-contract.test.js tests/runtime-i18n.test.js tests/tesseract-adaptive-ocr.test.js tests/tesseract-node24-boot.test.js tests/session-vision-state.test.js tests/session-vision-state-integration.test.js tests/session-vision-event-feed.test.js tests/image-resource-governor.test.js tests/resource-retention-lifecycle.test.js tests/pixel-diff-stream.test.js tests/large-image-resource-integration.test.js tests/structured-guard-idempotency.test.js tests/vision-routing-product.test.js tests/vision-runtime-performance.test.js tests/vision-routing-settings-prelude.test.js tests/v2-settings-ia-integration.test.js tests/vision-capability-router.test.js tests/vision-capability-reference.test.js tests/vision-capability-benchmark.test.js tests/vision-capability-grounding-proof-contract.test.js tests/vision-capability-probe.test.js tests/vision-capability-axis-freshness.test.js tests/vision-capability-shadow-health.test.js tests/vision-capability-benchmark-service.test.js tests/vision-capability-preflight-hardening.test.js tests/vision-capability-benchmark-contract.test.js tests/vision-capability-benchmark-client.test.js tests/vision-capability-benchmark-client-productization.test.js tests/vision-capability-adapter-route.test.js tests/vision-background-benchmark.test.js tests/vision-background-lifecycle.test.js tests/vision-background-benchmark-productization.test.js tests/vision-capability-benchmark-budget.test.js tests/vision-image-input-verdict.test.js tests/vision-capability-failure-classification.test.js tests/vision-capability-gate-client.test.js tests/v2-product-review-fixes.test.js tests/qa-top5-reliability.test.js tests/qa-screenshot-runtime.test.js tests/qa-runtime-identity.test.js tests/qa-turn-budget-cancellation.test.js tests/qa-cancellation-publication.test.js tests/qa-reliability-tail.test.js tests/qa-endpoint-route-alias.test.js tests/settings-native-card-semantics.test.js tests/settings-native-card-lazy-data.test.js tests/settings-invalid-staged-dirty.test.js tests/vision-toggle-root-hardening.test.js && node --test tests/vision-backend-runtime-policy.test.js",
     "test:core": "node --test tests/core.test.js tests/degraded-local-evidence.test.js tests/runtime-e2e.test.js tests/structured-bootstrap.test.js tests/structured-flow-hardening.test.js tests/structured-flow-adversarial.test.js tests/vision-execution-policy.test.js tests/vision-backend-runtime-policy.test.js",
     "test:routing": "node --test tests/issue-374-delegated-call-config.test.js tests/twin-image-capability-fallback.test.js tests/twin-image-custom-wrapper.test.js tests/vision-routing-product.test.js tests/vision-capability-router.test.js tests/vision-capability-probe.test.js tests/vision-capability-shadow-health.test.js tests/vision-runtime-performance.test.js tests/vision-background-benchmark.test.js tests/vision-image-input-verdict.test.js",
     "test:session": "node --test tests/session-vision-state.test.js tests/session-vision-state-integration.test.js tests/replay-delegation.test.js tests/legacy-session-repair.test.js tests/session-repair-v2.test.js tests/issue-276-session-image-ownership.test.js",
     "test:resources": "node --test tests/artifact-path-security.test.js tests/image-resource-governor.test.js tests/resource-retention-lifecycle.test.js tests/pixel-diff-stream.test.js tests/large-image-resource-integration.test.js tests/qa-turn-budget-cancellation.test.js tests/qa-cancellation-publication.test.js",
-    "test:compat": "node --test tests/adapter-prepare-call-compat.test.js tests/attachment-admission-policy.test.js tests/rc6-rc7-compat.test.js tests/rc6-real-settings-persistence.test.js tests/android-attachment-compat.test.js tests/http-compat.test.js tests/pi-ai-bridge-wire-compat.test.js tests/native-image-coexistence.test.js tests/tesseract-node24-boot.test.js tests/dsh-host-capabilities.test.js",
+    "test:compat": "node --test tests/adapter-prepare-call-compat.test.js tests/attachment-admission-policy.test.js tests/rc6-rc7-compat.test.js tests/rc6-real-settings-persistence.test.js tests/android-attachment-compat.test.js tests/http-compat.test.js tests/pi-ai-bridge-wire-compat.test.js tests/fetch-wrapper-lifecycle.test.js tests/fetch-wrapper-composition.test.js tests/native-image-coexistence.test.js tests/tesseract-node24-boot.test.js tests/dsh-host-capabilities.test.js",
     "test:web": "node --test tests/alpha1-browser-lifecycle-integration.test.js tests/issue-367-remote-session-inject.test.js tests/vision-mode-toggle-injection.test.js tests/client.test.js tests/client-presentation-boundary.test.js tests/clipboard-image-paste-compat.test.js tests/settings-ia-client-prelude.test.js tests/settings-ia-acceptance-regression.test.js tests/remote-settings-bridge.test.js tests/remote-settings-v2-contract.test.js tests/local-remote-settings-permission.test.js tests/v2-settings-ia-integration.test.js tests/logging-ui.test.js",
     "test:contract": "node --test tests/manifest-dependencies.test.js tests/bundle-defaults.test.js tests/zero-regression-gate.test.js tests/issue-289-native-nonintervention.test.js tests/issue-374-delegated-call-config.test.js tests/runtime-boundary-fixes.test.js tests/security-adversarial-fuzz-contract.test.js tests/runtime-i18n.test.js tests/adapter-prepare-call-compat.test.js tests/rc6-rc7-compat.test.js tests/attachment-admission-policy.test.js tests/dsh-host-capabilities.test.js tests/doctor-host-capabilities.test.js tests/structured-bootstrap.test.js tests/structured-bootstrap-gate.test.js",
     "test:grounding": "node --test tests/grounding-coordinate-frame.test.js tests/grounding-coordinate-runtime.test.js tests/vision-capability-grounding-proof-contract.test.js",