From 7fe9c06fa64125c97026c0b958b19675312358de Mon Sep 17 00:00:00 2001
From: Kaige-Gao <michellegkg@163.com>
Date: Wed, 23 Sep 2026 16:16:30 +0800
Subject: [PATCH 1/6] feat(chat): preview image links on hover and expand
 inline images

---
 .../clickable-links-gallery/ui.expected.md    |  3 +-
 .../expected/markdown-images/ui.expected.md   | 27 ++++--
 .../file-reference-prompt.expected.md         |  2 +-
 apps/web/tests/markdown-images.e2e.ts         | 40 +++++++--
 .../client/ui-attachment/README.i18n.yaml     |  4 +-
 packages/client/ui-attachment/README.md       |  2 +-
 packages/client/ui-attachment/README.zh.md    |  2 +-
 .../client/ui-attachment/src/MessageImage.tsx |  4 +-
 .../src/client/ComposerAttachments.tsx        |  2 +-
 .../client/ui-attachment/src/client/labels.ts |  2 +-
 .../tests/image-lightbox.client.spec.tsx      |  2 +-
 packages/client/ui-chat/README.i18n.yaml      |  4 +-
 packages/client/ui-chat/README.md             |  2 +
 packages/client/ui-chat/README.zh.md          |  2 +
 .../src/client/chat/AssistantMarkdown.tsx     | 12 +--
 .../ui-chat/src/client/chat/ChatView.tsx      | 10 ++-
 packages/client/ui-chat/src/client/locale.ts  | 10 +++
 ...stant-markdown-path-images.client.spec.tsx | 11 ++-
 .../client/ui-deliverables/README.i18n.yaml   |  4 +-
 packages/client/ui-deliverables/README.md     |  2 +-
 packages/client/ui-deliverables/README.zh.md  |  2 +-
 packages/client/ui-deliverables/src/index.ts  |  4 +-
 .../ui-deliverables/tests/prompt.host.spec.ts |  2 +-
 .../client/ui-primitives/README.i18n.yaml     |  4 +-
 packages/client/ui-primitives/README.md       |  3 +
 packages/client/ui-primitives/README.zh.md    |  3 +
 .../ui-primitives/src/HoverCard.module.css    | 11 +++
 .../client/ui-primitives/src/HoverCard.tsx    | 31 +++++--
 .../src/ImageLightbox.module.css              |  5 +-
 .../src/ImageLightbox.tsx                     |  5 +-
 .../ui-primitives/src/ImagePreview.module.css | 24 +++++
 .../client/ui-primitives/src/ImagePreview.tsx | 39 +++++++++
 packages/client/ui-primitives/src/index.ts    |  3 +
 .../src/markdown/MarkdownDelegate.tsx         |  9 +-
 .../src/markdown/MarkdownText.module.css      | 23 +++++
 .../src/markdown/local-image-syntax.ts        | 28 ++++++
 .../ui-primitives/src/markdown/parse.ts       |  9 +-
 .../ui-primitives/src/markdown/render.tsx     | 72 ++++++++++-----
 .../tests/image-preview.client.spec.tsx       | 19 ++++
 .../markdown-image-entries.client.spec.tsx    | 87 +++++++++++++++++++
 .../src/client/markdown/path-images.ts        |  4 +-
 packages/util/workspace-path/README.i18n.yaml |  4 +-
 packages/util/workspace-path/README.md        |  2 +
 packages/util/workspace-path/README.zh.md     |  2 +
 packages/util/workspace-path/src/index.ts     | 12 +++
 .../tests/file-media-url.spec.ts              | 20 +++++
 .../system-prompt.expected.md                 |  2 +-
 .../web/ptc-round/system-prompt.expected.md   |  2 +-
 48 files changed, 492 insertions(+), 86 deletions(-)
 rename packages/client/{ui-attachment => ui-primitives}/src/ImageLightbox.module.css (86%)
 rename packages/client/{ui-attachment => ui-primitives}/src/ImageLightbox.tsx (90%)
 create mode 100644 packages/client/ui-primitives/src/ImagePreview.module.css
 create mode 100644 packages/client/ui-primitives/src/ImagePreview.tsx
 create mode 100644 packages/client/ui-primitives/src/markdown/local-image-syntax.ts
 create mode 100644 packages/client/ui-primitives/tests/image-preview.client.spec.tsx
 create mode 100644 packages/client/ui-primitives/tests/markdown-image-entries.client.spec.tsx
 create mode 100644 packages/util/workspace-path/tests/file-media-url.spec.ts

diff --git a/apps/web/tests/expected/clickable-links-gallery/ui.expected.md b/apps/web/tests/expected/clickable-links-gallery/ui.expected.md
index ab3230e5bd..120dd9b7ee 100644
--- a/apps/web/tests/expected/clickable-links-gallery/ui.expected.md
+++ b/apps/web/tests/expected/clickable-links-gallery/ui.expected.md
@@ -137,7 +137,8 @@
   - code: notes.md
   - text: untouched.
 - paragraph:
-  - img "Token preview"
+  - 'button "View full image: Token preview"':
+    - img "Token preview"
 - text: css
 - button "Wrap lines" [pressed]
 - button "Copy"
diff --git a/apps/web/tests/expected/markdown-images/ui.expected.md b/apps/web/tests/expected/markdown-images/ui.expected.md
index 199f2afb89..31dee5c21a 100644
--- a/apps/web/tests/expected/markdown-images/ui.expected.md
+++ b/apps/web/tests/expected/markdown-images/ui.expected.md
@@ -11,15 +11,28 @@
 - button "Took {{duration}}" [disabled]
 - heading "Markdown images" [level=2]
 - paragraph:
-  - img "Remote test image"
-- paragraph: Local test image
+  - 'button "View full image: Remote test image"':
+    - img "Remote test image"
 - paragraph:
-  - img "Workspace test image"
-- paragraph: Oversized image
+  - 'button "View full image: Local test image"':
+    - img "Local test image"
 - paragraph:
-  - img "Outside workspace image"
-- paragraph: Missing image
-- paragraph: {{cwd}}/corrupt.png
+  - 'button "View full image: Workspace test image"':
+    - img "Workspace test image"
+- paragraph:
+  - button "View comparison"
+- paragraph:
+  - 'button "View full image: Space path"':
+    - img "Space path"
+- paragraph:
+  - 'button "View full image: Encoded path"':
+    - img "Encoded path"
+- paragraph: Image preview unavailable · Oversized image
+- paragraph:
+  - 'button "View full image: Outside workspace image"':
+    - img "Outside workspace image"
+- paragraph: Image preview unavailable · Missing image
+- paragraph: Image preview unavailable · {{cwd}}/corrupt.png
 - paragraph: REMOTE_IMAGE_DONE
 - button "Copy"
 - button "Good response"
diff --git a/apps/web/tests/expected/web-runtime-context/file-reference-prompt.expected.md b/apps/web/tests/expected/web-runtime-context/file-reference-prompt.expected.md
index f4bdf601f8..7a9e1faff5 100644
--- a/apps/web/tests/expected/web-runtime-context/file-reference-prompt.expected.md
+++ b/apps/web/tests/expected/web-runtime-context/file-reference-prompt.expected.md
@@ -1 +1 @@
-Prefer showing the primary results within your final response alongside a brief explanation. Markdown file links such as [Report](path/to/report.html) open the file in the sidebar preview. For images, you can add an inline preview such as ![Preview](/absolute/path/image.png); include a file link as well so the image remains accessible in clients that cannot display it inline. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, especially Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
+Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
diff --git a/apps/web/tests/markdown-images.e2e.ts b/apps/web/tests/markdown-images.e2e.ts
index b8f18c6c67..ed93628d8b 100644
--- a/apps/web/tests/markdown-images.e2e.ts
+++ b/apps/web/tests/markdown-images.e2e.ts
@@ -1,5 +1,5 @@
 // Real browser image loading and failure fallbacks through the shipped Web composition.
-import { open, writeFile } from 'node:fs/promises'
+import { mkdir, open, writeFile } from 'node:fs/promises'
 import { createServer, type Server } from 'node:http'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -112,6 +112,12 @@ function markdownImageFixture(remoteUrl: string, outsidePath: string): string {
           '',
           `![${WORKSPACE_ALT}]({{cwd}}/valid.png)`,
           '',
+          '[View comparison](./valid.png)',
+          '',
+          '![Space path]({{cwd}}/test workspace/测试图.png)',
+          '',
+          '![Encoded path]({{cwd}}/test%20workspace/测试图.png)',
+          '',
           '![Oversized image]({{cwd}}/oversized.png)',
           '',
           `![Outside workspace image](${outsidePath})`,
@@ -164,6 +170,9 @@ describe('web e2e: Markdown image rendering', () => {
     imageOrigin = await startImageOrigin()
     scaffold = await launchWebScaffold({})
     await writeFile(join(scaffold.workspaceCwd, 'valid.png'), PNG)
+    await writeFile(join(scaffold.workspaceCwd, 'local-image.png'), PNG)
+    await mkdir(join(scaffold.workspaceCwd, 'test workspace'))
+    await writeFile(join(scaffold.workspaceCwd, 'test workspace/测试图.png'), PNG)
     await writeFile(join(scaffold.workspaceCwd, 'corrupt.png'), 'invalid image')
     const oversized = await open(join(scaffold.workspaceCwd, 'oversized.png'), 'w')
     try {
@@ -237,11 +246,13 @@ describe('web e2e: Markdown image rendering', () => {
       borderRadius: '8px',
       decoding: 'async',
       loading: 'lazy',
-      maxWidth: '100%',
+      maxWidth: 'min(100%, 640px)',
       referrerPolicy: 'no-referrer',
     })
-    expect(await page.getByRole('img', { name: LOCAL_ALT }).count()).toBe(0)
-    expect(await page.getByText(LOCAL_ALT, { exact: true }).count()).toBe(1)
+    await expect.poll(() => page.getByRole('img', { name: LOCAL_ALT }).evaluate(element => (element as HTMLImageElement).naturalWidth)).toBe(1)
+    for (const name of ['Space path', 'Encoded path']) {
+      await expect.poll(() => page.getByRole('img', { name, exact: true }).evaluate(element => (element as HTMLImageElement).naturalWidth)).toBe(1)
+    }
     expect(imageOrigin.requests).toEqual([{ path: '/image.png', referer: undefined }])
 
     const workspaceImage = page.getByRole('img', { name: WORKSPACE_ALT })
@@ -253,23 +264,40 @@ describe('web e2e: Markdown image rendering', () => {
     const outsideImage = page.getByRole('img', { name: 'Outside workspace image' })
     await expect.poll(() => outsideImage.evaluate(element => (element as HTMLImageElement).naturalWidth)).toBe(1)
     for (const alt of ['Oversized image', 'Missing image']) {
-      await page.getByText(alt, { exact: true }).waitFor()
+      await page.getByText(`Image preview unavailable · ${alt}`, { exact: true }).waitFor()
       expect(await page.getByRole('img', { name: alt }).count()).toBe(0)
     }
-    await page.getByText(join(scaffold.workspaceCwd, 'corrupt.png'), { exact: true }).waitFor()
+    await page.getByText(`Image preview unavailable · ${join(scaffold.workspaceCwd, 'corrupt.png')}`, { exact: true }).waitFor()
     expect(mediaResponses).toEqual(new Map([
       [join(scaffold.workspaceCwd, 'valid.png'), 200],
+      [`${scaffold.workspaceCwd}/./local-image.png`, 200],
+      [join(scaffold.workspaceCwd, 'test workspace/测试图.png'), 200],
       [join(scaffold.workspaceCwd, 'oversized.png'), 413],
       [join(scaffold.persistenceRoot, 'outside.png'), 200],
       [join(scaffold.workspaceCwd, 'missing.png'), 404],
       [join(scaffold.workspaceCwd, 'corrupt.png'), 200],
     ]))
 
+    await page.getByRole('button', { name: `View full image: ${WORKSPACE_ALT}`, exact: true }).click()
+    const lightbox = page.getByRole('dialog', { name: 'Image preview', exact: true })
+    await lightbox.waitFor()
+    await lightbox.getByRole('button', { name: 'Close image preview' }).click()
+    await lightbox.waitFor({ state: 'detached' })
+    const link = page.getByRole('button', { name: 'View comparison', exact: true })
+    await link.hover()
+    const hoverImage = page.getByRole('img', { name: './valid.png', exact: true })
+    await hoverImage.waitFor()
+    await expect.poll(() => hoverImage.evaluate(element => (element as HTMLImageElement).naturalWidth)).toBe(1)
+    await link.press('Escape')
+    await hoverImage.waitFor({ state: 'detached' })
+
     const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
       .split(SEED_ID).join('{{seededId}}')
     await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
+    await link.click()
+    await expect.poll(() => page.locator('[data-image-preview] img').evaluate(element => (element as HTMLImageElement).naturalWidth)).toBe(1)
   }, 60_000)
 })
diff --git a/packages/client/ui-attachment/README.i18n.yaml b/packages/client/ui-attachment/README.i18n.yaml
index 0fad5492e0..a3dcf88ee8 100644
--- a/packages/client/ui-attachment/README.i18n.yaml
+++ b/packages/client/ui-attachment/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-attachment/README.md
-README.md: 5a3e697189936a79df19ff9b976f06e0dd6191fb
-README.zh.md: 4168650770f42e7b94146041f37ffc440a5ec52e
+README.md: af2ed79cc2ede546db06187df4750b9d0fa698dd
+README.zh.md: 64d12869c5038ceb19675d554f9055411cfac433
diff --git a/packages/client/ui-attachment/README.md b/packages/client/ui-attachment/README.md
index 5a3e697189..af2ed79cc2 100644
--- a/packages/client/ui-attachment/README.md
+++ b/packages/client/ui-attachment/README.md
@@ -58,7 +58,7 @@ The plugin waits for `conversation.input.attachments`, `conversation.message.ima
 | [`src/AttachmentRail.tsx`](src/AttachmentRail.tsx) | Horizontal attachment overflow, wheel translation, edge arrows |
 | [`src/client/MessageImages.tsx`](src/client/MessageImages.tsx) | Per-message gallery + lightbox assembly |
 | [`src/MessageImage.tsx`](src/MessageImage.tsx) | Single image sizing, load/retry, click-to-open; local submission-echo previews render their object URL directly |
-| [`src/ImageLightbox.tsx`](src/ImageLightbox.tsx) | Document-level modal preview over the shared mask |
+| [`ImageLightbox`](../ui-primitives/src/ImageLightbox.tsx) | Document-level modal preview over the shared mask |
 | [`src/DropOverlay.tsx`](src/DropOverlay.tsx) | Pointer-inert drag invitation portal |
 
 </details>
diff --git a/packages/client/ui-attachment/README.zh.md b/packages/client/ui-attachment/README.zh.md
index 4168650770..64d12869c5 100644
--- a/packages/client/ui-attachment/README.zh.md
+++ b/packages/client/ui-attachment/README.zh.md
@@ -58,7 +58,7 @@ Trajectory 附件行使用 48px 方形缩略图，完整缩放图片而不裁剪
 | [`src/AttachmentRail.tsx`](src/AttachmentRail.tsx) | 附件横向溢出、滚轮转换、边缘箭头 |
 | [`src/client/MessageImages.tsx`](src/client/MessageImages.tsx) | 每消息画廊＋灯箱的组装 |
 | [`src/MessageImage.tsx`](src/MessageImage.tsx) | 单图尺寸、加载／重试、点击打开；本地提交回显预览直接显示其 object URL |
-| [`src/ImageLightbox.tsx`](src/ImageLightbox.tsx) | 铺在共享遮罩上的文档级模态预览 |
+| [`ImageLightbox`](../ui-primitives/src/ImageLightbox.tsx) | 铺在共享遮罩上的文档级模态预览 |
 | [`src/DropOverlay.tsx`](src/DropOverlay.tsx) | 不接收指针事件的拖放提示 portal |
 
 </details>
diff --git a/packages/client/ui-attachment/src/MessageImage.tsx b/packages/client/ui-attachment/src/MessageImage.tsx
index caf8fe08f8..7f350bbc94 100644
--- a/packages/client/ui-attachment/src/MessageImage.tsx
+++ b/packages/client/ui-attachment/src/MessageImage.tsx
@@ -1,8 +1,8 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import { IconLoadingOutlineRegular, IconRefreshOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
-import { ImageLightbox } from './ImageLightbox.tsx'
-import type { ImageLightboxLabels } from './ImageLightbox.tsx'
+import { ImageLightbox } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ImageLightboxLabels } from '@deepseek-ai/dsh-client-ui-primitives'
 import css from './MessageImage.module.css'
 
 /** Loads a session-authorized durable image URL and may expose a cached URL synchronously. */
diff --git a/packages/client/ui-attachment/src/client/ComposerAttachments.tsx b/packages/client/ui-attachment/src/client/ComposerAttachments.tsx
index 7c9054890d..0065410b9d 100644
--- a/packages/client/ui-attachment/src/client/ComposerAttachments.tsx
+++ b/packages/client/ui-attachment/src/client/ComposerAttachments.tsx
@@ -7,7 +7,7 @@ import { AttachmentRail } from '../AttachmentRail.tsx'
 import type { AttachmentRailItem } from '../AttachmentRail.tsx'
 import { DropOverlay } from '../DropOverlay.tsx'
 import { FileCard } from '../FileCard.tsx'
-import { ImageLightbox } from '../ImageLightbox.tsx'
+import { ImageLightbox } from '@deepseek-ai/dsh-client-ui-primitives'
 import { attachmentRailLabels, dropOverlayLabels, fileCardLabels, lightboxLabels } from './labels.ts'
 import { installDocumentDropEvents } from './drop-events.ts'
 import css from './ComposerAttachments.module.css'
diff --git a/packages/client/ui-attachment/src/client/labels.ts b/packages/client/ui-attachment/src/client/labels.ts
index 990f8959c7..257a362d97 100644
--- a/packages/client/ui-attachment/src/client/labels.ts
+++ b/packages/client/ui-attachment/src/client/labels.ts
@@ -2,7 +2,7 @@ import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 import type { AttachmentRailLabels } from '../AttachmentRail.tsx'
 import type { DropOverlayLabels } from '../DropOverlay.tsx'
 import type { FileCardLabels } from '../FileCard.tsx'
-import type { ImageLightboxLabels } from '../ImageLightbox.tsx'
+import type { ImageLightboxLabels } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { MessageImageLabels } from '../MessageImage.tsx'
 
 /**
diff --git a/packages/client/ui-attachment/tests/image-lightbox.client.spec.tsx b/packages/client/ui-attachment/tests/image-lightbox.client.spec.tsx
index 5959fad3d4..3efde85334 100644
--- a/packages/client/ui-attachment/tests/image-lightbox.client.spec.tsx
+++ b/packages/client/ui-attachment/tests/image-lightbox.client.spec.tsx
@@ -2,7 +2,7 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
-import { ImageLightbox } from '../src/ImageLightbox.tsx'
+import { ImageLightbox } from '@deepseek-ai/dsh-client-ui-primitives'
 
 afterEach(cleanup)
 
diff --git a/packages/client/ui-chat/README.i18n.yaml b/packages/client/ui-chat/README.i18n.yaml
index f30604f200..ab7779ba68 100644
--- a/packages/client/ui-chat/README.i18n.yaml
+++ b/packages/client/ui-chat/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-chat/README.md
-README.md: 1aa7d71b3f932a7a14ef6d23e9ace7eda444fc3b
-README.zh.md: 2239234448e1e00fd395634de39a96c2a80a35f7
+README.md: 655b01885a27fd6d79ec9c9f81291bc75581c9d5
+README.zh.md: 748a304ae0b888c0b5b0a3b64254f557ad55568d
diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md
index 1aa7d71b3f..655b01885a 100644
--- a/packages/client/ui-chat/README.md
+++ b/packages/client/ui-chat/README.md
@@ -33,6 +33,8 @@ File-mention providers receive the viewed Session ID with the closing-turn owner
 
 Chat supplies file and HTTP(S) navigation through one `MarkdownDelegateProvider` around its node list. Assistant Markdown file links open in the right Sidebar after the message settles, including references to unmodified files. Relative paths resolve in the viewed Session's workspace; absolute paths retain the same Session's filesystem access. `#L24` and `#L24-L30` navigate to the first specified line and reuse an existing file tab. Missing files show the preview's error state.
 
+Standalone Markdown images show contained previews and open the shared image lightbox; local paths resolve against the viewed workspace after settlement. Image file links keep their sidebar activation and show a thumbnail after hover dwell or keyboard focus. Escape dismisses the thumbnail. Failed images retain a localized status and their description; no duplicate-image filtering is applied.
+
 Settings → General → Open chat links in selects the destination for ordinary clicks on Chat HTTP(S) links: In-App Sidebar (default) opens a new right-Sidebar Browser tab, while Default Browser opens an external tab. The setting is shown only while the Sidebar Browser is available. If the Sidebar Browser is not registered, both choices use the external browser; modified clicks retain native behavior. The `ui-chat.linkOpening` preference persists on loopback browsers and stays process-local when settings cannot persist writes. Sent file references and skills confirmed by the message’s logged invocation also open in the right Sidebar. File paths use the viewed Session; skill names resolve through its current input-trigger source. Both use the prose file-link dotted underline on hover or focus. Sessions, directories, and command labels remain non-navigating references.
 
 <a id="system-prompt-row"></a>
diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md
index 2239234448..748a304ae0 100644
--- a/packages/client/ui-chat/README.zh.md
+++ b/packages/client/ui-chat/README.zh.md
@@ -33,6 +33,8 @@ kind: "package-reference"
 
 Chat 在节点列表外通过一个 `MarkdownDelegateProvider` 提供文件及 HTTP(S) 导航。Assistant Markdown 文件链接在消息落定后可于右侧栏打开，包括未修改文件的引用。相对路径基于当前查看的 Session 工作区解析；绝对路径仍使用同一 Session 的文件系统访问。`#L24` 和 `#L24-L30` 定位到指定起始行，并复用现有文件标签。文件缺失时显示预览错误状态。
 
+独立的 Markdown 图片以内嵌预览显示，点击打开共享图片浮层；本地路径在消息落定后基于当前查看的工作区解析。图片文件链接保持点击打开侧栏，鼠标停留或键盘聚焦时显示缩略图，Esc 关闭缩略图。图片加载失败时保留本地化状态与图片说明；不执行重复图片过滤。
+
 设置 → 通用设置 → 网页链接默认打开方式控制普通点击 Chat HTTP(S) 链接时的目标：「应用内侧边栏」（默认）打开新的右侧 Sidebar Browser tab，「默认浏览器」打开外部标签页。该设置项仅在 Sidebar Browser 可用时显示。若 Sidebar Browser 未注册，两种选择均使用外部浏览器；带修饰键的点击保留原生行为。`ui-chat.linkOpening` 偏好在回环地址浏览器中持久化，设置无法持久化写入时仅在当前进程内生效。已发送的文件引用及消息日志确认调用的 skill 也可在右侧栏打开预览。文件路径使用当前查看的 Session；skill 名称由该 Session 当前的输入触发源解析。两者悬停或聚焦时均使用正文文件链接的虚线下划线。会话、目录和命令标签仍只作为引用展示。
 
 <a id="system-prompt-row"></a>
diff --git a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
index 1dd235d3c1..41d8c5b8c1 100644
--- a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
@@ -1,4 +1,5 @@
 import { Fragment, memo, useMemo } from 'react'
+import { fileMediaUrl } from '@deepseek-ai/dsh-util-workspace-path'
 import type { ReactNode } from 'react'
 import { JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { MarkdownFileMentions, MarkdownPathImages } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -10,16 +11,17 @@ import { useSearchableHidden } from './searchable-hidden.ts'
 import css from './AssistantMarkdown.module.css'
 
 /**
- * Resolve an authored POSIX image path against the document's file API.
+ * Resolve an authored absolute image path against the document's file API.
  * @param base - canonical `document.baseURI` at render time.
- * @param value - authored markdown destination.
+ * @param value - authored Markdown destination; URL escapes are decoded once.
  * @returns an absolute HTTP(S) file-API URL, or undefined for unsupported
  * protocols and non-local paths.
  */
 export function localPathMediaUrl(base: string, value: string): string | undefined {
-  if (!value.startsWith('/') || value.startsWith('//')) return undefined
-  if (!base.startsWith('http:') && !base.startsWith('https:')) return undefined
-  return new URL(`api/file?path=${encodeURIComponent(value)}`, base).href
+  let path: string
+  try { path = decodeURIComponent(value.split(/[?#]/u)[0] ?? '') }
+  catch { return undefined } // Malformed URL escapes cannot identify a file.
+  return fileMediaUrl(base, path)
 }
 
 export interface AssistantMarkdownProps {
diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
index a7c9ef0bae..0514068aed 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
@@ -20,6 +20,7 @@ import { assertNever } from '@deepseek-ai/dsh-util-values'
 import { TurnNavigator } from './TurnNavigator.tsx'
 import { mergeTurnRailItems } from './turn-rail-items.ts'
 import { useChatScroll } from './use-chat-scroll.ts'
+import { fileMediaUrl, resolveWorkspacePath } from '@deepseek-ai/dsh-util-workspace-path'
 import css from './ChatView.module.css'
 
 /** Host/OS refusal text for the file-open dialog; empty throws keep a locale fallback. */
@@ -120,6 +121,13 @@ export function ChatView({
   const inbox = useProjection('inbox') as unknown as InboxState | undefined
   // Workspace root off the session list row: path summaries display relative to it.
   const cwd = useSessions(s => s.byId[sessionId]?.cwd)
+  const fileImages = useMemo(() => ({
+    resolve: (path: string) => fileMediaUrl(document.baseURI, resolveWorkspacePath(cwd, path)),
+    labels: {
+      open: t('image.open'), loading: t('image.loading'), failed: t('image.failed'),
+      dialog: t('image.dialog'), close: t('image.close'),
+    },
+  }), [cwd, t])
   const running = useSession(s => s.running)
   const openState = useSession(s => s.openState)
   const openError = useSession(s => s.openError)
@@ -237,7 +245,7 @@ export function ChatView({
                 </button>
               </div>
             )}
-            <MarkdownDelegateProvider openExternalLink={openExternalLink} openFile={requestOpenFile}>
+            <MarkdownDelegateProvider openExternalLink={openExternalLink} openFile={requestOpenFile} fileImages={fileImages}>
               <ChatNodeList
                 entries={entries}
                 pendingInputs={pendingInputs}
diff --git a/packages/client/ui-chat/src/client/locale.ts b/packages/client/ui-chat/src/client/locale.ts
index 9638f554e0..188190edc9 100644
--- a/packages/client/ui-chat/src/client/locale.ts
+++ b/packages/client/ui-chat/src/client/locale.ts
@@ -49,6 +49,11 @@ export const zh = {
   'message.turnProcess.took': '用时 {duration}',
   'message.turnProcess.failed': '处理失败',
   'view.chat': '对话',
+  'image.open': '查看大图',
+  'image.loading': '加载图片…',
+  'image.failed': '图片无法预览',
+  'image.dialog': '图片预览',
+  'image.close': '关闭图片预览',
   'number.groupSeparator': ',',
   'duration.compactSeconds': '{seconds}秒',
   'duration.compactMinutes': '{minutes}分{seconds}秒',
@@ -207,6 +212,11 @@ export const en = {
   'message.turnProcess.took': 'Took {duration}',
   'message.turnProcess.failed': 'Failed',
   'view.chat': 'Chat',
+  'image.open': 'View full image',
+  'image.loading': 'Loading image…',
+  'image.failed': 'Image preview unavailable',
+  'image.dialog': 'Image preview',
+  'image.close': 'Close image preview',
   'number.groupSeparator': ',',
   'duration.compactSeconds': '{seconds}s',
   'duration.compactMinutes': '{minutes}m{seconds}s',
diff --git a/packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx b/packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx
index 5040efcdc0..2edebf11b6 100644
--- a/packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx
+++ b/packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx
@@ -43,7 +43,7 @@ describe('localPathMediaUrl', () => {
     expect(localPathMediaUrl(BASE, '')).toBeUndefined()
     expect(localPathMediaUrl(BASE, '//cdn.example.com/x.png')).toBeUndefined()
     expect(localPathMediaUrl(BASE, 'relative.png')).toBeUndefined()
-    expect(localPathMediaUrl(BASE, 'C:\\tmp\\x.png')).toBeUndefined()
+    expect(new URL(localPathMediaUrl(BASE, 'C:\\tmp\\x.png')!).searchParams.get('path')).toBe('C:\\tmp\\x.png')
   })
 
   it('encodes the full path including spaces', () => {
@@ -84,3 +84,12 @@ describe('AssistantMarkdown local-path images', () => {
     expect(container.textContent).toContain('diagram')
   })
 })
+
+it('decodes Markdown URL escapes once before encoding the file query', () => {
+  for (const [authored, path] of [
+    ['/work/test%20workspace/图.png', '/work/test workspace/图.png'],
+    ['/work/100%25%23.png', '/work/100%#.png'],
+    ['/work/literal%2520.png', '/work/literal%20.png'],
+  ]) expect(new URL(localPathMediaUrl(BASE, authored!)!).searchParams.get('path')).toBe(path)
+  expect(localPathMediaUrl(BASE, '/work/bad%escape.png')).toBeUndefined()
+})
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index ec9b6a2d71..ff3260836e 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-deliverables/README.md
-README.md: c52db38df0c800f52de4eebb3a9692eabef6c9df
-README.zh.md: 785c2215746e36ead16fe08b1a21b04a58ef418c
+README.md: 6ec8f1282c8173b83bcb24f40741cd5eab02fb79
+README.zh.md: b3140ff4c28702fd63f71c259954831acf1eb32f
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index c52db38df0..6ec8f1282c 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -89,7 +89,7 @@ Read these pages when the deliverables surface is not enough. They move from the
 
 #### What the model sees
 
-The guidance prefers primary results in the final reply: file links open Sidebar previews, and image previews include a file link for clients without inline-image support. It recommends separate `present` cards for complete file deliverables, especially Office files, usually selecting the most important one or two, with at most four files per call when more are needed. It discourages cards solely for code edits and extra commands to inspect diff visibility. This guidance applies even with developer tools disabled: it accepts fewer file surfaces to avoid duplicate presentation and unnecessary tool calls. It asks the model to link every existing-file mention outside commands, configuration expressions, and code blocks, including repeats and tables. Labels default to filenames or clear aliases, with only enough parent directories to distinguish files. Precise references display `filename:24` or `filename:24–30`; their destinations retain full relative or absolute paths with `#L24` or `#L24-L30` anchors. The display suffix contains neither `#` nor `L`.
+The guidance prefers primary results in the final reply: inline images support explanations and comparisons, image links offer hover previews and open in the Sidebar, and image file cards serve separate deliverables. File destinations use angle brackets, including paths with spaces. It recommends separate `present` cards for complete file deliverables, especially Office files, usually selecting the most important one or two, with at most four files per call when more are needed. It discourages cards solely for code edits and extra commands to inspect diff visibility. This guidance applies even with developer tools disabled: it accepts fewer file surfaces to avoid duplicate presentation and unnecessary tool calls. It asks the model to link every existing-file mention outside commands, configuration expressions, and code blocks, including repeats and tables. Labels default to filenames or clear aliases, with only enough parent directories to distinguish files. Precise references display `filename:24` or `filename:24–30`; their destinations retain full relative or absolute paths with `#L24` or `#L24-L30` anchors. The display suffix contains neither `#` nor `L`.
 
 #### Token effect
 
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index 785c221574..b3140ff4c2 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -89,7 +89,7 @@ Node 半部注册[模型体验](#model-experience)所述的静态 `ui:deliverabl
 
 #### 模型看到的内容
 
-提示词建议在最终回复中展示主要结果：文件链接打开 Sidebar 预览，图片预览同时保留文件链接，供不支持行内图片的客户端使用。对于需要完整文件的交付，尤其是 Office 文件，建议使用独立的 `present` 卡片，通常选最重要的一两项，需要时可以更多，但每次调用最多四项。提示词建议避免仅为列出代码改动生成卡片，也不为确认 diff 是否显示额外运行命令。开发者工具关闭时仍采用这条建议，接受较少的文件展示入口，以减少重复展示和不必要的工具调用。文件引用要求链接命令、配置表达式和代码块以外的每次现有文件提及，包括重复提及和表格。标签默认使用文件名或清楚的别名，仅添加足以区分文件的父目录。精确引用显示为 `filename:24` 或 `filename:24–30`；目标保留完整相对路径或绝对路径，以及 `#L24` 或 `#L24-L30` 锚点。显示后缀不含 `#` 或 `L`。
+提示词建议在最终回复中展示主要结果：内嵌图片用于讲解与对比，图片链接提供悬停预览并在点击时打开 Sidebar，图片文件卡片用于独立交付。文件目标路径使用尖括号包裹，包括含空格的路径。对于需要完整文件的交付，尤其是 Office 文件，建议使用独立的 `present` 卡片，通常选最重要的一两项，需要时可以更多，但每次调用最多四项。提示词建议避免仅为列出代码改动生成卡片，也不为确认 diff 是否显示额外运行命令。开发者工具关闭时仍采用这条建议，接受较少的文件展示入口，以减少重复展示和不必要的工具调用。文件引用要求链接命令、配置表达式和代码块以外的每次现有文件提及，包括重复提及和表格。标签默认使用文件名或清楚的别名，仅添加足以区分文件的父目录。精确引用显示为 `filename:24` 或 `filename:24–30`；目标保留完整相对路径或绝对路径，以及 `#L24` 或 `#L24-L30` 锚点。显示后缀不含 `#` 或 `L`。
 
 #### Token 影响
 
diff --git a/packages/client/ui-deliverables/src/index.ts b/packages/client/ui-deliverables/src/index.ts
index 33ede599ca..7762a67d16 100644
--- a/packages/client/ui-deliverables/src/index.ts
+++ b/packages/client/ui-deliverables/src/index.ts
@@ -15,9 +15,9 @@ export const inject = ['systemPrompt', 'connection', 'sessionQuery', 'sessionCon
 
 /** Static Web guidance for primary outputs and existing-file references. */
 const FILE_REFERENCE_PROMPT = 'Prefer showing the primary results within your final response alongside a brief explanation. '
-  + 'Markdown file links such as [Report](path/to/report.html) open the file in the sidebar preview. For images, you can add an inline preview such as ![Preview](/absolute/path/image.png); include a file link as well so the image remains accessible in clients that cannot display it inline. '
+  + 'Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. '
   + 'Do not call present just to list edited source files, or run commands to check whether a diff view will appear. '
-  + 'Use present when a separate file card helps the user open the complete deliverable, especially Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. '
+  + 'Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. '
   + 'Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. '
   + 'Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. '
   + 'Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.'
diff --git a/packages/client/ui-deliverables/tests/prompt.host.spec.ts b/packages/client/ui-deliverables/tests/prompt.host.spec.ts
index 9758dba3c5..249792ec88 100644
--- a/packages/client/ui-deliverables/tests/prompt.host.spec.ts
+++ b/packages/client/ui-deliverables/tests/prompt.host.spec.ts
@@ -29,7 +29,7 @@ describe('ui-deliverables node plugin', () => {
 
     const section = (await ctx.systemPrompt.assemble()).sections
       .find(entry => entry.name === 'ui:deliverable-file-references')
-    expect(section?.text).toMatchInlineSnapshot('"Prefer showing the primary results within your final response alongside a brief explanation. Markdown file links such as [Report](path/to/report.html) open the file in the sidebar preview. For images, you can add an inline preview such as ![Preview](/absolute/path/image.png); include a file link as well so the image remains accessible in clients that cannot display it inline. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, especially Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix."')
+    expect(section?.text).toMatchInlineSnapshot('"Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix."')
 
     // Only live request pins track current guidance; seeded sessions retain their recorded prompt.
     for (const scenario of ['fresh-round-trip', 'ptc-round']) {
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 66c0f146c7..b7c783080c 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md
-README.md: 5b8a16739504d8da169e04f64b0feb684f47f8c3
-README.zh.md: 291beb0cef60584ec86d349e8be8a11a1ae1694b
+README.md: 349921e171336dc16f9ae38ac815a9e042bc447c
+README.zh.md: eec967d30243566ce2f78e1b325c1af96d663519
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 5b8a167395..349921e171 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -54,6 +54,7 @@ Check this table before writing a control in a feature package. A plugin cannot
 | `OnboardingSurface` | First-run stage that holds the application root inert. |
 | `Tooltip` | Hover text anchored to a cloned child; optional `portal` rendering escapes clipping containers and ancestor stacking contexts that cap the bubble's z-index. |
 | `HoverCard` | Hover preview the pointer can rest on and select from; optional copy button. |
+| `ImageLightbox`, `ImagePreview` | Shared image modal and passive contained preview with loading/failure states. |
 | `Toast` | Transient top-center banner held for the owner's `holdMs`. |
 | `SettingsForm`, `SettingsValueField`, `SettingsSecretField` | The frame and the controls of a plugin's settings page: the frame takes its copy as `labels`, saves only on its button, and discards on unmount; a value field shows staged text with the overridden badge and reset; a secret field starts blank and reports only whether a value is configured. |
 | `SettingsFormModel`, `settingsNumberField`, `settingsTextField` | The staged-edit model behind such a page over a settings scope: drafts are staged and written on save, a field is overridden by its presence in the user layer, and a save that did not land keeps its drafts. |
@@ -95,6 +96,8 @@ The nearest `MarkdownDelegateProvider` supplies optional `openExternalLink` and
 
 `JsonTree` clamps collapsed strings to `collapsedStringLines` (three by default). Expanded strings show raw text, retain sibling commas, and fit within the window and outer scrolling containers. Resize and ancestor-scroll events update that limit. Row copy feedback updates independently of JSON value rendering; pending clipboard writes cannot update a different row or an unmounted tree.
 
+`ImageLightbox` is the shared original-image modal with focus restoration and Escape dismissal; `ImagePreview` is a passive, contained thumbnail with owner-supplied loading/failure labels. `HoverCard.inline` keeps a file link in the text flow and uses the shared menu material, keyboard focus, and viewport-clamped placement. `MarkdownDelegateProvider.fileImages` supplies a decoded-path resolver and complete image labels: settled image links gain hover previews, and standalone images gain lightbox activation. Image-only anchors retain their single navigation target. The parser recovers only complete, unescaped, standalone local image references with bare spaces and an unambiguous supported image suffix; code and ambiguous destinations remain literal.
+
 ### Localizing copy
 
 The atoms cannot read the application locale, so every piece of user-facing copy arrives through required label props. `HoverCard`, `TerminalBlock`, `JsonTree`, `CodeBlock`, `MarkdownText`, `JsonBlock`, `ConnectionIndicator`, `Modal`, `DiffBlock`, `ReadBlock`, `SearchBlock`, and `WebBlock` accept complete localized labels. The package owns no language fallback; omission fails typechecking, and each feature maps its typed `t` seat into the primitive's label interface.
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index 291beb0cef..eec967d302 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -54,6 +54,7 @@ kind: "package-library"
 | `OnboardingSurface` | 首次运行的引导舞台，期间保持应用根节点 inert。 |
 | `Tooltip` | 锚定在克隆子元素上的悬停文本；可通过 `portal` 渲染到外层，避免被容器裁剪，或受祖先层叠上下文限制其 z-index。 |
 | `HoverCard` | 指针可停留、可选中的悬停预览；可选带复制按钮。 |
+| `ImageLightbox`, `ImagePreview` | 共享图片浮层，以及带加载和失败状态的等比预览。 |
 | `Toast` | 顶部居中的瞬时横幅，保持时长由所有者的 `holdMs` 决定。 |
 | `SettingsForm`、`SettingsValueField`、`SettingsSecretField` | 插件设置页的框架与控件：框架以 `labels` 接收文案，只在按钮点击时保存，卸载即丢弃；值字段显示暂存文本以及已覆盖标签和重置；密文字段每次为空，只报告是否已配置。 |
 | `SettingsFormModel`、`settingsNumberField`、`settingsTextField` | 这类页面背后基于设置 scope 的暂存编辑模型：草稿先暂存、保存时写入，字段是否被覆盖看用户层是否含有它，未落地的保存保留草稿。 |
@@ -95,6 +96,8 @@ kind: "package-library"
 
 `JsonTree` 把折叠字符串限制为 `collapsedStringLines` 行（默认三行）。展开后显示原始文本、保留同级逗号，并限制在窗口与外层滚动容器内；尺寸变化和祖先滚动事件会更新此限制。行复制反馈独立于 JSON 值渲染更新；尚未完成的剪贴板写入不会更新另一行或已卸载的树。
 
+`ImageLightbox` 是共享原图浮层，支持焦点恢复与 Esc 关闭；`ImagePreview` 是被动的等比缩略图，由调用方提供加载及失败文案。`HoverCard.inline` 使文件链接保持在文本流内，并使用共享菜单材质、键盘聚焦和视口内定位。`MarkdownDelegateProvider.fileImages` 提供已解码路径解析器与完整图片文案：消息落定后的图片链接支持悬停预览，独立图片支持点击放大。仅包含图片的链接保留单一导航目标。解析器仅恢复完整、未转义、独立成段且带明确图片扩展名的含裸空格本地图片引用；代码与有歧义的目标保持原文。
+
 ### 本地化文案
 
 这些原子组件无法读取应用 locale，因此每段面向用户的文案都必须通过 label prop 提供。`HoverCard`、`TerminalBlock`、`JsonTree`、`CodeBlock`、`MarkdownText`、`JsonBlock`、`ConnectionIndicator`、`Modal`、`DiffBlock`、`ReadBlock`、`SearchBlock` 与 `WebBlock` 接收完整的本地化 label。本包不拥有语言回退；遗漏会导致类型检查失败，各功能会把带类型的 `t` 席位映射到 primitive 的 label 接口。
diff --git a/packages/client/ui-primitives/src/HoverCard.module.css b/packages/client/ui-primitives/src/HoverCard.module.css
index e23a27e11e..db4805c894 100644
--- a/packages/client/ui-primitives/src/HoverCard.module.css
+++ b/packages/client/ui-primitives/src/HoverCard.module.css
@@ -79,3 +79,14 @@
 @media (prefers-reduced-motion: reduce) {
   .preview { transition: none; }
 }
+
+.inline { display: inline; }
+.media {
+  width: min(300px, calc(100vw - 16px));
+  padding: 8px;
+  border: 0;
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-specific-menu);
+  backdrop-filter: var(--dsw-menu-backdrop-filter);
+  box-shadow: var(--dsw-elevation-panel);
+}
diff --git a/packages/client/ui-primitives/src/HoverCard.tsx b/packages/client/ui-primitives/src/HoverCard.tsx
index b0c8ae86f8..dfb752ee35 100644
--- a/packages/client/ui-primitives/src/HoverCard.tsx
+++ b/packages/client/ui-primitives/src/HoverCard.tsx
@@ -32,9 +32,11 @@ const VIEWPORT_MARGIN = 8
  */
 export function HoverCard({
   anchor, content, openDelayMs = 500, disabled = false,
-  copyText, copyLabel, copiedLabel, variant = 'compact', widthAnchorRef,
+  copyText, copyLabel, copiedLabel, variant = 'compact', widthAnchorRef, inline = false,
 }: {
   anchor: ReactNode
+  /** Inline media preview using the shared menu material and keyboard focus. */
+  inline?: boolean
   content: ReactNode
   openDelayMs?: number
   disabled?: boolean
@@ -148,11 +150,19 @@ export function HoverCard({
         })
         return
       }
+      if (inline) {
+        const w = cardRef.current?.offsetWidth ?? 300
+        setPos({
+          left: Math.max(VIEWPORT_MARGIN, Math.min(r.left, window.innerWidth - w - VIEWPORT_MARGIN)),
+          top: Math.max(overlayTopMargin(VIEWPORT_MARGIN), Math.min(r.bottom + ANCHOR_GAP, window.innerHeight - h - VIEWPORT_MARGIN)),
+        })
+        return
+      }
       const top = r.top + h > window.innerHeight - VIEWPORT_MARGIN ? window.innerHeight - h - VIEWPORT_MARGIN : r.top
       setPos({ left: r.right + ANCHOR_GAP, top })
     }
     place()
-    const observer = variant === 'preview' && typeof ResizeObserver !== 'undefined' ? new ResizeObserver(place) : null
+    const observer = (variant === 'preview' || inline) && typeof ResizeObserver !== 'undefined' ? new ResizeObserver(place) : null
     for (const element of [cardRef.current, rootRef.current, widthAnchorRef?.current]) {
       if (element !== null && element !== undefined) observer?.observe(element)
     }
@@ -163,7 +173,7 @@ export function HoverCard({
       window.removeEventListener('scroll', place, true)
       window.removeEventListener('resize', place)
     }
-  }, [open, variant, widthAnchorRef, positioned])
+  }, [open, variant, widthAnchorRef, positioned, inline])
 
   // The first placement ran before the card mounted (height read 0): once the
   // card's real height is measurable, correct the bottom-edge clamp. The
@@ -202,7 +212,7 @@ export function HoverCard({
   const card = open && pos !== null && (
     <div
       ref={cardRef}
-      className={clsx(css.card, variant === 'preview' && css.preview, copyable && css.copyable, copied && css.feedback)}
+      className={clsx(css.card, variant === 'preview' && css.preview, inline && css.media, copyable && css.copyable, copied && css.feedback)}
       data-closing={closing || undefined}
       style={{
         ...pos, minHeight: copied && copyHeightRef.current !== null ? copyHeightRef.current : undefined,
@@ -237,9 +247,16 @@ export function HoverCard({
   return (
     <span
       ref={rootRef}
-      className={css.root}
-      onPointerEnter={() => {
-        if (disabled) return
+      className={clsx(css.root, inline && css.inline)}
+      onFocus={inline ? () => { if (!disabled) { cancelClose(); setPhase('open') } } : undefined}
+      onBlur={inline ? (event) => {
+        if (!event.currentTarget.contains(event.relatedTarget)) { clearTimer(); cancelClose(); close() }
+      } : undefined}
+      onKeyDown={inline ? (event) => {
+        if (event.key === 'Escape') { event.stopPropagation(); clearTimer(); cancelClose(); close() }
+      } : undefined}
+      onPointerEnter={(event) => {
+        if (disabled || (inline && event.pointerType === 'touch')) return
         // Coming back inside during the grace (the gap, or the card itself)
         // keeps the current card rather than restarting the dwell.
         cancelClose()
diff --git a/packages/client/ui-attachment/src/ImageLightbox.module.css b/packages/client/ui-primitives/src/ImageLightbox.module.css
similarity index 86%
rename from packages/client/ui-attachment/src/ImageLightbox.module.css
rename to packages/client/ui-primitives/src/ImageLightbox.module.css
index dffba50e82..520b050d02 100644
--- a/packages/client/ui-attachment/src/ImageLightbox.module.css
+++ b/packages/client/ui-primitives/src/ImageLightbox.module.css
@@ -24,7 +24,8 @@
   object-fit: contain;
   border-radius: 12px;
   background: var(--dsw-specific-input-major);
-  box-shadow: var(--dsw-shadow-lv3);
+  border: 0;
+  box-shadow: var(--dsw-elevation-prominent);
 }
 
 .close {
@@ -43,3 +44,5 @@
   color: var(--dsw-alias-label-primary);
   cursor: pointer;
 }
+
+.close:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary); outline-offset: 3px; }
diff --git a/packages/client/ui-attachment/src/ImageLightbox.tsx b/packages/client/ui-primitives/src/ImageLightbox.tsx
similarity index 90%
rename from packages/client/ui-attachment/src/ImageLightbox.tsx
rename to packages/client/ui-primitives/src/ImageLightbox.tsx
index c2aff2eeb3..76c8aa2875 100644
--- a/packages/client/ui-attachment/src/ImageLightbox.tsx
+++ b/packages/client/ui-primitives/src/ImageLightbox.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useRef } from 'react'
 import { createPortal } from 'react-dom'
-import { IconCloseOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconCloseOutlineRegular } from './icons/index.tsx'
 import css from './ImageLightbox.module.css'
 
 /** Lightbox strings the owner resolves from its own locale namespace. */
@@ -37,7 +37,8 @@ export function ImageLightbox({ src, alt, labels, onClose }: {
     restoreRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null
     closeRef.current?.focus()
     const onKeyDown = (event: globalThis.KeyboardEvent): void => {
-      if (event.key === 'Escape') onClose()
+      if (event.key === 'Escape') { event.stopPropagation(); onClose() }
+      if (event.key === 'Tab') { event.preventDefault(); closeRef.current?.focus() }
     }
     window.addEventListener('keydown', onKeyDown)
     return () => {
diff --git a/packages/client/ui-primitives/src/ImagePreview.module.css b/packages/client/ui-primitives/src/ImagePreview.module.css
new file mode 100644
index 0000000000..037782c02d
--- /dev/null
+++ b/packages/client/ui-primitives/src/ImagePreview.module.css
@@ -0,0 +1,24 @@
+.frame {
+  position: relative;
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 180px;
+  overflow: hidden;
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-base);
+}
+.image { width: 100%; height: 100%; min-height: 0; object-fit: contain; opacity: 0; }
+.image[data-ready] { opacity: 1; }
+.status {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding: 12px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 18px;
+}
diff --git a/packages/client/ui-primitives/src/ImagePreview.tsx b/packages/client/ui-primitives/src/ImagePreview.tsx
new file mode 100644
index 0000000000..ffe6fec1b9
--- /dev/null
+++ b/packages/client/ui-primitives/src/ImagePreview.tsx
@@ -0,0 +1,39 @@
+/** Passive, contained image preview for Markdown image links. */
+import { useState } from 'react'
+import clsx from 'clsx'
+import { IconLoadingOutlineRegular } from './icons/index.tsx'
+import css from './ImagePreview.module.css'
+
+/**
+ * Render an image without introducing a second activation target.
+ * @param props - Source, accessible description, localized status, and owner layout class.
+ * @returns A contained preview with loading or failure status.
+ */
+export function ImagePreview({ src, alt, loadingLabel, failedLabel, className }: {
+  src: string
+  alt: string
+  loadingLabel: string
+  failedLabel: string
+  className?: string | undefined
+}) {
+  return <Preview key={src} src={src} alt={alt} loadingLabel={loadingLabel} failedLabel={failedLabel} className={className} />
+}
+
+function Preview({ src, alt, loadingLabel, failedLabel, className }: {
+  src: string
+  alt: string
+  loadingLabel: string
+  failedLabel: string
+  className: string | undefined
+}) {
+  const [state, setState] = useState<'loading' | 'ready' | 'failed'>('loading')
+  return <span className={clsx(css.frame, className)}>
+    {state !== 'failed' && <img src={src} alt={alt} loading="lazy" decoding="async" referrerPolicy="no-referrer"
+      className={css.image} data-ready={state === 'ready' || undefined}
+      onLoad={() => { setState('ready') }} onError={() => { setState('failed') }} />}
+    {state !== 'ready' && <span className={css.status} role="status">
+      {state === 'loading' && <IconLoadingOutlineRegular size={16} />}
+      <span>{state === 'loading' ? loadingLabel : failedLabel}</span>
+    </span>}
+  </span>
+}
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index b8ec370298..def473220c 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -102,3 +102,6 @@ export * from './icons/index.tsx'
 export {
   PluginArtworkTerminal, PluginArtworkLoop, PluginArtworkSubagent, PluginArtworkSearch, PluginArtworkDefault,
 } from './plugin-artwork.tsx'
+export { ImageLightbox } from './ImageLightbox.tsx'
+export type { ImageLightboxLabels } from './ImageLightbox.tsx'
+export { ImagePreview } from './ImagePreview.tsx'
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownDelegate.tsx b/packages/client/ui-primitives/src/markdown/MarkdownDelegate.tsx
index 0dfcb56cf0..681e8f5608 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownDelegate.tsx
+++ b/packages/client/ui-primitives/src/markdown/MarkdownDelegate.tsx
@@ -1,6 +1,7 @@
 /** Consumer-owned navigation for Markdown links. */
 import { createContext, useContext, useMemo } from 'react'
 import type { ReactNode } from 'react'
+import type { ImageLightboxLabels } from '../ImageLightbox.tsx'
 
 /**
  * Handle one sanitized absolute HTTP(S) URL selected from Markdown.
@@ -10,6 +11,11 @@ export type MarkdownExternalLinkHandler = (href: string) => void
 
 /** Navigation capabilities supplied by the nearest Markdown owner. */
 export interface MarkdownDelegate {
+  /** Image previews for decoded local paths in this owner's workspace. */
+  readonly fileImages?: {
+    resolve: (path: string) => string | undefined
+    labels: ImageLightboxLabels & { open: string; loading: string; failed: string }
+  } | undefined
   /** Ordinary HTTP(S) activation; absent handlers retain native anchor behavior. */
   readonly openExternalLink?: MarkdownExternalLinkHandler | undefined
   /**
@@ -37,8 +43,9 @@ export function MarkdownDelegateProvider({
   children,
   openExternalLink,
   openFile,
+  fileImages,
 }: MarkdownDelegateProviderProps): ReactNode {
-  const delegate = useMemo(() => ({ openExternalLink, openFile }), [openExternalLink, openFile])
+  const delegate = useMemo(() => ({ openExternalLink, openFile, fileImages }), [openExternalLink, openFile, fileImages])
   return (
     <MarkdownDelegateContext.Provider value={delegate}>
       {children}
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
index e3c5b31953..3f495bc594 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
@@ -442,3 +442,26 @@
 .compact :global(.katex-display) {
   margin: 4px 0;
 }
+
+.imageButton {
+  display: inline-block;
+  max-width: 100%;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  background: transparent;
+  vertical-align: middle;
+  cursor: zoom-in;
+}
+.imageButton .image { max-width: min(100%, 640px); max-height: 360px; }
+.imageButton:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary); outline-offset: 3px; }
+.previewName {
+  display: block;
+  margin-top: 8px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 12px;
+  line-height: 18px;
+}
diff --git a/packages/client/ui-primitives/src/markdown/local-image-syntax.ts b/packages/client/ui-primitives/src/markdown/local-image-syntax.ts
new file mode 100644
index 0000000000..a22c1b9d81
--- /dev/null
+++ b/packages/client/ui-primitives/src/markdown/local-image-syntax.ts
@@ -0,0 +1,28 @@
+/** Recover standalone local image references with bare spaces without changing code or source offsets. */
+import type { Root, RootContent } from 'mdast'
+
+/**
+ * Recover only unambiguous, unescaped image-only paragraphs containing a local path with spaces.
+ * @param root - Parsed Markdown tree, modified in place.
+ * @param source - Original source used to distinguish authored syntax from escaped examples.
+ * @returns The same root with recovered image nodes.
+ */
+export function recoverLocalImages(root: Root, source: string): Root {
+  const visit = (node: Root | RootContent): void => {
+    if (node.type === 'paragraph' && node.children.length === 1) {
+      const child = node.children[0]
+      if (child?.type === 'text' && child.position !== undefined
+        && source.slice(child.position.start.offset, child.position.end.offset) === child.value) {
+        const pattern = /^!\[([^\]\n]*)\]\(((?:\/(?!\/)|\.{1,2}\/|[a-z]:[\\/])[^\n<>()[\]"']+\.(?:png|jpe?g|gif|webp|svg|bmp|ico))\)$/iu
+        const match = pattern.exec(child.value)
+        if (match !== null && match[2]?.includes(' ')) {
+          node.children = [{ type: 'image', alt: match[1] ?? '', url: match[2], position: child.position }]
+        }
+      }
+    } else if ('children' in node) {
+      for (const child of node.children) visit(child)
+    }
+  }
+  visit(root)
+  return root
+}
diff --git a/packages/client/ui-primitives/src/markdown/parse.ts b/packages/client/ui-primitives/src/markdown/parse.ts
index 50f8f179b9..46559c3f47 100644
--- a/packages/client/ui-primitives/src/markdown/parse.ts
+++ b/packages/client/ui-primitives/src/markdown/parse.ts
@@ -9,6 +9,7 @@
  */
 
 import type { Root } from 'mdast'
+import { recoverLocalImages } from './local-image-syntax.ts'
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
 import { mathFromMarkdown } from 'mdast-util-math'
@@ -24,10 +25,10 @@ import { mathCompatibility } from './mathCompatibility.ts'
  * @returns The mdast root.
  */
 export function parseGfm(text: string): Root {
-  return fromMarkdown(text, {
+  return recoverLocalImages(fromMarkdown(text, {
     extensions: [gfm(), cjkFriendlyStrong()],
     mdastExtensions: [gfmFromMarkdown()],
-  })
+  }), text)
 }
 
 /**
@@ -37,8 +38,8 @@ export function parseGfm(text: string): Root {
  * @returns The mdast root.
  */
 export function parseGfmWithMath(text: string): Root {
-  return fromMarkdown(text, {
+  return recoverLocalImages(fromMarkdown(text, {
     extensions: [gfm(), cjkFriendlyStrong(), mathCompatibility(), math()],
     mdastExtensions: [gfmFromMarkdown(), mathFromMarkdown()],
-  })
+  }), text)
 }
diff --git a/packages/client/ui-primitives/src/markdown/render.tsx b/packages/client/ui-primitives/src/markdown/render.tsx
index 84a9c2857a..10b3e59fb1 100644
--- a/packages/client/ui-primitives/src/markdown/render.tsx
+++ b/packages/client/ui-primitives/src/markdown/render.tsx
@@ -16,7 +16,7 @@
  * may add node types this renderer has no mapping for.
  */
 
-import { Fragment, createElement, useState } from 'react'
+import { Fragment, createElement, useCallback, useState } from 'react'
 import type { Key, ReactNode } from 'react'
 import clsx from 'clsx'
 import type * as Md from 'mdast'
@@ -28,6 +28,9 @@ import { parseFileLink } from './file-link.ts'
 import { renderTexToReact } from './katex.tsx'
 import { LinkIconMedium, classifyLinkPath } from '../LinkIcon.tsx'
 import { useMarkdownDelegate } from './MarkdownDelegate.tsx'
+import { HoverCard } from '../HoverCard.tsx'
+import { ImageLightbox } from '../ImageLightbox.tsx'
+import { ImagePreview } from '../ImagePreview.tsx'
 import type { PositionedBlock } from './incremental.ts'
 import css from './MarkdownText.module.css'
 
@@ -579,19 +582,27 @@ function MarkdownFileLink({ file, glyph, children }: {
   readonly glyph: boolean
   readonly children: ReactNode[]
 }): ReactNode {
-  const { openFile } = useMarkdownDelegate()
+  const { openFile, fileImages } = useMarkdownDelegate()
   if (openFile === undefined) return <>{children}</>
-  return (
+  const preview = glyph && classifyLinkPath(file.path) === 'image' ? fileImages : undefined
+  const src = preview?.resolve(file.path)
+  const anchor = (
     <button
       type="button"
       className={clsx(css.fileMention, css.fileLink)}
-      title={file.path}
+      title={src === undefined ? file.path : undefined}
       onClick={() => { openFile(file.path, file.line === undefined ? undefined : { line: file.line }) }}
     >
       {glyph && <LinkIconMedium kind={classifyLinkPath(file.path)} className={css.linkIcon} />}
       {children}
     </button>
   )
+  if (src === undefined || preview === undefined) return anchor
+  return <HoverCard inline anchor={anchor} copyLabel={preview.labels.open} copiedLabel={preview.labels.open}
+    content={<>
+      <ImagePreview src={src} alt={file.path} loadingLabel={preview.labels.loading} failedLabel={preview.labels.failed} />
+      <span className={css.previewName}>{file.path.split(/[\\/]/u).pop()}</span>
+    </>} />
 }
 
 /**
@@ -610,28 +621,43 @@ function inlineCodeHttpUrl(value: string): string | undefined {
 }
 
 function renderImage(url: string, alt: string, key: Key, context: MarkdownRenderContext): ReactNode {
-  const imageSrc = imageSource(url, context.pathImages)
-  if (imageSrc === undefined) {
-    return <span key={key} className={css.imageAlt}>{alt}</span>
-  }
-  return <MarkdownImage key={`${key}:${imageSrc}`} src={imageSrc} alt={alt} destination={url} />
+  return <MarkdownImage key={`${key}:${url}`} destination={url} alt={alt}
+    pathImages={context.pathImages} streaming={context.streaming} inLink={context.inLink === true} />
 }
 
-/** Failed loads retain the authored alt or destination; a new source remounts the image. */
-function MarkdownImage({ src, alt, destination }: { src: string; alt: string; destination: string }): ReactNode {
+function MarkdownImage({ destination, alt, pathImages, streaming, inLink }: {
+  destination: string
+  alt: string
+  pathImages: MarkdownPathImages | undefined
+  streaming: boolean
+  inLink: boolean
+}): ReactNode {
+  const { fileImages } = useMarkdownDelegate()
+  const file = streaming ? undefined : parseFileLink(destination)
+  const src = (file === undefined ? undefined : fileImages?.resolve(file.path)) ?? imageSource(destination, pathImages)
+  if (src === undefined) return <span className={css.imageAlt}>{alt}</span>
+  return <LoadedMarkdownImage key={src} src={src} alt={alt} destination={destination} preview={inLink ? undefined : fileImages} />
+}
+
+function LoadedMarkdownImage({ src, alt, destination, preview }: {
+  src: string
+  alt: string
+  destination: string
+  preview: ReturnType<typeof useMarkdownDelegate>['fileImages']
+}): ReactNode {
   const [failed, setFailed] = useState(false)
-  if (failed) return <span className={css.imageAlt}>{alt || destination}</span>
-  return (
-    <img
-      className={css.image}
-      src={src}
-      alt={alt}
-      onError={() => { setFailed(true) }}
-      loading="lazy"
-      decoding="async"
-      referrerPolicy="no-referrer"
-    />
-  )
+  const [open, setOpen] = useState(false)
+  const close = useCallback(() => { setOpen(false) }, [])
+  if (failed) return <span className={css.imageAlt}>{preview === undefined ? '' : `${preview.labels.failed} · `}{alt || destination}</span>
+  const img = <img className={css.image} src={src} alt={alt}
+    onError={() => { setFailed(true) }} loading="lazy" decoding="async" referrerPolicy="no-referrer" />
+  if (preview === undefined) return img
+  return <>
+    <button type="button" className={css.imageButton} title={preview.labels.open}
+      aria-label={alt ? `${preview.labels.open}: ${alt}` : preview.labels.open}
+      onClick={(event) => { event.preventDefault(); event.stopPropagation(); setOpen(true) }}>{img}</button>
+    {open && <ImageLightbox src={src} alt={alt} labels={preview.labels} onClose={close} />}
+  </>
 }
 
 /** The bracketed source text a reference reverts to when its definition is missing. */
diff --git a/packages/client/ui-primitives/tests/image-preview.client.spec.tsx b/packages/client/ui-primitives/tests/image-preview.client.spec.tsx
new file mode 100644
index 0000000000..97389ad9ab
--- /dev/null
+++ b/packages/client/ui-primitives/tests/image-preview.client.spec.tsx
@@ -0,0 +1,19 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, expect, it } from 'vitest'
+import { ImagePreview } from '../src/ImagePreview.tsx'
+
+afterEach(cleanup)
+it('keeps status inside the preview and resets failures when the source changes', () => {
+  const props = { src: '/one.png', alt: 'Comparison', loadingLabel: 'Loading image', failedLabel: 'Image unavailable' }
+  const { rerender } = render(<ImagePreview {...props} />)
+  expect(screen.getByRole('status').textContent).toBe('Loading image')
+  fireEvent.error(screen.getByRole('img'))
+  expect(screen.getByRole('status').textContent).toBe('Image unavailable')
+  expect(screen.queryByRole('img')).toBeNull()
+  rerender(<ImagePreview {...props} src="/two.png" />)
+  expect(screen.getByRole('status').textContent).toBe('Loading image')
+  fireEvent.load(screen.getByRole('img'))
+  expect(screen.queryByRole('status')).toBeNull()
+  expect(screen.queryByRole('button')).toBeNull()
+})
diff --git a/packages/client/ui-primitives/tests/markdown-image-entries.client.spec.tsx b/packages/client/ui-primitives/tests/markdown-image-entries.client.spec.tsx
new file mode 100644
index 0000000000..ba8dd1a4f2
--- /dev/null
+++ b/packages/client/ui-primitives/tests/markdown-image-entries.client.spec.tsx
@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+import { MarkdownDelegateProvider } from '../src/markdown/MarkdownDelegate.tsx'
+import { MarkdownText } from './markdown-test-components.tsx'
+import { parseGfm, parseGfmWithMath } from '../src/markdown/parse.ts'
+
+afterEach(() => { cleanup(); vi.useRealTimers() })
+const labels = { open: 'View full image', dialog: 'Image preview', close: 'Close preview', loading: 'Loading image', failed: 'Image unavailable' }
+const fileImages = { resolve: (path: string) => `https://example.com/api/file?path=${encodeURIComponent('/workspace/' + path)}`, labels }
+function mount(text: string, streaming = false) {
+  const openFile = vi.fn()
+  const view = render(<MarkdownDelegateProvider openFile={openFile} fileImages={fileImages}>
+    <MarkdownText text={text} streaming={streaming} />
+  </MarkdownDelegateProvider>)
+  return { ...view, openFile }
+}
+
+it('opens inline images in the shared lightbox, restores focus, and never opens the sidebar', () => {
+  const { openFile } = mount('![Compare](<.artifacts/对比 image.png>)')
+  const trigger = screen.getByRole('button', { name: 'View full image: Compare' })
+  trigger.focus()
+  expect(new URL(screen.getByRole('img').getAttribute('src')!).searchParams.get('path')).toBe('/workspace/.artifacts/对比 image.png')
+  fireEvent.click(trigger)
+  expect(screen.getByRole('dialog', { name: 'Image preview' })).toBeTruthy()
+  fireEvent.keyDown(window, { key: 'Tab' })
+  expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Close preview' }))
+  fireEvent.click(screen.getByRole('button', { name: 'Close preview' }))
+  expect(screen.queryByRole('dialog')).toBeNull()
+  expect(document.activeElement).toBe(trigger)
+  expect(openFile).not.toHaveBeenCalled()
+})
+
+it('loads a link preview only after hover dwell and keeps its existing sidebar activation', () => {
+  vi.useFakeTimers()
+  const { openFile } = mount('[View comparison](.artifacts/对比%20image.png)')
+  const link = screen.getByRole('button', { name: 'View comparison' })
+  expect(screen.queryByRole('img')).toBeNull()
+  fireEvent.pointerEnter(link.parentElement!)
+  act(() => { vi.advanceTimersByTime(499) })
+  expect(screen.queryByRole('img')).toBeNull()
+  act(() => { vi.advanceTimersByTime(1) })
+  const image = screen.getByRole('img')
+  expect(new URL(image.getAttribute('src')!).searchParams.get('path')).toBe('/workspace/.artifacts/对比 image.png')
+  fireEvent.load(image)
+  expect(screen.queryByText('Loading image')).toBeNull()
+  fireEvent.pointerDown(link)
+  fireEvent.click(link)
+  expect(screen.queryByRole('img')).toBeNull()
+  expect(openFile).toHaveBeenCalledWith('.artifacts/对比 image.png', undefined)
+})
+
+it('supports keyboard previews, Escape dismissal, and an inert failure state', () => {
+  mount('[View comparison](graph.png)')
+  const link = screen.getByRole('button', { name: 'View comparison' })
+  fireEvent.focus(link)
+  fireEvent.error(screen.getByRole('img'))
+  expect(screen.getByText('Image unavailable')).toBeTruthy()
+  fireEvent.keyDown(link, { key: 'Escape' })
+  expect(screen.queryByText('Image unavailable')).toBeNull()
+})
+
+it('leaves non-image links and streaming paths without a preview', () => {
+  mount('[Report](report.pdf)')
+  fireEvent.focus(screen.getByRole('button', { name: 'Report' }))
+  expect(screen.queryByRole('img')).toBeNull()
+  cleanup()
+  mount('![Compare](image.png)', true)
+  expect(screen.queryByRole('img')).toBeNull()
+})
+
+it('keeps image-only links as one activation target', () => {
+  const { container, openFile } = mount('[![Compare](image.png)](image.png)')
+  expect(container.querySelectorAll('button')).toHaveLength(1)
+  fireEvent.click(screen.getByRole('button'))
+  expect(openFile).toHaveBeenCalledWith('image.png', undefined)
+  expect(screen.queryByRole('dialog')).toBeNull()
+})
+
+it.each([parseGfm, parseGfmWithMath])('recovers standalone bare-space paths without promoting code or escaped syntax', (parse) => {
+  const source = '![图](/work/test workspace/测试文件/图.png)'
+  expect(parse(source).children[0]).toMatchObject({ children: [{ type: 'image', url: '/work/test workspace/测试文件/图.png' }] })
+  for (const example of ['`' + source + '`', '```md\n' + source + '\n```', '\\' + source, 'Example: ' + source,
+    '![图](https://example.com/test image.png)', '![图](/work/test (image).png)']) {
+    expect(JSON.stringify(parse(example))).not.toContain('"type":"image"')
+  }
+})
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/markdown/path-images.ts b/packages/client/ui-sidebar-documentpreview/src/client/markdown/path-images.ts
index e70f3cfaf8..7030cc9c26 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/markdown/path-images.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/markdown/path-images.ts
@@ -1,5 +1,5 @@
 /** Local Markdown image destinations served by the authenticated file route. */
-import { isAbsoluteWorkspacePath, pathPartsOf } from '@deepseek-ai/dsh-util-workspace-path'
+import { fileMediaUrl, isAbsoluteWorkspacePath, pathPartsOf } from '@deepseek-ai/dsh-util-workspace-path'
 
 /**
  * Build a file URL, resolving relative destinations beside the previewed file.
@@ -25,5 +25,5 @@ export function markdownImageUrl(base: string, documentPath: string | undefined,
     if (documentPath === undefined) return undefined
     path = pathPartsOf(documentPath).directory + path
   }
-  return new URL(`api/file?path=${encodeURIComponent(path)}`, base).href
+  return fileMediaUrl(base, path)
 }
diff --git a/packages/util/workspace-path/README.i18n.yaml b/packages/util/workspace-path/README.i18n.yaml
index 0f1d1603b1..1ebe67bac4 100644
--- a/packages/util/workspace-path/README.i18n.yaml
+++ b/packages/util/workspace-path/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/workspace-path/README.md
-README.md: ab7787f3649c8f75a0f0e0745bc78ea32edb5925
-README.zh.md: 270c79f7bb57def13a7656e8f76f900c1e094f4f
+README.md: 2de3157ee8bbe5ea216be303c1a1520d4b92126c
+README.zh.md: b46402b0ecf4025224768a29af1ea984ff7d497f
diff --git a/packages/util/workspace-path/README.md b/packages/util/workspace-path/README.md
index ab7787f364..2de3157ee8 100644
--- a/packages/util/workspace-path/README.md
+++ b/packages/util/workspace-path/README.md
@@ -26,6 +26,8 @@ A resource address is `dsh-resource://<type>/…`, and the type — the URI host
 
 `sessionFileAddress(sessionId, path)` normalizes `\` to `/` and drops leading `./`, but preserves leading `/` characters. Every id and path segment is component-encoded with `:` kept literal. `fileAddressFor(sessionId, cwd, path)` always builds a Session address: paths inside `cwd` become relative; other absolute paths, including when `cwd` is unknown, stay absolute within that Session address. `absoluteFileAddress(absolutePath)` builds only the Session-less form. `parseFileAddress(address)` checks the exact file-address prefix, ignores query and fragment suffixes, decodes each segment, and returns `{ scope, sessionId, path }` for a Session address or `{ scope, path }` for the Session-less form. Another type or scheme, an unknown scope, a missing id or path, or a malformed escape returns `undefined`.
 
+`fileMediaUrl(base, path)` builds an authenticated file-route URL from an already-decoded absolute path. It preserves literal percent signs and deployment prefixes, and rejects non-HTTP application bases, relative paths, network-path prefixes, and control characters. Markdown owners decode authored URLs before calling it; native file-card paths are passed unchanged.
+
 -----
 
 ## Known Limitations and Deferred Work
diff --git a/packages/util/workspace-path/README.zh.md b/packages/util/workspace-path/README.zh.md
index 270c79f7bb..b46402b0ec 100644
--- a/packages/util/workspace-path/README.zh.md
+++ b/packages/util/workspace-path/README.zh.md
@@ -26,6 +26,8 @@ kind: "package-library"
 
 `sessionFileAddress(sessionId, path)` 将 `\` 归一为 `/`，去掉前导 `./`，但保留前导 `/` 字符。id 和每个路径段都做组件编码，`:` 保持字面。`fileAddressFor(sessionId, cwd, path)` 始终构造 Session 地址：`cwd` 内的路径转为相对路径；其他绝对路径（包括 `cwd` 未知时）仍作为该 Session 地址内的绝对路径。`absoluteFileAddress(absolutePath)` 只构造不带 Session 的形式。`parseFileAddress(address)` 检查精确的文件地址前缀、忽略查询与片段后缀、逐段解码，并为 Session 地址返回 `{ scope, sessionId, path }`，为不带 Session 的形式返回 `{ scope, path }`。其他 type 或 scheme、未知作用域、缺 id 或路径，或错误转义都返回 `undefined`。
 
+`fileMediaUrl(base, path)` 从已解码的绝对路径生成带认证文件路由的 URL，保留字面量百分号与部署前缀，并拒绝非 HTTP 应用基址、相对路径、网络路径前缀和控制字符。Markdown 调用方先解码所写 URL；原生文件卡片路径原样传入。
+
 -----
 
 ## 已知限制与暂缓事项
diff --git a/packages/util/workspace-path/src/index.ts b/packages/util/workspace-path/src/index.ts
index 00a1db7732..84dfd8885b 100644
--- a/packages/util/workspace-path/src/index.ts
+++ b/packages/util/workspace-path/src/index.ts
@@ -110,3 +110,15 @@ export function relativizeToCwd(text: string, cwd: string | undefined): string {
   if (text.startsWith(`${root}/`) || text.startsWith(`${root}\\`)) return text.slice(root.length + 1)
   return text
 }
+
+/**
+ * Address a decoded absolute file path through the authenticated file route.
+ * @param base - HTTP(S) application base, including its deployment prefix.
+ * @param path - Native file path; URL escapes in authored Markdown must already be decoded.
+ * @returns File URL, or undefined for unsupported transports and non-absolute paths.
+ */
+export function fileMediaUrl(base: string, path: string): string | undefined {
+  if (!/^https?:/u.test(base) || !isAbsoluteWorkspacePath(path)
+    || /^[/\\]{2}/u.test(path) || /[\u0000-\u001f\u007f]/u.test(path)) return undefined
+  return new URL(`api/file?path=${encodeURIComponent(path)}`, base).href
+}
diff --git a/packages/util/workspace-path/tests/file-media-url.spec.ts b/packages/util/workspace-path/tests/file-media-url.spec.ts
new file mode 100644
index 0000000000..0053373989
--- /dev/null
+++ b/packages/util/workspace-path/tests/file-media-url.spec.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { fileMediaUrl } from '../src/index.ts'
+
+describe('fileMediaUrl', () => {
+  it.each(['/work/测试 文件#100%.png', 'C:\\work\\测试 文件.png'])(
+    'preserves the decoded native path %s under a mounted application', (path) => {
+      const url = new URL(fileMediaUrl('https://host/tools/dsh/', path)!)
+      expect(url.pathname).toBe('/tools/dsh/api/file')
+      expect(url.searchParams.get('path')).toBe(path)
+    },
+  )
+  it.each(['image.png', '//host/image.png', '\\\\host\\image.png', '/work/\u0000.png', '/work/\n.png'])(
+    'rejects a non-local or invalid path %s', (path) => {
+      expect(fileMediaUrl('https://host/', path)).toBeUndefined()
+    },
+  )
+  it('requires an HTTP application base', () => {
+    expect(fileMediaUrl('file:///app/', '/work/image.png')).toBeUndefined()
+  })
+})
diff --git a/snapshots/web/fresh-round-trip/system-prompt.expected.md b/snapshots/web/fresh-round-trip/system-prompt.expected.md
index e05a41da44..55df661994 100644
--- a/snapshots/web/fresh-round-trip/system-prompt.expected.md
+++ b/snapshots/web/fresh-round-trip/system-prompt.expected.md
@@ -30,7 +30,7 @@ Use subagent in the background by default. Start independent delegations togethe
 
 Use subagent_fork in the background by default. Start independent delegations together in one assistant message and continue useful work while they run. Set `run_in_background: false` only when your next action depends on that subagent's result. When a background run settles, the runtime sends you a notice containing its outcome and any final assistant message.
 
-Prefer showing the primary results within your final response alongside a brief explanation. Markdown file links such as [Report](path/to/report.html) open the file in the sidebar preview. For images, you can add an inline preview such as ![Preview](/absolute/path/image.png); include a file link as well so the image remains accessible in clients that cannot display it inline. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, especially Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
+Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
 
 The DeepSeek Harness implementation checkout is at {{sourceRoot}}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.
 
diff --git a/snapshots/web/ptc-round/system-prompt.expected.md b/snapshots/web/ptc-round/system-prompt.expected.md
index 7b0afba97a..fb616a1ef9 100644
--- a/snapshots/web/ptc-round/system-prompt.expected.md
+++ b/snapshots/web/ptc-round/system-prompt.expected.md
@@ -546,7 +546,7 @@ declare const tools: {
 }
 ```
 
-Prefer showing the primary results within your final response alongside a brief explanation. Markdown file links such as [Report](path/to/report.html) open the file in the sidebar preview. For images, you can add an inline preview such as ![Preview](/absolute/path/image.png); include a file link as well so the image remains accessible in clients that cannot display it inline. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, especially Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
+Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
 
 The DeepSeek Harness implementation checkout is at {{sourceRoot}}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.
 

From 48392399545a31ae492402d411b8a31ae1de61ae Mon Sep 17 00:00:00 2001
From: Kaige-Gao <michellegkg@163.com>
Date: Wed, 23 Sep 2026 17:12:03 +0800
Subject: [PATCH 2/6] fix(chat): address image preview review and coverage gaps

---
 .../file-reference-prompt.expected.md         |  2 +-
 apps/web/tests/markdown-images.e2e.ts         | 23 +++++-
 .../src/client/chat/AssistantMarkdown.tsx     |  3 +
 .../client/ui-deliverables/README.i18n.yaml   |  4 +-
 packages/client/ui-deliverables/README.md     |  4 +-
 packages/client/ui-deliverables/README.zh.md  |  4 +-
 packages/client/ui-deliverables/src/index.ts  |  2 +-
 .../ui-deliverables/tests/prompt.host.spec.ts |  2 +-
 .../client/ui-primitives/README.i18n.yaml     |  4 +-
 packages/client/ui-primitives/README.md       |  6 +-
 packages/client/ui-primitives/README.zh.md    |  6 +-
 .../ui-primitives/src/HoverCard.module.css    |  2 +-
 .../client/ui-primitives/src/HoverCard.tsx    | 37 ++++++----
 .../ui-primitives/src/ImageLightbox.tsx       |  4 +-
 .../client/ui-primitives/src/ImagePreview.tsx | 13 ++--
 packages/client/ui-primitives/src/index.ts    |  1 -
 .../src/markdown/local-image-syntax.ts        | 15 ++--
 .../ui-primitives/src/markdown/render.tsx     |  5 +-
 .../tests/hover-card.client.spec.tsx          | 74 ++++++++++++++++++-
 .../tests/image-lightbox.client.spec.tsx      |  9 ++-
 .../markdown-image-entries.client.spec.tsx    | 34 ++++++++-
 .../src/client/markdown/path-images.ts        |  3 +-
 .../system-prompt.expected.md                 |  2 +-
 .../web/ptc-round/system-prompt.expected.md   |  2 +-
 24 files changed, 199 insertions(+), 62 deletions(-)
 rename packages/client/{ui-attachment => ui-primitives}/tests/image-lightbox.client.spec.tsx (86%)

diff --git a/apps/web/tests/expected/web-runtime-context/file-reference-prompt.expected.md b/apps/web/tests/expected/web-runtime-context/file-reference-prompt.expected.md
index 7a9e1faff5..62c89bd029 100644
--- a/apps/web/tests/expected/web-runtime-context/file-reference-prompt.expected.md
+++ b/apps/web/tests/expected/web-runtime-context/file-reference-prompt.expected.md
@@ -1 +1 @@
-Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
+Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison. Use [Description](<path/to/image.png>) when referring to an image or listing files. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
diff --git a/apps/web/tests/markdown-images.e2e.ts b/apps/web/tests/markdown-images.e2e.ts
index ed93628d8b..bc24459a1e 100644
--- a/apps/web/tests/markdown-images.e2e.ts
+++ b/apps/web/tests/markdown-images.e2e.ts
@@ -288,7 +288,12 @@ describe('web e2e: Markdown image rendering', () => {
     const hoverImage = page.getByRole('img', { name: './valid.png', exact: true })
     await hoverImage.waitFor()
     await expect.poll(() => hoverImage.evaluate(element => (element as HTMLImageElement).naturalWidth)).toBe(1)
-    await link.press('Escape')
+    await page.keyboard.press('Escape')
+    await hoverImage.waitFor({ state: 'detached' })
+    await link.press('Tab')
+    await page.keyboard.press('Shift+Tab')
+    await hoverImage.waitFor()
+    await page.keyboard.press('Escape')
     await hoverImage.waitFor({ state: 'detached' })
 
     const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
@@ -297,7 +302,21 @@ describe('web e2e: Markdown image rendering', () => {
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
-    await link.click()
+    await link.evaluate((element) => { element.scrollIntoView({ block: 'end' }) })
+    await page.mouse.move(0, 0)
+    await link.hover()
+    await hoverImage.waitFor()
+    const linkRect = await link.boundingBox()
+    if (linkRect === null) throw new Error('image link is not visible')
+    const previewRect = await hoverImage.evaluate((element) => {
+      const rect = element.parentElement!.parentElement!.getBoundingClientRect()
+      return { top: rect.top, bottom: rect.bottom }
+    })
+    expect(previewRect.bottom <= linkRect.y || previewRect.top >= linkRect.y + linkRect.height).toBe(true)
+    const thumbnailRect = await hoverImage.boundingBox()
+    if (thumbnailRect === null) throw new Error('image preview is not visible')
+    expect(thumbnailRect.y + thumbnailRect.height).toBeLessThanOrEqual(previewRect.bottom)
+    await page.mouse.click(linkRect.x + linkRect.width / 2, linkRect.y + linkRect.height / 2)
     await expect.poll(() => page.locator('[data-image-preview] img').evaluate(element => (element as HTMLImageElement).naturalWidth)).toBe(1)
   }, 60_000)
 })
diff --git a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
index 41d8c5b8c1..d6d7c0d3ad 100644
--- a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
@@ -11,6 +11,9 @@ import { useSearchableHidden } from './searchable-hidden.ts'
 import css from './AssistantMarkdown.module.css'
 
 /**
+ * Standalone fallback for image destinations (query/fragment suffixes are ignored).
+ * Chat fileImages resolves decoded file references against cwd; pathImages also
+ * serves this component outside that provider and accepts legacy image URL suffixes.
  * Resolve an authored absolute image path against the document's file API.
  * @param base - canonical `document.baseURI` at render time.
  * @param value - authored Markdown destination; URL escapes are decoded once.
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index a032d8124f..4eda4bc0fc 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-deliverables/README.md
-README.md: 5ddf6cfc314a56c096ee75849873471c3f5366ab
-README.zh.md: 23b992ee192f2f24e21b3d3ea73877c16b92990e
+README.md: 786495d76098ce134ac378858c177cc498bd4c9f
+README.zh.md: 9a1f000845ffab755ce23bd570cbe1a79b133676
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index 5ddf6cfc31..786495d760 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -91,7 +91,7 @@ Read these pages when the deliverables surface is not enough. They move from the
 
 #### What the model sees
 
-The guidance prefers primary results in the final reply: inline images support explanations and comparisons, image links offer hover previews and open in the Sidebar, and image file cards serve separate deliverables. File destinations use angle brackets, including paths with spaces. It recommends separate `present` cards for complete file deliverables, especially Office files, usually selecting the most important one or two, with at most four files per call when more are needed. It discourages cards solely for code edits and extra commands to inspect diff visibility. This guidance applies even with developer tools disabled: it accepts fewer file surfaces to avoid duplicate presentation and unnecessary tool calls. It asks the model to link every existing-file mention outside commands, configuration expressions, and code blocks, including repeats and tables. Labels default to filenames or clear aliases, with only enough parent directories to distinguish files. Precise references display `filename:24` or `filename:24–30`; their destinations retain full relative or absolute paths with `#L24` or `#L24-L30` anchors. The display suffix contains neither `#` nor `L`.
+The guidance prefers primary results in the final reply: inline images support explanations and comparisons, image links serve references and file lists, and image file cards serve separate deliverables. File destinations use angle brackets, including paths with spaces. It recommends separate `present` cards for complete file deliverables, especially Office files, usually selecting the most important one or two, with at most four files per call when more are needed. It discourages cards solely for code edits and extra commands to inspect diff visibility. This guidance applies even with developer tools disabled: it accepts fewer file surfaces to avoid duplicate presentation and unnecessary tool calls. It asks the model to link every existing-file mention outside commands, configuration expressions, and code blocks, including repeats and tables. Labels default to filenames or clear aliases, with only enough parent directories to distinguish files. Precise references display `filename:24` or `filename:24–30`; their destinations retain full relative or absolute paths with `#L24` or `#L24-L30` anchors. The display suffix contains neither `#` nor `L`.
 
 #### Token effect
 
@@ -108,7 +108,7 @@ The section is static at first-party order 9000 for the lifetime of the package
 
 These limits define the current deliverables vocabulary. They are current package constraints, not a general file-linking comparison or a task backlog.
 
-- **Inline local images require HTTP(S) and POSIX absolute paths**: Desktop’s `dsh-app:` pages and Windows drive-letter paths do not support inline local images. The guidance retains a Markdown file link so users can open the Sidebar preview.
+- **Inline local images require an HTTP(S) page**: Desktop’s `dsh-app:` pages do not support this file route. POSIX absolute paths and Windows drive-letter paths are supported; relative Chat image paths require the viewed Session’s workspace root. Separate image file links are optional.
 - **Mention matching is exact path or unique basename only** — a suffix mention stays inert; widening the matcher is deferred until a real closing-message shape needs it.
 - **Terminal-created files require explicit delivery** — the card lists them once git records the change, but delivery cards and inline-code references require `present`; explicit Markdown links can reference existing files directly.
 - **Declarations do not preserve file contents** — reopening or transferring a Session requires source files accessible through the viewed Session’s filesystem. Missing files, directories, and final symbolic links return 404.
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index 23b992ee19..9a1f000845 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -91,7 +91,7 @@ Node 半部注册[模型体验](#model-experience)所述的静态 `ui:deliverabl
 
 #### 模型看到的内容
 
-提示词建议在最终回复中展示主要结果：内嵌图片用于讲解与对比，图片链接提供悬停预览并在点击时打开 Sidebar，图片文件卡片用于独立交付。文件目标路径使用尖括号包裹，包括含空格的路径。对于需要完整文件的交付，尤其是 Office 文件，建议使用独立的 `present` 卡片，通常选最重要的一两项，需要时可以更多，但每次调用最多四项。提示词建议避免仅为列出代码改动生成卡片，也不为确认 diff 是否显示额外运行命令。开发者工具关闭时仍采用这条建议，接受较少的文件展示入口，以减少重复展示和不必要的工具调用。文件引用要求链接命令、配置表达式和代码块以外的每次现有文件提及，包括重复提及和表格。标签默认使用文件名或清楚的别名，仅添加足以区分文件的父目录。精确引用显示为 `filename:24` 或 `filename:24–30`；目标保留完整相对路径或绝对路径，以及 `#L24` 或 `#L24-L30` 锚点。显示后缀不含 `#` 或 `L`。
+提示词建议在最终回复中展示主要结果：内嵌图片用于讲解与对比，图片链接用于引用和文件列表，图片文件卡片用于独立交付。文件目标路径使用尖括号包裹，包括含空格的路径。对于需要完整文件的交付，尤其是 Office 文件，建议使用独立的 `present` 卡片，通常选最重要的一两项，需要时可以更多，但每次调用最多四项。提示词建议避免仅为列出代码改动生成卡片，也不为确认 diff 是否显示额外运行命令。开发者工具关闭时仍采用这条建议，接受较少的文件展示入口，以减少重复展示和不必要的工具调用。文件引用要求链接命令、配置表达式和代码块以外的每次现有文件提及，包括重复提及和表格。标签默认使用文件名或清楚的别名，仅添加足以区分文件的父目录。精确引用显示为 `filename:24` 或 `filename:24–30`；目标保留完整相对路径或绝对路径，以及 `#L24` 或 `#L24-L30` 锚点。显示后缀不含 `#` 或 `L`。
 
 #### Token 影响
 
@@ -108,7 +108,7 @@ Node 半部注册[模型体验](#model-experience)所述的静态 `ui:deliverabl
 
 这些限制界定了当前产出物词表。它们是当前包约束，不是通用文件链接对比或任务积压。
 
-- **本地行内图片要求 HTTP(S) 页面和 POSIX 绝对路径**：Desktop 的 `dsh-app:` 页面和 Windows 盘符路径不支持本地行内图片。提示词要求保留 Markdown 文件链接，让用户仍可打开 Sidebar 预览。
+- **本地行内图片要求 HTTP(S) 页面**：Desktop 的 `dsh-app:` 页面不支持此文件路由。支持 POSIX 绝对路径与 Windows 盘符路径；Chat 中的相对图片路径需要当前查看的 Session 工作区根目录。图片的独立文件链接是可选的。
 - **提及匹配只认精确路径或唯一 basename**——后缀式提及保持惰性；等真实的收尾消息形态产生需求后再放宽匹配规则。
 - **终端创建的文件需要显式交付**——git 记录到改动后卡片会列出它们，但交付卡片和行内代码引用需要调用 `present`；显式 Markdown 链接可以直接引用现有文件。
 - **声明不保存文件内容**：重新打开或转移 Session 后，源文件仍需能被当前查看的 Session 文件系统访问。文件缺失、为目录或最终路径为符号链接时返回 404。
diff --git a/packages/client/ui-deliverables/src/index.ts b/packages/client/ui-deliverables/src/index.ts
index 7762a67d16..6280740f3c 100644
--- a/packages/client/ui-deliverables/src/index.ts
+++ b/packages/client/ui-deliverables/src/index.ts
@@ -15,7 +15,7 @@ export const inject = ['systemPrompt', 'connection', 'sessionQuery', 'sessionCon
 
 /** Static Web guidance for primary outputs and existing-file references. */
 const FILE_REFERENCE_PROMPT = 'Prefer showing the primary results within your final response alongside a brief explanation. '
-  + 'Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. '
+  + 'Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison. Use [Description](<path/to/image.png>) when referring to an image or listing files. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. '
   + 'Do not call present just to list edited source files, or run commands to check whether a diff view will appear. '
   + 'Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. '
   + 'Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. '
diff --git a/packages/client/ui-deliverables/tests/prompt.host.spec.ts b/packages/client/ui-deliverables/tests/prompt.host.spec.ts
index 249792ec88..001d73eada 100644
--- a/packages/client/ui-deliverables/tests/prompt.host.spec.ts
+++ b/packages/client/ui-deliverables/tests/prompt.host.spec.ts
@@ -29,7 +29,7 @@ describe('ui-deliverables node plugin', () => {
 
     const section = (await ctx.systemPrompt.assemble()).sections
       .find(entry => entry.name === 'ui:deliverable-file-references')
-    expect(section?.text).toMatchInlineSnapshot('"Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix."')
+    expect(section?.text).toMatchInlineSnapshot('"Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison. Use [Description](<path/to/image.png>) when referring to an image or listing files. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix."')
 
     // Only live request pins track current guidance; seeded sessions retain their recorded prompt.
     for (const scenario of ['fresh-round-trip', 'ptc-round']) {
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index b7c783080c..1747da058c 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md
-README.md: 349921e171336dc16f9ae38ac815a9e042bc447c
-README.zh.md: eec967d30243566ce2f78e1b325c1af96d663519
+README.md: fbb8ef676e55d1ef2c3c5c8a6c91a12a3c8fe556
+README.zh.md: 822ff17c3c4c6b02339cdacd03d9c52c67a738c7
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 349921e171..fbb8ef676e 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -54,7 +54,7 @@ Check this table before writing a control in a feature package. A plugin cannot
 | `OnboardingSurface` | First-run stage that holds the application root inert. |
 | `Tooltip` | Hover text anchored to a cloned child; optional `portal` rendering escapes clipping containers and ancestor stacking contexts that cap the bubble's z-index. |
 | `HoverCard` | Hover preview the pointer can rest on and select from; optional copy button. |
-| `ImageLightbox`, `ImagePreview` | Shared image modal and passive contained preview with loading/failure states. |
+| `ImageLightbox` | Shared image modal with focus restoration and Escape dismissal. |
 | `Toast` | Transient top-center banner held for the owner's `holdMs`. |
 | `SettingsForm`, `SettingsValueField`, `SettingsSecretField` | The frame and the controls of a plugin's settings page: the frame takes its copy as `labels`, saves only on its button, and discards on unmount; a value field shows staged text with the overridden badge and reset; a secret field starts blank and reports only whether a value is configured. |
 | `SettingsFormModel`, `settingsNumberField`, `settingsTextField` | The staged-edit model behind such a page over a settings scope: drafts are staged and written on save, a field is overridden by its presence in the user layer, and a save that did not land keeps its drafts. |
@@ -86,7 +86,7 @@ The catalog above lists what each export is for; this section covers the behavio
 
 The nearest `MarkdownDelegateProvider` supplies optional `openExternalLink` and `openFile` navigation callbacks. Nested providers replace the enclosing capabilities, and callback changes reach already-rendered links without rebuilding Markdown. Its `openFile` makes local Markdown links clickable after settlement. Absolute and workspace-relative paths support percent escapes and `#L24` / `#L24-L30` fragments; ranges open at their first line. Literal `?` and `#` in filenames must be percent-encoded. The tooltip uses the decoded path and supplies the accessible name when the label is empty. The callback receives the decoded path and optional line, while the renderer preserves the label and displays a file icon. Without a callback, local links remain text. URL schemes, queries, unsupported fragments, and malformed destinations never reach the file opener.
 
-`MarkdownText` renders untrusted GFM and TeX math, blocks unsafe links and images, and can turn resolved file mentions into explicit controls. A surrounding `MarkdownDelegateProvider` receives sanitized HTTP(S) URLs from ordinary clicks; modified clicks and links outside a provider retain native external-anchor behavior. When the owner passes a `pathImages` vocabulary, image destinations that are local media paths rewrite to displayable URLs on settled renders only (the same streaming gate as file mentions); without a vocabulary, local destinations remain inert alt text. A load or decode failure replaces the image with its authored alt text, or the original destination when alt is empty. Changing the image source permits a fresh load. While a reply streams, it freezes completed blocks, advances a top-level open fence by completed lines, and highlights that fence from saved Shiki grammar state. Completed token lines enter fixed-size React groups, so later chunks reconcile only the growing group; an unchanged fence retains that DOM when the final full parse resolves cross-document syntax. `TerminalBlock`, `ReadBlock`, `DiffBlock`, `SearchBlock`, and `WebBlock` render the matching tool-result intent with copy controls, overflow handling, and ANSI processing where applicable. `JsonTree` and `JsonBlock` inspect JSON values read-only, while `projectUserText` projects sent user text into inline plain runs and reference chips for the message bubble and queue rows. Reference labels inherit the consumer’s wrapping policy: long names wrap within a bubble, while queue previews retain their single-line layout. When supplied with `UserTextReferences`, file and skill references become keyboard-accessible preview buttons using the same hover and focus styling as prose file links; the first pointer click can open a preview, while subsequent clicks and existing text selections retain native selection handling. Keyboard activation opens previews even when text is selected.
+`MarkdownText` renders untrusted GFM and TeX math, blocks unsafe links and images, and can turn resolved file mentions into explicit controls. A surrounding `MarkdownDelegateProvider` receives sanitized HTTP(S) URLs from ordinary clicks; modified clicks and links outside a provider retain native external-anchor behavior. When the owner passes a `pathImages` vocabulary, image destinations that are local media paths rewrite to displayable URLs on settled renders only (the same streaming gate as file mentions); without a vocabulary, local destinations remain inert alt text. A load or decode failure replaces the image with its authored alt text, or the original destination when alt is empty; `fileImages` additionally supplies a localized failure prefix. Changing the image source permits a fresh load. While a reply streams, it freezes completed blocks, advances a top-level open fence by completed lines, and highlights that fence from saved Shiki grammar state. Completed token lines enter fixed-size React groups, so later chunks reconcile only the growing group; an unchanged fence retains that DOM when the final full parse resolves cross-document syntax. `TerminalBlock`, `ReadBlock`, `DiffBlock`, `SearchBlock`, and `WebBlock` render the matching tool-result intent with copy controls, overflow handling, and ANSI processing where applicable. `JsonTree` and `JsonBlock` inspect JSON values read-only, while `projectUserText` projects sent user text into inline plain runs and reference chips for the message bubble and queue rows. Reference labels inherit the consumer’s wrapping policy: long names wrap within a bubble, while queue previews retain their single-line layout. When supplied with `UserTextReferences`, file and skill references become keyboard-accessible preview buttons using the same hover and focus styling as prose file links; the first pointer click can open a preview, while subsequent clicks and existing text selections retain native selection handling. Keyboard activation opens previews even when text is selected.
 
 `MarkdownText` defaults to `variant="body"`. Use `variant="compact"` for secondary content: its 13px text and 20px line height follow the content-size setting, all heading levels use the same size with weight 600, and paragraphs and lists use tighter spacing. Text, links, and code keep the tertiary color; dotted underlines distinguish links. Code headers scroll with their blocks. Tables and math stay enabled at the surrounding text size and scroll horizontally within the available width. Both variants share the parser and streaming cache.
 
@@ -96,7 +96,7 @@ The nearest `MarkdownDelegateProvider` supplies optional `openExternalLink` and
 
 `JsonTree` clamps collapsed strings to `collapsedStringLines` (three by default). Expanded strings show raw text, retain sibling commas, and fit within the window and outer scrolling containers. Resize and ancestor-scroll events update that limit. Row copy feedback updates independently of JSON value rendering; pending clipboard writes cannot update a different row or an unmounted tree.
 
-`ImageLightbox` is the shared original-image modal with focus restoration and Escape dismissal; `ImagePreview` is a passive, contained thumbnail with owner-supplied loading/failure labels. `HoverCard.inline` keeps a file link in the text flow and uses the shared menu material, keyboard focus, and viewport-clamped placement. `MarkdownDelegateProvider.fileImages` supplies a decoded-path resolver and complete image labels: settled image links gain hover previews, and standalone images gain lightbox activation. Image-only anchors retain their single navigation target. The parser recovers only complete, unescaped, standalone local image references with bare spaces and an unambiguous supported image suffix; code and ambiguous destinations remain literal.
+`ImageLightbox` is the shared original-image modal with focus restoration and Escape dismissal. The internal thumbnail renderer receives loading/failure labels from its owner. `HoverCard.inline` keeps a file link in the text flow and uses the shared menu material, keyboard-visible focus, and placement above or below the anchor without covering it. Escape closes an open thumbnail even when focus is elsewhere; subsequent Escape presses reach the owner. `MarkdownDelegateProvider.fileImages` supplies a decoded-path resolver and complete image labels: settled image links gain hover previews, and standalone images gain lightbox activation. Image-only anchors retain their single navigation target. The parser recovers only complete, unescaped, standalone local image references with bare spaces and an unambiguous supported image suffix; code and ambiguous destinations remain literal.
 
 ### Localizing copy
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index eec967d302..822ff17c3c 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -54,7 +54,7 @@ kind: "package-library"
 | `OnboardingSurface` | 首次运行的引导舞台，期间保持应用根节点 inert。 |
 | `Tooltip` | 锚定在克隆子元素上的悬停文本；可通过 `portal` 渲染到外层，避免被容器裁剪，或受祖先层叠上下文限制其 z-index。 |
 | `HoverCard` | 指针可停留、可选中的悬停预览；可选带复制按钮。 |
-| `ImageLightbox`, `ImagePreview` | 共享图片浮层，以及带加载和失败状态的等比预览。 |
+| `ImageLightbox` | 共享图片浮层，支持焦点恢复与 Esc 关闭。 |
 | `Toast` | 顶部居中的瞬时横幅，保持时长由所有者的 `holdMs` 决定。 |
 | `SettingsForm`、`SettingsValueField`、`SettingsSecretField` | 插件设置页的框架与控件：框架以 `labels` 接收文案，只在按钮点击时保存，卸载即丢弃；值字段显示暂存文本以及已覆盖标签和重置；密文字段每次为空，只报告是否已配置。 |
 | `SettingsFormModel`、`settingsNumberField`、`settingsTextField` | 这类页面背后基于设置 scope 的暂存编辑模型：草稿先暂存、保存时写入，字段是否被覆盖看用户层是否含有它，未落地的保存保留草稿。 |
@@ -86,7 +86,7 @@ kind: "package-library"
 
 最近的 `MarkdownDelegateProvider` 提供可选的 `openExternalLink` 和 `openFile` 导航回调。嵌套 Provider 替换外层能力，回调变化无需重新构建 Markdown 即可到达已渲染链接。其 `openFile` 使本地 Markdown 链接在落定后可点击。绝对路径和工作区相对路径支持百分号转义以及 `#L24` / `#L24-L30` 片段；范围定位到起始行。文件名中的字面 `?` 和 `#` 必须百分号编码。悬停提示使用解码后的路径，并在标签为空时提供可访问名称。回调接收解码后的路径和可选行号，渲染器保留标签并显示文件图标。不传回调时，本地链接仍为文本。URL 协议、查询串、不支持的片段及格式错误的目标不会传给文件打开器。
 
-`MarkdownText` 渲染不可信的 GFM 与 TeX 公式、阻止不安全的链接与图片，并可把已解析的文件提及转换为显式控件。外层 `MarkdownDelegateProvider` 会接收普通点击产生的已净化 HTTP(S) URL；带修饰键的点击和 Provider 外的链接保留原生外部 anchor 行为。当 owner 传入 `pathImages` 词表时，本地媒体路径的图片目标只在落定渲染阶段重写为可展示 URL（与 file mentions 相同的流式门）；不传词表时本地目标保持惰性 alt 文本。加载或解码失败后，图片替换为作者的 alt 文本；alt 为空时显示原始目标路径。图片源变化后可重新加载。回复流式输出时，它冻结已完成的块、按已完成行推进顶层未闭合 fence，并从保存的 Shiki grammar state 为该 fence 增量高亮。已完成的 token 行进入固定大小的 React 分组，后续分片只 reconcile 正在增长的分组；最终全量解析解决跨文档语法时，未变化的 fence 会保留该 DOM。`TerminalBlock`、`ReadBlock`、`DiffBlock`、`SearchBlock` 与 `WebBlock` 把对应的工具结果意图渲染为带复制控件、溢出处理及适用时 ANSI 处理的卡片。`JsonTree` 与 `JsonBlock` 以只读方式检查 JSON 值；`projectUserText` 把已发送的用户文本投影为行内普通文本段与引用 chip，供消息气泡和排队行使用。引用名称继承调用方的换行规则：长名称在气泡内换行，排队预览保持单行布局。传入 `UserTextReferences` 时，文件和 skill 引用成为支持键盘操作的预览按钮，复用正文文件链接的悬停和聚焦样式；第一次指针点击可以打开预览，后续点击和已有选区保留原生选择行为。键盘激活在存在选区时仍可打开预览。
+`MarkdownText` 渲染不可信的 GFM 与 TeX 公式、阻止不安全的链接与图片，并可把已解析的文件提及转换为显式控件。外层 `MarkdownDelegateProvider` 会接收普通点击产生的已净化 HTTP(S) URL；带修饰键的点击和 Provider 外的链接保留原生外部 anchor 行为。当 owner 传入 `pathImages` 词表时，本地媒体路径的图片目标只在落定渲染阶段重写为可展示 URL（与 file mentions 相同的流式门）；不传词表时本地目标保持惰性 alt 文本。加载或解码失败后，图片替换为作者的 alt 文本；alt 为空时显示原始目标路径；`fileImages` 还提供本地化的失败提示前缀。图片源变化后可重新加载。回复流式输出时，它冻结已完成的块、按已完成行推进顶层未闭合 fence，并从保存的 Shiki grammar state 为该 fence 增量高亮。已完成的 token 行进入固定大小的 React 分组，后续分片只 reconcile 正在增长的分组；最终全量解析解决跨文档语法时，未变化的 fence 会保留该 DOM。`TerminalBlock`、`ReadBlock`、`DiffBlock`、`SearchBlock` 与 `WebBlock` 把对应的工具结果意图渲染为带复制控件、溢出处理及适用时 ANSI 处理的卡片。`JsonTree` 与 `JsonBlock` 以只读方式检查 JSON 值；`projectUserText` 把已发送的用户文本投影为行内普通文本段与引用 chip，供消息气泡和排队行使用。引用名称继承调用方的换行规则：长名称在气泡内换行，排队预览保持单行布局。传入 `UserTextReferences` 时，文件和 skill 引用成为支持键盘操作的预览按钮，复用正文文件链接的悬停和聚焦样式；第一次指针点击可以打开预览，后续点击和已有选区保留原生选择行为。键盘激活在存在选区时仍可打开预览。
 
 `MarkdownText` 默认为 `variant="body"`。次级内容使用 `variant="compact"`：其 13px 字号与 20px 行高跟随内容字号设置，各级标题保持同一字号并使用 600 字重，段落与列表采用更紧凑的间距。正文、链接和代码均保持 tertiary 颜色，以点状下划线区分链接。代码标题栏随代码块滚动。表格和公式仍然启用，使用周围文字的字号，并在可用宽度内横向滚动。两个变体共享解析器与流式缓存。
 
@@ -96,7 +96,7 @@ kind: "package-library"
 
 `JsonTree` 把折叠字符串限制为 `collapsedStringLines` 行（默认三行）。展开后显示原始文本、保留同级逗号，并限制在窗口与外层滚动容器内；尺寸变化和祖先滚动事件会更新此限制。行复制反馈独立于 JSON 值渲染更新；尚未完成的剪贴板写入不会更新另一行或已卸载的树。
 
-`ImageLightbox` 是共享原图浮层，支持焦点恢复与 Esc 关闭；`ImagePreview` 是被动的等比缩略图，由调用方提供加载及失败文案。`HoverCard.inline` 使文件链接保持在文本流内，并使用共享菜单材质、键盘聚焦和视口内定位。`MarkdownDelegateProvider.fileImages` 提供已解码路径解析器与完整图片文案：消息落定后的图片链接支持悬停预览，独立图片支持点击放大。仅包含图片的链接保留单一导航目标。解析器仅恢复完整、未转义、独立成段且带明确图片扩展名的含裸空格本地图片引用；代码与有歧义的目标保持原文。
+`ImageLightbox` 是共享原图浮层，支持焦点恢复与 Esc 关闭。包内缩略图渲染器由调用方提供加载及失败文案。`HoverCard.inline` 使文件链接保持在文本流内，并使用共享菜单材质、键盘可见焦点，并在锚点上方或下方定位而不遮挡锚点。即使焦点位于其他位置，Esc 也会关闭已打开的缩略图；后续 Esc 按键继续传给 owner。`MarkdownDelegateProvider.fileImages` 提供已解码路径解析器与完整图片文案：消息落定后的图片链接支持悬停预览，独立图片支持点击放大。仅包含图片的链接保留单一导航目标。解析器仅恢复完整、未转义、独立成段且带明确图片扩展名的含裸空格本地图片引用；代码与有歧义的目标保持原文。
 
 ### 本地化文案
 
diff --git a/packages/client/ui-primitives/src/HoverCard.module.css b/packages/client/ui-primitives/src/HoverCard.module.css
index db4805c894..c6a1757d86 100644
--- a/packages/client/ui-primitives/src/HoverCard.module.css
+++ b/packages/client/ui-primitives/src/HoverCard.module.css
@@ -82,7 +82,7 @@
 
 .inline { display: inline; }
 .media {
-  width: min(300px, calc(100vw - 16px));
+  overflow: auto;
   padding: 8px;
   border: 0;
   color: var(--dsw-alias-label-primary);
diff --git a/packages/client/ui-primitives/src/HoverCard.tsx b/packages/client/ui-primitives/src/HoverCard.tsx
index dfb752ee35..aa8aec1613 100644
--- a/packages/client/ui-primitives/src/HoverCard.tsx
+++ b/packages/client/ui-primitives/src/HoverCard.tsx
@@ -11,6 +11,7 @@ import css from './HoverCard.module.css'
 const PREVIEW_FADE_MS = 100
 const PREVIEW_MAX_HEIGHT = 420
 const PREVIEW_INSET = 24
+const INLINE_PREVIEW_WIDTH = 300
 const ANCHOR_GAP = 8
 const VIEWPORT_MARGIN = 8
 
@@ -23,6 +24,7 @@ const VIEWPORT_MARGIN = 8
  * @param props.variant - compact card beside the anchor, or a preview above/below it
  * with 24px side insets, a 420px height cap, frame-top clearance, and 100ms opacity transitions.
  * @param props.widthAnchorRef - optional element whose width and horizontal position size the preview.
+ * @param props.inline - keep the anchor in prose; show a contained preview on hover or keyboard focus.
  * @param props.disabled - suppress opening; turning true dismisses an open card.
  * @param props.copyText - optional primary value copied by activation and
  * included in the card's accessible name.
@@ -114,15 +116,17 @@ export function HoverCard({
   }, [])
 
   useEffect(() => {
-    if (!open || variant !== 'preview') return
+    if (!open || (variant !== 'preview' && !inline)) return
     const dismiss = (event: KeyboardEvent): void => {
       if (event.key !== 'Escape') return
+      if (inline) event.stopPropagation()
+      clearTimer()
       cancelClose()
       close()
     }
-    window.addEventListener('keydown', dismiss)
-    return () => { window.removeEventListener('keydown', dismiss) }
-  }, [open, variant, cancelClose, close])
+    window.addEventListener('keydown', dismiss, inline)
+    return () => { window.removeEventListener('keydown', dismiss, inline) }
+  }, [open, variant, inline, cancelClose, close])
 
   // Fixed-position from the anchor rect before paint; track the anchor while
   // open (capture-phase scroll catches nested panes), as in Menu portal mode.
@@ -151,10 +155,18 @@ export function HoverCard({
         return
       }
       if (inline) {
-        const w = cardRef.current?.offsetWidth ?? 300
+        const height = Math.max(h, cardRef.current?.scrollHeight ?? 0)
+        const width = Math.max(0, Math.min(INLINE_PREVIEW_WIDTH, window.innerWidth - VIEWPORT_MARGIN * 2))
+        const topMargin = overlayTopMargin(VIEWPORT_MARGIN)
+        const belowTop = Math.max(topMargin, r.bottom + ANCHOR_GAP)
+        const above = Math.max(0, r.top - ANCHOR_GAP - topMargin)
+        const below = Math.max(0, window.innerHeight - belowTop - VIEWPORT_MARGIN)
+        const onTop = height > below && above > below
+        const maxHeight = onTop ? above : below
         setPos({
-          left: Math.max(VIEWPORT_MARGIN, Math.min(r.left, window.innerWidth - w - VIEWPORT_MARGIN)),
-          top: Math.max(overlayTopMargin(VIEWPORT_MARGIN), Math.min(r.bottom + ANCHOR_GAP, window.innerHeight - h - VIEWPORT_MARGIN)),
+          left: Math.max(VIEWPORT_MARGIN, Math.min(r.left, window.innerWidth - width - VIEWPORT_MARGIN)),
+          top: onTop ? r.top - ANCHOR_GAP - Math.min(height, maxHeight) : belowTop,
+          width, maxHeight,
         })
         return
       }
@@ -179,13 +191,13 @@ export function HoverCard({
   // card's real height is measurable, correct the bottom-edge clamp. The
   // correction converges — a clamped top satisfies the guard, so it runs once.
   useLayoutEffect(() => {
-    if (!open || pos === null || variant === 'preview') return
+    if (!open || pos === null || variant === 'preview' || inline) return
     /* v8 ignore next -- the card is mounted whenever pos is set, so the ref is attached here. */
     const h = cardRef.current?.offsetHeight ?? 0
     if (pos.top + h > window.innerHeight - VIEWPORT_MARGIN) {
       setPos({ left: pos.left, top: window.innerHeight - h - VIEWPORT_MARGIN })
     }
-  }, [open, pos, variant])
+  }, [open, pos, variant, inline])
 
   const copy = async (text: string): Promise<void> => {
     if (copied || copyingRef.current) return
@@ -248,13 +260,12 @@ export function HoverCard({
     <span
       ref={rootRef}
       className={clsx(css.root, inline && css.inline)}
-      onFocus={inline ? () => { if (!disabled) { cancelClose(); setPhase('open') } } : undefined}
+      onFocus={inline ? (event) => {
+        if (!disabled && event.target.matches(':focus-visible')) { cancelClose(); setPhase('open') }
+      } : undefined}
       onBlur={inline ? (event) => {
         if (!event.currentTarget.contains(event.relatedTarget)) { clearTimer(); cancelClose(); close() }
       } : undefined}
-      onKeyDown={inline ? (event) => {
-        if (event.key === 'Escape') { event.stopPropagation(); clearTimer(); cancelClose(); close() }
-      } : undefined}
       onPointerEnter={(event) => {
         if (disabled || (inline && event.pointerType === 'touch')) return
         // Coming back inside during the grace (the gap, or the card itself)
diff --git a/packages/client/ui-primitives/src/ImageLightbox.tsx b/packages/client/ui-primitives/src/ImageLightbox.tsx
index 76c8aa2875..893ed2fe95 100644
--- a/packages/client/ui-primitives/src/ImageLightbox.tsx
+++ b/packages/client/ui-primitives/src/ImageLightbox.tsx
@@ -40,9 +40,9 @@ export function ImageLightbox({ src, alt, labels, onClose }: {
       if (event.key === 'Escape') { event.stopPropagation(); onClose() }
       if (event.key === 'Tab') { event.preventDefault(); closeRef.current?.focus() }
     }
-    window.addEventListener('keydown', onKeyDown)
+    window.addEventListener('keydown', onKeyDown, true)
     return () => {
-      window.removeEventListener('keydown', onKeyDown)
+      window.removeEventListener('keydown', onKeyDown, true)
       restoreRef.current?.focus()
     }
   }, [onClose])
diff --git a/packages/client/ui-primitives/src/ImagePreview.tsx b/packages/client/ui-primitives/src/ImagePreview.tsx
index ffe6fec1b9..1875a151c8 100644
--- a/packages/client/ui-primitives/src/ImagePreview.tsx
+++ b/packages/client/ui-primitives/src/ImagePreview.tsx
@@ -1,33 +1,30 @@
 /** Passive, contained image preview for Markdown image links. */
 import { useState } from 'react'
-import clsx from 'clsx'
 import { IconLoadingOutlineRegular } from './icons/index.tsx'
 import css from './ImagePreview.module.css'
 
 /**
  * Render an image without introducing a second activation target.
- * @param props - Source, accessible description, localized status, and owner layout class.
+ * @param props - Source, accessible description, localized status.
  * @returns A contained preview with loading or failure status.
  */
-export function ImagePreview({ src, alt, loadingLabel, failedLabel, className }: {
+export function ImagePreview({ src, alt, loadingLabel, failedLabel }: {
   src: string
   alt: string
   loadingLabel: string
   failedLabel: string
-  className?: string | undefined
 }) {
-  return <Preview key={src} src={src} alt={alt} loadingLabel={loadingLabel} failedLabel={failedLabel} className={className} />
+  return <Preview key={src} src={src} alt={alt} loadingLabel={loadingLabel} failedLabel={failedLabel} />
 }
 
-function Preview({ src, alt, loadingLabel, failedLabel, className }: {
+function Preview({ src, alt, loadingLabel, failedLabel }: {
   src: string
   alt: string
   loadingLabel: string
   failedLabel: string
-  className: string | undefined
 }) {
   const [state, setState] = useState<'loading' | 'ready' | 'failed'>('loading')
-  return <span className={clsx(css.frame, className)}>
+  return <span className={css.frame}>
     {state !== 'failed' && <img src={src} alt={alt} loading="lazy" decoding="async" referrerPolicy="no-referrer"
       className={css.image} data-ready={state === 'ready' || undefined}
       onLoad={() => { setState('ready') }} onError={() => { setState('failed') }} />}
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index def473220c..ab82a9f6a5 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -104,4 +104,3 @@ export {
 } from './plugin-artwork.tsx'
 export { ImageLightbox } from './ImageLightbox.tsx'
 export type { ImageLightboxLabels } from './ImageLightbox.tsx'
-export { ImagePreview } from './ImagePreview.tsx'
diff --git a/packages/client/ui-primitives/src/markdown/local-image-syntax.ts b/packages/client/ui-primitives/src/markdown/local-image-syntax.ts
index a22c1b9d81..c59a323923 100644
--- a/packages/client/ui-primitives/src/markdown/local-image-syntax.ts
+++ b/packages/client/ui-primitives/src/markdown/local-image-syntax.ts
@@ -1,5 +1,6 @@
 /** Recover standalone local image references with bare spaces without changing code or source offsets. */
-import type { Root, RootContent } from 'mdast'
+import type { Root, RootContent, PhrasingContent } from 'mdast'
+import { classifyFileType } from '../FileTypeIcon.tsx'
 
 /**
  * Recover only unambiguous, unescaped image-only paragraphs containing a local path with spaces.
@@ -10,13 +11,13 @@ import type { Root, RootContent } from 'mdast'
 export function recoverLocalImages(root: Root, source: string): Root {
   const visit = (node: Root | RootContent): void => {
     if (node.type === 'paragraph' && node.children.length === 1) {
-      const child = node.children[0]
-      if (child?.type === 'text' && child.position !== undefined
+      const [child] = node.children as [PhrasingContent]
+      if (child.type === 'text' && child.position !== undefined
         && source.slice(child.position.start.offset, child.position.end.offset) === child.value) {
-        const pattern = /^!\[([^\]\n]*)\]\(((?:\/(?!\/)|\.{1,2}\/|[a-z]:[\\/])[^\n<>()[\]"']+\.(?:png|jpe?g|gif|webp|svg|bmp|ico))\)$/iu
-        const match = pattern.exec(child.value)
-        if (match !== null && match[2]?.includes(' ')) {
-          node.children = [{ type: 'image', alt: match[1] ?? '', url: match[2], position: child.position }]
+        const pattern = /^!\[([^\]\n]*)\]\(((?:\/(?!\/)|\.{1,2}\/|[a-z]:[\\/])[^\n<>()[\]"']+\.[a-z\d]+)\)$/iu
+        const match = pattern.exec(child.value) as [string, string, string] | null
+        if (match !== null && match[2].includes(' ') && classifyFileType(match[2]) === 'image') {
+          node.children = [{ type: 'image', alt: match[1], url: match[2], position: child.position }]
         }
       }
     } else if ('children' in node) {
diff --git a/packages/client/ui-primitives/src/markdown/render.tsx b/packages/client/ui-primitives/src/markdown/render.tsx
index 10b3e59fb1..aefe70f2ec 100644
--- a/packages/client/ui-primitives/src/markdown/render.tsx
+++ b/packages/client/ui-primitives/src/markdown/render.tsx
@@ -584,6 +584,7 @@ function MarkdownFileLink({ file, glyph, children }: {
 }): ReactNode {
   const { openFile, fileImages } = useMarkdownDelegate()
   if (openFile === undefined) return <>{children}</>
+  // Pure-image anchors already contain their preview and keep one navigation target.
   const preview = glyph && classifyLinkPath(file.path) === 'image' ? fileImages : undefined
   const src = preview?.resolve(file.path)
   const anchor = (
@@ -598,7 +599,7 @@ function MarkdownFileLink({ file, glyph, children }: {
     </button>
   )
   if (src === undefined || preview === undefined) return anchor
-  return <HoverCard inline anchor={anchor} copyLabel={preview.labels.open} copiedLabel={preview.labels.open}
+  return <HoverCard inline anchor={anchor}
     content={<>
       <ImagePreview src={src} alt={file.path} loadingLabel={preview.labels.loading} failedLabel={preview.labels.failed} />
       <span className={css.previewName}>{file.path.split(/[\\/]/u).pop()}</span>
@@ -655,7 +656,7 @@ function LoadedMarkdownImage({ src, alt, destination, preview }: {
   return <>
     <button type="button" className={css.imageButton} title={preview.labels.open}
       aria-label={alt ? `${preview.labels.open}: ${alt}` : preview.labels.open}
-      onClick={(event) => { event.preventDefault(); event.stopPropagation(); setOpen(true) }}>{img}</button>
+      onClick={() => { setOpen(true) }}>{img}</button>
     {open && <ImageLightbox src={src} alt={alt} labels={preview.labels} onClose={close} />}
   </>
 }
diff --git a/packages/client/ui-primitives/tests/hover-card.client.spec.tsx b/packages/client/ui-primitives/tests/hover-card.client.spec.tsx
index a71922c828..a933f6d3c2 100644
--- a/packages/client/ui-primitives/tests/hover-card.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/hover-card.client.spec.tsx
@@ -6,7 +6,7 @@ import { POINTER_GRACE_MS } from '../src/pointer-grace.ts'
 
 afterEach(cleanup)
 beforeEach(() => { vi.useFakeTimers() })
-afterEach(() => { vi.useRealTimers(); vi.unstubAllGlobals() })
+afterEach(() => { vi.useRealTimers(); vi.unstubAllGlobals(); vi.restoreAllMocks() })
 
 /** Anchor wrapper rect: the card positions from this (jsdom rects are all-zero by default). */
 function stubAnchorRect(anchor: HTMLElement, rect: { top: number; right: number }): void {
@@ -566,3 +566,75 @@ describe('HoverCard', () => {
     expect(screen.queryByText('card body')).toBeNull()
   })
 })
+
+it('opens inline previews only for keyboard focus and closes when focus leaves the anchor', () => {
+  const anchor = <><button>first</button><button>second</button></>
+  const view = render(<HoverCard inline anchor={anchor} content={<span>thumbnail</span>} />)
+  const first = screen.getByRole('button', { name: 'first' })
+  const second = screen.getByRole('button', { name: 'second' })
+  const matches = vi.spyOn(first, 'matches').mockReturnValue(false)
+  fireEvent.focus(first)
+  expect(screen.queryByText('thumbnail')).toBeNull()
+  matches.mockReturnValue(true)
+  fireEvent.focus(first)
+  expect(screen.getByText('thumbnail')).toBeTruthy()
+  fireEvent.blur(first, { relatedTarget: second })
+  expect(screen.getByText('thumbnail')).toBeTruthy()
+  fireEvent.blur(second, { relatedTarget: document.body })
+  expect(screen.queryByText('thumbnail')).toBeNull()
+  view.rerender(<HoverCard inline disabled anchor={anchor} content={<span>thumbnail</span>} />)
+  fireEvent.focus(first)
+  expect(screen.queryByText('thumbnail')).toBeNull()
+  matches.mockRestore()
+})
+
+it('dismisses an inline hover without anchor focus and lets the next Escape reach the owner', () => {
+  const ownerKey = vi.fn()
+  render(<div onKeyDown={ownerKey}>
+    <button>outside</button>
+    <HoverCard inline anchor={<button>image link</button>} content={<span>thumbnail</span>} />
+  </div>)
+  const outside = screen.getByRole('button', { name: 'outside' })
+  outside.focus()
+  const wrapper = screen.getByRole('button', { name: 'image link' }).parentElement!
+  // jsdom lacks PointerEvent; preserve its pointerType through a regular DOM event.
+  const touch = new Event('pointerover', { bubbles: true })
+  Object.defineProperty(touch, 'pointerType', { value: 'touch' })
+  fireEvent(wrapper, touch)
+  act(() => { vi.advanceTimersByTime(500) })
+  expect(screen.queryByText('thumbnail')).toBeNull()
+  fireEvent.pointerEnter(wrapper)
+  act(() => { vi.advanceTimersByTime(500) })
+  expect(document.activeElement).toBe(outside)
+  fireEvent.keyDown(outside, { key: 'a' })
+  expect(screen.getByText('thumbnail')).toBeTruthy()
+  ownerKey.mockClear()
+  fireEvent.keyDown(outside, { key: 'Escape' })
+  expect(screen.queryByText('thumbnail')).toBeNull()
+  expect(ownerKey).not.toHaveBeenCalled()
+  fireEvent.keyDown(outside, { key: 'Escape' })
+  expect(ownerKey).toHaveBeenCalledOnce()
+})
+
+it('flips inline media above a bottom link and constrains it without covering the anchor', () => {
+  render(<HoverCard inline anchor={<button>image link</button>} content={<span>thumbnail</span>} />)
+  const wrapper = screen.getByRole('button').parentElement!
+  wrapper.getBoundingClientRect = () => DOMRect.fromRect({ x: window.innerWidth - 100, y: window.innerHeight - 60, width: 80, height: 24 })
+  fireEvent.pointerEnter(wrapper)
+  act(() => { vi.advanceTimersByTime(500) })
+  const card = screen.getByText('thumbnail').parentElement!
+  Object.defineProperty(card, 'offsetHeight', { configurable: true, value: 28 })
+  Object.defineProperty(card, 'scrollHeight', { configurable: true, value: 220 })
+  fireEvent.resize(window)
+  expect(Number.parseFloat(card.style.top) + 220).toBe(window.innerHeight - 68)
+  expect(Number.parseFloat(card.style.left) + Number.parseFloat(card.style.width)).toBe(window.innerWidth - 8)
+  // Neither side fits: constrain the larger side and keep the link unobstructed.
+  Object.defineProperty(card, 'offsetHeight', { configurable: true, value: 1000 })
+  fireEvent.resize(window)
+  expect(card.style.top).toBe('8px')
+  expect(Number.parseFloat(card.style.maxHeight)).toBe(window.innerHeight - 76)
+  wrapper.getBoundingClientRect = () => DOMRect.fromRect({ x: 30, y: 10, width: 80, height: 24 })
+  fireEvent.resize(window)
+  expect(card.style.top).toBe('42px')
+  expect(Number.parseFloat(card.style.maxHeight)).toBe(window.innerHeight - 50)
+})
diff --git a/packages/client/ui-attachment/tests/image-lightbox.client.spec.tsx b/packages/client/ui-primitives/tests/image-lightbox.client.spec.tsx
similarity index 86%
rename from packages/client/ui-attachment/tests/image-lightbox.client.spec.tsx
rename to packages/client/ui-primitives/tests/image-lightbox.client.spec.tsx
index 3efde85334..93fd5a5c4a 100644
--- a/packages/client/ui-attachment/tests/image-lightbox.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/image-lightbox.client.spec.tsx
@@ -2,7 +2,7 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
-import { ImageLightbox } from '@deepseek-ai/dsh-client-ui-primitives'
+import { ImageLightbox } from '../src/ImageLightbox.tsx'
 
 afterEach(cleanup)
 
@@ -19,7 +19,12 @@ describe('ImageLightbox', () => {
     expect(document.activeElement).toBe(close)
     fireEvent.keyDown(window, { key: 'a' })
     expect(onClose).not.toHaveBeenCalled()
-    fireEvent.keyDown(window, { key: 'Escape' })
+    const outerKey = vi.fn()
+    document.body.addEventListener('keydown', outerKey)
+    try {
+      fireEvent.keyDown(close, { key: 'Escape' })
+      expect(outerKey).not.toHaveBeenCalled()
+    } finally { document.body.removeEventListener('keydown', outerKey) }
     fireEvent.click(close)
     expect(onClose).toHaveBeenCalledTimes(2)
     view.unmount()
diff --git a/packages/client/ui-primitives/tests/markdown-image-entries.client.spec.tsx b/packages/client/ui-primitives/tests/markdown-image-entries.client.spec.tsx
index ba8dd1a4f2..1d7a95b692 100644
--- a/packages/client/ui-primitives/tests/markdown-image-entries.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-image-entries.client.spec.tsx
@@ -5,7 +5,7 @@ import { MarkdownDelegateProvider } from '../src/markdown/MarkdownDelegate.tsx'
 import { MarkdownText } from './markdown-test-components.tsx'
 import { parseGfm, parseGfmWithMath } from '../src/markdown/parse.ts'
 
-afterEach(() => { cleanup(); vi.useRealTimers() })
+afterEach(() => { cleanup(); vi.useRealTimers(); vi.restoreAllMocks() })
 const labels = { open: 'View full image', dialog: 'Image preview', close: 'Close preview', loading: 'Loading image', failed: 'Image unavailable' }
 const fileImages = { resolve: (path: string) => `https://example.com/api/file?path=${encodeURIComponent('/workspace/' + path)}`, labels }
 function mount(text: string, streaming = false) {
@@ -53,7 +53,9 @@ it('loads a link preview only after hover dwell and keeps its existing sidebar a
 it('supports keyboard previews, Escape dismissal, and an inert failure state', () => {
   mount('[View comparison](graph.png)')
   const link = screen.getByRole('button', { name: 'View comparison' })
-  fireEvent.focus(link)
+  // jsdom does not model keyboard input modality for :focus-visible.
+  vi.spyOn(link, 'matches').mockReturnValue(true)
+  act(() => { link.focus() })
   fireEvent.error(screen.getByRole('img'))
   expect(screen.getByText('Image unavailable')).toBeTruthy()
   fireEvent.keyDown(link, { key: 'Escape' })
@@ -85,3 +87,31 @@ it.each([parseGfm, parseGfmWithMath])('recovers standalone bare-space paths with
     expect(JSON.stringify(parse(example))).not.toContain('"type":"image"')
   }
 })
+
+it('keeps an unavailable image link navigable without showing a hover preview', () => {
+  const openFile = vi.fn()
+  render(<MarkdownDelegateProvider openFile={openFile} fileImages={{ ...fileImages, resolve: () => undefined }}>
+    <MarkdownText text="[Image](relative.png)" />
+  </MarkdownDelegateProvider>)
+  const link = screen.getByRole('button', { name: 'Image' })
+  fireEvent.focus(link)
+  expect(screen.queryByRole('img')).toBeNull()
+  fireEvent.click(link)
+  expect(openFile).toHaveBeenCalledWith('relative.png', undefined)
+})
+
+it('labels empty-alt image activation and retains a localized failure description', () => {
+  mount('![](image.png)')
+  expect(screen.getByRole('button', { name: 'View full image' })).toBeTruthy()
+  fireEvent.error(document.querySelector('img')!)
+  expect(screen.getByText('Image unavailable · image.png')).toBeTruthy()
+  expect(screen.queryByRole('button')).toBeNull()
+})
+
+it.each([parseGfm, parseGfmWithMath])('uses the shared image categories for bare-space recovery', (parse) => {
+  for (const extension of ['avif', 'tif', 'tiff', 'heic', 'heif']) {
+    expect(parse(`![图](/work/test dir/photo.${extension})`).children[0])
+      .toMatchObject({ children: [{ type: 'image', url: `/work/test dir/photo.${extension}` }] })
+  }
+  expect(JSON.stringify(parse('![report](/work/test dir/report.pdf)'))).not.toContain('"type":"image"')
+})
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/markdown/path-images.ts b/packages/client/ui-sidebar-documentpreview/src/client/markdown/path-images.ts
index 7030cc9c26..ae7d5c6991 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/markdown/path-images.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/markdown/path-images.ts
@@ -9,7 +9,6 @@ import { fileMediaUrl, isAbsoluteWorkspacePath, pathPartsOf } from '@deepseek-ai
  * @returns an HTTP(S) file URL, or undefined for unsupported or malformed destinations.
  */
 export function markdownImageUrl(base: string, documentPath: string | undefined, destination: string): string | undefined {
-  if (!base.startsWith('http:') && !base.startsWith('https:')) return undefined
   const suffix = destination.search(/[?#]/u)
   let path: string
   try {
@@ -18,7 +17,7 @@ export function markdownImageUrl(base: string, documentPath: string | undefined,
     // Malformed percent escapes do not identify a local file.
     return undefined
   }
-  if (path.length === 0 || path.includes('\0') || /^[/\\]{2}/u.test(path)) return undefined
+  if (path.length === 0) return undefined
   const windowsDrive = /^[a-z]:[/\\]/iu.test(path)
   if (!windowsDrive && /^[a-z][a-z\d+.-]*:/iu.test(path)) return undefined
   if (!isAbsoluteWorkspacePath(path)) {
diff --git a/snapshots/web/fresh-round-trip/system-prompt.expected.md b/snapshots/web/fresh-round-trip/system-prompt.expected.md
index 55df661994..618ad7a41a 100644
--- a/snapshots/web/fresh-round-trip/system-prompt.expected.md
+++ b/snapshots/web/fresh-round-trip/system-prompt.expected.md
@@ -30,7 +30,7 @@ Use subagent in the background by default. Start independent delegations togethe
 
 Use subagent_fork in the background by default. Start independent delegations together in one assistant message and continue useful work while they run. Set `run_in_background: false` only when your next action depends on that subagent's result. When a background run settles, the runtime sends you a notice containing its outcome and any final assistant message.
 
-Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
+Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison. Use [Description](<path/to/image.png>) when referring to an image or listing files. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
 
 The DeepSeek Harness implementation checkout is at {{sourceRoot}}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.
 
diff --git a/snapshots/web/ptc-round/system-prompt.expected.md b/snapshots/web/ptc-round/system-prompt.expected.md
index fb616a1ef9..7089411c70 100644
--- a/snapshots/web/ptc-round/system-prompt.expected.md
+++ b/snapshots/web/ptc-round/system-prompt.expected.md
@@ -546,7 +546,7 @@ declare const tools: {
 }
 ```
 
-Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison; it appears inline and opens a larger preview on click. Use [Description](<path/to/image.png>) when referring to an image or listing files; image links offer a hover preview and open in the sidebar on click. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
+Prefer showing the primary results within your final response alongside a brief explanation. Use ![Description](<path/to/image.png>) when an image supports an explanation or comparison. Use [Description](<path/to/image.png>) when referring to an image or listing files. Enclose Markdown file destinations in angle brackets, especially paths containing spaces. Do not call present just to list edited source files, or run commands to check whether a diff view will appear. Use present when a separate file card helps the user open the complete deliverable, including images, Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. Usually select the 1-2 most important deliverables; include more when needed, but at most 4 files in a single present call. Avoid repeating results already shown inline unless the separate card adds useful access. Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.
 
 The DeepSeek Harness implementation checkout is at {{sourceRoot}}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.
 

From bd2a49a2ca3ef47d8fa2e165a129140c0851402b Mon Sep 17 00:00:00 2001
From: Kaige-Gao <michellegkg@163.com>
Date: Wed, 23 Sep 2026 17:22:55 +0800
Subject: [PATCH 3/6] fix(chat): use elevated scrollbar colors for image
 previews

---
 packages/client/ui-primitives/src/HoverCard.module.css | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/client/ui-primitives/src/HoverCard.module.css b/packages/client/ui-primitives/src/HoverCard.module.css
index c6a1757d86..dcd2698ad8 100644
--- a/packages/client/ui-primitives/src/HoverCard.module.css
+++ b/packages/client/ui-primitives/src/HoverCard.module.css
@@ -82,6 +82,8 @@
 
 .inline { display: inline; }
 .media {
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
   overflow: auto;
   padding: 8px;
   border: 0;

From e4234651ee810765447f291dedb1dc54e3202c4f Mon Sep 17 00:00:00 2001
From: yudshj <maghsk2017@gmail.com>
Date: Wed, 23 Sep 2026 17:52:13 +0800
Subject: [PATCH 4/6] fix(web): support spreadsheet tab gestures and readable
 name box

---
 apps/web/tests/document-preview.e2e.ts              | 13 +++++++++++++
 .../ui-sidebar-documentpreview/README.i18n.yaml     |  4 ++--
 .../client/ui-sidebar-documentpreview/README.md     |  2 +-
 .../client/ui-sidebar-documentpreview/README.zh.md  |  2 +-
 .../src/client/excel/ExcelBody.module.css           |  9 +++++++++
 5 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/apps/web/tests/document-preview.e2e.ts b/apps/web/tests/document-preview.e2e.ts
index 14c2728288..b55c5acfda 100644
--- a/apps/web/tests/document-preview.e2e.ts
+++ b/apps/web/tests/document-preview.e2e.ts
@@ -238,6 +238,16 @@ it.skipIf(MODE === 'record').each(['en-US', 'zh-CN'])('fills the spreadsheet pan
       expect(await selection.innerText()).toBe('A1')
       await expect.poll(() => excel.locator('.fortune-sheettab-scroll').count()).toBe(width === 360 ? 2 : 0)
     }
+    const gridOffset = await excel.locator('.luckysheet-scrollbar-x').evaluate(node => node.scrollLeft)
+    await tabScroller.hover()
+    await page.mouse.wheel(180, 0)
+    await expect.poll(() => tabScroller.evaluate(node => node.scrollLeft)).toBeGreaterThan(0)
+    await page.mouse.wheel(-1000, 0)
+    await expect.poll(() => tabScroller.evaluate(node => node.scrollLeft)).toBe(0)
+    expect(await activeSheet.innerText()).toBe('会议信息')
+    expect(await selection.innerText()).toBe('A1')
+    expect(await zoom.innerText()).toBe('100%')
+    expect(await excel.locator('.luckysheet-scrollbar-x').evaluate(node => node.scrollLeft)).toBe(gridOffset)
     for (const direction of ['right', 'left'] as const) {
       const arrow = excel.locator(`#fortune-sheettab-${direction}scroll`)
       for (let step = 0; step < 8; step += 1) {
@@ -277,6 +287,9 @@ it.skipIf(MODE === 'record').each(['en-US', 'zh-CN'])('fills the spreadsheet pan
         await openPreviewFile(column, filesTab, preview, name)
         await excel.locator('.fortune-sheet-overlay').waitFor()
         await expectExcelLayout(excel)
+        expect(await selection.evaluate(node => ({
+          text: getComputedStyle(node).color, background: getComputedStyle(node).backgroundColor,
+        }))).toEqual({ text: 'rgb(0, 0, 0)', background: 'rgb(255, 255, 255)' })
         if (name === 'values.csv') {
           await excel.locator('.fortune-sheet-overlay').click({ position: { x: 70, y: 30 } })
           await expect.poll(() => formula.textContent()).toBe(longCellText)
diff --git a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml b/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
index 946ec07ffb..87dd80cf92 100644
--- a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
+++ b/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-sidebar-documentpreview/README.md
-README.md: 0571c4537f5ff98d8ec1713c297397da1941780b
-README.zh.md: 949e66546b8a4f25a388178dea47f90a8d6d324c
+README.md: 8861b11babfa39909ea639bb3caf0dad6f5ccfa3
+README.zh.md: bfd80bdc8f03a181a526c281fe603299ee3a1bc8
diff --git a/packages/client/ui-sidebar-documentpreview/README.md b/packages/client/ui-sidebar-documentpreview/README.md
index 0571c4537f..8861b11bab 100644
--- a/packages/client/ui-sidebar-documentpreview/README.md
+++ b/packages/client/ui-sidebar-documentpreview/README.md
@@ -66,7 +66,7 @@ Initial reads, additional pages, and HTML/PDF/image preparation share the ongoin
 <a id="excel-preview"></a>
 ## Excel preview
 
-Open `.xlsx`, `.xls`, `.csv`, and `.tsv` directly in the browser with worksheet tabs, cell selection, copying, and a read-only formula bar. XLSX retains fonts, solid fills, borders, number formats, rich text, merged cells, row and column sizes, hidden rows/columns/sheets, and frozen headings. XLS retains saved values, formulas, number formats, merges, and available row/column metadata; fonts, borders, and frozen panes are unsupported. Workbooks display saved formula results without recalculating; missing results remain blank, and a compact formula-bar warning marks workbooks whose displayed results may be incomplete or inaccurate. The workbook viewport fills the preview pane and follows its size changes without reloading its sheets or selection. Worksheet tabs start at the left edge; overflowing tabs scroll with left/right navigation beside a separate zoom control. Selection statistics and inactive worksheet menu arrows are hidden. Frozen headings remain fixed while scrolling, without freeze dividers or drag handles. Spreadsheet preview does not call the Office conversion service.
+Open `.xlsx`, `.xls`, `.csv`, and `.tsv` directly in the browser with worksheet tabs, cell selection, copying, and a read-only formula bar. XLSX retains fonts, solid fills, borders, number formats, rich text, merged cells, row and column sizes, hidden rows/columns/sheets, and frozen headings. XLS retains saved values, formulas, number formats, merges, and available row/column metadata; fonts, borders, and frozen panes are unsupported. Workbooks display saved formula results without recalculating; missing results remain blank, and a compact formula-bar warning marks workbooks whose displayed results may be incomplete or inaccurate. The workbook viewport fills the preview pane and follows its size changes without reloading its sheets or selection. Worksheet tabs start at the left edge; overflowing tabs scroll with horizontal trackpad gestures or left/right navigation beside a separate zoom control. Spreadsheet controls retain dark text on their light background in both app themes. Selection statistics and inactive worksheet menu arrows are hidden. Frozen headings remain fixed while scrolling, without freeze dividers or drag handles. Spreadsheet preview does not call the Office conversion service.
 
 XLSX preview omits DrawingML parts from an in-memory copy before parsing and ignores worksheet drawing references. The original file and worksheet XML remain unchanged. A notice above the table lists detected charts, images, shapes, and conditional formatting that are not displayed, and recommends opening the workbook in a system application. Files without these detected features have no notice; formula warnings remain separate.
 
diff --git a/packages/client/ui-sidebar-documentpreview/README.zh.md b/packages/client/ui-sidebar-documentpreview/README.zh.md
index 949e66546b..bfd80bdc8f 100644
--- a/packages/client/ui-sidebar-documentpreview/README.zh.md
+++ b/packages/client/ui-sidebar-documentpreview/README.zh.md
@@ -66,7 +66,7 @@ PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `<img>` 静态
 <a id="excel-preview"></a>
 ## Excel 预览
 
-直接在浏览器中打开 `.xlsx`、`.xls`、`.csv` 和 `.tsv`，支持工作表标签、单元格选择、复制和只读公式栏。XLSX 保留字体、纯色填充、边框、数字格式、富文本、合并单元格、行列尺寸、隐藏行列及工作表，以及冻结标题。XLS 保留已保存的值、公式、数字格式、合并及可用的行列元数据；不支持字体、边框和冻结窗格。工作簿显示已保存的公式结果而不重新计算；缺少的结果保持为空，公式栏旁的紧凑提示会标记显示结果可能不完整或不准确的工作簿。工作簿视图填满预览面板，并随面板尺寸变化自动调整，无需重新加载工作表或选择状态。工作表标签从左侧边缘开始排列；标签溢出时可用左右按钮滚动，缩放控件独立占位。隐藏选区统计栏及无效的工作表菜单箭头。冻结标题在滚动时保持固定，不显示冻结分隔线和拖拽条。表格预览不调用 Office 转换服务。
+直接在浏览器中打开 `.xlsx`、`.xls`、`.csv` 和 `.tsv`，支持工作表标签、单元格选择、复制和只读公式栏。XLSX 保留字体、纯色填充、边框、数字格式、富文本、合并单元格、行列尺寸、隐藏行列及工作表，以及冻结标题。XLS 保留已保存的值、公式、数字格式、合并及可用的行列元数据；不支持字体、边框和冻结窗格。工作簿显示已保存的公式结果而不重新计算；缺少的结果保持为空，公式栏旁的紧凑提示会标记显示结果可能不完整或不准确的工作簿。工作簿视图填满预览面板，并随面板尺寸变化自动调整，无需重新加载工作表或选择状态。工作表标签从左侧边缘开始排列；标签溢出时可用触控板横向手势或左右按钮滚动，缩放控件独立占位。表格控件在应用的明暗两种主题下均保持浅色背景和深色文字。隐藏选区统计栏及无效的工作表菜单箭头。冻结标题在滚动时保持固定，不显示冻结分隔线和拖拽条。表格预览不调用 Office 转换服务。
 
 XLSX 预览在解析前从内存副本中移除 DrawingML 部件，并忽略工作表的绘图引用。原文件和工作表 XML 保持不变。表格上方的提示列出实际检测到但未展示的图表、图片、形状和条件格式，并建议使用系统应用打开工作簿。未检测到这些内容的文件不显示此提示；公式提示保持独立。
 
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/excel/ExcelBody.module.css b/packages/client/ui-sidebar-documentpreview/src/client/excel/ExcelBody.module.css
index cb4408cbd8..13c28ffbaa 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/excel/ExcelBody.module.css
+++ b/packages/client/ui-sidebar-documentpreview/src/client/excel/ExcelBody.module.css
@@ -14,6 +14,8 @@
   min-height: 0;
   min-width: 0;
   color-scheme: light;
+  /* FortuneSheet's white controls need light-scheme text even in a dark app. */
+  color: CanvasText;
 }
 
 /* Hide editing handles and redundant controls within the read-only preview. */
@@ -43,6 +45,13 @@
   max-width: 100%;
 }
 
+.workbook :global(.fortune-sheettab-container .fortune-sheettab-container-c) {
+  overflow-x: auto;
+  overflow-y: hidden;
+  overscroll-behavior-x: contain;
+  scrollbar-width: none;
+}
+
 .workbook :global(.fortune-sheettab-scroll),
 .workbook :global(.fortune-sheet-area-right) {
   flex: none;

From 19d6df2b2f6addbb6356206c895aef52c784499c Mon Sep 17 00:00:00 2001
From: yudshj <maghsk2017@gmail.com>
Date: Wed, 23 Sep 2026 18:13:19 +0800
Subject: [PATCH 5/6] fix(web): pan read-only spreadsheets on both trackpad
 axes

---
 apps/web/tests/document-preview.e2e.ts        | 33 +++++++++++++++++++
 .../README.i18n.yaml                          |  4 +--
 .../ui-sidebar-documentpreview/README.md      |  2 +-
 .../ui-sidebar-documentpreview/README.zh.md   |  2 +-
 patches/@fortune-sheet__core@1.0.4.patch      | 32 ++++++++++++++++--
 pnpm-lock.yaml                                |  8 ++---
 6 files changed, 71 insertions(+), 10 deletions(-)

diff --git a/apps/web/tests/document-preview.e2e.ts b/apps/web/tests/document-preview.e2e.ts
index b55c5acfda..151120c05a 100644
--- a/apps/web/tests/document-preview.e2e.ts
+++ b/apps/web/tests/document-preview.e2e.ts
@@ -319,6 +319,38 @@ it.skipIf(MODE === 'record').each(['en-US', 'zh-CN'])('fills the spreadsheet pan
   }
 })
 
+/** Pan with native pixel wheel input in every direction and along the sheet edges. */
+async function expectExcelPanning(page: Page, excel: Locator): Promise<void> {
+  // Chromium's CDP wheel distances scale with the emulated device pixel ratio.
+  const scale = await page.evaluate(() => window.devicePixelRatio)
+  const wheel = async (x: number, y: number) => { await page.mouse.wheel(x * scale, y * scale) }
+  const offset = async () => await excel.evaluate(node => ({
+    x: node.querySelector('.luckysheet-scrollbar-x')!.scrollLeft,
+    y: node.querySelector('.luckysheet-scrollbar-y')!.scrollTop,
+  }))
+  const selection = await excel.locator('.fortune-name-box').innerText()
+  await excel.evaluate((node) => {
+    node.querySelector('.luckysheet-scrollbar-x')!.scrollLeft = 240
+    node.querySelector('.luckysheet-scrollbar-y')!.scrollTop = 240
+  })
+  await expect.poll(offset).toEqual({ x: 240, y: 240 })
+  await excel.locator('.fortune-sheet-overlay').hover({ position: { x: 260, y: 160 } })
+  for (const [dx, dy] of [[37, 19], [-13, 27], [-19, -11], [23, -17], [11, 0], [0, 13], [-9, 0], [0, -7]] as const) {
+    const before = await offset()
+    await wheel(dx, dy)
+    await expect.poll(offset).toEqual({ x: before.x + dx, y: before.y + dy })
+  }
+  expect(await excel.locator('.fortune-name-box').innerText()).toBe(selection)
+  await wheel(-10000, -10000)
+  await expect.poll(offset).toEqual({ x: 0, y: 0 })
+  await wheel(-20, 20)
+  await expect.poll(offset).toEqual({ x: 0, y: 20 })
+  await wheel(20, -20)
+  await expect.poll(offset).toEqual({ x: 20, y: 0 })
+  await wheel(-20, 0)
+  await expect.poll(offset).toEqual({ x: 0, y: 0 })
+}
+
 /** Sample the pixel band before the divider center, excluding the adjacent cell grid line. */
 async function freezeDividerInk(excel: Locator, axis: 'x' | 'y'): Promise<number> {
   return await excel.evaluate((node, direction) => {
@@ -387,6 +419,7 @@ it.skipIf(MODE === 'record').each([1, 2])('keeps frozen headings without divider
             await expect.poll(() => freezeDividerInk(excel, axis)).toBe(0)
           }
         }
+        await expectExcelPanning(page, excel)
         await successShot(page, `excel-freeze-${sheet}-${ratio}-${deviceScaleFactor}`)
       }
       await excel.locator('.luckysheet-scrollbar-x').evaluate((node) => { node.scrollLeft = 240 })
diff --git a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml b/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
index 87dd80cf92..5f16c0fdaa 100644
--- a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
+++ b/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-sidebar-documentpreview/README.md
-README.md: 8861b11babfa39909ea639bb3caf0dad6f5ccfa3
-README.zh.md: bfd80bdc8f03a181a526c281fe603299ee3a1bc8
+README.md: a0c08803fd13b32cb968f3415dec522a95937da3
+README.zh.md: 7ba9b4397fd34a43a0d399ca0cf4c16df10dc808
diff --git a/packages/client/ui-sidebar-documentpreview/README.md b/packages/client/ui-sidebar-documentpreview/README.md
index 8861b11bab..a0c08803fd 100644
--- a/packages/client/ui-sidebar-documentpreview/README.md
+++ b/packages/client/ui-sidebar-documentpreview/README.md
@@ -66,7 +66,7 @@ Initial reads, additional pages, and HTML/PDF/image preparation share the ongoin
 <a id="excel-preview"></a>
 ## Excel preview
 
-Open `.xlsx`, `.xls`, `.csv`, and `.tsv` directly in the browser with worksheet tabs, cell selection, copying, and a read-only formula bar. XLSX retains fonts, solid fills, borders, number formats, rich text, merged cells, row and column sizes, hidden rows/columns/sheets, and frozen headings. XLS retains saved values, formulas, number formats, merges, and available row/column metadata; fonts, borders, and frozen panes are unsupported. Workbooks display saved formula results without recalculating; missing results remain blank, and a compact formula-bar warning marks workbooks whose displayed results may be incomplete or inaccurate. The workbook viewport fills the preview pane and follows its size changes without reloading its sheets or selection. Worksheet tabs start at the left edge; overflowing tabs scroll with horizontal trackpad gestures or left/right navigation beside a separate zoom control. Spreadsheet controls retain dark text on their light background in both app themes. Selection statistics and inactive worksheet menu arrows are hidden. Frozen headings remain fixed while scrolling, without freeze dividers or drag handles. Spreadsheet preview does not call the Office conversion service.
+Open `.xlsx`, `.xls`, `.csv`, and `.tsv` directly in the browser with worksheet tabs, cell selection, copying, and a read-only formula bar. XLSX retains fonts, solid fills, borders, number formats, rich text, merged cells, row and column sizes, hidden rows/columns/sheets, and frozen headings. XLS retains saved values, formulas, number formats, merges, and available row/column metadata; fonts, borders, and frozen panes are unsupported. Workbooks display saved formula results without recalculating; missing results remain blank, and a compact formula-bar warning marks workbooks whose displayed results may be incomplete or inaccurate. The workbook viewport fills the preview pane and follows its size changes without reloading its sheets or selection. Worksheet tabs start at the left edge; overflowing tabs scroll with horizontal trackpad gestures or left/right navigation beside a separate zoom control. Spreadsheet controls retain dark text on their light background in both app themes. Pixel-based trackpad gestures pan the grid on both axes together, including diagonally, at the gesture’s speed; frozen headings stay fixed. Selection statistics and inactive worksheet menu arrows are hidden. Frozen headings remain fixed while scrolling, without freeze dividers or drag handles. Spreadsheet preview does not call the Office conversion service.
 
 XLSX preview omits DrawingML parts from an in-memory copy before parsing and ignores worksheet drawing references. The original file and worksheet XML remain unchanged. A notice above the table lists detected charts, images, shapes, and conditional formatting that are not displayed, and recommends opening the workbook in a system application. Files without these detected features have no notice; formula warnings remain separate.
 
diff --git a/packages/client/ui-sidebar-documentpreview/README.zh.md b/packages/client/ui-sidebar-documentpreview/README.zh.md
index bfd80bdc8f..7ba9b4397f 100644
--- a/packages/client/ui-sidebar-documentpreview/README.zh.md
+++ b/packages/client/ui-sidebar-documentpreview/README.zh.md
@@ -66,7 +66,7 @@ PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `<img>` 静态
 <a id="excel-preview"></a>
 ## Excel 预览
 
-直接在浏览器中打开 `.xlsx`、`.xls`、`.csv` 和 `.tsv`，支持工作表标签、单元格选择、复制和只读公式栏。XLSX 保留字体、纯色填充、边框、数字格式、富文本、合并单元格、行列尺寸、隐藏行列及工作表，以及冻结标题。XLS 保留已保存的值、公式、数字格式、合并及可用的行列元数据；不支持字体、边框和冻结窗格。工作簿显示已保存的公式结果而不重新计算；缺少的结果保持为空，公式栏旁的紧凑提示会标记显示结果可能不完整或不准确的工作簿。工作簿视图填满预览面板，并随面板尺寸变化自动调整，无需重新加载工作表或选择状态。工作表标签从左侧边缘开始排列；标签溢出时可用触控板横向手势或左右按钮滚动，缩放控件独立占位。表格控件在应用的明暗两种主题下均保持浅色背景和深色文字。隐藏选区统计栏及无效的工作表菜单箭头。冻结标题在滚动时保持固定，不显示冻结分隔线和拖拽条。表格预览不调用 Office 转换服务。
+直接在浏览器中打开 `.xlsx`、`.xls`、`.csv` 和 `.tsv`，支持工作表标签、单元格选择、复制和只读公式栏。XLSX 保留字体、纯色填充、边框、数字格式、富文本、合并单元格、行列尺寸、隐藏行列及工作表，以及冻结标题。XLS 保留已保存的值、公式、数字格式、合并及可用的行列元数据；不支持字体、边框和冻结窗格。工作簿显示已保存的公式结果而不重新计算；缺少的结果保持为空，公式栏旁的紧凑提示会标记显示结果可能不完整或不准确的工作簿。工作簿视图填满预览面板，并随面板尺寸变化自动调整，无需重新加载工作表或选择状态。工作表标签从左侧边缘开始排列；标签溢出时可用触控板横向手势或左右按钮滚动，缩放控件独立占位。表格控件在应用的明暗两种主题下均保持浅色背景和深色文字。触控板的像素位移可同时平移表格的横纵两个方向，包括斜向平移，移动距离跟随手势；冻结标题保持固定。隐藏选区统计栏及无效的工作表菜单箭头。冻结标题在滚动时保持固定，不显示冻结分隔线和拖拽条。表格预览不调用 Office 转换服务。
 
 XLSX 预览在解析前从内存副本中移除 DrawingML 部件，并忽略工作表的绘图引用。原文件和工作表 XML 保持不变。表格上方的提示列出实际检测到但未展示的图表、图片、形状和条件格式，并建议使用系统应用打开工作簿。未检测到这些内容的文件不显示此提示；公式提示保持独立。
 
diff --git a/patches/@fortune-sheet__core@1.0.4.patch b/patches/@fortune-sheet__core@1.0.4.patch
index b0cbd57e3f..bb06fdbd98 100644
--- a/patches/@fortune-sheet__core@1.0.4.patch
+++ b/patches/@fortune-sheet__core@1.0.4.patch
@@ -1,5 +1,5 @@
 diff --git a/dist/index.esm.js b/dist/index.esm.js
-index 5c9820b1a261305d500e69eeaf350821872beaf4..c0e1bf786c0333fa56edc007c3fd700d834fa40f 100644
+index 5c9820b1a261305d500e69eeaf350821872beaf4..819c6d2e3ffa422b1d1bf163bf56df13bd3af17e 100644
 --- a/dist/index.esm.js
 +++ b/dist/index.esm.js
 @@ -62866,7 +62866,7 @@ function rangeValueToHtml(ctx, sheetId, ranges) {
@@ -19,8 +19,22 @@ index 5c9820b1a261305d500e69eeaf350821872beaf4..c0e1bf786c0333fa56edc007c3fd700d
        var horizontalTop = _ref2.horizontalTop,
          verticalLeft = _ref2.verticalLeft;
        var renderCtx = this.canvasElement.getContext("2d");
+@@ -77244,6 +77245,13 @@ function handleGlobalWheel(ctx, e, cache, scrollbarX, scrollbarY) {
+   var _cache$searchDialog;
+   if (((_cache$searchDialog = cache.searchDialog) === null || _cache$searchDialog === void 0 ? void 0 : _cache$searchDialog.mouseEnter) && ctx.showSearch && ctx.showReplace) return;
+   if (ctx.filterContextMenu != null) return;
++  // Read-only trackpad panning follows pixel deltas on both axes without a gesture lock.
++  if (ctx.allowEdit === false && e.deltaMode === 0) {
++    scrollbarX.scrollLeft += e.deltaX;
++    scrollbarY.scrollTop += e.deltaY;
++    e.preventDefault();
++    return;
++  }
+   var scrollLeft = scrollbarX.scrollLeft;
+   var scrollTop = scrollbarY.scrollTop;
+   var visibledatacolumn_c = ctx.visibledatacolumn;
 diff --git a/dist/index.js b/dist/index.js
-index 04113a18dee9feee28e9434ee3023626c800e7d3..8e68fb2436e7662e3c26ba0308e70b7be1567767 100644
+index 04113a18dee9feee28e9434ee3023626c800e7d3..29e35f51fbf1c3bb16cca54ce2bda81bae4fef64 100644
 --- a/dist/index.js
 +++ b/dist/index.js
 @@ -62876,7 +62876,7 @@ function rangeValueToHtml(ctx, sheetId, ranges) {
@@ -40,3 +54,17 @@ index 04113a18dee9feee28e9434ee3023626c800e7d3..8e68fb2436e7662e3c26ba0308e70b7b
        var horizontalTop = _ref2.horizontalTop,
          verticalLeft = _ref2.verticalLeft;
        var renderCtx = this.canvasElement.getContext("2d");
+@@ -77254,6 +77255,13 @@ function handleGlobalWheel(ctx, e, cache, scrollbarX, scrollbarY) {
+   var _cache$searchDialog;
+   if (((_cache$searchDialog = cache.searchDialog) === null || _cache$searchDialog === void 0 ? void 0 : _cache$searchDialog.mouseEnter) && ctx.showSearch && ctx.showReplace) return;
+   if (ctx.filterContextMenu != null) return;
++  // Read-only trackpad panning follows pixel deltas on both axes without a gesture lock.
++  if (ctx.allowEdit === false && e.deltaMode === 0) {
++    scrollbarX.scrollLeft += e.deltaX;
++    scrollbarY.scrollTop += e.deltaY;
++    e.preventDefault();
++    return;
++  }
+   var scrollLeft = scrollbarX.scrollLeft;
+   var scrollTop = scrollbarY.scrollTop;
+   var visibledatacolumn_c = ctx.visibledatacolumn;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bdd23c40d2..e93f8c24b1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -12,7 +12,7 @@ overrides:
 patchedDependencies:
   '@earendil-works/pi-ai@0.85.1': b9bcce474fb2ac44633dff0fa722816a5bff5451b4575d5874035ea14ba70a4f
   '@electron/osx-sign@1.3.3': 280e7b2816caf01423097d24e79107a66afeb563a348630ce9928ae8499a5861
-  '@fortune-sheet/core@1.0.4': 7d369e6feca3c674aeb089624e38e0a79ad61e695d6bdae89711876cbd178f24
+  '@fortune-sheet/core@1.0.4': 886223a70a0cf76d4fa174608852763fe76bbdc9374db127665024c8c150dd68
   '@fortune-sheet/react@1.0.4': 2932e52e79afcd4ced08cfa123b5eded786c85043da32f622f3e80af6fc96c37
   '@yao-pkg/pkg@6.21.0': 75891fc22b277c145cafeab83e41baf4a70f5b8fe6dc0801c6a0b922d7ee88c7
   exceljs@4.4.0: c1bf8ac8f319dab382f08e3a669b715e691d46c703ac5a4163eb383fbedd1d48
@@ -5042,7 +5042,7 @@ importers:
         version: link:../../util/workspace-path
       '@fortune-sheet/core':
         specifier: 1.0.4
-        version: 1.0.4(patch_hash=7d369e6feca3c674aeb089624e38e0a79ad61e695d6bdae89711876cbd178f24)
+        version: 1.0.4(patch_hash=886223a70a0cf76d4fa174608852763fe76bbdc9374db127665024c8c150dd68)
       '@fortune-sheet/react':
         specifier: 1.0.4
         version: 1.0.4(patch_hash=2932e52e79afcd4ced08cfa123b5eded786c85043da32f622f3e80af6fc96c37)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
@@ -22485,7 +22485,7 @@ snapshots:
       bessel: 1.0.2
       jstat: 1.9.6
 
-  '@fortune-sheet/core@1.0.4(patch_hash=7d369e6feca3c674aeb089624e38e0a79ad61e695d6bdae89711876cbd178f24)':
+  '@fortune-sheet/core@1.0.4(patch_hash=886223a70a0cf76d4fa174608852763fe76bbdc9374db127665024c8c150dd68)':
     dependencies:
       '@fortune-sheet/formula-parser': 0.2.13
       dayjs: 1.11.21
@@ -22501,7 +22501,7 @@ snapshots:
 
   '@fortune-sheet/react@1.0.4(patch_hash=2932e52e79afcd4ced08cfa123b5eded786c85043da32f622f3e80af6fc96c37)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@fortune-sheet/core': 1.0.4(patch_hash=7d369e6feca3c674aeb089624e38e0a79ad61e695d6bdae89711876cbd178f24)
+      '@fortune-sheet/core': 1.0.4(patch_hash=886223a70a0cf76d4fa174608852763fe76bbdc9374db127665024c8c150dd68)
       '@types/regenerator-runtime': 0.13.8
       immer: 9.0.21
       lodash: 4.18.1

From 2c676339904bef553472152b87d33254b5151c8f Mon Sep 17 00:00:00 2001
From: turtle1999 <turtle1999@deepseek.com>
Date: Wed, 23 Sep 2026 15:36:48 +0800
Subject: [PATCH 6/6] feat(plugins): enforce DSH peer compatibility with exact
 exemptions

---
 apps/cli/README.i18n.yaml                     |   4 +-
 apps/cli/README.md                            |   2 +
 apps/cli/README.zh.md                         |   2 +
 apps/cli/src/bin.ts                           |  16 +-
 apps/cli/src/plugin.ts                        |  67 ++-
 .../plugin-compatibility.expected.e2e.ts      |  69 +++
 apps/cli/tests/plugin.spec.ts                 |  91 ++++
 apps/web/tests/plugin-install-registry.e2e.ts |   8 +-
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |   2 +-
 docs/config-catalog.zh.md                     |   2 +-
 docs/event-producer-consumer.i18n.yaml        |   4 +-
 docs/event-producer-consumer.md               |   2 +-
 docs/event-producer-consumer.zh.md            |   2 +-
 docs/subsystems/boot.i18n.yaml                |   4 +-
 docs/subsystems/boot.md                       |  15 +
 docs/subsystems/boot.zh.md                    |  15 +
 docs/tool-catalog.i18n.yaml                   |   4 +-
 docs/tool-catalog.md                          |  16 +-
 docs/tool-catalog.zh.md                       |  16 +-
 packages/boot/app-boot/README.i18n.yaml       |   4 +-
 packages/boot/app-boot/README.md              |   9 +-
 packages/boot/app-boot/README.zh.md           |   9 +-
 packages/boot/app-boot/package.json           |   5 +-
 .../app-boot/src/compatibility-preflight.ts   | 185 +++++++
 packages/boot/app-boot/src/index.ts           |  38 +-
 .../boot/app-boot/src/plugin-compatibility.ts | 102 ++++
 .../app-boot/src/profile-compatibility.ts     | 141 ++++++
 .../tests/compatibility-preflight.spec.ts     | 351 +++++++++++++
 .../tests/plugin-compatibility.spec.ts        | 177 +++++++
 .../tests/profile-compatibility.spec.ts       | 132 +++++
 packages/boot/app-boot/tsconfig.json          |   3 +
 packages/boot/plugin-manager/README.i18n.yaml |   4 +-
 packages/boot/plugin-manager/README.md        |  11 +
 packages/boot/plugin-manager/README.zh.md     |  11 +
 packages/boot/plugin-manager/src/index.ts     |  46 +-
 .../boot/plugin-manager/src/operations.ts     | 215 +++++++-
 packages/boot/plugin-manager/src/tools.ts     |  16 +-
 .../boot/plugin-manager/tests/manager.spec.ts |  59 ++-
 .../tests/operations-process.spec.ts          |   6 +-
 .../plugin-manager/tests/operations.spec.ts   | 475 ++++++++++++++++--
 .../boot/plugin-manager/tests/tools.spec.ts   |  15 +-
 .../extensions/tool-cordis/src/api-catalog.ts |  12 +
 .../preset/agent-preset-registry/package.json |   2 +-
 .../preset/agent-preset-registry/src/mount.ts |   6 +-
 .../agent-preset-registry/tests/mount.spec.ts |  59 ++-
 pnpm-lock.yaml                                |  15 +-
 .../plugin-manager-mcp/session.v4.jsonl       |  29 ++
 .../tool-schemas.expected.json                |  32 +-
 .../session/plugin-manager/session.v4.jsonl   |  27 +
 .../plugin-manager/tool-schemas.expected.json |  16 +-
 51 files changed, 2406 insertions(+), 151 deletions(-)
 create mode 100644 apps/cli/tests/plugin-compatibility.expected.e2e.ts
 create mode 100644 apps/cli/tests/plugin.spec.ts
 create mode 100644 packages/boot/app-boot/src/compatibility-preflight.ts
 create mode 100644 packages/boot/app-boot/src/plugin-compatibility.ts
 create mode 100644 packages/boot/app-boot/src/profile-compatibility.ts
 create mode 100644 packages/boot/app-boot/tests/compatibility-preflight.spec.ts
 create mode 100644 packages/boot/app-boot/tests/plugin-compatibility.spec.ts
 create mode 100644 packages/boot/app-boot/tests/profile-compatibility.spec.ts
 create mode 100644 snapshots/session/plugin-manager-mcp/session.v4.jsonl
 create mode 100644 snapshots/session/plugin-manager/session.v4.jsonl

diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 7e395f72d5..430fd91f46 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/README.md
-README.md: 4eb113a6155433cb69f949d9e461ccfbd0142e7c
-README.zh.md: 6a0e8a38a70d2ad551b4e91619545b3def09f2ec
+README.md: 765440438175083d2dbd765592731df5ec148bcf
+README.zh.md: 08db105b160199cb9a64276f273b8b00f0d21c09
diff --git a/apps/cli/README.md b/apps/cli/README.md
index 4eb113a615..7654404381 100644
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -36,6 +36,8 @@ dsh --help                          # the launcher's own help
 
 A profile directory holds a `package.json` (out-of-tree plugin dependencies plus the profile manifest `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml` (the user's own patch layer). `dsh-hmr`, when enabled in YAML, watches the profile manifest and both profile and home patch files, then recomposes all layers through one serialized reload. Without HMR, changes apply on restart. Edits arriving during watcher registration use the same nonfatal reload reporting as later edits. [Plugin Manager](../../packages/boot/plugin-manager/README.md) shares package operations and the profile write lock with `dsh plugin`; package updates retain disabled bundle selections. CLI package commands inherit authentication variables and terminal descriptors, including interactive build approval; service calls retain their scrubbed environment and captured diagnostics.
 
+Installation and profile startup enforce declared DSH peer ranges against the same runtime version shown by `dsh --version`. Incompatible plugins require an explicitly acknowledged exact-version exemption. The [plugin manager's compatibility reference](../../packages/boot/plugin-manager/README.md#version-compatibility-and-exemptions) documents `version-exemptions`, `allow-version`, `revoke-version`, persistence, and risks.
+
 The tree composes over an empty root:
 - each bundle's patch in `dsh.profile.bundles` order
 - then the profile's `cordis.patch.yml`, then the home-level `$DSH_HOME/cordis.patch.yml`
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 6a0e8a38a7..08db105b16 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -36,6 +36,8 @@ dsh --help                          # the launcher's own help
 
 profile 目录包含一个 `package.json`，其中记录树外插件依赖，以及 profile manifest（元数据清单）`dsh.profile`、其中按顺序排列的 `bundles` 列表；还包含一个 `cordis.patch.yml`，其中保存用户自己的 patch 层。在 YAML 中启用的 `dsh-hmr` 监视 profile manifest、profile 与 home 级 patch 文件，再通过统一串行重载重新组合所有层。未启用 HMR 时，更改在重启后生效。监听器注册期间发生的编辑与后续编辑使用相同的非致命重载错误报告。[插件管理器](../../packages/boot/plugin-manager/README.zh.md) 与 `dsh plugin` 共享包操作和 profile 写锁；更新依赖会保留已停用的组合包选择。CLI 包操作继承认证环境和终端描述符，支持交互式构建批准；service 调用保留清理后的环境并捕获诊断。
 
+安装和 profile 启动会按声明的 DSH peer 范围，检查与 `dsh --version` 显示值相同的运行时版本。不兼容插件需要用户明确确认精确版本豁免。[插件管理器的兼容性参考](../../packages/boot/plugin-manager/README.zh.md#version-compatibility-and-exemptions)说明 `version-exemptions`、`allow-version`、`revoke-version`、持久化规则与风险。
+
 配置树以空根为起点，依次叠加以下配置层：
 - `dsh.profile.bundles` 中各组合包的 patch
 - profile 自身的 `cordis.patch.yml`，然后是 home 级的 `$DSH_HOME/cordis.patch.yml`
diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
index e52c7c8202..20f5867e23 100644
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -6,29 +6,17 @@
 
 /* v8 ignore file -- built-bin acceptance exercises this self-executing dispatch. */
 
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { loadLayeredEnv, StartupError } from '@deepseek-ai/dsh-app-boot'
+import { getDshRuntimeVersion, loadLayeredEnv, StartupError } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
 import { parseDshArgs } from './args.ts'
 import { reportStartupFailure } from './startup-diagnostics.ts'
 
-// Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib) sit
-// one directory under apps/cli, so the checked-in manifest resolves with the
-// same relative hop from either artifact.
-function readVersion(): string {
-  const manifest = JSON.parse(
-    readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'),
-  ) as { version?: unknown }
-  return typeof manifest.version === 'string' ? manifest.version : '0.0.0'
-}
-
 /**
  * Run the public dsh command-line interface.
  * @returns a promise that settles when the selected command mode finishes.
  */
 export async function runCli(): Promise<void> {
-  const version = readVersion()
+  const version = getDshRuntimeVersion()
   const invocation = parseDshArgs(process.argv.slice(2), version)
 
   switch (invocation.mode) {
diff --git a/apps/cli/src/plugin.ts b/apps/cli/src/plugin.ts
index 12a0dbc443..a246af7573 100644
--- a/apps/cli/src/plugin.ts
+++ b/apps/cli/src/plugin.ts
@@ -1,19 +1,76 @@
-/** dsh plugin forwards pnpm through the shared profile package operations. */
-import { runPluginCommand } from '@deepseek-ai/dsh-plugin-manager/operations'
+/** Profile package management and explicit, exact-version compatibility approvals. */
+import { runPluginCommand, setProfileVersionExemption } from '@deepseek-ai/dsh-plugin-manager/operations'
 import { INSTALL_ANCHOR } from './profile-boot.ts'
-import { resolveProfileDir } from '@deepseek-ai/dsh-app-boot'
+import { DEFAULT_PROFILE_BUNDLES, initProfile, PROFILE_TEMPLATES, readProfileCompatibility, resolveProfileDir } from '@deepseek-ai/dsh-app-boot'
+import { withFileLock } from '@deepseek-ai/dsh-atomic-write'
+import { existsSync } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 
+/** Parse only DSH-owned commands; all other arguments remain pnpm's responsibility. */
+async function versionCommand(profile: string, args: readonly string[]): Promise<number | undefined> {
+  const [command, ...rest] = args
+  if (command !== 'allow-version' && command !== 'revoke-version' && command !== 'version-exemptions') return undefined
+  try {
+    let packageVersion: string | undefined
+    let runtimeVersion: string | undefined
+    let acceptRisk = false
+    const argumentsIterator = rest.values()
+    for (const argument of argumentsIterator) {
+      if (argument === '--accept-risk' && command === 'allow-version' && !acceptRisk) acceptRisk = true
+      else if (argument === '--dsh-version' && runtimeVersion === undefined) runtimeVersion = argumentsIterator.next().value
+      else if (argument.startsWith('--dsh-version=') && runtimeVersion === undefined) runtimeVersion = argument.slice('--dsh-version='.length)
+      else if (!argument.startsWith('-') && packageVersion === undefined) packageVersion = argument
+      else throw new Error(`unexpected argument ${JSON.stringify(argument)}`)
+    }
+    if (command === 'version-exemptions' && rest.length > 0) throw new Error('usage: dsh plugin version-exemptions')
+    let request: { packageVersion: string; runtimeVersion: string } | undefined
+    if (command !== 'version-exemptions') {
+      if (packageVersion === undefined || runtimeVersion === undefined) {
+        throw new Error(`usage: dsh plugin ${command} <package@version> --dsh-version <exact>${command === 'allow-version' ? ' --accept-risk' : ''}`)
+      }
+      request = { packageVersion, runtimeVersion }
+    }
+    if (command === 'allow-version') {
+      process.stderr.write('dsh: warning: allowing incompatible plugin versions can break the application or corrupt data. Approval applies only to the exact package and DSH versions.\n')
+    }
+    const dir = resolveProfileDir(profile)
+    await mkdir(dir, { recursive: true })
+    await withFileLock(join(dir, 'package.json'), async () => {
+      if (!existsSync(join(dir, 'package.json'))) initProfile(dir, PROFILE_TEMPLATES[profile]?.bundles ?? DEFAULT_PROFILE_BUNDLES)
+      if (request === undefined) {
+        const { exemptions, warnings } = readProfileCompatibility(dir)
+        for (const warning of warnings) process.stderr.write(`dsh: warning: ${warning}\n`)
+        process.stdout.write(JSON.stringify(exemptions, undefined, 2) + '\n')
+      } else {
+        await setProfileVersionExemption(dir, request.packageVersion, request.runtimeVersion, command === 'allow-version', acceptRisk)
+        process.stdout.write(`dsh: ${command === 'allow-version' ? 'allowed' : 'revoked'} ${request.packageVersion} for DSH ${request.runtimeVersion}\n`)
+      }
+    }, { waitMs: 120000 })
+    return 0
+  } catch (error) {
+    process.stderr.write(`dsh: ${String(error)}\n`)
+    return 1
+  }
+}
+
 /** Run package management for a profile.
  * @param profile Profile name.
- * @param args Pnpm arguments relative to the invoking directory.
- * @returns Pnpm exit code.
+ * @param args DSH exemption command or pnpm arguments relative to the invoking directory.
+ * @returns Zero on success; nonzero on invalid approval or package-manager failure.
  */
 export async function runPlugin(profile: string, args: readonly string[]): Promise<number> {
+  const versionResult = await versionCommand(profile, args)
+  if (versionResult !== undefined) return versionResult
+  const dir = resolveProfileDir(profile)
+  if (existsSync(join(dir, 'package.json'))) {
+    for (const warning of readProfileCompatibility(dir).warnings) process.stderr.write(`dsh: warning: ${warning}\n`)
+  }
   const result = await runPluginCommand({ profile, installAnchor: INSTALL_ANCHOR, cwd: process.cwd() }, args, {
     execution: 'cli',
     outputBytes: 16384,
     lockWaitMs: 120000,
+    lookupTimeoutMs: 120000,
     onOutput: (text, stream) => { process[stream].write(text) },
   })
   if (result.exitCode === 127) process.stderr.write('dsh: pnpm was not found; install pnpm and make it available on PATH.\n')
diff --git a/apps/cli/tests/plugin-compatibility.expected.e2e.ts b/apps/cli/tests/plugin-compatibility.expected.e2e.ts
new file mode 100644
index 0000000000..a002bb2514
--- /dev/null
+++ b/apps/cli/tests/plugin-compatibility.expected.e2e.ts
@@ -0,0 +1,69 @@
+/** Published CLI acceptance for actual pnpm installation, restart checks, and explicit exemptions. */
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execa } from 'execa'
+import { expect, it, onTestFinished } from 'vitest'
+
+const bin = fileURLToPath(new URL('../lib/bin.js', import.meta.url))
+const version = (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }).version
+
+it('refuses incompatible installation and startup until an exact risk exemption is granted', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'dsh-compatibility-cli-'))
+  onTestFinished(() => { rmSync(home, { recursive: true, force: true }) })
+  const profile = join(home, 'profiles', 'compatibility')
+  const source = join(home, 'fixture-plugin')
+  mkdirSync(profile, { recursive: true })
+  mkdirSync(source)
+  const profileFile = join(profile, 'package.json')
+  const initial = { name: 'compatibility-profile', private: true, dependencies: {}, dsh: { profile: { bundles: [] } } }
+  writeFileSync(profileFile, JSON.stringify(initial))
+  writeFileSync(join(profile, 'pnpm-workspace.yaml'), 'packages:\n  - .\nnodeLinker: hoisted\nautoInstallPeers: false\n')
+  writeFileSync(join(source, 'package.json'), JSON.stringify({
+    name: 'compatibility-fixture', version: '1.0.0', type: 'module',
+    peerDependencies: { '@deepseek-ai/dsh': '999.0.0' }, dsh: { bundle: { patch: './cordis.patch.yml' } },
+  }))
+  writeFileSync(join(source, 'cordis.patch.yml'), '- insert:\n    - id: compatibility-fixture\n      name: ./index.mjs\n')
+  writeFileSync(join(source, 'index.mjs'), 'process.stdout.write("PLUGIN_IMPORTED\\n"); export function apply() { process.stdout.write("PLUGIN_STARTED\\n") }\n')
+  const run = async (args: string[]) => {
+    const result = await execa(process.execPath, [bin, ...args], {
+      cwd: home, env: { ...process.env, DSH_HOME: home }, extendEnv: false, reject: false, timeout: 60_000,
+    })
+    expect(result.timedOut).toBe(false)
+    expect(result.signal).toBeUndefined()
+    return result
+  }
+  const plugin = (args: string[]) => run(['plugin', '--profile', 'compatibility', ...args])
+  const refused = await plugin(['add', source, '--offline', '--ignore-scripts'])
+  expect(refused.exitCode).toBe(1)
+  expect(refused.stderr).toContain('crashes or data loss')
+  expect(JSON.parse(readFileSync(profileFile, 'utf8'))).toEqual(initial)
+  expect(existsSync(join(profile, 'compatibility.json'))).toBe(false)
+  // The named package is checked before installation, so a refused one never lands on disk.
+  expect(refused.stderr).toContain('nothing was installed')
+  expect(existsSync(join(profile, 'node_modules', 'compatibility-fixture'))).toBe(false)
+
+  // A package installed outside DSH still goes through the independent startup check.
+  cpSync(source, join(profile, 'node_modules', 'compatibility-fixture'), { recursive: true })
+  writeFileSync(profileFile, JSON.stringify({ ...initial,
+    dependencies: { 'compatibility-fixture': `file:${source}` }, dsh: { profile: { bundles: ['compatibility-fixture'] } },
+  }))
+  const deniedStartup = await run(['--profile', 'compatibility'])
+  expect(deniedStartup.stdout).not.toContain('PLUGIN_IMPORTED')
+  expect(deniedStartup.stderr).toContain('incompatible')
+  const missingConsent = await plugin(['allow-version', 'compatibility-fixture@1.0.0', '--dsh-version', version])
+  expect(missingConsent.exitCode).toBe(1)
+  const granted = await plugin(['allow-version', 'compatibility-fixture@1.0.0', '--dsh-version', version, '--accept-risk'])
+  expect(granted.exitCode).toBe(0)
+  expect(granted.stderr).toContain('break the application or corrupt data')
+  // The exemption is profile metadata of its own; the dependency manifest and bundle list stay untouched.
+  expect(JSON.parse(readFileSync(join(profile, 'compatibility.json'), 'utf8'))).toEqual({ 'compatibility-fixture@1.0.0': [version] })
+  expect(JSON.parse(readFileSync(profileFile, 'utf8'))).not.toHaveProperty('dsh.profile.versionExemptions')
+  expect((await plugin(['add', source, '--offline', '--ignore-scripts'])).exitCode).toBe(0)
+  const admittedStartup = await run(['--profile', 'compatibility'])
+  expect(admittedStartup.exitCode).toBe(0)
+  expect(admittedStartup.stdout).toContain('PLUGIN_STARTED')
+  expect((await plugin(['revoke-version', 'compatibility-fixture@1.0.0', '--dsh-version', version])).exitCode).toBe(0)
+  expect((await run(['--profile', 'compatibility'])).stdout).not.toContain('PLUGIN_IMPORTED')
+})
diff --git a/apps/cli/tests/plugin.spec.ts b/apps/cli/tests/plugin.spec.ts
new file mode 100644
index 0000000000..f3163d5d3d
--- /dev/null
+++ b/apps/cli/tests/plugin.spec.ts
@@ -0,0 +1,91 @@
+/** Explicit CLI exemptions use the profile lock and never become pnpm arguments. */
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it, onTestFinished, vi } from 'vitest'
+import { getDshRuntimeVersion, readProfileVersionExemptions } from '@deepseek-ai/dsh-app-boot'
+import { runPluginCommand } from '@deepseek-ai/dsh-plugin-manager/operations'
+import { runPlugin } from '../src/plugin.ts'
+
+vi.mock('../src/profile-boot.ts', () => ({ INSTALL_ANCHOR: '/installation/package.json' }))
+vi.mock('@deepseek-ai/dsh-plugin-manager/operations', async importOriginal => ({
+  ...await importOriginal<typeof import('@deepseek-ai/dsh-plugin-manager/operations')>(),
+  runPluginCommand: vi.fn(),
+}))
+
+function fixture() {
+  const home = mkdtempSync(join(tmpdir(), 'cli-version-exemptions-'))
+  vi.stubEnv('DSH_HOME', home)
+  const stdout = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
+  const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+  onTestFinished(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllEnvs()
+    vi.mocked(runPluginCommand).mockReset()
+    rmSync(home, { recursive: true, force: true })
+  })
+  return { dir: join(home, 'profiles', 'test'), stdout, stderr }
+}
+
+it('requires explicit acknowledgement, grants only the exact pair, lists and revokes it without pnpm', async () => {
+  const { dir, stdout, stderr } = fixture()
+  const runtime = getDshRuntimeVersion()
+  expect(await runPlugin('test', ['allow-version', '@example/plugin@1.2.3', '--dsh-version', runtime, '--accept-risk'])).toBe(0)
+  expect(stderr.mock.calls.map(call => call[0]).join('')).toMatchInlineSnapshot(`
+    "dsh: warning: allowing incompatible plugin versions can break the application or corrupt data. Approval applies only to the exact package and DSH versions.
+    "
+  `)
+  expect(stderr.mock.invocationCallOrder[0]).toBeLessThan(stdout.mock.invocationCallOrder[0]!)
+  expect(readProfileVersionExemptions(dir)).toEqual({ '@example/plugin@1.2.3': [runtime] })
+  expect(JSON.parse(readFileSync(join(dir, 'compatibility.json'), 'utf8'))).toEqual({ '@example/plugin@1.2.3': [runtime] })
+  expect(await runPlugin('test', ['version-exemptions'])).toBe(0)
+  expect(stdout).toHaveBeenLastCalledWith(JSON.stringify({ '@example/plugin@1.2.3': [runtime] }, undefined, 2) + '\n')
+  expect(await runPlugin('test', ['revoke-version', '@example/plugin@1.2.3', `--dsh-version=${runtime}`])).toBe(0)
+  expect(readProfileVersionExemptions(dir)).toEqual({})
+  expect(runPluginCommand).not.toHaveBeenCalled()
+})
+
+it.each([
+  ['allow-version', 'plugin@1.2.3', '--dsh-version', 'CURRENT'],
+  ['allow-version', 'plugin@1.2.3', '--accept-risk'],
+  ['allow-version', 'plugin@^1.2.3', '--dsh-version', 'CURRENT', '--accept-risk'],
+  ['allow-version', 'plugin@1.2.3', '--dsh-version', '999.0.0', '--accept-risk'],
+  ['allow-version', 'plugin@1.2.3', '--dsh-version', 'CURRENT', '--accept-risk=false'],
+  ['allow-version', 'plugin@1.2.3', '--dsh-version', 'CURRENT', '--accept-risk', '--accept-risk'],
+  ['revoke-version', 'plugin@1.2.3'],
+  ['version-exemptions', 'extra'],
+])('rejects malformed or unacknowledged exemption command %j', async (...arguments_) => {
+  const { dir, stderr } = fixture()
+  const args = arguments_.map(value => value === 'CURRENT' ? getDshRuntimeVersion() : value)
+  expect(await runPlugin('test', args)).toBe(1)
+  expect(stderr).toHaveBeenCalled()
+  expect(existsSync(join(dir, 'compatibility.json'))).toBe(false)
+  expect(runPluginCommand).not.toHaveBeenCalled()
+})
+
+it('uses shipped profile defaults when listing a missing profile', async () => {
+  fixture()
+  expect(await runPlugin('web', ['version-exemptions'])).toBe(0)
+  expect(runPluginCommand).not.toHaveBeenCalled()
+})
+
+it.each([0, 1])('forwards ordinary pnpm output and exit status %s', async (exitCode) => {
+  const { stdout, stderr } = fixture()
+  vi.mocked(runPluginCommand).mockImplementation(async (_context, _args, options) => {
+    options.onOutput?.('pnpm output', 'stdout')
+    return { exitCode, output: '', truncated: false, logPath: '/profile/log' }
+  })
+  expect(await runPlugin('test', ['list'])).toBe(exitCode)
+  expect(stdout).toHaveBeenCalledWith('pnpm output')
+  if (exitCode === 0) expect(stderr).not.toHaveBeenCalled()
+  else expect(stderr).toHaveBeenCalledWith('dsh: pnpm failed; diagnostics: /profile/log\n')
+})
+
+it('forwards all other commands unchanged and retains package diagnostics', async () => {
+  const { stderr } = fixture()
+  vi.mocked(runPluginCommand).mockResolvedValue({ exitCode: 127, output: '', truncated: false, logPath: '/profile/log' })
+  const args = ['add', 'github:example/plugin']
+  expect(await runPlugin('test', args)).toBe(127)
+  expect(runPluginCommand).toHaveBeenCalledWith(expect.objectContaining({ profile: 'test' }), args, expect.objectContaining({ execution: 'cli' }))
+  expect(stderr.mock.calls.map(call => call[0]).join('')).toContain('pnpm was not found')
+})
diff --git a/apps/web/tests/plugin-install-registry.e2e.ts b/apps/web/tests/plugin-install-registry.e2e.ts
index 16a9d7d0a9..ca1ef80e6d 100644
--- a/apps/web/tests/plugin-install-registry.e2e.ts
+++ b/apps/web/tests/plugin-install-registry.e2e.ts
@@ -107,8 +107,12 @@ it.each(['https://registry.npmjs.org/', MIRROR])('selects the fastest responding
       await dialog.getByRole('button', { name: '立即启用', exact: true }).waitFor({ timeout: 20_000 })
       await dialog.getByText('版本 2.0.0', { exact: true }).waitFor()
       const lookups = (await readFile(join(profile, '.registry-lookups'), 'utf8')).trim().split('\n')
-      expect(lookups).toHaveLength(1)
-      expect(JSON.parse(lookups[0]!)).toContain('--registry=' + MIRROR)
+        .map(line => JSON.parse(line) as string[])
+      // The inspection asked the mirror first, and each install attempt checked the named package's
+      // DSH peers at the registry that attempt would use: the mirror, then pnpm's own.
+      expect(lookups.map(call => call.filter(argument => argument.startsWith('--registry=')))).toEqual([
+        ['--registry=' + MIRROR], ['--registry=' + MIRROR], [],
+      ])
       await dialog.getByRole('button', { name: '查看安装详情', exact: true }).click()
       await dialog.getByText('Installed from the registry pnpm names', { exact: true }).waitFor()
       await dialog.getByText('第 1 次 · 中国大陆镜像源', { exact: true }).waitFor()
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index b2f5692dec..4c969b9423 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: eb66160994cb6d7792fb8225aa07839f988e53dc
-config-catalog.zh.md: 2fbadf572626b0c1938f88ed2189a25f0a6c7268
+config-catalog.md: eb63c85c48d91bc9a79ebd909f2e0acd3a406d26
+config-catalog.zh.md: cdbfb07a2ecda96c8df282b8c49ec59ec34d8401
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index eb66160994..eb63c85c48 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2194,7 +2194,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/boot/plugin-manager/src/index.ts:38`](../packages/boot/plugin-manager/src/index.ts)
+Source: [`packages/boot/plugin-manager/src/index.ts:40`](../packages/boot/plugin-manager/src/index.ts)
 
 <a id="deepseek-aidsh-plugin-package-inventory-deepseek"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 2fbadf5726..cdbfb07a2e 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -2196,7 +2196,7 @@ export interface Config {
 }
 ```
 
-来源： [`packages/boot/plugin-manager/src/index.ts:38`](../packages/boot/plugin-manager/src/index.ts)
+来源： [`packages/boot/plugin-manager/src/index.ts:40`](../packages/boot/plugin-manager/src/index.ts)
 
 <a id="deepseek-aidsh-plugin-package-inventory-deepseek"></a>
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index e3971707b4..a86f94ab5f 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
-event-producer-consumer.md: 54a5e36bb6d2c39606c2e0263cad89293e6bb613
-event-producer-consumer.zh.md: 248aacbafc115d2c7aea8480406d2a1842ed293d
+event-producer-consumer.md: fb0816fe5f66b3981eac1f0fcb2b4d418a12ecfe
+event-producer-consumer.zh.md: b2f7a1b2075bd8328a45ed7eedef2c5a3eecd1ce
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 54a5e36bb6..fb0816fe5f 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -26,7 +26,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:616`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:595`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:602`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `app-boot/config-reload` | `emit` | [`packages/boot/app-boot/src/index.ts:45`](../packages/boot/app-boot/src/index.ts) | [`app-boot`](../packages/boot/app-boot) (`emit`) | [`settings`](../packages/settings/settings) |
+| `app-boot/config-reload` | `emit` | [`packages/boot/app-boot/src/index.ts:52`](../packages/boot/app-boot/src/index.ts) | [`app-boot`](../packages/boot/app-boot) (`emit`) | [`settings`](../packages/settings/settings) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 248aacbafc..b2f7a1b207 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -28,7 +28,7 @@
 | `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:616`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:595`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:602`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `app-boot/config-reload` | `emit` | [`packages/boot/app-boot/src/index.ts:43`](../packages/boot/app-boot/src/index.ts) | [`app-boot`](../packages/boot/app-boot) (`emit`) | [`settings`](../packages/settings/settings) |
+| `app-boot/config-reload` | `emit` | [`packages/boot/app-boot/src/index.ts:52`](../packages/boot/app-boot/src/index.ts) | [`app-boot`](../packages/boot/app-boot) (`emit`) | [`settings`](../packages/settings/settings) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
diff --git a/docs/subsystems/boot.i18n.yaml b/docs/subsystems/boot.i18n.yaml
index 598649b415..54a45c2704 100644
--- a/docs/subsystems/boot.i18n.yaml
+++ b/docs/subsystems/boot.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/boot.md
-boot.md: 5faf482b0532058e480adf13bf7fee8bb882498d
-boot.zh.md: 1f50732fd36a996c6bc15b406f7e9a4ac83bcb26
+boot.md: 07391705977bc7b3cba9377e3142feea7d62f69f
+boot.zh.md: 64ff36d41295f529b81f2856f2fbc77f09efa808
diff --git a/docs/subsystems/boot.md b/docs/subsystems/boot.md
index 5faf482b05..0739170597 100644
--- a/docs/subsystems/boot.md
+++ b/docs/subsystems/boot.md
@@ -89,6 +89,21 @@ Source: [`packages/boot/hmr/src/index.ts`](../../packages/boot/hmr/src/index.ts)
 Manage profile files and apply their declared reload lifecycle.
 
 ```ts cordis-catalog
+/** Read exact plugin-version exemptions saved in this profile.
+ * @returns Accepted package-name@version keys with the runtime versions they may run on, and any
+ * record or file problem the reader rejected, which the caller reports instead of failing.
+ */
+@Remote listVersionExemptions(): { exemptions: Record<string, string[]>; warnings: string[] }
+
+/** Grant or revoke one exact plugin/runtime exemption and reevaluate live plugins.
+ * @param packageVersion Exact manifest package name followed by @ and its version; never an installation spec or alias.
+ * @param runtimeVersion Exact current DSH version for grants; revocation may name a previous runtime.
+ * @param enabled Whether to grant rather than revoke the exemption.
+ * @param acceptRisk Required true for grants after the user accepts possible crashes and data loss.
+ * @returns Saved and runtime outcomes. Startup-only profiles require restart.
+ */
+@Remote setVersionExemption(packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk?: boolean): Promise<ChangeResult>
+
 /** Read current plugins, including why a row cannot be changed through the profile patch.
  * @returns Current runtime entries with persistent patch targets.
  */
diff --git a/docs/subsystems/boot.zh.md b/docs/subsystems/boot.zh.md
index 1f50732fd3..64ff36d412 100644
--- a/docs/subsystems/boot.zh.md
+++ b/docs/subsystems/boot.zh.md
@@ -89,6 +89,21 @@ Source: [`packages/boot/hmr/src/index.ts`](../../packages/boot/hmr/src/index.ts)
 Manage profile files and apply their declared reload lifecycle.
 
 ```ts cordis-catalog
+/** Read exact plugin-version exemptions saved in this profile.
+ * @returns Accepted package-name@version keys with the runtime versions they may run on, and any
+ * record or file problem the reader rejected, which the caller reports instead of failing.
+ */
+@Remote listVersionExemptions(): { exemptions: Record<string, string[]>; warnings: string[] }
+
+/** Grant or revoke one exact plugin/runtime exemption and reevaluate live plugins.
+ * @param packageVersion Exact manifest package name followed by @ and its version; never an installation spec or alias.
+ * @param runtimeVersion Exact current DSH version for grants; revocation may name a previous runtime.
+ * @param enabled Whether to grant rather than revoke the exemption.
+ * @param acceptRisk Required true for grants after the user accepts possible crashes and data loss.
+ * @returns Saved and runtime outcomes. Startup-only profiles require restart.
+ */
+@Remote setVersionExemption(packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk?: boolean): Promise<ChangeResult>
+
 /** Read current plugins, including why a row cannot be changed through the profile patch.
  * @returns Current runtime entries with persistent patch targets.
  */
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index d020d136a3..2b04d1eacd 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/tool-catalog.md
-tool-catalog.md: 8e1f4f7c8c8b36de366aa8a1b795106f4ae32283
-tool-catalog.zh.md: 0995196921738ad4b5a5deda0cf48c83b1d4e664
+tool-catalog.md: 3e4407192ee75b61537d9fd09f3d68381d1e803e
+tool-catalog.zh.md: cf78ee4d4f0d8a8bdddbf4ad3987a18bd1f300d1
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 8e1f4f7c8c..3e4407192e 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -52,7 +52,7 @@ This table connects model-visible tool names to the plugin package and service s
 
 ### `plugin_manager`
 
-List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart.
+List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart. Incompatible DSH peer dependencies block installation and activation. Version exemptions risk crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.
 
 ```json
 {
@@ -67,7 +67,9 @@ List plugins or bundles in the current profile, enable or disable them, install
         "set_plugin",
         "set_bundle",
         "install_bundle",
-        "remove_bundle"
+        "remove_bundle",
+        "list_version_exemptions",
+        "set_version_exemption"
       ]
     },
     "target": {
@@ -76,7 +78,15 @@ List plugins or bundles in the current profile, enable or disable them, install
     },
     "enabled": {
       "type": "boolean",
-      "description": "Required for set operations; defaults to true for installation."
+      "description": "Required for set operations; defaults to true for installation. For set_version_exemption, true grants and false revokes."
+    },
+    "runtimeVersion": {
+      "type": "string",
+      "description": "For set_version_exemption: exact DSH version from list_version_exemptions. Target must be the manifest package-name@version, not an alias or version range."
+    },
+    "acceptRisk": {
+      "type": "boolean",
+      "description": "For granting an exemption: true only after warning the user about possible crashes and data loss and receiving explicit permission for this exact plugin/runtime pair. General installation permission is not enough."
     },
     "approvedBuilds": {
       "type": "array",
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index 0995196921..cf78ee4d4f 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -56,7 +56,7 @@
 
 ### `plugin_manager`
 
-列出当前 profile 中的插件或组合包，启用或禁用它们，安装组合包或移除已安装的组合包。每项操作都要求 danger-full-access 权限或本次调用的批准。批准不改变会话权限模式。变更影响该 profile 的所有会话。先列出条目以获取准确标识。包安装可能运行已获批准的构建脚本。支持热更新的 profile 立即应用变更；仅启动时加载的 profile 需要重启。
+列出当前 profile 中的插件或组合包，启用或禁用它们，安装组合包或移除已安装的组合包。每项操作都要求 danger-full-access 权限或本次调用的批准。批准不改变会话权限模式。变更影响该 profile 的所有会话。先列出条目以获取准确标识。包安装可能运行已获批准的构建脚本。支持热更新的 profile 立即应用变更；仅启动时加载的 profile 需要重启。不兼容的 DSH peer 依赖会阻止安装和激活。版本豁免可能导致崩溃和数据丢失：授权前必须警告用户，并获得用户对精确插件版本与运行时版本组合的明确许可。
 
 ```json
 {
@@ -71,7 +71,9 @@
         "set_plugin",
         "set_bundle",
         "install_bundle",
-        "remove_bundle"
+        "remove_bundle",
+        "list_version_exemptions",
+        "set_version_exemption"
       ]
     },
     "target": {
@@ -80,7 +82,15 @@
     },
     "enabled": {
       "type": "boolean",
-      "description": "Required for set operations; defaults to true for installation."
+      "description": "Required for set operations; defaults to true for installation. For set_version_exemption, true grants and false revokes."
+    },
+    "runtimeVersion": {
+      "type": "string",
+      "description": "For set_version_exemption: exact DSH version from list_version_exemptions. Target must be the manifest package-name@version, not an alias or version range."
+    },
+    "acceptRisk": {
+      "type": "boolean",
+      "description": "For granting an exemption: true only after warning the user about possible crashes and data loss and receiving explicit permission for this exact plugin/runtime pair. General installation permission is not enough."
     },
     "approvedBuilds": {
       "type": "array",
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index ff61bc8512..8a77721112 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
-README.md: 70a8e235ac5846061ea47e79e7dc575881110a50
-README.zh.md: 9849b033e01827a4c50a22b72ea20deebb0fdd85
+README.md: 729a4b1552cd28e89698580860f8c9e31043a76c
+README.zh.md: c401978fdf05651479c8c6b74b01d48287fa2b63
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index 70a8e235ac..729a4b1552 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -49,6 +49,12 @@ Import profile and bundle declaration types from [`@deepseek-ai/dsh-package-mani
 
 A profile is how one dsh installation ships different app surfaces: `web`, `headless`, `acp`, `sdk`, and `sdk-minimal` start distinct compositions from the same launcher. A profile lives at `$DSH_HOME/profiles/<name>` and combines installable bundles with its own `cordis.patch.yml`. A bundle's `dsh.bundle.patch` names one patch file or an ordered list of files; `bundlePatchFiles` validates the declaration and `bundlePatchPaths` resolves it to absolute paths; the layer concatenates their patch lists in that order. The YAML composition enables or disables HMR. The shipped `web` template uses live reload, while the other shipped templates apply patches only at startup. `sdk-minimal` names only its standalone bundle; the other templates retain base-plus-mode stacks. `dsh --profile <name> --from-default-profile <template>` creates a custom profile at a new non-shipped name from one shipped template, while `dsh plugin` initializes a base-backed profile and manages its installed bundles. Bundle resolution, manifest, and patch-loading failures print a diagnostic and skip that bundle without changing its selection. Remaining bundles keep their order; profile and user-patch errors still fail startup. Skipping a bundle does not guarantee that the remaining composition can provide the required services. Application-owned npm projects, such as Electron's reserved Desktop profile, use `loadProfileDirectory` to load an already initialized directory without exposing it through CLI profile lookup.
 
+Before a profile imports a plugin, DSH checks its `peerDependencies` on `@deepseek-ai/dsh` and `@deepseek-ai/dsh-*` against the single runtime version returned by `getDshRuntimeVersion()`. Every declared range must match; prereleases participate in range matching. Source-workspace `workspace:^`, `workspace:~`, and `workspace:*` refer to that same runtime. Missing DSH peers impose no constraint; invalid ranges are incompatible. These checks use peer declarations, not `engines.dsh`, and are not a sandbox against malicious package code.
+
+Admission happens only at composition boundaries DSH owns, and a denied row is denied in the launcher's own copy of the composition: no profile patch layer, dependency manifest, or bundle list changes. `prepareProfilePatches` composes over the launcher's empty profile root and runs while the root Include is mounted and on every profile recomposition, so a denied plugin never imports its module. `prepareProfileEntries` does the same for a preset's rows. A denied ordinary row becomes a detached `disabled: true` row; a native group stays mounted and its denied children do not load; a native Include that reaches a denied plugin is omitted whole, because its file is never rewritten. A row denied by policy keeps its configured `disabled` value in the profile, and every refusal is reported with the package, versions, and risk. These boundaries do not cover plugins another embedder mounts through its own `ctx.plugin` call. Two edits made directly to files during a session are judged only at the next recomposition or startup: a running plugin's own `package.json` peer declaration, and an entry-list file the Loader reads itself, such as the launcher's root config or a nested `cordis:include` file. `--dump-config` reports the configured composition, so a denied plugin still appears there, and `--dump-config-schema` imports each composed module to read its schema; run it only against a profile whose plugins you already trust.
+
+Exact-version exemptions live in the profile's own `compatibility.json`, not in its `package.json`, so an exemption write never touches the dependency manifest, the bundle list, or Cordis patch files. It maps exact `package-name@version` keys to lists of exact DSH runtime versions; neither a plugin upgrade nor a DSH upgrade inherits permission. A missing file means no exemptions. A malformed one never stops the profile from starting: records the reader accepts still apply, each rejected record is reported on stderr beside the plugin denials, and the file is then treated as read-only, so a grant or revocation refuses and asks the user to repair it by hand instead of overwriting their content. [Plugin Manager](../plugin-manager/README.md#version-compatibility-and-exemptions) owns the grant, revocation, and risk confirmation each change requires.
+
 Your machine-local preferences also live in the Harness home:
 
 - **`.env`** — your ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. Variables that decide how the process starts (`PATH`, `DSH_*`, `XDG_*` and similar) are rejected from files: export them instead. The four proxy names (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`) are accepted from the Harness-home file only, never from the invoking directory's, which arrives with a clone. For a non-product bin that just wants one directory's `.env`, a missing file is fine and an unloadable one prints one labelled warning line.
@@ -122,6 +128,7 @@ This section explains how the outcomes above are realized and points at the code
 
 ### Design notes
 
+- **Runtime version.** `getDshRuntimeVersion()` reads this package's manifest through a filesystem path, including the executable's virtual filesystem; missing or invalid versions fail rather than bypassing compatibility checks.
 - **Profile launch data.** `ctx.profileContext` contains only profile locations, startup bundle names, parsed invocation overlays and the telemetry opt-out value. `readProfilePatches()` composes the supplied startup profile or reads current files at those locations; callers schedule and apply the result.
 - **Process-local module resolution.** The launcher installs the runtime resolution on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer. Explicit CommonJS `paths` always retain native lookup, including paths inside profiles.
 - **Linked directories.** A profile link to an external directory admits its importers to peer-aware ancestor lookup, even without its own `package.json`. At each `D/node_modules` position, current `D/package.json` peer names present in the runtime table use the runtime package; other names use the physical candidate. A nearer physical package precedes a later peer declaration, and a peer position needs no physical `node_modules`. Installation-scope package directories are excluded from linked interception; overlapping roots do not change the importer's lookup order ([rule](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md)).
@@ -192,7 +199,7 @@ These limits describe when this boot library is a poor fit or needs special care
 
 - **Runtime resolution depends on Node internals** — supported Node versions require the native builtin-access addon and executable compatibility coverage. Only built Harness-owned Workers receive the runtime resolution bootstrap; third-party Workers and custom `vm` linkers keep native resolution.
 - **Relinking a profile package needs a restart** — Node caches real paths, so changing the target of a profile link or a dependency link requires a process restart.
-- **Linked scope follows recorded real directories** — a hoisted dependency outside every linked root uses native Node. Current peer reads do not invalidate Node caches, watch files, or validate peer version ranges.
+- **Linked scope follows recorded real directories** — a hoisted dependency outside every linked root uses native Node. A peer read never invalidates Node caches or changes which files are watched.
 - **Source launches use an ESM-only hook** — CommonJS requests still need the JavaScript files selected by package exports; resolution does not supply missing build outputs.
 - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
 - **Environment discovery is launch-scoped** — `loadLayeredEnv` reads only the invocation directory and Harness home once; it does not search parents or follow a workspace selected later. `loadEnv` remains the one-directory helper for non-product bins.
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 9849b033e0..c401978fdf 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -49,6 +49,12 @@ Profile 与组合包的声明类型从 [`@deepseek-ai/dsh-package-manifest`](../
 
 profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`headless`、`acp`、`sdk` 与 `sdk-minimal` 从同一 launcher 启动不同组合。profile 位于 `$DSH_HOME/profiles/<name>`，由可安装组合包和自身 `cordis.patch.yml` 组成。组合包的 `dsh.bundle.patch` 指定一个 patch 文件或一个有序的文件列表；`bundlePatchFiles` 校验该声明，`bundlePatchPaths` 把它解析为绝对路径；该层按此顺序拼接各文件的 patch 列表。YAML 组合决定是否启用 HMR。随产品交付的 `web` 模板实时重载，其他随附模板只在启动时应用 patch。`sdk-minimal` 只列出自身的独立组合包，其他模板保留 base 加模式的组合包栈。`dsh --profile <name> --from-default-profile <template>` 从一个随附模板，在新的非内置名称处创建自定义 profile；`dsh plugin` 则初始化以 base 为基础的 profile，并管理其中安装的组合包。组合包解析、manifest 读取或 patch 加载失败时会输出诊断并跳过该组合包，不改变其选择状态。其余组合包保持原顺序；profile 和用户 patch 错误仍会导致启动失败。跳过组合包不保证剩余组合能够提供所需服务。由应用持有的 npm 项目（例如 Electron 保留的 Desktop profile）通过 `loadProfileDirectory` 加载已经初始化的目录，而不会将它暴露给 CLI profile 查找。
 
+profile 导入插件前，DSH 会检查其 `peerDependencies` 中对 `@deepseek-ai/dsh` 和 `@deepseek-ai/dsh-*` 的依赖，与 `getDshRuntimeVersion()` 返回的唯一运行时版本比较。每个声明的版本范围都必须匹配；预发布版本参与范围匹配。源码工作区的 `workspace:^`、`workspace:~` 和 `workspace:*` 指向同一个运行时。未声明 DSH peer 时不施加版本约束；无效范围视为不兼容。这些检查使用 peer 声明，而不是 `engines.dsh`，也不是防范恶意包代码的沙箱。
+
+检查只发生在 DSH 自己持有的组合入口，改写的是启动器自己的那份组合：profile 的 patch 层、依赖清单与组合包列表都不会改变。`prepareProfilePatches` 在启动器的空 profile 根之上组合，并在挂载根 Include 时以及每次 profile 重新组合时执行，因此被拒绝的插件永远不会导入其模块；`prepareProfileEntries` 对 preset 行做同样的事。被拒绝的普通行会变成游离的 `disabled: true` 行；原生 group 保持挂载，其被拒绝的子行不会加载；若某个原生 Include 会到达被拒绝的插件，则整体省略该 Include，因为它的文件不会被改写。被策略拒绝的行在 profile 中保留其配置的 `disabled` 值，每次拒绝都会报告包名、版本与风险。这些入口不覆盖其他嵌入方通过自己的 `ctx.plugin` 调用挂载的插件。会话中直接改文件的两类编辑只在下一次重新组合或启动时才被判定：正在运行的插件自己的 `package.json` peer 声明，以及 Loader 自己读取的入口清单文件（如启动器的根配置或嵌套的 `cordis:include` 文件）。`--dump-config` 报告的是配置出的组合，因此被拒绝的插件仍会出现在其中；`--dump-config-schema` 会导入每个组合模块以读取其 schema，请只对已经信任其插件的 profile 运行。
+
+精确版本豁免保存在 profile 自己的 `compatibility.json` 中，而不是 `package.json`，因此写豁免不会触及依赖清单、组合包列表或 Cordis patch 文件。它把精确的 `package-name@version` 键映射到精确 DSH 运行时版本列表；插件升级和 DSH 升级都不继承授权。文件缺失表示没有豁免。文件损坏绝不会阻止 profile 启动：读取器接受的记录仍然生效，每条被拒绝的记录会与插件拒绝信息一起输出到 stderr，此后该文件被视为只读，因此授予或撤销会拒绝执行并要求用户手工修复，而不是覆盖用户的内容。[插件管理器](../plugin-manager/README.zh.md#version-compatibility-and-exemptions)负责每次变更所需的授权、撤销与风险确认。
+
 你的机器本地偏好同样位于 harness home 中：
 
 - **`.env`**——你的普通环境层：调用目录的文件优先于 harness home 的文件，两者都低于继承环境。在文件中设置的进程启动变量（如 `PATH`、`DSH_*`、`XDG_*`）会被拒绝：请改为导出这些变量。四个代理名（`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY`）只从 harness home 的文件接受，绝不从调用目录的文件接受——后者随 clone 一起到来。对于只想加载某个目录 `.env` 的非产品 bin，文件缺失不影响启动，文件无法加载时输出一行带标签的警告。
@@ -122,6 +128,7 @@ Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如
 
 ### 设计说明
 
+- **运行时版本。** `getDshRuntimeVersion()` 通过文件系统路径读取本包清单，也支持可执行文件内的虚拟文件系统；版本缺失或无效时会失败，而不会绕过兼容性检查。
 - **Profile 启动数据。** `ctx.profileContext` 只包含 profile 位置、启动时组合包名称、已解析的调用级 overlay 与遥测退出值。`readProfilePatches()` 组合传入的启动 profile，或读取这些位置上的当前文件；调用方负责调度和应用结果。
 - **进程内模块解析。** launcher 在挂载 profile 条目前，将 runtime resolution 安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、子路径、模块缓存和错误码仍由 Node 负责；路由后的 ESM 失败报告原始 importer。显式 CommonJS `paths` 始终保留原生查询，包括指向 profile 内的路径。
 - **链接目录。** profile 链接到树外目录时，其下的 importer 参与逐层 peer 查询，即使目标没有自身的 `package.json`。在每个 `D/node_modules` 位置，当前 `D/package.json` 的 peer 包名若存在于运行时表，就使用运行时包；其他包名查询物理候选。更近的物理包先于后续 peer 声明，peer 位置无需物理 `node_modules`。installation 作用域包目录不参与 linked 拦截，重叠 root 不改变 importer 的查询顺序（[规则](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md)）。
@@ -192,7 +199,7 @@ Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如
 
 - **运行时解析依赖 Node 内部机制**——受支持的 Node 版本需要 native builtin access addon 和可执行兼容验证。只有构建后的 Harness 自有 Worker 接收 runtime resolution bootstrap；第三方 Worker 与自定义 `vm` linker 保持原生解析。
 - **重新链接 profile 包需要重启**——Node 缓存真实路径，因此改变 profile 链接或依赖链接的目标需要重启进程。
-- **链接作用域以记录的真实目录为准**——提升后的依赖若在所有 linked root 之外，就使用原生 Node。实时读取 peer 不会使 Node 缓存失效、监视文件或校验 peer 版本范围。
+- **链接作用域以记录的真实目录为准**——提升后的依赖若在所有 linked root 之外，就使用原生 Node。每次读取 peer 都不会使 Node 缓存失效，也不会改变被监视的文件。
 - **源码启动只安装 ESM 钩子**——CommonJS 请求仍需要 package exports 选中的 JavaScript 文件，解析器不会补出缺失的构建产物。
 - **快照回放替换仅识别特定 basename**——只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
 - **环境发现以启动为界**——`loadLayeredEnv` 只读取一次调用目录与 harness home 中的 `.env`；它不搜索父目录，也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。
diff --git a/packages/boot/app-boot/package.json b/packages/boot/app-boot/package.json
index 051c79d0bd..9a114e8061 100644
--- a/packages/boot/app-boot/package.json
+++ b/packages/boot/app-boot/package.json
@@ -32,12 +32,14 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@deepseek-ai/dsh-atomic-write": "workspace:*",
     "@deepseek-ai/dsh-package-manifest": "workspace:*",
     "@eslint-community/regexpp": "^4.12.2",
     "ajv": "^8.20.0",
     "js-yaml": "^4.2.0",
     "node-addon-require-builtin": "^0.1.6",
-    "resolve.exports": "^2.0.3"
+    "resolve.exports": "^2.0.3",
+    "semver": "^7.8.5"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis-plugin-group": "workspace:~",
@@ -58,6 +60,7 @@
     "@deepseek-ai/dsh-home-paths": "workspace:*",
     "@deepseek-ai/dsh-system-prompt": "workspace:*",
     "@types/js-yaml": "^4.0.9",
+    "@types/semver": "^7.8.0",
     "@deepseek-ai/cordis": "workspace:~"
   }
 }
diff --git a/packages/boot/app-boot/src/compatibility-preflight.ts b/packages/boot/app-boot/src/compatibility-preflight.ts
new file mode 100644
index 0000000000..0827b5f54e
--- /dev/null
+++ b/packages/boot/app-boot/src/compatibility-preflight.ts
@@ -0,0 +1,185 @@
+/** Compatibility checks at the composition entry points DSH owns; no Loader instrumentation. */
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, extname, isAbsolute, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
+import { applyEntryPatches, entryListSchema, type PatchOptions } from '@deepseek-ai/cordis-plugin-include'
+import { load } from 'js-yaml'
+import { resolvePluginResource } from './package-meta.ts'
+import { barePackageName } from './profile-resolution/resolver.ts'
+import type {} from './profile-resolution/service.ts'
+import type {} from './profile-context.ts'
+import { evaluatePluginCompatibility, pluginCompatibilityWarning } from './plugin-compatibility.ts'
+import { readProfileCompatibility } from './profile-compatibility.ts'
+
+function readManifest(filename: string): object {
+  return JSON.parse(readFileSync(filename, 'utf8')) as object
+}
+
+/** Render the patch wording an Include would report, through the profile's logger. */
+function patchWarning(ctx: Context): (message: string, ...args: unknown[]) => void {
+  return (message, ...args) => {
+    let index = 0
+    ctx.logger.warn(message.replace(/%C/g, () => JSON.stringify(args[index++])))
+  }
+}
+
+function manifestOf(ctx: Context, name: string, parentURL: string): object | undefined {
+  if (name.startsWith('cordis:')) return undefined
+  const specifier = name.startsWith('#') ? resolvePluginResource(name, parentURL) : name
+  const packages = ctx.get('pluginPackages')
+  const pkg = packages?.packageOf(specifier, parentURL)
+  if (pkg !== undefined) return readManifest(pkg.manifestPath)
+  const bare = barePackageName(specifier)
+  if (bare !== undefined && packages === undefined) {
+    // An embedder without the package service falls back to Node's own lookup, as `packageDirFromParent` does.
+    for (const path of createRequire(parentURL).resolve.paths(bare) as string[]) {
+      const filename = join(path, bare, 'package.json')
+      if (existsSync(filename)) return readManifest(filename)
+    }
+  }
+  if (!isAbsolute(specifier) && !specifier.startsWith('.') && !specifier.startsWith('file:')) return undefined
+  const url = isAbsolute(specifier) ? pathToFileURL(specifier) : new URL(specifier, parentURL)
+  let dir: string
+  try { dir = dirname(realpathSync(fileURLToPath(url))) }
+  catch (error) {
+    // A row this profile cannot resolve is the Loader's import failure to report, not a compatibility decision.
+    if (['ENOENT', 'ENOTDIR', 'EISDIR'].includes(String((error as NodeJS.ErrnoException).code))) return undefined
+    throw error
+  }
+  while (true) {
+    try { return readManifest(join(dir, 'package.json')) }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      const parent = dirname(dir)
+      if (parent === dir) return undefined
+      dir = parent
+    }
+  }
+}
+
+/** Prepare profile or preset rows before the owning DSH caller passes them to Loader.
+ * Only a compatibility conflict denies a row: an entry whose manifest cannot be resolved keeps
+ * the Loader's own import failure. A denied ordinary row gains `disabled`; a native Include that
+ * reaches a denied plugin is denied as a whole, because its file is never rewritten.
+ * @param ctx Context carrying launcher-owned profile facts; non-profile contexts retain their rows.
+ * @param entries Complete effective entry list, after patch composition.
+ * @param parentURL Resolution base of the tree that will import these rows.
+ * @param binName Diagnostic prefix for a denied row; defaults to `dsh`.
+ * @returns Detached rows with incompatible entries denied; reads the profile compatibility file once.
+ * @throws For malformed compatibility permissions or a profile composition without a resolution base.
+ */
+export function prepareProfileEntries(
+  ctx: Context, entries: readonly EntryOptions[], parentURL: string | undefined, binName = 'dsh',
+): EntryOptions[] {
+  // Admission runs before the composed tree mounts, so no plugin-owned logger exporter exists yet;
+  // composition-stage diagnostics go to stderr like the profile launcher's skipped-bundle report.
+  return preflight(ctx, entries, parentURL, (row, reason) => {
+    process.stderr.write(`${binName}: disabling profile plugin ${row.name}: ${reason}\n`)
+  }).rows
+}
+
+/** Denial reporter invoked once per denied row. */
+type DenialReporter = (row: EntryOptions, reason: string) => void
+
+function preflight(
+  ctx: Context, entries: readonly EntryOptions[], parentURL: string | undefined, report: DenialReporter,
+) {
+  const rows = structuredClone(entries) as EntryOptions[]
+  const profile = ctx.get('profileContext')
+  if (profile === undefined) return { rows, blocked: false }
+  if (parentURL === undefined) throw new Error('Profile compatibility preflight requires a resolution base')
+  // A damaged permission file authorizes nothing, but it must not stop the profile from starting.
+  const { exemptions, warnings } = readProfileCompatibility(profile.dir)
+  for (const warning of warnings) process.stderr.write(`${warning}\n`)
+  const includes = new Set<string>()
+  /** Only a compatibility conflict denies a row; every other failure keeps the Loader's own diagnosis. */
+  const denial = (row: EntryOptions, base: string): string | undefined => {
+    try {
+      const manifest = manifestOf(ctx, row.name, base)
+      if (manifest === undefined) return undefined
+      const issue = evaluatePluginCompatibility(manifest, exemptions)
+      return issue === undefined || issue.exempted ? undefined : pluginCompatibilityWarning(issue)
+    } catch (error) {
+      // Peer metadata that cannot be read or validated is refused rather than silently admitted.
+      /* v8 ignore next -- every reader and parser used here rejects with an Error. */
+      const detail = error instanceof Error ? error.message : String(error)
+      return `its declared peer dependencies cannot be validated: ${detail}`
+    }
+  }
+  const deny = (row: EntryOptions, reason: string): void => {
+    row.disabled = true
+    if (row.group) row.group = false
+    report(row, reason)
+  }
+  const check = (rows: EntryOptions[], base: string): boolean => {
+    let blocked = false
+    for (const row of rows) {
+      if (row.disabled === true && !row.group) continue
+      const conflict = denial(row, base)
+      if (conflict !== undefined) {
+        deny(row, conflict)
+        blocked = true
+        continue
+      }
+      // The `group` marker, not the module name, is what makes a row another tree carrier.
+      if ((row.group === true || row.name === 'cordis:group' || row.name === '@deepseek-ai/cordis-plugin-group')
+        && Array.isArray(row.config) && check(row.config as EntryOptions[], base)) blocked = true
+      if (row.name !== 'cordis:include' && row.name !== '@deepseek-ai/cordis-plugin-include') continue
+      const reached = includedConflicts(row, base)
+      if (reached !== undefined) {
+        deny(row, reached)
+        blocked = true
+      }
+    }
+    return blocked
+  }
+  /** Whether a native Include reaches a denied plugin; an unreadable one has no compatibility opinion. */
+  const includedConflicts = (row: EntryOptions, base: string): string | undefined => {
+    const config = row.config as { path?: unknown; patches?: PatchOptions[]; initial?: EntryOptions[] } | undefined
+    if (typeof config?.path !== 'string' || !['.yml', '.yaml', '.json'].includes(extname(config.path))) {
+      // A dynamic Include is resolved by the Include plugin itself; this walk cannot judge its rows.
+      return undefined
+    }
+    const requested = isAbsolute(config.path) ? config.path : fileURLToPath(new URL(config.path, base))
+    const filename = existsSync(requested) ? realpathSync(requested) : requested
+    if (includes.has(filename)) return undefined
+    includes.add(filename)
+    try {
+      let data: unknown
+      try { data = load(readFileSync(filename, 'utf8'), { schema: entryListSchema }) }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT' || config.initial === undefined) return undefined
+        data = config.initial
+      }
+      if (!Array.isArray(data)) return undefined
+      const children = applyEntryPatches(data as EntryOptions[], config.patches, patchWarning(ctx))
+      return check(children, pathToFileURL(filename).href)
+        ? `its included file ${filename} reaches an incompatible plugin, and that file is never rewritten`
+        : undefined
+    } finally {
+      includes.delete(filename)
+    }
+  }
+  return { rows, blocked: check(rows, parentURL) }
+}
+
+/** Apply compatibility policy to the complete patch composition over a profile's empty root.
+ * The caller passes every patch layer of the profile, because this returns one insertion patch for
+ * that empty root: a non-empty root config would lose the caller's override patches by id.
+ * @param ctx Profile context prepared by the launcher.
+ * @param patches Original ordered profile patches; these remain unchanged.
+ * @param parentURL Root Include's resolution base.
+ * @param binName Diagnostic prefix for a denied row; defaults to `dsh`.
+ * @returns One prepared insertion patch for profiles, or the original patches for non-profile callers.
+ */
+export function prepareProfilePatches(
+  ctx: Context, patches: PatchOptions[], parentURL: string, binName = 'dsh',
+): PatchOptions[] {
+  if (ctx.get('profileContext') === undefined) return patches
+  const entries = applyEntryPatches([], patches, patchWarning(ctx))
+  const rows = prepareProfileEntries(ctx, entries, parentURL, binName)
+  return rows.length === 0 ? [] : [{ insert: rows }]
+}
diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts
index 0881307284..68e6cc667c 100644
--- a/packages/boot/app-boot/src/index.ts
+++ b/packages/boot/app-boot/src/index.ts
@@ -19,6 +19,13 @@ import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-home-paths'
 import { createLaunchEnvironmentSnapshot, type LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment'
 export { readProfilePatches, resolveTelemetryPatch, type ProfileContext, type ProfilePnpmInvocation } from './profile-context.ts'
 export { sanitizeProfile } from './profile-sanitize.ts'
+export { getDshRuntimeVersion, evaluatePluginCompatibility, pluginCompatibilityWarning, type PluginCompatibility } from './plugin-compatibility.ts'
+export {
+  PROFILE_COMPATIBILITY_FILENAME, readProfileCompatibility, readProfileVersionExemptions,
+  setProfileVersionExemption, type ProfileCompatibility,
+} from './profile-compatibility.ts'
+import { prepareProfilePatches } from './compatibility-preflight.ts'
+export { prepareProfileEntries, prepareProfilePatches } from './compatibility-preflight.ts'
 export { readPluginMeta } from './package-meta.ts'
 export { generateConfigSchema, type ConfigSchemaDump, type NativeConfigSchema } from './config-schema/index.ts'
 export { createConfigProjector, LOADER_EXPRESSION_SCHEMA, type ConfigProjection } from './config-schema/projector.ts'
@@ -274,7 +281,10 @@ export async function reconcileProfilePatches(
     fiber: row.fiber, failed: row.fiber.state === FIBER_FAILED || row.fiber.state === FIBER_DISPOSED,
   }])
   const { patches: _previous, ...includeConfig } = entry.options.config as Include.Config
-  await entry.update({ config: { ...includeConfig, patches } })
+  // The recomposition judges the rows the launch judged, resolved from the file this Include read.
+  const parentURL = new URL('.', new URL(includeConfig.path, entry.parent.tree.ctx.baseUrl)).href
+  const prepared = prepareProfilePatches(ctx, patches, parentURL, binName)
+  await entry.update({ config: { ...includeConfig, patches: prepared } })
   const results = await Promise.allSettled(previousFibers.map(({ fiber }) => fiber.await()))
   await ctx.loader.await()
   const failures = await inactiveEntries(ctx)
@@ -384,14 +394,15 @@ export interface ConfigDumpLayer {
 }
 
 /**
- * Compose the effective entry list exactly as `boot()` would mount it: parse
- * the base config file with the include's entry-list dialect, apply every
- * layer's patches as ONE flattened list through the include's own patch
- * algorithm (`applyEntryPatches`) — the same single call `boot()` makes, so
- * even patch-visibility corner cases (a later layer targeting a group child a
- * plain config replacement introduced, which the single-pass id index never
- * sees) compose identically — then render the result as YAML in the same
- * dialect (`!!js` expressions print verbatim, unevaluated).
+ * Compose the configured entry list: parse the base config file with the
+ * include's entry-list dialect, apply every layer's patches as ONE flattened
+ * list through the include's own patch algorithm (`applyEntryPatches`) — the
+ * same call `boot()` makes, so even patch-visibility corner cases (a later
+ * layer targeting a group child a plain config replacement introduced, which
+ * the single-pass id index never sees) compose identically — then render the
+ * result as YAML in the same dialect (`!!js` expressions print verbatim,
+ * unevaluated). Admission is a later stage: this dump reports what the profile
+ * configures, and a plugin the compatibility policy denies still appears here.
  *
  * Every run of rows from the same file and patch layers is preceded by a `# ==` comment
  * naming the file that contributed the rows and any layers that patched them,
@@ -517,6 +528,7 @@ function groupedDump(
  * @param patches - initial app and user patches, applied in order.
  * @param bareModuleBaseUrl - optional installed-host base for bare package
  * names; relative names continue to resolve beside the configuration file.
+ * @param binName - diagnostic prefix for a profile plugin denied by compatibility policy; defaults to `dsh`.
  * @returns the created root Include entry, or `undefined` when a surface
  * disposed the whole tree (taking the Loader service with it) while the
  * entry creation was in flight.
@@ -526,6 +538,7 @@ export async function mountRootInclude(
   absoluteConfigPath: string,
   patches: readonly PatchOptions[] = [],
   bareModuleBaseUrl?: string,
+  binName = 'dsh',
 ): Promise<Entry | undefined> {
   ctx.loader.builtins.include = bareModuleBaseUrl === undefined
     ? Include
@@ -549,9 +562,12 @@ export async function mountRootInclude(
   // Pinned id: the bootstrap include is app glue, not a config row, and its
   // id appears in Loader failure chains — a random id would make startup
   // diagnostics unstable across runs (and snapshot fixtures).
+  // The launcher's own copy is prepared here: compatibility decisions must be made before the root
+  // Include imports anything, and they change no profile patch layer, manifest, or bundle list.
+  const prepared = prepareProfilePatches(ctx, [...patches], pathToFileURL(dirname(absoluteConfigPath)).href + '/', binName)
   const includeConfig: Include.Config = {
     path: pathToFileURL(absoluteConfigPath).href,
-    ...patches.length > 0 ? { patches: [...patches] } : {},
+    ...prepared.length > 0 ? { patches: prepared } : {},
   }
   const rootInclude: EntryOptions = {
     id: 'include',
@@ -983,7 +999,7 @@ export async function boot(
     await ctx.plugin(Loader)
     await prepare?.(ctx)
     stage = 'plugin tree failed to load'
-    await mountRootInclude(ctx, absoluteConfigPath, patches, bareModuleBaseUrl)
+    await mountRootInclude(ctx, absoluteConfigPath, patches, bareModuleBaseUrl, binName)
     // A surface can finish and dispose the whole tree while startup is still
     // in flight, before the last entry settles. The Loader service goes with
     // it, and the activation audit describes a live tree — reading `ctx.loader`
diff --git a/packages/boot/app-boot/src/plugin-compatibility.ts b/packages/boot/app-boot/src/plugin-compatibility.ts
new file mode 100644
index 0000000000..e2e90f10ab
--- /dev/null
+++ b/packages/boot/app-boot/src/plugin-compatibility.ts
@@ -0,0 +1,102 @@
+/** Evaluate plugin dsh peer requirements without importing plugin code. */
+
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import semver from 'semver'
+
+/** Incompatible dsh peers and the exact plugin/runtime exemption decision. */
+export interface PluginCompatibility {
+  name: string
+  version: string
+  runtimeVersion: string
+  /** Only peer requirements not satisfied by the running dsh version. */
+  peers: Record<string, string>
+  exempted: boolean
+}
+
+function objectOf(value: unknown, field: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${field} must be an object`)
+  }
+  return value as Record<string, unknown>
+}
+
+function runtimeVersionOf(value: unknown): string {
+  if (typeof value !== 'string' || semver.valid(value) === null) {
+    throw new Error(`Invalid dsh runtime version: ${JSON.stringify(value)}; expected a semantic version`)
+  }
+  return value
+}
+
+function identityField(manifest: Record<string, unknown>, field: 'name' | 'version'): string {
+  const value = Object.hasOwn(manifest, field) ? manifest[field] : undefined
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`Plugin manifest ${field} must be a non-empty string when dsh peers are incompatible`)
+  }
+  return value
+}
+
+/**
+ * Read this app-boot package's version in both source and bundled installations.
+ * @returns the validated runtime semantic version, preserving its exact spelling.
+ * @throws if package.json cannot be read or its version is missing or invalid.
+ */
+export function getDshRuntimeVersion(): string {
+  // The executable's virtual filesystem intercepts string paths, not URL arguments.
+  const filename = fileURLToPath(new URL('../package.json', import.meta.url))
+  const manifest = objectOf(JSON.parse(fs.readFileSync(filename, 'utf8')), 'app-boot package.json')
+  return runtimeVersionOf(Object.hasOwn(manifest, 'version') ? manifest.version : undefined)
+}
+
+/**
+ * Check every @deepseek-ai/dsh or @deepseek-ai/dsh-* peer against the runtime.
+ * Prereleases participate in ranges. workspace:^, workspace:~, and workspace:*
+ * refer to the current runtime; other invalid ranges are incompatible.
+ * @param manifest - parsed plugin package.json; inherited fields are ignored.
+ * @param exemptions - exact plugin name@version keys mapped to exact runtime versions.
+ * @param runtimeVersion - running dsh version, defaulting to this app-boot package.
+ * @returns incompatible peers and exemption status, or undefined when none are incompatible.
+ * @throws for malformed manifest peer fields, invalid runtime versions, or missing identity on a mismatch.
+ */
+export function evaluatePluginCompatibility(
+  manifest: object,
+  exemptions: Readonly<Record<string, readonly string[]>> = {},
+  runtimeVersion = getDshRuntimeVersion(),
+): PluginCompatibility | undefined {
+  runtimeVersionOf(runtimeVersion)
+  const fields = objectOf(manifest, 'Plugin manifest')
+  if (!Object.hasOwn(fields, 'peerDependencies')) return undefined
+  const dependencies = objectOf(fields.peerDependencies, 'Plugin manifest peerDependencies')
+  const peers: Record<string, string> = {}
+  for (const [name, range] of Object.entries(dependencies)) {
+    if (typeof range !== 'string') {
+      throw new Error(`Plugin manifest peerDependencies[${JSON.stringify(name)}] must be a string`)
+    }
+    if (name !== '@deepseek-ai/dsh' && !name.startsWith('@deepseek-ai/dsh-')) continue
+    const requirement = ['workspace:^', 'workspace:~', 'workspace:*'].includes(range) ? runtimeVersion : range
+    if (requirement.trim() === '' || !semver.satisfies(runtimeVersion, requirement, { includePrerelease: true })) {
+      peers[name] = range
+    }
+  }
+  if (Object.keys(peers).length === 0) return undefined
+  const name = identityField(fields, 'name')
+  const version = identityField(fields, 'version')
+  const key = `${name}@${version}`
+  const exemptedVersions = Object.hasOwn(exemptions, key) ? exemptions[key] : undefined
+  const exempted = exemptedVersions?.includes(runtimeVersion) === true
+  return { name, version, runtimeVersion, peers, exempted }
+}
+
+/**
+ * Describe incompatible peers, their risk, and the exact-version remedy.
+ * @param issue - incompatible plugin/runtime result, including exempted mismatches.
+ * @returns a warning suitable for CLI and plugin-management diagnostics.
+ */
+export function pluginCompatibilityWarning(issue: PluginCompatibility): string {
+  const key = `${issue.name}@${issue.version}`
+  return `Plugin ${key} is incompatible with dsh ${issue.runtimeVersion}: peerDependencies ${JSON.stringify(issue.peers)}. `
+    + 'Running it may cause crashes or data loss. '
+    + 'Update the plugin or install a plugin version compatible with this dsh runtime. '
+    + `To accept this risk explicitly, add the exact-version exemption ${JSON.stringify({ [key]: [issue.runtimeVersion] })}. `
+    + `Exact-version exemption: ${issue.exempted ? 'active' : 'not active'}.`
+}
diff --git a/packages/boot/app-boot/src/profile-compatibility.ts b/packages/boot/app-boot/src/profile-compatibility.ts
new file mode 100644
index 0000000000..e0cf107f62
--- /dev/null
+++ b/packages/boot/app-boot/src/profile-compatibility.ts
@@ -0,0 +1,141 @@
+/** Profile-local compatibility permissions readable before any Cordis plugins load. */
+import { readFileSync } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parse } from 'semver'
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
+import { getDshRuntimeVersion } from './plugin-compatibility.ts'
+
+/** Independent profile metadata; neither package manifests nor Cordis patches carry grants. */
+export const PROFILE_COMPATIBILITY_FILENAME = 'compatibility.json'
+
+/** Published and scoped npm package names, as npm accepts them in a manifest dependency key. */
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/
+
+/** Whether a decoded record accepts only exact DSH versions. */
+function isVersionList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(version => typeof version === 'string' && isExactPluginVersion(version))
+}
+
+/** Test whether an exemption names a canonical exact SemVer, including build metadata.
+ * @param value Version supplied by a manifest or user.
+ * @returns False for ranges, prefixes, whitespace, and malformed versions.
+ */
+export function isExactPluginVersion(value: string): boolean {
+  const parsed = parse(value)
+  return parsed !== null && value === `${parsed.version}${parsed.build.length === 0 ? '' : `+${parsed.build.join('.')}`}`
+}
+
+/** Validate one explicit exemption without granting it.
+ * @param packageVersion Exact npm package-name@version, never an installation spec or range.
+ * @param runtimeVersion Exact DSH version, including prerelease and build metadata.
+ * @throws When either identity is not canonical.
+ */
+export function validatePluginVersionExemption(packageVersion: string, runtimeVersion: string): void {
+  const separator = packageVersion.lastIndexOf('@')
+  if (separator <= 0 || !PACKAGE_NAME.test(packageVersion.slice(0, separator))
+    || !isExactPluginVersion(packageVersion.slice(separator + 1)) || !isExactPluginVersion(runtimeVersion)) {
+    throw new Error('Version exemptions require an exact npm package-name@version and an exact DSH runtime version')
+  }
+}
+
+/** What one profile's compatibility file currently authorizes, and what is wrong with it. */
+export interface ProfileCompatibility {
+  /** Accepted exact package-name@version keys mapped to their allowed DSH versions. */
+  readonly exemptions: Record<string, string[]>
+  /** Human-readable problems; empty when every record was accepted. */
+  readonly warnings: string[]
+  /**
+   * Whether the file holds nothing this reader rejected, so a grant or revocation may rewrite it.
+   * A false value means writing would discard content the user must repair by hand.
+   */
+  readonly rewritable: boolean
+}
+
+/** Read the profile's independent compatibility file without loading plugins.
+ * A missing file authorizes nothing. An unreadable or unparsable file authorizes nothing and is
+ * reported instead of failing, so a bad file can never make the profile unusable; rejected records
+ * are skipped while the remaining valid ones still apply.
+ * @param profileDir Absolute profile directory.
+ * @returns Accepted exemptions plus every problem found; no manifest fallback is used.
+ */
+export function readProfileCompatibility(profileDir: string): ProfileCompatibility {
+  const filename = join(profileDir, PROFILE_COMPATIBILITY_FILENAME)
+  const unreadable = (reason: string): ProfileCompatibility =>
+    ({ exemptions: {}, warnings: [`${filename} ${reason}; treating the profile as having no exemptions`], rewritable: false })
+  let text: string
+  try { text = readFileSync(filename, 'utf8') }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { exemptions: {}, warnings: [], rewritable: true }
+    return unreadable(`cannot be read (${String(error)})`)
+  }
+  let value: unknown
+  try { value = JSON.parse(text) }
+  catch (error) { return unreadable(`is not valid JSON (${String(error)})`) }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return unreadable('must map exact package@version keys to DSH version lists')
+  }
+  const exemptions: Record<string, string[]> = {}
+  const warnings: string[] = []
+  for (const [key, versions] of Object.entries(value as Record<string, unknown>)) {
+    const separator = key.lastIndexOf('@')
+    if (separator <= 0 || !PACKAGE_NAME.test(key.slice(0, separator)) || !isExactPluginVersion(key.slice(separator + 1))) {
+      warnings.push(`${filename}: ${JSON.stringify(key)} is not an exact package-name@version key; the record is ignored`)
+      continue
+    }
+    if (!isVersionList(versions)) {
+      warnings.push(`${filename}: ${key} must contain a list of exact DSH versions; the record is ignored`)
+      continue
+    }
+    exemptions[key] = versions
+  }
+  return { exemptions, warnings, rewritable: warnings.length === 0 }
+}
+
+/** Read only the accepted exemptions of a profile.
+ * @param profileDir Absolute profile directory.
+ * @returns Exact package-name@version keys mapped to their allowed DSH versions.
+ */
+export function readProfileVersionExemptions(profileDir: string): Record<string, string[]> {
+  return readProfileCompatibility(profileDir).exemptions
+}
+
+/** Persist one informed grant or revocation under the compatibility file's own lock.
+ * @param profileDir Profile directory; no package manifest is created or modified.
+ * @param packageVersion Exact manifest package-name@version.
+ * @param runtimeVersion Exact DSH version; grants must name the current runtime, revocations may name historical ones.
+ * @param enabled Whether to grant rather than revoke.
+ * @param acceptRisk Required true for grants after explicit acknowledgement of possible crashes or data loss.
+ * @returns After the atomic write. Existing plugin instances are not reloaded by this operation.
+ * @throws For invalid identities, missing consent, a stale runtime, or a file the reader rejected,
+ * which the user must repair by hand because rewriting it would discard their content.
+ */
+export async function setProfileVersionExemption(
+  profileDir: string, packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk: boolean,
+): Promise<void> {
+  validatePluginVersionExemption(packageVersion, runtimeVersion)
+  if (enabled && !acceptRisk) {
+    throw new Error('Incompatible plugins may cause crashes or data loss. To grant this exact-version exemption, explicitly acknowledge the risk with --accept-risk (acceptRisk: true).')
+  }
+  const current = getDshRuntimeVersion()
+  if (enabled && runtimeVersion !== current) {
+    throw new Error(`Cannot approve DSH ${runtimeVersion}: this application runs DSH ${current}. Use --dsh-version ${current}.`)
+  }
+  await mkdir(profileDir, { recursive: true })
+  const filename = join(profileDir, PROFILE_COMPATIBILITY_FILENAME)
+  await withFileLock(filename, async () => {
+    const current = readProfileCompatibility(profileDir)
+    if (!current.rewritable) {
+      throw new Error(`${PROFILE_COMPATIBILITY_FILENAME} must be repaired before exemptions change:\n${current.warnings.join('\n')}`)
+    }
+    const exemptions = current.exemptions
+    const versions = exemptions[packageVersion] ?? []
+    if (enabled) exemptions[packageVersion] = [...new Set([...versions, runtimeVersion])]
+    else {
+      const retained = versions.filter(version => version !== runtimeVersion)
+      if (retained.length) exemptions[packageVersion] = retained
+      else Reflect.deleteProperty(exemptions, packageVersion)
+    }
+    await writeFileAtomic(filename, JSON.stringify(exemptions, undefined, 2) + '\n', { mode: 0o600 })
+  })
+}
diff --git a/packages/boot/app-boot/tests/compatibility-preflight.spec.ts b/packages/boot/app-boot/tests/compatibility-preflight.spec.ts
new file mode 100644
index 0000000000..b1836fee84
--- /dev/null
+++ b/packages/boot/app-boot/tests/compatibility-preflight.spec.ts
@@ -0,0 +1,351 @@
+/** Admission of profile composition rows before the Loader imports any plugin code. */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Context } from '@deepseek-ai/cordis'
+import { entryListSchema, type PatchOptions } from '@deepseek-ai/cordis-plugin-include'
+import { load } from 'js-yaml'
+import { describe, expect, it, onTestFinished, vi } from 'vitest'
+import {
+  PROFILE_COMPATIBILITY_FILENAME, PluginPackages, boot, getDshRuntimeVersion,
+  prepareProfileEntries, prepareProfilePatches, type ProfileContext,
+} from '../src/index.ts'
+
+const runtime = getDshRuntimeVersion()
+
+function fixture() {
+  const temporary = mkdtempSync(join(tmpdir(), 'dsh-preflight-'))
+  let ctx: Context | undefined
+  onTestFinished(async () => {
+    try { await ctx?.fiber.dispose() } finally { rmSync(temporary, { recursive: true, force: true }) }
+  })
+  const dir = realpathSync(temporary)
+  const effects = join(dir, 'effects')
+  const warnings: string[] = []
+  // Admission diagnostics precede the composed tree, so stderr is the channel under test.
+  const stderr = vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => {
+    warnings.push(String(chunk))
+    return true
+  })
+  onTestFinished(() => { stderr.mockRestore() })
+
+  function plugin(name: string, options: { version?: string; peer?: string; alias?: string } = {}): void {
+    const packageDir = join(dir, 'node_modules', options.alias ?? name)
+    mkdirSync(packageDir, { recursive: true })
+    writeFileSync(join(packageDir, 'package.json'), JSON.stringify({
+      name, version: options.version ?? '1.0.0', type: 'module', exports: './index.mjs',
+      ...options.peer === undefined ? {} : { peerDependencies: { '@deepseek-ai/dsh-test': options.peer } },
+    }))
+    writeFileSync(join(packageDir, 'index.mjs'), `import { appendFileSync } from 'node:fs'
+const record = (value) => appendFileSync(new URL('${pathToFileURL(effects).href}'), value + '\\n')
+record('import:${name}')
+export function apply() { record('apply:${name}') }
+`)
+  }
+
+  function exemptions(value: Record<string, string[]>): void {
+    writeFileSync(join(dir, PROFILE_COMPATIBILITY_FILENAME), JSON.stringify(value))
+  }
+
+  const profile: ProfileContext = {
+    name: 'preflight', dir, patchPath: join(dir, 'cordis.patch.yml'),
+    installAnchor: join(dir, 'package.json'), cwd: dir, home: dir,
+    startedBundles: [], overlays: [], telemetryDisabledEnv: undefined,
+  }
+  const configPath = join(dir, 'cordis.yml')
+  writeFileSync(configPath, '[]\n')
+  exemptions({})
+
+  /** Boot the profile with these patches and return the recorded plugin effects. */
+  async function run(patches: PatchOptions[], packages = false): Promise<string[]> {
+    ctx = await boot('preflight', configPath, patches, async (host) => {
+      host.provide('profileContext', profile)
+      if (packages) await host.plugin(PluginPackages)
+      host.logger.exporter({ levels: { default: 3 }, export(message) {
+        if (message.type === 'warn' || message.type === 'error') warnings.push(String(message.args[0]))
+      } })
+    })
+    return existsSync(effects) ? readFileSync(effects, 'utf8').trim().split('\n') : []
+  }
+
+  return { dir, profile, configPath, warnings, plugin, exemptions, run }
+}
+
+const insert = (...names: string[]) => [{ insert: names.map((name, index) => ({ id: `row-${String(index)}`, name })) }]
+
+it('blocks an incompatible plugin before its module is imported while a compatible sibling loads', async () => {
+  const f = fixture()
+  f.plugin('denied-plugin', { peer: '^9.0.0' })
+  f.plugin('allowed-plugin')
+  const effects = await f.run(insert('allowed-plugin', 'denied-plugin'))
+  expect(effects).toEqual(['import:allowed-plugin', 'apply:allowed-plugin'])
+  expect(f.warnings.join('\n')).toContain('denied-plugin@1.0.0')
+  expect(f.warnings.join('\n')).toContain('data loss')
+})
+
+it('admits the same plugin only for its exact version and the running runtime', async () => {
+  const granted = fixture()
+  granted.plugin('denied-plugin', { peer: '^9.0.0' })
+  granted.exemptions({ 'denied-plugin@1.0.0': [runtime] })
+  expect(await granted.run(insert('denied-plugin'))).toEqual(['import:denied-plugin', 'apply:denied-plugin'])
+
+  const otherVersion = fixture()
+  otherVersion.plugin('denied-plugin', { version: '2.0.0', peer: '^9.0.0' })
+  otherVersion.exemptions({ 'denied-plugin@1.0.0': [runtime] })
+  expect(await otherVersion.run(insert('denied-plugin'))).toEqual([])
+
+  const otherRuntime = fixture()
+  otherRuntime.plugin('denied-plugin', { peer: '^9.0.0' })
+  otherRuntime.exemptions({ 'denied-plugin@1.0.0': ['9.9.9'] })
+  expect(await otherRuntime.run(insert('denied-plugin'))).toEqual([])
+})
+
+const denialSpecifiers: Array<[string, (name: string, dir: string) => string]> = [
+  ['a package name', () => 'denied-plugin'],
+  ['a relative module', () => './node_modules/denied-plugin/index.mjs'],
+  ['an absolute module', (name, dir) => join(dir, 'node_modules', name, 'index.mjs')],
+  ['a file URL', (name, dir) => pathToFileURL(join(dir, 'node_modules', name, 'index.mjs')).href],
+]
+
+it.each(denialSpecifiers)('blocks an incompatible %s before import', async (_label, specifier) => {
+  const f = fixture()
+  f.plugin('denied-plugin', { peer: '^9.0.0' })
+  expect(await f.run(insert(specifier('denied-plugin', f.dir)))).toEqual([])
+})
+
+it('blocks a denied plugin reached through a package-imports alias', async () => {
+  const f = fixture()
+  const aliased = join(f.dir, 'aliased')
+  mkdirSync(aliased)
+  writeFileSync(join(aliased, 'package.json'), JSON.stringify({
+    name: 'denied-plugin', version: '1.0.0', type: 'module', exports: './index.mjs',
+    peerDependencies: { '@deepseek-ai/dsh-test': '^9.0.0' },
+  }))
+  writeFileSync(join(aliased, 'index.mjs'), `import { appendFileSync } from 'node:fs'
+appendFileSync(new URL('${pathToFileURL(join(f.dir, 'effects')).href}'), 'import:denied-plugin\\n')
+export function apply() {}
+`)
+  writeFileSync(join(f.dir, 'package.json'), JSON.stringify({
+    name: 'preflight-profile', private: true, type: 'module',
+    imports: { '#denied': './aliased/index.mjs' },
+  }))
+  expect(await f.run(insert('#denied'))).toEqual([])
+  expect(f.warnings.join('\n')).toContain('denied-plugin@1.0.0')
+})
+
+it('blocks an incompatible descendant of a native group while its compatible sibling loads', async () => {
+  const f = fixture()
+  f.plugin('denied-plugin', { peer: '^9.0.0' })
+  f.plugin('allowed-plugin')
+  const effects = await f.run([{ insert: [{ id: 'group', name: 'cordis:group', group: true, config: [
+    { id: 'allowed', name: 'allowed-plugin' },
+    { id: 'denied', name: 'denied-plugin' },
+  ] }] }])
+  expect(effects).toEqual(['import:allowed-plugin', 'apply:allowed-plugin'])
+})
+
+it('omits a native Include that reaches an incompatible plugin and keeps an unrelated Include', async () => {
+  const f = fixture()
+  f.plugin('denied-plugin', { peer: '^9.0.0' })
+  f.plugin('allowed-plugin')
+  const deniedList = join(f.dir, 'denied.cordis.yml')
+  const allowedList = join(f.dir, 'allowed.cordis.yml')
+  writeFileSync(deniedList, JSON.stringify([{ id: 'denied', name: 'denied-plugin' }]))
+  writeFileSync(allowedList, JSON.stringify([{ id: 'allowed', name: 'allowed-plugin' }]))
+  const effects = await f.run([{ insert: [
+    { id: 'denied-include', name: 'cordis:include', config: { path: pathToFileURL(deniedList).href } },
+    { id: 'allowed-include', name: 'cordis:include', config: { path: pathToFileURL(allowedList).href } },
+  ] }])
+  expect(effects).toEqual(['import:allowed-plugin', 'apply:allowed-plugin'])
+  expect(f.warnings.join('\n')).toContain('never rewritten')
+})
+
+it('leaves an unresolvable row to the Loader instead of denying it', async () => {
+  const f = fixture()
+  expect(await f.run(insert('./missing.mjs'))).toEqual([])
+  expect(f.warnings.join('\n')).toContain('missing.mjs')
+  expect(f.warnings.join('\n')).not.toContain('disabled:')
+})
+
+it('denies a row whose peer metadata cannot be validated', async () => {
+  const f = fixture()
+  f.plugin('malformed-plugin')
+  writeFileSync(join(f.dir, 'node_modules', 'malformed-plugin', 'package.json'),
+    JSON.stringify({ name: 'malformed-plugin', version: '1.0.0', peerDependencies: ['@deepseek-ai/dsh'] }))
+  expect(await f.run(insert('malformed-plugin'))).toEqual([])
+  expect(f.warnings.join('\n')).toContain('cannot be validated')
+})
+
+it('leaves an explicitly disabled row and a non-profile composition untouched', async () => {
+  const f = fixture()
+  f.plugin('denied-plugin', { peer: '^9.0.0' })
+  expect(await f.run([{ insert: [{ id: 'off', name: 'denied-plugin', disabled: true }] }])).toEqual([])
+
+  const unrelated = new Context()
+  onTestFinished(() => unrelated.fiber.dispose())
+  const rows = [{ id: 'row', name: 'denied-plugin' }]
+  expect(prepareProfileEntries(unrelated, rows, f.dir)).toEqual(rows)
+})
+
+it('reports a rejected record while the records it accepted still apply', async () => {
+  const f = fixture()
+  f.plugin('denied-plugin', { peer: '^9.0.0' })
+  f.plugin('allowed-plugin')
+  writeFileSync(join(f.dir, PROFILE_COMPATIBILITY_FILENAME),
+    JSON.stringify({ 'denied-plugin@1.0.0': [runtime], 'broken@*': [runtime] }))
+  // The accepted grant still admits its plugin; only the broken record is reported and dropped.
+  expect((await f.run(insert('allowed-plugin', 'denied-plugin'))).sort())
+    .toEqual(['apply:allowed-plugin', 'apply:denied-plugin', 'import:allowed-plugin', 'import:denied-plugin'])
+  expect(f.warnings.join('\n')).toContain('is not an exact package-name@version key')
+})
+
+it('starts with no exemptions and a warning when the permission file is unparsable', async () => {
+  const f = fixture()
+  f.plugin('denied-plugin', { peer: '^9.0.0' })
+  writeFileSync(join(f.dir, PROFILE_COMPATIBILITY_FILENAME), '{ not json')
+  expect(await f.run(insert('denied-plugin'))).toEqual([])
+  expect(f.warnings.join('\n')).toContain('is not valid JSON')
+  expect(f.warnings.join('\n')).toContain('is incompatible with dsh')
+})
+
+describe('manifest resolution', () => {
+  function context(f: ReturnType<typeof fixture>): Context {
+    const ctx = new Context()
+    onTestFinished(() => ctx.fiber.dispose())
+    ctx.provide('profileContext', f.profile)
+    return ctx
+  }
+
+  it('leaves rows with no resolvable manifest to the Loader', () => {
+    const f = fixture()
+    writeFileSync(join(f.dir, 'standalone.mjs'), 'export function apply() {}\n')
+    const rows = [
+      { id: 'outside', name: './standalone.mjs' },
+      { id: 'builtin', name: 'node:fs' },
+      { id: 'missing', name: 'missing-package' },
+    ]
+    expect(prepareProfileEntries(context(f), rows, pathToFileURL(f.dir).href + '/')).toEqual(rows)
+  })
+
+  it('denies through the mounted package service when the launcher supplies one', async () => {
+    const f = fixture()
+    f.plugin('denied-plugin', { peer: '^9.0.0' })
+    expect(await f.run(insert('denied-plugin'), true)).toEqual([])
+    expect(f.warnings.join('\n')).toContain('denied-plugin@1.0.0')
+  })
+
+  it('stops at a recursive Include instead of recursing forever', () => {
+    const f = fixture()
+    const inner = join(f.dir, 'inner.cordis.yml')
+    const outer = join(f.dir, 'outer.cordis.yml')
+    writeFileSync(inner, `- id: nested\n  name: cordis:include\n  config: { path: ${JSON.stringify(outer)} }\n`)
+    writeFileSync(outer, `- id: outer\n  name: cordis:include\n  config: { path: ${JSON.stringify(inner)} }\n`)
+    const rows = prepareProfileEntries(context(f), [{ id: 'cycle', name: 'cordis:include', config: { path: inner } }],
+      pathToFileURL(f.dir).href + '/')
+    expect(rows[0]?.disabled).toBeUndefined()
+  })
+
+  it('leaves an Include whose file is not an entry list undecided', () => {
+    const f = fixture()
+    const mapping = join(f.dir, 'mapping.cordis.yml')
+    writeFileSync(mapping, 'id: nested\nname: denied-plugin\n')
+    const rows = prepareProfileEntries(context(f), [{ id: 'row', name: 'cordis:include', config: { path: mapping } }],
+      pathToFileURL(f.dir).href + '/')
+    expect(rows[0]?.disabled).toBeUndefined()
+  })
+
+  it('warns about ignored patches while the included rows still decide', () => {
+    const f = fixture()
+    f.plugin('allowed-plugin')
+    const list = join(f.dir, 'patched.cordis.yml')
+    writeFileSync(list, '- id: nested\n  name: allowed-plugin\n')
+    const ctx = context(f)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    onTestFinished(() => { warn.mockRestore() })
+    const rows = prepareProfileEntries(ctx, [{ id: 'outer', name: 'cordis:include',
+      config: { path: list, patches: [{ id: 'absent', disabled: true }] } }], pathToFileURL(f.dir).href + '/')
+    expect(rows[0]?.disabled).toBeUndefined()
+    expect(warn.mock.calls.flat().map(String).join(' ')).toContain('absent')
+  })
+
+  it.each([
+    ['an unreadable manifest', (f: ReturnType<typeof fixture>) => {
+      f.plugin('denied-plugin')
+      rmSync(join(f.dir, 'node_modules', 'denied-plugin', 'package.json'))
+      mkdirSync(join(f.dir, 'node_modules', 'denied-plugin', 'package.json'))
+    }],
+    ['a module path that loops', (f: ReturnType<typeof fixture>) => {
+      f.plugin('denied-plugin')
+      symlinkSync('loop.mjs', join(f.dir, 'node_modules', 'denied-plugin', 'loop.mjs'))
+    }],
+  ])('refuses a row whose %s cannot be read', (_label, prepare) => {
+    const f = fixture()
+    prepare(f)
+    const name = _label === 'a module path that loops'
+      ? './node_modules/denied-plugin/loop.mjs' : './node_modules/denied-plugin/index.mjs'
+    const rows = prepareProfileEntries(context(f), [{ id: 'row', name }], pathToFileURL(f.dir).href + '/')
+    expect(rows[0]?.disabled).toBe(true)
+    expect(f.warnings.join('\n')).toContain('cannot be validated')
+  })
+
+  it('denies a group-shaped row and clears its group flag', () => {
+    const f = fixture()
+    f.plugin('denied-plugin', { peer: '^9.0.0' })
+    const rows = prepareProfileEntries(context(f), [{ id: 'row', name: 'denied-plugin', group: true, config: [] }],
+      pathToFileURL(f.dir).href + '/')
+    expect(rows[0]).toMatchObject({ disabled: true, group: false })
+  })
+
+  it('ignores a native Include whose path is not a literal YAML or JSON file', () => {
+    const f = fixture()
+    const ctx = context(f)
+    for (const config of [undefined, { path: 7 }, { path: './plugin.mjs' }]) {
+      expect(prepareProfileEntries(ctx, [{ id: 'row', name: 'cordis:include', config }],
+        pathToFileURL(f.dir).href + '/')).toEqual([{ id: 'row', name: 'cordis:include', config }])
+    }
+  })
+
+  it('ignores an absent literal Include without initial entries and reads them when provided', () => {
+    const f = fixture()
+    f.plugin('denied-plugin', { peer: '^9.0.0' })
+    const ctx = context(f)
+    const base = pathToFileURL(f.dir).href + '/'
+    const missing = join(f.dir, 'missing.cordis.yml')
+    expect(prepareProfileEntries(ctx, [{ id: 'row', name: 'cordis:include', config: { path: missing } }], base))
+      .toEqual([{ id: 'row', name: 'cordis:include', config: { path: missing } }])
+    const rows = prepareProfileEntries(ctx, [{ id: 'row', name: 'cordis:include',
+      config: { path: missing, initial: [{ id: 'denied', name: 'denied-plugin' }] } }], base)
+    expect(rows[0]?.disabled).toBe(true)
+    expect(f.warnings.join('\n')).toContain('never rewritten')
+  })
+
+  it('returns no patches for a profile whose composition has no rows and warns about an unmatched patch', () => {
+    const f = fixture()
+    const ctx = context(f)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    onTestFinished(() => { warn.mockRestore() })
+    const base = pathToFileURL(f.dir).href + '/'
+    expect(prepareProfilePatches(ctx, [], base)).toEqual([])
+    expect(prepareProfilePatches(ctx, [{ id: 'absent', disabled: true }], base)).toEqual([])
+    expect(warn.mock.calls.flat().map(String).join(' ')).toContain('absent')
+  })
+
+  it('requires a resolution base for a profile composition', () => {
+    const f = fixture()
+    expect(() => { prepareProfileEntries(context(f), [{ id: 'row', name: 'allowed-plugin' }], undefined) })
+      .toThrow('requires a resolution base')
+  })
+
+})
+
+it('reuses the documented literal Include dialect when reading included entries', async () => {
+  const f = fixture()
+  f.plugin('allowed-plugin')
+  const list = join(f.dir, 'nested.cordis.yml')
+  writeFileSync(list, '- id: nested\n  name: allowed-plugin\n')
+  expect(load(readFileSync(list, 'utf8'), { schema: entryListSchema })).toEqual([{ id: 'nested', name: 'allowed-plugin' }])
+  // The launcher mounts an Include with a file URL, which a Windows path cannot stand in for: `C:` reads as a scheme.
+  expect(await f.run([{ insert: [{ id: 'outer', name: 'cordis:include', config: { path: pathToFileURL(list).href } }] }]))
+    .toEqual(['import:allowed-plugin', 'apply:allowed-plugin'])
+})
diff --git a/packages/boot/app-boot/tests/plugin-compatibility.spec.ts b/packages/boot/app-boot/tests/plugin-compatibility.spec.ts
new file mode 100644
index 0000000000..b55187eeab
--- /dev/null
+++ b/packages/boot/app-boot/tests/plugin-compatibility.spec.ts
@@ -0,0 +1,177 @@
+/** Plugin peer checks retain exact mismatches and never inherit exemption entries. */
+
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import semver from 'semver'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { evaluatePluginCompatibility, getDshRuntimeVersion, pluginCompatibilityWarning } from '../src/plugin-compatibility.ts'
+
+const runtime = '0.1.7-alpha.1'
+const identity = { name: '@example/plugin', version: '2.0.0' }
+const incompatible = { ...identity, peerDependencies: { '@deepseek-ai/dsh': '^0.2.0' } }
+
+function check(peerDependencies: object) {
+  return evaluatePluginCompatibility({ ...identity, peerDependencies }, {}, runtime)
+}
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('dsh runtime version', () => {
+  it('reads the exact version with a string path accepted by executable virtual filesystems', () => {
+    const { version: expected } = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }
+    const read = vi.spyOn(fs, 'readFileSync')
+    expect(getDshRuntimeVersion()).toBe(expected)
+    expect(semver.valid(expected)).not.toBeNull()
+    expect(read).toHaveBeenCalledWith(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')
+  })
+
+  it.each([{}, { version: null }, { version: 1 }, { version: '' }, { version: 'not-semver' }])(
+    'rejects an invalid or absent package version: %j', (manifest) => {
+      vi.spyOn(fs, 'readFileSync').mockReturnValueOnce(JSON.stringify(manifest))
+      expect(() => getDshRuntimeVersion()).toThrow('Invalid dsh runtime version')
+    },
+  )
+
+  it.each(['null', '[]', '1', '"text"'])('rejects non-object package JSON: %s', (contents) => {
+    vi.spyOn(fs, 'readFileSync').mockReturnValueOnce(contents)
+    expect(() => getDshRuntimeVersion()).toThrow('app-boot package.json must be an object')
+  })
+
+  it('propagates malformed JSON and read failures', () => {
+    const read = vi.spyOn(fs, 'readFileSync').mockReturnValueOnce('{')
+    expect(() => getDshRuntimeVersion()).toThrow(SyntaxError)
+    read.mockImplementationOnce(() => { throw new Error('manifest unavailable') })
+    expect(() => getDshRuntimeVersion()).toThrow('manifest unavailable')
+  })
+})
+
+describe('plugin compatibility', () => {
+  it('defaults to the installed runtime and needs no identity without mismatches', () => {
+    expect(evaluatePluginCompatibility({})).toBeUndefined()
+    expect(evaluatePluginCompatibility({ peerDependencies: { '@deepseek-ai/dsh': getDshRuntimeVersion() } })).toBeUndefined()
+    expect(check({})).toBeUndefined()
+  })
+
+  it.each(['*', '^0.1.0', '~0.1.0', '>=0.1.0 <0.2.0', '0.1.x', '0.1.0 - 0.1.9', '^0.2.0 || ^0.1.0', runtime])(
+    'includes prereleases in supported semver range %s', (range) => {
+      expect(check({ '@deepseek-ai/dsh': range, '@deepseek-ai/dsh-session': range })).toBeUndefined()
+    },
+  )
+
+  it.each(['workspace:^', 'workspace:~', 'workspace:*'])('uses the source runtime for %s', (range) => {
+    expect(check({ '@deepseek-ai/dsh-session': range })).toBeUndefined()
+  })
+
+  it('checks the intersection of dsh requirements and returns only mismatches', () => {
+    expect(check({
+      '@deepseek-ai/dsh': '^0.1.0',
+      '@deepseek-ai/dsh-session': '>=0.2.0',
+      '@deepseek-ai/dsh-tools': '<0.1.0',
+      '@deepseek-ai/cordis': '^99.0.0',
+    })).toEqual({
+      ...identity,
+      runtimeVersion: runtime,
+      peers: { '@deepseek-ai/dsh-session': '>=0.2.0', '@deepseek-ai/dsh-tools': '<0.1.0' },
+      exempted: false,
+    })
+  })
+
+  it.each(['^0.2.0', '>=0.1.7', 'broken', '', ' ', 'workspace:>=0.2.0', 'file:../dsh', 'npm:dsh@*'])(
+    'fails closed for an incompatible or malformed range %j', (range) => {
+      expect(check({ '@deepseek-ai/dsh': range })?.peers).toEqual({ '@deepseek-ai/dsh': range })
+    },
+  )
+
+  it('ignores unrelated names and dependency fields', () => {
+    expect(check({
+      '@deepseek-ai/cordis': 'broken', '@deepseek-ai/cordis-plugin-loader': '^99',
+      '@other/dsh': '^99', '@deepseek-ai/dshx': '^99', dsh: '^99',
+      constructor: '^99', hasOwnProperty: '^99', ['__proto__']: '^99',
+    })).toBeUndefined()
+    expect(evaluatePluginCompatibility({ dependencies: { '@deepseek-ai/dsh': '^99' } }, {}, runtime)).toBeUndefined()
+  })
+
+  it.each([null, [], 'bad', 1, false, undefined])('rejects malformed peerDependencies: %j', (peerDependencies) => {
+    expect(() => evaluatePluginCompatibility({ ...identity, peerDependencies }, {}, runtime)).toThrow('peerDependencies must be an object')
+  })
+
+  it.each([null, [], {}, 1, false, undefined])('rejects non-string peer ranges: %j', (range) => {
+    for (const name of ['@deepseek-ai/dsh', '@deepseek-ai/cordis']) {
+      expect(() => check({ [name]: range })).toThrow(`peerDependencies[${JSON.stringify(name)}] must be a string`)
+    }
+  })
+
+  it.each(['name', 'version'] as const)('requires own non-empty %s on a mismatch', (field) => {
+    for (const value of [undefined, null, '', ' ', 3]) {
+      expect(() => evaluatePluginCompatibility({ ...incompatible, [field]: value }, {}, runtime))
+        .toThrow(`Plugin manifest ${field} must be a non-empty string`)
+    }
+    const inherited = Object.assign(
+      Object.create({ [field]: identity[field] }) as object,
+      Object.fromEntries(Object.entries(incompatible).filter(([name]) => name !== field)),
+    )
+    expect(() => evaluatePluginCompatibility(inherited, {}, runtime)).toThrow(`Plugin manifest ${field}`)
+  })
+
+  it('ignores inherited peer declarations and inherited peer entries', () => {
+    expect(evaluatePluginCompatibility(Object.create(incompatible) as object, {}, runtime)).toBeUndefined()
+    expect(check(Object.create(incompatible.peerDependencies) as object)).toBeUndefined()
+    expect(check(Object.assign(Object.create({ '@deepseek-ai/dsh': '^99' }) as object, { '@deepseek-ai/dsh-session': '*' }))).toBeUndefined()
+  })
+
+  it('rejects an invalid explicit runtime even when no peers are declared', () => {
+    expect(() => evaluatePluginCompatibility({}, {}, 'invalid')).toThrow('Invalid dsh runtime version')
+  })
+
+  it('rejects array plugin manifests', () => {
+    expect(() => evaluatePluginCompatibility([], {}, runtime)).toThrow('Plugin manifest must be an object')
+  })
+})
+
+describe('exact-version exemptions', () => {
+  const exemptions = { '@example/plugin@2.0.0': [runtime] }
+
+  it('exempts only the exact scoped plugin and runtime versions', () => {
+    expect(evaluatePluginCompatibility(incompatible, exemptions, runtime)?.exempted).toBe(true)
+    expect(evaluatePluginCompatibility({ ...incompatible, version: '2.0.1' }, exemptions, runtime)?.exempted).toBe(false)
+    expect(evaluatePluginCompatibility({ ...incompatible, name: '@other/plugin' }, exemptions, runtime)?.exempted).toBe(false)
+    expect(evaluatePluginCompatibility(incompatible, exemptions, '0.1.7-alpha.2')?.exempted).toBe(false)
+    expect(evaluatePluginCompatibility(incompatible, exemptions, `${runtime}+build`)?.exempted).toBe(false)
+  })
+
+  it.each(['*', '^0.1.0', '0.1.7', '0.1.7-alpha.2'])('does not interpret exemption value %s as a range', (version) => {
+    expect(evaluatePluginCompatibility(incompatible, { '@example/plugin@2.0.0': [version] }, runtime)?.exempted).toBe(false)
+  })
+
+  it('does not accept inherited exemptions, but accepts own entries on null-prototype maps', () => {
+    expect(evaluatePluginCompatibility(incompatible, Object.create(exemptions) as typeof exemptions, runtime)?.exempted).toBe(false)
+    const ownExemptions = Object.assign(Object.create(null) as object, exemptions)
+    expect(evaluatePluginCompatibility(incompatible, ownExemptions, runtime)?.exempted).toBe(true)
+  })
+
+  it.each(['constructor', 'hasOwnProperty', '__proto__'])('handles plugin identity %s without prototype lookup', (name) => {
+    const manifest = { ...incompatible, name }
+    expect(evaluatePluginCompatibility(manifest, {}, runtime)?.exempted).toBe(false)
+    expect(evaluatePluginCompatibility(manifest, { [`${name}@2.0.0`]: [runtime] }, runtime)?.exempted).toBe(true)
+  })
+
+  it('does not produce issues for compatible exempted plugins', () => {
+    expect(evaluatePluginCompatibility({ ...identity, peerDependencies: { '@deepseek-ai/dsh': '*' } }, exemptions, runtime)).toBeUndefined()
+  })
+})
+
+describe('compatibility warning', () => {
+  it.each([false, true])('retains mismatch details and risk when exemption status is %s', (exempted) => {
+    expect(pluginCompatibilityWarning({
+      ...identity, runtimeVersion: runtime,
+      peers: { '@deepseek-ai/dsh': '^0.2.0', '@deepseek-ai/dsh-session': 'broken' }, exempted,
+    })).toBe(
+      'Plugin @example/plugin@2.0.0 is incompatible with dsh 0.1.7-alpha.1: '
+      + 'peerDependencies {"@deepseek-ai/dsh":"^0.2.0","@deepseek-ai/dsh-session":"broken"}. '
+      + 'Running it may cause crashes or data loss. '
+      + 'Update the plugin or install a plugin version compatible with this dsh runtime. '
+      + 'To accept this risk explicitly, add the exact-version exemption {"@example/plugin@2.0.0":["0.1.7-alpha.1"]}. '
+      + `Exact-version exemption: ${exempted ? 'active' : 'not active'}.`,
+    )
+  })
+})
diff --git a/packages/boot/app-boot/tests/profile-compatibility.spec.ts b/packages/boot/app-boot/tests/profile-compatibility.spec.ts
new file mode 100644
index 0000000000..0fdc9e395b
--- /dev/null
+++ b/packages/boot/app-boot/tests/profile-compatibility.spec.ts
@@ -0,0 +1,132 @@
+/** Profile-local compatibility permissions: exact identities, informed grants, and malformed data. */
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it, onTestFinished } from 'vitest'
+import { getDshRuntimeVersion } from '../src/index.ts'
+import {
+  PROFILE_COMPATIBILITY_FILENAME, isExactPluginVersion,
+  readProfileCompatibility, readProfileVersionExemptions, setProfileVersionExemption, validatePluginVersionExemption,
+} from '../src/profile-compatibility.ts'
+
+const runtime = getDshRuntimeVersion()
+
+function profileFixture(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-compatibility-'))
+  onTestFinished(() => { rmSync(dir, { recursive: true, force: true }) })
+  return dir
+}
+
+function write(dir: string, value: unknown): void {
+  writeFileSync(join(dir, PROFILE_COMPATIBILITY_FILENAME), JSON.stringify(value))
+}
+
+it('reads no permissions from a profile without a compatibility file', () => {
+  expect(readProfileVersionExemptions(profileFixture())).toEqual({})
+})
+
+it('reports an unreadable permission file instead of failing the profile', () => {
+  const dir = profileFixture()
+  mkdirSync(join(dir, PROFILE_COMPATIBILITY_FILENAME))
+  const read = readProfileCompatibility(dir)
+  expect(read.exemptions).toEqual({})
+  expect(read.rewritable).toBe(false)
+  expect(read.warnings.join('\n')).toMatch(/cannot be read/)
+})
+
+it('reads exact plugin and runtime identities, including build metadata', () => {
+  const dir = profileFixture()
+  write(dir, { '@scope/plugin@1.2.3+build.7': [runtime, '2.0.0-alpha+runtime'] })
+  expect(readProfileVersionExemptions(dir)).toEqual({ '@scope/plugin@1.2.3+build.7': [runtime, '2.0.0-alpha+runtime'] })
+})
+
+it.each([
+  ['an array', []], ['a string', 'all'], ['null', null],
+  ['a non-list value', { 'plugin@1.2.3': '1.2.3' }],
+  ['a non-string version', { 'plugin@1.2.3': [1] }],
+  ['a range version', { 'plugin@1.2.3': ['^1.2.3'] }],
+  ['a range key', { 'plugin@^1.2.3': [runtime] }],
+  ['an unversioned key', { plugin: [runtime] }],
+])('authorizes nothing for malformed permissions and reports them: %s', (_label, value) => {
+  const dir = profileFixture()
+  write(dir, value)
+  const read = readProfileCompatibility(dir)
+  // A bad file must never make the profile unusable: it grants nothing, so incompatible plugins stay denied.
+  expect(read.exemptions).toEqual({})
+  expect(read.rewritable).toBe(false)
+  expect(read.warnings).toHaveLength(1)
+  expect(read.warnings[0]).toContain(PROFILE_COMPATIBILITY_FILENAME)
+})
+
+it('keeps the records it accepted and reports only the rejected ones', () => {
+  const dir = profileFixture()
+  write(dir, { 'good@1.2.3': [runtime], 'bad@^1.0.0': [runtime], 'also-good@2.0.0': [] })
+  const read = readProfileCompatibility(dir)
+  expect(read.exemptions).toEqual({ 'good@1.2.3': [runtime], 'also-good@2.0.0': [] })
+  expect(read.warnings).toHaveLength(1)
+  expect(read.warnings[0]).toContain('bad@^1.0.0')
+  expect(read.rewritable).toBe(false)
+})
+
+it('accepts an empty permission list as authorizing nothing', () => {
+  const dir = profileFixture()
+  write(dir, { 'plugin@1.2.3': [] })
+  expect(readProfileVersionExemptions(dir)).toEqual({ 'plugin@1.2.3': [] })
+  expect(readProfileCompatibility(dir)).toEqual({ exemptions: { 'plugin@1.2.3': [] }, warnings: [], rewritable: true })
+})
+
+it.each(['1.2.3', '1.2.3-alpha.1', '1.2.3+build.7', '1.2.3-alpha+build'])('accepts exact version %s', (version) => {
+  expect(isExactPluginVersion(version)).toBe(true)
+  expect(() => { validatePluginVersionExemption(`@scope/plugin@${version}`, version) }).not.toThrow()
+})
+
+it.each([
+  ['plugin', '1.2.3'], ['plugin@^1.2.3', '1.2.3'], ['plugin@v1.2.3', '1.2.3'],
+  ['plugin@1.2.3', '*'], ['plugin@1.2.3', ' 1.2.3'], ['../plugin@1.2.3', '1.2.3'],
+])('rejects noncanonical identity %s / %s', (plugin, version) => {
+  expect(() => { validatePluginVersionExemption(plugin, version) }).toThrow('exact')
+})
+
+it('requires explicit risk acknowledgement and the running runtime for a grant', async () => {
+  const dir = profileFixture()
+  await expect(setProfileVersionExemption(dir, 'plugin@1.0.0', runtime, true, false)).rejects.toThrow('crashes or data loss')
+  await expect(setProfileVersionExemption(dir, 'plugin@1.0.0', '9.9.9', true, true)).rejects.toThrow(`runs DSH ${runtime}`)
+  expect(readProfileVersionExemptions(dir)).toEqual({})
+})
+
+it('persists grants with owner-only permissions and revokes one runtime without losing the others', async () => {
+  const dir = profileFixture()
+  await setProfileVersionExemption(dir, 'plugin@1.0.0', runtime, true, true)
+  await setProfileVersionExemption(dir, 'other@2.0.0', runtime, true, true)
+  const filename = join(dir, PROFILE_COMPATIBILITY_FILENAME)
+  expect(readProfileVersionExemptions(dir)).toEqual({ 'plugin@1.0.0': [runtime], 'other@2.0.0': [runtime] })
+  expect(JSON.parse(readFileSync(filename, 'utf8'))).toEqual({ 'plugin@1.0.0': [runtime], 'other@2.0.0': [runtime] })
+  if (process.platform !== 'win32') expect(statSync(filename).mode & 0o777).toBe(0o600)
+
+  // A repeated grant never duplicates, and a grant left by an older runtime can still be revoked.
+  await setProfileVersionExemption(dir, 'plugin@1.0.0', runtime, true, true)
+  expect(readProfileVersionExemptions(dir)['plugin@1.0.0']).toEqual([runtime])
+  write(dir, { 'plugin@1.0.0': [runtime, '0.0.1'], 'other@2.0.0': [runtime] })
+  await setProfileVersionExemption(dir, 'plugin@1.0.0', '0.0.1', false, false)
+  expect(readProfileVersionExemptions(dir)).toEqual({ 'plugin@1.0.0': [runtime], 'other@2.0.0': [runtime] })
+  await setProfileVersionExemption(dir, 'plugin@1.0.0', runtime, false, false)
+  expect(readProfileVersionExemptions(dir)).toEqual({ 'other@2.0.0': [runtime] })
+})
+
+it('creates the profile directory for a first grant and refuses to widen malformed permissions', async () => {
+  const dir = profileFixture()
+  const nested = join(dir, 'profiles', 'test')
+  await setProfileVersionExemption(nested, 'plugin@1.0.0', runtime, true, true)
+  expect(readProfileVersionExemptions(nested)).toEqual({ 'plugin@1.0.0': [runtime] })
+  write(nested, { 'plugin@*': [runtime] })
+  // Rewriting a file the reader rejected would discard the user's content, so a write refuses.
+  await expect(setProfileVersionExemption(nested, 'other@1.0.0', runtime, true, true)).rejects.toThrow(/must be repaired/)
+  expect(readFileSync(join(nested, PROFILE_COMPATIBILITY_FILENAME), 'utf8')).toContain('plugin@*')
+})
+
+it('still revokes an accepted grant while another record is rejected', async () => {
+  const dir = profileFixture()
+  await setProfileVersionExemption(dir, 'plugin@1.0.0', runtime, true, true)
+  write(dir, { 'plugin@1.0.0': [runtime], 'bad@1.0.0': 'not-a-list' })
+  await expect(setProfileVersionExemption(dir, 'plugin@1.0.0', runtime, false, false)).rejects.toThrow(/must be repaired/)
+})
diff --git a/packages/boot/app-boot/tsconfig.json b/packages/boot/app-boot/tsconfig.json
index c1e709f660..e59c38f2ba 100644
--- a/packages/boot/app-boot/tsconfig.json
+++ b/packages/boot/app-boot/tsconfig.json
@@ -31,6 +31,9 @@
     },
     {
       "path": "../../util/package-manifest"
+    },
+    {
+      "path": "../../util/atomic-write"
     }
   ]
 }
diff --git a/packages/boot/plugin-manager/README.i18n.yaml b/packages/boot/plugin-manager/README.i18n.yaml
index c612967bc1..64798be732 100644
--- a/packages/boot/plugin-manager/README.i18n.yaml
+++ b/packages/boot/plugin-manager/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/plugin-manager/README.md
-README.md: 24936df8b1be4e2997c2382e0d84fddd2dfc5345
-README.zh.md: 122ccc9a2796caf891b19a38c3c90e9d32a22fdc
+README.md: 4977a59a1a3a313580cb2ddad8c9054c36da7af9
+README.zh.md: fcf4b6dc69689a6c71631bfd51ca3cdba5147f9e
diff --git a/packages/boot/plugin-manager/README.md b/packages/boot/plugin-manager/README.md
index 24936df8b1..4977a59a1a 100644
--- a/packages/boot/plugin-manager/README.md
+++ b/packages/boot/plugin-manager/README.md
@@ -57,6 +57,17 @@ The browser-safe `@deepseek-ai/dsh-plugin-manager/registry` entry exports `OFFIC
 
 When pnpm 11 blocks dependency scripts, the failed installation reports every pending package name in the profile under `pendingBuilds`, including names left by earlier attempts; a failed run restores `package.json` and `pnpm-lock.yaml` but deliberately not `pnpm-workspace.yaml`, where pnpm records them. The Web plugin page offers **Allow these scripts and retry**; the tool can grant permission on the user's behalf through `approvedBuilds` on `install_bundle`, after the user approves those scripts in the conversation. The service validates pending names; it does not verify conversation approval. Approval persists by package name in this profile, permits commands with the host user's permissions, and survives another installation failure. Only currently undecided names can be approved; existing denials and wildcard rules cannot be overridden through this action. Approval rejects YAML anchors or aliases inside `allowBuilds`. Retry preserves the original activation choice.
 
+<a id="version-compatibility-and-exemptions"></a>
+### Version compatibility and exemptions
+
+An install command that names packages (`add`, or `install` with specs) is checked before pnpm runs: a local path is read from its own `package.json`, and a registry spec is resolved through pnpm's registry lookup for the version its range selects and the peers that version declares. An incompatible DSH peer rejects the operation before pnpm runs, so nothing is downloaded and no build script runs; a build approval the caller supplied with the request is recorded before this check and remains. A git or tarball spec needs the fetch itself, so it is judged after installation: the operation then restores the profile manifest and lockfile, reinstalls the restored lockfile, and reports whether that recovery succeeded; already permitted build-script effects may remain. A dependency the run did not change never blocks an unrelated operation: it stays installed, the run reports a warning naming it, and profile startup denies it. Installation requests with `enabled: false` are checked the same way. Startup checks run independently; see [App boot](../app-boot/README.md#profiles) for range semantics. Version exemptions do not authorize dependency scripts.
+
+An exemption is an exact `package-name@version` mapped to a list of exact DSH runtime versions in the profile's own `compatibility.json`, beside `package.json` and `cordis.patch.yml`. Writing it changes no dependency, no bundle selection, and no patch layer. Neither plugin upgrades nor DSH upgrades inherit permission. Use `plugin_manager` with `list_version_exemptions` to obtain the runtime version and saved grants, then `set_version_exemption` with `target`, `runtimeVersion`, and `enabled`. Granting also requires `acceptRisk: true`, only after warning the user that incompatible plugins may cause crashes or data loss and receiving explicit permission for that pair. The service checks the acknowledgement and versions, not conversation history. Revocation can remove historical runtime grants.
+
+A grant takes effect on the next composition. A live profile recomposes, so the granted plugin mounts in the running session and the result reports `applied`; a startup-only profile keeps its current entries until restart and reports `restart-required`.
+
+The CLI exposes `dsh plugin --profile <profile> version-exemptions`, `allow-version <package@version> --dsh-version <runtime> --accept-risk`, and `revoke-version <package@version> --dsh-version <runtime>`. A grant prints a risk warning before saving. The Web page reports compatibility failures; use the tool or CLI to grant an exemption and retry the original operation.
+
 ### Configuration
 
 | Field | Default | Meaning |
diff --git a/packages/boot/plugin-manager/README.zh.md b/packages/boot/plugin-manager/README.zh.md
index 122ccc9a27..fcf4b6dc69 100644
--- a/packages/boot/plugin-manager/README.zh.md
+++ b/packages/boot/plugin-manager/README.zh.md
@@ -57,6 +57,17 @@ kind: "package-reference"
 
 pnpm 11 拦下依赖脚本时，失败的安装在 `pendingBuilds` 里报告 profile 中所有待决定的包名，包括先前尝试留下的；失败的运行会恢复 `package.json` 与 `pnpm-lock.yaml`，但有意不恢复 pnpm 记录这些名字的 `pnpm-workspace.yaml`。Web 插件页提供**允许这些脚本并重试**；工具可以在用户于对话中批准这些脚本后，通过 `install_bundle` 的 `approvedBuilds` 代为授权。服务只校验待决定的名字，不核实对话中的批准。授权按包名保存在当前 profile，允许以宿主用户的权限执行命令，并在再次安装失败后保留。只能批准当前未决定的名字；已有的拒绝与通配规则不能通过此操作覆盖。`allowBuilds` 里出现 YAML 锚点或别名时拒绝授权。重试保留原来的启用选择。
 
+<a id="version-compatibility-and-exemptions"></a>
+### 版本兼容性与豁免
+
+点名软件包的安装命令（`add`，或带 spec 的 `install`）会在 pnpm 运行前完成检查：本地路径直接读取其 `package.json`，registry spec 通过 pnpm 的 registry 查询得到该范围选中的版本及其声明的 peer。不兼容的 DSH peer 会在 pnpm 运行前使操作失败，因此不会下载任何内容、不会运行构建脚本；调用方随请求提交的构建批准在此检查之前记录，会保留下来。git 或 tarball spec 必须先抓取，因此在安装后才判定：此时操作会恢复 profile 清单与锁文件，并按恢复后的锁文件重新安装，同时报告该恢复是否成功；已获准构建脚本的副作用可能保留。本次运行未改动的依赖不会阻塞无关操作：它保持已安装状态，运行会输出点名它的警告，由 profile 启动拒绝加载。请求 `enabled: false` 的安装同样受检。启动检查独立执行；版本范围语义见 [App boot](../app-boot/README.zh.md#profiles)。版本豁免不授权依赖脚本。
+
+豁免保存在 profile 自己的 `compatibility.json` 中（与 `package.json`、`cordis.patch.yml` 并列），将精确的 `package-name@version` 映射到精确 DSH 运行时版本列表。写豁免不改变依赖、组合包选择或 patch 层。插件升级和 DSH 升级都不继承授权。使用 `plugin_manager` 的 `list_version_exemptions` 获取运行时版本与已有授权，再通过 `set_version_exemption` 提交 `target`、`runtimeVersion` 和 `enabled`。授权还要求 `acceptRisk: true`；只能在警告用户不兼容插件可能导致崩溃或数据丢失，并获得用户对此版本组合的明确许可后传入。服务校验确认参数和版本，不核实对话历史。撤销可以移除历史运行时版本的授权。
+
+授权在下一次组合时生效。在线 profile 会重新组合，被授权的插件会在当前会话中挂载，结果报告 `applied`；仅启动型 profile 在重启前保留当前条目并报告 `restart-required`。
+
+CLI 提供 `dsh plugin --profile <profile> version-exemptions`、`allow-version <package@version> --dsh-version <runtime> --accept-risk` 和 `revoke-version <package@version> --dsh-version <runtime>`。授权会在保存前打印风险警告。Web 页面报告兼容性失败；通过工具或 CLI 添加豁免后，重试原操作。
+
 ### 配置
 
 | 字段 | 默认值 | 含义 |
diff --git a/packages/boot/plugin-manager/src/index.ts b/packages/boot/plugin-manager/src/index.ts
index 818b68ac16..6f5a5cc1c1 100644
--- a/packages/boot/plugin-manager/src/index.ts
+++ b/packages/boot/plugin-manager/src/index.ts
@@ -14,6 +14,8 @@ import { pluginEntryId, readPluginInventory } from '@deepseek-ai/dsh-host-plugin
 import {
   readPluginMeta, readProfileManifest, resolveBundleDir, loadOverlayPatches, composeEntries,
   reconcileProfilePatches, readProfilePatches, OPTIONAL_BUNDLES, bundlePatchPaths,
+  evaluatePluginCompatibility, pluginCompatibilityWarning, readProfileCompatibility, readProfileVersionExemptions,
+  setProfileVersionExemption, PROFILE_COMPATIBILITY_FILENAME,
 } from '@deepseek-ai/dsh-app-boot'
 import type {} from '@deepseek-ai/dsh-hmr'
 import type { ProfileContext, ProfileManifest } from '@deepseek-ai/dsh-app-boot'
@@ -221,6 +223,31 @@ export class PluginManager extends TypertRemoteService {
     }, 'plugin-manager: package cancellation')
   }
 
+  /** Read exact plugin-version exemptions saved in this profile.
+   * @returns Accepted package-name@version keys with the runtime versions they may run on, and any
+   * record or file problem the reader rejected, which the caller reports instead of failing.
+   */
+  @Remote
+  listVersionExemptions(): { exemptions: Record<string, string[]>; warnings: string[] } {
+    const { exemptions, warnings } = readProfileCompatibility(this.profile.dir)
+    return { exemptions, warnings }
+  }
+
+  /** Grant or revoke one exact plugin/runtime exemption and reevaluate live plugins.
+   * @param packageVersion Exact manifest package name followed by @ and its version; never an installation spec or alias.
+   * @param runtimeVersion Exact current DSH version for grants; revocation may name a previous runtime.
+   * @param enabled Whether to grant rather than revoke the exemption.
+   * @param acceptRisk Required true for grants after the user accepts possible crashes and data loss.
+   * @returns Saved and runtime outcomes. Startup-only profiles require restart.
+   */
+  @Remote
+  setVersionExemption(packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk?: boolean): Promise<ChangeResult> {
+    return this.change(result => this.configure(async () => {
+      await setProfileVersionExemption(this.profile.dir, packageVersion, runtimeVersion, enabled, acceptRisk === true)
+      result.warnings = await this.reload()
+    }), { stage: 'enable', target: packageVersion, enabled }, 'bundle')
+  }
+
   /** Read current plugins, including why a row cannot be changed through the profile patch.
    * @returns Current runtime entries with persistent patch targets.
    */
@@ -251,6 +278,7 @@ export class PluginManager extends TypertRemoteService {
   @Remote
   listBundles(): Promise<BundleInfo[]> {
     const manifest = readProfileManifest('dsh', this.profile.dir)
+    const exemptions = readProfileVersionExemptions(this.profile.dir)
     const selected = manifest.dsh?.profile?.bundles ?? []
     const dependencies = Object.keys(manifest.dependencies ?? {})
     const installation = JSON.parse(readFileSync(this.profile.installAnchor, 'utf8')) as InstallationManifest
@@ -269,6 +297,8 @@ export class PluginManager extends TypertRemoteService {
             ...(readOnlyReason === undefined ? {} : { readOnlyReason }), error: { code: 'not-bundle' }, rows: [], overrides: [] })
           continue
         }
+        const compatibility = evaluatePluginCompatibility(info, exemptions)
+        if (compatibility !== undefined && !compatibility.exempted) throw new Error(pluginCompatibilityWarning(compatibility))
         const dir = resolveBundleDir('dsh', name, this.profile.installAnchor, this.profile.dir)
         const meta = readPluginMeta(info.name ?? name, pathToFileURL(join(dir, 'package.json')).href)
         bundles.push({ name, ...(info.version === undefined ? {} : { version: info.version }),
@@ -510,6 +540,8 @@ export class PluginManager extends TypertRemoteService {
         const dir = resolveBundleDir('dsh', name, this.profile.installAnchor, this.profile.dir)
         const manifest = bundleManifest(name, this.profile.dir, this.profile.installAnchor)
         if (manifest?.dsh?.bundle === undefined) throw new ManagementFailure('not-bundle')
+        const compatibility = evaluatePluginCompatibility(manifest, readProfileVersionExemptions(this.profile.dir))
+        if (compatibility !== undefined && !compatibility.exempted) throw new Error(pluginCompatibilityWarning(compatibility))
         for (const file of bundlePatchPaths(dir, manifest.dsh.bundle)) loadOverlayPatches('dsh', file)
       } catch (error) {
         // pnpm has exited by now, so the files it rewrote go back as they were.
@@ -634,6 +666,7 @@ export class PluginManager extends TypertRemoteService {
       execution: 'service', ...this.profile.packageManager ?? { command: this.pnpmCommand },
       signal: signal === undefined ? this.abort.signal : AbortSignal.any([this.abort.signal, signal]),
       outputBytes: this.outputBytes, activateNewBundles: false, idleTimeoutMs: this.idleTimeoutMs,
+      lookupTimeoutMs: this.inspectTimeoutMs,
       onOutput: (text, stream) => {
         this.ownerContext.emit('plugin-manager/install-log', { ...identity, jobId, argv, cwd, stream, text })
       },
@@ -679,10 +712,15 @@ export class PluginManager extends TypertRemoteService {
   private async selectBundle(name: string, enabled: boolean): Promise<void> {
     const manifest = readProfileManifest('dsh', this.profile.dir)
     const previous = manifest.dsh?.profile?.bundles ?? []
-    if ((enabled || !previous.includes(name)) && bundleManifest(name, this.profile.dir, this.profile.installAnchor) === undefined) {
-      throw new ManagementFailure('not-bundle')
+    if (enabled || !previous.includes(name)) {
+      const metadata = bundleManifest(name, this.profile.dir, this.profile.installAnchor)
+      if (metadata === undefined) throw new ManagementFailure('not-bundle')
+      if (enabled) {
+        const compatibility = evaluatePluginCompatibility(metadata, readProfileVersionExemptions(this.profile.dir))
+        if (compatibility !== undefined && !compatibility.exempted) throw new Error(pluginCompatibilityWarning(compatibility))
+        this.bundleRows(name)
+      }
     }
-    if (enabled) this.bundleRows(name)
     if (!enabled && previous.includes(name)) {
       if (this.protectsManager(name)) throw new ManagementFailure('management-required')
     }
@@ -750,7 +788,7 @@ export class PluginManager extends TypertRemoteService {
   }
 
   private diskState(): string {
-    return ['package.json', 'cordis.patch.yml', 'pnpm-workspace.yaml'].map((file) => {
+    return ['package.json', 'cordis.patch.yml', 'pnpm-workspace.yaml', PROFILE_COMPATIBILITY_FILENAME].map((file) => {
       try { return readFileSync(join(this.profile.dir, file), 'utf8') }
       catch (error) {
         if ((error as NodeJS.ErrnoException).code === 'ENOENT') return ''
diff --git a/packages/boot/plugin-manager/src/operations.ts b/packages/boot/plugin-manager/src/operations.ts
index 817a4e2219..160e8714e1 100644
--- a/packages/boot/plugin-manager/src/operations.ts
+++ b/packages/boot/plugin-manager/src/operations.ts
@@ -1,17 +1,21 @@
 /** Shared profile package operations used by dsh plugin and the running manager. */
 import { once } from 'node:events'
-import { existsSync } from 'node:fs'
-import { mkdir, mkdtemp, open } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { mkdir, mkdtemp, open, rm } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
 import { execa } from 'execa'
+import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
 import {
   DEFAULT_PROFILE_BUNDLES, bundlePatchPaths, initProfile, PROFILE_TEMPLATES, readProfileManifest,
-  resolveBundleDir, resolveProfileDir, loadOverlayPatches, type ProfileManifest,
+  resolveBundleDir, resolveProfileDir, loadOverlayPatches, composeEntries, readProfileVersionExemptions,
+  evaluatePluginCompatibility, pluginCompatibilityWarning, type ProfileManifest,
 } from '@deepseek-ai/dsh-app-boot'
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
+import { parseInstallSpec } from './install-spec.ts'
 import { awaitTreeGone, leadsOwnGroup } from './run-tree.ts'
 import type { PackageResult, Registry } from './types.ts'
+export { setProfileVersionExemption, readProfileVersionExemptions } from '@deepseek-ai/dsh-app-boot'
 
 /** Profile and invocation locations supplied by the launcher. */
 export interface PackageOperationContext {
@@ -45,6 +49,8 @@ export interface PackageOperationOptions {
    * with inherited descriptors captures nothing and is never bound.
    */
   idleTimeoutMs?: number
+  /** Bound on the pre-install registry lookup, in milliseconds; without one a fixed bound applies. */
+  lookupTimeoutMs?: number
 }
 
 /** Resolve relative package specs against the caller's directory.
@@ -132,18 +138,112 @@ async function drainWithin(collectors: readonly Promise<void>[], ms: number): Pr
   }
 }
 
+/** Install commands that take the packages to install as positionals. */
+const INSTALL_COMMANDS = new Set(['add', 'install', 'i'])
+
+/** Bound on a pre-install registry lookup when the caller names none. */
+const LOOKUP_TIMEOUT_MS = 20_000
+
+/** Package specs an install command names explicitly, in order. */
+function namedSpecs(args: readonly string[]): string[] {
+  const index = args.findIndex(argument => !argument.startsWith('-'))
+  const command = index < 0 ? undefined : args[index]
+  if (command === undefined || !INSTALL_COMMANDS.has(command)) return []
+  return args.slice(index + 1).filter(argument => !argument.startsWith('-'))
+}
+
+/** The manifest a named spec would install, read without installing it.
+ * A path spec is read from disk. A registry spec asks pnpm's own configuration for the version the
+ * range selects and its peer requirements. A git or tarball spec needs the fetch itself, so the
+ * check after installation is what judges it.
+ * @param dir Profile directory the lookup runs in.
+ * @param spec Anchored install spec.
+ * @param options Pnpm executable, prefix arguments, the caller's bound and signal.
+ * @param environment Environment of the caller's pnpm invocations.
+ * @param flags Flags of the run itself, so the lookup asks the registry that run will use.
+ * @returns The package manifest, or undefined when reading it would need the installation itself.
+ */
+async function namedSpecManifest(
+  dir: string, spec: string, options: PackageOperationOptions, environment: Readonly<Record<string, string | undefined>>,
+  flags: readonly string[],
+): Promise<object | undefined> {
+  const parsed = parseInstallSpec(spec)
+  if (parsed.kind === 'path') {
+    const filename = join(parsed.path, 'package.json')
+    return existsSync(filename) ? JSON.parse(readFileSync(filename, 'utf8')) as object : undefined
+  }
+  if (parsed.kind !== 'registry') return undefined
+  const viewed = await execa(options.command ?? 'pnpm', [
+    ...options.args ?? [], 'view', parsed.spec, 'name', 'version', 'peerDependencies', '--json',
+    ...flags, '--config.fetch-retries=0',
+  ], {
+    cwd: dir, env: environment, extendEnv: false, reject: false, stdin: 'ignore',
+    ...options.signal === undefined ? {} : { cancelSignal: options.signal },
+    timeout: options.lookupTimeoutMs ?? LOOKUP_TIMEOUT_MS,
+  })
+  if (viewed.exitCode !== 0) return undefined
+  const value: unknown = JSON.parse(viewed.stdout)
+  return (Array.isArray(value) ? value.at(-1) : value) as object
+}
+
+/** Missing installed packages are repairable; their absence is part of the before/after comparison. */
+function optionalFile(path: string): string | undefined {
+  try { return readFileSync(path, 'utf8') } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+/** pnpm can install plugins through any direct-dependency field. */
+function directDependencies(manifest: ProfileManifest): Record<string, string> {
+  const extra = manifest as ProfileManifest & { devDependencies?: Record<string, string>; optionalDependencies?: Record<string, string> }
+  return { ...extra.devDependencies, ...manifest.dependencies, ...extra.optionalDependencies }
+}
+
+/** Inspect only plugin rows contributed by the changed bundle, not its dependency closure. */
+function bundleComponentManifests(manifest: ProfileManifest, dir: string, anchor: string): ProfileManifest[] {
+  const bundle = manifest.dsh?.bundle
+  if (bundle === undefined) return []
+  const patches = bundlePatchPaths(dir, bundle).flatMap(file => loadOverlayPatches('dsh', file))
+  const names = new Set<string>()
+  const visit = (rows: EntryOptions[]) => {
+    for (const row of rows) {
+      if (row.group && Array.isArray(row.config)) visit(row.config as EntryOptions[])
+      if (typeof row.name !== 'string' || row.name.startsWith('.') || row.name.startsWith('/') || row.name.includes(':')) continue
+      const parts = row.name.split('/')
+      names.add(parts.slice(0, row.name.startsWith('@') ? 2 : 1).join('/'))
+    }
+  }
+  visit(composeEntries([patches.filter(patch => patch.insert !== undefined)]))
+  return [...names].flatMap((name) => {
+    let packageDir: string
+    try { packageDir = resolveBundleDir('dsh', name, anchor, dir) } catch (error) {
+      // Resolution errors for uninstalled or dynamic rows remain subject to the startup loader's checks.
+      void error
+      return []
+    }
+    return [readProfileManifest('dsh', packageDir)]
+  })
+}
+
 /** Execute pnpm inside a profile whose caller already holds the profile write lock.
+ * Newly installed or updated direct dependencies are checked even when activation is disabled;
+ * an untouched dependency never blocks an unrelated operation and stays denied at startup.
+ * Compatibility denial restores the profile manifest and lockfile, but leaves downloaded modules on disk.
  * @param context Launcher-owned profile and resolution locations.
  * @param args Pnpm arguments, before relative path anchoring.
  * @param options Output, activation and cancellation policy.
  * @returns Exit status, whether the silence bound stopped the run, and the diagnostic path.
- * Service output is bounded; CLI output uses inherited descriptors.
+ * A compatibility denial returns exit code 1. Service output is bounded; CLI output uses inherited descriptors.
  */
 export async function runProfilePnpm(
   context: PackageOperationContext, args: readonly string[], options: PackageOperationOptions,
 ): Promise<PackageResult> {
   const dir = context.dir ?? resolveProfileDir(context.profile, context.home)
   const before = readProfileManifest('dsh', dir)
+  const savedFiles = ['package.json', 'pnpm-lock.yaml'].map(name => ({ path: join(dir, name), text: optionalFile(join(dir, name)) }))
+  const beforeDependencies = directDependencies(before)
+  const installedBefore = new Map(Object.keys(beforeDependencies).map(name => [name, optionalFile(join(dir, 'node_modules', name, 'package.json'))]))
   const logRoot = join(dir, '.plugin-manager', 'logs')
   await mkdir(logRoot, { recursive: true, mode: 0o700 })
   const logDir = await mkdtemp(join(logRoot, 'operation-'))
@@ -151,19 +251,6 @@ export async function runProfilePnpm(
   const log = await open(logPath, 'wx', 0o600)
   let output = Buffer.alloc(0)
   let truncated = false
-  const cancellation = new AbortController()
-  // A service run captures output, so execa terminates the tree it leads when the
-  // run is killed: a lifecycle script outlives the pnpm process that started it.
-  // The CLI keeps the caller's process group, so an interrupt still reaches it.
-  const grouped = leadsOwnGroup(options.execution)
-  const child = execa(options.command ?? 'pnpm', [...options.args ?? [], ...args.map(arg => anchorPathSpec(arg, context.cwd))], {
-    cwd: dir, env: { ...(options.execution === 'cli' ? process.env : scrubbedParentEnv()), ...options.env }, extendEnv: false, reject: false,
-    stdout: options.execution === 'cli' ? 'inherit' : 'pipe',
-    stderr: options.execution === 'cli' ? 'inherit' : 'pipe',
-    killDescendants: options.execution === 'service',
-    buffer: false, stdin: options.execution === 'cli' ? 'inherit' : 'ignore', cancelSignal: options.signal === undefined
-      ? cancellation.signal : AbortSignal.any([cancellation.signal, options.signal]),
-  })
   const append = (bytes: Buffer): void => {
     output = Buffer.concat([output, bytes])
     if (output.length > options.outputBytes) {
@@ -171,6 +258,51 @@ export async function runProfilePnpm(
       output = output.subarray(output.length - options.outputBytes)
     }
   }
+  const environment = { ...(options.execution === 'cli' ? process.env : scrubbedParentEnv()), ...options.env }
+  const restore = async (): Promise<void> => {
+    for (const file of savedFiles) {
+      if (file.text === undefined) await rm(file.path, { force: true })
+      else await writeFileAtomic(file.path, file.text, { mode: 0o600 })
+    }
+  }
+  const rejected = async (warnings: readonly string[], restoration: string): Promise<PackageResult> => {
+    const diagnostic = `\ndsh: installation rejected: ${warnings.join('\n')}\ndsh: ${restoration}.\n`
+    await log.write(diagnostic)
+    options.onOutput?.(diagnostic, 'stderr')
+    append(Buffer.from(diagnostic))
+    await log.close()
+    return { exitCode: 1, output: output.toString('utf8'), truncated, logPath }
+  }
+  // An install command names the packages it adds, so their manifests are read and checked before
+  // pnpm runs: an incompatible version is never installed, and the one already in use keeps working.
+  const preflight: string[] = []
+  const exemptions = readProfileVersionExemptions(dir)
+  // The run's own registry flags, so the lookup asks the registry the installation will use.
+  const registryFlags = args.filter(argument => argument.startsWith('--registry='))
+  for (const raw of namedSpecs(args)) {
+    // A spec whose manifest cannot be read or validated is left to the run itself and to the check
+    // after installation, which reports what it could not validate.
+    try {
+      const manifest = await namedSpecManifest(dir, anchorPathSpec(raw, context.cwd), options, environment, registryFlags)
+      if (manifest === undefined) continue
+      const issue = evaluatePluginCompatibility(manifest, exemptions)
+      if (issue !== undefined && !issue.exempted) preflight.push(pluginCompatibilityWarning(issue))
+    } catch (error) { void error; continue }
+  }
+  if (preflight.length > 0) return rejected(preflight, 'nothing was installed')
+  const cancellation = new AbortController()
+  // A service run captures output, so execa terminates the tree it leads when the
+  // run is killed: a lifecycle script outlives the pnpm process that started it.
+  // The CLI keeps the caller's process group, so an interrupt still reaches it.
+  const grouped = leadsOwnGroup(options.execution)
+  const child = execa(options.command ?? 'pnpm', [...options.args ?? [], ...args.map(arg => anchorPathSpec(arg, context.cwd))], {
+    cwd: dir, env: environment, extendEnv: false, reject: false,
+    stdout: options.execution === 'cli' ? 'inherit' : 'pipe',
+    stderr: options.execution === 'cli' ? 'inherit' : 'pipe',
+    killDescendants: options.execution === 'service',
+    buffer: false, stdin: options.execution === 'cli' ? 'inherit' : 'ignore', cancelSignal: options.signal === undefined
+      ? cancellation.signal : AbortSignal.any([cancellation.signal, options.signal]),
+  })
   let writes = Promise.resolve()
   /** `settled` records that the process outcome is known; `stalled` that the silence bound stopped the run. */
   const control = { settled: false, stalled: false }
@@ -268,8 +400,53 @@ export async function runProfilePnpm(
       output = Buffer.from(diagnostic).subarray(0, options.outputBytes)
     }
     // A terminated run's exit status says nothing about what it wrote, so it never reconciles the selection.
-    if (exitCode === 0 && !control.stalled && options.activateNewBundles !== false) {
-      await reconcile(before, dir, context.installAnchor, options)
+    if (exitCode === 0 && !control.stalled) {
+      const after = readProfileManifest('dsh', dir)
+      const warnings: string[] = []
+      for (const [name, spec] of Object.entries(directDependencies(after))) {
+        const packageDir = join(dir, 'node_modules', name)
+        const installed = optionalFile(join(packageDir, 'package.json'))
+        if (installed === undefined) continue
+        // A dependency this run did not touch never blocks an unrelated operation; profile startup denies it.
+        const untouched = beforeDependencies[name] === spec && installedBefore.get(name) === installed
+        const found: string[] = []
+        try {
+          const manifest = readProfileManifest('dsh', packageDir)
+          for (const candidate of [manifest, ...bundleComponentManifests(manifest, packageDir, context.installAnchor)]) {
+            const issue = evaluatePluginCompatibility(candidate, readProfileVersionExemptions(dir))
+            if (issue !== undefined && !issue.exempted) found.push(pluginCompatibilityWarning(issue))
+          }
+        } catch (error) {
+          found.push(`Cannot validate installed package ${name}: ${String(error)}`)
+        }
+        if (found.length === 0) continue
+        if (!untouched) warnings.push(...found)
+        else {
+          const notice = `\ndsh: warning: ${found.join('\n')}\ndsh: it stays installed but profile startup denies it until you grant an exemption for those exact versions.\n`
+          await log.write(notice)
+          options.onOutput?.(notice, 'stderr')
+        }
+      }
+      if (warnings.length > 0) {
+        // A bundle component's peers need installed contents, so this rejection lands after pnpm
+        // replaced the tree: restore the files, then reinstall the restored lockfile so the version
+        // that worked before this run keeps loading.
+        await restore()
+        const repaired = await execa(options.command ?? 'pnpm', [...options.args ?? [], 'install', '--frozen-lockfile'], {
+          cwd: dir, env: environment, extendEnv: false, reject: false, stdin: 'ignore',
+          ...options.idleTimeoutMs === undefined ? {} : { timeout: options.idleTimeoutMs },
+        })
+        exitCode = 1
+        const restoration = repaired.exitCode === 0
+          ? 'restored package.json, pnpm-lock.yaml, and node_modules'
+          : "restored package.json and pnpm-lock.yaml, but node_modules could not be reinstalled; run 'dsh plugin install'"
+        const diagnostic = `\ndsh: installation rejected: ${warnings.join('\n')}\ndsh: ${restoration}.\n`
+        await log.write(diagnostic)
+        options.onOutput?.(diagnostic, 'stderr')
+        append(Buffer.from(diagnostic))
+      } else if (options.activateNewBundles !== false) {
+        await reconcile(before, dir, context.installAnchor, options)
+      }
     }
   } finally {
     control.settled = true
diff --git a/packages/boot/plugin-manager/src/tools.ts b/packages/boot/plugin-manager/src/tools.ts
index 2b65dd8bc2..df9b0a200e 100644
--- a/packages/boot/plugin-manager/src/tools.ts
+++ b/packages/boot/plugin-manager/src/tools.ts
@@ -7,6 +7,7 @@ import type {} from '@deepseek-ai/dsh-user-approval'
 import { approveEscalation } from '@deepseek-ai/dsh-sandbox'
 import type { PluginEntryId } from './types.ts'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { getDshRuntimeVersion } from '@deepseek-ai/dsh-app-boot'
 
 /** Required services for the management tool. */
 export const inject = ['tools', 'pluginManager', 'sandboxPolicy']
@@ -17,11 +18,13 @@ export const inject = ['tools', 'pluginManager', 'sandboxPolicy']
 export function apply(ctx: Context): void {
   ctx.tools.register(defineTool({
     name: 'plugin_manager',
-    description: 'List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart.',
+    description: 'List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart. Incompatible DSH peer dependencies block installation and activation. Version exemptions risk crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.',
     parameters: {
-      action: { type: 'string', required: true, enum: ['list_plugins', 'list_bundles', 'set_plugin', 'set_bundle', 'install_bundle', 'remove_bundle'], description: 'Management operation.' },
+      action: { type: 'string', required: true, enum: ['list_plugins', 'list_bundles', 'set_plugin', 'set_bundle', 'install_bundle', 'remove_bundle', 'list_version_exemptions', 'set_version_exemption'], description: 'Management operation.' },
       target: { type: 'string', description: 'Plugin entry id, bundle package name, or installation spec, according to action.' },
-      enabled: { type: 'boolean', description: 'Required for set operations; defaults to true for installation.' },
+      enabled: { type: 'boolean', description: 'Required for set operations; defaults to true for installation. For set_version_exemption, true grants and false revokes.' },
+      runtimeVersion: { type: 'string', description: 'For set_version_exemption: exact DSH version from list_version_exemptions. Target must be the manifest package-name@version, not an alias or version range.' },
+      acceptRisk: { type: 'boolean', description: 'For granting an exemption: true only after warning the user about possible crashes and data loss and receiving explicit permission for this exact plugin/runtime pair. General installation permission is not enough.' },
       approvedBuilds: { type: 'array', items: { type: 'string' }, description: 'For install_bundle: pass names from pendingBuilds only after the user explicitly approves running their install scripts in the conversation. This grants persistent permission for this profile.' },
       registry: { type: 'string', description: 'For install_bundle: the npm registry URL asked first, when the user names one; otherwise the configured registry is asked, and its configured fallbacks while a registry is unreachable.' },
       offset: { type: 'number', description: 'Zero-based list offset; defaults to 0.' },
@@ -41,6 +44,13 @@ export function apply(ctx: Context): void {
       exec.signal.throwIfAborted()
       const manager = ctx.pluginManager
       switch (args.action) {
+        case 'list_version_exemptions':
+          return JSON.stringify({ runtimeVersion: getDshRuntimeVersion(), ...manager.listVersionExemptions() })
+        case 'set_version_exemption':
+          if (args.target === undefined || args.runtimeVersion === undefined || args.enabled === undefined) {
+            throw new Error('target package-name@version, runtimeVersion, and enabled are required')
+          }
+          return JSON.stringify(await manager.setVersionExemption(args.target, args.runtimeVersion, args.enabled, args.acceptRisk))
         case 'list_plugins':
         case 'list_bundles': {
           const offset = args.offset ?? 0
diff --git a/packages/boot/plugin-manager/tests/manager.spec.ts b/packages/boot/plugin-manager/tests/manager.spec.ts
index d80755bba2..b064b95e64 100644
--- a/packages/boot/plugin-manager/tests/manager.spec.ts
+++ b/packages/boot/plugin-manager/tests/manager.spec.ts
@@ -12,7 +12,7 @@ import type { Context } from '@deepseek-ai/cordis'
 import { expect, it, onTestFinished, vi } from 'vitest'
 import {
   boot, composeEntries, initProfile, loadProfileDirectory, readProfilePatches, readProfileManifest,
-  reconcileProfilePatches, OPTIONAL_BUNDLES, PluginPackages, readPluginMeta,
+  reconcileProfilePatches, OPTIONAL_BUNDLES, PluginPackages, readPluginMeta, getDshRuntimeVersion,
   type ProfileContext, type RuntimeResolution,
 } from '@deepseek-ai/dsh-app-boot'
 import PluginManager, { type Config, type PluginChange, type PluginInstallLogChunk, type PluginInstallProgress, type PluginInstallRequestId } from '../src/index.ts'
@@ -430,6 +430,7 @@ it('retains installed dependencies when toggling a bundle and appends it when re
   bundle('third', [])
   await manager.setBundleEnabled('third', true)
   expect(await manager.setBundleEnabled('extra', false)).toMatchObject({ changed: true, application: 'applied' })
+  expect(await manager.setBundleEnabled('extra', false)).toMatchObject({ changed: false, application: 'applied' })
   expect(readProfileManifest('test', dir).dependencies).toEqual({ extra: '1.0.0' })
   expect((await manager.listPlugins()).some(row => row.patchId === 'managed')).toBe(false)
   await manager.setBundleEnabled('extra', true)
@@ -1322,3 +1323,59 @@ it('answers the configured registries in pnpm\'s comparison form with what pnpm
   expect(() => PluginManager.Config({ registry: 'npm.corp.example' })).toThrow()
   expect(() => PluginManager.Config({ fallbackRegistries: ['ftp://npm.corp.example/'] })).toThrow()
 })
+
+it.each(['live', 'startup'] as const)('requires exact risk acknowledgement and preserves exemptions in a %s profile', async (mode) => {
+  const { manager, dir, ctx } = await fixture(mode, false, undefined, {}, undefined, (dir) => {
+    const file = join(dir, 'node_modules', 'extra', 'package.json')
+    const metadata = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>
+    writeFileSync(file, JSON.stringify({ ...metadata, peerDependencies: { '@deepseek-ai/dsh': '999.0.0' } }))
+  })
+  const runtime = getDshRuntimeVersion()
+  const managed = () => [...ctx.loader.entries()].find(entry => entry.id === 'include:managed')
+  // Admission disables the incompatible row where it is composed: the Loader keeps its entry and gives it no fiber.
+  expect(managed()?.disabled).toBe(true)
+  expect((await manager.listBundles()).find(bundle => bundle.name === 'extra')?.error?.diagnostic).toContain('crashes or data loss')
+  expect(await manager.setBundleEnabled('extra', true)).toMatchObject({ changed: false, application: 'failed' })
+  expect(await manager.setVersionExemption('extra@1.0.0', runtime, true)).toMatchObject({ changed: false, application: 'failed' })
+  expect(manager.listVersionExemptions()).toEqual({ exemptions: {}, warnings: [] })
+  expect(existsSync(join(dir, 'compatibility.json'))).toBe(false)
+  expect(await manager.setVersionExemption('extra@1.0.0', runtime, true, true)).toMatchObject({
+    changed: true, application: mode === 'live' ? 'applied' : 'restart-required',
+  })
+  expect(manager.listVersionExemptions()).toEqual({ exemptions: { 'extra@1.0.0': [runtime] }, warnings: [] })
+  // The grant is persisted only in the profile's compatibility file, never in its package manifest.
+  expect(JSON.parse(readFileSync(join(dir, 'compatibility.json'), 'utf8'))).toEqual({ 'extra@1.0.0': [runtime] })
+  expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['core', 'extra'])
+  // `setVersionExemption` reconciles the profile itself, so a live tree re-admits the row here;
+  // no manifest watch or Loader instrumentation participates. A startup-only profile keeps it disabled until restart.
+  if (mode === 'live') expect(managed()?.fiber?.state).toBe(2)
+  else expect(managed()?.disabled).toBe(true)
+  expect(await manager.setVersionExemption('extra@1.0.0', runtime, false)).toMatchObject({ changed: true })
+  expect(manager.listVersionExemptions()).toEqual({ exemptions: {}, warnings: [] })
+  expect(JSON.parse(readFileSync(join(dir, 'compatibility.json'), 'utf8'))).toEqual({})
+  if (mode === 'live') expect(managed()?.disabled).toBe(true)
+})
+
+it.each([false, true])('rechecks installed bundle peers before accepting a disabled installation (exempted=%s)', async (exempted) => {
+  const { manager, dir, bundle } = await fixture()
+  if (exempted) await manager.setVersionExemption('incompatible@1.0.0', getDshRuntimeVersion(), true, true)
+  const before = readFileSync(join(dir, 'package.json'), 'utf8')
+  const install = vi.spyOn(operations, 'runProfilePnpm').mockImplementation(async () => {
+    bundle('incompatible', [])
+    const file = join(dir, 'node_modules', 'incompatible', 'package.json')
+    const metadata = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>
+    writeFileSync(file, JSON.stringify({ ...metadata, peerDependencies: { '@deepseek-ai/dsh': '<0.0.0' } }))
+    const profile = readProfileManifest('test', dir)
+    profile.dependencies = { ...profile.dependencies, incompatible: '1.0.0' }
+    writeFileSync(join(dir, 'package.json'), JSON.stringify(profile))
+    return { exitCode: 0, output: 'installed', truncated: false, logPath: join(dir, 'pnpm.log') }
+  })
+  onTestFinished(() => { install.mockRestore() })
+  const result = await manager.installBundle('incompatible', { enabled: false })
+  expect(result).toMatchObject({ application: exempted ? 'applied' : 'failed', changed: exempted })
+  if (!exempted) {
+    expect(result.error?.diagnostic).toContain('incompatible@1.0.0')
+    expect(readFileSync(join(dir, 'package.json'), 'utf8')).toBe(before)
+  }
+  expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['core', 'extra'])
+})
diff --git a/packages/boot/plugin-manager/tests/operations-process.spec.ts b/packages/boot/plugin-manager/tests/operations-process.spec.ts
index d4ad5f28ce..1b228cd4c7 100644
--- a/packages/boot/plugin-manager/tests/operations-process.spec.ts
+++ b/packages/boot/plugin-manager/tests/operations-process.spec.ts
@@ -111,7 +111,7 @@ function fixture(child: string, descendant: string) {
 describe.skipIf(process.platform === 'win32')('a run with descendants', () => {
   it('settles a run whose pipes a descendant keeps open', async () => {
     const { context, pidFile, options } = fixture(DRAIN_CHILD, HOLDER_SCRIPT)
-    const outcome = await runProfilePnpm(context, ['add', 'held'], options)
+    const outcome = await runProfilePnpm(context, ['add', './held'], options)
     const descendant = await readPid(pidFile)
     expect(outcome).toMatchObject({ exitCode: 0 })
     expect(outcome.output).toContain('dsh: pnpm output was cut short after its process exited')
@@ -121,7 +121,7 @@ describe.skipIf(process.platform === 'win32')('a run with descendants', () => {
 
   it('surfaces an output consumer failure that the bounded drain cuts short', async () => {
     const { context, options } = fixture(DRAIN_CHILD, HOLDER_SCRIPT)
-    const run = runProfilePnpm(context, ['add', 'held'], {
+    const run = runProfilePnpm(context, ['add', './held'], {
       ...options,
       onOutput() { throw new Error('output destination closed') },
     })
@@ -130,7 +130,7 @@ describe.skipIf(process.platform === 'win32')('a run with descendants', () => {
 
   it('stops the whole tree of a stalled run before returning', async () => {
     const { context, pidFile, lateFile, options } = fixture(STALLED_CHILD, LATE_SCRIPT)
-    const outcome = await runProfilePnpm(context, ['add', 'stalled'], { ...options, idleTimeoutMs: 300 })
+    const outcome = await runProfilePnpm(context, ['add', './stalled'], { ...options, idleTimeoutMs: 300 })
     const descendant = await readPid(pidFile)
     expect(outcome).toMatchObject({ timedOut: true })
     // The descendant is gone, so the marker it would have written 1.5s in never appears.
diff --git a/packages/boot/plugin-manager/tests/operations.spec.ts b/packages/boot/plugin-manager/tests/operations.spec.ts
index 190f567cf9..740d2abf31 100644
--- a/packages/boot/plugin-manager/tests/operations.spec.ts
+++ b/packages/boot/plugin-manager/tests/operations.spec.ts
@@ -1,17 +1,19 @@
 /** The CLI and manager share package reconciliation, path anchoring and diagnostics. */
 import { EventEmitter } from 'node:events'
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { PassThrough } from 'node:stream'
 import { expect, it, onTestFinished, vi } from 'vitest'
-import { initProfile, readProfileManifest } from '@deepseek-ai/dsh-app-boot'
+import { getDshRuntimeVersion, initProfile, readProfileManifest } from '@deepseek-ai/dsh-app-boot'
 import { anchorPathSpec, readProfileRegistry, runPluginCommand, runProfilePnpm, viewProfilePackage } from '../src/operations.ts'
 
-/** What execa resolves for a run that settled. */
+/** What execa resolves for a run that settled, including the buffered output the pre-install lookup is read for. */
 interface FakeOutcome {
   exitCode: number | undefined
   failed: boolean
+  stdout?: string
+  stderr?: string
   code?: string
   shortMessage?: string
 }
@@ -24,17 +26,55 @@ interface FakeChild {
   kill?: () => boolean
 }
 
+/** What each kind of pnpm invocation changes in the profile and what it answers. */
+interface FakePnpm {
+  /** What the run changes in the profile. */
+  mutate: (dir: string) => void
+  /** The run's exit code and captured output. */
+  exitCode: number
+  output: string
+  /** Exit code of the `install --frozen-lockfile` run that repairs a post-install refusal. */
+  repairExit: number
+  /** What the pre-install `pnpm view` lookup answers for one spec; `{}` declares no peers. */
+  view: (spec: string) => { exitCode: number; stdout: string }
+  /** The specs the pre-install check asked `pnpm view` about, in order. */
+  views: string[]
+}
+
 const command = vi.hoisted(() => ({ run: vi.fn<(...args: unknown[]) => Promise<FakeOutcome> & FakeChild>() }))
 vi.mock('execa', () => ({ execa: (...args: unknown[]) => command.run(...args) }))
 
 function fixture() {
   const home = mkdtempSync(join(tmpdir(), 'manager-pnpm-'))
-  onTestFinished(() => { command.run.mockReset(); rmSync(home, { recursive: true, force: true }) })
   const dir = join(home, 'profiles', 'test')
   const installAnchor = join(home, 'package.json')
   writeFileSync(installAnchor, '{}\n')
   initProfile(dir, [])
-  return { home, dir, context: { home, profile: 'test', installAnchor, cwd: home } }
+  // One pnpm command per operation: a lookup that only reads the registry, the frozen install that
+  // repairs a post-install refusal, and the run itself, which applies the test's mutation and exit code.
+  const pnpm: FakePnpm = {
+    mutate: () => {},
+    exitCode: 0,
+    output: '',
+    repairExit: 0,
+    view: () => ({ exitCode: 0, stdout: '{}' }),
+    views: [],
+  }
+  command.run.mockImplementation((...call: unknown[]) => {
+    const argv = call[1] as readonly string[]
+    const runDir = (call[2] as { cwd: string }).cwd
+    const lookup = argv.indexOf('view')
+    if (lookup !== -1) {
+      const spec = argv[lookup + 1] as string
+      pnpm.views.push(spec)
+      const answer = pnpm.view(spec)
+      return result(answer.exitCode, answer.stdout)
+    }
+    if (argv.includes('--frozen-lockfile')) return result(pnpm.repairExit, '')
+    return result(pnpm.exitCode, pnpm.output, () => { pnpm.mutate(runDir) })
+  })
+  onTestFinished(() => { command.run.mockReset(); rmSync(home, { recursive: true, force: true }) })
+  return { home, dir, context: { home, profile: 'test', installAnchor, cwd: home }, pnpm }
 }
 
 function result(
@@ -48,7 +88,7 @@ function result(
     mutate()
     stdout.end(output)
     stderr.end()
-    return { exitCode, failed: exitCode !== 0, ...details }
+    return { exitCode, failed: exitCode !== 0, stdout: output, stderr: '', ...details }
   })
   // A launch failure reports on the raw child, which never emits an exit; anything else exits once execa's promise settles.
   // Both arrive on a macrotask, so a fixture built before the run still reaches the listener the run attaches.
@@ -117,6 +157,350 @@ function install(dir: string, name: string) {
   writeFileSync(join(dir, 'package.json'), JSON.stringify(manifest))
 }
 
+function installGuarded(dir: string, dependency: string, name = dependency, version = '1.0.0', peer = '>=999.0.0') {
+  install(dir, dependency)
+  writeFileSync(join(dir, 'node_modules', dependency, 'package.json'), JSON.stringify({
+    name, version, peerDependencies: { '@deepseek-ai/dsh-app-boot': peer }, dsh: { bundle: { patch: './cordis.patch.yml' } },
+  }))
+}
+
+/** A path spec whose manifest declares a peer requirement the running dsh does not satisfy. */
+function writePathSpec(home: string, peer: string): void {
+  mkdirSync(join(home, 'plugin'), { recursive: true })
+  writeFileSync(join(home, 'plugin', 'package.json'), JSON.stringify({
+    name: 'plugin', version: '1.0.0', peerDependencies: { '@deepseek-ai/dsh': peer },
+  }))
+}
+
+it.each([
+  { form: 'a relative path', spec: () => './plugin' },
+  { form: 'a file: path', spec: () => 'file:./plugin' },
+  { form: 'a link: path', spec: () => 'link:./plugin' },
+  { form: 'an absolute path', spec: (home: string) => join(home, 'plugin') },
+])('rejects an incompatible $form before pnpm runs and leaves both profile files alone', async ({ spec }) => {
+  const { home, dir, context } = fixture()
+  writePathSpec(home, '999.0.0')
+  const manifestBefore = readFileSync(join(dir, 'package.json'), 'utf8')
+  writeFileSync(join(dir, 'pnpm-lock.yaml'), 'original-lock\n')
+  const messages: string[] = []
+  const outcome = await runProfilePnpm(context, ['add', spec(home)], {
+    execution: 'service', outputBytes: 8192, onOutput: (text) => { messages.push(text) },
+  })
+  expect(outcome.exitCode).toBe(1)
+  expect(outcome.output).toContain('installation rejected')
+  expect(outcome.output).toContain('plugin@1.0.0')
+  expect(outcome.output).toContain('nothing was installed')
+  expect(messages.join('')).toContain('nothing was installed')
+  expect(readFileSync(outcome.logPath, 'utf8')).toContain('plugin@1.0.0')
+  // The spec was read from disk, so no pnpm invocation exists to install anything.
+  expect(command.run).not.toHaveBeenCalled()
+  expect(existsSync(join(dir, 'node_modules'))).toBe(false)
+  expect(readFileSync(join(dir, 'package.json'), 'utf8')).toBe(manifestBefore)
+  expect(readFileSync(join(dir, 'pnpm-lock.yaml'), 'utf8')).toBe('original-lock\n')
+})
+
+it.each(['plugin@1.0.0', '@scope/plugin@1.0.0'])('rejects the registry spec %s the pre-install lookup denies, without installing it', async (spec) => {
+  const { dir, context, pnpm } = fixture()
+  const name = spec.slice(0, spec.lastIndexOf('@'))
+  pnpm.view = () => ({
+    exitCode: 0,
+    stdout: JSON.stringify({ name, version: '1.0.0', peerDependencies: { '@deepseek-ai/dsh': '999.0.0' } }),
+  })
+  const manifestBefore = readFileSync(join(dir, 'package.json'), 'utf8')
+  const outcome = await runProfilePnpm(context, ['add', spec], { execution: 'service', outputBytes: 8192 })
+  expect(outcome).toMatchObject({ exitCode: 1 })
+  expect(outcome.output).toContain('installation rejected')
+  expect(outcome.output).toContain(`${name}@1.0.0`)
+  expect(outcome.output).toContain('nothing was installed')
+  // The lookup is the only pnpm invocation: the refused spec never reached an install.
+  expect(pnpm.views).toEqual([spec])
+  expect(command.run).toHaveBeenCalledTimes(1)
+  expect(command.run.mock.calls[0]?.[1] as readonly string[]).toContain('view')
+  expect(existsSync(join(dir, 'node_modules'))).toBe(false)
+  expect(readFileSync(join(dir, 'package.json'), 'utf8')).toBe(manifestBefore)
+})
+
+it('reads the last match when the registry lookup answers with several versions', async () => {
+  const { context, pnpm } = fixture()
+  pnpm.view = () => ({
+    exitCode: 0,
+    stdout: JSON.stringify([
+      { name: 'plugin', version: '1.0.0' },
+      { name: 'plugin', version: '2.0.0', peerDependencies: { '@deepseek-ai/dsh': '999.0.0' } },
+    ]),
+  })
+  const outcome = await runProfilePnpm(context, ['add', 'plugin@^2', '--registry=https://registry.example'], {
+    execution: 'service', outputBytes: 8192, lookupTimeoutMs: 5_000, signal: new AbortController().signal,
+  })
+  expect(outcome).toMatchObject({ exitCode: 1 })
+  expect(outcome.output).toContain('plugin@2.0.0')
+  expect(pnpm.views).toEqual(['plugin@^2'])
+  // The lookup asks the registry the installation would use.
+  expect(command.run.mock.calls[0]?.[1] as readonly string[]).toContain('--registry=https://registry.example')
+  expect(command.run).toHaveBeenCalledTimes(1)
+})
+
+it('runs an invocation that names no command without a registry lookup', async () => {
+  const { context, pnpm } = fixture()
+  expect(await runProfilePnpm(context, ['--version'], { execution: 'service', outputBytes: 8192 }))
+    .toMatchObject({ exitCode: 0 })
+  expect(pnpm.views).toEqual([])
+})
+
+it('installs an incompatible path spec the profile exempts', async () => {
+  const { home, dir, context, pnpm } = fixture()
+  writePathSpec(home, '999.0.0')
+  writeFileSync(join(dir, 'compatibility.json'), JSON.stringify({ 'plugin@1.0.0': [getDshRuntimeVersion()] }) + '\n')
+  pnpm.mutate = (target) => {
+    install(target, 'plugin')
+    writeFileSync(join(target, 'node_modules', 'plugin', 'package.json'), JSON.stringify({
+      name: 'plugin', version: '1.0.0', peerDependencies: { '@deepseek-ai/dsh': '999.0.0' },
+      dsh: { bundle: { patch: './cordis.patch.yml' } },
+    }))
+  }
+  expect(await runProfilePnpm(context, ['add', './plugin'], { execution: 'service', outputBytes: 8192 }))
+    .toMatchObject({ exitCode: 0 })
+  // A path spec never needs a registry lookup, and the exemption covers the installed manifest too.
+  expect(pnpm.views).toEqual([])
+  expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['plugin'])
+})
+
+it('installs a compatible path spec', async () => {
+  const { home, dir, context, pnpm } = fixture()
+  writePathSpec(home, '*')
+  pnpm.mutate = (target) => { install(target, 'plugin') }
+  expect(await runProfilePnpm(context, ['add', './plugin'], { execution: 'service', outputBytes: 8192 }))
+    .toMatchObject({ exitCode: 0 })
+  expect(pnpm.views).toEqual([])
+  expect(command.run).toHaveBeenCalledTimes(1)
+  expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['plugin'])
+})
+
+it('runs the install with the caller\'s flags and its path specs anchored', async () => {
+  const { context, pnpm } = fixture()
+  pnpm.mutate = (target) => { install(target, 'extra') }
+  expect(await runProfilePnpm(context, ['add', './extra', '--ignore-scripts'], {
+    execution: 'service', outputBytes: 8192, activateNewBundles: false,
+  })).toMatchObject({ exitCode: 0 })
+  expect(command.run.mock.calls[0]?.[1]).toEqual(['add', join(context.cwd, 'extra'), '--ignore-scripts'])
+})
+
+it.each([
+  { answer: 'a failing lookup', view: { exitCode: 1, stdout: '' } },
+  { answer: 'an unparsable answer', view: { exitCode: 0, stdout: 'ERR_PNPM_UNEXPECTED' } },
+])('continues to the install after $answer', async ({ view }) => {
+  const { dir, context, pnpm } = fixture()
+  pnpm.view = () => view
+  pnpm.mutate = (target) => { install(target, 'plugin') }
+  expect(await runProfilePnpm(context, ['add', 'plugin'], { execution: 'service', outputBytes: 8192 }))
+    .toMatchObject({ exitCode: 0 })
+  // The lookup could not judge the spec, so the run itself is what installs and checks it.
+  expect(pnpm.views).toEqual(['plugin'])
+  expect(command.run).toHaveBeenCalledTimes(2)
+  expect(command.run.mock.lastCall?.[1]).toEqual(['add', 'plugin'])
+  expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['plugin'])
+})
+
+it.each(['github:owner/repo', 'https://example.com/plugin.tgz'])(
+  'reaches the install for %s without asking the registry', async (spec) => {
+    const { context, pnpm } = fixture()
+    expect(await runProfilePnpm(context, ['add', spec], { execution: 'service', outputBytes: 8192 }))
+      .toMatchObject({ exitCode: 0 })
+    expect(pnpm.views).toEqual([])
+    expect(command.run).toHaveBeenCalledTimes(1)
+    expect(command.run.mock.calls[0]?.[1]).toEqual(['add', spec])
+  })
+
+it('makes no registry lookup for commands that are not installs', async () => {
+  const { context, pnpm } = fixture()
+  for (const args of [['update'], ['remove', 'plugin'], ['list'], ['approve-builds']]) {
+    expect(await runProfilePnpm(context, args, { execution: 'service', outputBytes: 8192 }))
+      .toMatchObject({ exitCode: 0 })
+  }
+  expect(pnpm.views).toEqual([])
+  expect(command.run).toHaveBeenCalledTimes(4)
+})
+
+it.each([true, false])('rejects incompatible installed manifests before activation (%s) and restores exact profile files', async (activateNewBundles) => {
+  const { dir, context, pnpm } = fixture()
+  const manifestBefore = readFileSync(join(dir, 'package.json'), 'utf8')
+  writeFileSync(join(dir, 'pnpm-lock.yaml'), 'original-lock\n')
+  const messages: string[] = []
+  // Only the installed manifest carries the incompatibility, so it is the post-install check that refuses it.
+  pnpm.mutate = (target) => {
+    installGuarded(target, 'incompatible')
+    writeFileSync(join(target, 'pnpm-lock.yaml'), 'changed-lock\n')
+  }
+  const outcome = await runProfilePnpm(context, ['add', 'incompatible'], {
+    execution: 'service', outputBytes: 8192, activateNewBundles, onOutput: (text) => { messages.push(text) },
+  })
+  expect(outcome.exitCode).toBe(1)
+  expect(outcome.output).toContain('incompatible@1.0.0')
+  expect(outcome.output).toContain('installation rejected')
+  expect(readFileSync(outcome.logPath, 'utf8')).toContain('incompatible@1.0.0')
+  expect(messages.join('')).toContain('installation rejected')
+  expect(readFileSync(join(dir, 'package.json'), 'utf8')).toBe(manifestBefore)
+  expect(readFileSync(join(dir, 'pnpm-lock.yaml'), 'utf8')).toBe('original-lock\n')
+  // The refused run replaced the installed tree, so the restored lockfile is reinstalled.
+  expect(command.run).toHaveBeenLastCalledWith(expect.anything(), ['install', '--frozen-lockfile'], expect.anything())
+  expect(outcome.output).toContain('and node_modules')
+})
+
+it('reports an unrepaired node_modules when the restoring install fails', async () => {
+  const { context, pnpm } = fixture()
+  pnpm.mutate = (target) => { installGuarded(target, 'incompatible') }
+  pnpm.repairExit = 1
+  const outcome = await runProfilePnpm(context, ['add', 'incompatible'], {
+    execution: 'service', outputBytes: 8192, idleTimeoutMs: 5_000,
+  })
+  expect(outcome).toMatchObject({ exitCode: 1 })
+  expect(outcome.output).toContain('node_modules could not be reinstalled')
+  expect(outcome.output).toContain("run 'dsh plugin install'")
+})
+
+it('detects a version update that keeps the dependency spec and removes a lockfile the run created', async () => {
+  const { dir, context, pnpm } = fixture()
+  // The installed tree holds an accepted generation of the dependency the profile already selects.
+  installGuarded(dir, 'updated', 'updated', '1.0.0', '*')
+  const before = readFileSync(join(dir, 'package.json'), 'utf8')
+  // `pnpm update` keeps the manifest spec and replaces only the installed contents.
+  pnpm.mutate = (target) => {
+    writeFileSync(join(target, 'node_modules', 'updated', 'package.json'), JSON.stringify({
+      name: 'updated', version: '2.0.0', peerDependencies: { '@deepseek-ai/dsh-app-boot': '>=999.0.0' },
+      dsh: { bundle: { patch: './cordis.patch.yml' } },
+    }))
+    writeFileSync(join(target, 'pnpm-lock.yaml'), 'changed-lock\n')
+  }
+  const outcome = await runProfilePnpm(context, ['update'], { execution: 'service', outputBytes: 8192 })
+  expect(outcome).toMatchObject({ exitCode: 1 })
+  expect(outcome.output).toContain('updated@2.0.0')
+  expect(readFileSync(join(dir, 'package.json'), 'utf8')).toBe(before)
+  // The run created the lockfile, so the refusal removes it instead of restoring one.
+  expect(existsSync(join(dir, 'pnpm-lock.yaml'))).toBe(false)
+})
+
+it('does not fail an unrelated installation on an untouched incompatible dependency', async () => {
+  const { context, dir, pnpm } = fixture()
+  installGuarded(dir, 'incompatible')
+  const messages: string[] = []
+  pnpm.mutate = (target) => { install(target, 'unrelated') }
+  expect(await runProfilePnpm(context, ['add', 'unrelated'], {
+    execution: 'service', outputBytes: 8192, onOutput: (text) => { messages.push(text) },
+  })).toMatchObject({ exitCode: 0 })
+  expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['unrelated'])
+  expect(messages.join('')).toContain('startup denies it')
+})
+
+it('installs a dependency whose installed manifest declares compatible peers', async () => {
+  const { dir, context, pnpm } = fixture()
+  pnpm.mutate = (target) => {
+    install(target, 'plugin')
+    writeFileSync(join(target, 'node_modules', 'plugin', 'package.json'), JSON.stringify({
+      name: 'plugin', version: '1.0.0', peerDependencies: { '@deepseek-ai/dsh': '*' },
+      dsh: { bundle: { patch: './cordis.patch.yml' } },
+    }))
+  }
+  expect(await runProfilePnpm(context, ['add', 'plugin'], { execution: 'service', outputBytes: 8192 }))
+    .toMatchObject({ exitCode: 0 })
+  expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['plugin'])
+})
+
+it.each([
+  { key: 'actual@1.0.0', runtime: 'current', exitCode: 0 },
+  { key: 'alias@1.0.0', runtime: 'current', exitCode: 1 },
+  { key: 'actual@2.0.0', runtime: 'current', exitCode: 1 },
+  { key: 'actual@1.0.0', runtime: '999.0.0', exitCode: 1 },
+])('matches exemptions to the actual alias manifest and exact versions: $key / $runtime', async ({ key, runtime, exitCode }) => {
+  const { dir, context, pnpm } = fixture()
+  writeFileSync(join(dir, 'compatibility.json'), JSON.stringify({ [key]: [runtime === 'current' ? getDshRuntimeVersion() : runtime] }) + '\n')
+  pnpm.mutate = (target) => { installGuarded(target, 'alias', 'actual') }
+  expect(await runProfilePnpm(context, ['add', 'alias@npm:actual@1.0.0'], { execution: 'service', outputBytes: 8192 })).toMatchObject({ exitCode })
+  expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(exitCode === 0 ? ['alias'] : [])
+})
+
+it.each(['list', 'remove'])('allows %s with preexisting incompatible packages', async (operation) => {
+  const { dir, context, pnpm } = fixture()
+  installGuarded(dir, 'incompatible')
+  // An inventory command changes nothing; `remove` deletes the row the run reports it deleted.
+  if (operation === 'remove') {
+    pnpm.mutate = (target) => {
+      const manifest = readProfileManifest('test', target)
+      delete manifest.dependencies?.incompatible
+      writeFileSync(join(target, 'package.json'), JSON.stringify(manifest))
+    }
+  }
+  expect(await runProfilePnpm(context, [operation, 'incompatible'], { execution: 'service', outputBytes: 8192 })).toMatchObject({ exitCode: 0 })
+})
+
+it.each(['devDependencies', 'optionalDependencies'])('checks installed direct plugins in %s', async (field) => {
+  const { context, pnpm } = fixture()
+  pnpm.mutate = (target) => {
+    installGuarded(target, 'incompatible')
+    const manifest = readProfileManifest('test', target)
+    writeFileSync(join(target, 'package.json'), JSON.stringify({ ...manifest, dependencies: {}, [field]: { incompatible: '1' } }))
+  }
+  expect(await runProfilePnpm(context, ['install'], { execution: 'service', outputBytes: 8192 })).toMatchObject({ exitCode: 1 })
+})
+
+it('rejects an incompatible component declared by a newly installed bundle', async () => {
+  const { dir, context, pnpm } = fixture()
+  pnpm.mutate = (target) => {
+    install(target, 'bundle')
+    const packageDir = join(target, 'node_modules', 'bundle')
+    const component = join(packageDir, 'node_modules', 'component')
+    mkdirSync(component, { recursive: true })
+    writeFileSync(join(component, 'package.json'), JSON.stringify({
+      name: 'component', version: '1.0.0', peerDependencies: { '@deepseek-ai/dsh': '>=999.0.0' },
+    }))
+    writeFileSync(join(packageDir, 'cordis.patch.yml'), '- insert:\n    - id: component\n      name: component/subpath\n')
+  }
+  const outcome = await runProfilePnpm(context, ['add', 'bundle'], { execution: 'service', outputBytes: 8192, activateNewBundles: false })
+  expect(outcome.exitCode).toBe(1)
+  expect(outcome.output).toContain('component@1.0.0')
+  expect(readProfileManifest('test', dir).dependencies).toEqual({})
+})
+
+it('restores the manifest on malformed installed peer metadata and bounds the warning', async () => {
+  const { dir, context, pnpm } = fixture()
+  const before = readFileSync(join(dir, 'package.json'), 'utf8')
+  pnpm.mutate = (target) => {
+    install(target, 'malformed')
+    writeFileSync(join(target, 'node_modules', 'malformed', 'package.json'), JSON.stringify({ name: 'malformed', version: '1.0.0', peerDependencies: [] }))
+  }
+  const outcome = await runProfilePnpm(context, ['add', 'malformed'], { execution: 'service', outputBytes: 4 })
+  expect(outcome).toMatchObject({ exitCode: 1, truncated: true })
+  expect(Buffer.byteLength(outcome.output)).toBe(4)
+  expect(readFileSync(outcome.logPath, 'utf8')).toContain('Cannot validate installed package malformed')
+  expect(readFileSync(join(dir, 'package.json'), 'utf8')).toBe(before)
+})
+
+it('checks scoped components in nested groups while leaving unresolved and local rows to startup', async () => {
+  const { context, pnpm } = fixture()
+  pnpm.mutate = (target) => {
+    install(target, 'bundle')
+    const packageDir = join(target, 'node_modules', 'bundle')
+    const component = join(packageDir, 'node_modules', '@example', 'component')
+    mkdirSync(component, { recursive: true })
+    writeFileSync(join(component, 'package.json'), JSON.stringify({ name: '@example/component', version: '1.0.0' }))
+    writeFileSync(join(packageDir, 'cordis.patch.yml'), JSON.stringify([{ insert: [
+      { id: 'group', group: true, config: [{ id: 'component', name: '@example/component/subpath' }] },
+      { id: 'empty-group', group: true, config: {} },
+      { id: 'relative', name: './plugin.mjs' },
+      { id: 'absolute', name: '/plugin.mjs' },
+      { id: 'url', name: 'file:///plugin.mjs' },
+      { id: 'unresolved', name: 'uninstalled-plugin' },
+    ] }]))
+  }
+  expect(await runProfilePnpm(context, ['add', 'bundle'], { execution: 'service', outputBytes: 8192 })).toMatchObject({ exitCode: 0 })
+})
+
+it('reports unreadable snapshot files before invoking pnpm', async () => {
+  const { dir, context } = fixture()
+  mkdirSync(join(dir, 'pnpm-lock.yaml'))
+  await expect(runProfilePnpm(context, ['install'], { execution: 'service', outputBytes: 100 })).rejects.toThrow()
+  expect(command.run).not.toHaveBeenCalled()
+})
+
 it('anchors relative package specs without rewriting registry specs', () => {
   expect(anchorPathSpec('.', '/workspace')).toBe(resolve('/workspace'))
   expect(anchorPathSpec('file:../plugin', '/workspace/project')).toBe(`file:${resolve('/workspace/plugin')}`)
@@ -124,19 +508,20 @@ it('anchors relative package specs without rewriting registry specs', () => {
 })
 
 it('activates newly installed bundles and leaves retained disabled dependencies disabled', async () => {
-  const { dir, context } = fixture()
+  const { dir, context, pnpm } = fixture()
   install(dir, 'disabled')
-  command.run.mockImplementationOnce(() => result(0, 'installed', () =>{  install(dir, 'new-bundle') }))
+  pnpm.mutate = (target) => { install(target, 'new-bundle') }
   expect(await runPluginCommand(context, ['add', 'new-bundle'], { execution: 'service', outputBytes: 100 })).toMatchObject({ exitCode: 0 })
   expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['new-bundle'])
-  command.run.mockImplementationOnce(() => result(0, 'updated'))
+  pnpm.mutate = () => {}
   await runPluginCommand(context, ['update'], { execution: 'service', outputBytes: 100 })
   expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['new-bundle'])
 })
 
 it('can install without activation and bounds output while retaining the complete log', async () => {
-  const { dir, context } = fixture()
-  command.run.mockImplementationOnce(() => result(0, '0123456789', () =>{  install(dir, 'extra') }))
+  const { dir, context, pnpm } = fixture()
+  pnpm.mutate = (target) => { install(target, 'extra') }
+  pnpm.output = '0123456789'
   const outcome = await runProfilePnpm(context, ['add', './extra'], { execution: 'service', outputBytes: 4, activateNewBundles: false })
   expect(outcome).toMatchObject({ exitCode: 0, output: '6789', truncated: true })
   expect(readFileSync(outcome.logPath, 'utf8')).toBe('0123456789')
@@ -145,21 +530,22 @@ it('can install without activation and bounds output while retaining the complet
 })
 
 it.each([runPluginCommand, runProfilePnpm])('installs into the supplied application profile directory with %s', async (run) => {
-  const { home, dir: namedDir, context } = fixture()
+  const { home, dir: namedDir, context, pnpm } = fixture()
   const dir = join(home, 'application', 'profile')
   initProfile(dir, [])
-  command.run.mockImplementationOnce(() => result(0, 'installed', () => { install(dir, 'extra') }))
+  pnpm.mutate = (target) => { install(target, 'extra') }
   const outcome = await run({ ...context, dir }, ['add', 'extra'], { execution: 'service', outputBytes: 100 })
   expect(outcome.exitCode).toBe(0)
-  expect(command.run.mock.calls[0]?.[2]).toMatchObject({ cwd: dir })
+  expect(command.run).toHaveBeenCalledWith(expect.anything(), ['add', 'extra'], expect.objectContaining({ cwd: dir }))
   expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['extra'])
   expect(readProfileManifest('test', namedDir).dependencies).not.toHaveProperty('extra')
   expect(readProfileManifest('test', namedDir).dsh?.profile?.bundles).toEqual([])
 })
 
-it('retains partial package-manager changes after failure without activating them', async () => {
-  const { dir, context } = fixture()
-  command.run.mockImplementationOnce(() => result(1, 'installation failed', () =>{  install(dir, 'partial') }))
+it('retains partial package-manager changes after a failed install without activating them', async () => {
+  const { dir, context, pnpm } = fixture()
+  pnpm.mutate = (target) => { install(target, 'partial') }
+  pnpm.exitCode = 1
   expect(await runProfilePnpm(context, ['add', 'partial'], { execution: 'service', outputBytes: 100 })).toMatchObject({ exitCode: 1 })
   expect(readProfileManifest('test', dir).dependencies).toEqual({ partial: '1' })
   expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual([])
@@ -169,7 +555,6 @@ it('retains partial package-manager changes after failure without activating the
 it('initializes missing profiles under the same lock and reports initialization', async () => {
   const { home, context } = fixture()
   const messages: string[] = []
-  command.run.mockImplementation(() => result(0, ''))
   for (const profile of ['custom', 'web']) {
     await runPluginCommand({ ...context, profile }, ['root'], {
       execution: 'service', outputBytes: 100, lockWaitMs: 1000, onOutput: (text) => { messages.push(text) },
@@ -182,7 +567,7 @@ it('initializes missing profiles under the same lock and reports initialization'
 it('terminates a run that stopped printing and reports the silence bound', async () => {
   const { context } = fixture()
   command.run.mockImplementationOnce(() => silentChild('installing\n'))
-  const outcome = await runProfilePnpm(context, ['add', 'silent'], { execution: 'service', outputBytes: 100, idleTimeoutMs: 20 })
+  const outcome = await runProfilePnpm(context, ['add', './extra'], { execution: 'service', outputBytes: 100, idleTimeoutMs: 20 })
   expect(outcome).toMatchObject({ exitCode: 1, timedOut: true })
   expect(outcome.output).toBe('installing\ndsh: pnpm printed nothing for 20ms and was terminated\n')
   expect(readFileSync(outcome.logPath, 'utf8')).toBe(outcome.output)
@@ -192,7 +577,7 @@ it('settles a run whose pipes stay open past the process exit', async () => {
   const { context } = fixture()
   const child = heldPipeChild('installed\n')
   command.run.mockImplementationOnce(() => child)
-  const outcome = await runProfilePnpm(context, ['add', 'held'], {
+  const outcome = await runProfilePnpm(context, ['add', './extra'], {
     execution: 'service', outputBytes: 100, activateNewBundles: false,
   })
   expect(outcome).toMatchObject({ exitCode: 0 })
@@ -206,7 +591,7 @@ it('settles a run whose pipes stay open past the process exit', async () => {
 it('reports a terminated run that trapped the signal and exited zero', async () => {
   const { context } = fixture()
   command.run.mockImplementationOnce(() => silentChild('installing\n', 0))
-  const outcome = await runProfilePnpm(context, ['add', 'trapped'], { execution: 'service', outputBytes: 100, idleTimeoutMs: 20 })
+  const outcome = await runProfilePnpm(context, ['add', './extra'], { execution: 'service', outputBytes: 100, idleTimeoutMs: 20 })
   // The independent facts stay separate: the signal was trapped, so the exit status is still zero.
   expect(outcome).toMatchObject({ exitCode: 0, timedOut: true })
   expect(outcome.output).toContain('printed nothing for 20ms and was terminated')
@@ -215,7 +600,7 @@ it('reports a terminated run that trapped the signal and exited zero', async ()
 it('surfaces an output consumer failure the bounded drain cuts short', async () => {
   const { context } = fixture()
   command.run.mockImplementationOnce(() => heldPipeChild('installed\n'))
-  await expect(runProfilePnpm(context, ['add', 'held'], {
+  await expect(runProfilePnpm(context, ['add', './extra'], {
     execution: 'service', outputBytes: 100, activateNewBundles: false,
     onOutput() { throw new Error('output destination closed') },
   })).rejects.toThrow('output destination closed')
@@ -225,7 +610,7 @@ it('reports a reading that fails with something other than an Error by its text'
   const { context } = fixture()
   const child = heldPipeChild('installed\n')
   command.run.mockImplementationOnce(() => child)
-  await expect(runProfilePnpm(context, ['add', 'held'], {
+  await expect(runProfilePnpm(context, ['add', './extra'], {
     execution: 'service', outputBytes: 100, activateNewBundles: false,
     // A reading can reject with any value; its text is what the failure reports.
     onOutput() { throw 'pipe broke' },
@@ -234,7 +619,6 @@ it('reports a reading that fails with something other than an Error by its text'
 
 it('terminates a service run as a tree and leaves the CLI in the caller group', async () => {
   const { context } = fixture()
-  command.run.mockImplementation(() => result(0, ''))
   await runProfilePnpm(context, ['add', 'tree'], { execution: 'service', outputBytes: 100, activateNewBundles: false })
   await runProfilePnpm(context, ['add', 'tree'], { execution: 'cli', outputBytes: 100, activateNewBundles: false })
   expect(command.run).toHaveBeenCalledWith(
@@ -246,33 +630,33 @@ it('terminates a service run as a tree and leaves the CLI in the caller group',
 })
 
 it('retains built-in layers, removes deleted dependencies and warns about plain packages', async () => {
-  const { context, dir } = fixture()
+  const { context, dir, pnpm } = fixture()
   install(dir, 'removed')
   const manifest = readProfileManifest('test', dir)
   manifest.dsh = { profile: { bundles: ['builtin', 'removed'] } }
   writeFileSync(join(dir, 'package.json'), JSON.stringify(manifest))
   const messages: string[] = []
-  command.run.mockImplementationOnce(() => result(0, '', () => {
-    install(dir, 'plain')
-    writeFileSync(join(dir, 'node_modules', 'plain', 'package.json'), '{"name":"plain"}')
-    const after = readProfileManifest('test', dir)
+  pnpm.mutate = (target) => {
+    install(target, 'plain')
+    writeFileSync(join(target, 'node_modules', 'plain', 'package.json'), '{"name":"plain"}')
+    const after = readProfileManifest('test', target)
     delete after.dependencies?.removed
-    writeFileSync(join(dir, 'package.json'), JSON.stringify(after))
-  }))
+    writeFileSync(join(target, 'package.json'), JSON.stringify(after))
+  }
   await runPluginCommand(context, ['remove', 'removed'], { execution: 'service', outputBytes: 100, onOutput: (text) => { messages.push(text) } })
   expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['builtin'])
   expect(messages.join('')).toContain('plain dependency')
 })
 
 it('preserves a package-manager selected new bundle without adding it twice', async () => {
-  const { context, dir } = fixture()
+  const { context, dir, pnpm } = fixture()
   writeFileSync(join(dir, 'package.json'), '{}')
-  command.run.mockImplementationOnce(() => result(0, '', () => {
-    install(dir, 'new')
-    const manifest = readProfileManifest('test', dir)
+  pnpm.mutate = (target) => {
+    install(target, 'new')
+    const manifest = readProfileManifest('test', target)
     manifest.dsh = { profile: { bundles: ['new'] } }
-    writeFileSync(join(dir, 'package.json'), JSON.stringify(manifest))
-  }))
+    writeFileSync(join(target, 'package.json'), JSON.stringify(manifest))
+  }
   await runProfilePnpm(context, ['add', 'new'], { execution: 'service', outputBytes: 100 })
   expect(readProfileManifest('test', dir).dsh?.profile?.bundles).toEqual(['new'])
 })
@@ -298,7 +682,7 @@ it('cancels and settles package output when the output consumer fails', async ()
     child.stdout.setEncoding('utf8')
     return child
   })
-  await expect(runProfilePnpm(context, ['root'], {
+  await expect(runProfilePnpm(context, ['add', './extra'], {
     execution: 'service', outputBytes: 100, onOutput() { throw new Error('output destination closed') },
   })).rejects.toThrow('output destination closed')
   expect(cancellation?.aborted).toBe(true)
@@ -317,6 +701,15 @@ it('preserves an unexpected subprocess rejection after both streams settle', asy
 })
 
 
+it('allows inventory commands when a declared dependency is missing from disk', async () => {
+  const { context, dir } = fixture()
+  install(dir, 'missing')
+  rmSync(join(dir, 'node_modules', 'missing'), { recursive: true })
+  command.run.mockImplementationOnce(() => result(0, 'missing dependency'))
+  expect(await runProfilePnpm(context, ['list'], { execution: 'service', outputBytes: 100, activateNewBundles: false }))
+    .toMatchObject({ exitCode: 0 })
+})
+
 it('handles manifests without dependency or bundle selections', async () => {
   const { context, dir } = fixture()
   command.run.mockImplementationOnce(() => result(0, '', () => { writeFileSync(join(dir, 'package.json'), '{}') }))
@@ -335,7 +728,6 @@ it.each(['cli', 'service'] as const)('uses the %s environment and interaction po
     })
   })
   for (const name of names) process.env[name] = 'fixture-credential'
-  command.run.mockImplementationOnce(() => result(0, ''))
   await runPluginCommand(context, ['approve-builds'], { execution, outputBytes: 100 })
   const options = command.run.mock.calls[0]?.[2] as { env: NodeJS.ProcessEnv; stdin: string; stdout: string; stderr: string }
   for (const name of names) expect(options.env[name]).toBe(execution === 'cli' ? 'fixture-credential' : undefined)
@@ -401,10 +793,9 @@ it('asks the registry through pnpm view in the profile directory, without pnpm\'
 it('uses application-owned executable arguments and environment for package operations and inspection', async () => {
   const { dir, context } = fixture()
   const runtime = { command: '/app/electron', args: ['--expose-internals', '/app/pnpm.mjs'], env: { ELECTRON_RUN_AS_NODE: '1', PATH: '/app/bin' } }
-  command.run.mockImplementationOnce(() => result(0, ''))
   await runProfilePnpm(context, ['add', './extra'], { ...runtime, execution: 'service', outputBytes: 100, activateNewBundles: false })
-  expect(command.run).toHaveBeenLastCalledWith(runtime.command, [...runtime.args, 'add', resolve(context.cwd, 'extra')],
-    expect.objectContaining({ env: expect.objectContaining(runtime.env) as unknown }))
+  expect(command.run.mock.calls[0]).toEqual([runtime.command, [...runtime.args, 'add', resolve(context.cwd, 'extra')],
+    expect.objectContaining({ env: expect.objectContaining(runtime.env) as unknown })])
   command.run.mockResolvedValueOnce(Object.assign({ exitCode: 0, failed: false }, { stdout: '{}', stderr: '', timedOut: false }))
   await viewProfilePackage(dir, 'example', { ...runtime, timeoutMs: 1000 })
   expect(command.run).toHaveBeenLastCalledWith(runtime.command,
diff --git a/packages/boot/plugin-manager/tests/tools.spec.ts b/packages/boot/plugin-manager/tests/tools.spec.ts
index da2221433d..021df877a6 100644
--- a/packages/boot/plugin-manager/tests/tools.spec.ts
+++ b/packages/boot/plugin-manager/tests/tools.spec.ts
@@ -27,6 +27,8 @@ async function fixture(mode: 'read-only' | 'workspace-write' | 'danger-full-acce
     setBundleEnabled: vi.fn(async () => ({ changed: true, application: 'applied' })),
     installBundle: vi.fn(async () => ({ changed: true, application: 'restart-required' })),
     removeBundle: vi.fn(async () => ({ changed: false, application: 'failed' })),
+    listVersionExemptions: vi.fn(() => ({ exemptions: { 'example@1.2.3': ['0.1.7-alpha.1'] }, warnings: [] })),
+    setVersionExemption: vi.fn(async () => ({ changed: true, application: 'applied' })),
   }
   ctx.provide('pluginManager', manager as unknown as PluginManager)
   await ctx.plugin(SystemPrompt)
@@ -43,7 +45,7 @@ async function fixture(mode: 'read-only' | 'workspace-write' | 'danger-full-acce
 
 it.each(['read-only', 'workspace-write'] as const)('denies every management action in %s before accessing the manager', async (mode) => {
   const { call, manager } = await fixture(mode)
-  for (const action of ['list_plugins', 'list_bundles', 'set_plugin', 'set_bundle', 'install_bundle', 'remove_bundle']) {
+  for (const action of ['list_plugins', 'list_bundles', 'set_plugin', 'set_bundle', 'install_bundle', 'remove_bundle', 'list_version_exemptions', 'set_version_exemption']) {
     const result = await call({ action, target: 'bundle', enabled: true })
     expect(result.isError).toBe(true)
     expect(JSON.stringify(result.content)).toContain('requires approval, but no approval service is composed')
@@ -105,14 +107,14 @@ it.each(['read-only', 'workspace-write'] as const)('approves each action once in
   const agent = activeAgent()
   const prompted = vi.fn(async () => 'allowed-once' as const)
   const dispose = ctx.on('approval/request', prompted)
-  for (const action of ['list_plugins', 'list_bundles', 'set_plugin', 'set_bundle', 'install_bundle', 'remove_bundle']) {
-    expect((await call({ action, target: 'bundle', enabled: true }, agent)).isError).toBe(false)
+  for (const action of ['list_plugins', 'list_bundles', 'set_plugin', 'set_bundle', 'install_bundle', 'remove_bundle', 'list_version_exemptions', 'set_version_exemption']) {
+    expect((await call({ action, target: 'bundle@1.0.0', enabled: true, runtimeVersion: '0.1.7-alpha.1', acceptRisk: true }, agent)).isError).toBe(false)
   }
-  expect(prompted).toHaveBeenCalledTimes(6)
+  expect(prompted).toHaveBeenCalledTimes(8)
   for (const method of Object.values(manager)) expect(method).toHaveBeenCalledTimes(1)
   expect(ctx.sandboxPolicy.resolve({ session: agent.session }).mode).toBe(mode)
   const audit = agent.session.snapshotEvents().filter(event => event.type.startsWith('approval/'))
-  expect(audit).toHaveLength(12)
+  expect(audit).toHaveLength(16)
   expect(audit[0]).toMatchObject({ type: 'approval/asked', data: {
     toolName: 'plugin_manager', callId: 'manager-call',
   } })
@@ -228,6 +230,9 @@ it.each([
   { action: 'set_plugin', enabled: true },
   { action: 'set_bundle', target: 'bundle' },
   { action: 'install_bundle' }, { action: 'remove_bundle' },
+  { action: 'set_version_exemption', enabled: true, runtimeVersion: '1.0.0' },
+  { action: 'set_version_exemption', target: 'plugin@1.0.0', enabled: true },
+  { action: 'set_version_exemption', target: 'plugin@1.0.0', runtimeVersion: '1.0.0' },
 ])('rejects incomplete or unbounded tool inputs: %j', async (args) => {
   const { call } = await fixture()
   expect((await call(args)).isError).toBe(true)
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index b218954333..fdc2bb3304 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -1591,6 +1591,18 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     summary: 'Manage profile files and apply their declared reload lifecycle.',
     description: 'Manage profile files and apply their declared reload lifecycle.',
     methods: [
+      {
+        signature: '@Remote listVersionExemptions(): { exemptions: Record<string, string[]>; warnings: string[] }',
+        description: 'Read exact plugin-version exemptions saved in this profile.',
+        parameters: [],
+        returns: 'Accepted package-name@version keys with the runtime versions they may run on, and any record or file problem the reader rejected, which the caller reports instead of failing.',
+      },
+      {
+        signature: '@Remote setVersionExemption(packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk?: boolean): Promise<ChangeResult>',
+        description: 'Grant or revoke one exact plugin/runtime exemption and reevaluate live plugins.',
+        parameters: [{ name: 'packageVersion', description: 'Exact manifest package name followed by @ and its version; never an installation spec or alias.' }, { name: 'runtimeVersion', description: 'Exact current DSH version for grants; revocation may name a previous runtime.' }, { name: 'enabled', description: 'Whether to grant rather than revoke the exemption.' }, { name: 'acceptRisk', description: 'Required true for grants after the user accepts possible crashes and data loss.' }],
+        returns: 'Saved and runtime outcomes. Startup-only profiles require restart.',
+      },
       {
         signature: '@Remote async listPlugins(): Promise<PluginInfo[]>',
         description: 'Read current plugins, including why a row cannot be changed through the profile patch.',
diff --git a/packages/preset/agent-preset-registry/package.json b/packages/preset/agent-preset-registry/package.json
index c0c1de5dbc..e618bd3948 100644
--- a/packages/preset/agent-preset-registry/package.json
+++ b/packages/preset/agent-preset-registry/package.json
@@ -67,12 +67,12 @@
     "@deepseek-ai/cordis": "workspace:~"
   },
   "dependencies": {
+    "@deepseek-ai/dsh-app-boot": "workspace:*",
     "@deepseek-ai/schemastery": "workspace:~",
     "zod": "^4.4.3",
     "js-yaml": "^4.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-app-boot": "workspace:*",
     "@deepseek-ai/cordis-plugin-group": "workspace:~",
     "@deepseek-ai/cordis-plugin-include": "workspace:~",
     "@deepseek-ai/cordis-plugin-loader": "workspace:~",
diff --git a/packages/preset/agent-preset-registry/src/mount.ts b/packages/preset/agent-preset-registry/src/mount.ts
index bbfa8026cb..ece3ab5762 100644
--- a/packages/preset/agent-preset-registry/src/mount.ts
+++ b/packages/preset/agent-preset-registry/src/mount.ts
@@ -1,6 +1,7 @@
 /** Runtime plugin trees shared by Agents selecting one preset revision. */
 import { Context, type Fiber } from '@deepseek-ai/cordis'
 import { EntryTree, type EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
+import { prepareProfileEntries } from '@deepseek-ai/dsh-app-boot'
 import type { PresetDefinition } from './definition.ts'
 import { scopeOf, scopeParentOf, type ScopeKey } from '@deepseek-ai/dsh-scope'
 
@@ -246,6 +247,9 @@ function mountDetail(error: unknown): string {
  * Failed rows and root-realm service leaks reject the mount. Rows waiting for
  * a Host service stay mounted: they activate by themselves once the provider
  * finishes, and the registry re-audits them after the Host tree settles.
+ * Inside a profile, compatibility policy decides admission first: a row whose
+ * plugin the profile denies mounts disabled, so the audit reads it as
+ * intentionally inactive instead of reporting a failed import.
  * @param ctx Scope context inheriting the declaring Loader's resolution base.
  * @param id Preset identity.
  * @param plugins Declared Cordis entry list.
@@ -256,7 +260,7 @@ export async function mountPreset(ctx: Context, id: string, plugins: PresetDefin
   await ctx.fiber.await()
   const tree = new PresetTree(ctx)
   ctx.effect(() => () =>{  tree.root.stop() }, 'agent-preset.tree')
-  await tree.root.update(structuredClone(plugins) as EntryOptions[])
+  await tree.root.update(prepareProfileEntries(ctx, plugins as EntryOptions[], ctx.baseUrl))
   const audit = await auditRows(tree)
   const leaked = leakedServices(ctx, ctx.fiber)
   if (audit.failed.length > 0) throw new Error(audit.failed.join('\n'))
diff --git a/packages/preset/agent-preset-registry/tests/mount.spec.ts b/packages/preset/agent-preset-registry/tests/mount.spec.ts
index 7199bda34a..aec99369b1 100644
--- a/packages/preset/agent-preset-registry/tests/mount.spec.ts
+++ b/packages/preset/agent-preset-registry/tests/mount.spec.ts
@@ -1,8 +1,13 @@
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { Context } from '@deepseek-ai/cordis'
+import { getDshRuntimeVersion, type ProfileContext } from '@deepseek-ai/dsh-app-boot'
 import { createScope } from '@deepseek-ai/dsh-scope'
 import { expect, it, onTestFinished } from 'vitest'
 import { harness, declare } from './harness.ts'
-import { auditRows, mountPreset, livePresetMounts } from '../src/mount.ts'
+import { auditRows, mountPreset, livePresetMounts, type PresetMount } from '../src/mount.ts'
 import { mountedCompositionRows } from '../src/composition-inventory.ts'
 
 it('preserves individual causes of import and plugin failures', async () => {
@@ -70,3 +75,55 @@ it('reports grouped and conditional plugin rows from the activated tree', async
   const tree = livePresetMounts(ctx.fiber)[0]!.tree
   expect(mountedCompositionRows(tree)).toEqual([{ entryId: 'off', moduleName: 'missing', enabled: false, condition: 'true' }])
 })
+
+it('mounts a profile-denied row disabled and the same row active once exempted', async () => {
+  const ctx = await harness()
+  onTestFinished(() => ctx.fiber.dispose())
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-preset-compat-')))
+  onTestFinished(() => { rmSync(dir, { recursive: true, force: true }) })
+  const pluginDir = join(dir, 'plugin')
+  mkdirSync(pluginDir, { recursive: true })
+  const loaded = join(pluginDir, 'loaded.txt')
+  writeFileSync(join(pluginDir, 'package.json'), JSON.stringify({
+    name: 'incompatible-preset-plugin', version: '1.0.0', type: 'module', main: 'index.mjs',
+    peerDependencies: { '@deepseek-ai/dsh': '<0.0.0' },
+  }))
+  writeFileSync(join(pluginDir, 'index.mjs'), [
+    "import { writeFileSync } from 'node:fs'",
+    "writeFileSync(new URL('./loaded.txt', import.meta.url), '')",
+    'export function apply() {}',
+    '',
+  ].join('\n'))
+  const profileDir = join(dir, 'profile')
+  mkdirSync(profileDir, { recursive: true })
+  const compatibilityPath = join(profileDir, 'compatibility.json')
+  writeFileSync(compatibilityPath, '{}\n')
+  ctx.provide('profileContext', {
+    name: 'test', dir: profileDir, patchPath: join(profileDir, 'cordis.patch.yml'), home: dir,
+    cwd: dir, installAnchor: join(dir, 'package.json'), startedBundles: [], overlays: [],
+    telemetryDisabledEnv: undefined,
+  } satisfies ProfileContext)
+  const row = { id: 'row', name: pathToFileURL(join(pluginDir, 'index.mjs')).href }
+  const scopes: ReturnType<typeof createScope>[] = []
+  onTestFinished(async () => { for (const scope of scopes) await scope.dispose() })
+  const mounts: PresetMount[] = []
+  const loadedWhileDenied: boolean[] = []
+  // A scope inherits the dependency API of the context that mints it, and the
+  // preset tree needs `loader`, so the mounts run under a loader-injecting row.
+  await ctx.plugin({ inject: ['loader'], async apply(owner: Context) {
+    const deniedScope = createScope(owner, {})
+    scopes.push(deniedScope)
+    mounts.push(await mountPreset(deniedScope.ctx, 'denied', [row]))
+    loadedWhileDenied.push(existsSync(loaded))
+    writeFileSync(compatibilityPath, JSON.stringify({ 'incompatible-preset-plugin@1.0.0': [getDshRuntimeVersion()] }))
+    const exemptedScope = createScope(owner, {})
+    scopes.push(exemptedScope)
+    mounts.push(await mountPreset(exemptedScope.ctx, 'exempted', [row]))
+  } })
+
+  expect(mountedCompositionRows(mounts[0]!.tree)).toEqual([{ entryId: 'row', moduleName: row.name, enabled: false }])
+  expect(await auditRows(mounts[0]!.tree)).toEqual({ failed: [], pending: [] })
+  expect(loadedWhileDenied).toEqual([false])
+  expect(mountedCompositionRows(mounts[1]!.tree)[0]!.enabled).toBe(true)
+  expect(existsSync(loaded)).toBe(true)
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bdd23c40d2..4fb2febfed 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1582,6 +1582,9 @@ importers:
 
   packages/boot/app-boot:
     dependencies:
+      '@deepseek-ai/dsh-atomic-write':
+        specifier: workspace:*
+        version: link:../../util/atomic-write
       '@deepseek-ai/dsh-package-manifest':
         specifier: workspace:*
         version: link:../../util/package-manifest
@@ -1600,6 +1603,9 @@ importers:
       resolve.exports:
         specifier: ^2.0.3
         version: 2.0.3
+      semver:
+        specifier: ^7.8.5
+        version: 7.8.5
     devDependencies:
       '@deepseek-ai/cordis':
         specifier: workspace:~
@@ -1631,6 +1637,9 @@ importers:
       '@types/js-yaml':
         specifier: ^4.0.9
         version: 4.0.9
+      '@types/semver':
+        specifier: ^7.8.0
+        version: 7.8.0
 
   packages/boot/cmdline:
     devDependencies:
@@ -9616,6 +9625,9 @@ importers:
 
   packages/preset/agent-preset-registry:
     dependencies:
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:*
+        version: link:../../boot/app-boot
       '@deepseek-ai/schemastery':
         specifier: link:../../../vendor/schemastery
         version: link:../../../vendor/schemastery
@@ -9647,9 +9659,6 @@ importers:
       '@deepseek-ai/dsh-agent-preset':
         specifier: workspace:*
         version: link:../agent-preset
-      '@deepseek-ai/dsh-app-boot':
-        specifier: workspace:*
-        version: link:../../boot/app-boot
       '@deepseek-ai/dsh-atomic-write':
         specifier: workspace:*
         version: link:../../util/atomic-write
diff --git a/snapshots/session/plugin-manager-mcp/session.v4.jsonl b/snapshots/session/plugin-manager-mcp/session.v4.jsonl
new file mode 100644
index 0000000000..b6fddf7de2
--- /dev/null
+++ b/snapshots/session/plugin-manager-mcp/session.v4.jsonl
@@ -0,0 +1,29 @@
+{"type":"session","version":4,"id":"{{session:1}}","createdAt":1789533543993,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0}
+{"type":"permission/preset","data":{"preset":"danger-full-access"}}
+{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
+{"type":"approval/policy","data":{"policy":"never"}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use plugin_manager with action set_plugin, target include:demo, enabled true to activate the configured MCP entry. Then call its newly discovered mcp__demo__ping tool and report the result. Do not use other tools."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","data":{"turn":1,"step":1}}
+{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use plugin_manager with action set_plugin, target include:demo, enabled true to activate the configured MCP entry. Then call its newly discovered mcp__demo__ping tool and report the result. Do not use other tools."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"max"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":1000000}}
+{"type":"session/title","data":{"title":"Use plugin_manager with action set_plugi","messageSeqs":[8],"source":{"kind":"fallback"}}}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to activate a plugin via plugin_manager, then call an MCP tool. Let me do the plugin_manager call first.\n\nNote: they say \"Do not use other tools\" other than plugin_manager and the mcp tool. But I need to first enable it. Let's call plugin_manager set_plugin.\n\nLet me also list plugins first? The instruction says use plugin_manager with action set_plugin, target include:demo, enabled true. Let's just do that."},{"type":"tool-call","id":"call_00_xLhr9wia3A5m7wuSRWwD0436","name":"plugin_manager","arguments":"{\"action\": \"set_plugin\", \"target\": \"include:demo\", \"enabled\": true}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"75d99e21-1d47-4a33-bb88-340a1e84b749"},{"type":"tool-call"}]}},"id":"{{message:4}}"},"usage":{"inputTokens":7220,"outputTokens":174,"cacheReadTokens":0,"cacheWriteTokens":0,"totalTokens":7394},"stream":[{"type":"chunk","time":1789533544754,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1789533545009,"index":0,"dt":[48,8,2,0,0,11,2,0,13,1,0,12,0,0,12,15,2,0,0,11,2,0,12,2,12,2,0,0,0,0,14,0,0,0,0,0,11,2,14,15,0,12,0,0,13,0,0,13,18,0,10,13,2,14,12,2,0,0,0,0,14,0,14,0,13,0,0,0,1,14,0,0,14,1,0,0,17,0,0,0,0,10,7,0,0,0,0,11,3,0,0,0,0,7,0,0,0,0],"texts":["The"," user"," wants"," me"," to"," activate"," a"," plugin"," via"," plugin","_manager",","," then"," call"," an"," M","CP"," tool","."," Let"," me"," do"," the"," plugin","_manager"," call"," first",".\n\n","Note",":"," they"," say"," \"","Do"," not"," use"," other"," tools","\""," other"," than"," plugin","_manager"," and"," the"," m","cp"," tool","."," But"," I"," need"," to"," first"," enable"," it","."," Let","'s"," call"," plugin","_manager"," set","_","plugin",".\n\n","Let"," me"," also"," list"," plugins"," first","?"," The"," instruction"," says"," use"," plugin","_manager"," with"," action"," set","_","plugin",","," target"," include",":","demo",","," enabled"," true","."," Let","'s"," just"," do"," that","."]},{"type":"chunk","time":1789533545515,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to activate a plugin via plugin_manager, then call an MCP tool. Let me do the plugin_manager call first.\n\nNote: they say \"Do not use other tools\" other than plugin_manager and the mcp tool. But I need to first enable it. Let's call plugin_manager set_plugin.\n\nLet me also list plugins first? The instruction says use plugin_manager with action set_plugin, target include:demo, enabled true. Let's just do that."}}},{"type":"chunk","time":1789533545515,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1789533545515,"index":1,"dt":[],"id":"call_00_xLhr9wia3A5m7wuSRWwD0436","name":"plugin_manager","args":[""]},{"type":"tool-call-chunks","time0":1789533545515,"index":1,"dt":[0,15,0,0,0,5,1,0,0,49,0,0,0,0,0,0,0,0,0,18,0,9,0,0,0,26,5],"id":"call_00_xLhr9wia3A5m7wuSRWwD0436","args":["{","\"","action","\"",": ","\"","set","_","plugin","\"",", ","\"","target","\"",": ","\"","include",":","demo","\"",", ","\"","en","abled","\"",": ","true","}"]},{"type":"chunk","time":1789533545662,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_xLhr9wia3A5m7wuSRWwD0436","name":"plugin_manager","arguments":"{\"action\": \"set_plugin\", \"target\": \"include:demo\", \"enabled\": true}"}}},{"type":"chunk","time":1789533545662,"chunk":{"type":"usage","usage":{"inputTokens":7220,"outputTokens":174,"cacheReadTokens":0,"cacheWriteTokens":0,"totalTokens":7394}}},{"type":"chunk","time":1789533545662,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"75d99e21-1d47-4a33-bb88-340a1e84b749"},{"type":"tool-call"}]}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_00_xLhr9wia3A5m7wuSRWwD0436","name":"plugin_manager","arguments":"{\"action\": \"set_plugin\", \"target\": \"include:demo\", \"enabled\": true}"}}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_xLhr9wia3A5m7wuSRWwD0436"},"toolCallId":"call_00_xLhr9wia3A5m7wuSRWwD0436","content":[{"type":"text","text":"{\"stage\":\"enable\",\"target\":\"include:demo\",\"enabled\":true,\"changed\":true,\"application\":\"applied\",\"warnings\":[]}"}],"isError":false,"id":"{{message:5}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":1}}
+{"type":"step/start","data":{"turn":1,"step":2}}
+{"type":"system/message","data":{"turn":1,"step":2,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:6}}"}},"sourceEventSeqs":[7],"surfaceOp":{"op":"replace","startSeq":7,"endSeq":7}}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"max"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":"{{tools}}"},"reason":"change","startsSeries":true}}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The plugin was enabled. Now call mcp__demo__ping.\n\nWait — the tool was already listed in my tools before enabling. Let's call it anyway."},{"type":"tool-call","id":"call_00_miuKfLCTz5Cb38gdp8kK5186","name":"mcp__demo__ping","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"b1ec1efe-4be6-4836-a10c-e5d6bfdce520"},{"type":"tool-call"}]}},"id":"{{message:7}}"},"usage":{"inputTokens":7035,"outputTokens":59,"cacheReadTokens":768,"cacheWriteTokens":0,"totalTokens":7862},"stream":[{"type":"chunk","time":1789533546526,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1789533547070,"index":0,"dt":[89,50,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,7,3,13,3,0,0,48,2,0,0,2,0,0,1,0],"texts":["The"," plugin"," was"," enabled","."," Now"," call"," m","cp","__","demo","__","ping",".\n\n","Wait"," —"," the"," tool"," was"," already"," listed"," in"," my"," tools"," before"," enabling","."," Let","'s"," call"," it"," anyway","."]},{"type":"chunk","time":1789533547335,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The plugin was enabled. Now call mcp__demo__ping.\n\nWait — the tool was already listed in my tools before enabling. Let's call it anyway."}}},{"type":"chunk","time":1789533547335,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1789533547335,"index":1,"dt":[],"id":"call_00_miuKfLCTz5Cb38gdp8kK5186","name":"mcp__demo__ping","args":[""]},{"type":"tool-call-chunks","time0":1789533547340,"index":1,"dt":[],"id":"call_00_miuKfLCTz5Cb38gdp8kK5186","args":["{}"]},{"type":"chunk","time":1789533547355,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_miuKfLCTz5Cb38gdp8kK5186","name":"mcp__demo__ping","arguments":"{}"}}},{"type":"chunk","time":1789533547357,"chunk":{"type":"usage","usage":{"inputTokens":7035,"outputTokens":59,"cacheReadTokens":768,"cacheWriteTokens":0,"totalTokens":7862}}},{"type":"chunk","time":1789533547357,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"b1ec1efe-4be6-4836-a10c-e5d6bfdce520"},{"type":"tool-call"}]}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":2,"callId":"call_00_miuKfLCTz5Cb38gdp8kK5186","name":"mcp__demo__ping","arguments":"{}"}}
+{"type":"tool/result","data":{"turn":1,"step":2,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_miuKfLCTz5Cb38gdp8kK5186"},"toolCallId":"call_00_miuKfLCTz5Cb38gdp8kK5186","content":[{"type":"text","text":"pong"}],"isError":false,"id":"{{message:8}}"}},"sourceEventSeqs":[21],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":2}}
+{"type":"step/start","data":{"turn":1,"step":3}}
+{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"reasoning","text":""},{"type":"text","text":"Done.\n\n- `plugin_manager` → `set_plugin`, target `include:demo`, enabled `true`: `changed: true`, `application: \"applied\"`, no warnings.\n- `mcp__demo__ping` → returned `pong`."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"b192fd4d-5258-4783-82d1-ece01c761f95"},{"type":"text"}]}},"id":"{{message:9}}"},"usage":{"inputTokens":196,"outputTokens":55,"cacheReadTokens":7680,"cacheWriteTokens":0,"totalTokens":7931},"stream":[{"type":"chunk","time":1789533548147,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"chunk","time":1789533548478,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":""}}},{"type":"chunk","time":1789533548479,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1789533548479,"index":1,"dt":[10,1,12,14,2,0,0,12,1,1,0,0,13,19,0,0,0,0,0,0,0,0,8,17,10,2,0,0,0,0,12,1,0,0,13,1,0,0,0,0,15,0,0,0,0,0,12,2,0,15,0,0,0],"texts":["Done",".\n\n","-"," `","plugin","_manager","`"," →"," `","set","_","plugin","`,"," target"," `","include",":","demo","`,"," enabled"," `","true","`:"," `","changed",":"," true","`,"," `","application",":"," \"","app","lied","\"","`,"," no"," warnings",".\n","-"," `","m","cp","__","demo","__","ping","`"," →"," returned"," `","p","ong","`."]},{"type":"chunk","time":1789533548672,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"Done.\n\n- `plugin_manager` → `set_plugin`, target `include:demo`, enabled `true`: `changed: true`, `application: \"applied\"`, no warnings.\n- `mcp__demo__ping` → returned `pong`."}}},{"type":"chunk","time":1789533548672,"chunk":{"type":"usage","usage":{"inputTokens":196,"outputTokens":55,"cacheReadTokens":7680,"cacheWriteTokens":0,"totalTokens":7931}}},{"type":"chunk","time":1789533548672,"chunk":{"type":"finish","reason":{"kind":"stop"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"b192fd4d-5258-4783-82d1-ece01c761f95"},{"type":"text"}]}}}]},"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":3}}
+{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json b/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json
index 333edf7654..1f40739eb5 100644
--- a/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json
+++ b/snapshots/session/plugin-manager-mcp/tool-schemas.expected.json
@@ -262,7 +262,7 @@
     },
     {
       "name": "plugin_manager",
-      "description": "List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart.",
+      "description": "List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart. Incompatible DSH peer dependencies block installation and activation. Version exemptions risk crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -275,7 +275,9 @@
               "set_plugin",
               "set_bundle",
               "install_bundle",
-              "remove_bundle"
+              "remove_bundle",
+              "list_version_exemptions",
+              "set_version_exemption"
             ]
           },
           "target": {
@@ -284,7 +286,15 @@
           },
           "enabled": {
             "type": "boolean",
-            "description": "Required for set operations; defaults to true for installation."
+            "description": "Required for set operations; defaults to true for installation. For set_version_exemption, true grants and false revokes."
+          },
+          "runtimeVersion": {
+            "type": "string",
+            "description": "For set_version_exemption: exact DSH version from list_version_exemptions. Target must be the manifest package-name@version, not an alias or version range."
+          },
+          "acceptRisk": {
+            "type": "boolean",
+            "description": "For granting an exemption: true only after warning the user about possible crashes and data loss and receiving explicit permission for this exact plugin/runtime pair. General installation permission is not enough."
           },
           "approvedBuilds": {
             "type": "array",
@@ -978,7 +988,7 @@
       },
       {
         "name": "plugin_manager",
-        "description": "List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart.",
+        "description": "List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart. Incompatible DSH peer dependencies block installation and activation. Version exemptions risk crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -991,7 +1001,9 @@
                 "set_plugin",
                 "set_bundle",
                 "install_bundle",
-                "remove_bundle"
+                "remove_bundle",
+                "list_version_exemptions",
+                "set_version_exemption"
               ]
             },
             "target": {
@@ -1000,7 +1012,15 @@
             },
             "enabled": {
               "type": "boolean",
-              "description": "Required for set operations; defaults to true for installation."
+              "description": "Required for set operations; defaults to true for installation. For set_version_exemption, true grants and false revokes."
+            },
+            "runtimeVersion": {
+              "type": "string",
+              "description": "For set_version_exemption: exact DSH version from list_version_exemptions. Target must be the manifest package-name@version, not an alias or version range."
+            },
+            "acceptRisk": {
+              "type": "boolean",
+              "description": "For granting an exemption: true only after warning the user about possible crashes and data loss and receiving explicit permission for this exact plugin/runtime pair. General installation permission is not enough."
             },
             "approvedBuilds": {
               "type": "array",
diff --git a/snapshots/session/plugin-manager/session.v4.jsonl b/snapshots/session/plugin-manager/session.v4.jsonl
new file mode 100644
index 0000000000..7f2c1357ba
--- /dev/null
+++ b/snapshots/session/plugin-manager/session.v4.jsonl
@@ -0,0 +1,27 @@
+{"type":"session","version":4,"id":"{{session:1}}","createdAt":1789456219793,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0}
+{"type":"permission/preset","data":{"preset":"danger-full-access"}}
+{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
+{"type":"approval/policy","data":{"policy":"never"}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use plugin_manager with action set_plugin, target include:tool-todo, and enabled false. Then call it again with enabled true. Do not use other tools. Finish by replying exactly PLUGIN_MANAGER_DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","data":{"turn":1,"step":1}}
+{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use plugin_manager with action set_plugin, target include:tool-todo, and enabled false. Then call it again with enabled true. Do not use other tools. Finish by replying exactly PLUGIN_MANAGER_DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"max"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":1000000}}
+{"type":"session/title","data":{"title":"Use plugin_manager with action set_plugi","messageSeqs":[8],"source":{"kind":"fallback"}}}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to call plugin_manager twice with the given parameters, then reply \"PLUGIN_MANAGER_DONE\". Let me make the calls. The first call with enabled false, then the second with enabled true. These are dependent in sequence (toggle off, then on), so I should do them sequentially — actually, the instruction says call it again after. Let me do them one at a time to be safe, since the second depends on the first having applied.\n\nActually the user says \"Do not use other tools\" — plugin_manager is fine. Let me make the first call."},{"type":"tool-call","id":"call_00_XgwocGXnE4z5t7I5ENoS0769","name":"plugin_manager","arguments":"{\"action\": \"set_plugin\", \"target\": \"include:tool-todo\", \"enabled\": false}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"14ac483b-5df3-4d50-9aac-43c9caa07684"},{"type":"tool-call"}]}},"id":"{{message:4}}"},"usage":{"inputTokens":7164,"outputTokens":199,"cacheReadTokens":0,"cacheWriteTokens":0,"totalTokens":7363},"stream":[{"type":"chunk","time":1789475683170,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1789475683170,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," me"," to"," call"," plugin","_manager"," twice"," with"," the"," given"," parameters",","," then"," reply"," \"","PL","UG","IN","_M","AN","AG","ER","_D","ONE","\"."," Let"," me"," make"," the"," calls","."," The"," first"," call"," with"," enabled"," false",","," then"," the"," second"," with"," enabled"," true","."," These"," are"," dependent"," in"," sequence"," (","toggle"," off",","," then"," on","),"," so"," I"," should"," do"," them"," sequentially"," —"," actually",","," the"," instruction"," says"," call"," it"," again"," after","."," Let"," me"," do"," them"," one"," at"," a"," time"," to"," be"," safe",","," since"," the"," second"," depends"," on"," the"," first"," having"," applied",".\n\n","Actually"," the"," user"," says"," \"","Do"," not"," use"," other"," tools","\""," —"," plugin","_manager"," is"," fine","."," Let"," me"," make"," the"," first"," call","."]},{"type":"chunk","time":1789475683171,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to call plugin_manager twice with the given parameters, then reply \"PLUGIN_MANAGER_DONE\". Let me make the calls. The first call with enabled false, then the second with enabled true. These are dependent in sequence (toggle off, then on), so I should do them sequentially — actually, the instruction says call it again after. Let me do them one at a time to be safe, since the second depends on the first having applied.\n\nActually the user says \"Do not use other tools\" — plugin_manager is fine. Let me make the first call."}}},{"type":"chunk","time":1789475683171,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1789475683171,"index":1,"dt":[],"id":"call_00_XgwocGXnE4z5t7I5ENoS0769","name":"plugin_manager","args":[""]},{"type":"tool-call-chunks","time0":1789475683171,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_XgwocGXnE4z5t7I5ENoS0769","args":["{","\"","action","\"",": ","\"","set","_","plugin","\"",", ","\"","target","\"",": ","\"","include",":","tool","-t","odo","\"",", ","\"","en","abled","\"",": ","false","}"]},{"type":"chunk","time":1789475683171,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_XgwocGXnE4z5t7I5ENoS0769","name":"plugin_manager","arguments":"{\"action\": \"set_plugin\", \"target\": \"include:tool-todo\", \"enabled\": false}"}}},{"type":"chunk","time":1789475683171,"chunk":{"type":"usage","usage":{"inputTokens":7164,"outputTokens":199,"cacheReadTokens":0,"cacheWriteTokens":0,"totalTokens":7363}}},{"type":"chunk","time":1789475683171,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"14ac483b-5df3-4d50-9aac-43c9caa07684"},{"type":"tool-call"}]}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_00_XgwocGXnE4z5t7I5ENoS0769","name":"plugin_manager","arguments":"{\"action\": \"set_plugin\", \"target\": \"include:tool-todo\", \"enabled\": false}"}}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_XgwocGXnE4z5t7I5ENoS0769"},"toolCallId":"call_00_XgwocGXnE4z5t7I5ENoS0769","content":[{"type":"text","text":"{\"stage\":\"enable\",\"target\":\"include:tool-todo\",\"enabled\":false,\"changed\":true,\"application\":\"restart-required\",\"warnings\":[]}"}],"isError":false,"id":"{{message:5}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":1}}
+{"type":"step/start","data":{"turn":1,"step":2}}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"Now the second call with enabled true."},{"type":"tool-call","id":"call_00_8FDEYUdbLsc4vBZYHKUs0380","name":"plugin_manager","arguments":"{\"action\": \"set_plugin\", \"enabled\": true, \"target\": \"include:tool-todo\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"4f20c714-9549-4b29-b0de-3e3bfb2d70e8"},{"type":"tool-call"}]}},"id":"{{message:6}}"},"usage":{"inputTokens":151,"outputTokens":85,"cacheReadTokens":7296,"cacheWriteTokens":0,"totalTokens":7532},"stream":[{"type":"chunk","time":1789475683202,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1789475683202,"index":0,"dt":[0,0,0,0,0,0,0],"texts":["Now"," the"," second"," call"," with"," enabled"," true","."]},{"type":"chunk","time":1789475683202,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Now the second call with enabled true."}}},{"type":"chunk","time":1789475683202,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1789475683202,"index":1,"dt":[],"id":"call_00_8FDEYUdbLsc4vBZYHKUs0380","name":"plugin_manager","args":[""]},{"type":"tool-call-chunks","time0":1789475683202,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_8FDEYUdbLsc4vBZYHKUs0380","args":["{","\"","action","\"",": ","\"","set","_","plugin","\"",", ","\"","en","abled","\"",": ","true",", ","\"","target","\"",": ","\"","include",":","tool","-t","odo","\"","}"]},{"type":"chunk","time":1789475683202,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_8FDEYUdbLsc4vBZYHKUs0380","name":"plugin_manager","arguments":"{\"action\": \"set_plugin\", \"enabled\": true, \"target\": \"include:tool-todo\"}"}}},{"type":"chunk","time":1789475683202,"chunk":{"type":"usage","usage":{"inputTokens":151,"outputTokens":85,"cacheReadTokens":7296,"cacheWriteTokens":0,"totalTokens":7532}}},{"type":"chunk","time":1789475683202,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"4f20c714-9549-4b29-b0de-3e3bfb2d70e8"},{"type":"tool-call"}]}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":2,"callId":"call_00_8FDEYUdbLsc4vBZYHKUs0380","name":"plugin_manager","arguments":"{\"action\": \"set_plugin\", \"enabled\": true, \"target\": \"include:tool-todo\"}"}}
+{"type":"tool/result","data":{"turn":1,"step":2,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_8FDEYUdbLsc4vBZYHKUs0380"},"toolCallId":"call_00_8FDEYUdbLsc4vBZYHKUs0380","content":[{"type":"text","text":"{\"stage\":\"enable\",\"target\":\"include:tool-todo\",\"enabled\":true,\"changed\":true,\"application\":\"restart-required\",\"warnings\":[]}"}],"isError":false,"id":"{{message:7}}"}},"sourceEventSeqs":[19],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":2}}
+{"type":"step/start","data":{"turn":1,"step":3}}
+{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"reasoning","text":""},{"type":"text","text":"PLUGIN_MANAGER_DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"f082a27e-1e6a-4a30-b674-1a229370cd70"},{"type":"text"}]}},"id":"{{message:8}}"},"usage":{"inputTokens":192,"outputTokens":10,"cacheReadTokens":7424,"cacheWriteTokens":0,"totalTokens":7626},"stream":[{"type":"chunk","time":1789475683228,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"chunk","time":1789475683228,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":""}}},{"type":"chunk","time":1789475683228,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1789475683228,"index":1,"dt":[0,0,0,0,0,0,0,0],"texts":["PL","UG","IN","_M","AN","AG","ER","_D","ONE"]},{"type":"chunk","time":1789475683228,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"PLUGIN_MANAGER_DONE"}}},{"type":"chunk","time":1789475683228,"chunk":{"type":"usage","usage":{"inputTokens":192,"outputTokens":10,"cacheReadTokens":7424,"cacheWriteTokens":0,"totalTokens":7626}}},{"type":"chunk","time":1789475683228,"chunk":{"type":"finish","reason":{"kind":"stop"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"deepseek-v4-flash"},"blocks":[{"type":"reasoning","signature":"f082a27e-1e6a-4a30-b674-1a229370cd70"},{"type":"text"}]}}}]},"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":3}}
+{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/session/plugin-manager/tool-schemas.expected.json b/snapshots/session/plugin-manager/tool-schemas.expected.json
index b58a167b44..aff31d32c1 100644
--- a/snapshots/session/plugin-manager/tool-schemas.expected.json
+++ b/snapshots/session/plugin-manager/tool-schemas.expected.json
@@ -262,7 +262,7 @@
     },
     {
       "name": "plugin_manager",
-      "description": "List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart.",
+      "description": "List plugins or bundles in the current profile, enable or disable them, install a bundle, or remove an installed bundle. Every action requires danger-full-access permission or approval for this call. Approval does not change the session permission mode. Changes affect every session in this profile. List first to obtain exact identifiers. Package installation can execute allowed build scripts. Live profiles apply changes immediately; startup profiles require restart. Incompatible DSH peer dependencies block installation and activation. Version exemptions risk crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -275,7 +275,9 @@
               "set_plugin",
               "set_bundle",
               "install_bundle",
-              "remove_bundle"
+              "remove_bundle",
+              "list_version_exemptions",
+              "set_version_exemption"
             ]
           },
           "target": {
@@ -284,7 +286,15 @@
           },
           "enabled": {
             "type": "boolean",
-            "description": "Required for set operations; defaults to true for installation."
+            "description": "Required for set operations; defaults to true for installation. For set_version_exemption, true grants and false revokes."
+          },
+          "runtimeVersion": {
+            "type": "string",
+            "description": "For set_version_exemption: exact DSH version from list_version_exemptions. Target must be the manifest package-name@version, not an alias or version range."
+          },
+          "acceptRisk": {
+            "type": "boolean",
+            "description": "For granting an exemption: true only after warning the user about possible crashes and data loss and receiving explicit permission for this exact plugin/runtime pair. General installation permission is not enough."
           },
           "approvedBuilds": {
             "type": "array",