dsh-vision-router 3.0.2 → 3.0.4

package/lib/vision-background-benchmark.js

@@ -10,6 +10,7 @@ import { resolveVisionRoutingAuthority } from './vision-routing-authority.js'
 import { redactDiagnosticText } from './diagnostic-redaction.js'
 import { installVisionExactCheckClient } from './vision-exact-check-client.js'
 import { createImageInputVerdictStore } from './vision-image-input-verdict.js'
+import { hostImageDeliveryFromInfo, localOnlyVisionCallAllowed, resolvedHostInfo } from './vision-backend-runtime-policy.js'
 import { createBackgroundBenchmarkStopStore } from './vision-background-stop-store.js'
 import { backgroundFailurePolicy } from './vision-background-failure-policy.js'
 import { isLocalUiRequest } from './web-capability-boundary.js'
@@ -288,9 +289,18 @@ function candidateBlockedByFailure(backoff, candidate, at) {
   return false
 }
 
-async function imageVerdictFor(imageVerdictStore, candidate) {
+async function currentHostImageDelivery(ctx, provider, model) {
+  if (provider === 'vision-http') return 'native-image'
+  return hostImageDeliveryFromInfo(await resolvedHostInfo(ctx?.llm, { provider, model }))
+}
+
+async function imageVerdictFor(imageVerdictStore, candidate, ctx) {
   if (!candidate?.endpointFingerprint || typeof imageVerdictStore?.get !== 'function') return undefined
-  try { return await imageVerdictStore.get(candidate.endpointFingerprint) } catch { return undefined }
+  try {
+    const verdict = await imageVerdictStore.get(candidate.endpointFingerprint)
+    if (!verdict || verdict.hostMode !== 'native-image') return undefined
+    return await currentHostImageDelivery(ctx, candidate.provider, candidate.model) === 'native-image' ? verdict : undefined
+  } catch { return undefined }
 }
 
 async function chooseNextWork({ ctx, config, core, store, now, backoff, excluded, imageVerdictStore, backgroundStopStore }) {
@@ -302,7 +312,7 @@ async function chooseNextWork({ ctx, config, core, store, now, backoff, excluded
   await restorePersistentStops(backoff, collected, backgroundStopStore, ctx, now)
   const candidates = []
   for (const candidate of collected) {
-    const verdict = await imageVerdictFor(imageVerdictStore, candidate)
+    const verdict = await imageVerdictFor(imageVerdictStore, candidate, ctx)
     if (verdict?.state === 'unsupported') {
       excluded.set(candidate.key, { key: candidate.key, reason: 'measured-text-only' })
       continue
@@ -470,6 +480,13 @@ export async function runExactVisionCheck({ ctx, config, core, store, provider,
   const wantedModel = typeof model === 'string' ? model.trim() : ''
   if (!wantedProvider || !wantedModel) throw Object.assign(new Error('provider and model are required'), { code: 'VISION_CHECK_BACKEND_REQUIRED' })
   const current = activeSettings(ctx, config)
+  if (!localOnlyVisionCallAllowed(core, current, wantedProvider, wantedModel)) {
+    const error = new Error('local-only vision policy prevents testing a nonlocal backend')
+    error.code = 'VISION_LOCAL_ONLY_POLICY'
+    error.benchmarkClass = 'host-configuration'
+    throw error
+  }
+  const declaredBefore = await currentHostImageDelivery(ctx, wantedProvider, wantedModel)
   const candidates = await collectVisionRoutingCandidates(ctx, current, core, store)
   const candidate = candidates.find((entry) => entry?.provider === wantedProvider && entry?.model === wantedModel)
     ?? exactAdapterCandidate(ctx, core, wantedProvider, wantedModel)
@@ -513,6 +530,12 @@ export async function runExactVisionCheck({ ctx, config, core, store, provider,
     remaining(),
     'exact image check timed out',
   )
+  if (declaredBefore !== await currentHostImageDelivery(ctx, wantedProvider, wantedModel)) {
+    const error = new Error('Host image-input declaration changed during the test; retest the model')
+    error.code = 'VISION_CHECK_STALE_CONFIG'
+    error.benchmarkClass = 'host-configuration'
+    throw error
+  }
   return {
     ok: true,
     key: candidate.key,
@@ -602,13 +625,15 @@ export function createBackgroundCapabilityProfiler({
     excluded.set(candidate.key, { key: candidate.key, reason: 'measured-text-only' })
     clearDeferredForCandidate(candidate)
     await clearPersistentStopsForCandidate(candidate)
-    if (candidate.endpointFingerprint && typeof imageVerdictStore?.markUnsupported === 'function') {
+    if (candidate.endpointFingerprint && typeof imageVerdictStore?.markUnsupported === 'function'
+      && await currentHostImageDelivery(ctx, candidate.provider, candidate.model) === 'native-image') {
       try {
         await imageVerdictStore.markUnsupported({
           fingerprint: candidate.endpointFingerprint,
           key: candidate.key,
           provider: candidate.provider,
           model: candidate.model,
+          hostMode: 'native-image',
           measuredAt: Number(now()),
         })
       } catch (error) {
@@ -1140,7 +1165,9 @@ export function installBackgroundCapabilityProfiling(ctx, config, core, store, o
             const timedOut = error?.name === 'TimeoutError' || error?.name === 'AbortError' || /timed out|timeout|deadline/i.test(String(error?.message ?? ''))
             const failureClass = error?.benchmarkClass ?? classifyCapabilityBenchmarkFailure(error)
             const unsupportedImage = !timedOut && failureClass === 'unsupported-image'
-            if (unsupportedImage) await profiler.recordImageUnsupported(body.provider, body.model)
+            if (unsupportedImage && await currentHostImageDelivery(ctx, body.provider, body.model) === 'native-image') {
+              await profiler.recordImageUnsupported(body.provider, body.model)
+            }
             const code = timedOut
               ? 'VISION_CHECK_TIMEOUT'
               : unsupportedImage
@@ -1151,6 +1178,7 @@ export function installBackgroundCapabilityProfiling(ctx, config, core, store, o
               'VISION_CHECK_INVALID_JSON',
               'VISION_CHECK_BACKEND_REQUIRED',
               'VISION_CHECK_BACKEND_STALE',
+              'VISION_CHECK_STALE_CONFIG',
             ]).has(code)
             sendJson(res, unsupportedImage ? 422 : clientError ? 400 : 502, {
               ok: false,

package/lib/vision-capability-benchmark-service.js

@@ -14,6 +14,8 @@ import { resolveVisionCredential } from './vision-capability-identity.js'
 import { redactDiagnosticText } from './diagnostic-redaction.js'
 import { wireSessionAffinityId } from './session-affinity.js'
 import { streamWithVisionSessionAffinity } from './session-affinity-runtime.js'
+import { hostImageDeliveryFromInfo, resolvedHostInfo } from './vision-backend-runtime-policy.js'
+import { isLocalImageCapabilityAdmissionFailure } from './vision-execution-policy.js'
 import { streamWithLegacyGlobalProxyScope } from './legacy-global-proxy-boundary.js'
 import {
   hardenCapabilityBenchmarkFixture,
@@ -205,13 +207,28 @@ function failureError(failure, fallback) {
 async function collectStreamText(streamLike) {
   const stream = await streamLike
   let text = ''
-  for await (const chunk of stream) {
-    if (chunk && typeof chunk.text === 'string') text += chunk.text
-    if (chunk?.type === 'finish') {
-      const kind = chunk.reason?.kind
-      if (kind === 'error' || kind === 'aborted') throw failureError(chunk.reason?.failure, kind)
+  let observedOutput = false
+  try {
+    for await (const chunk of stream) {
+      // Any non-terminal output proves that the adapter began responding.
+      // Retrying through a second transport could duplicate a billed call.
+      if (chunk && chunk.type !== 'finish' && chunk.type !== 'error' && chunk.type !== 'aborted') {
+        observedOutput = true
+      }
+      if (chunk && typeof chunk.text === 'string') text += chunk.text
+      if (chunk?.type === 'finish') {
+        const kind = chunk.reason?.kind
+        if (kind === 'error' || kind === 'aborted') throw failureError(chunk.reason?.failure, kind)
+      }
+      if (chunk?.type === 'error' || chunk?.type === 'aborted') throw failureError(chunk.failure, chunk.type)
+    }
+  } catch (error) {
+    if (observedOutput) {
+      const failure = failureError(error)
+      failure.visionAdapterProducedOutput = true
+      throw failure
     }
-    if (chunk?.type === 'error' || chunk?.type === 'aborted') throw failureError(chunk.failure, chunk.type)
+    throw error
   }
   return text
 }
@@ -223,20 +240,22 @@ function tagInvocationError(value) {
   return error
 }
 
-function mayUseExactAdapterBridge(core, error, directProvider) {
-  if (directProvider === undefined) return false
-  try {
-    const classification = core?.classifyVisionFailure?.(error)
-    const kinds = core?.VISION_FAILURE_KINDS
-    const allowed = new Set([
-      kinds?.INVALID_REQUEST,
-      kinds?.NETWORK,
-      kinds?.OTHER,
-    ].filter(Boolean))
-    return classification && allowed.has(classification.kind)
-  } catch {
-    return false
-  }
+function mayUseExactAdapterBridge(_core, error, directProvider) {
+  if (directProvider === undefined || error?.visionAdapterProducedOutput === true) return false
+  // Share the runtime's exact pre-wire pi-ai admission predicate. Provider
+  // HTTP 400s, ambiguous image errors and network failures must never replay.
+  return isLocalImageCapabilityAdmissionFailure(error)
+}
+
+export function exactHostImageDeliveryPlan(info, candidate, core) {
+  const delivery = hostImageDeliveryFromInfo(info)
+  if (delivery !== 'text-projected') return { delivery, path: 'adapter' }
+  const verified = candidate?.evidenceScope === 'endpoint'
+    && candidate?.endpointConfig?.api === 'openai-completions'
+    && typeof candidate?.endpoint === 'string'
+    && typeof core?.isOpenAIHttpBridgeTransport === 'function'
+    && core.isOpenAIHttpBridgeTransport({ api: 'openai-completions', baseURL: candidate.endpoint })
+  return { delivery, path: verified ? 'http-direct' : 'refuse' }
 }
 
 function benchmarkMaxTokensForProvider(provider) {
@@ -295,6 +314,22 @@ export function createExactCapabilityInvoker(ctx, core, candidate, config, optio
       )
       const callSignal = mergedSignal(signal, AbortSignal.timeout(fixtureTimeoutMs))
       const exactHttpProvider = directProviderFor(candidate, config, core)
+      const hostInfo = candidate.provider === 'vision-http' ? undefined :
+        await resolvedHostInfo(ctx?.llm, { provider: candidate.provider, model: candidate.model, signal: callSignal })
+      const imagePlan = candidate.provider === 'vision-http'
+        ? { path: 'http-direct' }
+        : exactHostImageDeliveryPlan(hostInfo, candidate, core)
+      if (imagePlan.path === 'refuse') {
+        const error = new Error('Host declares this model text-only and removes image pixels before adapter dispatch; enable Image in DSH model input types, then retest')
+        error.code = 'VISION_IMAGE_DELIVERY_UNAVAILABLE'
+        error.benchmarkClass = 'host-configuration'
+        throw error
+      }
+      if (imagePlan.path === 'http-direct' && exactHttpProvider === undefined) {
+        const error = new Error('verified HTTP image bridge unavailable for this model')
+        error.code = 'CAPABILITY_BENCHMARK_PROTOCOL'
+        throw error
+      }
       const callExactHttp = async () => {
         if (exactHttpProvider === undefined) {
           const error = new Error('exact HTTP bridge is unavailable for this benchmark backend')
@@ -323,7 +358,7 @@ export function createExactCapabilityInvoker(ctx, core, candidate, config, optio
       let output
       let transport
       let latencyMs
-      if (candidate.provider === 'vision-http') {
+      if (candidate.provider === 'vision-http' || imagePlan.path === 'http-direct') {
         const direct = await callExactHttp()
         output = direct.output
         latencyMs = direct.latencyMs
@@ -404,8 +439,11 @@ async function declaredImageState(ctx, core, config, candidate) {
       candidate.model,
       config?.extraVisionModels,
     )
-    if (decision?.image === true) return 'declared'
-    if (decision?.image === false) return 'text-only'
+    const hostMode = hostImageDeliveryFromInfo(info)
+    if (hostMode === 'native-image') return 'declared'
+    if (hostMode === 'text-projected') return 'text-only'
+    // Name-based guesses and user labels do not rewrite Host input metadata.
+    if (decision?.image === true) return 'unknown'
   } catch {
     // Metadata is advisory. Exact configured routes remain force-testable.
   }

package/lib/vision-exact-check-client.js

@@ -80,6 +80,9 @@ export const VISION_EXACT_CHECK_CLIENT = String.raw`(function(){
       VISION_CHECK_BACKEND_STALE:[text('当前模型暂时无法直接调用，请确认供应商/模型仍可用后重试','This model is not currently callable; verify the provider/model and retry')],
       VISION_CHECK_TIMEOUT:[text('测试超时，已自动结束','Test timed out and was stopped')],
       VISION_CHECK_UNSUPPORTED_IMAGE:[text('实测仅文本 · 图片请求被模型拒绝','Measured text-only · the model rejected image input')],
+      VISION_IMAGE_DELIVERY_UNAVAILABLE:[text('Host未声明图片输入，请在DSH模型设置中启用Image再测','Host declares text-only input; enable Image in DSH Models settings and retest')],
+      VISION_CHECK_STALE_CONFIG:[text('测试期间模型配置已变化，请重新测试','Model input settings changed during the test; retest required')],
+      VISION_LOCAL_ONLY_POLICY:[text('本地识图模式下不允许测试非本地后端','Local-only vision policy blocks testing nonlocal backends')],
       VISION_CHECK_INFRASTRUCTURE:[text('识图测试组件暂不可用','Vision check infrastructure is unavailable')],
       CAPABILITY_BENCHMARK_INFRASTRUCTURE:[text('识图测试组件暂不可用','Vision check infrastructure is unavailable')],
       CAPABILITY_BENCHMARK_VISUAL_PROOF_FAILED:[text('模型没有正确读出测试图','The model did not correctly inspect the test image')]
@@ -91,9 +94,16 @@ export const VISION_EXACT_CHECK_CLIENT = String.raw`(function(){
   }
   function reset(control){
     if(!control)return;
+    delete control.dataset.lastResult;
     setStatus(control,text('快速自检 · 1次请求 · 只验证当前模型能否识图 · 不写入Auto能力分数','Quick check · 1 request · verifies image input only · does not write Auto capability scores'));
     setButton(control,text('测试识图','Test vision'),false);
   }
+  function makeRemoteNotice(row){
+    var note=document.createElement('div');note.setAttribute(CONTROL_ATTR,'remote');
+    note.style.cssText='flex:1 0 100%;font-size:12px;opacity:.7;margin-top:4px';
+    note.textContent=text('识图自检仅可在DSH本机界面执行；远程页面不发送测试请求。','Vision testing is local-only. Open the DSH UI on the Host to run the image check.');
+    row.appendChild(note);return note;
+  }
   function makeControl(row){
     if(!row||!row.style)return undefined;
     row.style.flexWrap='wrap';
@@ -131,15 +141,15 @@ export const VISION_EXACT_CHECK_CLIENT = String.raw`(function(){
       if(!currentRun(control,token,key))return;
       if(!response.ok||!body||body.ok!==true){
         var raw=String(body&&(body.error||body.code)||('HTTP '+response.status));
-        setStatus(control,'✗ '+selection.provider+'/'+selection.model+' · '+failureMessage(body,response.status),raw);notifyChanged();return;
+        setStatus(control,'✗ '+selection.provider+'/'+selection.model+' · '+failureMessage(body,response.status),raw);control.dataset.lastResult=String(Date.now());notifyChanged();return;
       }
       var via=transport(body.transport),latency=seconds(body.latencyMs),output=short(body.output,72);
       var suffix=(via?' · '+via:'')+(latency?' · '+latency:'')+(output?' · '+output:'');
-      setStatus(control,'✓ '+selection.provider+'/'+selection.model+text(' · 图片识别正常',' · image verified')+suffix);notifyChanged();
+      setStatus(control,'✓ '+selection.provider+'/'+selection.model+text(' · 图片识别正常',' · image verified')+suffix+' · '+new Date().toLocaleTimeString());control.dataset.lastResult=String(Date.now());notifyChanged();
     }catch(error){
       if(!currentRun(control,token,key))return;
       var message=error&&error.name==='AbortError'?text('测试超时，已自动结束','Test timed out and was stopped'):text('测试失败','Vision check failed');
-      setStatus(control,'✗ '+selection.provider+'/'+selection.model+' · '+message,String(error&&error.message||error));
+      setStatus(control,'✗ '+selection.provider+'/'+selection.model+' · '+message,String(error&&error.message||error));control.dataset.lastResult=String(Date.now());
     }finally{
       if(timer!==undefined)clearTimeout(timer);
       if(ticker!==undefined)clearInterval(ticker);
@@ -148,12 +158,13 @@ export const VISION_EXACT_CHECK_CLIENT = String.raw`(function(){
     }
   }
   function scan(){
-    if(!localPage())return;
+    var local=localPage();
     var rows=[];try{rows=Array.prototype.slice.call(document.querySelectorAll(ROW_SELECTOR));}catch(_){rows=[];}
     rows.forEach(function(row){
       var selection=rowSelection(row),control=row.querySelector('['+CONTROL_ATTR+']');
       if(!complete(selection)){if(control){abortActive(control);if(control.remove)control.remove();}return;}
-      if(!control)control=makeControl(row);
+      if(!control)control=local?makeControl(row):makeRemoteNotice(row);
+      if(!local)return;
       var key=selectionKey(selection);
       if(control&&control.dataset.selection!==key){abortActive(control);control.dataset.selection=key;reset(control);}
     });
@@ -167,8 +178,15 @@ export const VISION_EXACT_CHECK_CLIENT = String.raw`(function(){
     }catch(_){}
     return false;
   }
-  function start(){
+  function invalidatePreviousResults(){
     if(!localPage())return;
+    var controls=document.querySelectorAll('['+CONTROL_ATTR+'][data-last-result]');
+    controls.forEach(function(control){abortActive(control);reset(control);
+      setStatus(control,text('配置可能已变化，请重新测试','Configuration may have changed; retest required'));
+    });
+  }
+  function start(){
+    window.addEventListener('focus',invalidatePreviousResults);
     document.addEventListener('change',function(event){var row=event&&event.target&&event.target.closest?event.target.closest(ROW_SELECTOR):undefined;if(row)schedule();},true);
     if(typeof MutationObserver==='function'&&document.documentElement){
       var observer=new MutationObserver(function(records){

package/lib/vision-image-input-verdict.js

@@ -5,7 +5,7 @@ import process from 'node:process'
 import { resolveDshHome } from './doctor.js'
 import { CAPABILITY_BENCHMARK_SUITE_REVISION } from './vision-capability-benchmark.js'
 
-const CACHE_VERSION = 1
+const CACHE_VERSION = 2
 const MAX_ENTRIES = 128
 
 function cleanText(value, max = 256) {
@@ -14,7 +14,7 @@ function cleanText(value, max = 256) {
 
 function cleanVerdict(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
-  if (value.state !== 'unsupported') return undefined
+  if (value.state !== 'unsupported' || value.hostMode !== 'native-image') return undefined
   if (Number(value.suiteRevision) !== CAPABILITY_BENCHMARK_SUITE_REVISION) return undefined
   const fingerprint = cleanText(value.fingerprint, 64)
   if (!/^ep2_[0-9a-f]{32}$/.test(fingerprint)) return undefined
@@ -29,6 +29,7 @@ function cleanVerdict(value) {
     provider,
     model,
     state: 'unsupported',
+    hostMode: 'native-image',
     reason: 'provider-rejected-image',
     measuredAt,
     suiteRevision: CAPABILITY_BENCHMARK_SUITE_REVISION,
@@ -103,7 +104,7 @@ export function createImageInputVerdictStore(options = {}) {
       await ready
       return records.get(String(fingerprint ?? ''))
     },
-    async markUnsupported({ fingerprint, key, provider, model, measuredAt = Date.now() } = {}) {
+    async markUnsupported({ fingerprint, key, provider, model, hostMode, measuredAt = Date.now() } = {}) {
       await ready
       const clean = cleanVerdict({
         fingerprint,
@@ -111,6 +112,7 @@ export function createImageInputVerdictStore(options = {}) {
         provider,
         model,
         state: 'unsupported',
+        hostMode,
         measuredAt,
         suiteRevision: CAPABILITY_BENCHMARK_SUITE_REVISION,
       })

package/lib/vision-toggle-root-hardening.js

@@ -345,7 +345,15 @@ const CLIENT_PRELUDE = String.raw`(function(){
 })();`
 
 function replaceAll(source, before, after) {
-  return source.includes(before) ? source.split(before).join(after) : source
+  let result = source.includes(before) ? source.split(before).join(after) : source
+  // Windows git checkouts can put CRLF inside injected client-source template
+  // literals. Match only the same owned seam with CRLF; do not normalize or
+  // rewrite the surrounding HTML or any unrelated plugin's source.
+  if (before.includes('\n')) {
+    const windowsBefore = before.replaceAll('\n', '\r\n')
+    if (result.includes(windowsBefore)) result = result.split(windowsBefore).join(after)
+  }
+  return result
 }
 
 export function hardenVisionClientSource(source) {
@@ -403,7 +411,7 @@ export function hardenVisionClientSource(source) {
   next = replaceAll(
     next,
     `          var message = latest && typeof latest.error === 'string' && latest.error !== ''\n            ? latest.error\n            : t('failedUnknown');`,
-    `          var recovered = recovery && typeof recovery.getSnapshot === 'function' ? recovery.getSnapshot() : recoveryError;\n          var message = latest && typeof latest.error === 'string' && latest.error !== ''\n            ? latest.error\n            : recovered && recovered.message ? recovered.message : t('failedUnknown');`,
+    `          var recoveryStore = typeof recovery === 'undefined' ? null : recovery;\n          if (!recoveryStore && typeof window !== 'undefined') {\n            var hardening = window.__dshVisionRouterRootHardening;\n            if (hardening && typeof hardening.recoveryFor === 'function') recoveryStore = hardening.recoveryFor(directory);\n          }\n          var recovered = recoveryStore && typeof recoveryStore.getSnapshot === 'function' ? recoveryStore.getSnapshot() : null;\n          var message = latest && typeof latest.error === 'string' && latest.error !== ''\n            ? latest.error\n            : recovered && recovered.message ? recovered.message : t('failedUnknown');`,
   )
 
   next = replaceAll(
@@ -431,10 +439,19 @@ export function hardenVisionClientSource(source) {
   )
 
   next = replaceAll(next, `function wrapStore(store, settings) {`, `function wrapStore(store, settings, recovery) {`)
+  // A synthetic recovery snapshot must retain referential identity until
+  // its Host source snapshot or recovery error actually changes. Otherwise
+  // React's useSyncExternalStore sees a new snapshot on every read and can
+  // enter a maximum-update-depth loop after a failed select + catalog refresh.
+  next = replaceAll(
+    next,
+    `    var lastProjected;\n    function getSnapshot() {`,
+    `    var lastProjected;\n    var lastRecoverySource;\n    var lastRecoveryError;\n    var lastRecoveryRaw;\n    function getSnapshot() {`,
+  )
   next = replaceAll(
     next,
     `      var raw = typeof store.getSnapshot === 'function' ? store.getSnapshot() : undefined;\n      var config = currentVisionConfig(settings);`,
-    `      var raw = typeof store.getSnapshot === 'function' ? store.getSnapshot() : undefined;\n      var recovered = recovery && typeof recovery.getSnapshot === 'function' ? recovery.getSnapshot() : null;\n      if (recovered && raw && (raw.status === 'selecting' || raw.status === 'loading')) {\n        raw = Object.assign({}, raw, { status: 'error', error: recovered.message || String(recovered) });\n      }\n      var config = currentVisionConfig(settings);`,
+    `      var raw = typeof store.getSnapshot === 'function' ? store.getSnapshot() : undefined;\n      var recovered = recovery && typeof recovery.getSnapshot === 'function' ? recovery.getSnapshot() : null;\n      if (recovered && raw && (raw.status === 'selecting' || raw.status === 'loading')) {\n        if (raw !== lastRecoverySource || recovered !== lastRecoveryError) {\n          lastRecoverySource = raw;\n          lastRecoveryError = recovered;\n          lastRecoveryRaw = Object.assign({}, raw, { status: 'error', error: recovered.message || String(recovered) });\n        }\n        raw = lastRecoveryRaw;\n      }\n      var config = currentVisionConfig(settings);`,
   )
   next = replaceAll(
     next,

package/lib/web-capability-boundary.js

@@ -126,17 +126,42 @@ function isLocalHostName(value) {
   return host === 'localhost' || host.endsWith('.localhost') || isLoopbackAddress(host)
 }
 
+// Forwarding metadata can only *deny* a local-machine capability. Never
+// interpret X-Forwarded-For or similar caller-controlled headers as proof
+// that a request really originated at the local browser.
+const PROXY_PROVENANCE_HEADERS = new Set([
+  'forwarded',
+  'x-forwarded-for',
+  'x-forwarded-host',
+  'x-forwarded-proto',
+  'x-real-ip',
+  'x-client-ip',
+  'true-client-ip',
+  'cf-connecting-ip',
+  'via',
+])
+
+function hasProxyProvenance(req) {
+  const headers = req?.headers
+  return !!headers && typeof headers === 'object' &&
+    Object.keys(headers).some((name) => PROXY_PROVENANCE_HEADERS.has(name.toLowerCase()))
+}
+
 /**
  * Browser-facing local capability check. A real network request needs BOTH a
- * loopback TCP peer and a loopback/localhost Host header. This prevents the
- * common reverse-proxy shape (proxy -> 127.0.0.1, external Host preserved)
- * from silently acquiring local-machine capabilities. Internal direct handler
- * calls have no transport and remain compatible for tests/host composition.
+ * loopback TCP peer and a loopback/localhost Host header, with no forwarding
+ * metadata. This protects supported proxy deployments preserving external Host
+ * and fails closed when a proxy rewrites Host but keeps standard hop markers.
+ * A proxy that erases every originating fact is indistinguishable from a
+ * genuine loopback browser request; these headers are not an attestation.
+ * Internal direct handler calls have no socket and remain supported.
  */
 export function isLocalUiRequest(req) {
   const transport = req?.socket ?? req?.connection
   if (!transport) return true
-  return isLoopbackAddress(transport.remoteAddress) && isLocalHostName(requestHostName(req))
+  return isLoopbackAddress(transport.remoteAddress) &&
+    isLocalHostName(requestHostName(req)) &&
+    !hasProxyProvenance(req)
 }
 
 export function isLocalMutationRoute(path, method) {
@@ -204,40 +229,148 @@ function redactRemoteBody(path, body) {
   return body
 }
 
-/** Intercept one JSON end() so local capability material is never issued remotely. */
+// Remote metadata is small. Never buffer an unbounded response from a future
+// handler revision: local-only diagnostics should not turn into remote memory DoS.
+const MAX_REMOTE_REDACTION_BYTES = 1024 * 1024
+
+/**
+ * A remote response requiring redaction must be completely validated *before*
+ * emitting headers or bytes. Unlike intercepting end() alone, this also covers
+ * write()+end(), malformed JSON, oversize bodies and async stream completion.
+ * No handler may transmit its raw token, path or other local fields while the
+ * remote body remains unvalidated.
+ */
 function runWithRemoteReadRedaction(path, handler, req, res) {
   const originalEnd = res?.end
-  if (typeof originalEnd !== 'function') return handler(req, res)
-  let active = true
-  res.end = function redactedEnd(chunk, ...args) {
-    if (!active) return originalEnd.call(this, chunk, ...args)
-    let next = chunk
+  const originalWrite = res?.write
+  const originalWriteHead = res?.writeHead
+  const originalFlushHeaders = res?.flushHeaders
+  if (typeof originalEnd !== 'function' || typeof originalWriteHead !== 'function') {
+    throw new TypeError('vision-router: remote redaction requires a buffered HTTP response')
+  }
+
+  const chunks = []
+  let bytes = 0
+  let done = false
+  let head
+  const restore = () => {
+    if (res.end === redactedEnd) res.end = originalEnd
+    if (res.write === redactedWrite) {
+      if (originalWrite === undefined) delete res.write
+      else res.write = originalWrite
+    }
+    if (res.writeHead === redactedWriteHead) res.writeHead = originalWriteHead
+    if (res.flushHeaders === redactedFlushHeaders) {
+      if (originalFlushHeaders === undefined) delete res.flushHeaders
+      else res.flushHeaders = originalFlushHeaders
+    }
+  }
+  const stripStagedHeaders = () => {
+    // Route handlers own the pre-redaction response. Even header values may
+    // contain future local-only tokens, paths or Set-Cookie material.
+    // Never forward any unreviewed staged header to a remote client.
     try {
-      if (typeof chunk === 'string' || Buffer.isBuffer(chunk) || chunk instanceof Uint8Array) {
-        const parsed = JSON.parse(Buffer.isBuffer(chunk) || chunk instanceof Uint8Array ? Buffer.from(chunk).toString('utf8') : chunk)
-        next = JSON.stringify(redactRemoteBody(path, parsed))
-        try { this.removeHeader?.('content-length') } catch { /* best effort */ }
-      }
-    } catch {
-      // If a future handler stops returning JSON, do not corrupt its response.
+      for (const key of res.getHeaderNames?.() ?? []) res.removeHeader?.(key)
+    } catch { /* a test double may not expose the header table */ }
+    for (const key of ['content-length', 'content-encoding', 'transfer-encoding']) {
+      try { res.removeHeader?.(key) } catch {}
     }
-    return originalEnd.call(this, next, ...args)
   }
-  const redactedEndReference = res.end
-  const restore = () => {
-    active = false
-    if (res.end === redactedEndReference) res.end = originalEnd
+  const safeHeaders = () => ({
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  const complete = (body, rejected = false, callback) => {
+    if (done) return res
+    done = true
+    // On rejection, deliberately retain the buffered wrappers after sending
+    // the safe error. A drifting async handler may continue calling write()
+    // or end(); restoring the raw methods here would expose those later bytes.
+    // The response is already ended and these wrappers swallow late writes.
+    if (!rejected) restore()
+    stripStagedHeaders()
+    if (rejected) {
+      // An invalid or oversized response is an internal gateway failure. Do
+      // not repeat the untrusted data or send previously staged headers.
+      originalWriteHead.call(res, 502, safeHeaders())
+      return originalEnd.call(res, JSON.stringify({
+        ok: false,
+        error: 'remote response could not be safely redacted',
+      }), callback)
+    }
+    if (head) {
+      originalWriteHead.call(res, head.status, safeHeaders())
+    } else {
+      originalWriteHead.call(res, Number.isInteger(res.statusCode) ? res.statusCode : 200, safeHeaders())
+    }
+    return originalEnd.call(res, body, callback)
   }
-  let result
+  const append = (chunk, encoding) => {
+    if (chunk === undefined || chunk === null) return true
+    let value
+    try {
+      if (Buffer.isBuffer(chunk)) value = chunk
+      else if (typeof chunk === 'string') value = Buffer.from(chunk, typeof encoding === 'string' ? encoding : 'utf8')
+      else if (chunk instanceof Uint8Array) value = Buffer.from(chunk)
+      else return false
+    } catch { return false }
+    if (value.length > MAX_REMOTE_REDACTION_BYTES - bytes) return false
+    bytes += value.length
+    chunks.push(value)
+    return true
+  }
+  const failed = () => complete(undefined, true)
+  function redactedWriteHead(status, maybeMessage, maybeHeaders) {
+    if (done) return this
+    const message = typeof maybeMessage === 'string' ? maybeMessage : undefined
+    const headers = message === undefined ? maybeMessage : maybeHeaders
+    if (head || !Number.isInteger(status) || status < 100 || status > 599 ||
+      (headers !== undefined && (!headers || typeof headers !== 'object' || Array.isArray(headers)))) {
+      failed()
+      return this
+    }
+    head = { status, message, headers }
+    return this
+  }
+  function redactedFlushHeaders() {
+    // Deferring the header is essential: once sent, an invalid JSON body
+    // cannot be replaced by a safe 502.
+  }
+  function redactedWrite(chunk, encoding, callback) {
+    const completeWrite = typeof encoding === 'function' ? encoding : callback
+    if (!done && !append(chunk, encoding)) failed()
+    if (typeof completeWrite === 'function') queueMicrotask(completeWrite)
+    return !done
+  }
+  function redactedEnd(chunk, encoding, callback) {
+    if (done) return res
+    const completeEnd = typeof encoding === 'function' ? encoding : callback
+    if (!append(chunk, encoding)) return failed()
+    try {
+      const body = JSON.parse(Buffer.concat(chunks, bytes).toString('utf8'))
+      if (!body || typeof body !== 'object' || Array.isArray(body)) return failed()
+      const redacted = JSON.stringify(redactRemoteBody(path, body))
+      if (Buffer.byteLength(redacted, 'utf8') > MAX_REMOTE_REDACTION_BYTES) return failed()
+      return complete(redacted, false, completeEnd)
+    } catch {
+      return failed()
+    }
+  }
+
+  res.writeHead = redactedWriteHead
+  res.write = redactedWrite
+  res.end = redactedEnd
+  res.flushHeaders = redactedFlushHeaders
   try {
-    result = handler(req, res)
-  } catch (error) {
-    restore()
-    throw error
+    const result = handler(req, res)
+    if (result && typeof result.then === 'function') {
+      return Promise.resolve(result).catch(() => { if (!done) failed() })
+    }
+    return result
+  } catch {
+    if (!done) failed()
+    return undefined
   }
-  if (result && typeof result.then === 'function') return result.finally(restore)
-  restore()
-  return result
 }
 
 function guardedRoute(route, getConnection) {