dsh-vision-router 1.7.4 → 1.7.5

package/docs/doctor.md

@@ -1,10 +1,14 @@
 # Vision Router doctor / repair
 
-Vision Router ships a small standalone diagnostic CLI. It does not need DSH to boot first, so it can still run when DSH exits while parsing a broken profile manifest or when an older Vision Router build left one conversation unable to cold-resume.
+Vision Router ships a standalone diagnostic CLI. It can inspect a broken DSH profile even when DSH cannot boot, and it can optionally probe a running Web instance without executing any Vision Router action.
 
-## Normal installation stays unchanged
+The commands have a deliberately conservative split:
+
+- `doctor` is read-only by default;
+- `repair` changes only the two known profile-level faults described below;
+- `repair-sessions` changes only exact, known Vision Router session-corruption signatures and always makes a byte-for-byte backup first.
 
-Use DSH's own plugin command:
+## Normal installation stays unchanged
 
 ```sh
 npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
@@ -20,19 +24,90 @@ pnpm dsh web
 
 The doctor is a recovery/diagnostic tool, not a replacement installer.
 
-## Diagnose profiles
+## Doctor v2
+
+Run the normal health check:
 
 ```sh
 npx dsh-vision-router doctor
 ```
 
-To inspect only the Web profile:
+Or inspect one profile explicitly:
 
 ```sh
 npx dsh-vision-router doctor --profile web
 ```
 
-The command locates the DSH home (`$DSH_HOME` when set, otherwise `~/.dsh`), scans profile `package.json` files, reports UTF-8 BOM bytes, validates the JSON after ignoring a leading BOM for diagnosis, reports whether `dsh-vision-router` is present as a profile dependency and bundle layer, and flags version-pinned `minimumReleaseAgeExclude` entries in the profile's `pnpm-workspace.yaml` that would hold back the next release.
+The doctor now separates **"the profile JSON parses"** from **"Vision Router is actually healthy"**. A requested profile is unhealthy when the package is missing, declared but not installed, installed but not mounted, registered twice, or otherwise cannot form one valid activation path.
+
+It recognizes both supported profile shapes:
+
+- **bundle mode** — `dsh-vision-router` is declared in `dependencies` and registered once in `dsh.profile.bundles`;
+- **manual mode** — the dependency is declared and the profile's `cordis.patch.yml` contains one Vision Router row.
+
+It reports a hard failure for a bundle+manual double registration, duplicate bundle/manual rows, a missing installed package, or an installed/declared package with no activation row. Profiles that do not use Vision Router are shown as unrelated when scanning all profiles; they do not make another healthy Vision Router profile fail.
+
+The offline profile check also keeps the existing diagnostics for:
+
+- a leading UTF-8 BOM or otherwise invalid profile JSON;
+- stale version-pinned `minimumReleaseAgeExclude` entries;
+- coexisting vision plugins;
+- legacy profile patches that statically disable `llm-deepseek`;
+- recent structured `settings save failed field=... operation=... reason=...` records from the Vision Router log. Raw log lines, API keys and arbitrary values are not copied into the report.
+
+### Running-DSH route probe
+
+When DSH Web is reachable, doctor checks that the Vision Router exact routes are really registered. This catches the class of regressions where the plugin partly loads but routes such as `update-check` or `model-capabilities` silently disappear and the SPA fallback returns HTML instead.
+
+The probe sends an intentionally unsupported **DELETE** request to each known route. Every current Vision Router handler rejects that method with `405 Method Not Allowed` and its exact `Allow` contract **before** executing GET/POST behavior. Doctor verifies that exact method contract, so it does **not** run an update check, model discovery, connection test, settings mutation, self-update or log-opening action. Using the expected `Allow` set also prevents a generic SPA/unknown-route response from being mistaken for a registered Vision Router route.
+
+Default target:
+
+```text
+http://127.0.0.1:3080
+```
+
+Override it with:
+
+```sh
+npx dsh-vision-router doctor --runtime-url http://127.0.0.1:4000
+```
+
+or `DSH_WEB_URL`. To perform offline checks only:
+
+```sh
+npx dsh-vision-router doctor --no-runtime
+```
+
+An unreachable DSH process is advisory rather than a doctor failure; offline checks still complete. When `--profile` is used against a reachable runtime, doctor does not attribute green route health to that profile unless the runtime exposes a verified Vision Router profile identity. If ownership cannot be proven, the human report shows `? runtime profile ownership unknown` instead of a false green binding.
+
+### Local capability diagnostics
+
+Doctor reports the local platform, Node version, and whether it can find:
+
+- Tesseract (PATH plus the common Windows install location);
+- Chromium / Chrome / Edge (PATH plus common Windows and macOS locations);
+- `sharp` and selected DSH host package versions when they are present inside the inspected profile.
+
+Tesseract, Chromium and profile-local Sharp are advisory because the corresponding optional tool may be unused or supplied by the host through another resolution path.
+
+### Scan historical sessions
+
+Session scanning is opt-in because a large session store can take longer to read/decompress:
+
+```sh
+npx dsh-vision-router doctor --sessions
+```
+
+This is read-only. It looks only for the exact known Vision Router corruption signatures supported by `repair-sessions`.
+
+### Shareable JSON report
+
+```sh
+npx dsh-vision-router doctor --profile web --sessions --json
+```
+
+The JSON report is schema-versioned and includes the running Doctor/Vision Router version. It is intentionally minimized for issue reports: it does not contain the raw profile manifest, raw log lines, API keys, raw dependency specs, local dependency paths, URL credentials/query strings/fragments, session ids, or raw runtime error text. It keeps only structured diagnostic facts such as install mode, installed version, route status, failure counts, optional capability versions and known session-repair kinds.
 
 ## Repair the UTF-8 BOM startup failure
 
@@ -51,33 +126,47 @@ npx dsh-vision-router repair --profile web
 
 `repair` removes only the three-byte UTF-8 BOM prefix (`EF BB BF`) when it is present, then validates the remaining JSON. It does not reformat, regenerate, or otherwise rewrite the profile contents. If JSON is still invalid for another reason, the command reports that and stops rather than guessing a repair.
 
-## Repair a stale release-age exemption (the "update does nothing" gate)
-
-pnpm v11 defaults `minimumReleaseAge` to 1440 minutes: a version published less than 24 hours ago is not resolved, so `dsh plugin update` silently keeps the previous version and prints `downloaded 0 / added 0`. An exemption entry that pins a version — `dsh-vision-router@1.2.0` — only exempts that one version and goes stale on the next release, which is why "a new release is out but the update does nothing" keeps recurring.
+`doctor --fix` remains accepted for backward compatibility, but new troubleshooting instructions should prefer the explicit `repair` command so that ordinary doctor runs stay obviously read-only.
 
-The doctor flags version-pinned entries for `dsh-vision-router` and the `@deepseek-ai/*` host packages:
+## Repair a stale release-age exemption (the "update does nothing" gate)
 
-```text
-✗ web — … — release-age exemption version-pinned (dsh-vision-router@1.2.0) — releases younger than 24h will not be picked up
-```
+pnpm v11 defaults `minimumReleaseAge` to 1440 minutes. A version-pinned exemption such as `dsh-vision-router@1.2.0` exempts only that version and goes stale on the next release.
 
-Run:
+Doctor flags version-pinned entries for `dsh-vision-router` and `@deepseek-ai/*`. Run:
 
 ```sh
 npx dsh-vision-router repair --profile web
 ```
 
-to rewrite them to bare names (`dsh-vision-router`, `@deepseek-ai/*`), which exempt every future version, so upgrades take effect immediately again. Unrelated entries and the rest of the file are left untouched.
+to rewrite only those stale targets to bare names (`dsh-vision-router`, `@deepseek-ai/*`). Unrelated entries and the rest of the workspace file are left untouched.
+
+## Repair conversations that only break after restarting DSH
+
+Two historical Vision Router defects can leave already-persisted sessions unable to cold-resume even though current builds no longer create the bad events.
 
-## Repair a conversation that only breaks after restarting DSH
+### Legacy missing message id
 
-A very early Vision Router build briefly persisted the automatic vision-tool mount reminder as a `user/message` without a message `id`. The conversation could keep working in the live process, but after DSH restarted the stricter cold-resume validator could reject that stored event with an error containing:
+A very early build persisted the automatic vision-tool mount reminder as a `user/message` without an `id`. DSH can later reject it with an error containing:
 
 ```text
 lacks an identified message
 ```
 
-Current Vision Router builds no longer create that malformed event. To recover an already-affected conversation, **stop DSH first**, then run:
+### Duplicate structured guard-stop id
+
+Older structured-flow builds could persist the same exact guard message more than once in one turn, for example:
+
+```text
+vision-router-structured-guard-stop-1
+```
+
+DSH then sees more than one `input-message...` start when the conversation is reloaded and can fail with an error containing:
+
+```text
+received more than one start Match
+```
+
+To repair either known case, **stop DSH first**, then run:
 
 ```sh
 npx dsh-vision-router repair-sessions
@@ -85,12 +174,16 @@ npx dsh-vision-router repair-sessions
 
 The repair is intentionally narrow and fail-closed:
 
-- it scans `$DSH_HOME/sessions` for the exact historical Vision Router auto-mount reminder signature only;
-- unrelated malformed messages are not changed;
-- both raw `session.jsonl` and DSH's default checksummed `session.jsonl.zstd` format are supported;
-- unchanged Zstandard frames stay byte-for-byte identical;
-- torn/incomplete logs are refused so DSH can perform its own crash recovery first;
-- the source file identity is checked again immediately before replacement, so a live writer causes the operation to abort instead of racing;
-- every changed log receives a byte-for-byte backup next to the original before replacement, and the repaired log is re-read and verified before success is reported.
-
-After the command reports a repaired session, restart DSH and reopen the conversation. Running `repair-sessions` again is idempotent: already-repaired logs are left untouched.
+- the old missing-id repair still matches only the exact historical Vision Router auto-mount reminder;
+- duplicate guard repair recognizes only Vision Router `user/message` events with the exact historical guard id shape, plugin source and one of the exact known budget/depth exhaustion texts;
+- the first legitimate guard is preserved; later exact duplicates keep their original event and `seq`, but receive deterministic unique recovery ids so the durable event stream is not shortened;
+- if the same guard id appears with a different/near-miss shape or text, automatic repair aborts instead of deleting data;
+- raw `session.jsonl` and DSH's checksummed `session.jsonl.zstd` are supported;
+- duplicate detection is preserved across separate Zstandard frames, and packed chunk rows are understood when validating the contiguous durable `seq` stream;
+- unaffected Zstandard frames remain byte-for-byte identical;
+- mutation refuses torn/incomplete logs so DSH can perform its own crash recovery first; read-only `doctor --sessions` treats only an incomplete live tail as advisory while committed structural corruption remains a failure;
+- source file identity is rechecked immediately before replacement so a live writer aborts the operation;
+- every changed log receives a byte-for-byte backup next to the original before replacement;
+- the repaired file is re-read and verified before success is reported.
+
+After repair, restart DSH and reopen the affected conversation. Running `repair-sessions` again is idempotent.

package/entry.js

@@ -12,9 +12,13 @@ import { installVisionRouterFileLogging } from './lib/file-logger.js'
 import { contextWithDelegatedReplay } from './lib/replay-delegation.js'
 import { contextWithReplayEnvelopeV2Compat } from './lib/replay-envelope-v2-compat.js'
 import { contextWithVisionExecutionPolicy } from './lib/vision-execution-policy.js'
+import { contextWithNativeImageCoexistence } from './lib/native-image-coexistence.js'
+import { installPiAiBridgeWireCompat } from './lib/pi-ai-bridge-wire-compat.js'
 import { installLiveModelDiscovery } from './lib/live-model-discovery.js'
 import { installVisionModelRegistry } from './lib/vision-model-registry.js'
 import { installLiveModelClientPrelude } from './lib/live-model-client-prelude.js'
+import { installExactVisionTestClient } from './lib/vision-backend-smoke-test-client.js'
+import { installVisionBackendSmokeTest } from './lib/vision-backend-smoke-test.js'
 import { installClientPresentationBoundary } from './lib/client-presentation-boundary.js'
 import { installAdversarialHardening } from './lib/adversarial-hardening.js'
 import { installOllamaColdStartGuard } from './lib/ollama-cold-start.js'
@@ -201,11 +205,17 @@ export function apply(ctx, config = {}) {
   // The secure screenshot renderer owns its exact FsTarget and active browser
   // cancellation directly, so it does not depend on this placement.
   const toolRuntimeCtx = installVisionToolRuntimeBoundary(attachmentCompatCtx)
+  // DSH 0.1.1 publishes an exact native image-capable DeepSeek model. Do not
+  // put it ahead of Vision Router's own configured chain: only when the user
+  // has explicitly selected any Host-native image route, preserve raw pixels
+  // and skip the hidden instant-local caption pass for that turn. The override
+  // is AsyncLocalStorage-scoped and never mutates settings or provider order.
+  const nativeImageCompat = contextWithNativeImageCoexistence(toolRuntimeCtx, runtimeConfig)
   // Final structured-flow guard sits closest to core.apply so it sees the
   // actual tool registrations and pre-step listener. It makes bootstrap
   // one-shot, enforces fast/standard/deep/custom quotas, tracks mixed branches,
   // rejects empty/non-evidence results, and applies one shared visual deadline.
-  const structuredCtx = installStructuredFlowHardening(toolRuntimeCtx, runtimeConfig)
+  const structuredCtx = installStructuredFlowHardening(nativeImageCompat.ctx, nativeImageCompat.config)
   // Newer DSH releases publish llm/adapters-updated synchronously from inside
   // registerAdapter(). Coalesce only Vision Router's listener: nested events
   // mark the topology dirty and the outer pass reruns to a fixed point, so we
@@ -240,6 +250,15 @@ export function apply(ctx, config = {}) {
   // ordinary chat model picker). The existing classic client bundle stays the
   // DSH module-system artifact, including HMR/source-map behavior.
   installLiveModelClientPrelude(reconciledCtx)
+  // #266: 1.7.x gets one exact, no-fallback image smoke test per visible row.
+  // Keep it out of the controlled React form so the v2 capability-benchmark
+  // client can take ownership later without forking the stable settings UI.
+  installExactVisionTestClient(reconciledCtx)
+  // DSH 0.1.1 adds per-route/model pi-ai wire compatibility. The legacy
+  // direct image bridge is non-streaming and predates that surface, so preserve
+  // maxTokensField + route headers at its final fetch boundary. Ordinary DSH
+  // streams and unrelated Vision Router HTTP providers remain byte-identical.
+  installPiAiBridgeWireCompat(reconciledCtx, logging.logger)
   // Direct compatibility bridging is allowed only after DSH/pi-ai's exact
   // pre-wire image-capability admission rejection, or a local UNKNOWN_MODEL
   // backed by exact private-registry evidence. Record the same provenance in
@@ -251,6 +270,14 @@ export function apply(ctx, config = {}) {
     evidenceSource: (provider, model) => liveDiscovery.evidenceSource?.(provider, model),
     logger: logging.logger,
   })
+  // The smoke-test route sends only a built-in probe image to the exact selected
+  // backend. It never walks the configured fallback chain, so a healthy OVH
+  // fallback can no longer make a broken custom model look healthy. Its narrow
+  // compatibility bridge uses the same live-discovery evidence gate as runtime.
+  installVisionBackendSmokeTest(executionCtx, runtimeConfig, core, {
+    logger: logging.logger,
+    isBridgeEvidence: (provider, model) => liveDiscovery.hasModel(provider, model),
+  })
   // index.js historically passes image bytes as `options.input` to the async
   // execFile API. That option is not fed into child stdin, so Tesseract waits
   // for data until the OCR slice expires. Materialize only this exact
@@ -277,7 +304,7 @@ export function apply(ctx, config = {}) {
     /* diagnostics must never break apply */
   }
   try {
-    const result = core.apply(executionCtx, runtimeConfig)
+    const result = core.apply(executionCtx, nativeImageCompat.config)
     // On newer Hosts the Settings -> Models surface is backed by the
     // configurable-provider directory, not by the live adapter registry alone.
     // Publish the main DeepSeek + 自动识图 route as a derived alias of official

package/lib/client-presentation-boundary.js

@@ -26,6 +26,77 @@ export const CLIENT_PRESENTATION_PRELUDE = String.raw`(function(){
   var TARGET = 'dsh-vision-router';
   var LEGACY_ATTACHMENT_VALUE = '@deepseek-ai/dsh-client-ui-attachment';
 
+  // #271 pre-release regression fence: #210 made the walkthrough runtime lazy,
+  // but its document.body MutationObserver still invalidates the 250ms target
+  // cache for every class mutation. DSH toggles transient scroll/shadow classes
+  // while the settings modal moves, turning an otherwise cheap rAF scroll frame
+  // back into several querySelectorAll passes + forced layout. Keep the observer
+  // fully authoritative for child-list and aria mutations, but suppress class-
+  // only batches for the one exact Vision Router guide observer. Normal scroll
+  // frames will still refresh the cached geometry at the existing 250ms bound.
+  function installGuideMutationFence() {
+    var NativeObserver = window.MutationObserver;
+    var doc = window.document;
+    if (
+      typeof NativeObserver !== 'function' ||
+      NativeObserver.__visionRouterGuideMutationFence ||
+      !doc || !doc.body ||
+      typeof Proxy !== 'function'
+    ) return;
+
+    function isGuideObservation(callback, target, options) {
+      if (!callback || callback.name !== 'resolveSync') return false;
+      if (
+        target !== doc.body || !options ||
+        options.childList !== true || options.subtree !== true || options.attributes !== true
+      ) return false;
+      var filter = Array.isArray(options.attributeFilter) ? options.attributeFilter.slice().sort() : [];
+      return filter.length === 3 &&
+        filter[0] === 'aria-expanded' && filter[1] === 'aria-hidden' && filter[2] === 'class';
+    }
+
+    function withoutTransientClassMutations(records) {
+      if (!records || typeof records.filter !== 'function') return records;
+      return records.filter(function(record){
+        return !(record && record.type === 'attributes' && record.attributeName === 'class');
+      });
+    }
+
+    var WrappedObserver = new Proxy(NativeObserver, {
+      construct: function(Target, args) {
+        var callback = args && args[0];
+        var guideObservation = false;
+        var wrappedObserver;
+        var nativeObserver = new Target(function(records) {
+          var next = guideObservation ? withoutTransientClassMutations(records) : records;
+          if (!next || next.length === 0) return;
+          return callback(next, wrappedObserver || nativeObserver);
+        });
+        wrappedObserver = new Proxy(nativeObserver, {
+          get: function(target, property) {
+            if (property === 'observe') {
+              return function(node, options) {
+                guideObservation = isGuideObservation(callback, node, options);
+                return target.observe(node, options);
+              };
+            }
+            if (property === 'takeRecords') {
+              return function() {
+                var records = target.takeRecords();
+                return guideObservation ? withoutTransientClassMutations(records) : records;
+              };
+            }
+            var value = Reflect.get(target, property, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+          }
+        });
+        return wrappedObserver;
+      }
+    });
+    Object.defineProperty(WrappedObserver, '__visionRouterGuideMutationFence', { value: true });
+    window.MutationObserver = WrappedObserver;
+  }
+
   function createPresentation(React) {
     function PresentedImage(props) {
       var attachment = props.attachment;
@@ -221,6 +292,7 @@ export const CLIENT_PRESENTATION_PRELUDE = String.raw`(function(){
   }
 
   function install() {
+    installGuideMutationFence();
     if (window.__ModuleLoader__) {
       patchLoader(window.__ModuleLoader__);
       return;