dsh-vision-router 1.7.3 → 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'
@@ -25,16 +29,18 @@ import { contextWithCoalescedAdapterUpdates } from './lib/adapter-update-coalesc
 import { installTesseractExecFileCompat } from './lib/tesseract-exec-compat.js'
 import { installLocalMutationRouteBoundary } from './lib/web-capability-boundary.js'
 import { installScreenshotSourceBoundary } from './lib/screenshot-source-boundary.js'
+import { installVisionToolRuntimeBoundary } from './lib/vision-tool-runtime-boundary.js'
 import { installVisionRouterRemoteSettingsBridge } from './lib/remote-settings-bridge.js'
+import { installSettingsRc8ClientLifecycle } from './lib/settings-client-rc8-lifecycle.js'
 import {
   installStructuredFlowHardening,
   normalizeGuidanceOverrides,
 } from './lib/structured-flow-hardening.js'
 import {
   attachmentContextForContract,
-  ensureVisionAttachmentAdmissionPolicy,
   hasBatchAttachmentContract,
   installHostSettingsCompatibility,
+  installVisionAttachmentAdmissionPolicy,
   protectHostProviderOwnership,
 } from './lib/dsh-contract-compat.js'
 
@@ -84,6 +90,7 @@ export {
   ensureVisionAttachmentAdmissionPolicy,
   hasBatchAttachmentContract,
   installHostSettingsCompatibility,
+  installVisionAttachmentAdmissionPolicy,
   protectHostProviderOwnership,
   // Transitional public aliases retained for callers/tests written during the
   // rc.7 compatibility pass. Runtime code below no longer branches on names.
@@ -163,18 +170,20 @@ export function apply(ctx, config = {}) {
   // generation. Keep the branch named after that observable capability rather
   // than a release number so rc.8+ naturally follows the same public contract.
   const batchAttachmentHost = hasBatchAttachmentContract(stabilizedCtx)
-  // DSH profile overlays replace an attachment-local config object wholesale.
-  // A stale pre-rc.8 Vision Router profile row can therefore erase the newer
-  // bundle's maxImageDimension and silently restore rc.8's 2000px default even
-  // after the plugin package itself has updated. Repair only that historical
-  // 20MiB/100MP fingerprint; explicit deployment policies remain authoritative.
+  // DSH may reconstruct attachment-local after a profile/home patch reload.
+  // Keep the historical rc.8 overlay migration attached to that service
+  // lifecycle instead of healing only the instance present during apply().
   if (batchAttachmentHost) {
-    ensureVisionAttachmentAdmissionPolicy(stabilizedCtx, logging.logger)
+    installVisionAttachmentAdmissionPolicy(stabilizedCtx, logging.logger)
   }
   // The remote settings bridge uses DSH Connection's trusted-host carrier
   // fence and its own safe-field capability allow-list. Main's local Web
   // mutation boundary continues to protect the independent /_dsh write routes.
   installVisionRouterRemoteSettingsBridge(stabilizedCtx, logging.logger)
+  // rc.8 swaps ModuleLoader.load() while entering live mode. The older local
+  // permission/risk shims still own rc.6/rc.7; this narrow lifecycle shim
+  // re-installs both contexts after rc.8's queue -> live transition.
+  installSettingsRc8ClientLifecycle(stabilizedCtx)
   const ownershipCtx = batchAttachmentHost
     ? protectHostProviderOwnership(stabilizedCtx)
     : stabilizedCtx
@@ -191,11 +200,22 @@ export function apply(ctx, config = {}) {
   const attachmentCompatCtx = attachmentContextForContract(settingsCtx, logging.logger, {
     installAndroidAttachmentCompat,
   })
+  // Put per-tool cwd/cancellation/cache policy AFTER Host settings compatibility
+  // so rc.7/rc.8's synthetic settings injection is visible to the boundary.
+  // 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(attachmentCompatCtx, 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
@@ -230,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
@@ -241,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
@@ -267,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/adversarial-hardening.js

@@ -3,6 +3,7 @@ import { mkdir, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { writeArtifactFile } from './artifact-boundary.js'
+import { assertScreenshotSourceInWorkspace } from './screenshot-source-boundary.js'
 
 const DEFAULT_ARTIFACTS_DIR = '.dsh-vision-router/artifacts'
 const MAX_VIEWPORT_WIDTH = 4096
@@ -217,7 +218,7 @@ export async function wakePageForFullCaptureBounded(
 }
 
 function screenshotAbortError() {
-  const error = new Error('vision_html_screenshot: browser slot wait aborted')
+  const error = new Error('vision_html_screenshot: browser work aborted')
   error.name = 'AbortError'
   error.code = 'ABORT_ERR'
   return error
@@ -299,18 +300,26 @@ export function createSecureHtmlScreenshotExecute(ctx, core, config, deps = {})
 
   return async (args, exec) => {
     const source = String(args?.source ?? '')
+    const signal = exec?.signal
+    if (signal?.aborted) throw screenshotAbortError()
     if (!/\.(html?|htm)$/i.test(source)) {
       throw new Error('vision_html_screenshot: source must be a local .html/.htm file')
     }
     const fsService = ctx.get('fs')
     if (fsService === undefined) throw new Error('vision_html_screenshot: the fs service is not available')
-    const resolved = await fsService.resolve(source)
+    // Authorize the exact FsTarget that will be rendered. Do not validate one
+    // cwd interpretation and then resolve the same string again under the
+    // provider default cwd.
+    const resolved = await assertScreenshotSourceInWorkspace(ctx, core, source, exec, { realpathSync: realpath })
     const targetPath = core.toRealPath(fsService, resolved)
     if (!fileExists(targetPath)) throw new Error(`vision_html_screenshot: file not found: ${source}`)
 
     const targetReal = realpath(targetPath)
     const workspace = realpathOrResolve(workspaceOf(exec), realpath)
-    const sourceRoot = isPathInside(workspace, targetReal) ? workspace : realpath(path.dirname(targetReal))
+    if (!isPathInside(workspace, targetReal)) {
+      throw new Error('vision_html_screenshot: source must stay inside the session workspace')
+    }
+    const sourceRoot = workspace
 
     const width = safeViewportDimension(args?.width, 1200, MAX_VIEWPORT_WIDTH, 'width')
     const height = safeViewportDimension(args?.height, 720, MAX_VIEWPORT_HEIGHT, 'height')
@@ -336,13 +345,22 @@ export function createSecureHtmlScreenshotExecute(ctx, core, config, deps = {})
       )
     }
 
-    const releaseBrowserSlot = await browserGovernor.acquire({ signal: exec?.signal })
+    const releaseBrowserSlot = await browserGovernor.acquire({ signal })
     const launchArgs = ['--disable-gpu', '--hide-scrollbars', '--incognito']
     if (fullPage) launchArgs.push('--blink-settings=imagesLazyLoadingEnabled=false')
     const launcher = puppeteer.default ?? puppeteer
     let browser
+    let browserClosePromise
+    let abortHandler
     let png
     let pageHeight
+    const closeBrowser = () => {
+      if (!browser) return Promise.resolve()
+      if (!browserClosePromise) {
+        browserClosePromise = Promise.resolve(browser.close()).catch(() => undefined)
+      }
+      return browserClosePromise
+    }
     try {
       try {
         browser = await launcher.launch({ executablePath, headless: true, args: launchArgs })
@@ -350,6 +368,11 @@ export function createSecureHtmlScreenshotExecute(ctx, core, config, deps = {})
         const detail = error && error.message ? error.message : String(error)
         throw new Error(`vision_html_screenshot: secure Chrome sandbox launch failed: ${detail}`)
       }
+      if (signal) {
+        abortHandler = () => { void closeBrowser() }
+        signal.addEventListener('abort', abortHandler, { once: true })
+      }
+      if (signal?.aborted) throw screenshotAbortError()
 
       const page = await browser.newPage()
       await page.setViewport({ width, height })
@@ -362,6 +385,7 @@ export function createSecureHtmlScreenshotExecute(ctx, core, config, deps = {})
       await page.setOfflineMode(true)
       await wrapRequestInterception(page, sourceRoot)
       await page.goto(pathToFileURL(targetReal).href, { waitUntil: 'networkidle0', timeout: 30000 })
+      if (signal?.aborted) throw screenshotAbortError()
 
       if (fullPage) {
         pageHeight = await wakePageForFullCaptureBounded(page, height, width, {
@@ -371,13 +395,19 @@ export function createSecureHtmlScreenshotExecute(ctx, core, config, deps = {})
           maxWakeMs: deps.maxWakeMs,
         })
       }
+      if (signal?.aborted) throw screenshotAbortError()
 
       png = fullPage
         ? await page.screenshot({ type: 'png', fullPage: true })
         : await page.screenshot({ type: 'png' })
+      if (signal?.aborted) throw screenshotAbortError()
+    } catch (error) {
+      if (signal?.aborted && error?.code !== 'ABORT_ERR') throw screenshotAbortError()
+      throw error
     } finally {
+      if (signal && abortHandler) signal.removeEventListener('abort', abortHandler)
       try {
-        if (browser) await browser.close()
+        await closeBrowser()
       } finally {
         releaseBrowserSlot()
       }
@@ -385,6 +415,7 @@ export function createSecureHtmlScreenshotExecute(ctx, core, config, deps = {})
 
     // The heavyweight Chrome slot is released before filesystem artifact IO;
     // slow antivirus/indexing must not unnecessarily serialize later captures.
+    if (signal?.aborted) throw screenshotAbortError()
     const stem = fullPage ? `shot-${width}x${height}-fullpage` : `shot-${width}x${height}`
     const fileName = `${core.artifactStemOf(source, stem)}.png`
     let target

package/lib/artifact-boundary.js

@@ -1,6 +1,14 @@
 import { randomUUID } from 'node:crypto'
 import { lstat, mkdir, realpath, rename, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
+import {
+  currentVisionTurnBudget,
+  currentVisionTurnBudgetSignal,
+} from './turn-budget-context.js'
+import {
+  isManagedArtifactRunName,
+  scheduleArtifactRetention,
+} from './artifact-retention.js'
 
 export const DEFAULT_ARTIFACTS_DIR = '.dsh-vision-router/artifacts'
 
@@ -13,6 +21,22 @@ function isMissing(error) {
   return error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')
 }
 
+function artifactAbortError() {
+  const error = new Error('vision-router: artifact publication aborted')
+  error.name = 'AbortError'
+  error.code = 'ABORT_ERR'
+  return error
+}
+
+function throwIfVisionAborted() {
+  if (currentVisionTurnBudgetSignal()?.aborted) throw artifactAbortError()
+}
+
+function currentArtifactRunId() {
+  const value = currentVisionTurnBudget()?.artifactRunId
+  return isManagedArtifactRunName(value) ? value : undefined
+}
+
 export function normalizeArtifactsDir(value) {
   if (typeof value !== 'string' || value.trim() === '') return DEFAULT_ARTIFACTS_DIR
   const raw = value.trim()
@@ -69,18 +93,22 @@ async function safeLstat(target, lstatImpl) {
 /**
  * Resolve an artifact target without treating lexical workspace containment as
  * authority. Existing ancestors are canonicalized before mkdir runs, then the
- * completed parent is canonicalized again. This prevents an artifactsDir (or
- * nested OCR directory) symlink from turning a workspace-looking path into an
- * outside write.
+ * completed parent and artifact root are canonicalized again.
  */
 export async function resolveArtifactTarget(workspace, artifactsDir, relativePath, deps = {}) {
   const realpathImpl = deps.realpath ?? realpath
   const mkdirImpl = deps.mkdir ?? mkdir
   const lstatImpl = deps.lstat ?? lstat
 
+  throwIfVisionAborted()
   const workspaceReal = await realpathImpl(path.resolve(String(workspace ?? '')))
+  throwIfVisionAborted()
   const relativeBase = normalizeArtifactsDir(artifactsDir)
-  const relativeTarget = normalizeRelativeArtifactPath(relativePath)
+  const runId = currentArtifactRunId()
+  const requestedTarget = normalizeRelativeArtifactPath(relativePath)
+  const relativeTarget = runId
+    ? normalizeRelativeArtifactPath(path.join(runId, requestedTarget))
+    : requestedTarget
   const lexicalBase = path.resolve(workspaceReal, relativeBase)
   if (!isPathInside(workspaceReal, lexicalBase)) {
     throw new Error('vision-router: artifactsDir must stay inside the session workspace')
@@ -92,22 +120,27 @@ export async function resolveArtifactTarget(workspace, artifactsDir, relativePat
 
   const lexicalParent = path.dirname(lexicalTarget)
   const existingAncestorReal = await realpathNearestExisting(lexicalParent, realpathImpl)
+  throwIfVisionAborted()
   if (!isPathInside(workspaceReal, existingAncestorReal)) {
     throw new Error('vision-router: artifact parent escapes the session workspace through a symlink')
   }
 
   await mkdirImpl(lexicalParent, { recursive: true })
+  throwIfVisionAborted()
   const parentReal = await realpathImpl(lexicalParent)
-  if (!isPathInside(workspaceReal, parentReal)) {
+  const artifactsBaseReal = await realpathImpl(lexicalBase)
+  throwIfVisionAborted()
+  if (!isPathInside(workspaceReal, parentReal) || !isPathInside(workspaceReal, artifactsBaseReal)) {
     throw new Error('vision-router: artifact parent escapes the session workspace through a symlink')
   }
 
   const target = path.join(parentReal, path.basename(lexicalTarget))
   const existing = await safeLstat(target, lstatImpl)
+  throwIfVisionAborted()
   if (existing?.isDirectory?.()) {
     throw new Error('vision-router: artifact target is a directory')
   }
-  return { target, parentReal, existing }
+  return { target, parentReal, artifactsBaseReal, existing, runId }
 }
 
 /**
@@ -126,16 +159,22 @@ export async function writeArtifactFile(workspace, artifactsDir, relativePath, d
   )
   let published = false
   try {
+    throwIfVisionAborted()
     await writeFileImpl(temp, data, { mode: 0o600 })
+    throwIfVisionAborted()
     if (resolved.existing !== undefined) {
       try {
         await unlinkImpl(resolved.target)
       } catch (error) {
         if (!isMissing(error)) throw error
       }
+      throwIfVisionAborted()
     }
     await renameImpl(temp, resolved.target)
     published = true
+    if (resolved.runId) {
+      scheduleArtifactRetention(resolved.artifactsBaseReal, { protectRunId: resolved.runId })
+    }
     return resolved.target
   } finally {
     if (!published) {