dsh-vision-router 1.7.3 → 1.7.4

package/entry.js

@@ -25,16 +25,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 +86,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 +166,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 +196,16 @@ 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)
   // 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(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

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)
+  }
+}

package/lib/live-model-client-prelude.js

@@ -415,6 +415,7 @@ export const LIVE_MODEL_CLIENT_PRELUDE = String.raw`(function(){
     if (next.zh && typeof next.zh === 'object') {
       next.zh = Object.assign({}, next.zh, {
         catalogPartialFailure: '部分已配置供应商的模型目录加载失败：{detail}。供应商仍会保留在识图设置中；若无法枚举模型，可选择“手动输入模型 ID”。',
+        chainHint: '请先在「设置 → 模型」中配置可用模型，再回到这里选择 Vision Router 用来读取图片的模型。将按从上到下的顺序尝试，失败时自动切换到下一个。',
         visionDepthStandard: '标准（最多再细看 2 次，默认）',
         visionDepthDeep: '细致（最多再细看 4 次）',
         hintVisionDepth: '结构化预识别之后：快速最多再细看 1 次、标准最多 2 次、细致最多 4 次；自定义可自行设置上限。档位只限制追加的证据深挖次数，具体看什么仍由模型按你的问题决定。',
@@ -424,6 +425,7 @@ export const LIVE_MODEL_CLIENT_PRELUDE = String.raw`(function(){
     if (next.en && typeof next.en === 'object') {
       next.en = Object.assign({}, next.en, {
         catalogPartialFailure: 'Some configured providers failed to load their model catalog: {detail}. The provider stays available in Vision Router; choose “Enter model ID” when its models cannot be enumerated.',
+        chainHint: 'Configure the model first in Settings → Models, then return here to choose which models Vision Router uses to read images. They are tried from top to bottom, with automatic failover.',
         visionDepthStandard: 'Standard (at most 2 more looks, default)',
         visionDepthDeep: 'Thorough (at most 4 more looks)',
         hintVisionDepth: 'After the structured pre-scan: Quick allows at most 1 more evidence look, Standard 2, Thorough 4, and Custom lets you set the cap. The tier limits only additional evidence calls; the model still decides what to inspect from your request.',
@@ -460,6 +462,10 @@ export const LIVE_MODEL_CLIENT_PRELUDE = String.raw`(function(){
           if (typeof register !== 'function') return register;
           return function(options) {
             var args = Array.prototype.slice.call(arguments);
+            if (options && options.name === 'settings.plugin.item'
+                && (options.id === SETTINGS_SECTION_ID || options.key === SETTINGS_SECTION_ID)) {
+              return function(){};
+            }
             if (options && options.name === 'settings.section' && options.id === SETTINGS_SECTION_ID) {
               args[0] = Object.assign({}, options, {
                 order: settingsSectionOrder(target, SETTINGS_SECTION_ID)
@@ -610,4 +616,4 @@ export function installLiveModelClientPrelude(ctx) {
       'vision-router: live model client prelude',
     )
   })
-}
+}

package/lib/repetition-guard.js

@@ -1,45 +1,63 @@
 /**
  * Repetition-loop guard for vision backend output.
  *
- * Some vision backends occasionally degenerate into repetition loops when
- * asked for long constrained output (e.g. the structured-bootstrap JSON
- * schema) over a tall screenshot — the "answer" is one short phrase repeated
- * hundreds of times (observed in the wild as 「網絡路由器 互聯網 路由器…」
- * or 「華爲數據中心…」). Such output is useless to the agent and, worse,
- * it looks like a successful backend result, so the fallback chain never
- * runs. This module detects the signature of such loops so the vision chain
- * can treat them as backend failures and move to the next candidate.
- *
- * Detection is intentionally cheap and heuristic:
- *  - whitespace is stripped first, because loops are often separated by
- *    spaces/punctuation that vary;
- *  - a consecutive-run scan looks for one window repeated back-to-back
- *    (the classic loop shape);
- *  - a token-density check catches non-consecutive-but-overwhelming
- *    repetition (the "路由器 / 互聯網 路由器" alternation shape).
+ * The guard targets language-generation loops, not legitimate OCR filler,
+ * numeric tables or long machine data. Analysis is deliberately bounded so a
+ * near-limit backend response cannot turn the detector itself into a memory
+ * spike.
  */
 
 export const REPETITION_LOOP_MARKER = 'vision backend returned a repetition loop'
+export const DEFAULT_REPETITION_ANALYSIS_CHARS = 128 * 1024
+export const DEFAULT_REPETITION_DENSITY_CHARS = 64 * 1024
 
 /** Strip whitespace (and NBSP) so loops split by varying whitespace collapse. */
 export function compactForRepetition(text) {
   return String(text ?? '').replace(/[\s\u00a0]+/gu, '')
 }
 
+/**
+ * Bound analysis to front/middle/tail samples. NUL separators prevent a phrase
+ * ending one sample and starting another from fabricating a consecutive run.
+ */
+export function sampleForRepetition(text, maxChars = DEFAULT_REPETITION_ANALYSIS_CHARS) {
+  const source = String(text ?? '')
+  const limit = Math.max(256, Math.floor(Number(maxChars) || DEFAULT_REPETITION_ANALYSIS_CHARS))
+  if (source.length <= limit) return source
+  const frontSize = Math.floor(limit * 0.5)
+  const middleSize = Math.floor(limit * 0.25)
+  const tailSize = Math.max(1, limit - frontSize - middleSize)
+  const middleStart = Math.max(frontSize, Math.floor((source.length - middleSize) / 2))
+  return [
+    source.slice(0, frontSize),
+    source.slice(middleStart, middleStart + middleSize),
+    source.slice(-tailSize),
+  ].join('\u0000')
+}
+
 const CANDIDATE_WINDOWS = [2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 40]
 
+// Repetition failures seen from generative models contain words/ideographs.
+// Pure digits/punctuation are common in OCR, matrices, serial numbers and
+// telemetry, so those windows must not be treated as language loops.
+function informativeWindow(value) {
+  return /\p{L}/u.test(String(value ?? ''))
+}
+
 /**
  * @param {string} text raw backend output
  * @param {object} [options]
  * @param {number} [options.minRun=6] minimum consecutive repeats for a run
  * @param {number} [options.minCoveredChars=32] minimum chars a loop must cover
- * @param {number} [options.minCoveredRatio=0.35] minimum share of the text a
- *   consecutive run must cover (0..1)
+ * @param {number} [options.minCoveredRatio=0.35] minimum share of analyzed text
  * @param {number} [options.maxWindow=40] largest window size to try
+ * @param {number} [options.maxAnalysisChars=131072] maximum sampled chars
+ * @param {number} [options.maxDensityChars=65536] maximum density-map chars
  * @returns {object|undefined} loop description, or undefined when healthy
  */
 export function detectRepetitionLoop(text, options = {}) {
-  const source = compactForRepetition(text)
+  const sampled = sampleForRepetition(text, options.maxAnalysisChars)
+  const source = compactForRepetition(sampled)
   const total = source.length
   const minRun = options.minRun ?? 6
   const minCoveredChars = options.minCoveredChars ?? 32
@@ -48,15 +66,15 @@ export function detectRepetitionLoop(text, options = {}) {
   if (total < minCoveredChars) return undefined
   const coveredFloor = Math.max(minCoveredChars, total * minCoveredRatio)
 
-  // Pass 0: exact period — the whole text is one phrase repeated, possibly
-  // with a partial trailing repeat. Handles clean loops whose period is not
-  // one of the candidate windows below.
+  // Pass 0: exact period. Require semantic characters so an OCR column made of
+  // zeros/dashes is not mistaken for a model language loop.
   const maxPeriod = Math.min(64, Math.floor(total / 2))
   for (let period = 2; period <= maxPeriod; period++) {
     const full = Math.floor(total / period)
     const remainder = total % period
     if (full < minRun) continue
     const prefix = source.slice(0, period)
+    if (!informativeWindow(prefix)) continue
     let matches = true
     for (let block = 1; block < full; block++) {
       if (!source.startsWith(prefix, block * period)) {
@@ -78,7 +96,7 @@ export function detectRepetitionLoop(text, options = {}) {
     }
   }
 
-  // Pass 1: one window repeated consecutively, back-to-back.
+  // Pass 1: one language-bearing window repeated consecutively, back-to-back.
   for (const windowSize of CANDIDATE_WINDOWS) {
     if (windowSize > maxWindow || windowSize > Math.floor(total / 2)) continue
     let bestCount = 0
@@ -91,11 +109,11 @@ export function detectRepetitionLoop(text, options = {}) {
         count += 1
         cursor += windowSize
       }
-      if (count > bestCount) {
+      if (informativeWindow(candidate) && count > bestCount) {
         bestCount = count
         bestWindow = candidate
       }
-      i = cursor
+      i = Math.max(i + 1, cursor)
     }
     const covered = bestCount * windowSize
     if (bestCount >= minRun && covered >= coveredFloor) {
@@ -112,13 +130,20 @@ export function detectRepetitionLoop(text, options = {}) {
     }
   }
 
-  // Pass 2: one short token dominating the text without being consecutive
-  // (the alternating loop shape).
+  // Pass 2: one short language token dominating the text. Build maps only over
+  // a bounded slice, so high-entropy megabyte responses have a fixed ceiling.
+  const densityLimit = Math.max(
+    256,
+    Math.floor(Number(options.maxDensityChars) || DEFAULT_REPETITION_DENSITY_CHARS),
+  )
+  const densitySource = source.slice(0, densityLimit)
+  const densityTotal = densitySource.length
   for (const windowSize of [2, 3, 4]) {
     if (windowSize > maxWindow) continue
     const counts = new Map()
-    for (let i = 0; i + windowSize <= total; i++) {
-      const token = source.slice(i, i + windowSize)
+    for (let i = 0; i + windowSize <= densityTotal; i++) {
+      const token = densitySource.slice(i, i + windowSize)
+      if (!informativeWindow(token)) continue
       counts.set(token, (counts.get(token) ?? 0) + 1)
     }
     let topToken = ''
@@ -130,7 +155,7 @@ export function detectRepetitionLoop(text, options = {}) {
       }
     }
     const covered = topCount * windowSize
-    if (topCount >= minRun && covered >= Math.max(minCoveredChars, total * 0.5)) {
+    if (topCount >= minRun && covered >= Math.max(minCoveredChars, densityTotal * 0.5)) {
       return {
         looped: true,
         mode: 'token-density',
@@ -147,17 +172,13 @@ export function detectRepetitionLoop(text, options = {}) {
   return undefined
 }
 
-/**
- * Throw when the output is a repetition loop. The thrown Error carries no
- * status/code, so the vision chain's classifier maps it by message pattern;
- * the message intentionally includes a stable marker for that classifier.
- */
+/** Throw when the output is a repetition loop. */
 export function assertNoRepetitionLoop(text, backendKey) {
   const loop = detectRepetitionLoop(text)
   if (loop === undefined) return
   const label = backendKey ? ` (${backendKey})` : ''
   throw new Error(
     `${REPETITION_LOOP_MARKER}${label}: ${loop.repetitions} repeats of ${JSON.stringify(loop.window)} ` +
-      `(${loop.mode}) covering ${loop.coveredChars}/${loop.totalChars} chars; first ${loop.windowSize}-char window sampled from ${JSON.stringify(loop.sample)}`,
+      `(${loop.mode}) covering ${loop.coveredChars}/${loop.totalChars} analyzed chars; sampled from ${JSON.stringify(loop.sample)}`,
   )
 }