dsh-vision-router 2.1.3 → 2.1.4

package/README.md

@@ -413,7 +413,7 @@ ollama pull qwen2.5vl
 ## Requirements
 
 - DeepSeek Harness Web profile. Normal installs can use `npx @deepseek-ai/dsh ...`; source checkouts use `pnpm dsh ...`. A bare `dsh ...` command only works when the CLI is already on your shell `PATH`.
-- **DSH Host support window:** DVR 2.1.x supports DSH `0.1.0-rc.8` (minimum), `0.1.1-rc.1` (previous released train), and current `0.1.1-rc.2`; DSH `0.1.2-alpha.4` is canary-only evidence. DVR 2.0.x was the final train with public support for rc.6/rc.7. See [DSH Host support window](docs/architecture/dsh-support-window.md).
+- **DSH Host support policy:** DVR 2.1.x keeps DSH `0.1.0-rc.8` as the public minimum and currently supports the released stable channel through `0.1.2-rc.1`. Exact `0.1.3-alpha.2` coverage is **verification evidence only**, not a preview support promise; scheduled `latest`/`alpha` canaries monitor drift without changing the support policy. DVR 2.0.x was the final train with public support for rc.6/rc.7. See [DSH Host support window](docs/architecture/dsh-support-window.md).
 - Node ≥ 22 (host side).
 - No API key for the default free chain; a credential reference (`apiKeyEnv`) only for paid `httpProviders`.
 - Chrome / Chromium / Edge is needed only for `vision_html_screenshot`; every other tool works without a browser.

package/README.zh.md

@@ -411,7 +411,7 @@ ollama pull qwen2.5vl
 ## 环境要求
 
 - DeepSeek Harness 的 Web profile。普通安装可用 `npx @deepseek-ai/dsh ...`；从源码仓库运行时用 `pnpm dsh ...`。只有 CLI 已经进入系统 `PATH` 时才能直接写 `dsh ...`。
-- **DSH Host 支持窗口：** DVR 2.1.x 支持 DSH `0.1.0-rc.8`（最低）、`0.1.1-rc.1`（上一正式支持线）以及当前 `0.1.1-rc.2`；DSH `0.1.2-alpha.4` 仅作为 canary 兼容证据。DVR 2.0.x 是最后公开支持 rc.6/rc.7 的版本线。详见 [DSH Host 支持窗口](docs/architecture/dsh-support-window.md)。
+- **DSH Host 支持策略：** DVR 2.1.x 的公开最低 Host 仍为 DSH `0.1.0-rc.8`，当前正式发布通道已验证并支持到 `0.1.2-rc.1`。对 `0.1.3-alpha.2` 的精确覆盖**只属于验证证据**，不代表对 preview 的公开支持承诺；定时 `latest`/`alpha` canary 只负责发现上游漂移，也不会自动改变支持策略。DVR 2.0.x 是最后公开支持 rc.6/rc.7 的版本线。详见 [DSH Host 支持窗口](docs/architecture/dsh-support-window.md)。
 - Node ≥ 22（宿主侧）。
 - 默认免费链路无需 API Key；付费 `httpProviders` 只需一个凭据引用（`apiKeyEnv`）。
 - 只有 `vision_html_screenshot` 需要 Chrome / Chromium / Edge；其余工具无浏览器也能用。

package/docs/architecture/compat-inventory.md

@@ -40,12 +40,12 @@ P0 records why each major compatibility seam exists and the condition that permi
 
 ## `lib/pi-ai-bridge-wire-compat.js`
 
-- **Reason:** make the legacy direct image bridge transport-equivalent to pi-ai declared wire compatibility without reading credentials or changing provider priority.
-- **Host gap:** the direct bridge predates route/model wire metadata such as max-token fields and route-owned headers.
-- **First needed for:** DSH 0.1.1 pi-ai declared provider/wire compatibility.
-- **Feature detection:** exact non-streaming OpenAI-compatible image bridge fingerprint plus resolved route/model facts; normal streaming Host traffic does not match.
-- **Removal condition:** the direct bridge is removed or every supported Host executes this image path through the native pi-ai wire seam.
-- **Tests:** `pi-ai-bridge-wire-compat`, native process-restart/cold-resume contract.
+- **Reason:** keep the legacy direct image bridge transport-equivalent to pi-ai declared wire compatibility and, while upstream lacks the OpenCode-specific carrier, project Vision Router-owned session affinity onto the final Go wire without taking ownership of ordinary Host traffic. `lib/session-affinity-runtime.js` is the scoped AsyncLocalStorage companion; it carries affinity only while a Router-owned lazy stream is executing.
+- **Host gap:** the direct bridge predates route/model wire metadata such as max-token fields and route-owned headers; current DSH/pi-ai accepts `GenerateOptions.sessionId` but emits generic affinity carriers rather than OpenCode Go's required `x-opencode-session`.
+- **First needed for:** DSH 0.1.1 pi-ai declared provider/wire compatibility; OpenCode Go's September 2026 required session header.
+- **Feature detection:** legacy wire recovery still requires the exact non-streaming OpenAI-compatible image bridge fingerprint plus resolved route/model facts. OpenCode affinity requires an active Vision Router AsyncLocalStorage scope, the exact official HTTPS `opencode.ai/zen/go...` endpoint, and absence of an upstream-native `x-opencode-session`; unrelated Host/plugin traffic is inert.
+- **Removal condition:** remove legacy bridge recovery when every supported Host executes that image path through native pi-ai wire facts; remove the scoped OpenCode projection independently once every supported DSH/pi-ai path emits `x-opencode-session` from `GenerateOptions.sessionId`. The native header must win before deletion so the compatibility rule self-retires.
+- **Tests:** `pi-ai-bridge-wire-compat`, real `opencode-session-wire-contract`, native process-restart/cold-resume contract.
 
 ## `lib/settings-client-rc8-lifecycle.js`
 

package/docs/architecture/dsh-compatibility-matrix.md

@@ -8,10 +8,11 @@ The matrix is capability-based. Runtime code must feature-detect the seam it nee
 
 | CI fixture | DSH package line | Role |
 | --- | --- | --- |
-| `minimum-contract` | `0.1.0-rc.6` | Minimum supported Host contract. Must remain green. |
-| `legacy-contract` | `0.1.0-rc.8` | Legacy contract carrying batch attachments and dimension policy. |
-| `current-contract` | `0.1.1-rc.2` | Current contract baseline for 2.x convergence. Must be green before P1. |
-| `latest-dsh` | resolved dynamically from npm | Scheduled canary only. Never a normal PR required check. |
+| `minimum-contract` | `0.1.0-rc.6` | Historical compatibility-retention fixture. The name is legacy; DVR 2.1.x public support starts at rc.8. |
+| `legacy-contract` | `0.1.0-rc.8` | Public support-floor fixture carrying batch attachments and dimension policy. |
+| `current-contract` | `0.1.2-rc.1` | Current stable Host contract baseline. Must remain green. |
+| exact preview gates | `0.1.3-alpha.2` | Required verification evidence only; not a public preview-support claim. |
+| `latest-dsh` / alpha canaries | resolved dynamically from npm dist-tags | Scheduled drift surveillance only. Never changes support policy by itself. |
 
 Node 22 and Node 24 remain the general required runtime matrix. The Host contract jobs are additive; they do not replace the normal test matrix.
 
@@ -19,7 +20,7 @@ Node 22 and Node 24 remain the general required runtime matrix. The Host contrac
 
 `yes` means the fixture has a direct positive test or feature probe. `no` means a direct negative probe exists. `compat` means the fixture proves Vision Router can safely carry the newer input/config through that Host, but does **not** claim the Host owns that capability. `probe` means the capability is intentionally not inferred from the version label and is verified at runtime/contract-test time.
 
-| Capability | minimum-contract rc.6 | legacy-contract rc.8 | current-contract rc.2 | Evidence / detection |
+| Capability | minimum-contract rc.6 | legacy-contract rc.8 | current-contract rc.1 (0.1.2) | Evidence / detection |
 | --- | --- | --- | --- | --- |
 | Batch attachment save | no | yes | yes | `hasBatchAttachmentContract()` checks the released `attachments.saveImages` prototype; `tests/rc6-rc7-compat.test.js`; contract CI. |
 | Max image dimension policy | compat | yes | yes | All fixtures parse the complete attachment-local row; rc.8/current positively retain the field and the established admission tests exercise the 10000/10001 boundary. Older Schemastery passthrough is not treated as ownership evidence. |
@@ -53,5 +54,5 @@ Every compatibility seam must answer the same six questions: **Reason**, **Host
 
 1. A new version-specific branch requires evidence that no stable capability probe exists.
 2. A compatibility layer may narrow behavior to preserve an existing product contract; it may not expand routing authority.
-3. `latest-dsh` can reveal upstream drift, but a canary failure must not silently redefine the supported contract.
+3. Exact preview and dynamic canary evidence can reveal upstream drift, but neither may silently redefine the public support policy.
 4. P1 may begin only when all three gating fixtures and the existing cold-resume/resource baselines are green.

package/docs/architecture/dsh-support-window.md

@@ -1,21 +1,41 @@
 # DSH Host support window
 
-Status: normative for the DVR 2.x compatibility program.
+Status: normative for the current DVR 2.x compatibility program.
 
-## Current DVR 2.1.x window
+## Public support policy
+
+The public support policy contains only released Host semantics. Preview/canary versions are intentionally excluded from this table.
 
 | Role | DSH train | Meaning |
 |---|---|---|
 | Minimum Supported Host | `0.1.0-rc.8` | Oldest Host generation that DVR 2.1.x publicly supports. |
-| Previous Supported Train | `0.1.1-rc.1` | Previous released Host train kept in the compatibility matrix. |
-| Current Supported Train | `0.1.1-rc.2` | Current released train used by the required current-contract gate. |
-| Canary only | `0.1.2-alpha.4` | Latest upstream prerelease evidence at v2.1.0 release preparation time. It is not a released support-floor claim and does not authorize compat deletion by itself. |
+| Current Stable Host | `0.1.2-rc.1` | Current npm stable-channel release covered by required exact Host and browser evidence. |
+
+DVR `2.1.x` therefore keeps `0.1.0-rc.8` as its public floor and supports released Host trains through the current stable channel. Runtime branching remains capability-based rather than version-string-driven.
+
+No later support-floor increase is currently announced.
+
+## Verification evidence — not support policy
+
+Compatibility evidence answers a different question: what exact upstream releases and moving channels have current CI proof? It must never be interpreted as a public support-floor change.
+
+| Evidence role | DSH source | Meaning |
+|---|---|---|
+| Exact stable evidence | `0.1.2-rc.1` | Required Host/wire and real Host + Chromium coverage for the current stable release. |
+| Exact preview evidence | `0.1.3-alpha.2` | Required preview Host/wire/lifecycle/browser evidence. This is not a preview support promise. |
+| Stable drift canary | npm dist-tag `latest` | Scheduled, dynamically resolved surveillance. A failure starts compatibility investigation; it does not rewrite support policy. |
+| Preview drift canary | npm dist-tag `alpha` | Scheduled, dynamically resolved surveillance with preview-specific lifecycle coverage. A failure does not rewrite support policy. |
+
+The exact evidence values may move in a patch-level maintenance PR when CI proof advances. The public minimum may move only under the support-floor protocol below.
+
+Historical release notes under `docs/releases/` are release-time snapshots and are not rewritten when later evidence advances.
+
 
-DVR `2.1.x` therefore supports DSH `0.1.0-rc.8` and newer released trains covered by the published matrix. Runtime branching remains capability-based rather than version-string-driven.
+The optional peer-dependency range may admit an exact preview version so CI/users can install a verified preview Host without peer-resolution noise. That install admission is compatibility evidence, not a public preview support promise.
 
 ## Floor transition from DVR 2.0.x
 
-DVR 2.0.x was released with DSH `0.1.0-rc.6` as its minimum Host. The 2.1.0 boundary was announced in advance and raises the public minimum to DSH `0.1.0-rc.8`.
+DVR 2.0.x was released with DSH `0.1.0-rc.6` as its minimum Host. The 2.1.0 boundary was announced in advance and raised the public minimum to DSH `0.1.0-rc.8`.
 
 ```text
 DVR 2.0.x minimum: DSH 0.1.0-rc.6
@@ -26,24 +46,24 @@ Users still on rc.6/rc.7 should upgrade DSH before upgrading to DVR 2.1.x.
 
 This support-floor transition does **not** require deleting every rc.6-era compatibility seam in the same release. Compatibility code is retired only after a separate proof shows it is unreachable or unnecessary on every supported Host and durable-history path.
 
-No later support-floor increase is currently announced.
-
-## Support-window change protocol
+## Support-policy change protocol
 
-A Host support-floor change is valid only when all of the following are true:
+A public Host support-floor change is valid only when all of the following are true:
 
-1. the change is announced in a DVR minor or major release, never only in a patch release;
+1. the floor change is announced in a DVR minor or major release, never only in a patch release;
 2. README / support documentation and release notes state the old and new floors;
-3. Doctor reports the effective support window and gives a capability-based upgrade result for Hosts below the active floor;
-4. required CI has stable minimum, previous, current, and canary evidence for the declared window;
+3. Doctor reports the effective public support policy and gives a capability-based upgrade result for Hosts below the active floor;
+4. required CI proves the public floor and current stable Host, while preview and dynamic canaries remain separately labelled verification evidence;
 5. compatibility seams are removed only after the new minimum Host proves the replacement capability;
 6. removal PRs keep restart, settings, native-image coexistence, tool execution, Node 22/24 and supported-platform regressions green.
 
+Advancing an exact stable/preview evidence version or a moving canary target does **not** by itself change the public support floor.
+
 ## Capability-first rule
 
-Version labels describe the public support window; runtime branching still uses capabilities.
+Version labels describe support policy and CI evidence; runtime branching still uses capabilities.
 
-DVR must not turn this table into widespread version-string conditionals. Runtime compatibility continues to feature-detect the concrete Host seam it needs. If a capability cannot be proven safely, the compatibility path fails open or reports an explicit unsupported/unknown state according to that seam's contract.
+DVR must not turn these tables into widespread version-string conditionals. Runtime compatibility continues to feature-detect the concrete Host seam it needs. If a capability cannot be proven safely, the compatibility path fails open or reports an explicit unsupported/unknown state according to that seam's contract.
 
 ## Compatibility-retirement rule
 

package/docs/architecture/p3-compat-retirement.md

@@ -2,15 +2,17 @@
 
 Decision date: 2026-08-28
 
-Current DVR train: `2.0.x`
+Status: historical P3-B audit snapshot. It records the 2.0.x support policy in force at the decision date; it is **not** the current Host support policy. See [`dsh-support-window.md`](dsh-support-window.md) for the normative current policy and verification evidence.
 
-Current minimum supported Host: DSH `0.1.0-rc.6`
+DVR train at decision time: `2.0.x`
+
+Minimum supported Host at decision time: DSH `0.1.0-rc.6`
 
 ## Result
 
 **NO COMPAT DELETION IS CURRENTLY AUTHORIZED.**
 
-P3-B is intentionally a retirement audit, not a quota to delete files. Under the current 2.0.x support window, every Host-generation compatibility seam that materially exists for rc.6/rc.8 users still has a reachable support case.
+P3-B is intentionally a retirement audit, not a quota to delete files. Under the 2.0.x support window in force at the decision date, every Host-generation compatibility seam that materially exists for rc.6/rc.8 users still has a reachable support case.
 
 ## Seam review
 
@@ -18,7 +20,7 @@ P3-B is intentionally a retirement audit, not a quota to delete files. Under the
 |---|---|---|
 | attachment contract / Android attachment fallback | rc.6 remains the minimum and does not provide the later batch-attachment contract used by the modern path | after the released minimum Host no longer needs the single-attachment/permission fallback and the replacement is proven on the new minimum |
 | Host settings compatibility | rc.6 remains supported; live settings/client behavior differs across the support window | after the new minimum exposes the stable settings seam used by DVR without compatibility wrapping |
-| rc.8 browser/client lifecycle compatibility | rc.8 is still inside the declared support window and remains the Previous Supported Train | only after rc.8 itself leaves the support window or the same path becomes unreachable by capability proof |
+| rc.8 browser/client lifecycle compatibility | rc.8 is still inside the declared support window and was the Previous Supported Train at the decision date | only after rc.8 itself leaves the support window or the same path becomes unreachable by capability proof |
 | replay envelope v2 compatibility | old durable histories remain valid inputs even when the live Host is newer | only when the supported history/runtime window no longer needs producer rebinding or Host provides an equivalent native replay identity seam |
 | adapter prepareCall/coalescing compatibility | the support matrix still spans Host generations with different adapter-registration/update behavior | only when the minimum Host and every DVR-owned adapter satisfy one stable registration/update contract |
 | pi-ai bridge wire compatibility | legacy direct-bridge traffic remains a supported route shape | only after the direct bridge is retired or all supported Hosts execute that path through an equivalent native wire seam |
@@ -41,6 +43,6 @@ Each deletion still requires proof on:
 
 ## P3-B verdict
 
-`PASS — no expired seam under the current 2.0.x support window.`
+`PASS — no expired seam under the 2.0.x support window in force at the decision date.`
 
 Deleting a still-supported rc.6 seam merely to make the compatibility inventory smaller would violate the P3 plan and the published 2.0.x compatibility contract.

package/docs/architecture/p3-host-native-seams.md

@@ -2,7 +2,9 @@
 
 Decision date: 2026-08-28
 
-Support window: DVR `2.0.x` / minimum DSH `0.1.0-rc.6` / previous `0.1.0-rc.8` / current `0.1.1-rc.2`.
+Status: historical P3-D audit snapshot. It records the support policy in force when this decision was made; it is **not** the current Host support policy. See [`dsh-support-window.md`](dsh-support-window.md) for the normative current policy and verification evidence.
+
+Support window at decision time: DVR `2.0.x` / minimum DSH `0.1.0-rc.6` / previous `0.1.0-rc.8` / current `0.1.1-rc.2`.
 
 P3-D permits a migration only when all four conditions are true:
 

package/docs/doctor.md

@@ -79,7 +79,7 @@ or `DSH_WEB_URL`. To perform offline checks only:
 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.
+An unreachable DSH process is advisory rather than a doctor failure; offline checks still complete. DSH Web may also require its signed browser-session cookie before any `/api` route is visible. If every side-effect-free route probe is rejected with `401`, Doctor reports the runtime as **reachable but authentication-required** and keeps plugin route health/ownership unknown instead of printing false route failures or bypassing Host authentication. The JSON report exposes `runtime.authenticationRequired: true`; capability support advice remains unknown because no Host seam was actually observed. When `--profile` is used against an authenticated reachable runtime, Doctor still 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
 
@@ -91,6 +91,9 @@ Doctor reports the local platform, Node version, and whether it can find:
 
 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.
 
+
+Doctor also keeps **public Host support policy** separate from **compatibility verification evidence**. Human output lists the DVR support floor/current stable Host in the support section, then lists exact stable/preview CI evidence and moving npm canary channels in a separate verification section. In `--json`, these are separate `hostSupportWindow` and `hostVerificationEvidence` objects; preview/canary values never appear inside `hostSupportWindow`.
+
 ### Scan historical sessions
 
 Session scanning is opt-in because a large session store can take longer to read/decompress:

package/docs/releases/v2.1.4.md

@@ -0,0 +1,34 @@
+# v2.1.4
+
+DVR 2.1.4 is a compatibility and reliability patch for the current DSH stable/preview trains. It hardens Windows capture, OpenCode Go session affinity, attachment/timeout lifecycle boundaries, live-model credentials, background capability measurement, and Doctor diagnostics without changing the public 2.1.x routing model.
+
+## Runtime reliability
+
+- Replaces the legacy Windows DPI screenshot shim with a dedicated PMv2 → PMv1 DPI-aware desktop capture path. Compilation uses an isolated ASCII temp directory so non-ASCII Windows user profiles no longer break `Add-Type`, while incorrect DPI contexts still fail closed instead of returning a cropped desktop.
+- Propagates the real DSH session identity through vision child calls and isolates OpenCode Go wire affinity from internal Session identity. Direct Go requests without a stable session fail closed, existing upstream `x-opencode-session` headers remain authoritative, and benchmark traffic uses isolated synthetic affinity rather than contaminating user sessions.
+- Bounds the user-facing lifetime of vision tools across Host attachment saves by combining the ambient turn signal, Host execution signal, and live `visionTaskTimeoutMs` deadline. Late plugin work observes the spent signal even though the Host attachment store itself has no physical cancellation primitive.
+- Keeps `visionTaskTimeoutMs` hot: Settings changes are read on the next invocation without restarting DSH or re-registering tools.
+
+## DSH stable / preview compatibility
+
+- Adds exact compatibility evidence for DSH `0.1.2-rc.1` and `0.1.3-alpha.2`, including real Host contracts, pi-ai wire behavior, Session-v2 restart coverage, cold Vision-toggle browser smoke, and alpha mixed generic-file paste lifecycle.
+- Splits scheduled release canaries into npm `latest` (stable) and npm `alpha` (preview). These moving canaries automatically test newly published DSH trains while fixed exact-version gates preserve reproducible compatibility evidence.
+- Hardens bitmap normalization and alpha mixed paste so MIME/extension mismatches, text+image+generic-file combinations, and duplicate lifecycle delivery cannot silently corrupt attachment intake.
+
+## Security, discovery, and diagnostics
+
+- Separates public Host support policy from compatibility verification evidence. DVR 2.1.x keeps `0.1.0-rc.8` as its public minimum and `0.1.2-rc.1` as the current stable Host, while exact preview evidence and moving npm canaries are reported separately and never become an implicit support promise.
+- Removes secret-derived data from live-model route fingerprints and from persisted background AUTH stops. Credential rotation is handled by the current `credentials/reference-updated` event with legacy-event compatibility, immediately invalidating stale evidence and revalidating with the new credential.
+- Makes unattended background failures quieter and more accurate: authentication, protocol, and rate-limit failures share bounded transport-scope cooldowns instead of rotating through sibling models/axes every short gap, while ordinary network/timeout failures remain narrowly axis-scoped.
+- Treats token-authenticated DSH Web correctly in Doctor. A blanket `401` now means “runtime reachable, browser authentication required, route health unknown” instead of a false route failure; Doctor does not bypass the Host’s signed-cookie boundary.
+- Closes the remaining CodeQL findings without dismissing them; current Code Scanning is clean.
+
+## Validation
+
+- Covered by Node 22/24, DSH rc.6/rc.7/rc.8 contracts, exact stable `0.1.2-rc.1`, exact preview `0.1.3-alpha.2`, Windows Node 24 screenshot runtime, provider transport, routing parity, Session surfaces, real browser lifecycle gates, and CodeQL.
+- Local release-candidate verification completed with the full test suite at zero failures, contract tests at zero failures, and backend runtime policy coverage green.
+- No Settings migration is required. Restart DSH Web/Desktop after upgrading so the new runtime and browser-side compatibility logic are loaded.
+
+## Upgrade
+
+Upgrade to 2.1.4 and restart DSH Web/Desktop. Existing Vision Router settings remain compatible.

package/docs/v2-capability-routing.md

@@ -156,17 +156,26 @@ intentional: standing background authority is the user's permission to verify
 capability within the selected local/free/paid cost boundary, not permission to
 trust possibly stale Host modality metadata as ground truth.
 
-Transient failure state is scoped to the exact deployment fingerprint plus model
-and axis. Network, timeout, and rate-limit conditions receive retry backoff.
-Clear deployment-level non-retryable failures such as authentication failure,
-unavailable model, and unsupported protocol are persisted for the same exact
-fingerprint and stop unattended measurement across axes, including after process
-restart. Visual-proof and Benchmark-infrastructure failures remain axis-scoped;
-they do not manufacture a text-only verdict or disable other axes. An explicit
-image-input rejection is persisted separately as a measured text-only verdict.
-Ordinary settings refreshes, adapter notifications, and process restart do not
-silently clear these same-fingerprint stops. A changed deployment fingerprint
-creates a new evidence scope, and an explicit successful Test Vision clears the
+Failure lifetime follows the narrowest authority that can explain the failure.
+Timeout, network, visual-proof, and Benchmark-infrastructure failures remain
+model/axis-scoped, so one failed axis does not suppress another axis or an
+independent route. Authentication and unsupported-protocol failures apply to the
+same transport scope (provider + endpoint + protocol + credential reference), and
+rate-limit backoff is shared by sibling models on that same scope, preventing an
+invalid or throttled account/endpoint from rotating through every model and axis
+at the normal 15-second background gap.
+
+Authentication stops are process-local and bounded; Vision Router never persists
+an API-key value or deterministic derivative just to recognize a later key
+rotation. Current `credentials/reference-updated` and legacy
+`credentials/updated` notifications synchronously revoke the in-memory AUTH stop
+and rescan with the new credential. Unsupported-protocol and unavailable-model
+stops remain bounded persistent evidence (the former also suppresses sibling
+models on the same transport; the latter stays model-specific). Visual-proof and
+Benchmark-infrastructure failures do not manufacture a text-only verdict or
+disable other axes. An explicit image-input rejection is persisted separately as
+a measured text-only verdict. A changed deployment fingerprint creates a new
+evidence scope, and an explicit successful Test Vision clears the corresponding
 same-fingerprint stop. Public background status exposes only a sanitized failure
 class/code; raw provider responses and credentials are not published to the
 browser.

package/index.js

@@ -44,6 +44,14 @@ import { createRequire } from 'node:module'
 import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
 import { appendPromptToImageOnlyMessage, fetchWithOpenAICompatibility } from './lib/http-compat.js'
+import {
+  directSessionAffinityHeaders,
+  isOfficialOpenCodeGoUrl,
+  openCodeSessionAffinityHeaderForUrl,
+  rawSessionIdentity,
+  sessionIdentityOf,
+} from './lib/session-affinity.js'
+import { runWithVisionSessionAffinity, streamWithVisionSessionAffinity } from './lib/session-affinity-runtime.js'
 import {
   routingCorrectionFor,
   toAnthropicMessages,
@@ -98,6 +106,7 @@ import {
 import { writeArtifactFile } from './lib/artifact-boundary.js'
 import { stripTrailingSlashes } from './lib/string-normalization.js'
 import { parseVersionComparator } from './lib/version-range.js'
+import { captureWindowsDesktop } from './lib/windows-desktop-capture.js'
 
 // sharp is a native module with platform-specific prebuilt binaries. It used
 // to be imported statically, so a missing, broken, or conflicting install
@@ -2213,6 +2222,9 @@ export async function callLocalBackend(provider, messages, options = {}) {
         signal: options.signal,
         allowKeyless: true,
         system: system.join('\n').trim(),
+        ...(rawSessionIdentity(options.sessionId) === undefined
+          ? {}
+          : { sessionId: rawSessionIdentity(options.sessionId) }),
         ...(typeof options.resolveCredential === 'function'
           ? { resolveCredential: options.resolveCredential }
           : {}),
@@ -2223,6 +2235,9 @@ export async function callLocalBackend(provider, messages, options = {}) {
   return callOpenAICompatible(provider, messages, {
     maxTokens,
     signal: options.signal,
+    ...(rawSessionIdentity(options.sessionId) === undefined
+      ? {}
+      : { sessionId: rawSessionIdentity(options.sessionId) }),
     ...(typeof options.resolveCredential === 'function'
       ? { resolveCredential: options.resolveCredential }
       : {}),
@@ -2349,7 +2364,10 @@ export function toAnthropicContent(content) {
 }
 
 export async function callOpenAICompatible(provider, messages, options = {}) {
-  const headers = { 'content-type': 'application/json' }
+  const headers = {
+    'content-type': 'application/json',
+    ...directSessionAffinityHeaders(provider, options.affinityId ?? options.sessionId),
+  }
   const apiKeyEnv = typeof provider.apiKeyEnv === 'string' ? provider.apiKeyEnv : ''
   let resolvedApiKey = ''
   if (apiKeyEnv !== '') {
@@ -2493,11 +2511,13 @@ export function createChunkAssembler() {
 }
 
 async function visionAnswer(llm, options) {
-  const assembler = createChunkAssembler()
-  for await (const chunk of llm.stream(options)) {
-    assembler.push(chunk)
-  }
-  return assembler.finish()
+  return runWithVisionSessionAffinity(options?.sessionId, async () => {
+    const assembler = createChunkAssembler()
+    for await (const chunk of llm.stream(options)) {
+      assembler.push(chunk)
+    }
+    return assembler.finish()
+  })
 }
 
 /** Environment shim for `resolveAdapterOptions`: `{ get: (name) => ({ value }) }`. */
@@ -3280,13 +3300,7 @@ export function apply(ctx, config = {}, runtime = {}) {
       return 0
     }
   }
-  const sessionIdOf = (session) => {
-    try {
-      return session && session.id !== undefined ? String(session.id) : 'anon'
-    } catch {
-      return 'anon'
-    }
-  }
+  const sessionIdOf = (session) => sessionIdentityOf(session) ?? 'anon'
   const visionScopeOf = (session) => `${sessionIdOf(session)}:${turnNumberOf(session)}`
 
   /** Stable, never-logged fingerprint of the credential a backend will use. */
@@ -3653,11 +3667,13 @@ export function apply(ctx, config = {}, runtime = {}) {
             ? callLocalBackend(entry.provider, openAIMessages, {
                 maxTokens: entry.provider.maxTokens ?? 4096,
                 signal: options.signal,
+                sessionId: options.sessionId,
                 resolveCredential,
               })
             : callOpenAICompatible(entry.provider, openAIMessages, {
                 maxTokens: entry.provider.maxTokens ?? 4096,
                 signal: options.signal,
+                sessionId: options.sessionId,
                 resolveCredential,
               }))
         } catch (error) {
@@ -4132,6 +4148,16 @@ export function apply(ctx, config = {}, runtime = {}) {
     }
     return { ok: true, rawProfile, resolvedProfile, transport }
   }
+  const assertOpenCodeGoAffinityForPair = (pair, sessionId) => {
+    const plan = channelBridgePlan(pair.provider, pair.model)
+    const baseURL = plan?.transport?.baseURL
+    if (!isOfficialOpenCodeGoUrl(baseURL)) return
+    // Validation only: Host receives the unmodified DSH sessionId, while the
+    // scoped final-wire compatibility layer owns x-opencode-session. Fail here
+    // before pi-ai can turn a non-ByteString id into an opaque SDK error.
+    openCodeSessionAffinityHeaderForUrl(baseURL, sessionId)
+  }
+
   const resolveChannelApiKey = async (plan) => {
     const ref = plan && plan.transport && plan.transport.apiKeyEnv
     if (typeof ref === 'string' && ref !== '') {
@@ -4163,7 +4189,7 @@ export function apply(ctx, config = {}, runtime = {}) {
     }
     return undefined
   }
-  const directChannelVisionAnswer = async (provider, model, blocks, instruction, signal) => {
+  const directChannelVisionAnswer = async (provider, model, blocks, instruction, options = {}) => {
     const plan = channelBridgePlan(provider, model)
     if (!plan.ok) throw new Error(`vision bridge unavailable: ${plan.reason}`)
     const apiKey = await resolveChannelApiKey(plan)
@@ -4187,7 +4213,12 @@ export function apply(ctx, config = {}, runtime = {}) {
         apiKeyEnv: '__vision-router-channel__',
       },
       [{ role: 'user', content: [...content, { type: 'text', text: instruction }] }],
-      { maxTokens: 4096, signal, resolveCredential: () => apiKey },
+      {
+        maxTokens: 4096,
+        signal: options.signal,
+        sessionId: options.sessionId,
+        resolveCredential: () => apiKey,
+      },
     )
   }
 
@@ -4266,6 +4297,7 @@ export function apply(ctx, config = {}, runtime = {}) {
         system: anthropic.system,
         maxTokens: options.maxTokens ?? 4096,
         signal: options.signal,
+        sessionId: options.sessionId,
         apiKey,
       },
     )
@@ -4275,12 +4307,16 @@ export function apply(ctx, config = {}, runtime = {}) {
   const callVisionPair = async (pair, messages, options = {}) => {
     const corrected = await correctedVisionAnswer(pair, messages, options)
     if (corrected !== undefined) return corrected
+    assertOpenCodeGoAffinityForPair(pair, options.sessionId)
     return visionAnswer(ctx.llm, {
       provider: pair.provider,
       model: pair.model,
       messages,
       maxTokens: options.maxTokens ?? 4096,
       signal: options.signal,
+      ...(rawSessionIdentity(options.sessionId) === undefined
+        ? {}
+        : { sessionId: rawSessionIdentity(options.sessionId) }),
     })
   }
 
@@ -4327,7 +4363,7 @@ export function apply(ctx, config = {}, runtime = {}) {
           pair.model,
           options.bridgeBlocks,
           options.bridgeInstruction,
-          options.signal,
+          { signal: options.signal, sessionId: options.sessionId },
         )
       }
       throw error
@@ -4582,16 +4618,18 @@ export function apply(ctx, config = {}, runtime = {}) {
               const text = await correctedVisionAnswer(pair, messages, {
                 maxTokens: options.maxTokens ?? 65536,
                 signal: attemptSignal,
+                sessionId: options.sessionId,
               })
               if (text === undefined) {
-                yield* ctx.llm.stream({
+                assertOpenCodeGoAffinityForPair(pair, options.sessionId)
+                yield* streamWithVisionSessionAffinity(options.sessionId, () => ctx.llm.stream({
                   ...options,
                   provider: pair.provider,
                   model: pair.model,
                   reasoningEffort: undefined,
                   messages,
                   signal: attemptSignal,
-                })
+                }))
                 return
               }
               if (text !== '') {
@@ -5310,6 +5348,7 @@ export function apply(ctx, config = {}, runtime = {}) {
         // later calls answer instantly — no network, no re-hitting a tripped
         // 401 provider, no minutes of "deep diving".
         const session = exec && exec.agent && exec.agent.session
+        const sessionId = sessionIdentityOf(session)
         const scope = visionScopeOf(session)
         if (visionTurnMemory.allFailed(scope)) {
           return JSON.stringify(
@@ -5383,6 +5422,7 @@ export function apply(ctx, config = {}, runtime = {}) {
             let text = await callVisionPairWithOptionalBridge(pair, messages, {
               maxTokens: 4096,
               signal,
+              sessionId,
               capability,
               bridgeBlocks: blocks,
               bridgeInstruction: promptText,
@@ -5421,6 +5461,7 @@ ctx.logger?.info(
                   text = await callVisionPairWithOptionalBridge(pair, messages, {
                     maxTokens: 4096,
                     signal,
+                    sessionId,
                     capability,
                     bridgeBlocks: blocks,
                     bridgeInstruction:
@@ -5524,6 +5565,7 @@ ctx.logger?.info(
                 {
                   maxTokens: provider.maxTokens ?? 4096,
                   signal: attemptSignal,
+                  sessionId,
                   resolveCredential,
                 },
               )
@@ -5966,6 +6008,7 @@ ctx.logger?.info(
             {
               maxTokens: 4096,
               signal: attemptSignal,
+              sessionId: options.sessionId,
               capability: pairCapability,
               bridgeBlocks: [block],
               bridgeInstruction: instruction,
@@ -6004,6 +6047,7 @@ ctx.logger?.info(
                 deadline.signal(),
                 AbortSignal.timeout(timeoutMs()),
               ),
+              sessionId: options.sessionId,
               resolveCredential,
             },
           )
@@ -6020,11 +6064,14 @@ ctx.logger?.info(
 
     // Tool-facing wrapper: binds the caller's session+turn scope so the
     // breaker and the turn memory act per conversation turn.
-    const answerVisionForTool = (exec, imageBytes, mediaType, instruction, options = {}) =>
-      answerVision(imageBytes, mediaType, instruction, {
-        scope: visionScopeOf(exec && exec.agent && exec.agent.session),
+    const answerVisionForTool = (exec, imageBytes, mediaType, instruction, options = {}) => {
+      const session = exec && exec.agent && exec.agent.session
+      return answerVision(imageBytes, mediaType, instruction, {
         ...options,
+        scope: visionScopeOf(session),
+        sessionId: sessionIdentityOf(session),
       })
+    }
 
     deepToolDefs.push({
       name: 'vision_ground',
@@ -6960,7 +7007,7 @@ ctx.logger?.info(
     })
 
     // ── dsh-vision 并入：屏幕截图（vision_screenshot）───────────────────────
-    // 截取用户桌面。平台命令：Windows PowerShell CopyFromScreen（虚拟屏幕）、
+    // 截取用户桌面。平台命令：Windows PMv2-aware PowerShell helper（虚拟屏幕）、
     // macOS screencapture（主显示器）、Linux ImageMagick import（回退 scrot，
     // 两者均为系统外部依赖）。产物写入工作区 artifacts 目录。
     // Boot-time opt-in: the tool is registered ONLY when desktopScreenshot is
@@ -6971,7 +7018,7 @@ ctx.logger?.info(
         name: 'vision_screenshot',
       description:
         'Capture the user\'s desktop screen as a PNG artifact (the virtual screen on Windows; the main display on macOS; the root display on Linux). ' +
-        'Windows: PowerShell CopyFromScreen; macOS: screencapture; Linux: ImageMagick import (falls back to scrot; either command must be installed). ' +
+        'Windows: per-monitor-DPI-aware PowerShell capture; macOS: screencapture; Linux: ImageMagick import (falls back to scrot; either command must be installed). ' +
         'This privacy-sensitive tool is disabled by default and works only after the user explicitly enables Desktop screenshot in Vision Router settings. ' +
         'Use it when you need to see what is on the user\'s screen right now — e.g. their current GUI, an app, or a page outside this browser. ' +
         'Optional identify=true also runs local recognition on the capture using the enabled local backends (Ollama, then LM Studio) and returns the description alongside the path.',
@@ -7000,18 +7047,13 @@ ctx.logger?.info(
         const platform = process.platform
         try {
           if (platform === 'win32') {
-            const script = [
-              'Add-Type -AssemblyName System.Windows.Forms,System.Drawing',
-              '$b=[System.Windows.Forms.SystemInformation]::VirtualScreen',
-              '$bmp=New-Object System.Drawing.Bitmap($b.Width,$b.Height)',
-              '$g=[System.Drawing.Graphics]::FromImage($bmp)',
-              '$g.CopyFromScreen($b.X,$b.Y,0,0,$bmp.Size)',
-              `$bmp.Save('${tmp.replace(/'/g, "''")}')`,
-              '$g.Dispose();$bmp.Dispose()',
-            ].join('; ')
-            await promisify(execFile)('powershell.exe', ['-NoProfile', '-STA', '-Command', script], {
-              timeout: timeoutMs(),
-              windowsHide: true,
+            // #409: own the DPI-aware capture here instead of emitting the
+            // known-broken logical-coordinate script and hoping a global
+            // promisify(execFile) shim rewrites it later. The helper also
+            // isolates CodeDom TEMP/TMP to a writable ASCII path.
+            await captureWindowsDesktop(tmp, {
+              timeoutMs: timeoutMs(),
+              signal: exec?.signal,
             })
           } else if (platform === 'darwin') {
             // Without -m, screencapture writes one file per display. The code