dsh-vision-router 2.0.0 → 2.1.0

package/lib/core-vision-surface.js

@@ -0,0 +1,124 @@
+import {
+  currentSessionSurfacePolicy,
+  resolveSessionSurfacePolicy,
+} from './session-surface-policy.js'
+
+const CORE_SURFACE_KEYS = Object.freeze([
+  'tool',
+  'rewriteImages',
+  'instantDescribe',
+  'autoActivateOnImage',
+  'structuredVisionBootstrap',
+])
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function own(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+function coreFlags(values) {
+  return {
+    toolAvailable: values.tool !== false,
+    rewriteEnabled: values.rewriteImages !== false,
+    instantDescribe: values.instantDescribe === true,
+    autoActivateOnImage: values.autoActivateOnImage !== false,
+    structuredBootstrap: values.structuredVisionBootstrap === true,
+  }
+}
+
+/**
+ * Explicit core-facing projection of the SessionSurfacePolicy.
+ *
+ * The returned object carries only the five config values that the historical
+ * Settings/config projection could override plus explicit booleans consumed by
+ * Core and the already-resolved image ownership facts. It deliberately cannot
+ * masquerade as a Settings service or a full plugin config object.
+ */
+export function projectCoreVisionSurface(config = {}, sessionPolicy) {
+  const value = isObject(config) ? config : {}
+  const policy = sessionPolicy && typeof sessionPolicy === 'object'
+    ? sessionPolicy
+    : resolveSessionSurfacePolicy({ config: value })
+  const overrides = isObject(policy.legacyConfigOverrides)
+    ? policy.legacyConfigOverrides
+    : {}
+  const projected = {}
+
+  for (const key of CORE_SURFACE_KEYS) {
+    projected[key] = own(overrides, key) ? overrides[key] : value[key]
+  }
+
+  return Object.freeze({
+    ownership: policy.ownership,
+    preserveRawImages: policy.preserveRawImages === true,
+    rewriteCurrentImages: policy.rewriteCurrentImages === true,
+    ...coreFlags(projected),
+    values: Object.freeze(projected),
+  })
+}
+
+/** Resolve an explicit core surface from an explicit ownership-policy input. */
+export function resolveCoreVisionSurface({
+  visionPolicy,
+  config = {},
+  schemaBootstrapping = false,
+} = {}) {
+  const value = isObject(config) ? config : {}
+  return projectCoreVisionSurface(
+    value,
+    resolveSessionSurfacePolicy({
+      visionPolicy,
+      config: value,
+      schemaBootstrapping,
+    }),
+  )
+}
+
+/** Resolve the current turn-local surface without exposing a Settings facade. */
+export function currentCoreVisionSurface(config = {}, options = {}) {
+  const value = isObject(config) ? config : {}
+  return projectCoreVisionSurface(
+    value,
+    currentSessionSurfacePolicy(value, {
+      schemaBootstrapping: options?.schemaBootstrapping === true,
+    }),
+  )
+}
+
+/**
+ * One explicit production seam for Core's five policy-derived switches.
+ *
+ * The config source stays live, but schema bootstrap is an internal lifecycle
+ * bit rather than a fake Settings/config value. Direct Core callers can keep
+ * their two-argument compatibility path; composition passes this runtime as
+ * the authoritative production surface.
+ */
+export function createCoreVisionSurfaceRuntime({ config = {} } = {}) {
+  let schemaBootstrapping = true
+
+  const current = () => {
+    let source = config
+    if (typeof config === 'function') {
+      try {
+        source = config()
+      } catch {
+        source = {}
+      }
+    }
+    return currentCoreVisionSurface(isObject(source) ? source : {}, {
+      schemaBootstrapping,
+    })
+  }
+
+  return Object.freeze({
+    current,
+    finishSchemaBootstrap() {
+      schemaBootstrapping = false
+    },
+  })
+}
+
+export const CORE_VISION_SURFACE_KEYS = CORE_SURFACE_KEYS

package/lib/depth-guidance.js

@@ -1,116 +1,140 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { runtimeLanguageFor } from './runtime-i18n.js'
 
 // 看图深度与场景引导（depth-guidance）。
 //
-// 移植自 dsh-vision 的「模板 + 路由」两层结构（prompts.py / vision_client.py）：
-// - 模板层：按大类各写一条引导（zoom_* 的等价物），彼此独立、无组合
-// - 档位层：fast/standard/deep/custom 只决定"深挖多少"（步骤/上限），不参与提示词组合
-// 因此这里是"模板集合"而非"提示词矩阵"——工作量 = 引导表 + 拼接函数。
+// 深度档位只决定模型如何查证，不再隐式决定调用次数：
+// - fast：整体优先，减少不必要的重复识别；
+// - standard：围绕用户问题按需查证；
+// - deep：主动做局部检查与交叉验证。
 //
-// 拼接规则（运行时）：
-//   guidance = 场景引导（按 visual_kind 查表）
-//            + general 时内容引导（按内容大类查表，纯提示词兜底）
-//            + 档位句（fast 附"档位不足"提示，搬 dsh-vision 回答节思想）
-// 语言模型的追问 question 由模型自己生成（现状已自由），本模块不生成。
+// 调用次数是独立的可选安全阀：visionDepthMaxCalls=0/空值表示不限，
+// 1-100 表示本轮成功深挖证据调用的硬上限。bootstrap 预识别不计入。
+// 旧配置 visionDepth=custom 继续兼容，按 standard 引导解释；正数
+// visionDepthMaxCalls 仍会作为独立次数上限生效。
 
 const MAX_OVERRIDE_CHARS = 2000
 const DEPTH_RUNTIME_CONTEXT = new AsyncLocalStorage()
 
-// index.js predates the custom tier and still normalizes an unknown depth to
-// standard before it calls the helpers below. Keep the public core untouched:
-// the entry-layer structured guard exposes the live settings through this
-// async-local scope, so both the old inner quota and the outer hardening guard
-// see one authoritative fast=1 / standard=2 / deep=4 / custom=N policy.
 export function runWithDepthConfig(config, execute) {
   if (typeof execute !== 'function') return undefined
   const value = config && typeof config === 'object' ? config : {}
   return DEPTH_RUNTIME_CONTEXT.run(value, execute)
 }
 
-function activeDepth(depth, customMax) {
+export function currentDepthRuntimeLocale() {
+  const value = DEPTH_RUNTIME_CONTEXT.getStore()?.__visionRouterLocale
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined
+}
+
+function strategyDepth(depth) {
   const runtime = DEPTH_RUNTIME_CONTEXT.getStore()
-  if (runtime && runtime.visionDepth === 'custom') {
-    return { depth: 'custom', customMax: runtime.visionDepthMaxCalls }
-  }
-  return { depth, customMax }
+  const candidate = runtime?.visionDepth ?? depth
+  return candidate === 'fast' || candidate === 'deep' ? candidate : 'standard'
 }
 
-function normalizeCustomMax(value) {
+function normalizeMaxCalls(value) {
   const number = Number(value)
-  if (!Number.isFinite(number) || number <= 0) return 0
+  if (!Number.isFinite(number) || number <= 0) return undefined
   return Math.min(100, Math.max(1, Math.floor(number)))
 }
 
-// 用 null-prototype 表避免异常 kind（如 constructor / __proto__）命中
-// Object.prototype 上的继承属性。
-const SCENE_GUIDANCE = Object.assign(Object.create(null), {
-  code: '检测到代码内容。代码必须逐字转写，建议分区域转写 + 语义确认，避免概括。',
-  document: '检测到文档内容。语义优先；仅当需要逐字引用（长文档/合同/表单）时才用 OCR。',
-  ui: '检测到界面内容。建议元素清单（detect）+ 关键元素定位（ground）。',
-  chat: '检测到聊天截图。关注气泡顺序与关键信息提取。',
-  // general 无固定场景引导——由 content_kind 内容引导接管（bootstrap 判出）
-  // mixed / unknown 无场景引导（mixed 走分支引导，unknown 放行）
+function effectiveMaxCalls(explicit) {
+  const runtime = DEPTH_RUNTIME_CONTEXT.getStore()
+  if (runtime && Object.prototype.hasOwnProperty.call(runtime, 'visionDepthMaxCalls')) {
+    return normalizeMaxCalls(runtime.visionDepthMaxCalls)
+  }
+  return normalizeMaxCalls(explicit)
+}
+
+const SCENE_GUIDANCE = Object.freeze({
+  zh: Object.assign(Object.create(null), {
+    code: '检测到代码内容。代码必须逐字转写，建议分区域转写 + 语义确认，避免概括。',
+    document: '检测到文档内容。语义优先；仅当需要逐字引用（长文档/合同/表单）时才用 OCR。',
+    ui: '检测到界面内容。建议元素清单（detect）+ 关键元素定位（ground）。',
+    chat: '检测到聊天截图。关注气泡顺序与关键信息提取。',
+  }),
+  en: Object.assign(Object.create(null), {
+    code: 'Code content detected. Transcribe code verbatim; use region-by-region transcription plus semantic verification instead of summarizing it.',
+    document: 'Document content detected. Prefer semantic understanding; use OCR only when verbatim quotation is required, such as for long documents, contracts, or forms.',
+    ui: 'UI content detected. Prefer an element inventory (detect) plus grounding of the important elements (ground).',
+    chat: 'Chat screenshot detected. Preserve message-bubble order and extract the important information.',
+  }),
+})
+
+const CONTENT_GUIDANCE = Object.freeze({
+  zh: Object.assign(Object.create(null), {
+    person: '图中主体为人物：关注身份/表情/数量/姿态/关系/穿着。',
+    animal: '图中主体为动物：关注物种/数量/状态/环境。',
+    plant: '图中主体为植物：关注种类/生长状态/环境。',
+    food: '图中主体为食物：关注菜品/食材/卖相/就餐场景。',
+    vehicle: '图中主体为交通工具：关注品牌/型号/颜色/新旧/牌照。',
+    machine: '图中主体为机器/设备：关注类型/用途/状态/铭牌。',
+    architecture: '图中主体为建筑：关注类型/风格/细节/年代。',
+    object: '图中主体为物品：关注名称/材质/用途/品牌/型号。',
+    scene: '图中主体为场景：关注场景类型/主体/前景背景/光线/天气。',
+    meme: '图中为表情包/梗图：关注模板、文字与表达含义。',
+  }),
+  en: Object.assign(Object.create(null), {
+    person: 'The main subject is a person or people: focus on identity, expression, count, posture, relationships, and clothing.',
+    animal: 'The main subject is an animal or animals: focus on species, count, condition, and environment.',
+    plant: 'The main subject is a plant or plants: focus on type, growth condition, and environment.',
+    food: 'The main subject is food: focus on the dish, ingredients, appearance, and dining context.',
+    vehicle: 'The main subject is a vehicle: focus on make, model, color, condition, and license plate when visible.',
+    machine: 'The main subject is a machine or device: focus on type, purpose, condition, and nameplate information.',
+    architecture: 'The main subject is architecture: focus on type, style, details, and period when inferable from visible evidence.',
+    object: 'The main subject is an object: focus on its name, material, purpose, brand, and model when visible.',
+    scene: 'The main subject is a scene: focus on scene type, subjects, foreground/background, lighting, and weather.',
+    meme: 'The image is a meme/reaction image: focus on the template, text, and intended meaning.',
+  }),
 })
 
-// ── 内容引导表（按 content_kind 大类；bootstrap 判出，纯提示词方向，无出口绑定）──
-// 能力上限由用户配置的后端链决定，本表只负责"问对方向"。
-const CONTENT_GUIDANCE = Object.assign(Object.create(null), {
-  person: '图中主体为人物：关注身份/表情/数量/姿态/关系/穿着。',
-  animal: '图中主体为动物：关注物种/数量/状态/环境。',
-  plant: '图中主体为植物：关注种类/生长状态/环境。',
-  food: '图中主体为食物：关注菜品/食材/卖相/就餐场景。',
-  vehicle: '图中主体为交通工具：关注品牌/型号/颜色/新旧/牌照。',
-  machine: '图中主体为机器/设备：关注类型/用途/状态/铭牌。',
-  architecture: '图中主体为建筑：关注类型/风格/细节/年代。',
-  object: '图中主体为物品：关注名称/材质/用途/品牌/型号。',
-  scene: '图中主体为场景：关注场景类型/主体/前景背景/光线/天气。',
-  meme: '图中为表情包/梗图：关注模板、文字与表达含义。',
+const GENERAL_FALLBACK_GUIDANCE = Object.freeze({
+  zh: '检测到未能明确归类的图。请先判断图中主体类别（人物/动物/植物/食物/交通工具/机器/建筑/物品/场景/表情包），再按该主体方向深挖（深挖时由你自行生成针对性问题）。',
+  en: 'The image could not be classified confidently. First identify the main subject category (person, animal, plant, food, vehicle, machine, architecture, object, scene, or meme), then deepen the inspection in that direction and generate targeted questions as needed.',
 })
 
-// general 且 content_kind 未知时的通用兜底（要求模型自行判断主体方向）。
-const GENERAL_FALLBACK_GUIDANCE =
-  '检测到未能明确归类的图。请先判断图中主体类别（人物/动物/植物/食物/交通工具/机器/建筑/物品/场景/表情包），' +
-  '再按该主体方向深挖（深挖时由你自行生成针对性问题）。'
+const DEPTH_COPY = Object.freeze({
+  zh: Object.freeze({
+    fast: '本轮看图策略为快速：先做整体判断，优先使用已有视觉基线；只有关键证据不确定，或用户明确要求精确定位/逐字信息时，再调用必要的视觉工具。避免重复泛化识别。',
+    standard: '本轮看图策略为标准：围绕用户问题按需查证关键区域；需要时使用定位、裁剪、OCR、比对等工具补充或验证证据。证据充分后直接作答，不必为了流程继续调用。',
+    deep: '本轮看图策略为细致：主动检查关键局部并做交叉验证；对重要文字、位置、细节或差异，按需组合定位、裁剪、OCR、比对等工具，重要结论尽量由独立证据相互印证后再作答。',
+  }),
+  en: Object.freeze({
+    fast: 'Vision strategy is Quick for this turn: start from the whole-image judgment and reuse the existing visual baseline. Call an additional vision tool only when key evidence is uncertain or the user explicitly needs precise localization or verbatim text. Avoid repeating generic recognition.',
+    standard: "Vision strategy is Standard for this turn: verify the key regions required by the user's question as needed. Use grounding, cropping, OCR, comparison, or other tools when they can add or verify evidence. Answer once the evidence is sufficient; do not keep calling tools just to satisfy a workflow.",
+    deep: 'Vision strategy is Thorough for this turn: proactively inspect important regions and cross-check key claims. Combine grounding, cropping, OCR, comparison, and other precision tools as needed for important text, positions, details, or differences, and prefer independent evidence to corroborate important conclusions before answering.',
+  }),
+})
 
-// ── 档位句 ────────────────────────────────────────────────────────────────
-const DEPTH_COPY = {
-  fast: '本轮深度档位为 fast：仅做初步判断 + 1 次深挖即可；若你的问题需要深度定向识别，请告知用户升级档位。',
-  standard: '本轮深度档位为 standard：深挖 1-2 次即可；第 2 次之后会停止新的证据调用。',
-  deep: '本轮深度档位为 deep：可做 2-4 次充分深挖（定位→裁剪→比对→OCR 等）后再作答。',
+function languageFor(locale) {
+  return runtimeLanguageFor(locale ?? currentDepthRuntimeLocale(), 'zh')
 }
 
 /**
- * 深度硬上限：fast=1、standard=2、deep=4。bootstrap 那 1 遍不计入。
- * custom=N（1-100）时 N 是本轮成功深挖调用的硬上限；custom=0/空值
- * 表示不设置次数上限。保存过的 custom 数值在切回内置档位后保留但不生效。
+ * Optional independent call cap. The depth strategy never supplies a cap.
+ * The depth parameter is retained for API/backward compatibility.
  */
-export function depthLimitFor(depth, customMax) {
-  const active = activeDepth(depth, customMax)
-  if (active.depth === 'custom') {
-    const custom = normalizeCustomMax(active.customMax)
-    return custom > 0 ? custom : undefined
-  }
-  if (active.depth === 'fast') return 1
-  if (active.depth === 'deep') return 4
-  return 2
+export function depthLimitFor(_depth, maxCalls) {
+  return effectiveMaxCalls(maxCalls)
 }
 
-/** 档位句，与 depthLimitFor 的实际硬限制保持一致。 */
-export function depthCopyFor(depth, customMax) {
-  const active = activeDepth(depth, customMax)
-  if (active.depth === 'custom') {
-    const custom = normalizeCustomMax(active.customMax)
-    return custom > 0
-      ? `本轮已自定义深挖上限为 ${custom} 次；达到上限后请基于已有证据作答。`
-      : '本轮已选择自定义深挖：不设置次数上限；请只在能新增或验证证据时继续调用视觉工具。'
-  }
-  return DEPTH_COPY[active.depth === 'fast' || active.depth === 'deep' ? active.depth : 'standard'] || ''
+/** Strategy guidance plus an optional, separately configured call-cap note. */
+export function depthCopyFor(depth, maxCalls, locale) {
+  const language = languageFor(locale)
+  const strategy = strategyDepth(depth)
+  const strategyCopy = DEPTH_COPY[language][strategy] || DEPTH_COPY[language].standard
+  const cap = effectiveMaxCalls(maxCalls)
+  if (cap === undefined) return strategyCopy
+  const capCopy = language === 'en'
+    ? `A separate deep-dive call cap is enabled for this turn: at most ${cap} successful evidence calls. The bootstrap pre-scan does not count, and failed or empty-evidence calls do not consume the cap.`
+    : `本轮另启用了深挖次数上限：最多 ${cap} 次成功证据调用；bootstrap 预识别不计入，失败或空证据调用不占次数。`
+  return `${strategyCopy}\n${capCopy}`
 }
 
 /** 查表：覆盖表（guidanceOverrides）优先，其次内置表，最后 fallback。 */
 function resolveGuidance(kind, overrides, table, fallback = '') {
   if (Array.isArray(overrides)) {
-    // 后写覆盖前写：重复 kind 的导入/编辑结果确定为 last-wins。
     for (let i = overrides.length - 1; i >= 0; i--) {
       const entry = overrides[i]
       if (entry && entry.kind === kind && typeof entry.text === 'string' && entry.text.trim() !== '') {
@@ -122,34 +146,34 @@ function resolveGuidance(kind, overrides, table, fallback = '') {
 }
 
 /** 场景引导：按 visual_kind 查表（覆盖优先）；无则空串（不硬套）。 */
-export function sceneGuidanceFor(visualKind, overrides) {
-  return resolveGuidance(visualKind, overrides, SCENE_GUIDANCE)
+export function sceneGuidanceFor(visualKind, overrides, locale) {
+  return resolveGuidance(visualKind, overrides, SCENE_GUIDANCE[languageFor(locale)])
 }
 
-/** 内容引导：按内容大类查表（覆盖优先）；无则空串。 */
-export function contentGuidanceFor(contentKind, overrides) {
-  return resolveGuidance(contentKind, overrides, CONTENT_GUIDANCE)
+/** 内容引导：按 content_kind 大类查表（覆盖优先）；无则空串。 */
+export function contentGuidanceFor(contentKind, overrides, locale) {
+  return resolveGuidance(contentKind, overrides, CONTENT_GUIDANCE[languageFor(locale)])
 }
 
 /**
- * 拼接一条完整的深挖引导（场景/内容 + 档位）。
+ * 拼接一条完整的深挖引导（场景/内容 + 策略 + 可选独立调用上限）。
  * general 时用 content_kind 内容引导（精确方向）；content_kind 未知 → 通用兜底句。
  * guidanceOverrides：可配置的引导覆盖表（默认 undefined = 内置表）。
- * @param {object} opts - { visualKind, contentKind, depth, guidanceOverrides, customMax }
- * @returns {string} 空串表示无引导（放行）
+ * locale：显式传入优先；否则跟随当前 Host runtime locale；缺失时保留历史 zh 默认。
  */
-export function renderDepthGuidance({ visualKind, contentKind, depth, guidanceOverrides, customMax } = {}) {
-  const depthCopy = depthCopyFor(depth, customMax)
+export function renderDepthGuidance({ visualKind, contentKind, depth, guidanceOverrides, customMax, maxCalls, locale } = {}) {
+  const language = languageFor(locale)
+  const callCap = maxCalls === undefined ? customMax : maxCalls
+  const depthCopy = depthCopyFor(depth, callCap, language)
   if (!depthCopy) return ''
-  const scene = sceneGuidanceFor(visualKind, guidanceOverrides)
-  const content = contentGuidanceFor(contentKind, guidanceOverrides)
+  const scene = sceneGuidanceFor(visualKind, guidanceOverrides, language)
+  const content = contentGuidanceFor(contentKind, guidanceOverrides, language)
   const parts = []
   if (scene) {
     parts.push(scene)
   } else if (visualKind === 'general') {
-    // general（媒介无引导）：bootstrap 判出的 content_kind 给精确方向；未知则兜底
-    parts.push(content || GENERAL_FALLBACK_GUIDANCE)
+    parts.push(content || GENERAL_FALLBACK_GUIDANCE[language])
   }
   parts.push(depthCopy)
-  return parts.join('')
+  return parts.join('\n')
 }

package/lib/doctor-cli-p0.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { run as runBaseDoctor } from './doctor-cli.js'
+import {
+  formatDshHostCapability,
+  normalizeDshHostCapabilities,
+} from './dsh-host-capabilities.js'
+import {
+  DSH_SUPPORT_WINDOW,
+  formatDshSupportWindowLines,
+  supportWindowUpgradeAdvice,
+} from './dsh-support-window.js'
+
+const HOST_CAPABILITIES_PATH = '/_dsh/vision-router/host-capabilities'
+
+function commandOf(argv) {
+  const first = argv.find((value) => typeof value === 'string' && !value.startsWith('-'))
+  return first && ['doctor', 'repair', 'repair-sessions'].includes(first) ? first : 'doctor'
+}
+
+function runtimeOptions(argv, env) {
+  let enabled = true
+  let baseUrl = env.DSH_WEB_URL || 'http://127.0.0.1:3080'
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index]
+    if (value === '--no-runtime') enabled = false
+    if (value === '--runtime-url' && argv[index + 1]) {
+      baseUrl = argv[index + 1]
+      index += 1
+    } else if (typeof value === 'string' && value.startsWith('--runtime-url=')) {
+      baseUrl = value.slice('--runtime-url='.length)
+    }
+  }
+  return { enabled, baseUrl }
+}
+
+function unknownSnapshot() {
+  return normalizeDshHostCapabilities({})
+}
+
+export async function probeDoctorHostCapabilities({ baseUrl, fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const normalized = new URL(baseUrl || 'http://127.0.0.1:3080')
+    normalized.pathname = HOST_CAPABILITIES_PATH
+    normalized.search = ''
+    normalized.hash = ''
+    if (typeof fetchImpl !== 'function') {
+      return { ok: false, source: 'runtime-unavailable', capabilities: unknownSnapshot() }
+    }
+    const response = await fetchImpl(normalized, {
+      method: 'GET',
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(1500),
+    })
+    if (!response.ok) {
+      return {
+        ok: false,
+        source: 'runtime-route-unavailable',
+        status: response.status,
+        capabilities: unknownSnapshot(),
+      }
+    }
+    const body = await response.json()
+    return {
+      ok: true,
+      source: 'live-runtime',
+      capabilities: normalizeDshHostCapabilities(body?.capabilities),
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      source: 'runtime-unavailable',
+      error: error instanceof Error ? error.message : String(error),
+      capabilities: unknownSnapshot(),
+    }
+  }
+}
+
+function capabilityLines(probe) {
+  const c = probe.capabilities
+  return [
+    'DSH Host capabilities:',
+    `  batch attachments: ${formatDshHostCapability(c.batchAttachments)}`,
+    `  max image dimension: ${formatDshHostCapability(c.maxImageDimension)}`,
+    `  adapter registration: ${formatDshHostCapability(c.adapterRegistration)}`,
+    `  registration replace: ${formatDshHostCapability(c.registrationReplace)}`,
+    `  jobs: ${formatDshHostCapability(c.jobs)}`,
+    `  surface replacement: ${formatDshHostCapability(c.surfaceReplacement)}`,
+    `  settings live namespace: ${formatDshHostCapability(c.settingsLiveNamespace)}`,
+    `  settings web exposure: ${formatDshHostCapability(c.settingsWebExposure)}`,
+    `  prepareCall: ${formatDshHostCapability(c.prepareCall)}`,
+    `  tool registration: ${formatDshHostCapability(c.toolRegistration)}`,
+    `  tool execution: ${formatDshHostCapability(c.toolExecution)}`,
+    `  source: ${probe.source}`,
+    ...formatDshSupportWindowLines(c),
+  ]
+}
+
+function isJsonRequest(argv) {
+  return argv.includes('--json')
+}
+
+function isHelpRequest(argv) {
+  return argv.includes('--help') || argv.includes('-h')
+}
+
+/**
+ * P0 Doctor wrapper. Existing health semantics and exit codes stay owned by the
+ * established Doctor implementation; Host-capability diagnostics and P3's
+ * support-window policy are appended as advisory data and therefore can never
+ * turn a healthy runtime unhealthy.
+ */
+export async function run(argv = process.argv.slice(2), io = console, env = process.env) {
+  if (commandOf(argv) !== 'doctor' || isHelpRequest(argv)) {
+    return runBaseDoctor(argv, io, env)
+  }
+
+  const runtime = runtimeOptions(argv, env)
+  const probe = runtime.enabled
+    ? await probeDoctorHostCapabilities({ baseUrl: runtime.baseUrl })
+    : { ok: false, source: 'runtime-probe-disabled', capabilities: unknownSnapshot() }
+
+  if (!isJsonRequest(argv)) {
+    const code = await runBaseDoctor(argv, io, env)
+    for (const line of capabilityLines(probe)) io.log(line)
+    return code
+  }
+
+  const logs = []
+  const errors = []
+  const capture = {
+    log(...values) { logs.push(values.map(String).join(' ')) },
+    error(...values) { errors.push(values.map(String).join(' ')) },
+  }
+  const code = await runBaseDoctor(argv, capture, env)
+  for (const line of errors) io.error(line)
+
+  if (logs.length === 1) {
+    try {
+      const report = JSON.parse(logs[0])
+      report.hostCapabilities = probe.capabilities
+      report.hostCapabilitiesSource = probe.source
+      report.hostSupportWindow = DSH_SUPPORT_WINDOW
+      report.hostSupportAdvice = supportWindowUpgradeAdvice(probe.capabilities)
+      io.log(JSON.stringify(report, null, 2))
+      return code
+    } catch {
+      // Fall through to the untouched output below.
+    }
+  }
+  for (const line of logs) io.log(line)
+  return code
+}
+
+export function isCliEntry(entry, moduleUrl = import.meta.url) {
+  if (typeof entry !== 'string' || entry.trim() === '') return false
+  const real = (value) => {
+    try { return realpathSync(value.startsWith('file:') ? fileURLToPath(value) : value) } catch { return value }
+  }
+  return real(entry) === real(moduleUrl)
+}
+
+if (isCliEntry(process.argv[1])) {
+  const code = await run()
+  if (Number.isInteger(code) && code !== 0) process.exitCode = code
+}

package/lib/doctor-cli.js

@@ -4,6 +4,7 @@ import { realpathSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { doctorProfiles, resolveDshHome } from './doctor.js'
 import { inspectPlatform, probeRuntime, supportReport } from './doctor-runtime.js'
+import { inspectDoctorVisionLimits, formatDoctorVisionLimits } from './doctor-vision-limits.js'
 import { repairLegacySessionLogs } from './legacy-session-repair.js'
 
 function usage() {
@@ -206,6 +207,7 @@ export async function run(argv = process.argv.slice(2), io = console, env = proc
     .filter((item) => item.installation?.applicable && item.profileDir)
     .map((item) => item.profileDir)
   const platform = inspectPlatform({ profileDirs: applicableDirs })
+  const visionLimits = inspectDoctorVisionLimits(profileReport.log?.file)
   let sessions
   if (options.sessions) sessions = repairLegacySessionLogs({ dshHome, fix: false })
 
@@ -215,6 +217,7 @@ export async function run(argv = process.argv.slice(2), io = console, env = proc
 
   if (options.json) {
     const report = supportReport({ profileReport, runtime, platform, sessions })
+    report.visionLimits = visionLimits
     report.ok = overallOk
     io.log(JSON.stringify(report, null, 2))
     return overallOk ? 0 : 1
@@ -231,6 +234,10 @@ export async function run(argv = process.argv.slice(2), io = console, env = proc
   if (profileReport.log?.historicalSettingsSaveFailures?.length > 0) {
     io.log(`! Historical settings save failures exist (${profileReport.log.historicalSettingsSaveFailures.length}); none are attributed to the latest plugin start.`)
   }
+  for (const line of formatDoctorVisionLimits(visionLimits)) {
+    if (line.startsWith('WARN:')) io.log(`! ${line.slice('WARN:'.length).trim()}`)
+    else io.log(`✓ ${line}`)
+  }
 
   if (runtime) {
     if (!runtime.reachable) io.log(`– Runtime probe: DSH not reachable at ${runtime.baseUrl}; offline checks still completed.`)