dsh-vision-router 2.1.7 → 2.2.0

package/index.js

@@ -17,10 +17,10 @@
 // advanced vision-only override for `proxyHosts`; Host-owned visual adapters use
 // a scoped compatibility wrapper, never configuration-wide process routing.
 
-// Compatibility shim: dsh 0.1.2-alpha.4 removed `session.events` in favor of
-// `session.snapshotEvents()`. This helper returns an array (or undefined) that
-// works on both old and new harness versions.
-function getSessionEvents(session) {
+// Legacy compatibility shim only. Modern supported Hosts use turnBoundary +
+// SessionQuery for ordinary runtime reads; this path remains for older/partial
+// Hosts that do not expose those capabilities.
+function legacySessionEvents(session) {
   if (!session) return undefined
   // alpha.4+ : snapshotEvents() returns a frozen array of the event log
   if (typeof session.snapshotEvents === 'function') {
@@ -60,6 +60,7 @@ import {
   anthropicMediaType,
 } from './lib/catalog-corrections.js'
 import { createCachedUpdateChecker } from './lib/update-check.js'
+import { getOfficialDeepSeekCatalog } from './lib/official-deepseek-catalog.js'
 import { probeLocalBackends } from './lib/local-connection-probe.js'
 import { detectDshSelfUpdatePlan, runDshPluginUpdate } from './lib/self-update.js'
 import {
@@ -95,6 +96,7 @@ import {
   scaleBox,
   scaledDimensions,
 } from './lib/image-resource-governor.js'
+import { createSessionEventReader, createSessionEventTailReader, createSessionLogReader, hostOwnsOfficialDeepSeekProvider } from './lib/dsh-contract-compat.js'
 import { createSessionVisionIndex } from './lib/session-vision-index.js'
 import { createSessionVisionStateStore } from './lib/session-vision-state.js'
 import {
@@ -104,12 +106,22 @@ import {
   readResponseJsonBounded,
   readResponseTextBounded,
 } from './lib/http-body-limit.js'
-import { writeArtifactFile } from './lib/artifact-boundary.js'
+import {
+  ARTIFACT_HANDOFF_RUN_ID,
+  ARTIFACT_RUNS_DIR,
+  normalizeArtifactsDir,
+  writeArtifactFile,
+  writePersistentArtifactFile,
+} from './lib/artifact-boundary.js'
+import { visionDescribeSuccessContext } from './lib/vision-evidence-guidance.js'
 import { stripTrailingSlashes } from './lib/string-normalization.js'
 import { streamWithLegacyGlobalProxyScope } from './lib/legacy-global-proxy-boundary.js'
 import { parseVersionComparator } from './lib/version-range.js'
 import { createCoalescingRunner } from './lib/adapter-update-coalescer.js'
 import { captureWindowsDesktop } from './lib/windows-desktop-capture.js'
+import { blocksHaveRetainedImage, isOffloadedImageBlock, offloadedImagePlaceholder } from './lib/image-offload-compat.js'
+import { createSessionTurnResolver } from './lib/session-turn-resolver.js'
+import { shouldBlockDegradedHostTool } from './lib/degraded-local-evidence.js'
 
 import {
   sharpPromise,
@@ -168,7 +180,7 @@ export const Config = z.object({
   wrapperRoute: z.string().default('deepseek-vision'),
   chainRoute: z.string().default('vision-chain'),
   // 默认关闭（issue #34 明确 opt-in）：关闭时官方 deepseek-official 路由
-  // 原样保留；唯一例外见 apply 里的 keep-alive 兜底（官方行被禁用时）。
+  // 原样保留；仅 legacy Host 保留 keep-alive 接管兼容（官方行被禁用时）。
   stealth: z.boolean().default(false),
   textProvider: z
     .object({
@@ -386,6 +398,7 @@ import {
   posterizeSvgColor,
   resolveVisionOcrEngine,
   ocrWithTesseract,
+  ocrWithTesseractAdaptive,
   estimateTokens,
   estimateMessages,
   trimMessagesToBudget,
@@ -482,6 +495,7 @@ export {
   posterizeSvgColor,
   resolveVisionOcrEngine,
   ocrWithTesseract,
+  ocrWithTesseractAdaptive,
   estimateTokens,
   estimateMessages,
   trimMessagesToBudget,
@@ -549,6 +563,8 @@ export function apply(ctx, config = {}, runtime = {}) {
   // adapter boundaries that do not expose a Session; ambiguous attachment ids
   // deliberately miss instead of crossing conversations.
   const sessionVisionRuntime = runtime?.sessionVision
+  const hostOwnsOfficialDeepSeek = runtime?.hostOwnsOfficialDeepSeek
+    ?? hostOwnsOfficialDeepSeekProvider(ctx)
   const visionState = sessionVisionRuntime?.stateStore ?? createSessionVisionStateStore({
     maxSessions: 64,
     idleTtlMs: 60 * 60 * 1000,
@@ -566,6 +582,8 @@ export function apply(ctx, config = {}, runtime = {}) {
     },
     config: () => current(),
     logger: ctx.logger,
+    readSessionEvent: createSessionEventReader(ctx),
+    readSessionLog: createSessionLogReader(ctx),
   })
   const imageMemory = visionState.descriptionFacade
   // #208 follow-up complete: session-visible paths use scoped memory; only
@@ -696,11 +714,18 @@ export function apply(ctx, config = {}, runtime = {}) {
   const visionBreaker = createVisionCircuitBreaker()
   const visionTurnMemory = createVisionTurnMemory()
 
-  // Same turn derivation the harness loop uses (dsh-agent-loop reads the last
-  // turn/start event), so tool-side memory and pre-step bindings agree.
+  const sessionTurnResolver = runtime?.sessionTurnResolver ?? createSessionTurnResolver(ctx)
+  const sessionEventTailReader = runtime?.sessionEventTailReader ?? createSessionEventTailReader(ctx)
+
+  // Current stable/preview Hosts expose the Agent loop's `turnBoundary`
+  // Session projection. Runtime composition shares one resolver with shadow
+  // health so breaker scopes cannot diverge; rc.8 retains the resolver's
+  // explicit legacy event fallback.
   const turnNumberOf = (session) => {
     try {
-      const events = getSessionEvents(session)
+      const projected = sessionTurnResolver.turnOf(session)
+      if (Number.isInteger(projected) && projected >= 0) return projected
+      const events = legacySessionEvents(session)
       if (!Array.isArray(events)) return 0
       const last = events.findLast((event) => event && event.type === 'turn/start')
       return last && Number.isInteger(last.data && last.data.turn) ? last.data.turn : 0
@@ -710,6 +735,41 @@ export function apply(ctx, config = {}, runtime = {}) {
   }
   const sessionIdOf = (session) => sessionIdentityOf(session) ?? 'anon'
   const visionScopeOf = (session) => `${sessionIdOf(session)}:${turnNumberOf(session)}`
+  const DEGRADED_LOCAL_REFINEMENT_LIMIT = 2
+  const visionEvidenceSourceKey = (value) => String(value ?? '').trim()
+  const degradedLocalFailure = (code, reason) => JSON.stringify({
+    ok: false,
+    code,
+    retryable: false,
+    reason,
+  })
+  const degradedLocalState = (session, source) => {
+    if (!session) return { active: false, scope: undefined, sourceKey: visionEvidenceSourceKey(source), used: 0 }
+    const scope = visionScopeOf(session)
+    const sourceKey = visionEvidenceSourceKey(source)
+    const active = visionTurnMemory.allFailed(scope) && visionTurnMemory.hasLocalOcr(scope, sourceKey)
+    return {
+      active,
+      scope,
+      sourceKey,
+      used: active ? visionTurnMemory.degradedRefinementCount(scope, sourceKey) : 0,
+    }
+  }
+
+  // DSH rc.8+ exposes a monotonic tool guard. Keep ordinary Host tools fully
+  // available, but do not let the same Agent rebuild an OCR/pixel-analysis
+  // pipeline from the current image bytes or Vision Router artifacts after every
+  // visual backend already failed and local OCR evidence exists for this turn.
+  if (typeof ctx.tools?.guard === 'function') {
+    ctx.tools.guard((exec) => {
+      const session = exec?.agent?.session
+      if (!session) return undefined
+      const scope = visionScopeOf(session)
+      const evidenceTokens = visionTurnMemory.degradedEvidenceTokens(scope)
+      if (!shouldBlockDegradedHostTool(exec.name, exec.arguments, evidenceTokens)) return undefined
+      return 'vision degraded-local evidence guard: do not reconstruct or re-parse this degraded image with Host tools after the visual backends failed; answer from the existing OCR evidence and state any remaining uncertainty'
+    })
+  }
 
   /** Stable, never-logged fingerprint of the credential a backend will use. */
   const credentialFingerprintOf = (value) => {
@@ -797,12 +857,10 @@ export function apply(ctx, config = {}, runtime = {}) {
   // image turns work. If the stock row is still active, taking over the route
   // throws DUPLICATE_ADAPTER and we fall back to the visible wrapper below.
   const stealthEnabled = current().stealth !== false
-  // Keep-alive fallback: stealth off leaves the stock `deepseek-official`
-  // route untouched — but when that route is dead (e.g. the official
-  // llm-deepseek row is disabled in the profile patch layer), serving it
-  // ourselves is the only way to keep the DeepSeek models in the picker.
-  // The settings card surfaces this condition as a hint, and re-enabling
-  // the stock row restores the fully official route.
+  // Legacy keep-alive fallback: older Hosts let DVR rebuild a missing stock
+  // `deepseek-official` route for compatibility. Newer Host generations own
+  // the provider's attachment/file lifecycle, so a missing official row is a
+  // Host configuration problem: DVR reports it and never reconstructs it.
   //
   // The takeover decision runs AFTER a short settle window, never inside
   // apply(): entry activation is service-driven, so this row can apply
@@ -888,11 +946,21 @@ export function apply(ctx, config = {}, runtime = {}) {
     if (adapterAvailable(ctx.llm, 'deepseek-official')) {
       if (stealthEnabled) {
         ctx.logger?.warn(
-          'vision-router: stealth is enabled but the stock deepseek-official route is alive; disable the llm-deepseek row to take it over',
+          hostOwnsOfficialDeepSeek
+            ? 'vision-router: stealth takeover is unavailable because this DSH Host owns deepseek-official; using the auto-vision wrapper instead'
+            : 'vision-router: legacy stealth takeover is enabled but the stock deepseek-official route is alive; disable llm-deepseek only on this legacy Host contract to take it over',
         )
       }
       return
     }
+    if (hostOwnsOfficialDeepSeek) {
+      takeoverAttempted = true
+      takeoverReason = 'host-owned-official-unavailable'
+      ctx.logger?.warn(
+        'vision-router: deepseek-official is unavailable on a Host-owned provider contract; re-enable the llm-deepseek row because Vision Router will not recreate it',
+      )
+      return
+    }
     attemptTakeover(stealthEnabled ? 'stealth' : 'official-unavailable')
   }
   let takeoverSettled = false
@@ -1020,6 +1088,10 @@ export function apply(ctx, config = {}, runtime = {}) {
           const content = []
           for (const block of message.content) {
             if (block && block.type === 'image' && block.attachment) {
+              if (isOffloadedImageBlock(block)) {
+                content.push({ type: 'text', text: offloadedImagePlaceholder(block) })
+                continue
+              }
               if (attachments === undefined) continue
               try {
                 const stored = await attachments.readImage(block.attachment)
@@ -1047,12 +1119,16 @@ export function apply(ctx, config = {}, runtime = {}) {
                 if (nested && nested.type === 'text' && typeof nested.text === 'string') {
                   parts.push(nested.text)
                 } else if (nested && nested.type === 'image') {
-                  const attachment = nested.attachment || {}
-                  const id = attachment.attachmentId || attachment.id || 'unknown'
-                  parts.push(
-                    `[attached image: ${id}] this tool result contained an image; ` +
-                      'inspect it with vision_describe (or re-read it with read_image)',
-                  )
+                  if (isOffloadedImageBlock(nested)) {
+                    parts.push(offloadedImagePlaceholder(nested))
+                  } else {
+                    const attachment = nested.attachment || {}
+                    const id = attachment.attachmentId || attachment.id || 'unknown'
+                    parts.push(
+                      `[attached image: ${id}] this tool result contained an image; ` +
+                        'inspect it with vision_describe (or re-read it with read_image)',
+                    )
+                  }
                 }
               }
               if (parts.length > 0) {
@@ -1173,7 +1249,7 @@ export function apply(ctx, config = {}, runtime = {}) {
         const real = delegateAdapter()
         if (real !== undefined && typeof real.listModels === 'function') {
           try {
-            const listed = await real.listModels('deepseek-official')
+            const listed = await getOfficialDeepSeekCatalog(real)
             entries.push(
               ...(Array.isArray(listed) ? listed : [])
                 .filter((model) => model && typeof model.id === 'string' && model.id !== '')
@@ -1239,7 +1315,7 @@ export function apply(ctx, config = {}, runtime = {}) {
           if (typeof real.listModels !== 'function') {
             throw new Error('vision-router: the official DeepSeek catalog is not available')
           }
-          const listed = await real.listModels('deepseek-official')
+          const listed = await getOfficialDeepSeekCatalog(real)
           const admitted = Array.isArray(listed) && listed.some(
             (entry) => entry && entry.id === model,
           )
@@ -1984,7 +2060,9 @@ export function apply(ctx, config = {}, runtime = {}) {
           if (!message || message.role !== 'user' || !Array.isArray(message.content)) continue
           // Deep collection: images nested inside tool-result blocks also
           // identify this turn's subject and deserve memory recording.
-          for (const found of collectImageBlocks([message])) imageIds.push(found.id)
+          for (const found of collectImageBlocks([message])) {
+            if (!isOffloadedImageBlock(found.block)) imageIds.push(found.id)
+          }
           if (imageIds.length > 0) break
         }
         let finalText = ''
@@ -2257,16 +2335,100 @@ export function apply(ctx, config = {}, runtime = {}) {
     },
     'vision-router: reactive routing mounts',
   )
-  // #208: attachment refs, description memory and the event-log cursor are
-  // owned by the same bounded SessionVisionStateStore above.
+  // #208: attachment refs and description memory are owned by the same
+  // bounded SessionVisionStateStore above. Historical ref recovery stays
+  // target-only inside SessionVisionIndex rather than maintaining a log cursor.
 
   // Host-owned proxy overrides are scoped by lib/legacy-global-proxy-boundary.js.
   // Core no longer owns or installs a process-wide proxy fetch implementation.
 
-  const lookupAttachment = (session, id) => sessionVisionIndex.lookupAttachment(session, id)
+  const resolveAttachment = (session, id) => sessionVisionIndex.resolveAttachment(session, id)
+  const resolveAttachments = (session, ids) => sessionVisionIndex.resolveAttachments(session, ids)
 
-  // session -> { turn, startIndex, hasImage, routed, failures, lastError }
+  // Session-local routing handoff between pre-step and agent/request. Modern
+  // Hosts store one exact async raw-log tail seq; legacy Hosts retain only the
+  // released synchronous array index fallback.
   const turnState = new WeakMap()
+  const midTurnReadWarnings = new WeakMap()
+
+  const warnMidTurnReadFailure = (session, error) => {
+    const message = String(error?.message ?? error ?? '').slice(0, 400)
+    if (midTurnReadWarnings.get(session) === message) return
+    midTurnReadWarnings.set(session, message)
+    ctx.logger?.warn?.('vision-router: mid-turn Session event read failed; routing conservatively to vision: %s', message)
+  }
+
+  const legacyTurnCapture = (session) => ({
+    legacyStartIndex: (legacySessionEvents(session) ?? []).length,
+  })
+
+  const captureTurnTail = async (session) => {
+    const anchorSeq = sessionTurnResolver?.eventAnchorOf?.(session)
+    if (!Number.isSafeInteger(anchorSeq) || anchorSeq < 0) return legacyTurnCapture(session)
+    if (typeof sessionEventTailReader !== 'function') return legacyTurnCapture(session)
+    try {
+      const tail = await sessionEventTailReader(session, anchorSeq, { collect: false })
+      if (tail?.supported === false) return legacyTurnCapture(session)
+      if (tail?.supported !== true || !Number.isSafeInteger(tail.capturedThroughSeq)) {
+        warnMidTurnReadFailure(session, new Error('Session tail reader returned an invalid capability result'))
+        return { scanUnknown: true }
+      }
+      midTurnReadWarnings.delete(session)
+      return tail.truncated === true
+        ? { capturedThroughSeq: tail.capturedThroughSeq, scanUnknown: true }
+        : { capturedThroughSeq: tail.capturedThroughSeq }
+    } catch (error) {
+      warnMidTurnReadFailure(session, error)
+      return { scanUnknown: true }
+    }
+  }
+
+  const refreshTurnImageState = async (session, state) => {
+    if (state.hasImage) return
+    if (state.scanUnknown === true) {
+      state.hasImage = true
+      return
+    }
+    if (Number.isSafeInteger(state.capturedThroughSeq)) {
+      try {
+        const tail = await sessionEventTailReader(session, state.capturedThroughSeq)
+        if (tail?.supported !== true || !Number.isSafeInteger(tail.capturedThroughSeq)) {
+          state.hasImage = true
+          warnMidTurnReadFailure(session, new Error('Session tail reader became unavailable after capture'))
+          return
+        }
+        midTurnReadWarnings.delete(session)
+        state.capturedThroughSeq = tail.capturedThroughSeq
+        if (tail.truncated === true || tail.events.some((event) => eventHasImage(event))) state.hasImage = true
+        return
+      } catch (error) {
+        state.hasImage = true
+        warnMidTurnReadFailure(session, error)
+        return
+      }
+    }
+
+    const events = legacySessionEvents(session) ?? []
+    const startIndex = Number.isSafeInteger(state.legacyStartIndex) ? state.legacyStartIndex : 0
+    for (let i = startIndex; i < events.length; i++) {
+      if (eventHasImage(events[i])) {
+        state.hasImage = true
+        break
+      }
+    }
+    state.legacyStartIndex = events.length
+  }
+
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    const downstream = await next()
+    if (downstream?.kind !== 'accept') return downstream
+    const context = visionDescribeSuccessContext(exec, result)
+    if (!context) return downstream
+    return {
+      ...downstream,
+      additionalContexts: [context, ...(downstream.additionalContexts ?? [])],
+    }
+  })
 
   ctx.on('agent/pre-step', async (payload, next) => {
     let decision = await next()
@@ -2291,7 +2453,7 @@ export function apply(ctx, config = {}, runtime = {}) {
     // settings 无该 key）一眼可见 "instant=off"。
     if (ctx.logger) {
       const hasImage = rawMessages.some(
-        (message) => message && Array.isArray(message.content) && blocksHaveImage(message.content),
+        (message) => message && Array.isArray(message.content) && blocksHaveRetainedImage(message.content),
       )
       if (hasImage) {
         ctx.logger.info(
@@ -2308,18 +2470,18 @@ export function apply(ctx, config = {}, runtime = {}) {
     // repair; Core retains only the current inbox sanitizer.
     const sanitizedToolResults = sanitizeToolResultImages(rawMessages)
     const messages = sanitizedToolResults.messages
-    const hasImage = messages.some((message) => blocksHaveImage(message && message.content))
+    const hasImage = messages.some((message) => blocksHaveRetainedImage(message && message.content))
 
     // Register the turn state BEFORE the image-turn branches below: those
     // branches return early (auto-mount reminder, history rewrite), and the
     // agent/request hook must still see the state, otherwise an image turn is
     // served by the text provider and rejected (issue #74, second root cause).
     if (routingEnabled()) {
-      const events = getSessionEvents(session) ?? []
+      const capture = hasImage ? {} : await captureTurnTail(session)
       turnState.set(session, {
         turn: payload.turn,
-        startIndex: events.length,
         hasImage,
+        ...capture,
       })
     }
     let bootstrapState = structuredBootstrapTurnState.get(session)
@@ -2536,15 +2698,7 @@ export function apply(ctx, config = {}, runtime = {}) {
     if (!session) return config0
     const state = turnState.get(session)
     if (!state || state.turn !== payload.turn) return config0
-    if (!state.hasImage) {
-    const events = getSessionEvents(session) ?? []
-    for (let i = state.startIndex; i < events.length; i++) {
-      if (eventHasImage(events[i])) {
-        state.hasImage = true
-        break
-      }
-    }
-    }
+    if (!state.hasImage) await refreshTurnImageState(session, state)
     if (!state.hasImage) {
       // Reverse routing: the session's entry model is a vision provider
       // (needed to pass the prompt admission); send text-only turns back
@@ -2654,6 +2808,10 @@ export function apply(ctx, config = {}, runtime = {}) {
           ...attachmentIds.map((id) => String(id)).filter((id) => isAttachmentIdInput(id)),
           ...paths.map((item) => String(item)).filter((item) => isAttachmentIdInput(item)),
         ])]
+        const attachmentSession = exec && exec.agent && exec.agent.session
+        const resolvedAttachmentRefs = materializableAttachmentIds.length > 0
+          ? await resolveAttachments(attachmentSession, materializableAttachmentIds)
+          : new Map()
 
         for (const path of paths) {
           let bytes
@@ -2662,7 +2820,7 @@ export function apply(ctx, config = {}, runtime = {}) {
             // readImageBytes accepts both filesystem paths and attachment ids
             // ("sha256:..."), so a model that passes an uploaded image's id as
             // a path gets the right pixels instead of a not-found error.
-            ;({ bytes, mediaType } = await readImageBytes(exec, path))
+            ;({ bytes, mediaType } = await readImageBytes(exec, path, resolvedAttachmentRefs))
           } catch (error) {
             throw new Error(
               `vision_describe: failed to read ${path} (${error && error.message ? error.message : String(error)})`,
@@ -2694,8 +2852,10 @@ export function apply(ctx, config = {}, runtime = {}) {
         }
 
         for (const id of attachmentIds) {
-          const session = exec && exec.agent && exec.agent.session
-          const ref = lookupAttachment(session, String(id))
+          const attachmentId = String(id)
+          const ref = isAttachmentIdInput(attachmentId)
+            ? resolvedAttachmentRefs.get(attachmentId)
+            : await resolveAttachment(attachmentSession, attachmentId)
           if (ref === undefined) {
             throw new Error(
               `vision_describe: unknown attachment id "${id}" (it must come from an image uploaded in this conversation)`,
@@ -3078,7 +3238,7 @@ ctx.logger?.info(
             tool: 'vision_materialize',
             attachmentIds: materializableAttachmentIds,
             advice:
-              'If another local/OCR tool requires a filesystem path, call vision_materialize for the uploaded attachment id. Do not guess a filename or the attachment store path.',
+              'For text transcription, call vision_ocr with {"image":"<attachment id>","engine":"tesseract"}; vision_ocr accepts uploaded attachment ids directly. Use vision_materialize only when a separate non-Vision-Router local parser genuinely requires a filesystem path. Do not guess a filename or the attachment store path.',
           }
         }
         return JSON.stringify(baseFailure)
@@ -3189,7 +3349,31 @@ ctx.logger?.info(
         ? config.artifactsDir
         : '.dsh-vision-router/artifacts'
 
-    const readImageBytes = async (exec, imagePath) => {
+    const resolveOcrImageInput = (args = {}) => {
+      const hasImageField = Object.prototype.hasOwnProperty.call(args, 'image')
+      const image = typeof args.image === 'string' ? args.image : undefined
+      const hasAttachmentIdsField = Object.prototype.hasOwnProperty.call(args, 'attachmentIds')
+      const attachmentIds = Array.isArray(args.attachmentIds) ? args.attachmentIds : []
+
+      if (hasImageField && (image === undefined || image.trim() === '')) {
+        throw new Error('vision_ocr: image must be a non-empty path or attachment id')
+      }
+      if (hasAttachmentIdsField && !Array.isArray(args.attachmentIds)) {
+        throw new Error('vision_ocr: attachmentIds must be an array containing exactly one uploaded attachment id')
+      }
+      if (hasImageField && hasAttachmentIdsField) {
+        throw new Error('vision_ocr: provide exactly one image using image or attachmentIds, not both')
+      }
+      if (hasImageField) return image
+      if (attachmentIds.length !== 1 || !isAttachmentIdInput(attachmentIds[0])) {
+        throw new Error(
+          'vision_ocr: provide one image via image or exactly one uploaded attachment id via attachmentIds',
+        )
+      }
+      return String(attachmentIds[0]).trim()
+    }
+
+    const readImageBytes = async (exec, imagePath, resolvedAttachmentRefs) => {
       const input = String(imagePath ?? '')
       let bytes
       let storedMediaType
@@ -3202,7 +3386,10 @@ ctx.logger?.info(
           throw new Error('vision-router: the attachment service is not available in this deployment')
         }
         const session = exec && exec.agent && exec.agent.session
-        const ref = lookupAttachment(session, input.trim())
+        const canonicalInput = input.trim()
+        const ref = resolvedAttachmentRefs instanceof Map
+          ? resolvedAttachmentRefs.get(canonicalInput)
+          : await resolveAttachment(session, canonicalInput)
         if (ref === undefined) {
           throw new Error(
             `vision-router: unknown attachment id "${input}" (it must come from an image uploaded in this conversation)`,
@@ -3250,6 +3437,8 @@ ctx.logger?.info(
 
     const saveArtifact = async (exec, relPath, data) =>
       writeArtifactFile(workspaceOf(exec), artifactsRel, relPath, data)
+    const savePersistentArtifact = async (exec, relPath, data) =>
+      writePersistentArtifactFile(workspaceOf(exec), artifactsRel, relPath, data)
 
     const artifactStem = (imagePath, suffix) => artifactStemOf(imagePath, suffix)
 
@@ -3263,7 +3452,8 @@ ctx.logger?.info(
     deepToolDefs.push({
       name: 'vision_materialize',
       description:
-        'Copy an uploaded image attachment (sha256:...) or readable local image into the session workspace and return a real filesystem path. ' +
+        'Copy an uploaded image attachment (sha256:...) or readable local image into a stable content-addressed file in the session workspace. ' +
+        'Returns both an absolute path and a shorter workspaceRelativePath; prefer workspaceRelativePath in later tool or shell calls to avoid copying long internal paths. ' +
         'This tool performs NO vision model/network call. Use it after vision_describe/vision_bootstrap returns ok:false when a local OCR/parser accepts only file_path. ' +
         'Never guess the attachment store path or search for a same-named file.',
       parameters: {
@@ -3277,6 +3467,14 @@ ctx.logger?.info(
       output: stringOutput,
       async execute(args, exec) {
         const source = String(args.image ?? '')
+        const session = exec?.agent?.session
+        const degraded = degradedLocalState(session, source)
+        if (degraded.active) {
+          return degradedLocalFailure(
+            'VISION_LOCAL_EVIDENCE_AVAILABLE',
+            'local OCR evidence already exists for this image and every configured vision backend has failed this turn; do not materialize the image to rebuild another parser/OCR pipeline',
+          )
+        }
         const { bytes, mediaType } = await readImageBytes(exec, source)
         const extension = mediaType === 'image/jpeg'
           ? 'jpg'
@@ -3285,9 +3483,26 @@ ctx.logger?.info(
             : mediaType === 'image/gif'
               ? 'gif'
               : 'png'
-        const target = await saveArtifact(exec, `${artifactStem(source, 'materialized')}.${extension}`, bytes)
+        const fingerprint = createHash('sha256').update(bytes).digest('hex').slice(0, 20)
+        const relativeArtifactPath = path.join('materialized', `${fingerprint}.${extension}`)
+        const artifactName = path.basename(relativeArtifactPath)
+        const target = await savePersistentArtifact(exec, relativeArtifactPath, bytes)
+        const workspaceRelativePath = path.join(
+          normalizeArtifactsDir(artifactsRel),
+          ARTIFACT_RUNS_DIR,
+          ARTIFACT_HANDOFF_RUN_ID,
+          relativeArtifactPath,
+        ).split(path.sep).join('/')
+        if (session) {
+          visionTurnMemory.recordDerivedArtifact(
+            visionScopeOf(session),
+            visionEvidenceSourceKey(source),
+            artifactName,
+          )
+        }
         return JSON.stringify({
           path: target,
+          workspaceRelativePath,
           mediaType,
           bytes: bytes.length,
           ...(isAttachmentIdInput(source) ? { source } : {}),
@@ -3678,6 +3893,14 @@ ctx.logger?.info(
       },
       output: stringOutput,
       async execute(args, exec) {
+        const session = exec?.agent?.session
+        const degraded = degradedLocalState(session, args.image)
+        if (degraded.active && degraded.used >= DEGRADED_LOCAL_REFINEMENT_LIMIT) {
+          return degradedLocalFailure(
+            'VISION_DEGRADED_LOCAL_LIMIT',
+            `the degraded local evidence budget for this image is exhausted after ${DEGRADED_LOCAL_REFINEMENT_LIMIT} refinement call(s); answer from existing evidence and state any remaining uncertainty`,
+          )
+        }
         const { bytes } = await readImageBytes(exec, args.image)
         const { width, height } = await imageDims(bytes)
         const box = parseBox(args.region)
@@ -3709,11 +3932,17 @@ ctx.logger?.info(
         } finally {
           releaseCrop()
         }
-        const target = await saveArtifact(
-          exec,
-          `${artifactStem(args.image, `crop-${box.x1}-${box.y1}-${box.x2}-${box.y2}`)}.png`,
-          cropped,
-        )
+        const artifactName = `${artifactStem(args.image, `crop-${box.x1}-${box.y1}-${box.x2}-${box.y2}`)}.png`
+        const target = await saveArtifact(exec, artifactName, cropped)
+        if (session) {
+          const scope = visionScopeOf(session)
+          visionTurnMemory.recordDerivedArtifact(
+            scope,
+            visionEvidenceSourceKey(args.image),
+            artifactName,
+          )
+          if (degraded.active) visionTurnMemory.recordDegradedRefinement(scope, degraded.sourceKey)
+        }
         const meta = await sharp(cropped).metadata()
         return JSON.stringify({
           path: target,
@@ -3978,34 +4207,83 @@ ctx.logger?.info(
         'ACCURACY: OCR transcribes characters verbatim and is systematically unreliable for confusable ' +
         'glyphs (1/l, 0/O), spacing and line breaks; prefer vision_describe / vision_detect for semantic ' +
         'understanding and use OCR only when exact verbatim text is required (executable code, exact ' +
-        'quotation, forms/contracts, table digits, CAPTCHAs). Treat OCR output as evidence to verify, ' +
-        'never as ground truth.',
+        'quotation, forms/contracts, table digits, CAPTCHAs). Local OCR uses a bounded layout review when ' +
+        'the first pass looks weak. If the result has uncertain:true, cross-check the ambiguous text when ' +
+        'another visual backend is available; otherwise state the remaining uncertainty. If uncertain:false ' +
+        'and the text directly answers the user, do not call more tools merely to re-prove the same text. ' +
+        'INPUT: `image` is the canonical single-image argument. For compatibility with other Vision Router ' +
+        'tools, one uploaded image may instead be passed as `attachmentIds: [id]`; do not pass both forms ' +
+        'or more than one attachment id.',
       parameters: {
         type: 'object',
         properties: {
-          image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+          image: { type: 'string', description: 'Canonical single-image input: local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+          attachmentIds: {
+            type: 'array',
+            items: { type: 'string' },
+            minItems: 1,
+            maxItems: 1,
+            description: 'Compatibility alias for one uploaded image attachment id. Use exactly one sha256:... id. Do not combine with image.',
+          },
           engine: {
             type: 'string',
             description: '"auto" (default): always try local Tesseract first, then fall back to the vision model if local OCR fails or returns no text. Structured 1+x does not change this order; use explicit "tesseract"/"vision" to force an engine.',
           },
         },
-        required: ['image'],
         additionalProperties: false,
       },
       output: stringOutput,
       async execute(args, exec) {
-        const { bytes, mediaType } = await readImageBytes(exec, args.image)
+        const imageInput = resolveOcrImageInput(args)
+        const session = exec?.agent?.session
         const engine = resolveVisionOcrEngine(args.engine)
+        const degraded = degradedLocalState(session, imageInput)
+        if (
+          engine !== 'vision' &&
+          degraded.active &&
+          degraded.used >= DEGRADED_LOCAL_REFINEMENT_LIMIT
+        ) {
+          return degradedLocalFailure(
+            'VISION_DEGRADED_LOCAL_LIMIT',
+            `the degraded local evidence budget for this image is exhausted after ${DEGRADED_LOCAL_REFINEMENT_LIMIT} refinement call(s); answer from existing evidence and state any remaining uncertainty`,
+          )
+        }
+        const { bytes, mediaType } = await readImageBytes(exec, imageInput)
         // ONE OCR budget shared by tesseract AND the vision fallback: tesseract
         // gets a capped slice (never more than 12s), the vision model only the
         // remainder. The two timeouts can never stack into a multi-minute wait.
         const deadline = createDeadline(ocrBudgetMs())
         const tesseractSlice = Math.min(12000, deadline.remaining())
         if (engine !== 'vision') {
+          let localAttempted = false
           try {
-            const text = await ocrWithTesseract(bytes, tesseractSlice)
-            if (text.trim() !== '') return JSON.stringify({ engine: 'tesseract', text: text.trim() })
-            if (engine === 'tesseract') return JSON.stringify({ engine: 'tesseract', text: '' })
+            localAttempted = true
+            const local = await ocrWithTesseractAdaptive(bytes, tesseractSlice)
+            if (local.text.trim() !== '') {
+              if (session) {
+                visionTurnMemory.recordLocalOcr(
+                  visionScopeOf(session),
+                  visionEvidenceSourceKey(imageInput),
+                  { uncertain: local.uncertain === true },
+                )
+              }
+              return JSON.stringify({
+                engine: 'tesseract',
+                text: local.text.trim(),
+                uncertain: local.uncertain === true,
+                ...(local.uncertain === true
+                  ? {
+                    review: {
+                      psm: local.psm,
+                      attemptedPsms: local.attemptedPsms,
+                      quality: Number(local.quality.toFixed(2)),
+                      riskyTokens: local.riskyTokens,
+                    },
+                  }
+                  : {}),
+              })
+            }
+            if (engine === 'tesseract') return JSON.stringify({ engine: 'tesseract', text: '', uncertain: true })
           } catch (error) {
             if (engine === 'tesseract') {
               throw new Error(
@@ -4013,6 +4291,13 @@ ctx.logger?.info(
               )
             }
             ctx.logger?.warn('vision-router: tesseract OCR unavailable, falling back to vision model')
+          } finally {
+            if (degraded.active && localAttempted && session) {
+              visionTurnMemory.recordDegradedRefinement(
+                visionScopeOf(session),
+                degraded.sourceKey,
+              )
+            }
           }
         }
         if (deadline.expired()) {
@@ -4850,10 +5135,16 @@ ctx.logger?.info(
             // Runtime takeover state: lets the settings card explain the
             // keep-alive fallback when stealth is off but the stock route is
             // disabled at the composition layer.
+            const officialRouteAvailable = adapterAvailable(ctx.llm, 'deepseek-official')
             result.stealth = {
               configured: stealthEnabled,
               active: stealthActive,
-              reason: stealthActive ? takeoverReason : undefined,
+              reason: stealthActive
+                ? takeoverReason
+                : hostOwnsOfficialDeepSeek && !officialRouteAvailable
+                  ? 'host-owned-official-unavailable'
+                  : undefined,
+              hostOwned: hostOwnsOfficialDeepSeek,
             }
             res.writeHead(result.ok ? 200 : 502, { 'content-type': 'application/json' })
             res.end(JSON.stringify(result))