dsh-vision-router 1.7.1 → 1.7.4

package/cordis.patch.yml

@@ -4,9 +4,9 @@
 # without any manual cordis.patch.yml edits. Later layers (the profile's own
 # cordis.patch.yml, --patch overlays) override these rows by id.
 
-# 纯增量补丁（issue #34）：不碰核心行。DSH rc.6仍保留旧版隐身接管兼容路径；
-# DSH rc.7则始终由宿主拥有deepseek-official，插件只提供「+ 自动识图」包装路由。
-# 因此这里永远不默认禁用官方llm-deepseek行。
+# 纯增量补丁（issue #34）：不碰核心行。最低支持 Host 仍保留旧兼容路径；
+# batch-attachment 合同的 Host 始终拥有 deepseek-official，插件只提供
+# 「+ 自动识图」包装路由，因此这里永远不默认禁用官方 llm-deepseek 行。
 
 # 挂载插件行。默认保持完整视觉工具表常驻（issue #81）：虽然渐进挂载可以
 # 少发一小段工具 schema，但图片轮首次扩展工具列表会改变请求前缀，可能让
@@ -18,14 +18,27 @@
       config:
         progressiveTools: false
 
-# 放宽附件图片限制（宿主默认 5MB / 4000 万像素 → 20MB / 1 亿像素），
-# 超长聊天记录截图（vision_long_screenshot_ocr 主场景）与大尺寸设计稿/
-# 扫描图可过宿主准入。rc6 与 rc7 的 @deepseek-ai/dsh-attachment-local
-# 均接受这两个可选字段（0.1.0-rc.6 / 0.1.0-rc.7 schema 已核对），且两边
-# dsh-base bundle 都存在 `- id: attachment-local` 行，因此该补丁在两个
-# 运行时上都有效、不破坏 host-neutral 原则；字段可选，不需要可在 profile
-# 补丁层覆写。
+# Vision Router 的附件产品契约：Host attachment store 负责保存用户提交的
+# durable 原件，具体视觉后端负责本次推理所需的 resize/tile/request budget。
+# 因此存储准入保持 20MiB / 1 亿像素，同时在 DSH rc.8 新增的单边限制上
+# 显式选择 10000px：覆盖 4K/手机原图和常见长截图，但不把 Host 的全局
+# 极端长边安全闸无限放开。该值作用于整个 attachment-local（包括原生视觉
+# provider），所以这里刻意不用 32768/无限；更大的部署需求仍可由后续
+# profile/--patch 层按实际 provider 能力覆盖。
+#
+# DSH 的 patch 是“整段 config 替换”而非深度合并。旧版 Vision Router 曾在
+# profile 自己的 cordis.patch.yml 写入同一行的 20MiB/100MP 两个字段；这层
+# 比 bundle 晚，会把这里新加的 maxImageDimension 擦掉，让 rc.8 又落回 2000。
+# 1.7.2 起运行时只对“20MiB + 100MP + rc.8 默认 2000px”这一历史指纹做一次
+# 内存态迁移到 10000px；显式自定义过 dimension 或其他附件策略一律不碰。
+# 这样升级旧 profile 不要求用户手工清理配置，同时后续 profile/--patch 的
+# 明确部署策略仍保持最终所有权。
+#
+# rc.6/rc.7 没有 maxImageDimension；发布合同 CI 会用真实旧包验证额外配置键
+# 不会破坏最低支持 Host。若旧 Host 开始严格拒绝未知键，此处必须改为按能力
+# 生成配置，而不是靠版本字符串分支。
 - id: attachment-local
   config:
     maxImageBytes: 20971520
     maxImagePixels: 100000000
+    maxImageDimension: 10000

package/entry.js

@@ -15,6 +15,7 @@ import { contextWithVisionExecutionPolicy } from './lib/vision-execution-policy.
 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 { installClientPresentationBoundary } from './lib/client-presentation-boundary.js'
 import { installAdversarialHardening } from './lib/adversarial-hardening.js'
 import { installOllamaColdStartGuard } from './lib/ollama-cold-start.js'
 import { installLocalVisionStabilizer } from './lib/local-vision-stabilizer.js'
@@ -24,16 +25,19 @@ 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,
-  installRc7SettingsCompatibility,
-  isRc7ContractRuntime,
-  protectRc7ProviderOwnership,
+  hasBatchAttachmentContract,
+  installHostSettingsCompatibility,
+  installVisionAttachmentAdmissionPolicy,
+  protectHostProviderOwnership,
 } from './lib/dsh-contract-compat.js'
 
 // Increment whenever the browser-visible settings contract gains a field whose
@@ -56,7 +60,7 @@ core.Config.set('visionTurnBudgetMs', z.number().step(1000).min(10000).max(60000
 // Both visible entry points — Settings > Vision Router and the legacy
 // Settings > Plugins compatibility card — edit the same Host-owned namespace.
 // Keep the depth enum and custom cap on this final public contract so either
-// entry serializes exactly the same shape and rc.7 Host persistence accepts it.
+// entry serializes exactly the same shape on every supported Host generation.
 core.Config.set('visionDepth', z.union(['fast', 'standard', 'deep', 'custom']).default('standard'))
 core.Config.set('visionDepthMaxCalls', z.number().step(1).min(0).max(100).default(0))
 
@@ -79,6 +83,13 @@ core.Config.set(
 export * from './index.js'
 export {
   attachmentContextForContract,
+  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.
   installRc7SettingsCompatibility,
   isRc7ContractRuntime,
   protectRc7ProviderOwnership,
@@ -106,7 +117,7 @@ export function apply(ctx, config = {}) {
         : 'deepseek-vision',
     visionConfig: config,
   })
-  // DSH rc.7 pi-ai replay v2 stores the real producer under
+  // Newer pi-ai replay envelopes store the real producer under
   // replayState.response.{provider,model}; the older delegated-replay shim
   // recognizes the pre-v2 top-level shape. Layer a narrow private compatibility
   // view so resumed wrapper history keeps provider-native replay metadata rather
@@ -150,31 +161,52 @@ export function apply(ctx, config = {}) {
         ? Number(bootConfig.visionTurnBudgetMs)
         : 90000,
   }
-  const rc7 = isRc7ContractRuntime(stabilizedCtx)
+  // The batch-attachment API is the released, non-incidental discriminator
+  // between the minimum Host contract and the newer Host-owned integration
+  // 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 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) {
+    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)
-  const ownershipCtx = rc7 ? protectRc7ProviderOwnership(stabilizedCtx) : stabilizedCtx
-  const settingsCtx = rc7
-    ? installRc7SettingsCompatibility(ownershipCtx, { ...runtimeConfig, stealth: false }, {
+  // 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
+  const settingsCtx = batchAttachmentHost
+    ? installHostSettingsCompatibility(ownershipCtx, { ...runtimeConfig, stealth: false }, {
         namespace: 'vision-router',
         Config: core.Config,
       })
     : ownershipCtx
-  // rc.6/Termux keeps the narrow process-local fallback that was required by
-  // the old attachment-local durability walk. rc.7 formalizes AttachmentId as
-  // store-owned, so never synthesize one there: host persistence errors remain
+  // The minimum Host keeps the narrow process-local fallback required by the
+  // old attachment-local durability walk. Batch-capable hosts keep AttachmentId
+  // store-owned, so never fabricate one there: host persistence errors remain
   // authoritative and diagnosable instead of creating a false durable ref.
   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)
   // 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)
-  // DSH rc.7 publishes llm/adapters-updated synchronously from inside
+  const structuredCtx = installStructuredFlowHardening(toolRuntimeCtx, runtimeConfig)
+  // 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
   // neither double-register a twin nor lose a provider added mid-pass.
@@ -196,6 +228,12 @@ export function apply(ctx, config = {}) {
   // source strictly for diagnostics (`known` vs `live`) without changing the
   // admission decision.
   installVisionModelRegistry(reconciledCtx, liveDiscovery, { config: runtimeConfig })
+  // rc.8 turns ui-attachment into a dynamic presentation plugin and no longer
+  // exports its React implementation as package values. Install a narrowly
+  // scoped browser boundary that supplies Vision Router's own lightweight
+  // gallery to the legacy 1.7.x client factory, so the official package is
+  // never value-required at runtime and remains free to evolve independently.
+  installClientPresentationBoundary(reconciledCtx)
   // Keep endpoint-discovered ids private to Vision Router's settings client:
   // the prelude wraps this package's browser context rather than changing the
   // global llm.models response (which would expose UNKNOWN_MODEL entries in the
@@ -229,7 +267,7 @@ export function apply(ctx, config = {}) {
     const lms = c.localLmStudio && typeof c.localLmStudio === 'object' ? c.localLmStudio : {}
     logging.logger.info(
       'vision-router: base config summary — contract=%s instantDescribe=%s localDescribeStyle=%s localOllama=%s localLmStudio=%s',
-      rc7 ? 'rc7' : 'rc6',
+      batchAttachmentHost ? 'batch-attachments' : 'single-attachment',
       c.instantDescribe === true ? 'on' : 'off',
       c.localDescribeStyle === 'structured' ? 'structured' : 'plain',
       local.enabled === true ? 'on' : 'off',
@@ -240,11 +278,10 @@ export function apply(ctx, config = {}) {
   }
   try {
     const result = core.apply(executionCtx, runtimeConfig)
-    // DSH rc.7's 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 DeepSeek so
-    // a reinstall restores the expected model-group row without making an
-    // arbitrary textProvider look like DeepSeek. On rc.6 the helper is inert.
+    // 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
+    // DeepSeek. On older Hosts the helper feature-detects and stays inert.
     installWrapperDirectoryAlias(attachmentCompatCtx, runtimeConfig, logging.logger)
     if (result && typeof result.then === 'function') {
       return result.catch((error) => {

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) {

package/lib/artifact-retention.js

@@ -0,0 +1,124 @@
+import { lstat, readdir, rm } from 'node:fs/promises'
+import path from 'node:path'
+
+export const ARTIFACT_RUN_PREFIX = '.vision-run-'
+export const DEFAULT_ARTIFACT_TTL_MS = 30 * 24 * 60 * 60 * 1000
+export const DEFAULT_ARTIFACT_MAX_BYTES = 2 * 1024 * 1024 * 1024
+export const DEFAULT_ARTIFACT_MAX_RUNS = 512
+export const DEFAULT_ARTIFACT_CLEANUP_INTERVAL_MS = 5 * 60 * 1000
+
+const cleanupState = new Map()
+const MAX_TRACKED_ROOTS = 64
+
+export function isManagedArtifactRunName(name) {
+  return typeof name === 'string' && /^\.vision-run-[A-Za-z0-9._-]+$/.test(name)
+}
+
+async function treeBytes(target) {
+  let info
+  try { info = await lstat(target) } catch { return 0 }
+  if (info.isSymbolicLink()) return 0
+  if (!info.isDirectory()) return Number(info.size) || 0
+  let total = 0
+  let entries
+  try { entries = await readdir(target, { withFileTypes: true }) } catch { return 0 }
+  for (const entry of entries) {
+    total += await treeBytes(path.join(target, entry.name))
+  }
+  return total
+}
+
+function finitePositive(value, fallback) {
+  const number = Number(value)
+  return Number.isFinite(number) && number > 0 ? number : fallback
+}
+
+/**
+ * Delete only Vision Router run directories. Unknown files, legacy artifacts,
+ * symlinks and user-created directories are intentionally outside this policy.
+ */
+export async function cleanupArtifactRuns(root, options = {}) {
+  const ttlMs = finitePositive(options.ttlMs, DEFAULT_ARTIFACT_TTL_MS)
+  const maxBytes = finitePositive(options.maxBytes, DEFAULT_ARTIFACT_MAX_BYTES)
+  const maxRuns = Math.max(1, Math.floor(finitePositive(options.maxRuns, DEFAULT_ARTIFACT_MAX_RUNS)))
+  const now = Number.isFinite(Number(options.now)) ? Number(options.now) : Date.now()
+  const protect = typeof options.protectRunId === 'string' ? options.protectRunId : undefined
+
+  let entries
+  try { entries = await readdir(root, { withFileTypes: true }) } catch { return { scanned: 0, removed: 0, bytes: 0 } }
+  const runs = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !isManagedArtifactRunName(entry.name)) continue
+    const target = path.join(root, entry.name)
+    let info
+    try { info = await lstat(target) } catch { continue }
+    if (!info.isDirectory() || info.isSymbolicLink()) continue
+    runs.push({
+      name: entry.name,
+      target,
+      mtimeMs: Number(info.mtimeMs) || 0,
+      bytes: await treeBytes(target),
+      protected: entry.name === protect,
+    })
+  }
+
+  runs.sort((a, b) => b.mtimeMs - a.mtimeMs)
+  const remove = new Set()
+  for (const run of runs) {
+    if (!run.protected && now - run.mtimeMs >= ttlMs) remove.add(run)
+  }
+
+  const survivors = () => runs.filter((run) => !remove.has(run))
+  let live = survivors()
+  while (live.length > maxRuns) {
+    const candidate = [...live].reverse().find((run) => !run.protected)
+    if (!candidate) break
+    remove.add(candidate)
+    live = survivors()
+  }
+
+  let totalBytes = live.reduce((sum, run) => sum + run.bytes, 0)
+  while (totalBytes > maxBytes) {
+    const candidate = [...live].reverse().find((run) => !run.protected)
+    if (!candidate) break
+    remove.add(candidate)
+    totalBytes -= candidate.bytes
+    live = survivors()
+  }
+
+  let removed = 0
+  for (const run of remove) {
+    try {
+      await rm(run.target, { recursive: true, force: true })
+      removed += 1
+    } catch {
+      // Retention is best-effort and must never make the foreground tool fail.
+    }
+  }
+  return { scanned: runs.length, removed, bytes: Math.max(0, totalBytes) }
+}
+
+/** Coalesce cleanup work per artifact root so foreground tools only schedule it. */
+export function scheduleArtifactRetention(root, options = {}) {
+  if (typeof root !== 'string' || root === '') return
+  const now = Date.now()
+  let state = cleanupState.get(root)
+  if (!state) {
+    state = { lastStartedAt: 0, promise: undefined }
+    cleanupState.set(root, state)
+  }
+  const intervalMs = finitePositive(options.intervalMs, DEFAULT_ARTIFACT_CLEANUP_INTERVAL_MS)
+  if (state.promise || now - state.lastStartedAt < intervalMs) return
+  state.lastStartedAt = now
+  state.promise = cleanupArtifactRuns(root, options)
+    .catch(() => undefined)
+    .finally(() => { state.promise = undefined })
+
+  cleanupState.delete(root)
+  cleanupState.set(root, state)
+  while (cleanupState.size > MAX_TRACKED_ROOTS) {
+    const oldest = cleanupState.keys().next().value
+    if (oldest === undefined) break
+    cleanupState.delete(oldest)
+  }
+}