dsh-vision-router 2.3.0 → 3.0.0

package/lib/vision-routing-product.js

@@ -5,40 +5,37 @@
 // A user chooses whether routing is automatic or strictly ordered, then chooses
 // a plain-language preference. The actual execution-changing auto mode is
 // enabled only when the runtime is ready to honor this contract.
-
-export const VISION_ROUTING_MODES = Object.freeze(['ordered', 'auto'])
-export const VISION_ROUTING_PREFERENCES = Object.freeze(['balanced', 'quality', 'speed', 'local'])
-
-const MODE_SET = new Set(VISION_ROUTING_MODES)
-const PREFERENCE_SET = new Set(VISION_ROUTING_PREFERENCES)
-
+export const VISION_ROUTING_MODES = Object.freeze(['ordered', 'auto']);
+export const VISION_ROUTING_PREFERENCES = Object.freeze(['balanced', 'quality', 'speed', 'local']);
+const MODE_SET = new Set(VISION_ROUTING_MODES);
+const PREFERENCE_SET = new Set(VISION_ROUTING_PREFERENCES);
 export function normalizeVisionRoutingMode(value, fallback = 'ordered') {
-  const normalizedFallback = MODE_SET.has(fallback) ? fallback : 'ordered'
-  return typeof value === 'string' && MODE_SET.has(value.trim()) ? value.trim() : normalizedFallback
+    const normalizedFallback = typeof fallback === 'string' && MODE_SET.has(fallback) ? fallback : 'ordered';
+    const candidate = typeof value === 'string' ? value.trim() : '';
+    return MODE_SET.has(candidate) ? candidate : normalizedFallback;
 }
-
 export function normalizeVisionRoutingPreference(value) {
-  if (typeof value === 'string') {
-    const candidate = value.trim()
-    if (PREFERENCE_SET.has(candidate)) return candidate
-  }
-
-  return 'balanced'
+    if (typeof value === 'string') {
+        const candidate = value.trim();
+        if (PREFERENCE_SET.has(candidate))
+            return candidate;
+    }
+    return 'balanced';
 }
-
 export function routingPreferenceToCapabilityStrategy(preference) {
-  const normalized = normalizeVisionRoutingPreference(preference)
-  return normalized === 'local' ? 'privacy' : normalized
+    const normalized = normalizeVisionRoutingPreference(preference);
+    return normalized === 'local' ? 'privacy' : normalized;
 }
-
 export function resolveVisionRoutingProduct(config = {}) {
-  const source = config && typeof config === 'object' && !Array.isArray(config) ? config : {}
-  const mode = normalizeVisionRoutingMode(source.routingMode)
-  const preference = normalizeVisionRoutingPreference(source.routingPreference)
-  return {
-    mode,
-    preference,
-    strategy: routingPreferenceToCapabilityStrategy(preference),
-    automatic: mode === 'auto',
-  }
+    const source = config && typeof config === 'object' && !Array.isArray(config)
+        ? config
+        : {};
+    const mode = normalizeVisionRoutingMode(source.routingMode);
+    const preference = normalizeVisionRoutingPreference(source.routingPreference);
+    return {
+        mode,
+        preference,
+        strategy: routingPreferenceToCapabilityStrategy(preference),
+        automatic: mode === 'auto',
+    };
 }

package/lib/vision-routing-settings-prelude.js

@@ -446,7 +446,7 @@ export const VISION_ROUTING_SETTINGS_PRELUDE = String.raw`(function(){
     try { state.backgroundTimer && state.backgroundTimer.unref && state.backgroundTimer.unref(); } catch (_) {}
     schedule();
 
-    var dispose = function() {
+    var dispose = async function() {
       state.disposed = true;
       if (state.scanTimer !== undefined) clearTimeout(state.scanTimer);
       if (state.backgroundTimer !== undefined) clearInterval(state.backgroundTimer);
@@ -456,13 +456,18 @@ export const VISION_ROUTING_SETTINGS_PRELUDE = String.raw`(function(){
         try { disposeRemote(); } catch (_) {}
       });
       state.remoteDisposers.length = 0;
-      if (remote && scope && typeof scope.dispose === 'function') void scope.dispose();
       if (state.panel && state.panel.parentNode) state.panel.parentNode.removeChild(state.panel);
       if (states) states.delete(ctx);
+      if (remote && scope && typeof scope.dispose === 'function') await scope.dispose();
     };
+    var lifecycleOwned = false;
     try {
-      if (typeof ctx.effect === 'function') ctx.effect(function(){ return dispose; }, 'vision-router: routing settings product panel');
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(function(){ return dispose; }, 'vision-router: routing settings product panel');
+        lifecycleOwned = true;
+      }
     } catch (_) {}
+    if (!lifecycleOwned) void dispose().catch(function(){});
   }
 
   function patchLoader(loader) {

package/lib/vision-runtime-performance-store.js

@@ -0,0 +1,166 @@
+import { BENCHMARK_AXES, } from './vision-capability-evidence.js';
+export const DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS = 60 * 60 * 1000;
+export const DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES = 8;
+export const DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES = 2;
+export const DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS = 128;
+function finiteLatency(value) {
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+function median(values) {
+    const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+    if (sorted.length === 0)
+        return undefined;
+    const middle = Math.floor(sorted.length / 2);
+    const right = sorted[middle];
+    if (right === undefined)
+        return undefined;
+    if (sorted.length % 2 === 1)
+        return right;
+    const left = sorted[middle - 1];
+    return left === undefined ? right : (left + right) / 2;
+}
+function cleanBackendKey(value) {
+    const text = typeof value === 'string' ? value.trim() : '';
+    return text === '' ? undefined : text.slice(0, 512);
+}
+function isBenchmarkAxis(value) {
+    return typeof value === 'string'
+        && BENCHMARK_AXES.includes(value);
+}
+export function createVisionRuntimePerformanceSampleStore(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : Date.now;
+    const maxAgeMs = Math.max(1_000, Number(options.maxAgeMs) || DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS);
+    const maxSamples = Math.max(1, Math.min(64, Math.floor(Number(options.maxSamples) || DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES)));
+    const minSamples = Math.max(1, Math.min(maxSamples, Math.floor(Number(options.minSamples) || DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES)));
+    const maxBackends = Math.max(1, Math.min(1024, Math.floor(Number(options.maxBackends) || DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS)));
+    const records = new Map();
+    let identityContext = options.context;
+    const identityResolver = options.identityResolver;
+    const resolvedStorageKey = (backendKey) => {
+        const key = cleanBackendKey(backendKey);
+        if (key === undefined)
+            return undefined;
+        let identity;
+        try {
+            identity = identityContext && identityResolver !== undefined
+                ? identityResolver(key, identityContext)
+                : undefined;
+        }
+        catch {
+            identity = undefined;
+        }
+        return identity ? `${key}\u0000${String(identity)}` : key;
+    };
+    const pruneAxis = (samples, at) => samples.filter((sample) => at - sample.at <= maxAgeMs);
+    const pruneBackend = (key, at) => {
+        const axes = records.get(key);
+        if (axes === undefined)
+            return undefined;
+        for (const [axis, samples] of axes) {
+            const current = pruneAxis(samples, at);
+            if (current.length === 0)
+                axes.delete(axis);
+            else if (current.length !== samples.length)
+                axes.set(axis, current);
+        }
+        if (axes.size === 0) {
+            records.delete(key);
+            return undefined;
+        }
+        records.delete(key);
+        records.set(key, axes);
+        return axes;
+    };
+    const bound = () => {
+        while (records.size > maxBackends) {
+            const oldest = records.keys().next().value;
+            if (oldest === undefined)
+                break;
+            records.delete(oldest);
+        }
+    };
+    return {
+        maxAgeMs,
+        maxSamples,
+        minSamples,
+        bindContext(context) {
+            identityContext = context;
+        },
+        record(backendKey, axisValue, latencyMsValue, atValue = now()) {
+            const key = resolvedStorageKey(backendKey);
+            const latencyMs = finiteLatency(latencyMsValue);
+            const at = Number(atValue);
+            if (key === undefined
+                || !isBenchmarkAxis(axisValue)
+                || latencyMs === undefined
+                || !Number.isFinite(at)) {
+                return false;
+            }
+            let axes = pruneBackend(key, at);
+            if (axes === undefined) {
+                axes = new Map();
+                records.set(key, axes);
+            }
+            const current = pruneAxis(axes.get(axisValue) ?? [], at);
+            current.push({ at, latencyMs });
+            if (current.length > maxSamples) {
+                current.splice(0, current.length - maxSamples);
+            }
+            axes.set(axisValue, current);
+            records.delete(key);
+            records.set(key, axes);
+            bound();
+            return true;
+        },
+        get(backendKey, atValue = now()) {
+            const key = resolvedStorageKey(backendKey);
+            const at = Number(atValue);
+            if (key === undefined || !Number.isFinite(at))
+                return undefined;
+            const axes = pruneBackend(key, at);
+            if (axes === undefined)
+                return undefined;
+            const observedLatencyMsByAxis = {};
+            const runtimeLatencyMsByAxis = {};
+            const sampleCountByAxis = {};
+            const observedAtByAxis = {};
+            for (const [axis, samples] of axes) {
+                const latencyMs = median(samples.map((sample) => sample.latencyMs));
+                if (latencyMs === undefined)
+                    continue;
+                observedLatencyMsByAxis[axis] = latencyMs;
+                sampleCountByAxis[axis] = samples.length;
+                observedAtByAxis[axis] = Math.max(...samples.map((sample) => sample.at));
+                if (samples.length >= minSamples)
+                    runtimeLatencyMsByAxis[axis] = latencyMs;
+            }
+            return {
+                runtimeLatencyMsByAxis,
+                observedLatencyMsByAxis,
+                sampleCountByAxis,
+                observedAtByAxis,
+                maxAgeMs,
+                minSamples,
+            };
+        },
+        clear(backendKey) {
+            if (backendKey === undefined) {
+                records.clear();
+                return;
+            }
+            const base = cleanBackendKey(backendKey);
+            if (base === undefined)
+                return;
+            records.delete(base);
+            const prefix = `${base}\u0000`;
+            for (const key of [...records.keys()]) {
+                if (key.startsWith(prefix))
+                    records.delete(key);
+            }
+        },
+        size() {
+            return records.size;
+        },
+    };
+}

package/lib/vision-runtime-performance.js

@@ -1,37 +1,19 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
-import {
-  benchmarkAxisForVisionIntent,
-  inferToolVisionIntent,
-} from './vision-capability-router.js'
+import { benchmarkAxisForVisionIntent } from './vision-capability-evidence.js'
+import { inferToolVisionIntent } from './vision-capability-router.js'
 import { capabilityEvidenceFingerprint } from './vision-capability-identity.js'
 import { providerTransportFor } from './live-model-discovery.js'
+import { createVisionRuntimePerformanceSampleStore } from './vision-runtime-performance-store.js'
 
-export const DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS = 60 * 60 * 1000
-export const DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES = 8
-export const DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES = 2
-export const DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS = 128
+export {
+  DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS,
+  DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES,
+  DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES,
+  DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS,
+} from './vision-runtime-performance-store.js'
 
 const runtimeScope = new AsyncLocalStorage()
 
-function finiteLatency(value) {
-  const number = Number(value)
-  return Number.isFinite(number) && number >= 0 ? number : undefined
-}
-
-function median(values) {
-  const sorted = values.filter(Number.isFinite).sort((a, b) => a - b)
-  if (sorted.length === 0) return undefined
-  const middle = Math.floor(sorted.length / 2)
-  return sorted.length % 2 === 1
-    ? sorted[middle]
-    : (sorted[middle - 1] + sorted[middle]) / 2
-}
-
-function cleanBackendKey(value) {
-  const text = typeof value === 'string' ? value.trim() : ''
-  return text === '' ? undefined : text.slice(0, 512)
-}
-
 function backendParts(backendKey) {
   const key = cleanBackendKey(backendKey)
   if (!key) return undefined
@@ -91,124 +73,13 @@ function failureFinish(chunk) {
 }
 
 export function createVisionRuntimePerformanceStore(options = {}) {
-  const now = typeof options.now === 'function' ? options.now : Date.now
-  const maxAgeMs = Math.max(1_000, Number(options.maxAgeMs) || DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS)
-  const maxSamples = Math.max(1, Math.min(64, Math.floor(Number(options.maxSamples) || DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES)))
-  const minSamples = Math.max(1, Math.min(maxSamples, Math.floor(Number(options.minSamples) || DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES)))
-  const maxBackends = Math.max(1, Math.min(1024, Math.floor(Number(options.maxBackends) || DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS)))
-  const records = new Map()
-  let identityContext = options.context
   const identityResolver = typeof options.identityResolver === 'function'
     ? options.identityResolver
     : (backendKey, ctx) => runtimePerformanceIdentityFor(ctx, backendKey)
-
-  const resolvedStorageKey = (backendKey) => {
-    const key = cleanBackendKey(backendKey)
-    if (!key) return undefined
-    let identity
-    try { identity = identityContext ? identityResolver(key, identityContext) : undefined } catch { identity = undefined }
-    return identity ? `${key}\u0000${identity}` : key
-  }
-
-  const pruneAxis = (samples, at) => samples.filter((sample) => at - sample.at <= maxAgeMs)
-
-  const pruneBackend = (key, at) => {
-    const axes = records.get(key)
-    if (!axes) return undefined
-    for (const [axis, samples] of axes) {
-      const current = pruneAxis(samples, at)
-      if (current.length === 0) axes.delete(axis)
-      else if (current.length !== samples.length) axes.set(axis, current)
-    }
-    if (axes.size === 0) {
-      records.delete(key)
-      return undefined
-    }
-    // LRU touch only on runtime-observation reads/writes; routing diagnostics
-    // are allowed to read this performance store because it is not the v1
-    // breaker and has no execution side effects.
-    records.delete(key)
-    records.set(key, axes)
-    return axes
-  }
-
-  const bound = () => {
-    while (records.size > maxBackends) {
-      const oldest = records.keys().next().value
-      if (oldest === undefined) break
-      records.delete(oldest)
-    }
-  }
-
-  return {
-    maxAgeMs,
-    maxSamples,
-    minSamples,
-    bindContext(ctx) {
-      identityContext = ctx
-    },
-    record(backendKey, axis, latencyMs, at = now()) {
-      const key = resolvedStorageKey(backendKey)
-      const latency = finiteLatency(latencyMs)
-      const timestamp = Number(at)
-      if (!key || !benchmarkAxisForVisionIntent(axis) || latency === undefined || !Number.isFinite(timestamp)) return false
-      let axes = pruneBackend(key, timestamp)
-      if (!axes) {
-        axes = new Map()
-        records.set(key, axes)
-      }
-      const current = pruneAxis(axes.get(axis) ?? [], timestamp)
-      current.push({ at: timestamp, latencyMs: latency })
-      if (current.length > maxSamples) current.splice(0, current.length - maxSamples)
-      axes.set(axis, current)
-      records.delete(key)
-      records.set(key, axes)
-      bound()
-      return true
-    },
-    get(backendKey, at = now()) {
-      const key = resolvedStorageKey(backendKey)
-      const timestamp = Number(at)
-      if (!key || !Number.isFinite(timestamp)) return undefined
-      const axes = pruneBackend(key, timestamp)
-      if (!axes) return undefined
-      const observedLatencyMsByAxis = {}
-      const runtimeLatencyMsByAxis = {}
-      const sampleCountByAxis = {}
-      const observedAtByAxis = {}
-      for (const [axis, samples] of axes) {
-        const latencies = samples.map((sample) => sample.latencyMs)
-        const value = median(latencies)
-        if (value === undefined) continue
-        observedLatencyMsByAxis[axis] = value
-        sampleCountByAxis[axis] = samples.length
-        observedAtByAxis[axis] = Math.max(...samples.map((sample) => sample.at))
-        if (samples.length >= minSamples) runtimeLatencyMsByAxis[axis] = value
-      }
-      return {
-        runtimeLatencyMsByAxis,
-        observedLatencyMsByAxis,
-        sampleCountByAxis,
-        observedAtByAxis,
-        maxAgeMs,
-        minSamples,
-      }
-    },
-    clear(backendKey) {
-      if (backendKey === undefined) {
-        records.clear()
-        return
-      }
-      const base = cleanBackendKey(backendKey)
-      if (!base) return
-      records.delete(base)
-      const prefix = `${base}\u0000`
-      for (const key of [...records.keys()]) if (key.startsWith(prefix)) records.delete(key)
-    },
-    size() {
-      return records.size
-    },
-  }
+  return createVisionRuntimePerformanceSampleStore({
+    ...options,
+    identityResolver,
+  })
 }
 
 export function withVisionRuntimePerformanceScope(toolName, args, fn) {

package/lib/vision-tool-runtime-boundary.js

@@ -17,6 +17,9 @@ const toolRuntime = new AsyncLocalStorage()
 const wrappedContexts = new WeakMap()
 const runtimeStates = new WeakMap()
 const wrappedFileSystems = new WeakMap()
+// Settings proxies are cached per underlying service/scope and per runtime
+// state. Re-creating them on every `ctx.settings` read would re-run scope
+// activation and register a second lifecycle effect for the same generation.
 const wrappedSettings = new WeakMap()
 const wrappedScopes = new WeakMap()
 const wrappedLlms = new WeakMap()
@@ -104,7 +107,7 @@ function createRuntimeState(initialConfig = {}) {
   const cache = new LiveDescribeCache()
   const endpoints = new HttpEndpointRevisionTracker()
   const transparentReasoning = new Map()
-  let config = {
+  const fallbackConfig = {
     cache: true,
     cacheMaxEntries: 200,
     cacheTtlSeconds: 3600,
@@ -115,8 +118,13 @@ function createRuntimeState(initialConfig = {}) {
       ? initialConfig
       : {}),
   }
+  let config = fallbackConfig
   let signature = stableRuntimeConfigSignature(config)
   let revision = 0
+  let activeSettingsGeneration
+  // scope -> { runtimeState, token, ownsLifecycle }: the generation registry
+  // that makes repeated activation idempotent per runtime.
+  const wiredScopes = new WeakMap()
 
   const noteConfig = (value) => {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return config
@@ -135,6 +143,59 @@ function createRuntimeState(initialConfig = {}) {
     return config
   }
 
+  const activateSettingsScope = (scope, ownerCtx, runtimeState) => {
+    if (!scope || (typeof scope !== 'object' && typeof scope !== 'function')) return undefined
+    // Registering the same scope twice (repeated `ctx.settings` reads, a
+    // generation that re-registers its namespace) must not stack lifecycle
+    // owners or mint a competing generation: reuse the existing one.
+    const known = wiredScopes.get(scope)
+    if (known && known.runtimeState === runtimeState) {
+      if (activeSettingsGeneration?.token !== known.token) {
+        activeSettingsGeneration = { token: known.token, scope, ownsLifecycle: known.ownsLifecycle }
+      }
+      return known.token
+    }
+    const token = {}
+    // Lifecycle ownership is an optimisation, not a precondition: a context
+    // without `effect()` (harness contexts, non-Cordis embeddings) still needs
+    // live settings to reach the runtime, but the generation must then be the
+    // most recently registered scope so a stale scope cannot outrank it.
+    let ownsLifecycle = false
+    try {
+      if (typeof ownerCtx?.effect === 'function') {
+        ownerCtx.effect(
+          () => () => {
+            if (activeSettingsGeneration?.token !== token) return
+            activeSettingsGeneration = undefined
+            noteConfig(fallbackConfig)
+          },
+          'vision-router: tool runtime settings lifecycle',
+        )
+        ownsLifecycle = true
+      }
+    } catch {
+      ownsLifecycle = false
+    }
+    wiredScopes.set(scope, { runtimeState, token, ownsLifecycle })
+    activeSettingsGeneration = { token, scope, ownsLifecycle }
+    try {
+      if (typeof scope.get === 'function') noteConfig(scope.get())
+    } catch {
+      // Boot config remains authoritative until the scope becomes readable.
+    }
+    return token
+  }
+
+  const noteSettingsConfig = (token, value) => {
+    // Only the active generation may write config. An unowned generation is
+    // still "the active one" while it is the latest registration, so a
+    // lifecycle-less context keeps its watch path exactly as before the token
+    // existed, while a retired generation can no longer resurrect stale config.
+    if (token === undefined || activeSettingsGeneration?.token !== token) return false
+    noteConfig(value)
+    return true
+  }
+
   const rememberTransparentReasoning = (key, value) => {
     if (transparentReasoning.size >= MAX_TRANSPARENT_REASONING_MEMORY && !transparentReasoning.has(key)) {
       const oldest = transparentReasoning.keys().next().value
@@ -156,6 +217,8 @@ function createRuntimeState(initialConfig = {}) {
     cache,
     endpoints,
     noteConfig,
+    activateSettingsScope,
+    noteSettingsConfig,
     config: () => config,
     revision: () => revision,
     rememberTransparentReasoning,
@@ -242,9 +305,12 @@ function wrapFileSystem(fs) {
   return wrapped
 }
 
-function projectLiveSettings(value, runtimeState) {
+function projectLiveSettings(value, runtimeState, settingsToken) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return value
-  runtimeState.noteConfig(value)
+  if (settingsToken !== undefined && runtimeState.noteSettingsConfig(settingsToken, value) !== true) {
+    return value
+  }
+  if (settingsToken === undefined) runtimeState.noteConfig(value)
   const toolState = toolRuntime.getStore()
   const httpProviders = runtimeState.endpoints.project(value.httpProviders)
   const suppressCoreCache = toolState?.disableCoreCache === true && value.cache !== false
@@ -256,21 +322,16 @@ function projectLiveSettings(value, runtimeState) {
   }
 }
 
-function wrapSettingsScope(scope, runtimeState) {
+function wrapSettingsScope(scope, runtimeState, settingsToken) {
   if (!scope || (typeof scope !== 'object' && typeof scope !== 'function')) return scope
-  let byRuntime = wrappedScopes.get(scope)
-  if (!byRuntime) {
-    byRuntime = new WeakMap()
-    wrappedScopes.set(scope, byRuntime)
-  }
-  const cached = byRuntime.get(runtimeState)
-  if (cached) return cached
+  const cached = wrappedScopes.get(scope)
+  if (cached && cached.runtimeState === runtimeState && cached.token === settingsToken) return cached.wrapped
   const wrapped = new Proxy(scope, {
     get(target, property) {
       if (property === 'get') {
         const get = Reflect.get(target, property, target)
         if (typeof get !== 'function') return get
-        return (...args) => projectLiveSettings(get.apply(target, args), runtimeState)
+        return (...args) => projectLiveSettings(get.apply(target, args), runtimeState, settingsToken)
       }
       if (property === 'watch') {
         const watch = Reflect.get(target, property, target)
@@ -278,7 +339,7 @@ function wrapSettingsScope(scope, runtimeState) {
         return (callback, ...rest) => watch.call(target, (...args) => {
           try {
             const get = Reflect.get(target, 'get', target)
-            if (typeof get === 'function') runtimeState.noteConfig(get.call(target))
+            if (typeof get === 'function') runtimeState.noteSettingsConfig(settingsToken, get.call(target))
           } catch {
             // Diagnostics refresh is best effort.
           }
@@ -289,19 +350,14 @@ function wrapSettingsScope(scope, runtimeState) {
       return typeof value === 'function' ? value.bind(target) : value
     },
   })
-  byRuntime.set(runtimeState, wrapped)
+  wrappedScopes.set(scope, { runtimeState, token: settingsToken, wrapped })
   return wrapped
 }
 
-function wrapSettingsService(settings, runtimeState) {
+function wrapSettingsService(settings, runtimeState, ownerCtx) {
   if (!settings || (typeof settings !== 'object' && typeof settings !== 'function')) return settings
-  let byRuntime = wrappedSettings.get(settings)
-  if (!byRuntime) {
-    byRuntime = new WeakMap()
-    wrappedSettings.set(settings, byRuntime)
-  }
-  const cached = byRuntime.get(runtimeState)
-  if (cached) return cached
+  const cached = wrappedSettings.get(settings)
+  if (cached && cached.runtimeState === runtimeState) return cached.wrapped
   const wrapped = new Proxy(settings, {
     get(target, property) {
       if (property === 'register') {
@@ -310,25 +366,22 @@ function wrapSettingsService(settings, runtimeState) {
         return (namespace, ...args) => {
           const scope = register.call(target, namespace, ...args)
           if (namespace !== 'vision-router') return scope
-          try {
-            if (typeof scope?.get === 'function') runtimeState.noteConfig(scope.get())
-          } catch {
-            // Core can still run from boot config if settings are late.
-          }
-          return wrapSettingsScope(scope, runtimeState)
+          const settingsToken = runtimeState.activateSettingsScope(scope, ownerCtx, runtimeState)
+          if (settingsToken === undefined) return scope
+          return wrapSettingsScope(scope, runtimeState, settingsToken)
         }
       }
       const value = Reflect.get(target, property, target)
       return typeof value === 'function' ? value.bind(target) : value
     },
   })
-  byRuntime.set(runtimeState, wrapped)
+  wrappedSettings.set(settings, { runtimeState, wrapped })
   return wrapped
 }
 
 function wrapSettingsContext(ctx, runtimeState) {
   if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function') || !ctx.settings) return ctx
-  const settings = wrapSettingsService(ctx.settings, runtimeState)
+  const settings = wrapSettingsService(ctx.settings, runtimeState, ctx)
   return new Proxy(ctx, {
     get(target, property) {
       if (property === 'settings') return settings
@@ -716,6 +769,22 @@ export function installVisionToolRuntimeBoundary(ctx, initialConfig = {}) {
   })
   wrappedContexts.set(ctx, wrapped)
   runtimeStates.set(wrapped, runtimeState)
+  let lifecycleOwned = false
+  try {
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(
+        () => () => {
+          if (wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
+        },
+        'vision-router: vision tool runtime context lifecycle',
+      )
+      lifecycleOwned = true
+    }
+  } catch {
+    // Keep the current returned view usable as a one-shot boundary.
+  }
+  // runtimeState captures this generation's config/cache/endpoint revision.
+  if (!lifecycleOwned && wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
   return wrapped
 }