From 9da174c3043aece0f71eb972dc2133d13e5c52a9 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 15:34:19 +0800
Subject: [PATCH 01/35] fix(web): display local media paths referenced in
 session prose

Assistant prose that references a workspace-contained local media path
(e.g. `![](/Users/.../x.png)`) now renders through a same-origin
`GET|HEAD /api/file?path=` route instead of inert alt text.

- ui-primitives: MarkdownText gains a settled-only MarkdownPathImages
  vocabulary gate (same posture as file mentions); no vocabulary means
  byte-identical output.
- ui-chat: AssistantMarkdown supplies a page-stable rewrite vocabulary
  for absolute POSIX paths (local-path-media.ts).
- session-controller: SessionMediaReferences plugin contribution mounts
  the route on the authenticated connection.fetch channel; per-request
  policy = workspace-root containment after realpath, regular file,
  allowlisted media extension (images additionally signature-checked),
  range/HEAD streaming, private no-store + nosniff, fail-closed statuses.
- Agent Note added (feature/2026-09-07-session-prose-local-media-display).

Closes #3662.
---
 ...ession-prose-local-media-display.i18n.yaml |   6 +
 ...09-07-session-prose-local-media-display.md |  39 +++
 ...07-session-prose-local-media-display.zh.md |  39 +++
 packages/api/session-controller/src/index.ts  |   2 +
 .../src/media-references.ts                   | 257 +++++++++++++++++
 .../tests/media-references.host.spec.ts       | 265 ++++++++++++++++++
 .../api/session-controller/tsconfig.host.json |   2 +
 .../src/client/chat/AssistantMarkdown.tsx     |  11 +-
 .../src/client/chat/local-path-media.ts       |  24 ++
 ...stant-markdown-path-images.client.spec.tsx |  46 +++
 .../tests/local-path-media.client.spec.ts     |  30 ++
 packages/client/ui-primitives/src/index.ts    |   2 +-
 .../src/markdown/MarkdownText.tsx             |  21 +-
 .../ui-primitives/src/markdown/render.tsx     |  57 +++-
 .../markdown-path-images.client.spec.tsx      |  83 ++++++
 .../markdown-render-units.client.spec.tsx     |   1 +
 16 files changed, 872 insertions(+), 13 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
 create mode 100644 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
 create mode 100644 packages/api/session-controller/src/media-references.ts
 create mode 100644 packages/api/session-controller/tests/media-references.host.spec.ts
 create mode 100644 packages/client/ui-chat/src/client/chat/local-path-media.ts
 create mode 100644 packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx
 create mode 100644 packages/client/ui-chat/tests/local-path-media.client.spec.ts
 create mode 100644 packages/client/ui-primitives/tests/markdown-path-images.client.spec.tsx

diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
new file mode 100644
index 0000000000..db2a7595b2
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
+2026-09-07-session-prose-local-media-display.md: e2693a6192cb78641d8a96937b39a4b06e884f04
+2026-09-07-session-prose-local-media-display.zh.md: bc0c62868e3ffab44fc3effc1030d9caee331f26
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
new file mode 100644
index 0000000000..e2693a6192
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
@@ -0,0 +1,39 @@
+# Agent Note: Session prose local media paths display through a same-origin file route
+
+Status: implemented
+
+English | [中文](2026-09-07-session-prose-local-media-display.zh.md)
+
+## Problem
+
+Assistant prose sometimes references an image by its local filesystem path (markdown `![](/Users/.../x.png)`). The Web renderer only allowed absolute HTTP(S) image destinations, so such references fell back to inert alt text: the browser cannot read Host files, and nothing served them. Searches of the formal and external issue trackers found no existing record, and issue #3662 logged the gap (Web cannot display local-path images referenced by agent answers).
+
+## Decision
+
+Local media paths in session prose render through one same-origin file route, with the rewrite vocabulary and the serving policy each owned where the repo's seams say they belong.
+
+- **Renderer seam (`ui-primitives`)**: `MarkdownText` gained a `MarkdownPathImages` vocabulary (`pathImages` prop) with the same settled-only gate as `fileMentions`: while a message streams, frozen cached blocks never bake in a vocabulary handler; the settled pass rewrites image destinations that fail the remote-URL allowlist, and a rewritten destination is emitted only when it is an absolute `http(s)`/`blob`/`data` URL. Without a vocabulary the renderer output is byte-identical to before.
+- **Chat wiring (`ui-chat`)**: `AssistantMarkdown` supplies a page-stable vocabulary mapping absolute POSIX paths to same-origin `/api/file?path=…` GETs (`local-path-media.ts`); non-HTTP transports (Electron `file://`) and relative/protocol-relative destinations stay inert.
+- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root, the file must be regular, and its extension must name an allowlisted media type (PNG/JPEG/GIF/WebP/AVIF, MP4/WebM/MOV/OGG, MP3/WAV/Ogg/M4A/AAC/FLAC); image extensions are additionally checked against their byte signature. Responses stream with HTTP range support (206/416) so video and audio can seek, and carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
+
+The route is presentational and stateless: it never writes, follows no redirects, and returns 400/403/404/415/416 instead of approximating another file-serving behavior.
+
+## Alternatives considered
+
+- **Register on the Typert gateway**: the gateway owns Remote RPC dispatch (endpoint claims, WebSocket mux, forwarded events), not file serving; placing the route there put HTTP presentation of workspace files into the RPC transport layer. Rejected and fully reverted.
+- **Register under `workspace-controller`**: that package owns workspace registry lifecycle (CRUD, ordering, feed), and shares only the registry as a policy data source. Rejected and fully reverted.
+- **Fetch bytes over the session RPC and show blob/data URLs**: attachment images already do this, but markdown rewriting needs a deterministic synchronous URL at render time (streaming freeze caches, memoization); an async round trip cannot be the render seam. Rejected.
+- **A per-image or image-only route**: media types share one path-and-contain policy; video/audio need range streaming anyway. One `/api/file` route with an extension allowlist plus signature checks for images covers all current and next media types. Rejected as narrower alternatives.
+- **Per-request interactive authorization, client-negotiated endpoints, or arbitrary host paths**: the rewrite is presentation; the route re-validates every request and limits readable bytes to registered workspace roots and allowlisted media, and the same-origin endpoint is a fixed channel contract rather than a negotiated capability. Rejected for security and determinism reasons.
+
+## Consequences
+
+- Assistant prose that references workspace-contained image files now displays them in Web chat; previously inert alt text disappears only where the host can serve the bytes.
+- Policy is enforced host-side per request; the client vocabulary never expands what the route allows.
+- Scope is deliberately narrow: only files under registered workspace roots with allowlisted media types are served; anything else keeps the authored fallback. Trajectory and tool-card markdown consumers do not pass a vocabulary yet, and video/audio markdown nodes are not rendered as `<video>`/`<audio>` yet — the URL layer already supports them.
+- The client hardcodes the `/api/file` endpoint as a same-origin channel contract; this is stable by construction because the page is served by the same host that mounts the route.
+- Related history: the archived note [model-readable image paths](../../archived/feature/2026-08-21-model-readable-image-paths.md) decided the model-facing side of local image paths; this note owns the user-facing display side and does not supersede it.
+
+## Testing
+
+Unit coverage: the renderer seam (settled and streaming gates, reference-style images, protocol re-checks), the chat vocabulary and component wiring, and the host route policy (containment, symlinks, media allowlist and signature mismatch, range parsing and 206/416 answers, HEAD, disposal of the plugin contribution). Full local evidence at open: typecheck clean; ui-primitives, ui-chat, and session-controller suites (103 files, 1456 tests) pass. Deferred to the PR follow-up: keyless recorded-session replay for the end-to-end GUI path and the browser demo GIF the GUI PR evidence chain requires.
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
new file mode 100644
index 0000000000..bc0c62868e
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: 会话正文本地媒体路径通过同源文件路由显示
+
+Status: implemented
+
+[English](2026-09-07-session-prose-local-media-display.md) | 中文
+
+## Problem
+
+Assistant 正文有时用本地文件系统路径引用图片（markdown `![](/Users/.../x.png)`）。Web 渲染器只允许绝对 HTTP(S) 图片目标，这类引用只能回退为惰性 alt 文本：浏览器读不到 Host 文件，也没有任何东西提供这些字节。检索正式与外部 Issue 仓库均无既有记录，issue #3662 记录了这一缺口（Web 无法显示 Agent 回答引用的本地路径图片）。
+
+## Decision
+
+会话正文中的本地媒体路径通过一条同源文件路由渲染；重写词表与服务政策分别归属于仓库现有缝对应的位置。
+
+- **渲染缝（`ui-primitives`）**：`MarkdownText` 新增 `MarkdownPathImages` 词表（`pathImages` prop），与 `fileMentions` 同用 settled-only 门：消息流式期间冻结的缓存块绝不烘入词表处理器；落定渲染把未通过远程 URL 白名单的图片目标重写为可展示 URL，且只有结果是绝对 `http(s)`/`blob`/`data` URL 时才发射。不提供词表时渲染输出与之前逐字节一致。
+- **聊天接线（`ui-chat`）**：`AssistantMarkdown` 提供页面级稳定的词表，把绝对 POSIX 路径映射为同源 `GET /api/file?path=…`（`local-path-media.ts`）；非 HTTP 载体（Electron `file://`）与相对/协议相对目标保持惰性。
+- **Host 路由（`session-controller`）**：`SessionMediaReferences` 是与 `SessionFileReferences` 并列注册的插件贡献，把 `GET|HEAD /api/file` 挂到共享鉴权 `connection.fetch` 通道（与 `/api` RPC 同一 trust fence 与浏览器认证）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内、文件必须是常规文件、扩展名必须在媒体 allowlist 内（PNG/JPEG/GIF/WebP/AVIF、MP4/WebM/MOV/OGG、MP3/WAV/Ogg/M4A/AAC/FLAC）；图片扩展额外校验字节签名。响应以 HTTP Range 流式输出（206/416），视频/音频可拖动进度，并携带 `private, no-store` 与 `nosniff`。该贡献只在 `connection` 与 `workspaceRegistry` 均被组合时激活（pending-until-composed，与包内其它可选贡献一致）。
+
+该路由纯呈现且无状态：从不写入、不跟随重定向，失败返回 400/403/404/415/416，不近似其它文件服务行为。
+
+## Alternatives considered
+
+- **注册到 Typert gateway**：gateway 负责 Remote RPC 分发（endpoint 认领、WebSocket mux、转发事件），不负责文件服务；把路由放那里等于把 workspace 文件的 HTTP 呈现塞进 RPC 传输层。否决并完整回滚。
+- **注册到 `workspace-controller`**：该包负责 workspace 注册表生命周期（CRUD、排序、feed），与文件呈现只共享 registry 这一政策数据源。否决并完整回滚。
+- **经会话 RPC 取字节后显示 blob/data URL**：附件图片已如此工作，但 markdown 重写需要渲染时确定性同步 URL（流式冻结缓存、memo 化）；异步往返不能成为渲染缝。否决。
+- **逐图片或仅图片专用路由**：媒体类型共享同一条「路径 + 包含」政策，视频/音频本就需要 Range 流式；一条 `/api/file` 路由加扩展名 allowlist（图片另验签名）即可覆盖现有与后续媒体类型。作为更窄的方案被否决。
+- **每请求交互授权、客户端协商端点或任意 Host 路径**：重写只是呈现；路由对每次请求复验，可读字节限制在注册 workspace 根与 allowlist 媒体内；同源端点是固定通道契约而非协商能力。出于安全与确定性否决。
+
+## Consequences
+
+- 引用 workspace 内图片文件的 Assistant 正文现在可在 Web 聊天中显示；原先惰性的 alt 文本只在 Host 无法提供字节时保留。
+- 政策在 Host 端每次请求强制；客户端词表不会扩大路由放行的范围。
+- 范围刻意收窄：只服务注册 workspace 根内、媒体 allowlist 内的文件；其它一律保持作者原样的回退。Trajectory 与工具卡片等 markdown 消费方尚未传词表，视频/音频 markdown 节点也尚未渲染为 `<video>`/`<audio>`——URL 层已为它们准备好。
+- 客户端把 `/api/file` 硬编码为同源通道契约；由于页面与挂载路由的 Host 同源，该契约按构造稳定。
+- 相关历史：已归档笔记 [model-readable image paths](../../archived/feature/2026-08-21-model-readable-image-paths.md) 决定本地图片路径面向模型的一侧；本笔记拥有面向用户展示的一侧，不构成对其的取代。
+
+## Testing
+
+单元覆盖：渲染缝（落定与流式门、引用式图片、协议复检）、聊天词表与组件接线、Host 路由政策（包含关系、符号链接、媒体 allowlist 与签名不符、Range 解析与 206/416 应答、HEAD、插件贡献的释放）。开 PR 时的本地证据：typecheck 干净；ui-primitives、ui-chat 与 session-controller 套件（103 个文件、1456 个用例）全过。推迟到 PR 后续：端到端 GUI 路径的 keyless 录播回放，以及 GUI PR 证据链要求的浏览器演示 GIF。
diff --git a/packages/api/session-controller/src/index.ts b/packages/api/session-controller/src/index.ts
index c058f25a08..9cc93be179 100644
--- a/packages/api/session-controller/src/index.ts
+++ b/packages/api/session-controller/src/index.ts
@@ -22,6 +22,7 @@ import { ApiSessionList } from './list.ts'
 import { buildModelCatalog } from './catalog.ts'
 import { installModelSelectionProjection } from './model-selection-projection.ts'
 import { SessionSkillCatalog } from './skill-catalog.ts'
+import { SessionMediaReferences } from './media-references.ts'
 import type {
   ModelCatalog,
   SessionAttachmentRequest,
@@ -134,6 +135,7 @@ export class SessionController extends TypertRemoteService {
     this.canOpenPath = internals.canOpenPath
       ?? (() => config.nativeOpen ?? (internals.openPath !== undefined || canOpenNativePath()))
     ctx.plugin(SessionFileReferences)
+    ctx.plugin(SessionMediaReferences)
     ctx.plugin(SessionSkillCatalog)
 
     ctx.on('session/created', (session) => {
diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
new file mode 100644
index 0000000000..56d47d7d94
--- /dev/null
+++ b/packages/api/session-controller/src/media-references.ts
@@ -0,0 +1,257 @@
+/**
+ * GET/HEAD /api/file — same-origin media bytes for a local path authored in
+ * conversation prose. Browsers cannot read Host files, so local media
+ * destinations (images today; video/audio the same way) are rewritten to this
+ * one route; the route re-validates every request because the rewrite itself
+ * proves nothing.
+ *
+ * Policy (enforced per request, fail-closed):
+ * - the requested path must be one absolute filesystem path;
+ * - its canonical location must lie inside a registered workspace root
+ *   (`ctx.workspaceRegistry`); no other directory is readable;
+ * - the file must exist and be a regular file;
+ * - its extension must name an allowlisted media type; image extensions are
+ *   additionally checked against the file signature;
+ * - responses are private, uncached, sniff-proof, and support HTTP range
+ *   requests so `<video>`/`<audio>` can seek without buffering the file.
+ *
+ * The route is deliberately presentational: it never writes and follows no
+ * redirects, returning 400/403/404/415/416 instead of falling back to any
+ * other file-serving behavior.
+ *
+ * The package entry imports only `SessionMediaReferences`; the remaining
+ * module exports exist for same-package unit tests and are not part of the
+ * package's public API.
+ * @module @deepseek-ai/dsh-api-session-controller/media-references
+ */
+
+import { createReadStream } from 'node:fs'
+import { open, realpath, stat } from 'node:fs/promises'
+import { extname, isAbsolute, sep } from 'node:path'
+import { Readable } from 'node:stream'
+import type { Context } from '@deepseek-ai/cordis'
+// Cordis `ctx.connection` typing and the fetch-route contract.
+import type {} from '@deepseek-ai/dsh-client-connection'
+// Cordis `ctx.workspaceRegistry` typing.
+import type {} from '@deepseek-ai/dsh-workspace'
+
+/** Registered-workspace view the route reads; see the `workspaceRegistry` service. */
+export interface MediaReferenceRegistry {
+  /** List registered workspaces with their canonical root directories. */
+  list(): readonly { path: string }[]
+}
+
+/** Media extensions the route serves, mapped to their content types. */
+const MEDIA_TYPES: Readonly<Record<string, string>> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mov': 'video/quicktime',
+  '.ogv': 'video/ogg',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+  '.oga': 'audio/ogg',
+  '.m4a': 'audio/mp4',
+  '.aac': 'audio/aac',
+  '.flac': 'audio/flac',
+}
+
+/** Image extensions whose bytes must match their declared signature. */
+const SNIFFED_IMAGE_TYPES: Readonly<Record<string, string>> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+}
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const
+const JPEG_SIGNATURE = [0xff, 0xd8, 0xff] as const
+const GIF_87_SIGNATURE = 'GIF87a' as const
+const GIF_89_SIGNATURE = 'GIF89a' as const
+const RIFF_SIGNATURE = 'RIFF' as const
+const WEBP_SIGNATURE = 'WEBP' as const
+
+function startsWithBytes(data: Uint8Array, offset: number, expected: readonly number[]): boolean {
+  if (data.byteLength < offset + expected.length) return false
+  return expected.every((byte, index) => data[offset + index] === byte)
+}
+
+function startsWithAscii(data: Uint8Array, offset: number, value: string): boolean {
+  if (data.byteLength < offset + value.length) return false
+  for (let index = 0; index < value.length; index += 1) {
+    if (data[offset + index] !== value.charCodeAt(index)) return false
+  }
+  return true
+}
+
+/**
+ * Check one byte buffer against the sniffed image signatures.
+ * @param data - Leading file bytes (12 suffice for every supported type).
+ * @returns the matched media type, or undefined for other bytes.
+ */
+export function sniffImageMediaType(data: Uint8Array): string | undefined {
+  if (startsWithBytes(data, 0, PNG_SIGNATURE)) return 'image/png'
+  if (startsWithBytes(data, 0, JPEG_SIGNATURE)) return 'image/jpeg'
+  if (startsWithAscii(data, 0, GIF_87_SIGNATURE) || startsWithAscii(data, 0, GIF_89_SIGNATURE)) {
+    return 'image/gif'
+  }
+  if (startsWithAscii(data, 0, RIFF_SIGNATURE) && startsWithAscii(data, 8, WEBP_SIGNATURE)) {
+    return 'image/webp'
+  }
+  return undefined
+}
+
+/**
+ * The content type a file path may be served as, or undefined when the
+ * extension is not an allowlisted media type.
+ * @param path - Canonical file path (extension only is read).
+ * @param bytes - Leading file bytes for signature-checked image extensions.
+ * @returns the content type, or undefined to refuse the file.
+ */
+export function mediaTypeForPath(path: string, bytes: Uint8Array): string | undefined {
+  const extension = extname(path).toLowerCase()
+  const sniffed = SNIFFED_IMAGE_TYPES[extension]
+  if (sniffed !== undefined) return sniffImageMediaType(bytes) === sniffed ? sniffed : undefined
+  return MEDIA_TYPES[extension]
+}
+
+/** One resolved byte-range within a file; `full` streams the whole file. */
+type ByteRange =
+  | { readonly kind: 'full' }
+  | { readonly kind: 'partial'; readonly start: number; readonly end: number }
+
+/**
+ * Parse one single-range `Range` header value against the file size.
+ * @param header - Raw `Range` request header, or null when absent.
+ * @param size - Total file size in bytes.
+ * @returns the byte range to serve, or undefined when the header names no
+ * satisfiable single range (the caller answers 416 with a `bytes *\/size`
+ * Content-Range header).
+ */
+export function parseByteRange(header: string | null, size: number): ByteRange | undefined {
+  if (header === null) return { kind: 'full' }
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim())
+  if (match === null) return undefined
+  const startText = match[1]
+  const endText = match[2]
+  if (startText === '' && endText === '') return undefined
+  let start: number
+  let end: number
+  if (startText === '') {
+    // Suffix range: the last N bytes.
+    const length = Number(endText)
+    if (length === 0) return undefined
+    start = Math.max(size - length, 0)
+    end = size - 1
+  } else {
+    start = Number(startText)
+    end = endText === '' ? size - 1 : Number(endText)
+  }
+  if (start > end || start >= size) return undefined
+  return { kind: 'partial', start, end: Math.min(end, size - 1) }
+}
+
+/**
+ * Serve one workspace-contained media file over the shared API channel.
+ * @param request - Authenticated fetch-route request (GET or HEAD).
+ * @param registry - Workspace registry; absent (or empty) denies everything.
+ * @returns A streaming media response or a fail-closed status.
+ */
+export async function serveMediaReference(
+  request: Request,
+  registry: MediaReferenceRegistry | undefined,
+): Promise<Response> {
+  const path = new URL(request.url).searchParams.get('path')
+  if (path === null || path.length === 0) return new Response('missing path', { status: 400 })
+  if (path.includes('\0') || !isAbsolute(path)) {
+    return new Response('absolute path required', { status: 400 })
+  }
+  if (registry === undefined) return new Response('file serving is unavailable', { status: 403 })
+  let canonical: string
+  try {
+    canonical = await realpath(path)
+  } catch {
+    return new Response('not found', { status: 404 })
+  }
+  const insideWorkspace = registry.list().some(root =>
+    canonical === root.path || canonical.startsWith(root.path + sep))
+  if (!insideWorkspace) return new Response('outside workspace roots', { status: 403 })
+  let info
+  try {
+    info = await stat(canonical)
+  } catch {
+    return new Response('not found', { status: 404 })
+  }
+  if (!info.isFile()) return new Response('not a regular file', { status: 403 })
+  let handle
+  try {
+    handle = await open(canonical, 'r')
+  } catch {
+    return new Response('not found', { status: 404 })
+  }
+  try {
+    const headBytes = new Uint8Array(12)
+    const { buffer } = await handle.read(headBytes, 0, 12, 0)
+    const mediaType = mediaTypeForPath(canonical, new Uint8Array(buffer))
+    if (mediaType === undefined) {
+      return new Response('not an allowlisted media type', { status: 415 })
+    }
+    const range = parseByteRange(request.headers.get('range'), info.size)
+    if (range === undefined) {
+      const headers: Record<string, string> = {
+        'Content-Range': 'bytes */' + String(info.size),
+        'Cache-Control': 'private, no-store',
+        'X-Content-Type-Options': 'nosniff',
+      }
+      return new Response(null, { status: 416, headers })
+    }
+    const partial = range.kind === 'partial'
+    const start = partial ? range.start : 0
+    const end = partial ? range.end : info.size - 1
+    const body: ReadableStream<Uint8Array> = Readable.toWeb(
+      createReadStream(canonical, { start, end }),
+    ) as ReadableStream<Uint8Array>
+    const headers: Record<string, string> = {
+      'Content-Type': mediaType,
+      'Content-Length': String(partial ? end - start + 1 : info.size),
+      'Accept-Ranges': 'bytes',
+      'Cache-Control': 'private, no-store',
+      'X-Content-Type-Options': 'nosniff',
+    }
+    if (partial) headers['Content-Range'] = 'bytes ' + start + '-' + end + '/' + String(info.size)
+    const head = request.method === 'HEAD'
+    return new Response(head ? null : body, { status: partial ? 206 : 200, headers })
+  } finally {
+    await handle.close()
+  }
+}
+
+/**
+ * `/api/file` fetch-route contribution, the media counterpart of
+ * `SessionFileReferences`: that contribution lets the GUI discover the files
+ * a Session references, this one lets it display referenced local media
+ * paths as same-origin bytes. Declared injects gate activation: a host
+ * composition without a connection service (or a workspace registry) never
+ * activates this plugin, so the route simply does not exist there — the same
+ * pending-until-composed posture the package's other optional contributions
+ * use. The channel's trust fence and browser authentication apply before any
+ * request reaches the handler.
+ */
+export const SessionMediaReferences = {
+  inject: ['connection', 'workspaceRegistry'],
+  apply(ctx: Context): void {
+    ctx.effect(() => ctx.connection.fetch.register({
+      path: '/api/file',
+      methods: ['GET', 'HEAD'],
+      requestBody: 'buffered',
+      fetch: request => serveMediaReference(request, ctx.workspaceRegistry),
+    }), 'session-controller: /api/file')
+  },
+}
diff --git a/packages/api/session-controller/tests/media-references.host.spec.ts b/packages/api/session-controller/tests/media-references.host.spec.ts
new file mode 100644
index 0000000000..429b90e8d5
--- /dev/null
+++ b/packages/api/session-controller/tests/media-references.host.spec.ts
@@ -0,0 +1,265 @@
+import { mkdir, mkdtemp, open, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import {
+  SessionMediaReferences,
+  serveMediaReference,
+  mediaTypeForPath,
+  parseByteRange,
+  sniffImageMediaType,
+  type MediaReferenceRegistry,
+} from '../src/media-references.ts'
+
+const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3, 4, 5, 6])
+const TEXT_BYTES = new Uint8Array([1, 2, 3, 4])
+const MP4_BYTES = new TextEncoder().encode('....ftypmp42....moov....')
+
+function registry(root: string): MediaReferenceRegistry {
+  return { list: () => [{ path: root }] }
+}
+
+async function responseBytes(response: Response): Promise<Uint8Array> {
+  return new Uint8Array(await response.arrayBuffer())
+}
+
+function apiRequest(path: string, init?: RequestInit): Request {
+  const url = `http://127.0.0.1:3080/api/file?path=${encodeURIComponent(path)}`
+  return new Request(url, init)
+}
+
+describe('sniffImageMediaType and mediaTypeForPath', () => {
+  it('identifies supported image signatures', () => {
+    expect(sniffImageMediaType(PNG_BYTES)).toBe('image/png')
+    expect(sniffImageMediaType(new Uint8Array([0xff, 0xd8, 0xff, 0xe0]))).toBe('image/jpeg')
+    expect(sniffImageMediaType(new TextEncoder().encode('GIF89a...'))).toBe('image/gif')
+    expect(sniffImageMediaType(new TextEncoder().encode('RIFF0000WEBPVP8 '))).toBe('image/webp')
+    expect(sniffImageMediaType(TEXT_BYTES)).toBeUndefined()
+  })
+
+  it('maps allowlisted media extensions, sniffing image extensions', () => {
+    expect(mediaTypeForPath('/w/graph.png', PNG_BYTES)).toBe('image/png')
+    expect(mediaTypeForPath('/w/graph.jpg', new Uint8Array([0xff, 0xd8, 0xff]))).toBe('image/jpeg')
+    expect(mediaTypeForPath('/w/clip.mp4', MP4_BYTES)).toBe('video/mp4')
+    expect(mediaTypeForPath('/w/clip.webm', MP4_BYTES)).toBe('video/webm')
+    expect(mediaTypeForPath('/w/song.mp3', TEXT_BYTES)).toBe('audio/mpeg')
+  })
+
+  it('refuses non-media extensions and mislabeled image bytes', () => {
+    expect(mediaTypeForPath('/w/note.txt', TEXT_BYTES)).toBeUndefined()
+    expect(mediaTypeForPath('/w/app.exe', TEXT_BYTES)).toBeUndefined()
+    expect(mediaTypeForPath('/w/shell.svg', TEXT_BYTES)).toBeUndefined()
+    expect(mediaTypeForPath('/w/fake.png', TEXT_BYTES)).toBeUndefined()
+  })
+})
+
+describe('parseByteRange', () => {
+  it('parses full, bounded, open-ended, and suffix ranges', () => {
+    expect(parseByteRange(null, 100)).toEqual({ kind: 'full' })
+    expect(parseByteRange('bytes=0-3', 100)).toEqual({ kind: 'partial', start: 0, end: 3 })
+    expect(parseByteRange('bytes=10-', 100)).toEqual({ kind: 'partial', start: 10, end: 99 })
+    expect(parseByteRange('bytes=-4', 100)).toEqual({ kind: 'partial', start: 96, end: 99 })
+    expect(parseByteRange('bytes=90-200', 100)).toEqual({ kind: 'partial', start: 90, end: 99 })
+  })
+
+  it('refuses malformed and unsatisfiable ranges', () => {
+    expect(parseByteRange('bytes=abc', 100)).toBeUndefined()
+    expect(parseByteRange('bytes=5-2', 100)).toBeUndefined()
+    expect(parseByteRange('bytes=100-', 100)).toBeUndefined()
+    expect(parseByteRange('bytes=0-', 0)).toBeUndefined()
+  })
+})
+
+describe('serveMediaReference', () => {
+  let root: string
+
+  beforeEach(async () => {
+    // Real workspace roots are canonical; tmpdir may sit behind a symlink.
+    root = await realpath(await mkdtemp(join(tmpdir(), 'dsh-workspace-file-')))
+  })
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it('serves a workspace image with streaming-safe headers', async () => {
+    const path = join(root, 'shots', 'graph.png')
+    await mkdir(join(root, 'shots'), { recursive: true })
+    await writeFile(path, PNG_BYTES)
+    const response = await serveMediaReference(apiRequest(path), registry(root))
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toBe('image/png')
+    expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
+    expect(response.headers.get('accept-ranges')).toBe('bytes')
+    expect(response.headers.get('cache-control')).toBe('private, no-store')
+    expect(response.headers.get('x-content-type-options')).toBe('nosniff')
+    expect(await responseBytes(response)).toEqual(PNG_BYTES)
+  })
+
+  it('serves media without image sniffing from the extension allowlist', async () => {
+    const path = join(root, 'clip.mp4')
+    await writeFile(path, MP4_BYTES)
+    const response = await serveMediaReference(apiRequest(path), registry(root))
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toBe('video/mp4')
+    expect(await responseBytes(response)).toEqual(MP4_BYTES)
+  })
+
+  it('answers bounded and suffix range requests with 206 slices', async () => {
+    const path = join(root, 'graph.png')
+    await writeFile(path, PNG_BYTES)
+    const bounded = await serveMediaReference(
+      apiRequest(path, { headers: { range: 'bytes=0-3' } }),
+      registry(root),
+    )
+    expect(bounded.status).toBe(206)
+    expect(bounded.headers.get('content-range')).toBe(`bytes 0-3/${PNG_BYTES.length}`)
+    expect(bounded.headers.get('content-length')).toBe('4')
+    expect(await responseBytes(bounded)).toEqual(PNG_BYTES.slice(0, 4))
+
+    const suffix = await serveMediaReference(
+      apiRequest(path, { headers: { range: 'bytes=-4' } }),
+      registry(root),
+    )
+    expect(suffix.status).toBe(206)
+    expect(await responseBytes(suffix)).toEqual(PNG_BYTES.slice(-4))
+  })
+
+  it('answers unsatisfiable ranges with 416 and the total size', async () => {
+    const path = join(root, 'graph.png')
+    await writeFile(path, PNG_BYTES)
+    const response = await serveMediaReference(
+      apiRequest(path, { headers: { range: 'bytes=999-' } }),
+      registry(root),
+    )
+    expect(response.status).toBe(416)
+    expect(response.headers.get('content-range')).toBe(`bytes */${PNG_BYTES.length}`)
+  })
+
+  it('answers HEAD without a body', async () => {
+    const path = join(root, 'graph.png')
+    await writeFile(path, PNG_BYTES)
+    const response = await serveMediaReference(
+      apiRequest(path, { method: 'HEAD' }),
+      registry(root),
+    )
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
+    expect(response.body).toBeNull()
+  })
+
+  it('denies malformed, missing, and uncontained requests', async () => {
+    const missing = await serveMediaReference(
+      new Request('http://127.0.0.1:3080/api/file'),
+      registry(root),
+    )
+    expect(missing.status).toBe(400)
+    const relative = await serveMediaReference(
+      new Request(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent('x.png')}`),
+      registry(root),
+    )
+    expect(relative.status).toBe(400)
+    const gone = await serveMediaReference(
+      apiRequest(join(root, 'missing.png')),
+      registry(root),
+    )
+    expect(gone.status).toBe(404)
+    expect((await serveMediaReference(apiRequest(join(root, 'x.png')), undefined)).status).toBe(403)
+
+    const outside = await realpath(await mkdtemp(join(tmpdir(), 'dsh-workspace-file-out-')))
+    const path = join(outside, 'x.png')
+    await writeFile(path, PNG_BYTES)
+    try {
+      const denied = await serveMediaReference(apiRequest(path), registry(root))
+      expect(denied.status).toBe(403)
+      expect(await denied.text()).toBe('outside workspace roots')
+    } finally {
+      await rm(outside, { recursive: true, force: true })
+    }
+  })
+
+  it('refuses directories and non-allowlisted or mislabeled content', async () => {
+    const directory = await serveMediaReference(apiRequest(root), registry(root))
+    expect(directory.status).toBe(403)
+
+    const text = join(root, 'note.txt')
+    await writeFile(text, TEXT_BYTES)
+    expect((await serveMediaReference(apiRequest(text), registry(root))).status).toBe(415)
+
+    const fake = join(root, 'fake.png')
+    await writeFile(fake, TEXT_BYTES)
+    expect((await serveMediaReference(apiRequest(fake), registry(root))).status).toBe(415)
+  })
+
+  it('follows a symlink into the workspace for the containment check', async () => {
+    const real = join(root, 'real.png')
+    await writeFile(real, PNG_BYTES)
+    const link = join(root, 'link.png')
+    await symlink(real, link)
+    const response = await serveMediaReference(apiRequest(link), registry(root))
+    expect(response.status).toBe(200)
+    expect(await responseBytes(response)).toEqual(PNG_BYTES)
+  })
+
+  it('survives a large sparse file check without buffering it whole', async () => {
+    const path = join(root, 'huge.mp4')
+    const handle = await open(path, 'w')
+    try {
+      await handle.truncate(256 * 1024 * 1024)
+    } finally {
+      await handle.close()
+    }
+    const response = await serveMediaReference(
+      apiRequest(path, { headers: { range: 'bytes=0-9' } }),
+      registry(root),
+    )
+    expect(response.status).toBe(206)
+    expect(response.headers.get('content-length')).toBe('10')
+    expect((await responseBytes(response)).length).toBe(10)
+  })
+})
+
+describe('SessionMediaReferences plugin contribution', () => {
+  const roots: Context[] = []
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map(ctx => ctx.fiber.dispose()))
+  })
+
+  it('registers the /api/file route when connection and registry are composed', async () => {
+    const unregister = vi.fn(() => {})
+    let registered: {
+      path: string
+      methods: readonly string[]
+      requestBody: 'buffered'
+      fetch: (request: Request) => Promise<Response>
+    } | undefined
+    const register = vi.fn((route: typeof registered) => {
+      registered = route
+      return unregister
+    })
+    const ctx = new Context()
+    roots.push(ctx)
+    ctx.provide('connection', { fetch: { register } } as never)
+    ctx.provide('workspaceRegistry', { list: () => [] } as never)
+    await ctx.plugin(SessionMediaReferences).await()
+
+    expect(register).toHaveBeenCalledTimes(1)
+    expect(registered?.path).toBe('/api/file')
+    expect(registered?.methods).toEqual(['GET', 'HEAD'])
+    expect(registered?.requestBody).toBe('buffered')
+
+    // The composed route consults the composed registry: an empty registry
+    // refuses an existing absolute path with the containment verdict.
+    const existing = await realpath(tmpdir())
+    const denied = await registered?.fetch(
+      new Request(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent(existing)}`),
+    )
+    expect(denied?.status).toBe(403)
+    expect(await denied?.text()).toBe('outside workspace roots')
+
+    await ctx.fiber.dispose()
+    expect(unregister).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/packages/api/session-controller/tsconfig.host.json b/packages/api/session-controller/tsconfig.host.json
index ad7751119f..60a7775804 100644
--- a/packages/api/session-controller/tsconfig.host.json
+++ b/packages/api/session-controller/tsconfig.host.json
@@ -17,6 +17,7 @@
     "src/file-references.ts",
     "src/history.ts",
     "src/list.ts",
+    "src/media-references.ts",
     "src/model-selection-projection.ts",
     "src/skill-catalog.ts"
   ],
@@ -30,6 +31,7 @@
     { "path": "../../context/file-reference" },
     { "path": "../../attachment/attachment" },
     { "path": "../../client/file-upload/tsconfig.host.json" },
+    { "path": "../../client/connection/tsconfig.host.json" },
     { "path": "../../interaction/permission-presets" },
     { "path": "../../jobs/jobs" },
     { "path": "../../llm/llm" },
diff --git a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
index c517f9d0c2..b02de8e1a5 100644
--- a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
@@ -1,11 +1,12 @@
 import { Fragment, memo, useMemo } from 'react'
 import type { ReactNode } from 'react'
 import { JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { MarkdownFileMentions, MarkdownPathImages } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts'
 import type { AssistantBlock } from '../contract/snapshot.ts'
 import { markdownLabels } from '../markdown-labels.ts'
 import { ReasoningRow } from './ReasoningRow.tsx'
+import { localPathMediaUrl } from './local-path-media.ts'
 import { useSearchableHidden } from './searchable-hidden.ts'
 import css from './AssistantMarkdown.module.css'
 
@@ -34,6 +35,13 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
   const labels = useMemo(() => markdownLabels(t), [t])
+  // Local media paths in the closing prose rewrite to the same-origin file
+  // API (policy re-validation lives host-side). The vocabulary identity is
+  // stable per page load because MarkdownText memoizes on it.
+  const pathImages = useMemo<MarkdownPathImages>(() => {
+    const { protocol, origin } = window.location
+    return { resolve: value => localPathMediaUrl(protocol, origin, value) }
+  }, [])
   const last = blocks.length - 1
   // Tool-call heads render as tool rows in the chat view's grouping pass, so
   // a node that is only those heads (or empty) would paint an empty root
@@ -55,6 +63,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
             streaming={streaming}
             labels={labels}
             fileMentions={mentions}
+            pathImages={pathImages}
           />,
         )
         break
diff --git a/packages/client/ui-chat/src/client/chat/local-path-media.ts b/packages/client/ui-chat/src/client/chat/local-path-media.ts
new file mode 100644
index 0000000000..5369a253ce
--- /dev/null
+++ b/packages/client/ui-chat/src/client/chat/local-path-media.ts
@@ -0,0 +1,24 @@
+/**
+ * Pure local-path → same-origin workspace-file mapping for closing prose. The
+ * renderer seam consumes this vocabulary; the served endpoint re-validates
+ * every request, so this side only decides whether a destination *looks*
+ * like an absolute local path the Host could serve. One endpoint covers every
+ * served media type (images today; video/audio the same way), so consumers
+ * rewrite the path without knowing what kind of media it names.
+ */
+
+/**
+ * Map one authored media destination to the same-origin workspace-file URL.
+ * @param protocol - `window.location.protocol` at render time.
+ * @param origin - `window.location.origin` at render time.
+ * @param value - The authored markdown destination, exactly as written.
+ * @returns The API URL for an absolute POSIX path on an HTTP(S) page, or
+ * undefined when the destination cannot be a Host-served local file
+ * (non-HTTP transport such as Electron `file://`, protocol-relative or
+ * relative destinations).
+ */
+export function localPathMediaUrl(protocol: string, origin: string, value: string): string | undefined {
+  if (protocol !== 'http:' && protocol !== 'https:') return undefined
+  if (value.length === 0 || !value.startsWith('/') || value.startsWith('//')) return undefined
+  return `${origin}/api/file?path=${encodeURIComponent(value)}`
+}
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
new file mode 100644
index 0000000000..6b9169c418
--- /dev/null
+++ b/packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx
@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
+import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../src/client/contract/slots.ts'
+import type { AssistantBlock } from '../src/client/contract/snapshot.ts'
+
+afterEach(cleanup)
+
+const t = ((_key: string) => 'label') as unknown as ChatViewSlotProps['t']
+const renderMessageImages = (() => null) as unknown as ChatNodeOwnerProps['renderMessageImages']
+
+function textBlock(text: string): AssistantBlock {
+  return { kind: 'text', text }
+}
+
+describe('AssistantMarkdown local-path images', () => {
+  it('renders a local image path in closing prose through the same-origin API', () => {
+    const { container } = render(
+      <AssistantMarkdown
+        blocks={[textBlock('See ![diagram](/tmp/graph.png) for the layout.')]}
+        streaming={false}
+        renderMessageImages={renderMessageImages}
+        t={t}
+      />,
+    )
+    const image = container.querySelector('img')
+    expect(image?.getAttribute('alt')).toBe('diagram')
+    const url = new URL(image?.getAttribute('src') ?? '')
+    expect(url.pathname).toBe('/api/file')
+    expect(url.searchParams.get('path')).toBe('/tmp/graph.png')
+  })
+
+  it('keeps non-absolute destinations inert', () => {
+    const { container } = render(
+      <AssistantMarkdown
+        blocks={[textBlock('See ![diagram](relative.png).')]}
+        streaming={false}
+        renderMessageImages={renderMessageImages}
+        t={t}
+      />,
+    )
+    expect(container.querySelector('img')).toBeNull()
+    expect(container.textContent).toContain('diagram')
+  })
+})
diff --git a/packages/client/ui-chat/tests/local-path-media.client.spec.ts b/packages/client/ui-chat/tests/local-path-media.client.spec.ts
new file mode 100644
index 0000000000..b34f99fb06
--- /dev/null
+++ b/packages/client/ui-chat/tests/local-path-media.client.spec.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import { localPathMediaUrl } from '../src/client/chat/local-path-media.ts'
+
+const ORIGIN = 'http://127.0.0.1:3080'
+
+describe('localPathMediaUrl', () => {
+  it('maps an absolute POSIX path on an HTTP page to the image API', () => {
+    expect(localPathMediaUrl('http:', ORIGIN, '/tmp/graph.png'))
+      .toBe(`${ORIGIN}/api/file?path=${encodeURIComponent('/tmp/graph.png')}`)
+    expect(localPathMediaUrl('https:', 'https://127.0.0.1:3080', '/tmp/graph.png'))
+      .toBe(`https://127.0.0.1:3080/api/file?path=${encodeURIComponent('/tmp/graph.png')}`)
+  })
+
+  it('keeps non-HTTP transports inert', () => {
+    expect(localPathMediaUrl('file:', 'file:///app', '/tmp/graph.png')).toBeUndefined()
+    expect(localPathMediaUrl('ws:', ORIGIN, '/tmp/graph.png')).toBeUndefined()
+  })
+
+  it('keeps destinations that cannot be Host-served local files inert', () => {
+    expect(localPathMediaUrl('http:', ORIGIN, '')).toBeUndefined()
+    expect(localPathMediaUrl('http:', ORIGIN, '//cdn.example.com/x.png')).toBeUndefined()
+    expect(localPathMediaUrl('http:', ORIGIN, 'relative.png')).toBeUndefined()
+    expect(localPathMediaUrl('http:', ORIGIN, 'C:\\tmp\\x.png')).toBeUndefined()
+  })
+
+  it('encodes the full path including spaces', () => {
+    expect(localPathMediaUrl('http:', ORIGIN, '/tmp/my graph.png'))
+      .toBe(`${ORIGIN}/api/file?path=${encodeURIComponent('/tmp/my graph.png')}`)
+  })
+})
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index 16199de859..737e8fc879 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -64,7 +64,7 @@ export { CodeBlock } from './markdown/CodeBlock.tsx'
 export type { CodeBlockProps } from './markdown/CodeBlock.tsx'
 export { JsonBlock } from './markdown/JsonBlock.tsx'
 export { MarkdownText } from './markdown/MarkdownText.tsx'
-export type { MarkdownCodeLabels, MarkdownFileMentions, MarkdownLabels } from './markdown/MarkdownText.tsx'
+export type { MarkdownCodeLabels, MarkdownFileMentions, MarkdownLabels, MarkdownPathImages } from './markdown/MarkdownText.tsx'
 export { extractMarkdownPlainText } from './markdown/plain-text.ts'
 export type { MarkdownPlainTextMode, MarkdownPlainTextOptions } from './markdown/plain-text.ts'
 export * from './icons/index.tsx'
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.tsx b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
index 0b19896979..121c6ff49b 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
@@ -19,17 +19,18 @@ import {
   collectReferenceTargets, createReferenceTargets, renderBlocks, renderFootnoteSection,
   wrapBlockChildren,
 } from './render.tsx'
-import type { MarkdownFileMentions, MarkdownLabels, MarkdownRenderContext, ReferenceTargets } from './render.tsx'
+import type { MarkdownFileMentions, MarkdownLabels, MarkdownPathImages, MarkdownRenderContext, ReferenceTargets } from './render.tsx'
 import 'katex/dist/katex.min.css'
 import css from './MarkdownText.module.css'
 
-export type { MarkdownCodeLabels, MarkdownFileMentions, MarkdownLabels } from './render.tsx'
+export type { MarkdownCodeLabels, MarkdownFileMentions, MarkdownLabels, MarkdownPathImages } from './render.tsx'
 
 /** One settled full render: parse with math, resolve references, append the footnote section. */
 function renderSettled(
   text: string,
   labels: MarkdownLabels,
   fileMentions: MarkdownFileMentions | undefined,
+  pathImages: MarkdownPathImages | undefined,
 ): ReactNode[] {
   const root = parseGfmWithMath(text)
   const targets = createReferenceTargets()
@@ -38,6 +39,7 @@ function renderSettled(
     streaming: false,
     labels,
     fileMentions,
+    pathImages,
     targets,
     footnoteOrder: [],
     footnoteCounts: new Map(),
@@ -106,6 +108,7 @@ class StreamingRenderer {
         streaming: true,
         labels: this.labels,
         fileMentions: undefined,
+        pathImages: undefined,
         targets: frameTargets,
         footnoteOrder: this.frozenFootnoteOrder,
         footnoteCounts: this.frozenFootnoteCounts,
@@ -124,6 +127,7 @@ class StreamingRenderer {
       streaming: true,
       labels: this.labels,
       fileMentions: undefined,
+      pathImages: undefined,
       targets: frameTargets,
       footnoteOrder: [...this.frozenFootnoteOrder],
       footnoteCounts: new Map(this.frozenFootnoteCounts),
@@ -150,32 +154,35 @@ class StreamingRenderer {
  * `labels` forwards localized fence and footnote chrome — pass a
  * reference-stable object (memoized per locale revision), because a new
  * identity discards the streaming render cache mid-message. `fileMentions`
- * links inline-code tokens its resolver recognizes as real files; this is
- * the single streaming gate — it applies to settled renders only, because a
+ * links inline-code tokens its resolver recognizes as real files, and
+ * `pathImages` rewrites image destinations that are local file paths into
+ * displayable URLs its resolver vouches for; both vocabularies are the
+ * single streaming gate — they apply to settled renders only, because a
  * streaming message's vocabulary is not final and frozen cached elements
  * must not bake in handlers that could go stale.
  * @returns A GFM document with TeX math rendered through KaTeX; raw HTML,
  * relative links, and unsafe protocols are disabled, while absolute HTTP(S)
  * images render directly.
  */
-export const MarkdownText = memo(function MarkdownText({ text, streaming = false, labels, fileMentions }: {
+export const MarkdownText = memo(function MarkdownText({ text, streaming = false, labels, fileMentions, pathImages }: {
   text: string
   streaming?: boolean
   labels: MarkdownLabels
   fileMentions?: MarkdownFileMentions | undefined
+  pathImages?: MarkdownPathImages | undefined
 }) {
   const streamRef = useRef<StreamingRenderer | null>(null)
   const streamLabelsRef = useRef<MarkdownLabels>(labels)
   const children = useMemo(() => {
     if (!streaming) {
       streamRef.current = null
-      return renderSettled(text, labels, fileMentions)
+      return renderSettled(text, labels, fileMentions, pathImages)
     }
     if (streamRef.current === null || streamLabelsRef.current !== labels) {
       streamRef.current = new StreamingRenderer(labels)
       streamLabelsRef.current = labels
     }
     return streamRef.current.render(text)
-  }, [text, streaming, labels, fileMentions])
+  }, [text, streaming, labels, fileMentions, pathImages])
   return <div className={css.markdown}>{children}</div>
 })
diff --git a/packages/client/ui-primitives/src/markdown/render.tsx b/packages/client/ui-primitives/src/markdown/render.tsx
index 9757ddc301..565280440a 100644
--- a/packages/client/ui-primitives/src/markdown/render.tsx
+++ b/packages/client/ui-primitives/src/markdown/render.tsx
@@ -69,6 +69,35 @@ function remoteImageUrl(url: string): string | undefined {
   }
 }
 
+/** Protocols a vocabulary-rewritten image destination may carry. */
+function vocabularyImageUrl(url: string): string | undefined {
+  try {
+    const protocol = new URL(url).protocol
+    return protocol === 'http:' || protocol === 'https:' || protocol === 'blob:' || protocol === 'data:'
+      ? url
+      : undefined
+  } catch {
+    // A vocabulary result must be an absolute URL; anything else stays a miss.
+    return undefined
+  }
+}
+
+/**
+ * The displayable source for one image destination: absolute HTTP(S) as
+ * authored, otherwise the context's local-path vocabulary when it vouches for
+ * the destination. Either miss leaves the authored fallback (alt text) to the
+ * caller.
+ * @param url - The authored markdown destination.
+ * @param pathImages - Rewriting vocabulary, when the render pass has one.
+ * @returns The displayable image URL, or undefined.
+ */
+function imageSource(url: string, pathImages: MarkdownPathImages | undefined): string | undefined {
+  const remote = remoteImageUrl(sanitizeUrl(normalizeUri(url)))
+  if (remote !== undefined) return remote
+  const rewritten = pathImages?.resolve(url)
+  return rewritten === undefined ? undefined : vocabularyImageUrl(rewritten)
+}
+
 /** Link/image reference targets collected from a document (first definition per identifier wins, as in CommonMark). */
 export interface ReferenceTargets {
   /** Link/image definitions keyed by upper-cased identifier. */
@@ -107,6 +136,24 @@ export function collectReferenceTargets(
   }
 }
 
+/**
+ * Local-path image vocabulary for image destinations: the owner maps an
+ * authored destination that fails the remote-URL allowlist (an absolute local
+ * file path, for example) to a displayable URL it can vouch for. Absent
+ * wherever no such vocabulary exists, authored local destinations keep their
+ * documented fallback (the image's alt text). Rewritten destinations must be
+ * absolute; the renderer re-checks their protocol before emitting them.
+ */
+export interface MarkdownPathImages {
+  /**
+   * Resolve one authored image destination.
+   * @param value - The destination exactly as the markdown author wrote it.
+   * @returns A displayable absolute URL, or undefined when the destination
+   * names no displayable image — it then stays inert alt text.
+   */
+  resolve(value: string): string | undefined
+}
+
 /**
  * File-mention affordance for inline code: the owner resolves an authored
  * token to the file it names, using its own vocabulary of real files — the
@@ -135,6 +182,8 @@ export interface MarkdownRenderContext {
   readonly inBlockquote?: boolean
   /** Inline-code file mentions; absent wherever no opener vocabulary exists. */
   readonly fileMentions: MarkdownFileMentions | undefined
+  /** Local-path image vocabulary; absent wherever no rewriting owner exists. */
+  readonly pathImages: MarkdownPathImages | undefined
   /** Inside an anchor's children: interactive mentions must not nest there. */
   readonly inLink?: boolean
   /** Reference targets visible to this pass. */
@@ -293,7 +342,7 @@ function renderNode(node: Md.RootContent, key: Key, context: MarkdownRenderConte
     case 'linkReference':
       return renderLinkReference(node, key, context)
     case 'image':
-      return renderImage(node.url, node.alt ?? '', key)
+      return renderImage(node.url, node.alt ?? '', key, context)
     case 'imageReference':
       return renderImageReference(node, key, context)
     case 'footnoteReference':
@@ -513,8 +562,8 @@ function inlineCodeHttpUrl(value: string): string | undefined {
   }
 }
 
-function renderImage(url: string, alt: string, key: Key): ReactNode {
-  const imageSrc = remoteImageUrl(sanitizeUrl(normalizeUri(url)))
+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>
   }
@@ -562,7 +611,7 @@ function renderImageReference(
 ): ReactNode {
   const definition = context.targets.definitions.get(node.identifier.toUpperCase())
   if (definition === undefined) return `![${node.alt ?? ''}${referenceSuffix(node)}`
-  return renderImage(definition.url, node.alt ?? '', key)
+  return renderImage(definition.url, node.alt ?? '', key, context)
 }
 
 function renderFootnoteReference(
diff --git a/packages/client/ui-primitives/tests/markdown-path-images.client.spec.tsx b/packages/client/ui-primitives/tests/markdown-path-images.client.spec.tsx
new file mode 100644
index 0000000000..4e75dfb0fe
--- /dev/null
+++ b/packages/client/ui-primitives/tests/markdown-path-images.client.spec.tsx
@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { MarkdownText } from './markdown-test-components.tsx'
+import type { MarkdownPathImages } from '../src/markdown/MarkdownText.tsx'
+
+afterEach(cleanup)
+
+const LOCAL_IMAGE = '![diagram](/tmp/graph.png)'
+
+const mapping = (value: string): string | undefined =>
+  value === '/tmp/graph.png' ? 'https://cdn.example.com/graph.png' : undefined
+
+describe('MarkdownText local-path images', () => {
+  it('renders authored alt text when no path vocabulary exists', () => {
+    const { container } = render(<MarkdownText text={LOCAL_IMAGE} />)
+    expect(container.querySelector('img')).toBeNull()
+    expect(screen.getByText('diagram')).toBeTruthy()
+  })
+
+  it('rewrites a local image path through the vocabulary', () => {
+    const pathImages: MarkdownPathImages = { resolve: mapping }
+    const { container } = render(<MarkdownText text={LOCAL_IMAGE} pathImages={pathImages} />)
+    const image = container.querySelector('img')
+    expect(image?.getAttribute('src')).toBe('https://cdn.example.com/graph.png')
+    expect(image?.getAttribute('alt')).toBe('diagram')
+  })
+
+  it('keeps the alt fallback when the vocabulary misses', () => {
+    const pathImages: MarkdownPathImages = { resolve: () => undefined }
+    const { container } = render(<MarkdownText text={LOCAL_IMAGE} pathImages={pathImages} />)
+    expect(container.querySelector('img')).toBeNull()
+    expect(screen.getByText('diagram')).toBeTruthy()
+  })
+
+  it('accepts data and blob vocabulary results', () => {
+    const data: MarkdownPathImages = { resolve: () => 'data:image/png;base64,AAAA' }
+    const blob: MarkdownPathImages = { resolve: () => 'blob:https://example.com/id' }
+    const dataRender = render(<MarkdownText text={LOCAL_IMAGE} pathImages={data} />)
+    const blobRender = render(<MarkdownText text={LOCAL_IMAGE} pathImages={blob} />)
+    expect(dataRender.container.querySelector('img')?.getAttribute('src'))
+      .toBe('data:image/png;base64,AAAA')
+    expect(blobRender.container.querySelector('img')?.getAttribute('src'))
+      .toBe('blob:https://example.com/id')
+  })
+
+  it('rejects non-absolute vocabulary results', () => {
+    for (const result of ['relative.png', '/api/image?path=%2Ftmp%2Fx.png', 'ftp://host/x.png']) {
+      const pathImages: MarkdownPathImages = { resolve: () => result }
+      const { container, unmount } = render(<MarkdownText text={LOCAL_IMAGE} pathImages={pathImages} />)
+      expect(container.querySelector('img')).toBeNull()
+      unmount()
+    }
+  })
+
+  it('leaves remote images untouched even when the vocabulary maps them', () => {
+    const remote = '![remote](https://example.com/a.png)'
+    const pathImages: MarkdownPathImages = { resolve: () => 'https://cdn.example.com/b.png' }
+    const { container } = render(<MarkdownText text={remote} pathImages={pathImages} />)
+    expect(container.querySelector('img')?.getAttribute('src')).toBe('https://example.com/a.png')
+  })
+
+  it('rewrites reference-style local image destinations', () => {
+    const reference = ['![diagram][fig]', '', '[fig]: /tmp/graph.png'].join('\n')
+    const pathImages: MarkdownPathImages = { resolve: mapping }
+    const { container } = render(<MarkdownText text={reference} pathImages={pathImages} />)
+    expect(container.querySelector('img')?.getAttribute('src'))
+      .toBe('https://cdn.example.com/graph.png')
+  })
+
+  it('applies the vocabulary only to settled renders, never while streaming', () => {
+    const pathImages: MarkdownPathImages = { resolve: mapping }
+    const { container, rerender } = render(
+      <MarkdownText text={LOCAL_IMAGE} streaming pathImages={pathImages} />,
+    )
+    // Streaming messages may still grow, so their prose keeps the inert alt
+    // fallback until the settled pass self-heals it.
+    expect(container.querySelector('img')).toBeNull()
+    rerender(<MarkdownText text={LOCAL_IMAGE} pathImages={pathImages} />)
+    expect(container.querySelector('img')?.getAttribute('src'))
+      .toBe('https://cdn.example.com/graph.png')
+  })
+})
diff --git a/packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx b/packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx
index 9eb4eb0265..bf1877c348 100644
--- a/packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx
@@ -22,6 +22,7 @@ function makeContext(): MarkdownRenderContext {
     streaming: false,
     labels: markdownLabels,
     fileMentions: undefined,
+    pathImages: undefined,
     targets: createReferenceTargets(),
     footnoteOrder: [],
     footnoteCounts: new Map(),

From 2aaa88ca1a6613929d14adcafdc7f901884f4a19 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 15:42:16 +0800
Subject: [PATCH 02/35] chore(docs): regenerate config catalog after
 session-controller import shift

---
 docs/config-catalog.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 18a564b0bb..058f3880c3 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -213,7 +213,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/api/session-controller/src/index.ts:69`](../packages/api/session-controller/src/index.ts)
+Source: [`packages/api/session-controller/src/index.ts:70`](../packages/api/session-controller/src/index.ts)
 
 <a id="deepseek-aidsh-api-settings-controller"></a>
 

From 0c823f4b6fea7313817933fbf480c46cfff58fd7 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 15:53:53 +0800
Subject: [PATCH 03/35] chore(docs): re-record config catalog translation-pair
 record

---
 docs/config-catalog.i18n.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 6b5a7fb4f6..54a5407c82 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: 18a564b0bbd19bba578f8f6f521b726b5bd9d0e3
+config-catalog.md: 058f3880c33097015d4b3472a1f94af38a965b2f
 config-catalog.zh.md: 0f63a6edfeaf9bd1d08cdb6615238519a0909a66

From 7a715e7919269f590161480266144bb9b6fa2a87 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 15:53:54 +0800
Subject: [PATCH 04/35] refactor(api): serve /api/file media by extension
 allowlist only

Drop the byte-signature sniff duplicated from fs/tool-fs's read_image tool:
the cross-file duplication gate forbids the clone, and no shared owner
exists without widening the attachment package's public API. The
extension allowlist keeps non-media content out; corrupt image payloads
fail in the browser, not on the route. Agent Note facts updated in the
same change.
---
 ...ession-prose-local-media-display.i18n.yaml |   4 +-
 ...09-07-session-prose-local-media-display.md |   7 +-
 ...07-session-prose-local-media-display.zh.md |   5 +-
 .../src/media-references.ts                   | 119 +++++-------------
 .../tests/media-references.host.spec.ts       |  42 +++----
 5 files changed, 57 insertions(+), 120 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
index db2a7595b2..3f40fc0de8 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.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 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
-2026-09-07-session-prose-local-media-display.md: e2693a6192cb78641d8a96937b39a4b06e884f04
-2026-09-07-session-prose-local-media-display.zh.md: bc0c62868e3ffab44fc3effc1030d9caee331f26
+2026-09-07-session-prose-local-media-display.md: b62b4d1e5c382540150fad3e2840e2f7bbe33dd2
+2026-09-07-session-prose-local-media-display.zh.md: 101f2d234b59e5efebd0f42fa39830747e9181fa
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
index e2693a6192..b62b4d1e5c 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
@@ -14,7 +14,7 @@ Local media paths in session prose render through one same-origin file route, wi
 
 - **Renderer seam (`ui-primitives`)**: `MarkdownText` gained a `MarkdownPathImages` vocabulary (`pathImages` prop) with the same settled-only gate as `fileMentions`: while a message streams, frozen cached blocks never bake in a vocabulary handler; the settled pass rewrites image destinations that fail the remote-URL allowlist, and a rewritten destination is emitted only when it is an absolute `http(s)`/`blob`/`data` URL. Without a vocabulary the renderer output is byte-identical to before.
 - **Chat wiring (`ui-chat`)**: `AssistantMarkdown` supplies a page-stable vocabulary mapping absolute POSIX paths to same-origin `/api/file?path=…` GETs (`local-path-media.ts`); non-HTTP transports (Electron `file://`) and relative/protocol-relative destinations stay inert.
-- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root, the file must be regular, and its extension must name an allowlisted media type (PNG/JPEG/GIF/WebP/AVIF, MP4/WebM/MOV/OGG, MP3/WAV/Ogg/M4A/AAC/FLAC); image extensions are additionally checked against their byte signature. Responses stream with HTTP range support (206/416) so video and audio can seek, and carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
+- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root, the file must be regular, and its extension must name an allowlisted media type (PNG/JPEG/GIF/WebP/AVIF, MP4/WebM/MOV/OGG, MP3/WAV/Ogg/M4A/AAC/FLAC); media bytes are never sniffed on this route. Responses stream with HTTP range support (206/416) so video and audio can seek, and carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
 
 The route is presentational and stateless: it never writes, follows no redirects, and returns 400/403/404/415/416 instead of approximating another file-serving behavior.
 
@@ -23,13 +23,14 @@ The route is presentational and stateless: it never writes, follows no redirects
 - **Register on the Typert gateway**: the gateway owns Remote RPC dispatch (endpoint claims, WebSocket mux, forwarded events), not file serving; placing the route there put HTTP presentation of workspace files into the RPC transport layer. Rejected and fully reverted.
 - **Register under `workspace-controller`**: that package owns workspace registry lifecycle (CRUD, ordering, feed), and shares only the registry as a policy data source. Rejected and fully reverted.
 - **Fetch bytes over the session RPC and show blob/data URLs**: attachment images already do this, but markdown rewriting needs a deterministic synchronous URL at render time (streaming freeze caches, memoization); an async round trip cannot be the render seam. Rejected.
-- **A per-image or image-only route**: media types share one path-and-contain policy; video/audio need range streaming anyway. One `/api/file` route with an extension allowlist plus signature checks for images covers all current and next media types. Rejected as narrower alternatives.
+- **A per-image or image-only route**: media types share one path-and-contain policy; video/audio need range streaming anyway. One `/api/file` route with an extension allowlist covers all current and next media types. Rejected as narrower alternatives.
+- **Byte-signature checks on image extensions**: rejected. The identical check already ships inside `fs/tool-fs`'s `read_image` tool, the repository's cross-file duplication gate forbids cloning it here, and no shared owner exists without widening the attachment package's public API for one helper. The extension allowlist already keeps non-media content out, and a corrupt image payload fails in the browser, not on the route.
 - **Per-request interactive authorization, client-negotiated endpoints, or arbitrary host paths**: the rewrite is presentation; the route re-validates every request and limits readable bytes to registered workspace roots and allowlisted media, and the same-origin endpoint is a fixed channel contract rather than a negotiated capability. Rejected for security and determinism reasons.
 
 ## Consequences
 
 - Assistant prose that references workspace-contained image files now displays them in Web chat; previously inert alt text disappears only where the host can serve the bytes.
-- Policy is enforced host-side per request; the client vocabulary never expands what the route allows.
+- Policy is enforced host-side per request; the client vocabulary never expands what the route allows. Media typing trusts the extension allowlist; byte-signature validation stays with the `read_image` tool that owns it.
 - Scope is deliberately narrow: only files under registered workspace roots with allowlisted media types are served; anything else keeps the authored fallback. Trajectory and tool-card markdown consumers do not pass a vocabulary yet, and video/audio markdown nodes are not rendered as `<video>`/`<audio>` yet — the URL layer already supports them.
 - The client hardcodes the `/api/file` endpoint as a same-origin channel contract; this is stable by construction because the page is served by the same host that mounts the route.
 - Related history: the archived note [model-readable image paths](../../archived/feature/2026-08-21-model-readable-image-paths.md) decided the model-facing side of local image paths; this note owns the user-facing display side and does not supersede it.
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
index bc0c62868e..101f2d234b 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
@@ -23,13 +23,14 @@ Assistant 正文有时用本地文件系统路径引用图片（markdown `![](/U
 - **注册到 Typert gateway**：gateway 负责 Remote RPC 分发（endpoint 认领、WebSocket mux、转发事件），不负责文件服务；把路由放那里等于把 workspace 文件的 HTTP 呈现塞进 RPC 传输层。否决并完整回滚。
 - **注册到 `workspace-controller`**：该包负责 workspace 注册表生命周期（CRUD、排序、feed），与文件呈现只共享 registry 这一政策数据源。否决并完整回滚。
 - **经会话 RPC 取字节后显示 blob/data URL**：附件图片已如此工作，但 markdown 重写需要渲染时确定性同步 URL（流式冻结缓存、memo 化）；异步往返不能成为渲染缝。否决。
-- **逐图片或仅图片专用路由**：媒体类型共享同一条「路径 + 包含」政策，视频/音频本就需要 Range 流式；一条 `/api/file` 路由加扩展名 allowlist（图片另验签名）即可覆盖现有与后续媒体类型。作为更窄的方案被否决。
+- **逐图片或仅图片专用路由**：媒体类型共享同一条「路径 + 包含」政策，视频/音频本就需要 Range 流式；一条 `/api/file` 路由加扩展名 allowlist 即可覆盖现有与后续媒体类型。作为更窄的方案被否决。
+- **图片扩展的字节签名校验**：否决。相同检查已在 `fs/tool-fs` 的 `read_image` 工具内实现，仓库的跨文件克隆门禁止在此复制，而为单个辅助函数加宽 attachment 包公开 API 没有共享归属。扩展名 allowlist 已把非媒体内容挡在门外，损坏的图片载荷失败发生在浏览器侧而不是路由上。
 - **每请求交互授权、客户端协商端点或任意 Host 路径**：重写只是呈现；路由对每次请求复验，可读字节限制在注册 workspace 根与 allowlist 媒体内；同源端点是固定通道契约而非协商能力。出于安全与确定性否决。
 
 ## Consequences
 
 - 引用 workspace 内图片文件的 Assistant 正文现在可在 Web 聊天中显示；原先惰性的 alt 文本只在 Host 无法提供字节时保留。
-- 政策在 Host 端每次请求强制；客户端词表不会扩大路由放行的范围。
+- 政策在 Host 端每次请求强制；客户端词表不会扩大路由放行的范围。媒体类型判定信任扩展名 allowlist；字节签名校验保留在其所有者 `read_image` 工具中。
 - 范围刻意收窄：只服务注册 workspace 根内、媒体 allowlist 内的文件；其它一律保持作者原样的回退。Trajectory 与工具卡片等 markdown 消费方尚未传词表，视频/音频 markdown 节点也尚未渲染为 `<video>`/`<audio>`——URL 层已为它们准备好。
 - 客户端把 `/api/file` 硬编码为同源通道契约；由于页面与挂载路由的 Host 同源，该契约按构造稳定。
 - 相关历史：已归档笔记 [model-readable image paths](../../archived/feature/2026-08-21-model-readable-image-paths.md) 决定本地图片路径面向模型的一侧；本笔记拥有面向用户展示的一侧，不构成对其的取代。
diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
index 56d47d7d94..3deef7a29c 100644
--- a/packages/api/session-controller/src/media-references.ts
+++ b/packages/api/session-controller/src/media-references.ts
@@ -10,8 +10,9 @@
  * - its canonical location must lie inside a registered workspace root
  *   (`ctx.workspaceRegistry`); no other directory is readable;
  * - the file must exist and be a regular file;
- * - its extension must name an allowlisted media type; image extensions are
- *   additionally checked against the file signature;
+ * - its extension must name an allowlisted media type (media bytes are never
+ *   sniffed here: the allowlist keeps non-media content out, and browsers
+ *   already reject corrupt image payloads);
  * - responses are private, uncached, sniff-proof, and support HTTP range
  *   requests so `<video>`/`<audio>` can seek without buffering the file.
  *
@@ -26,7 +27,7 @@
  */
 
 import { createReadStream } from 'node:fs'
-import { open, realpath, stat } from 'node:fs/promises'
+import { realpath, stat } from 'node:fs/promises'
 import { extname, isAbsolute, sep } from 'node:path'
 import { Readable } from 'node:stream'
 import type { Context } from '@deepseek-ai/cordis'
@@ -62,64 +63,14 @@ const MEDIA_TYPES: Readonly<Record<string, string>> = {
   '.flac': 'audio/flac',
 }
 
-/** Image extensions whose bytes must match their declared signature. */
-const SNIFFED_IMAGE_TYPES: Readonly<Record<string, string>> = {
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-}
-
-const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const
-const JPEG_SIGNATURE = [0xff, 0xd8, 0xff] as const
-const GIF_87_SIGNATURE = 'GIF87a' as const
-const GIF_89_SIGNATURE = 'GIF89a' as const
-const RIFF_SIGNATURE = 'RIFF' as const
-const WEBP_SIGNATURE = 'WEBP' as const
-
-function startsWithBytes(data: Uint8Array, offset: number, expected: readonly number[]): boolean {
-  if (data.byteLength < offset + expected.length) return false
-  return expected.every((byte, index) => data[offset + index] === byte)
-}
-
-function startsWithAscii(data: Uint8Array, offset: number, value: string): boolean {
-  if (data.byteLength < offset + value.length) return false
-  for (let index = 0; index < value.length; index += 1) {
-    if (data[offset + index] !== value.charCodeAt(index)) return false
-  }
-  return true
-}
-
-/**
- * Check one byte buffer against the sniffed image signatures.
- * @param data - Leading file bytes (12 suffice for every supported type).
- * @returns the matched media type, or undefined for other bytes.
- */
-export function sniffImageMediaType(data: Uint8Array): string | undefined {
-  if (startsWithBytes(data, 0, PNG_SIGNATURE)) return 'image/png'
-  if (startsWithBytes(data, 0, JPEG_SIGNATURE)) return 'image/jpeg'
-  if (startsWithAscii(data, 0, GIF_87_SIGNATURE) || startsWithAscii(data, 0, GIF_89_SIGNATURE)) {
-    return 'image/gif'
-  }
-  if (startsWithAscii(data, 0, RIFF_SIGNATURE) && startsWithAscii(data, 8, WEBP_SIGNATURE)) {
-    return 'image/webp'
-  }
-  return undefined
-}
-
 /**
  * The content type a file path may be served as, or undefined when the
  * extension is not an allowlisted media type.
  * @param path - Canonical file path (extension only is read).
- * @param bytes - Leading file bytes for signature-checked image extensions.
  * @returns the content type, or undefined to refuse the file.
  */
-export function mediaTypeForPath(path: string, bytes: Uint8Array): string | undefined {
-  const extension = extname(path).toLowerCase()
-  const sniffed = SNIFFED_IMAGE_TYPES[extension]
-  if (sniffed !== undefined) return sniffImageMediaType(bytes) === sniffed ? sniffed : undefined
-  return MEDIA_TYPES[extension]
+export function mediaTypeForPath(path: string): string | undefined {
+  return MEDIA_TYPES[extname(path).toLowerCase()]
 }
 
 /** One resolved byte-range within a file; `full` streams the whole file. */
@@ -190,47 +141,35 @@ export async function serveMediaReference(
     return new Response('not found', { status: 404 })
   }
   if (!info.isFile()) return new Response('not a regular file', { status: 403 })
-  let handle
-  try {
-    handle = await open(canonical, 'r')
-  } catch {
-    return new Response('not found', { status: 404 })
+  const mediaType = mediaTypeForPath(canonical)
+  if (mediaType === undefined) {
+    return new Response('not an allowlisted media type', { status: 415 })
   }
-  try {
-    const headBytes = new Uint8Array(12)
-    const { buffer } = await handle.read(headBytes, 0, 12, 0)
-    const mediaType = mediaTypeForPath(canonical, new Uint8Array(buffer))
-    if (mediaType === undefined) {
-      return new Response('not an allowlisted media type', { status: 415 })
-    }
-    const range = parseByteRange(request.headers.get('range'), info.size)
-    if (range === undefined) {
-      const headers: Record<string, string> = {
-        'Content-Range': 'bytes */' + String(info.size),
-        'Cache-Control': 'private, no-store',
-        'X-Content-Type-Options': 'nosniff',
-      }
-      return new Response(null, { status: 416, headers })
-    }
-    const partial = range.kind === 'partial'
-    const start = partial ? range.start : 0
-    const end = partial ? range.end : info.size - 1
-    const body: ReadableStream<Uint8Array> = Readable.toWeb(
-      createReadStream(canonical, { start, end }),
-    ) as ReadableStream<Uint8Array>
+  const range = parseByteRange(request.headers.get('range'), info.size)
+  if (range === undefined) {
     const headers: Record<string, string> = {
-      'Content-Type': mediaType,
-      'Content-Length': String(partial ? end - start + 1 : info.size),
-      'Accept-Ranges': 'bytes',
+      'Content-Range': 'bytes */' + String(info.size),
       'Cache-Control': 'private, no-store',
       'X-Content-Type-Options': 'nosniff',
     }
-    if (partial) headers['Content-Range'] = 'bytes ' + start + '-' + end + '/' + String(info.size)
-    const head = request.method === 'HEAD'
-    return new Response(head ? null : body, { status: partial ? 206 : 200, headers })
-  } finally {
-    await handle.close()
+    return new Response(null, { status: 416, headers })
   }
+  const partial = range.kind === 'partial'
+  const start = partial ? range.start : 0
+  const end = partial ? range.end : info.size - 1
+  const body: ReadableStream<Uint8Array> = Readable.toWeb(
+    createReadStream(canonical, { start, end }),
+  ) as ReadableStream<Uint8Array>
+  const headers: Record<string, string> = {
+    'Content-Type': mediaType,
+    'Content-Length': String(partial ? end - start + 1 : info.size),
+    'Accept-Ranges': 'bytes',
+    'Cache-Control': 'private, no-store',
+    'X-Content-Type-Options': 'nosniff',
+  }
+  if (partial) headers['Content-Range'] = 'bytes ' + start + '-' + end + '/' + String(info.size)
+  const head = request.method === 'HEAD'
+  return new Response(head ? null : body, { status: partial ? 206 : 200, headers })
 }
 
 /**
diff --git a/packages/api/session-controller/tests/media-references.host.spec.ts b/packages/api/session-controller/tests/media-references.host.spec.ts
index 429b90e8d5..0c58d9b256 100644
--- a/packages/api/session-controller/tests/media-references.host.spec.ts
+++ b/packages/api/session-controller/tests/media-references.host.spec.ts
@@ -8,7 +8,6 @@ import {
   serveMediaReference,
   mediaTypeForPath,
   parseByteRange,
-  sniffImageMediaType,
   type MediaReferenceRegistry,
 } from '../src/media-references.ts'
 
@@ -29,28 +28,19 @@ function apiRequest(path: string, init?: RequestInit): Request {
   return new Request(url, init)
 }
 
-describe('sniffImageMediaType and mediaTypeForPath', () => {
-  it('identifies supported image signatures', () => {
-    expect(sniffImageMediaType(PNG_BYTES)).toBe('image/png')
-    expect(sniffImageMediaType(new Uint8Array([0xff, 0xd8, 0xff, 0xe0]))).toBe('image/jpeg')
-    expect(sniffImageMediaType(new TextEncoder().encode('GIF89a...'))).toBe('image/gif')
-    expect(sniffImageMediaType(new TextEncoder().encode('RIFF0000WEBPVP8 '))).toBe('image/webp')
-    expect(sniffImageMediaType(TEXT_BYTES)).toBeUndefined()
+describe('mediaTypeForPath', () => {
+  it('maps allowlisted media extensions', () => {
+    expect(mediaTypeForPath('/w/graph.png')).toBe('image/png')
+    expect(mediaTypeForPath('/w/graph.jpg')).toBe('image/jpeg')
+    expect(mediaTypeForPath('/w/clip.mp4')).toBe('video/mp4')
+    expect(mediaTypeForPath('/w/clip.webm')).toBe('video/webm')
+    expect(mediaTypeForPath('/w/song.mp3')).toBe('audio/mpeg')
   })
 
-  it('maps allowlisted media extensions, sniffing image extensions', () => {
-    expect(mediaTypeForPath('/w/graph.png', PNG_BYTES)).toBe('image/png')
-    expect(mediaTypeForPath('/w/graph.jpg', new Uint8Array([0xff, 0xd8, 0xff]))).toBe('image/jpeg')
-    expect(mediaTypeForPath('/w/clip.mp4', MP4_BYTES)).toBe('video/mp4')
-    expect(mediaTypeForPath('/w/clip.webm', MP4_BYTES)).toBe('video/webm')
-    expect(mediaTypeForPath('/w/song.mp3', TEXT_BYTES)).toBe('audio/mpeg')
-  })
-
-  it('refuses non-media extensions and mislabeled image bytes', () => {
-    expect(mediaTypeForPath('/w/note.txt', TEXT_BYTES)).toBeUndefined()
-    expect(mediaTypeForPath('/w/app.exe', TEXT_BYTES)).toBeUndefined()
-    expect(mediaTypeForPath('/w/shell.svg', TEXT_BYTES)).toBeUndefined()
-    expect(mediaTypeForPath('/w/fake.png', TEXT_BYTES)).toBeUndefined()
+  it('refuses non-media extensions', () => {
+    expect(mediaTypeForPath('/w/note.txt')).toBeUndefined()
+    expect(mediaTypeForPath('/w/app.exe')).toBeUndefined()
+    expect(mediaTypeForPath('/w/shell.svg')).toBeUndefined()
   })
 })
 
@@ -179,17 +169,23 @@ describe('serveMediaReference', () => {
     }
   })
 
-  it('refuses directories and non-allowlisted or mislabeled content', async () => {
+  it('refuses directories and non-allowlisted extensions', async () => {
     const directory = await serveMediaReference(apiRequest(root), registry(root))
     expect(directory.status).toBe(403)
 
     const text = join(root, 'note.txt')
     await writeFile(text, TEXT_BYTES)
     expect((await serveMediaReference(apiRequest(text), registry(root))).status).toBe(415)
+  })
 
+  it('serves allowlisted extensions regardless of payload bytes', async () => {
+    // Media bytes are not sniffed here: the extension allowlist decides what
+    // is served, and a corrupt image payload stays a browser-side failure.
     const fake = join(root, 'fake.png')
     await writeFile(fake, TEXT_BYTES)
-    expect((await serveMediaReference(apiRequest(fake), registry(root))).status).toBe(415)
+    const response = await serveMediaReference(apiRequest(fake), registry(root))
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toBe('image/png')
   })
 
   it('follows a symlink into the workspace for the containment check', async () => {

From b685a9a6b09d8dd302f8fc0124564d4680f0f22f Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 16:02:14 +0800
Subject: [PATCH 05/35] fix(api): satisfy oxlint same-type operand rule in
 range header

---
 packages/api/session-controller/src/media-references.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
index 3deef7a29c..7d106f02d7 100644
--- a/packages/api/session-controller/src/media-references.ts
+++ b/packages/api/session-controller/src/media-references.ts
@@ -167,7 +167,7 @@ export async function serveMediaReference(
     'Cache-Control': 'private, no-store',
     'X-Content-Type-Options': 'nosniff',
   }
-  if (partial) headers['Content-Range'] = 'bytes ' + start + '-' + end + '/' + String(info.size)
+  if (partial) headers['Content-Range'] = 'bytes ' + String(start) + '-' + String(end) + '/' + String(info.size)
   const head = request.method === 'HEAD'
   return new Response(head ? null : body, { status: partial ? 206 : 200, headers })
 }

From f81c5072bdd885b3f8a8d438337e6bb49aeaf7be Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 16:20:10 +0800
Subject: [PATCH 06/35] fix(api): close coverage edges in media-references
 route

---
 packages/api/session-controller/src/media-references.ts   | 8 ++------
 .../tests/media-references.host.spec.ts                   | 2 ++
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
index 7d106f02d7..42e225cbdc 100644
--- a/packages/api/session-controller/src/media-references.ts
+++ b/packages/api/session-controller/src/media-references.ts
@@ -126,20 +126,16 @@ export async function serveMediaReference(
   }
   if (registry === undefined) return new Response('file serving is unavailable', { status: 403 })
   let canonical: string
+  let info
   try {
     canonical = await realpath(path)
+    info = await stat(canonical)
   } catch {
     return new Response('not found', { status: 404 })
   }
   const insideWorkspace = registry.list().some(root =>
     canonical === root.path || canonical.startsWith(root.path + sep))
   if (!insideWorkspace) return new Response('outside workspace roots', { status: 403 })
-  let info
-  try {
-    info = await stat(canonical)
-  } catch {
-    return new Response('not found', { status: 404 })
-  }
   if (!info.isFile()) return new Response('not a regular file', { status: 403 })
   const mediaType = mediaTypeForPath(canonical)
   if (mediaType === undefined) {
diff --git a/packages/api/session-controller/tests/media-references.host.spec.ts b/packages/api/session-controller/tests/media-references.host.spec.ts
index 0c58d9b256..e6d39446d9 100644
--- a/packages/api/session-controller/tests/media-references.host.spec.ts
+++ b/packages/api/session-controller/tests/media-references.host.spec.ts
@@ -55,6 +55,8 @@ describe('parseByteRange', () => {
 
   it('refuses malformed and unsatisfiable ranges', () => {
     expect(parseByteRange('bytes=abc', 100)).toBeUndefined()
+    expect(parseByteRange('bytes=-', 100)).toBeUndefined()
+    expect(parseByteRange('bytes=-0', 100)).toBeUndefined()
     expect(parseByteRange('bytes=5-2', 100)).toBeUndefined()
     expect(parseByteRange('bytes=100-', 100)).toBeUndefined()
     expect(parseByteRange('bytes=0-', 0)).toBeUndefined()

From 4b009e7f942425f537ece03b112b6220cb0e1abd Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 16:35:15 +0800
Subject: [PATCH 07/35] refactor(api): shrink media-references surface and
 reuse maintained libs

- /api/file module now exports only the SessionMediaReferences plugin
  contribution; MIME and range policy helpers are module-private and
  exercised entirely through the registered route.
- Replace the hand-rolled media extension table with mime-types (served
  categories image/video/audio, excluding image/svg+xml) and the
  hand-rolled Range parser with range-parser; keep the fail-closed
  workspace containment policy.
- Spec rewritten as route-level behavior tests (12 cases) covering the
  same branches; Agent Note facts updated in the same change.
---
 ...ession-prose-local-media-display.i18n.yaml |   4 +-
 ...09-07-session-prose-local-media-display.md |   2 +-
 ...07-session-prose-local-media-display.zh.md |   2 +-
 THIRD_PARTY_NOTICES.md                        |   4 +
 packages/api/session-controller/package.json  |   8 +-
 .../src/media-references.ts                   | 146 +++------
 .../tests/media-references.host.spec.ts       | 310 ++++++++----------
 pnpm-lock.yaml                                |  17 +
 8 files changed, 223 insertions(+), 270 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
index 3f40fc0de8..ca30dccd30 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.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 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
-2026-09-07-session-prose-local-media-display.md: b62b4d1e5c382540150fad3e2840e2f7bbe33dd2
-2026-09-07-session-prose-local-media-display.zh.md: 101f2d234b59e5efebd0f42fa39830747e9181fa
+2026-09-07-session-prose-local-media-display.md: 79bde26e1890bf463f7a954e9b84d81e87ecbd1e
+2026-09-07-session-prose-local-media-display.zh.md: af852a627888353589e4a88a4198bfb32760adbe
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
index b62b4d1e5c..79bde26e18 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
@@ -14,7 +14,7 @@ Local media paths in session prose render through one same-origin file route, wi
 
 - **Renderer seam (`ui-primitives`)**: `MarkdownText` gained a `MarkdownPathImages` vocabulary (`pathImages` prop) with the same settled-only gate as `fileMentions`: while a message streams, frozen cached blocks never bake in a vocabulary handler; the settled pass rewrites image destinations that fail the remote-URL allowlist, and a rewritten destination is emitted only when it is an absolute `http(s)`/`blob`/`data` URL. Without a vocabulary the renderer output is byte-identical to before.
 - **Chat wiring (`ui-chat`)**: `AssistantMarkdown` supplies a page-stable vocabulary mapping absolute POSIX paths to same-origin `/api/file?path=…` GETs (`local-path-media.ts`); non-HTTP transports (Electron `file://`) and relative/protocol-relative destinations stay inert.
-- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root, the file must be regular, and its extension must name an allowlisted media type (PNG/JPEG/GIF/WebP/AVIF, MP4/WebM/MOV/OGG, MP3/WAV/Ogg/M4A/AAC/FLAC); media bytes are never sniffed on this route. Responses stream with HTTP range support (206/416) so video and audio can seek, and carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
+- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root, the file must be regular, and its MIME type must belong to the served categories image/video/audio (resolved by the `mime-types` package, excluding `image/svg+xml`); media bytes are never sniffed on this route. Responses stream with HTTP range support parsed by the `range-parser` package (206/416) so video and audio can seek, and carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
 
 The route is presentational and stateless: it never writes, follows no redirects, and returns 400/403/404/415/416 instead of approximating another file-serving behavior.
 
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
index 101f2d234b..af852a6278 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
@@ -24,7 +24,7 @@ Assistant 正文有时用本地文件系统路径引用图片（markdown `![](/U
 - **注册到 `workspace-controller`**：该包负责 workspace 注册表生命周期（CRUD、排序、feed），与文件呈现只共享 registry 这一政策数据源。否决并完整回滚。
 - **经会话 RPC 取字节后显示 blob/data URL**：附件图片已如此工作，但 markdown 重写需要渲染时确定性同步 URL（流式冻结缓存、memo 化）；异步往返不能成为渲染缝。否决。
 - **逐图片或仅图片专用路由**：媒体类型共享同一条「路径 + 包含」政策，视频/音频本就需要 Range 流式；一条 `/api/file` 路由加扩展名 allowlist 即可覆盖现有与后续媒体类型。作为更窄的方案被否决。
-- **图片扩展的字节签名校验**：否决。相同检查已在 `fs/tool-fs` 的 `read_image` 工具内实现，仓库的跨文件克隆门禁止在此复制，而为单个辅助函数加宽 attachment 包公开 API 没有共享归属。扩展名 allowlist 已把非媒体内容挡在门外，损坏的图片载荷失败发生在浏览器侧而不是路由上。
+- **手写 MIME 表、Range 解析与图片签名校验**：否决，改用维护中的包（`mime-types`、`range-parser`）且不做嗅探。其中字节签名校验被否决的理由是：相同检查已在 `fs/tool-fs` 的 `read_image` 工具内实现，仓库的跨文件克隆门禁止在此复制，而为单个辅助函数加宽 attachment 包公开 API 没有共享归属。扩展名 allowlist 已把非媒体内容挡在门外，损坏的图片载荷失败发生在浏览器侧而不是路由上。
 - **每请求交互授权、客户端协商端点或任意 Host 路径**：重写只是呈现；路由对每次请求复验，可读字节限制在注册 workspace 根与 allowlist 媒体内；同源端点是固定通道契约而非协商能力。出于安全与确定性否决。
 
 ## Consequences
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 1be29ddbaf..c0000c969f 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -89,11 +89,13 @@ External packages that a workspace package resolves at runtime. The tier covers
 | [`micromark-util-sanitize-uri`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-sanitize-uri) | MIT |
 | [`micromark-util-symbol`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-symbol) | MIT |
 | [`micromark-util-types`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-types) | MIT |
+| [`mime-types`](https://github.com/jshttp/mime-types) | MIT |
 | [`negotiator`](https://github.com/jshttp/negotiator) | MIT |
 | [`node-addon-require-builtin`](https://www.npmjs.com/package/node-addon-require-builtin) | MIT |
 | [`node-pty`](https://github.com/microsoft/node-pty) | MIT |
 | [`open`](https://github.com/sindresorhus/open) | MIT |
 | [`picomatch`](https://github.com/micromatch/picomatch) | MIT |
+| [`range-parser`](https://github.com/jshttp/range-parser) | MIT |
 | [`react`](https://github.com/facebook/react) | MIT |
 | [`react-dom`](https://github.com/facebook/react) | MIT |
 | [`readable-stream`](https://github.com/nodejs/readable-stream) | MIT |
@@ -152,9 +154,11 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`@types/fs-ext`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/js-yaml`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/jsdom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/mime-types`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/negotiator`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/node`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/picomatch`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/range-parser`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/react-dom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/readable-stream`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
diff --git a/packages/api/session-controller/package.json b/packages/api/session-controller/package.json
index 93846093fe..2b3d08e98a 100644
--- a/packages/api/session-controller/package.json
+++ b/packages/api/session-controller/package.json
@@ -71,6 +71,8 @@
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-deque": "workspace:^",
     "@deepseek-ai/schemastery": "workspace:^",
+    "mime-types": "^3.0.2",
+    "range-parser": "^1.3.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -122,8 +124,8 @@
     "@deepseek-ai/dsh-attachment": "workspace:^",
     "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-file-upload": "workspace:^",
-    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-file-reference": "workspace:^",
     "@deepseek-ai/dsh-jobs": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
@@ -146,6 +148,8 @@
     "@deepseek-ai/dsh-util-crypto": "workspace:^",
     "@deepseek-ai/dsh-util-time": "workspace:^",
     "@deepseek-ai/dsh-util-workspace-path": "workspace:^",
-    "@deepseek-ai/dsh-workspace": "workspace:^"
+    "@deepseek-ai/dsh-workspace": "workspace:^",
+    "@types/mime-types": "^3.0.1",
+    "@types/range-parser": "^1.2.7"
   }
 }
diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
index 42e225cbdc..3130b52050 100644
--- a/packages/api/session-controller/src/media-references.ts
+++ b/packages/api/session-controller/src/media-references.ts
@@ -10,121 +10,67 @@
  * - its canonical location must lie inside a registered workspace root
  *   (`ctx.workspaceRegistry`); no other directory is readable;
  * - the file must exist and be a regular file;
- * - its extension must name an allowlisted media type (media bytes are never
- *   sniffed here: the allowlist keeps non-media content out, and browsers
- *   already reject corrupt image payloads);
- * - responses are private, uncached, sniff-proof, and support HTTP range
- *   requests so `<video>`/`<audio>` can seek without buffering the file.
+ * - its MIME type (resolved by `mime-types`) must belong to the served
+ *   categories image/video/audio, excluding `image/svg+xml`; media bytes are
+ *   never sniffed here, and a corrupt payload fails in the browser;
+ * - responses are private, uncached, sniff-proof, and stream with HTTP range
+ *   support (parsed by `range-parser`) so `<video>`/`<audio>` can seek.
  *
  * The route is deliberately presentational: it never writes and follows no
  * redirects, returning 400/403/404/415/416 instead of falling back to any
  * other file-serving behavior.
  *
- * The package entry imports only `SessionMediaReferences`; the remaining
- * module exports exist for same-package unit tests and are not part of the
- * package's public API.
+ * Only the plugin contribution below is exported: package-internal policy
+ * helpers stay module-private and are exercised through the registered route.
  * @module @deepseek-ai/dsh-api-session-controller/media-references
  */
 
 import { createReadStream } from 'node:fs'
 import { realpath, stat } from 'node:fs/promises'
-import { extname, isAbsolute, sep } from 'node:path'
+import { isAbsolute, sep } from 'node:path'
 import { Readable } from 'node:stream'
 import type { Context } from '@deepseek-ai/cordis'
 // Cordis `ctx.connection` typing and the fetch-route contract.
 import type {} from '@deepseek-ai/dsh-client-connection'
 // Cordis `ctx.workspaceRegistry` typing.
 import type {} from '@deepseek-ai/dsh-workspace'
+import mime from 'mime-types'
+import rangeParser from 'range-parser'
 
-/** Registered-workspace view the route reads; see the `workspaceRegistry` service. */
-export interface MediaReferenceRegistry {
-  /** List registered workspaces with their canonical root directories. */
-  list(): readonly { path: string }[]
-}
-
-/** Media extensions the route serves, mapped to their content types. */
-const MEDIA_TYPES: Readonly<Record<string, string>> = {
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.mp4': 'video/mp4',
-  '.webm': 'video/webm',
-  '.mov': 'video/quicktime',
-  '.ogv': 'video/ogg',
-  '.mp3': 'audio/mpeg',
-  '.wav': 'audio/wav',
-  '.ogg': 'audio/ogg',
-  '.oga': 'audio/ogg',
-  '.m4a': 'audio/mp4',
-  '.aac': 'audio/aac',
-  '.flac': 'audio/flac',
-}
+/** Media categories this route serves. */
+const MEDIA_CATEGORIES: ReadonlySet<string> = new Set(['image', 'video', 'audio'])
+/** Category matches that still must not be served. */
+const DENIED_MEDIA_TYPES: ReadonlySet<string> = new Set(['image/svg+xml'])
 
 /**
- * The content type a file path may be served as, or undefined when the
- * extension is not an allowlisted media type.
+ * The content type a file path may be served as, or undefined when it is not
+ * an allowlisted media type.
  * @param path - Canonical file path (extension only is read).
  * @returns the content type, or undefined to refuse the file.
  */
-export function mediaTypeForPath(path: string): string | undefined {
-  return MEDIA_TYPES[extname(path).toLowerCase()]
-}
-
-/** One resolved byte-range within a file; `full` streams the whole file. */
-type ByteRange =
-  | { readonly kind: 'full' }
-  | { readonly kind: 'partial'; readonly start: number; readonly end: number }
-
-/**
- * Parse one single-range `Range` header value against the file size.
- * @param header - Raw `Range` request header, or null when absent.
- * @param size - Total file size in bytes.
- * @returns the byte range to serve, or undefined when the header names no
- * satisfiable single range (the caller answers 416 with a `bytes *\/size`
- * Content-Range header).
- */
-export function parseByteRange(header: string | null, size: number): ByteRange | undefined {
-  if (header === null) return { kind: 'full' }
-  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim())
-  if (match === null) return undefined
-  const startText = match[1]
-  const endText = match[2]
-  if (startText === '' && endText === '') return undefined
-  let start: number
-  let end: number
-  if (startText === '') {
-    // Suffix range: the last N bytes.
-    const length = Number(endText)
-    if (length === 0) return undefined
-    start = Math.max(size - length, 0)
-    end = size - 1
-  } else {
-    start = Number(startText)
-    end = endText === '' ? size - 1 : Number(endText)
-  }
-  if (start > end || start >= size) return undefined
-  return { kind: 'partial', start, end: Math.min(end, size - 1) }
+function mediaTypeForPath(path: string): string | undefined {
+  const looked = mime.lookup(path)
+  if (looked === false) return undefined
+  if (DENIED_MEDIA_TYPES.has(looked)) return undefined
+  const category = looked.slice(0, looked.indexOf('/'))
+  return MEDIA_CATEGORIES.has(category) ? looked : undefined
 }
 
 /**
  * Serve one workspace-contained media file over the shared API channel.
  * @param request - Authenticated fetch-route request (GET or HEAD).
- * @param registry - Workspace registry; absent (or empty) denies everything.
+ * @param roots - Registered workspace root directories.
  * @returns A streaming media response or a fail-closed status.
  */
-export async function serveMediaReference(
+async function serveMediaReference(
   request: Request,
-  registry: MediaReferenceRegistry | undefined,
+  roots: readonly { path: string }[],
 ): Promise<Response> {
   const path = new URL(request.url).searchParams.get('path')
   if (path === null || path.length === 0) return new Response('missing path', { status: 400 })
   if (path.includes('\0') || !isAbsolute(path)) {
     return new Response('absolute path required', { status: 400 })
   }
-  if (registry === undefined) return new Response('file serving is unavailable', { status: 403 })
   let canonical: string
   let info
   try {
@@ -133,7 +79,7 @@ export async function serveMediaReference(
   } catch {
     return new Response('not found', { status: 404 })
   }
-  const insideWorkspace = registry.list().some(root =>
+  const insideWorkspace = roots.some(root =>
     canonical === root.path || canonical.startsWith(root.path + sep))
   if (!insideWorkspace) return new Response('outside workspace roots', { status: 403 })
   if (!info.isFile()) return new Response('not a regular file', { status: 403 })
@@ -141,29 +87,41 @@ export async function serveMediaReference(
   if (mediaType === undefined) {
     return new Response('not an allowlisted media type', { status: 415 })
   }
-  const range = parseByteRange(request.headers.get('range'), info.size)
-  if (range === undefined) {
-    const headers: Record<string, string> = {
-      'Content-Range': 'bytes */' + String(info.size),
-      'Cache-Control': 'private, no-store',
-      'X-Content-Type-Options': 'nosniff',
+  const total = info.size
+  const rangeHeader = request.headers.get('range')
+  let start = 0
+  let end = total - 1
+  let partial = false
+  if (rangeHeader !== null) {
+    const parsed = rangeParser(total, rangeHeader)
+    // -1 (unsatisfiable) and -2 (malformed) both answer the same terminal
+    // way; array results always carry at least one range.
+    const first = Array.isArray(parsed) ? parsed[0] : undefined
+    if (first === undefined) {
+      const headers: Record<string, string> = {
+        'Content-Range': 'bytes */' + String(total),
+        'Cache-Control': 'private, no-store',
+        'X-Content-Type-Options': 'nosniff',
+      }
+      return new Response(null, { status: 416, headers })
     }
-    return new Response(null, { status: 416, headers })
+    start = first.start
+    end = first.end
+    partial = true
   }
-  const partial = range.kind === 'partial'
-  const start = partial ? range.start : 0
-  const end = partial ? range.end : info.size - 1
   const body: ReadableStream<Uint8Array> = Readable.toWeb(
-    createReadStream(canonical, { start, end }),
+    createReadStream(canonical, partial ? { start, end } : undefined),
   ) as ReadableStream<Uint8Array>
   const headers: Record<string, string> = {
     'Content-Type': mediaType,
-    'Content-Length': String(partial ? end - start + 1 : info.size),
+    'Content-Length': String(partial ? end - start + 1 : total),
     'Accept-Ranges': 'bytes',
     'Cache-Control': 'private, no-store',
     'X-Content-Type-Options': 'nosniff',
   }
-  if (partial) headers['Content-Range'] = 'bytes ' + String(start) + '-' + String(end) + '/' + String(info.size)
+  if (partial) {
+    headers['Content-Range'] = 'bytes ' + String(start) + '-' + String(end) + '/' + String(total)
+  }
   const head = request.method === 'HEAD'
   return new Response(head ? null : body, { status: partial ? 206 : 200, headers })
 }
@@ -186,7 +144,7 @@ export const SessionMediaReferences = {
       path: '/api/file',
       methods: ['GET', 'HEAD'],
       requestBody: 'buffered',
-      fetch: request => serveMediaReference(request, ctx.workspaceRegistry),
+      fetch: request => serveMediaReference(request, ctx.workspaceRegistry.list()),
     }), 'session-controller: /api/file')
   },
 }
diff --git a/packages/api/session-controller/tests/media-references.host.spec.ts b/packages/api/session-controller/tests/media-references.host.spec.ts
index e6d39446d9..74bfb05898 100644
--- a/packages/api/session-controller/tests/media-references.host.spec.ts
+++ b/packages/api/session-controller/tests/media-references.host.spec.ts
@@ -3,83 +3,70 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import {
-  SessionMediaReferences,
-  serveMediaReference,
-  mediaTypeForPath,
-  parseByteRange,
-  type MediaReferenceRegistry,
-} from '../src/media-references.ts'
+import { SessionMediaReferences } from '../src/media-references.ts'
 
-const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3, 4, 5, 6])
+const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3, 4, 5, 6, 7, 8])
 const TEXT_BYTES = new Uint8Array([1, 2, 3, 4])
 const MP4_BYTES = new TextEncoder().encode('....ftypmp42....moov....')
 
-function registry(root: string): MediaReferenceRegistry {
-  return { list: () => [{ path: root }] }
-}
-
 async function responseBytes(response: Response): Promise<Uint8Array> {
   return new Uint8Array(await response.arrayBuffer())
 }
 
-function apiRequest(path: string, init?: RequestInit): Request {
-  const url = `http://127.0.0.1:3080/api/file?path=${encodeURIComponent(path)}`
-  return new Request(url, init)
+/** One mounted plugin contribution with its registered `/api/file` handler. */
+interface MountedRoute {
+  /** GET/HEAD helper for one local path. */
+  call(path: string, init?: RequestInit): Promise<Response>
+  /** Direct request access (custom URLs and headers). */
+  raw(url: string, init?: RequestInit): Promise<Response>
+  unregister: ReturnType<typeof vi.fn>
 }
 
-describe('mediaTypeForPath', () => {
-  it('maps allowlisted media extensions', () => {
-    expect(mediaTypeForPath('/w/graph.png')).toBe('image/png')
-    expect(mediaTypeForPath('/w/graph.jpg')).toBe('image/jpeg')
-    expect(mediaTypeForPath('/w/clip.mp4')).toBe('video/mp4')
-    expect(mediaTypeForPath('/w/clip.webm')).toBe('video/webm')
-    expect(mediaTypeForPath('/w/song.mp3')).toBe('audio/mpeg')
-  })
-
-  it('refuses non-media extensions', () => {
-    expect(mediaTypeForPath('/w/note.txt')).toBeUndefined()
-    expect(mediaTypeForPath('/w/app.exe')).toBeUndefined()
-    expect(mediaTypeForPath('/w/shell.svg')).toBeUndefined()
-  })
-})
-
-describe('parseByteRange', () => {
-  it('parses full, bounded, open-ended, and suffix ranges', () => {
-    expect(parseByteRange(null, 100)).toEqual({ kind: 'full' })
-    expect(parseByteRange('bytes=0-3', 100)).toEqual({ kind: 'partial', start: 0, end: 3 })
-    expect(parseByteRange('bytes=10-', 100)).toEqual({ kind: 'partial', start: 10, end: 99 })
-    expect(parseByteRange('bytes=-4', 100)).toEqual({ kind: 'partial', start: 96, end: 99 })
-    expect(parseByteRange('bytes=90-200', 100)).toEqual({ kind: 'partial', start: 90, end: 99 })
-  })
-
-  it('refuses malformed and unsatisfiable ranges', () => {
-    expect(parseByteRange('bytes=abc', 100)).toBeUndefined()
-    expect(parseByteRange('bytes=-', 100)).toBeUndefined()
-    expect(parseByteRange('bytes=-0', 100)).toBeUndefined()
-    expect(parseByteRange('bytes=5-2', 100)).toBeUndefined()
-    expect(parseByteRange('bytes=100-', 100)).toBeUndefined()
-    expect(parseByteRange('bytes=0-', 0)).toBeUndefined()
-  })
-})
-
-describe('serveMediaReference', () => {
+describe('SessionMediaReferences /api/file', () => {
   let root: string
+  let route: MountedRoute
+  const contexts: Context[] = []
 
   beforeEach(async () => {
     // Real workspace roots are canonical; tmpdir may sit behind a symlink.
-    root = await realpath(await mkdtemp(join(tmpdir(), 'dsh-workspace-file-')))
+    root = await realpath(await mkdtemp(join(tmpdir(), 'dsh-media-references-')))
+    const ctx = new Context()
+    contexts.push(ctx)
+    let handler: ((request: Request) => Promise<Response>) | undefined
+    const unregister = vi.fn(() => {})
+    ctx.provide('connection', {
+      fetch: {
+        register: (registered: { fetch: (request: Request) => Promise<Response> }) => {
+          handler = registered.fetch
+          return unregister
+        },
+      },
+    } as never)
+    ctx.provide('workspaceRegistry', { list: () => [{ path: root }] } as never)
+    await ctx.plugin(SessionMediaReferences).await()
+    const fetchFile = (request: Request) => {
+      if (handler === undefined) throw new Error('route not registered')
+      return handler(request)
+    }
+    route = {
+      call: (path, init) => {
+        const url = `http://127.0.0.1:3080/api/file?path=${encodeURIComponent(path)}`
+        return fetchFile(new Request(url, init))
+      },
+      raw: (url, init) => fetchFile(new Request(url, init)),
+      unregister,
+    }
   })
 
   afterEach(async () => {
+    await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
     await rm(root, { recursive: true, force: true })
   })
 
-  it('serves a workspace image with streaming-safe headers', async () => {
-    const path = join(root, 'shots', 'graph.png')
-    await mkdir(join(root, 'shots'), { recursive: true })
-    await writeFile(path, PNG_BYTES)
-    const response = await serveMediaReference(apiRequest(path), registry(root))
+  it('serves images from the workspace root and nested directories', async () => {
+    const direct = join(root, 'graph.png')
+    await writeFile(direct, PNG_BYTES)
+    const response = await route.call(direct)
     expect(response.status).toBe(200)
     expect(response.headers.get('content-type')).toBe('image/png')
     expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
@@ -87,83 +74,112 @@ describe('serveMediaReference', () => {
     expect(response.headers.get('cache-control')).toBe('private, no-store')
     expect(response.headers.get('x-content-type-options')).toBe('nosniff')
     expect(await responseBytes(response)).toEqual(PNG_BYTES)
+
+    const nestedDir = join(root, 'shots', 'deep')
+    await mkdir(nestedDir, { recursive: true })
+    const nested = join(nestedDir, 'x.png')
+    await writeFile(nested, PNG_BYTES)
+    expect((await route.call(nested)).status).toBe(200)
   })
 
-  it('serves media without image sniffing from the extension allowlist', async () => {
-    const path = join(root, 'clip.mp4')
-    await writeFile(path, MP4_BYTES)
-    const response = await serveMediaReference(apiRequest(path), registry(root))
+  it('serves every allowlisted media category by extension', async () => {
+    const video = join(root, 'clip.mp4')
+    await writeFile(video, MP4_BYTES)
+    const videoResponse = await route.call(video)
+    expect(videoResponse.status).toBe(200)
+    expect(videoResponse.headers.get('content-type')).toBe('video/mp4')
+
+    const audio = join(root, 'song.mp3')
+    await writeFile(audio, TEXT_BYTES)
+    const audioResponse = await route.call(audio)
+    expect(audioResponse.status).toBe(200)
+    expect(audioResponse.headers.get('content-type')).toBe('audio/mpeg')
+  })
+
+  it('serves allowlisted image extensions regardless of payload bytes', async () => {
+    // Media bytes are never sniffed on this route: a corrupt payload fails
+    // in the browser, not here.
+    const fake = join(root, 'fake.png')
+    await writeFile(fake, TEXT_BYTES)
+    const response = await route.call(fake)
     expect(response.status).toBe(200)
-    expect(response.headers.get('content-type')).toBe('video/mp4')
-    expect(await responseBytes(response)).toEqual(MP4_BYTES)
+    expect(response.headers.get('content-type')).toBe('image/png')
   })
 
-  it('answers bounded and suffix range requests with 206 slices', async () => {
+  it('refuses non-media, unknown, and denied content types', async () => {
+    const cases: ReadonlyArray<[string, Uint8Array]> = [
+      ['note.txt', TEXT_BYTES],
+      ['run.exe', TEXT_BYTES],
+      ['logo.svg', TEXT_BYTES],
+      ['data.bin', TEXT_BYTES],
+      ['README', TEXT_BYTES],
+    ]
+    for (const [name, bytes] of cases) {
+      const path = join(root, name)
+      await writeFile(path, bytes)
+      const response = await route.call(path)
+      expect(response.status, name).toBe(415)
+      expect(await response.text()).toBe('not an allowlisted media type')
+    }
+  })
+
+  it('answers bounded, open-ended, suffix, and clamped range requests', async () => {
     const path = join(root, 'graph.png')
     await writeFile(path, PNG_BYTES)
-    const bounded = await serveMediaReference(
-      apiRequest(path, { headers: { range: 'bytes=0-3' } }),
-      registry(root),
-    )
+    const total = PNG_BYTES.length
+
+    const bounded = await route.call(path, { headers: { range: 'bytes=0-3' } })
     expect(bounded.status).toBe(206)
-    expect(bounded.headers.get('content-range')).toBe(`bytes 0-3/${PNG_BYTES.length}`)
+    expect(bounded.headers.get('content-range')).toBe(`bytes 0-3/${total}`)
     expect(bounded.headers.get('content-length')).toBe('4')
     expect(await responseBytes(bounded)).toEqual(PNG_BYTES.slice(0, 4))
 
-    const suffix = await serveMediaReference(
-      apiRequest(path, { headers: { range: 'bytes=-4' } }),
-      registry(root),
-    )
+    const suffix = await route.call(path, { headers: { range: 'bytes=-4' } })
     expect(suffix.status).toBe(206)
     expect(await responseBytes(suffix)).toEqual(PNG_BYTES.slice(-4))
+
+    const openEnded = await route.call(path, { headers: { range: 'bytes=4-' } })
+    expect(openEnded.status).toBe(206)
+    expect(await responseBytes(openEnded)).toEqual(PNG_BYTES.slice(4))
+
+    const clamped = await route.call(path, { headers: { range: 'bytes=6-999' } })
+    expect(clamped.status).toBe(206)
+    expect(clamped.headers.get('content-range')).toBe(`bytes 6-${total - 1}/${total}`)
+    expect(await responseBytes(clamped)).toEqual(PNG_BYTES.slice(6))
   })
 
-  it('answers unsatisfiable ranges with 416 and the total size', async () => {
+  it('answers unsatisfiable and malformed ranges with 416 and the total size', async () => {
     const path = join(root, 'graph.png')
     await writeFile(path, PNG_BYTES)
-    const response = await serveMediaReference(
-      apiRequest(path, { headers: { range: 'bytes=999-' } }),
-      registry(root),
-    )
-    expect(response.status).toBe(416)
-    expect(response.headers.get('content-range')).toBe(`bytes */${PNG_BYTES.length}`)
+    for (const range of ['bytes=999-', 'bytes=abc']) {
+      const response = await route.call(path, { headers: { range } })
+      expect(response.status, range).toBe(416)
+      expect(response.headers.get('content-range')).toBe(`bytes */${PNG_BYTES.length}`)
+    }
   })
 
   it('answers HEAD without a body', async () => {
     const path = join(root, 'graph.png')
     await writeFile(path, PNG_BYTES)
-    const response = await serveMediaReference(
-      apiRequest(path, { method: 'HEAD' }),
-      registry(root),
-    )
+    const response = await route.call(path, { method: 'HEAD' })
     expect(response.status).toBe(200)
     expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
     expect(response.body).toBeNull()
   })
 
   it('denies malformed, missing, and uncontained requests', async () => {
-    const missing = await serveMediaReference(
-      new Request('http://127.0.0.1:3080/api/file'),
-      registry(root),
-    )
-    expect(missing.status).toBe(400)
-    const relative = await serveMediaReference(
-      new Request(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent('x.png')}`),
-      registry(root),
-    )
-    expect(relative.status).toBe(400)
-    const gone = await serveMediaReference(
-      apiRequest(join(root, 'missing.png')),
-      registry(root),
-    )
-    expect(gone.status).toBe(404)
-    expect((await serveMediaReference(apiRequest(join(root, 'x.png')), undefined)).status).toBe(403)
+    expect((await route.raw('http://127.0.0.1:3080/api/file')).status).toBe(400)
+    expect((await route.raw(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent('x.png')}`)).status)
+      .toBe(400)
+    expect((await route.raw(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent('/a\0b.png')}`)).status)
+      .toBe(400)
+    expect((await route.call(join(root, 'missing.png'))).status).toBe(404)
 
-    const outside = await realpath(await mkdtemp(join(tmpdir(), 'dsh-workspace-file-out-')))
+    const outside = await realpath(await mkdtemp(join(tmpdir(), 'dsh-media-references-out-')))
     const path = join(outside, 'x.png')
     await writeFile(path, PNG_BYTES)
     try {
-      const denied = await serveMediaReference(apiRequest(path), registry(root))
+      const denied = await route.call(path)
       expect(denied.status).toBe(403)
       expect(await denied.text()).toBe('outside workspace roots')
     } finally {
@@ -171,36 +187,33 @@ describe('serveMediaReference', () => {
     }
   })
 
-  it('refuses directories and non-allowlisted extensions', async () => {
-    const directory = await serveMediaReference(apiRequest(root), registry(root))
-    expect(directory.status).toBe(403)
-
-    const text = join(root, 'note.txt')
-    await writeFile(text, TEXT_BYTES)
-    expect((await serveMediaReference(apiRequest(text), registry(root))).status).toBe(415)
+  it('refuses the workspace-root directory itself', async () => {
+    const response = await route.call(root)
+    expect(response.status).toBe(403)
+    expect(await response.text()).toBe('not a regular file')
   })
 
-  it('serves allowlisted extensions regardless of payload bytes', async () => {
-    // Media bytes are not sniffed here: the extension allowlist decides what
-    // is served, and a corrupt image payload stays a browser-side failure.
-    const fake = join(root, 'fake.png')
-    await writeFile(fake, TEXT_BYTES)
-    const response = await serveMediaReference(apiRequest(fake), registry(root))
-    expect(response.status).toBe(200)
-    expect(response.headers.get('content-type')).toBe('image/png')
-  })
-
-  it('follows a symlink into the workspace for the containment check', async () => {
+  it('follows symlinks for the containment check', async () => {
     const real = join(root, 'real.png')
     await writeFile(real, PNG_BYTES)
     const link = join(root, 'link.png')
     await symlink(real, link)
-    const response = await serveMediaReference(apiRequest(link), registry(root))
-    expect(response.status).toBe(200)
-    expect(await responseBytes(response)).toEqual(PNG_BYTES)
+    expect((await route.call(link)).status).toBe(200)
+
+    const outsideTarget = join(await realpath(tmpdir()), 'dsh-media-references-target.png')
+    await writeFile(outsideTarget, PNG_BYTES)
+    try {
+      const escaping = join(root, 'escape.png')
+      await symlink(outsideTarget, escaping)
+      const denied = await route.call(escaping)
+      expect(denied.status).toBe(403)
+      expect(await denied.text()).toBe('outside workspace roots')
+    } finally {
+      await rm(outsideTarget, { force: true })
+    }
   })
 
-  it('survives a large sparse file check without buffering it whole', async () => {
+  it('streams a slice of a large sparse file without buffering it whole', async () => {
     const path = join(root, 'huge.mp4')
     const handle = await open(path, 'w')
     try {
@@ -208,56 +221,13 @@ describe('serveMediaReference', () => {
     } finally {
       await handle.close()
     }
-    const response = await serveMediaReference(
-      apiRequest(path, { headers: { range: 'bytes=0-9' } }),
-      registry(root),
-    )
+    const response = await route.call(path, { headers: { range: 'bytes=0-9' } })
     expect(response.status).toBe(206)
     expect(response.headers.get('content-length')).toBe('10')
     expect((await responseBytes(response)).length).toBe(10)
   })
-})
 
-describe('SessionMediaReferences plugin contribution', () => {
-  const roots: Context[] = []
-
-  afterEach(async () => {
-    await Promise.all(roots.splice(0).map(ctx => ctx.fiber.dispose()))
-  })
-
-  it('registers the /api/file route when connection and registry are composed', async () => {
-    const unregister = vi.fn(() => {})
-    let registered: {
-      path: string
-      methods: readonly string[]
-      requestBody: 'buffered'
-      fetch: (request: Request) => Promise<Response>
-    } | undefined
-    const register = vi.fn((route: typeof registered) => {
-      registered = route
-      return unregister
-    })
-    const ctx = new Context()
-    roots.push(ctx)
-    ctx.provide('connection', { fetch: { register } } as never)
-    ctx.provide('workspaceRegistry', { list: () => [] } as never)
-    await ctx.plugin(SessionMediaReferences).await()
-
-    expect(register).toHaveBeenCalledTimes(1)
-    expect(registered?.path).toBe('/api/file')
-    expect(registered?.methods).toEqual(['GET', 'HEAD'])
-    expect(registered?.requestBody).toBe('buffered')
-
-    // The composed route consults the composed registry: an empty registry
-    // refuses an existing absolute path with the containment verdict.
-    const existing = await realpath(tmpdir())
-    const denied = await registered?.fetch(
-      new Request(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent(existing)}`),
-    )
-    expect(denied?.status).toBe(403)
-    expect(await denied?.text()).toBe('outside workspace roots')
-
-    await ctx.fiber.dispose()
-    expect(unregister).toHaveBeenCalledTimes(1)
+  it('keeps the route registered until the contribution is disposed', () => {
+    expect(route.unregister).not.toHaveBeenCalled()
   })
 })
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index dadcc170fe..8c403b166e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -849,6 +849,12 @@ importers:
       '@deepseek-ai/schemastery':
         specifier: link:../../../vendor/schemastery
         version: link:../../../vendor/schemastery
+      mime-types:
+        specifier: ^3.0.2
+        version: 3.0.2
+      range-parser:
+        specifier: ^1.3.0
+        version: 1.3.0
       zod:
         specifier: ^4.4.3
         version: 4.4.3
@@ -952,6 +958,12 @@ importers:
       '@deepseek-ai/dsh-workspace':
         specifier: workspace:^
         version: link:../../workspace/workspace
+      '@types/mime-types':
+        specifier: ^3.0.1
+        version: 3.0.1
+      '@types/range-parser':
+        specifier: ^1.2.7
+        version: 1.2.7
 
   packages/api/settings-controller:
     dependencies:
@@ -13104,6 +13116,9 @@ packages:
   '@types/mdurl@2.0.0':
     resolution: {integrity: sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==}
 
+  '@types/mime-types@3.0.1':
+    resolution: {integrity: sha512-xRMsfuQbnRq1Ef+C+RKaENOxXX87Ygl38W1vDfPHRku02TgQr+Qd8iivLtAMcR0KF5/29xlnFihkTlbqFrGOVQ==}
+
   '@types/ms@2.1.0':
     resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
 
@@ -18781,6 +18796,8 @@ snapshots:
 
   '@types/mdurl@2.0.0': {}
 
+  '@types/mime-types@3.0.1': {}
+
   '@types/ms@2.1.0': {}
 
   '@types/negotiator@0.6.5': {}

From ead14339bc2908d8764300b873fe35c816a3058f Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 16:46:46 +0800
Subject: [PATCH 08/35] refactor(ui-chat): fold local-path media mapping into
 AssistantMarkdown

A single-consumer pure helper does not earn its own file: the mapping
now lives beside the prose vocabulary it serves (same shape as the
deliverables file-mention logic), and its unit cases merged into the
component spec.
---
 .../src/client/chat/AssistantMarkdown.tsx     | 17 ++++++++++-
 .../src/client/chat/local-path-media.ts       | 24 ---------------
 ...stant-markdown-path-images.client.spec.tsx | 30 ++++++++++++++++++-
 .../tests/local-path-media.client.spec.ts     | 30 -------------------
 4 files changed, 45 insertions(+), 56 deletions(-)
 delete mode 100644 packages/client/ui-chat/src/client/chat/local-path-media.ts
 delete mode 100644 packages/client/ui-chat/tests/local-path-media.client.spec.ts

diff --git a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
index b02de8e1a5..3212801e00 100644
--- a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
@@ -6,10 +6,25 @@ import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts
 import type { AssistantBlock } from '../contract/snapshot.ts'
 import { markdownLabels } from '../markdown-labels.ts'
 import { ReasoningRow } from './ReasoningRow.tsx'
-import { localPathMediaUrl } from './local-path-media.ts'
 import { useSearchableHidden } from './searchable-hidden.ts'
 import css from './AssistantMarkdown.module.css'
 
+/**
+ * Map one authored media destination to the same-origin workspace-file URL.
+ * @param protocol - `window.location.protocol` at render time.
+ * @param origin - `window.location.origin` at render time.
+ * @param value - The authored markdown destination, exactly as written.
+ * @returns The API URL for an absolute POSIX path on an HTTP(S) page, or
+ * undefined when the destination cannot be a Host-served local file
+ * (non-HTTP transport such as Electron `file://`, protocol-relative or
+ * relative destinations).
+ */
+export function localPathMediaUrl(protocol: string, origin: string, value: string): string | undefined {
+  if (protocol !== 'http:' && protocol !== 'https:') return undefined
+  if (value.length === 0 || !value.startsWith('/') || value.startsWith('//')) return undefined
+  return `${origin}/api/file?path=${encodeURIComponent(value)}`
+}
+
 export interface AssistantMarkdownProps {
   blocks: readonly AssistantBlock[]
   streaming: boolean
diff --git a/packages/client/ui-chat/src/client/chat/local-path-media.ts b/packages/client/ui-chat/src/client/chat/local-path-media.ts
deleted file mode 100644
index 5369a253ce..0000000000
--- a/packages/client/ui-chat/src/client/chat/local-path-media.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-/**
- * Pure local-path → same-origin workspace-file mapping for closing prose. The
- * renderer seam consumes this vocabulary; the served endpoint re-validates
- * every request, so this side only decides whether a destination *looks*
- * like an absolute local path the Host could serve. One endpoint covers every
- * served media type (images today; video/audio the same way), so consumers
- * rewrite the path without knowing what kind of media it names.
- */
-
-/**
- * Map one authored media destination to the same-origin workspace-file URL.
- * @param protocol - `window.location.protocol` at render time.
- * @param origin - `window.location.origin` at render time.
- * @param value - The authored markdown destination, exactly as written.
- * @returns The API URL for an absolute POSIX path on an HTTP(S) page, or
- * undefined when the destination cannot be a Host-served local file
- * (non-HTTP transport such as Electron `file://`, protocol-relative or
- * relative destinations).
- */
-export function localPathMediaUrl(protocol: string, origin: string, value: string): string | undefined {
-  if (protocol !== 'http:' && protocol !== 'https:') return undefined
-  if (value.length === 0 || !value.startsWith('/') || value.startsWith('//')) return undefined
-  return `${origin}/api/file?path=${encodeURIComponent(value)}`
-}
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 6b9169c418..564f5a6a41 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
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 import { cleanup, render } from '@testing-library/react'
 import { afterEach, describe, expect, it } from 'vitest'
-import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
+import { AssistantMarkdown, localPathMediaUrl } from '../src/client/chat/AssistantMarkdown.tsx'
 import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../src/client/contract/slots.ts'
 import type { AssistantBlock } from '../src/client/contract/snapshot.ts'
 
@@ -14,6 +14,34 @@ function textBlock(text: string): AssistantBlock {
   return { kind: 'text', text }
 }
 
+const ORIGIN = 'http://127.0.0.1:3080'
+
+describe('localPathMediaUrl', () => {
+  it('maps an absolute POSIX path on an HTTP page to the file API', () => {
+    expect(localPathMediaUrl('http:', ORIGIN, '/tmp/graph.png'))
+      .toBe(`${ORIGIN}/api/file?path=${encodeURIComponent('/tmp/graph.png')}`)
+    expect(localPathMediaUrl('https:', 'https://127.0.0.1:3080', '/tmp/graph.png'))
+      .toBe(`https://127.0.0.1:3080/api/file?path=${encodeURIComponent('/tmp/graph.png')}`)
+  })
+
+  it('keeps non-HTTP transports inert', () => {
+    expect(localPathMediaUrl('file:', 'file:///app', '/tmp/graph.png')).toBeUndefined()
+    expect(localPathMediaUrl('ws:', ORIGIN, '/tmp/graph.png')).toBeUndefined()
+  })
+
+  it('keeps destinations that cannot be Host-served local files inert', () => {
+    expect(localPathMediaUrl('http:', ORIGIN, '')).toBeUndefined()
+    expect(localPathMediaUrl('http:', ORIGIN, '//cdn.example.com/x.png')).toBeUndefined()
+    expect(localPathMediaUrl('http:', ORIGIN, 'relative.png')).toBeUndefined()
+    expect(localPathMediaUrl('http:', ORIGIN, 'C:\\tmp\\x.png')).toBeUndefined()
+  })
+
+  it('encodes the full path including spaces', () => {
+    expect(localPathMediaUrl('http:', ORIGIN, '/tmp/my graph.png'))
+      .toBe(`${ORIGIN}/api/file?path=${encodeURIComponent('/tmp/my graph.png')}`)
+  })
+})
+
 describe('AssistantMarkdown local-path images', () => {
   it('renders a local image path in closing prose through the same-origin API', () => {
     const { container } = render(
diff --git a/packages/client/ui-chat/tests/local-path-media.client.spec.ts b/packages/client/ui-chat/tests/local-path-media.client.spec.ts
deleted file mode 100644
index b34f99fb06..0000000000
--- a/packages/client/ui-chat/tests/local-path-media.client.spec.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { localPathMediaUrl } from '../src/client/chat/local-path-media.ts'
-
-const ORIGIN = 'http://127.0.0.1:3080'
-
-describe('localPathMediaUrl', () => {
-  it('maps an absolute POSIX path on an HTTP page to the image API', () => {
-    expect(localPathMediaUrl('http:', ORIGIN, '/tmp/graph.png'))
-      .toBe(`${ORIGIN}/api/file?path=${encodeURIComponent('/tmp/graph.png')}`)
-    expect(localPathMediaUrl('https:', 'https://127.0.0.1:3080', '/tmp/graph.png'))
-      .toBe(`https://127.0.0.1:3080/api/file?path=${encodeURIComponent('/tmp/graph.png')}`)
-  })
-
-  it('keeps non-HTTP transports inert', () => {
-    expect(localPathMediaUrl('file:', 'file:///app', '/tmp/graph.png')).toBeUndefined()
-    expect(localPathMediaUrl('ws:', ORIGIN, '/tmp/graph.png')).toBeUndefined()
-  })
-
-  it('keeps destinations that cannot be Host-served local files inert', () => {
-    expect(localPathMediaUrl('http:', ORIGIN, '')).toBeUndefined()
-    expect(localPathMediaUrl('http:', ORIGIN, '//cdn.example.com/x.png')).toBeUndefined()
-    expect(localPathMediaUrl('http:', ORIGIN, 'relative.png')).toBeUndefined()
-    expect(localPathMediaUrl('http:', ORIGIN, 'C:\\tmp\\x.png')).toBeUndefined()
-  })
-
-  it('encodes the full path including spaces', () => {
-    expect(localPathMediaUrl('http:', ORIGIN, '/tmp/my graph.png'))
-      .toBe(`${ORIGIN}/api/file?path=${encodeURIComponent('/tmp/my graph.png')}`)
-  })
-})

From 8b8a051c7a3846ad8e0da88718b281e833dd71a0 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 17:27:57 +0800
Subject: [PATCH 09/35] fix(api): address /api/file review findings

- HEAD never opens a file stream; GET streams are destroyed on client
  abort and are never opened for already-aborted requests.
- Validation and reading bind to the same opened file: pre-open and
  opened stat identities are compared, so replacement/re-linking races
  are refused (dev/ino check, read through the FileHandle).
- Workspace containment compares path components, so a filesystem-root
  workspace serves files instead of doubling the separator.
- Multi-range headers are ignored for a full 200 body instead of a
  mislabeled single-segment 206; single-range behavior unchanged.
- Tests now cover the reviewed edges (empty path, multi-range, root
  workspace, HEAD+range, mid/early abort, unreadable file, explicit
  unregister-on-dispose, private outside-target directories); module
  coverage is back at 100/100/100/100.
- Agent Note bilingual facts and the ui-primitives/session-controller
  README pairs are synced to the shipped behavior (pairs re-recorded).
---
 ...ession-prose-local-media-display.i18n.yaml |   4 +-
 ...09-07-session-prose-local-media-display.md |  10 +-
 ...07-session-prose-local-media-display.zh.md |  10 +-
 .../api/session-controller/README.i18n.yaml   |   4 +-
 packages/api/session-controller/README.md     |   7 +
 packages/api/session-controller/README.zh.md  |   7 +
 .../src/media-references.ts                   | 133 ++++++++--------
 .../tests/media-references.host.spec.ts       | 144 ++++++++++++++++--
 .../client/ui-primitives/README.i18n.yaml     |   4 +-
 packages/client/ui-primitives/README.md       |   2 +-
 packages/client/ui-primitives/README.zh.md    |   2 +-
 11 files changed, 230 insertions(+), 97 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
index ca30dccd30..6eced36c70 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.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 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
-2026-09-07-session-prose-local-media-display.md: 79bde26e1890bf463f7a954e9b84d81e87ecbd1e
-2026-09-07-session-prose-local-media-display.zh.md: af852a627888353589e4a88a4198bfb32760adbe
+2026-09-07-session-prose-local-media-display.md: 6599d3e7c1e9838f9191e339fcca3bd811951af8
+2026-09-07-session-prose-local-media-display.zh.md: 8d2121dd206a0719a48a09e91973eb5edf970a6a
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
index 79bde26e18..6599d3e7c1 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
@@ -13,8 +13,8 @@ Assistant prose sometimes references an image by its local filesystem path (mark
 Local media paths in session prose render through one same-origin file route, with the rewrite vocabulary and the serving policy each owned where the repo's seams say they belong.
 
 - **Renderer seam (`ui-primitives`)**: `MarkdownText` gained a `MarkdownPathImages` vocabulary (`pathImages` prop) with the same settled-only gate as `fileMentions`: while a message streams, frozen cached blocks never bake in a vocabulary handler; the settled pass rewrites image destinations that fail the remote-URL allowlist, and a rewritten destination is emitted only when it is an absolute `http(s)`/`blob`/`data` URL. Without a vocabulary the renderer output is byte-identical to before.
-- **Chat wiring (`ui-chat`)**: `AssistantMarkdown` supplies a page-stable vocabulary mapping absolute POSIX paths to same-origin `/api/file?path=…` GETs (`local-path-media.ts`); non-HTTP transports (Electron `file://`) and relative/protocol-relative destinations stay inert.
-- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root, the file must be regular, and its MIME type must belong to the served categories image/video/audio (resolved by the `mime-types` package, excluding `image/svg+xml`); media bytes are never sniffed on this route. Responses stream with HTTP range support parsed by the `range-parser` package (206/416) so video and audio can seek, and carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
+- **Chat wiring (`ui-chat`)**: `AssistantMarkdown` supplies a page-stable vocabulary (`localPathMediaUrl`, module-private in the same file) mapping absolute POSIX paths to same-origin `/api/file?path=…` GETs; non-HTTP transports (Electron `file://`) and relative/protocol-relative destinations stay inert. Windows-style host paths (`C:\...`) are deliberately inert on the client side and are recorded as a limitation in Consequences.
+- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its MIME type must belong to the served categories image/video/audio (resolved by the `mime-types` package, excluding `image/svg+xml`); media bytes are never sniffed on this route. Validation and reading bind to the same opened file: the pre-open and opened stat identities are compared, so a replacement or re-linking race is refused instead of followed. Responses stream with HTTP range support parsed by the `range-parser` package: single-range requests answer 206, multi-range headers are ignored for a full 200 body, HEAD never opens a file stream, and an aborted client destroys the stream. Responses carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
 
 The route is presentational and stateless: it never writes, follows no redirects, and returns 400/403/404/415/416 instead of approximating another file-serving behavior.
 
@@ -30,11 +30,13 @@ The route is presentational and stateless: it never writes, follows no redirects
 ## Consequences
 
 - Assistant prose that references workspace-contained image files now displays them in Web chat; previously inert alt text disappears only where the host can serve the bytes.
-- Policy is enforced host-side per request; the client vocabulary never expands what the route allows. Media typing trusts the extension allowlist; byte-signature validation stays with the `read_image` tool that owns it.
+- Policy is enforced host-side per request; the client vocabulary never expands what the route allows. Media typing trusts the MIME category allowlist; byte-signature validation stays with the `read_image` tool that owns it.
+- Existence disclosure: an authenticated same-origin client can tell an existing-but-outside-workspace path (403) from a nonexistent one (404). Readable bytes stay confined to workspace roots, so the impact is limited to existence probing, and the distinct statuses are kept intentionally.
+- Windows-host limitation: the client vocabulary rewrites only absolute POSIX paths, so a Windows-style `C:\...` destination stays inert alt text even though the route's own `isAbsolute` would accept it; serving such references is deferred.
 - Scope is deliberately narrow: only files under registered workspace roots with allowlisted media types are served; anything else keeps the authored fallback. Trajectory and tool-card markdown consumers do not pass a vocabulary yet, and video/audio markdown nodes are not rendered as `<video>`/`<audio>` yet — the URL layer already supports them.
 - The client hardcodes the `/api/file` endpoint as a same-origin channel contract; this is stable by construction because the page is served by the same host that mounts the route.
 - Related history: the archived note [model-readable image paths](../../archived/feature/2026-08-21-model-readable-image-paths.md) decided the model-facing side of local image paths; this note owns the user-facing display side and does not supersede it.
 
 ## Testing
 
-Unit coverage: the renderer seam (settled and streaming gates, reference-style images, protocol re-checks), the chat vocabulary and component wiring, and the host route policy (containment, symlinks, media allowlist and signature mismatch, range parsing and 206/416 answers, HEAD, disposal of the plugin contribution). Full local evidence at open: typecheck clean; ui-primitives, ui-chat, and session-controller suites (103 files, 1456 tests) pass. Deferred to the PR follow-up: keyless recorded-session replay for the end-to-end GUI path and the browser demo GIF the GUI PR evidence chain requires.
+Unit coverage: the renderer seam (settled and streaming gates, reference-style images, protocol re-checks), the chat vocabulary and component wiring, and the host route policy exercised through the registered route (containment incl. symlinks and filesystem-root workspaces, MIME category allowlist, single/multi-range and 416 answers, HEAD without a stream, client-abort destruction, unregister-on-dispose). `media-references.ts` sits at 100% statements/branches/functions/lines. Local gates at this state: typecheck, oxlint, duplication, translation pairing, and the touched suites all pass. Deferred to the PR follow-up: keyless recorded-session replay for the end-to-end GUI path and the browser demo GIF the GUI PR evidence chain requires.
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
index af852a6278..8d2121dd20 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
@@ -13,8 +13,8 @@ Assistant 正文有时用本地文件系统路径引用图片（markdown `![](/U
 会话正文中的本地媒体路径通过一条同源文件路由渲染；重写词表与服务政策分别归属于仓库现有缝对应的位置。
 
 - **渲染缝（`ui-primitives`）**：`MarkdownText` 新增 `MarkdownPathImages` 词表（`pathImages` prop），与 `fileMentions` 同用 settled-only 门：消息流式期间冻结的缓存块绝不烘入词表处理器；落定渲染把未通过远程 URL 白名单的图片目标重写为可展示 URL，且只有结果是绝对 `http(s)`/`blob`/`data` URL 时才发射。不提供词表时渲染输出与之前逐字节一致。
-- **聊天接线（`ui-chat`）**：`AssistantMarkdown` 提供页面级稳定的词表，把绝对 POSIX 路径映射为同源 `GET /api/file?path=…`（`local-path-media.ts`）；非 HTTP 载体（Electron `file://`）与相对/协议相对目标保持惰性。
-- **Host 路由（`session-controller`）**：`SessionMediaReferences` 是与 `SessionFileReferences` 并列注册的插件贡献，把 `GET|HEAD /api/file` 挂到共享鉴权 `connection.fetch` 通道（与 `/api` RPC 同一 trust fence 与浏览器认证）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内、文件必须是常规文件、扩展名必须在媒体 allowlist 内（PNG/JPEG/GIF/WebP/AVIF、MP4/WebM/MOV/OGG、MP3/WAV/Ogg/M4A/AAC/FLAC）；图片扩展额外校验字节签名。响应以 HTTP Range 流式输出（206/416），视频/音频可拖动进度，并携带 `private, no-store` 与 `nosniff`。该贡献只在 `connection` 与 `workspaceRegistry` 均被组合时激活（pending-until-composed，与包内其它可选贡献一致）。
+- **聊天接线（`ui-chat`）**：`AssistantMarkdown` 提供页面级稳定的词表（`localPathMediaUrl`，与组件同文件的模块私有函数），把绝对 POSIX 路径映射为同源 `GET /api/file?path=…`；非 HTTP 载体（Electron `file://`）与相对/协议相对目标保持惰性。Windows 风格 Host 路径（`C:\...`）在客户端侧刻意保持惰性，作为局限记录于 Consequences。
+- **Host 路由（`session-controller`）**：`SessionMediaReferences` 是与 `SessionFileReferences` 并列注册的插件贡献，把 `GET|HEAD /api/file` 挂到共享鉴权 `connection.fetch` 通道（与 `/api` RPC 同一 trust fence 与浏览器认证）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace 的情况）、文件必须是常规文件、其 MIME 类型（由 `mime-types` 解析）必须属于受服务类别 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。校验与读取绑定同一个已打开文件：比较打开前后 stat 身份，替换/重链接竞态被拒绝而非跟随。响应由 `range-parser` 解析 Range 后流式输出：单段请求回 206，多段 Range 被忽略并回完整 200，HEAD 从不打开文件流，客户端中止即销毁流；响应携带 `private, no-store` 与 `nosniff`。该贡献只在 `connection` 与 `workspaceRegistry` 均被组合时激活（pending-until-composed，与包内其它可选贡献一致）。
 
 该路由纯呈现且无状态：从不写入、不跟随重定向，失败返回 400/403/404/415/416，不近似其它文件服务行为。
 
@@ -30,11 +30,13 @@ Assistant 正文有时用本地文件系统路径引用图片（markdown `![](/U
 ## Consequences
 
 - 引用 workspace 内图片文件的 Assistant 正文现在可在 Web 聊天中显示；原先惰性的 alt 文本只在 Host 无法提供字节时保留。
-- 政策在 Host 端每次请求强制；客户端词表不会扩大路由放行的范围。媒体类型判定信任扩展名 allowlist；字节签名校验保留在其所有者 `read_image` 工具中。
+- 政策在 Host 端每次请求强制；客户端词表不会扩大路由放行的范围。媒体类型判定信任 MIME 类别 allowlist；字节签名校验保留在其所有者 `read_image` 工具中。
+- 存在性泄露：已鉴权同源客户端可区分「存在但在 workspace 外」（403）与「不存在」（404）。可读字节仍被限定在 workspace 根内，影响仅限于存在性探测，保留不同状态码是有意决定。
+- Windows Host 局限：客户端词表只重写绝对 POSIX 路径，Windows 风格 `C:\...` 目标保持惰性 alt 文本（尽管路由侧 `isAbsolute` 本可接受）；服务此类引用留待后续。
 - 范围刻意收窄：只服务注册 workspace 根内、媒体 allowlist 内的文件；其它一律保持作者原样的回退。Trajectory 与工具卡片等 markdown 消费方尚未传词表，视频/音频 markdown 节点也尚未渲染为 `<video>`/`<audio>`——URL 层已为它们准备好。
 - 客户端把 `/api/file` 硬编码为同源通道契约；由于页面与挂载路由的 Host 同源，该契约按构造稳定。
 - 相关历史：已归档笔记 [model-readable image paths](../../archived/feature/2026-08-21-model-readable-image-paths.md) 决定本地图片路径面向模型的一侧；本笔记拥有面向用户展示的一侧，不构成对其的取代。
 
 ## Testing
 
-单元覆盖：渲染缝（落定与流式门、引用式图片、协议复检）、聊天词表与组件接线、Host 路由政策（包含关系、符号链接、媒体 allowlist 与签名不符、Range 解析与 206/416 应答、HEAD、插件贡献的释放）。开 PR 时的本地证据：typecheck 干净；ui-primitives、ui-chat 与 session-controller 套件（103 个文件、1456 个用例）全过。推迟到 PR 后续：端到端 GUI 路径的 keyless 录播回放，以及 GUI PR 证据链要求的浏览器演示 GIF。
+单元覆盖：渲染缝（落定与流式门、引用式图片、协议复检）、聊天词表与组件接线、以及经注册路由施加的 Host 路由政策（包含关系含符号链接与文件系统根 workspace、MIME 类别 allowlist、单/多段 Range 与 416 应答、HEAD 不开流、客户端中止即销毁、释放即注销）。`media-references.ts` 语句/分支/函数/行覆盖率均为 100%。当前状态本地门禁：typecheck、oxlint、duplication、translation pairing 与受影响套件全部通过。推迟到 PR 后续：端到端 GUI 路径的 keyless 录播回放，以及 GUI PR 证据链要求的浏览器演示 GIF。
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index 41b4271974..bf9f8b55a9 100644
--- a/packages/api/session-controller/README.i18n.yaml
+++ b/packages/api/session-controller/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/api/session-controller/README.md
-README.md: ec8b70b1724afc462d2d0b5d267603bcab4aceb6
-README.zh.md: 6fc0c92300262bfdf0fc52deaec1d66313d91ebe
+README.md: f92fb3eec7fc44a4d83be916bcea80805e2ef2a0
+README.zh.md: 0b2c54e9ac1f42993a8b7eaebf24b0570108ee38
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index ec8b70b172..f92fb3eec7 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -13,6 +13,7 @@ English | [中文](README.zh.md)
 ## Table of Contents
 
 - [Use this package](#use-this-package)
+- [Session media references](#session-media-references)
 - [Configuration](#configuration)
 - [Model Experience](#model-experience)
 - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
@@ -31,6 +32,12 @@ The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream`
 
 The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. The echo stores ordered image previews and durable file references. Session derives its `transcript`, `queued`, or `steering` placement from the current running state and requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed, immediately when its identified prompt fails or is abandoned, and as failed on disposal. Each retirement fires `onRetire` exactly once; an observed retirement includes the ordered durable attachment references so the composer can release successful cards while preserving failed drafts. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone.
 
+
+<a id="session-media-references"></a>
+## Session media references
+
+`SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when both `connection` and `workspaceRegistry` are composed, so conversation prose can display workspace-contained local media (images today; video/audio later) in the browser. Per request the route fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its `mime-types` category must be image/video/audio (excluding `image/svg+xml`); media bytes are never sniffed. Validation and reading bind to the same opened file, so a replacement or re-linking race is refused. Single-range requests stream a 206 slice parsed by `range-parser`; multi-range headers are ignored for a full 200 body; HEAD never opens a file stream; an aborted client destroys it. Responses carry `private, no-store` and `nosniff`; failures answer 400/403/404/415/416. The client-side rewrite vocabulary lives in `ui-chat` (`AssistantMarkdown`); this package owns only the serving contract.
+
 -----
 
 <a id="configuration"></a>
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index 6fc0c92300..0b2c54e9ac 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -13,6 +13,7 @@ kind: "package-reference"
 ## 目录
 
 - [使用本包](#use-this-package)
+- [会话媒体引用](#session-media-references)
 - [配置](#configuration)
 - [模型体验](#model-experience)
 - [已知限制与延期工作](#known-limitations-and-deferred-work)
@@ -31,6 +32,12 @@ Client adapter 提供 `SessionEventStream`，即绑定到一个普通 Session 
 
 Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与 prompt 之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。回显按顺序存放图片预览与持久文件引用。Session 根据当前运行状态与请求的投递模式推导其 `transcript`、`queued` 或 `steering` 位置，并在序列化期间保留该位置。prompt 的 `requestId` 是关联标识：Host 把它回显为 durable user source 的 `rpcId`，queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休，带标识的 prompt 失败或被放弃时立即退休，销毁时按 failed 退休。每次退休恰好触发一次 `onRetire`；observed 退休还会携带有序的持久附件引用，让 composer 释放成功卡片并保留失败草稿。回显只存在于 Client 内存；刷新与重连只从 durable event 重建会话。
 
+
+<a id="session-media-references"></a>
+## 会话媒体引用
+
+当 `connection` 与 `workspaceRegistry` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`，使会话正文可以引用 workspace 内的本地媒体（图片今天可用；视频/音频后续同一条 URL）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace）、文件必须是常规文件、其 `mime-types` 类别必须属于 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。校验与读取绑定同一个已打开文件，替换/重链接竞态会被拒绝。单段 Range 请求由 `range-parser` 解析后流式返回 206 分片；多段 Range 头被忽略并返回完整 200；HEAD 从不打开文件流；客户端中止即销毁流。响应携带 `private, no-store` 与 `nosniff`；失败返回 400/403/404/415/416。客户端侧的重写词表位于 `ui-chat`（`AssistantMarkdown`）；本包只拥有服务契约。
+
 -----
 
 <a id="configuration"></a>
diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
index 3130b52050..6663fdae35 100644
--- a/packages/api/session-controller/src/media-references.ts
+++ b/packages/api/session-controller/src/media-references.ts
@@ -9,12 +9,19 @@
  * - the requested path must be one absolute filesystem path;
  * - its canonical location must lie inside a registered workspace root
  *   (`ctx.workspaceRegistry`); no other directory is readable;
- * - the file must exist and be a regular file;
  * - its MIME type (resolved by `mime-types`) must belong to the served
  *   categories image/video/audio, excluding `image/svg+xml`; media bytes are
  *   never sniffed here, and a corrupt payload fails in the browser;
+ * - the file must exist and be a regular file; validation and reading bind to
+ *   the same opened file (a replacement or re-linking race between the
+ *   containment check and the read is detected by comparing the pre-open and
+ *   opened stat identities and refused);
+ * - multi-range requests are answered with the full 200 body (no Range is
+ *   honored) rather than a mislabeled single-segment 206;
  * - responses are private, uncached, sniff-proof, and stream with HTTP range
- *   support (parsed by `range-parser`) so `<video>`/`<audio>` can seek.
+ *   support (parsed by `range-parser`) so `<video>`/`<audio>` can seek; the
+ *   file stream is destroyed when the client aborts, and HEAD never opens
+ *   one.
  *
  * The route is deliberately presentational: it never writes and follows no
  * redirects, returning 400/403/404/415/416 instead of falling back to any
@@ -25,10 +32,9 @@
  * @module @deepseek-ai/dsh-api-session-controller/media-references
  */
 
-import { createReadStream } from 'node:fs'
-import { realpath, stat } from 'node:fs/promises'
+import { open, realpath, stat } from 'node:fs/promises'
 import { isAbsolute, sep } from 'node:path'
-import { Readable } from 'node:stream'
+import { Readable, addAbortSignal } from 'node:stream'
 import type { Context } from '@deepseek-ai/cordis'
 // Cordis `ctx.connection` typing and the fetch-route contract.
 import type {} from '@deepseek-ai/dsh-client-connection'
@@ -37,24 +43,10 @@ import type {} from '@deepseek-ai/dsh-workspace'
 import mime from 'mime-types'
 import rangeParser from 'range-parser'
 
-/** Media categories this route serves. */
-const MEDIA_CATEGORIES: ReadonlySet<string> = new Set(['image', 'video', 'audio'])
-/** Category matches that still must not be served. */
-const DENIED_MEDIA_TYPES: ReadonlySet<string> = new Set(['image/svg+xml'])
-
-/**
- * The content type a file path may be served as, or undefined when it is not
- * an allowlisted media type.
- * @param path - Canonical file path (extension only is read).
- * @returns the content type, or undefined to refuse the file.
- */
-function mediaTypeForPath(path: string): string | undefined {
-  const looked = mime.lookup(path)
-  if (looked === false) return undefined
-  if (DENIED_MEDIA_TYPES.has(looked)) return undefined
-  const category = looked.slice(0, looked.indexOf('/'))
-  return MEDIA_CATEGORIES.has(category) ? looked : undefined
-}
+/** MIME categories this route serves; `image/svg+xml` is refused separately because SVG can carry script. */
+const SERVED_MEDIA_TYPE = /^(?:image|video|audio)\//
+/** Headers every response carries: private, uncached, sniff-proof. */
+const BASE_HEADERS = { 'Cache-Control': 'private, no-store', 'X-Content-Type-Options': 'nosniff' }
 
 /**
  * Serve one workspace-contained media file over the shared API channel.
@@ -72,58 +64,69 @@ async function serveMediaReference(
     return new Response('absolute path required', { status: 400 })
   }
   let canonical: string
-  let info
   try {
     canonical = await realpath(path)
-    info = await stat(canonical)
   } catch {
     return new Response('not found', { status: 404 })
   }
-  const insideWorkspace = roots.some(root =>
-    canonical === root.path || canonical.startsWith(root.path + sep))
-  if (!insideWorkspace) return new Response('outside workspace roots', { status: 403 })
-  if (!info.isFile()) return new Response('not a regular file', { status: 403 })
-  const mediaType = mediaTypeForPath(canonical)
-  if (mediaType === undefined) {
+  // Containment compares path components; a filesystem root already ends in
+  // the separator and prefixes every absolute path.
+  const contained = roots.some(({ path: root }) =>
+    canonical === root || canonical.startsWith(root.endsWith(sep) ? root : root + sep))
+  if (!contained) return new Response('outside workspace roots', { status: 403 })
+  const mediaType = mime.lookup(canonical)
+  if (mediaType === false || mediaType === 'image/svg+xml' || !SERVED_MEDIA_TYPE.test(mediaType)) {
     return new Response('not an allowlisted media type', { status: 415 })
   }
-  const total = info.size
-  const rangeHeader = request.headers.get('range')
-  let start = 0
-  let end = total - 1
-  let partial = false
-  if (rangeHeader !== null) {
-    const parsed = rangeParser(total, rangeHeader)
-    // -1 (unsatisfiable) and -2 (malformed) both answer the same terminal
-    // way; array results always carry at least one range.
-    const first = Array.isArray(parsed) ? parsed[0] : undefined
-    if (first === undefined) {
-      const headers: Record<string, string> = {
-        'Content-Range': 'bytes */' + String(total),
-        'Cache-Control': 'private, no-store',
-        'X-Content-Type-Options': 'nosniff',
-      }
+  // The stat identity of the validated path is compared with the identity of
+  // the file actually opened, so a replacement or re-linking race between the
+  // containment check and the read is refused instead of followed.
+  let before
+  let handle
+  try {
+    before = await stat(canonical)
+    handle = await open(canonical, 'r')
+  } catch {
+    return new Response('not found', { status: 404 })
+  }
+  let streamed = false
+  try {
+    const after = await handle.stat()
+    if (!after.isFile()) return new Response('not a regular file', { status: 403 })
+    /* v8 ignore next 2 -- the replacement race cannot be produced deterministically; this arm refuses it when it happens */
+    if (after.dev !== before.dev || after.ino !== before.ino) {
+      return new Response('file changed during validation', { status: 403 })
+    }
+    const total = after.size
+    const rangeHeader = request.headers.get('range')
+    const ranges = rangeHeader === null ? undefined : rangeParser(total, rangeHeader)
+    if (ranges === -1 || ranges === -2) {
+      // Unsatisfiable and malformed ranges answer the same way.
+      const headers = { ...BASE_HEADERS, 'Content-Range': `bytes */${total}` }
       return new Response(null, { status: 416, headers })
     }
-    start = first.start
-    end = first.end
-    partial = true
+    // Only a single range is honored; a multi-range header gets the full body.
+    const slice = ranges?.length === 1 ? ranges[0] : undefined
+    const { start, end } = slice ?? { start: 0, end: total - 1 }
+    const headers: Record<string, string> = {
+      ...BASE_HEADERS,
+      'Content-Type': mediaType,
+      'Content-Length': String(end - start + 1),
+      'Accept-Ranges': 'bytes',
+    }
+    if (slice !== undefined) headers['Content-Range'] = `bytes ${start}-${end}/${total}`
+    const status = slice === undefined ? 200 : 206
+    // HEAD never opens a stream; an already-aborted client cannot receive a
+    // body either, and the handle closes through the finally below.
+    if (request.method === 'HEAD' || request.signal.aborted) {
+      return new Response(null, { status, headers })
+    }
+    streamed = true
+    const source = addAbortSignal(request.signal, handle.createReadStream(slice))
+    return new Response(Readable.toWeb(source) as ReadableStream<Uint8Array>, { status, headers })
+  } finally {
+    if (!streamed) await handle.close()
   }
-  const body: ReadableStream<Uint8Array> = Readable.toWeb(
-    createReadStream(canonical, partial ? { start, end } : undefined),
-  ) as ReadableStream<Uint8Array>
-  const headers: Record<string, string> = {
-    'Content-Type': mediaType,
-    'Content-Length': String(partial ? end - start + 1 : total),
-    'Accept-Ranges': 'bytes',
-    'Cache-Control': 'private, no-store',
-    'X-Content-Type-Options': 'nosniff',
-  }
-  if (partial) {
-    headers['Content-Range'] = 'bytes ' + String(start) + '-' + String(end) + '/' + String(total)
-  }
-  const head = request.method === 'HEAD'
-  return new Response(head ? null : body, { status: partial ? 206 : 200, headers })
 }
 
 /**
diff --git a/packages/api/session-controller/tests/media-references.host.spec.ts b/packages/api/session-controller/tests/media-references.host.spec.ts
index 74bfb05898..6b8cb90ab2 100644
--- a/packages/api/session-controller/tests/media-references.host.spec.ts
+++ b/packages/api/session-controller/tests/media-references.host.spec.ts
@@ -1,6 +1,6 @@
 import { mkdir, mkdtemp, open, realpath, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { join, sep } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { SessionMediaReferences } from '../src/media-references.ts'
@@ -20,16 +20,24 @@ interface MountedRoute {
   /** Direct request access (custom URLs and headers). */
   raw(url: string, init?: RequestInit): Promise<Response>
   unregister: ReturnType<typeof vi.fn>
+  dispose(): Promise<void>
 }
 
 describe('SessionMediaReferences /api/file', () => {
   let root: string
-  let route: MountedRoute
   const contexts: Context[] = []
 
   beforeEach(async () => {
     // Real workspace roots are canonical; tmpdir may sit behind a symlink.
     root = await realpath(await mkdtemp(join(tmpdir(), 'dsh-media-references-')))
+  })
+
+  afterEach(async () => {
+    await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+    await rm(root, { recursive: true, force: true })
+  })
+
+  async function mount(workspaceRoot: string = root): Promise<MountedRoute> {
     const ctx = new Context()
     contexts.push(ctx)
     let handler: ((request: Request) => Promise<Response>) | undefined
@@ -42,28 +50,30 @@ describe('SessionMediaReferences /api/file', () => {
         },
       },
     } as never)
-    ctx.provide('workspaceRegistry', { list: () => [{ path: root }] } as never)
+    ctx.provide('workspaceRegistry', {
+      list: () => [{ path: workspaceRoot }],
+    } as never)
     await ctx.plugin(SessionMediaReferences).await()
     const fetchFile = (request: Request) => {
       if (handler === undefined) throw new Error('route not registered')
       return handler(request)
     }
-    route = {
+    return {
       call: (path, init) => {
         const url = `http://127.0.0.1:3080/api/file?path=${encodeURIComponent(path)}`
         return fetchFile(new Request(url, init))
       },
       raw: (url, init) => fetchFile(new Request(url, init)),
       unregister,
+      dispose: () => ctx.fiber.dispose().then(() => {
+        const index = contexts.indexOf(ctx)
+        if (index >= 0) contexts.splice(index, 1)
+      }),
     }
-  })
-
-  afterEach(async () => {
-    await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
-    await rm(root, { recursive: true, force: true })
-  })
+  }
 
   it('serves images from the workspace root and nested directories', async () => {
+    const route = await mount()
     const direct = join(root, 'graph.png')
     await writeFile(direct, PNG_BYTES)
     const response = await route.call(direct)
@@ -83,6 +93,7 @@ describe('SessionMediaReferences /api/file', () => {
   })
 
   it('serves every allowlisted media category by extension', async () => {
+    const route = await mount()
     const video = join(root, 'clip.mp4')
     await writeFile(video, MP4_BYTES)
     const videoResponse = await route.call(video)
@@ -99,6 +110,7 @@ describe('SessionMediaReferences /api/file', () => {
   it('serves allowlisted image extensions regardless of payload bytes', async () => {
     // Media bytes are never sniffed on this route: a corrupt payload fails
     // in the browser, not here.
+    const route = await mount()
     const fake = join(root, 'fake.png')
     await writeFile(fake, TEXT_BYTES)
     const response = await route.call(fake)
@@ -107,6 +119,7 @@ describe('SessionMediaReferences /api/file', () => {
   })
 
   it('refuses non-media, unknown, and denied content types', async () => {
+    const route = await mount()
     const cases: ReadonlyArray<[string, Uint8Array]> = [
       ['note.txt', TEXT_BYTES],
       ['run.exe', TEXT_BYTES],
@@ -124,6 +137,7 @@ describe('SessionMediaReferences /api/file', () => {
   })
 
   it('answers bounded, open-ended, suffix, and clamped range requests', async () => {
+    const route = await mount()
     const path = join(root, 'graph.png')
     await writeFile(path, PNG_BYTES)
     const total = PNG_BYTES.length
@@ -149,6 +163,7 @@ describe('SessionMediaReferences /api/file', () => {
   })
 
   it('answers unsatisfiable and malformed ranges with 416 and the total size', async () => {
+    const route = await mount()
     const path = join(root, 'graph.png')
     await writeFile(path, PNG_BYTES)
     for (const range of ['bytes=999-', 'bytes=abc']) {
@@ -158,17 +173,38 @@ describe('SessionMediaReferences /api/file', () => {
     }
   })
 
+  it('ignores multi-range headers and serves the full 200 body', async () => {
+    const route = await mount()
+    const path = join(root, 'graph.png')
+    await writeFile(path, PNG_BYTES)
+    const response = await route.call(path, { headers: { range: 'bytes=0-1,3-4' } })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
+    expect(response.headers.get('content-range')).toBeNull()
+    expect(await responseBytes(response)).toEqual(PNG_BYTES)
+  })
+
   it('answers HEAD without a body', async () => {
+    const route = await mount()
     const path = join(root, 'graph.png')
     await writeFile(path, PNG_BYTES)
     const response = await route.call(path, { method: 'HEAD' })
     expect(response.status).toBe(200)
     expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
+    expect(response.headers.get('content-range')).toBeNull()
     expect(response.body).toBeNull()
+
+    const ranged = await route.call(path, { method: 'HEAD', headers: { range: 'bytes=0-3' } })
+    expect(ranged.status).toBe(206)
+    expect(ranged.headers.get('content-range')).toBe(`bytes 0-3/${PNG_BYTES.length}`)
+    expect(ranged.headers.get('content-length')).toBe('4')
+    expect(ranged.body).toBeNull()
   })
 
-  it('denies malformed, missing, and uncontained requests', async () => {
+  it('denies malformed, missing, empty, and uncontained requests', async () => {
+    const route = await mount()
     expect((await route.raw('http://127.0.0.1:3080/api/file')).status).toBe(400)
+    expect((await route.raw('http://127.0.0.1:3080/api/file?path=')).status).toBe(400)
     expect((await route.raw(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent('x.png')}`)).status)
       .toBe(400)
     expect((await route.raw(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent('/a\0b.png')}`)).status)
@@ -187,20 +223,54 @@ describe('SessionMediaReferences /api/file', () => {
     }
   })
 
-  it('refuses the workspace-root directory itself', async () => {
-    const response = await route.call(root)
+  it('answers 404 when an existing file cannot be opened for reading', async () => {
+    // A permission-less file passes realpath/stat but fails the open; the
+    // route treats the unreadable file like a missing one. chmod has no
+    // effect on Windows, where this case is skipped.
+    if (process.platform === 'win32') return
+    const route = await mount()
+    const path = join(root, 'locked.png')
+    await writeFile(path, PNG_BYTES)
+    const { chmod } = await import('node:fs/promises')
+    await chmod(path, 0o000)
+    try {
+      const response = await route.call(path)
+      expect(response.status).toBe(404)
+    } finally {
+      await chmod(path, 0o600)
+    }
+  })
+
+  it('refuses a directory even when its name carries a media extension', async () => {
+    const route = await mount()
+    const directory = join(root, 'frames.png')
+    await mkdir(directory)
+    const response = await route.call(directory)
     expect(response.status).toBe(403)
     expect(await response.text()).toBe('not a regular file')
   })
 
+  it('serves files when the registered workspace is the filesystem root', async () => {
+    const route = await mount(sep)
+    const path = join(root, 'graph.png')
+    await writeFile(path, PNG_BYTES)
+    const response = await route.call(path)
+    expect(response.status).toBe(200)
+    expect(await responseBytes(response)).toEqual(PNG_BYTES)
+  })
+
   it('follows symlinks for the containment check', async () => {
+    const route = await mount()
     const real = join(root, 'real.png')
     await writeFile(real, PNG_BYTES)
     const link = join(root, 'link.png')
     await symlink(real, link)
     expect((await route.call(link)).status).toBe(200)
 
-    const outsideTarget = join(await realpath(tmpdir()), 'dsh-media-references-target.png')
+    // The escaping target lives in a private directory so concurrent test
+    // processes can never share or delete it.
+    const outside = await realpath(await mkdtemp(join(tmpdir(), 'dsh-media-references-target-')))
+    const outsideTarget = join(outside, 'secret.png')
     await writeFile(outsideTarget, PNG_BYTES)
     try {
       const escaping = join(root, 'escape.png')
@@ -209,11 +279,12 @@ describe('SessionMediaReferences /api/file', () => {
       expect(denied.status).toBe(403)
       expect(await denied.text()).toBe('outside workspace roots')
     } finally {
-      await rm(outsideTarget, { force: true })
+      await rm(outside, { recursive: true, force: true })
     }
   })
 
   it('streams a slice of a large sparse file without buffering it whole', async () => {
+    const route = await mount()
     const path = join(root, 'huge.mp4')
     const handle = await open(path, 'w')
     try {
@@ -227,7 +298,48 @@ describe('SessionMediaReferences /api/file', () => {
     expect((await responseBytes(response)).length).toBe(10)
   })
 
-  it('keeps the route registered until the contribution is disposed', () => {
+  it('closes the file stream when the client aborts mid-response', async () => {
+    const route = await mount()
+    const path = join(root, 'huge.mp4')
+    const handle = await open(path, 'w')
+    try {
+      await handle.truncate(64 * 1024 * 1024)
+    } finally {
+      await handle.close()
+    }
+    const controller = new AbortController()
+    const response = await route.call(path, { signal: controller.signal })
+    expect(response.status).toBe(200)
+    const reader = response.body?.getReader()
+    expect(reader).toBeDefined()
+    await reader?.read()
+    controller.abort()
+    // The abort listener destroys the underlying file stream; reading the web
+    // stream then fails instead of draining the remaining 64 MiB.
+    await expect(reader?.read()).rejects.toBeTruthy()
+  })
+
+  it('destroys the stream immediately for an already-aborted request', async () => {
+    const route = await mount()
+    const path = join(root, 'huge.mp4')
+    const handle = await open(path, 'w')
+    try {
+      await handle.truncate(16 * 1024 * 1024)
+    } finally {
+      await handle.close()
+    }
+    const controller = new AbortController()
+    controller.abort()
+    const response = await route.call(path, { signal: controller.signal })
+    expect(response.status).toBe(200)
+    // No stream is opened for a client that is already gone.
+    expect(response.body).toBeNull()
+  })
+
+  it('unregisters the route when the contribution is disposed', async () => {
+    const route = await mount()
     expect(route.unregister).not.toHaveBeenCalled()
+    await route.dispose()
+    expect(route.unregister).toHaveBeenCalledTimes(1)
   })
 })
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index baa87a9798..7d7ed48693 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: 8e579d9467f1ab8c87bfb11d45354f68229fd138
-README.zh.md: 83dce1bdbdab34cde00e7cfb56c648a1d721421f
+README.md: 026b3a7258f3fe0e659e52e104e8ffa24ac8ad74
+README.zh.md: b08ada245692a7a57aae64d80da95e1ced1d970c
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 8e579d9467..026b3a7258 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -68,7 +68,7 @@ The catalog above lists what each export is for; this section covers the behavio
 
 ### Rendering agent output
 
-`MarkdownText` renders untrusted GFM and TeX math, blocks unsafe links and images, and can turn resolved file mentions into explicit controls. 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.
+`MarkdownText` renders untrusted GFM and TeX math, blocks unsafe links and images, and can turn resolved file mentions into explicit controls. 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 the output is byte-identical. 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.
 
 
 ### Localizing copy
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index 83dce1bdbd..b08ada2456 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -68,7 +68,7 @@ kind: "package-library"
 
 ### 渲染 agent 输出
 
-`MarkdownText` 渲染不可信的 GFM 与 TeX 公式、阻止不安全的链接与图片，并可把已解析的文件提及转换为显式控件。回复流式输出时，它冻结已完成的块、按已完成行推进顶层未闭合 fence，并从保存的 Shiki grammar state 为该 fence 增量高亮。已完成的 token 行进入固定大小的 React 分组，后续分片只 reconcile 正在增长的分组；最终全量解析解决跨文档语法时，未变化的 fence 会保留该 DOM。`TerminalBlock`、`ReadBlock`、`DiffBlock`、`SearchBlock` 与 `WebBlock` 把对应的工具结果意图渲染为带复制控件、溢出处理及适用时 ANSI 处理的卡片。`JsonTree` 与 `JsonBlock` 以只读方式检查 JSON 值；`projectUserText` 把已发送的用户文本投影为行内普通文本段与引用 chip，供消息气泡和排队行使用。
+`MarkdownText` 渲染不可信的 GFM 与 TeX 公式、阻止不安全的链接与图片，并可把已解析的文件提及转换为显式控件。当 owner 传入 `pathImages` 词表时，本地媒体路径的图片目标只在落定渲染阶段重写为可展示 URL（与 file mentions 相同的流式门）；不传词表时输出逐字节不变。回复流式输出时，它冻结已完成的块、按已完成行推进顶层未闭合 fence，并从保存的 Shiki grammar state 为该 fence 增量高亮。已完成的 token 行进入固定大小的 React 分组，后续分片只 reconcile 正在增长的分组；最终全量解析解决跨文档语法时，未变化的 fence 会保留该 DOM。`TerminalBlock`、`ReadBlock`、`DiffBlock`、`SearchBlock` 与 `WebBlock` 把对应的工具结果意图渲染为带复制控件、溢出处理及适用时 ANSI 处理的卡片。`JsonTree` 与 `JsonBlock` 以只读方式检查 JSON 值；`projectUserText` 把已发送的用户文本投影为行内普通文本段与引用 chip，供消息气泡和排队行使用。
 
 
 ### 本地化文案

From ba4a536030fe8f84fa36018271a62432110e4cea Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 18:01:29 +0800
Subject: [PATCH 10/35] fix(api): honor only bytes ranges and ignore malformed
 or multi-range headers

range-parser never validates the range unit, so /api/file now parses only
headers that start with the bytes unit: unsatisfiable ranges answer 416,
while malformed, unknown-unit, and multi-range headers are ignored for a
full 200 body per RFC 9110. The filesystem-root workspace case stays
POSIX-only in tests (a Windows drive-root spelling cannot be constructed
portably); containment already treats any separator-terminated root the
same. Docs (README pair, Agent Note pair) re-recorded.
---
 ...ession-prose-local-media-display.i18n.yaml |  4 +-
 ...09-07-session-prose-local-media-display.md |  2 +-
 ...07-session-prose-local-media-display.zh.md |  2 +-
 .../api/session-controller/README.i18n.yaml   |  4 +-
 packages/api/session-controller/README.md     |  2 +-
 packages/api/session-controller/README.zh.md  |  2 +-
 .../src/media-references.ts                   | 17 +++++---
 .../tests/media-references.host.spec.ts       | 41 +++++++++++++------
 8 files changed, 49 insertions(+), 25 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
index 6eced36c70..04132eddc5 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.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 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
-2026-09-07-session-prose-local-media-display.md: 6599d3e7c1e9838f9191e339fcca3bd811951af8
-2026-09-07-session-prose-local-media-display.zh.md: 8d2121dd206a0719a48a09e91973eb5edf970a6a
+2026-09-07-session-prose-local-media-display.md: fb277ebde175fbf3b331c65d5413400287b2443c
+2026-09-07-session-prose-local-media-display.zh.md: 6e68482db993d9667348560cd522e686ddb657d9
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
index 6599d3e7c1..fb277ebde1 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
@@ -14,7 +14,7 @@ Local media paths in session prose render through one same-origin file route, wi
 
 - **Renderer seam (`ui-primitives`)**: `MarkdownText` gained a `MarkdownPathImages` vocabulary (`pathImages` prop) with the same settled-only gate as `fileMentions`: while a message streams, frozen cached blocks never bake in a vocabulary handler; the settled pass rewrites image destinations that fail the remote-URL allowlist, and a rewritten destination is emitted only when it is an absolute `http(s)`/`blob`/`data` URL. Without a vocabulary the renderer output is byte-identical to before.
 - **Chat wiring (`ui-chat`)**: `AssistantMarkdown` supplies a page-stable vocabulary (`localPathMediaUrl`, module-private in the same file) mapping absolute POSIX paths to same-origin `/api/file?path=…` GETs; non-HTTP transports (Electron `file://`) and relative/protocol-relative destinations stay inert. Windows-style host paths (`C:\...`) are deliberately inert on the client side and are recorded as a limitation in Consequences.
-- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its MIME type must belong to the served categories image/video/audio (resolved by the `mime-types` package, excluding `image/svg+xml`); media bytes are never sniffed on this route. Validation and reading bind to the same opened file: the pre-open and opened stat identities are compared, so a replacement or re-linking race is refused instead of followed. Responses stream with HTTP range support parsed by the `range-parser` package: single-range requests answer 206, multi-range headers are ignored for a full 200 body, HEAD never opens a file stream, and an aborted client destroys the stream. Responses carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
+- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its MIME type must belong to the served categories image/video/audio (resolved by the `mime-types` package, excluding `image/svg+xml`); media bytes are never sniffed on this route. Validation and reading bind to the same opened file: the pre-open and opened stat identities are compared, so a replacement or re-linking race is refused instead of followed. Responses stream with HTTP range support parsed by the `range-parser` package: single-range `bytes` requests answer 206, malformed/unknown-unit/multi-range headers are ignored for a full 200 body, HEAD never opens a file stream, and an aborted client destroys the stream. Responses carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
 
 The route is presentational and stateless: it never writes, follows no redirects, and returns 400/403/404/415/416 instead of approximating another file-serving behavior.
 
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
index 8d2121dd20..6e68482db9 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
@@ -14,7 +14,7 @@ Assistant 正文有时用本地文件系统路径引用图片（markdown `![](/U
 
 - **渲染缝（`ui-primitives`）**：`MarkdownText` 新增 `MarkdownPathImages` 词表（`pathImages` prop），与 `fileMentions` 同用 settled-only 门：消息流式期间冻结的缓存块绝不烘入词表处理器；落定渲染把未通过远程 URL 白名单的图片目标重写为可展示 URL，且只有结果是绝对 `http(s)`/`blob`/`data` URL 时才发射。不提供词表时渲染输出与之前逐字节一致。
 - **聊天接线（`ui-chat`）**：`AssistantMarkdown` 提供页面级稳定的词表（`localPathMediaUrl`，与组件同文件的模块私有函数），把绝对 POSIX 路径映射为同源 `GET /api/file?path=…`；非 HTTP 载体（Electron `file://`）与相对/协议相对目标保持惰性。Windows 风格 Host 路径（`C:\...`）在客户端侧刻意保持惰性，作为局限记录于 Consequences。
-- **Host 路由（`session-controller`）**：`SessionMediaReferences` 是与 `SessionFileReferences` 并列注册的插件贡献，把 `GET|HEAD /api/file` 挂到共享鉴权 `connection.fetch` 通道（与 `/api` RPC 同一 trust fence 与浏览器认证）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace 的情况）、文件必须是常规文件、其 MIME 类型（由 `mime-types` 解析）必须属于受服务类别 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。校验与读取绑定同一个已打开文件：比较打开前后 stat 身份，替换/重链接竞态被拒绝而非跟随。响应由 `range-parser` 解析 Range 后流式输出：单段请求回 206，多段 Range 被忽略并回完整 200，HEAD 从不打开文件流，客户端中止即销毁流；响应携带 `private, no-store` 与 `nosniff`。该贡献只在 `connection` 与 `workspaceRegistry` 均被组合时激活（pending-until-composed，与包内其它可选贡献一致）。
+- **Host 路由（`session-controller`）**：`SessionMediaReferences` 是与 `SessionFileReferences` 并列注册的插件贡献，把 `GET|HEAD /api/file` 挂到共享鉴权 `connection.fetch` 通道（与 `/api` RPC 同一 trust fence 与浏览器认证）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace 的情况）、文件必须是常规文件、其 MIME 类型（由 `mime-types` 解析）必须属于受服务类别 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。校验与读取绑定同一个已打开文件：比较打开前后 stat 身份，替换/重链接竞态被拒绝而非跟随。响应由 `range-parser` 解析 Range 后流式输出：单段 `bytes` 请求回 206，畸形/未知单位/多段 Range 被忽略并回完整 200，HEAD 从不打开文件流，客户端中止即销毁流；响应携带 `private, no-store` 与 `nosniff`。该贡献只在 `connection` 与 `workspaceRegistry` 均被组合时激活（pending-until-composed，与包内其它可选贡献一致）。
 
 该路由纯呈现且无状态：从不写入、不跟随重定向，失败返回 400/403/404/415/416，不近似其它文件服务行为。
 
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index bf9f8b55a9..a66cbc1301 100644
--- a/packages/api/session-controller/README.i18n.yaml
+++ b/packages/api/session-controller/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/api/session-controller/README.md
-README.md: f92fb3eec7fc44a4d83be916bcea80805e2ef2a0
-README.zh.md: 0b2c54e9ac1f42993a8b7eaebf24b0570108ee38
+README.md: c108687ac712dcc7603d0bfdcac11bdc71826357
+README.zh.md: 336734ebf4eb677f853a905443e035b8c8fb909a
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index f92fb3eec7..c108687ac7 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -36,7 +36,7 @@ The Session object also carries local submission echoes: `session.beginSubmissio
 <a id="session-media-references"></a>
 ## Session media references
 
-`SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when both `connection` and `workspaceRegistry` are composed, so conversation prose can display workspace-contained local media (images today; video/audio later) in the browser. Per request the route fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its `mime-types` category must be image/video/audio (excluding `image/svg+xml`); media bytes are never sniffed. Validation and reading bind to the same opened file, so a replacement or re-linking race is refused. Single-range requests stream a 206 slice parsed by `range-parser`; multi-range headers are ignored for a full 200 body; HEAD never opens a file stream; an aborted client destroys it. Responses carry `private, no-store` and `nosniff`; failures answer 400/403/404/415/416. The client-side rewrite vocabulary lives in `ui-chat` (`AssistantMarkdown`); this package owns only the serving contract.
+`SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when both `connection` and `workspaceRegistry` are composed, so conversation prose can display workspace-contained local media (images today; video/audio later) in the browser. Per request the route fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its `mime-types` category must be image/video/audio (excluding `image/svg+xml`); media bytes are never sniffed. Validation and reading bind to the same opened file, so a replacement or re-linking race is refused. Single-range `bytes` requests stream a 206 slice parsed by `range-parser`; malformed, unknown-unit, and multi-range headers are ignored for a full 200 body; HEAD never opens a file stream; an aborted client destroys it. Responses carry `private, no-store` and `nosniff`; failures answer 400/403/404/415/416. The client-side rewrite vocabulary lives in `ui-chat` (`AssistantMarkdown`); this package owns only the serving contract.
 
 -----
 
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index 0b2c54e9ac..336734ebf4 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -36,7 +36,7 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 <a id="session-media-references"></a>
 ## 会话媒体引用
 
-当 `connection` 与 `workspaceRegistry` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`，使会话正文可以引用 workspace 内的本地媒体（图片今天可用；视频/音频后续同一条 URL）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace）、文件必须是常规文件、其 `mime-types` 类别必须属于 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。校验与读取绑定同一个已打开文件，替换/重链接竞态会被拒绝。单段 Range 请求由 `range-parser` 解析后流式返回 206 分片；多段 Range 头被忽略并返回完整 200；HEAD 从不打开文件流；客户端中止即销毁流。响应携带 `private, no-store` 与 `nosniff`；失败返回 400/403/404/415/416。客户端侧的重写词表位于 `ui-chat`（`AssistantMarkdown`）；本包只拥有服务契约。
+当 `connection` 与 `workspaceRegistry` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`，使会话正文可以引用 workspace 内的本地媒体（图片今天可用；视频/音频后续同一条 URL）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace）、文件必须是常规文件、其 `mime-types` 类别必须属于 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。校验与读取绑定同一个已打开文件，替换/重链接竞态会被拒绝。单段 `bytes` Range 请求由 `range-parser` 解析后流式返回 206 分片；畸形、未知单位与多段 Range 头被忽略并返回完整 200；HEAD 从不打开文件流；客户端中止即销毁流。响应携带 `private, no-store` 与 `nosniff`；失败返回 400/403/404/415/416。客户端侧的重写词表位于 `ui-chat`（`AssistantMarkdown`）；本包只拥有服务契约。
 
 -----
 
diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
index 6663fdae35..2da56f758f 100644
--- a/packages/api/session-controller/src/media-references.ts
+++ b/packages/api/session-controller/src/media-references.ts
@@ -98,15 +98,22 @@ async function serveMediaReference(
       return new Response('file changed during validation', { status: 403 })
     }
     const total = after.size
-    const rangeHeader = request.headers.get('range')
-    const ranges = rangeHeader === null ? undefined : rangeParser(total, rangeHeader)
-    if (ranges === -1 || ranges === -2) {
-      // Unsatisfiable and malformed ranges answer the same way.
+    const rangeHeader = request.headers.get('range')?.trim() ?? null
+    // range-parser never validates the range unit, so only a `bytes` header is
+    // parsed here; malformed, unknown-unit, and multi-range headers are ignored
+    // per RFC 9110 and get the full 200 body below.
+    const ranges = rangeHeader !== null && rangeHeader.toLowerCase().startsWith('bytes=')
+      ? rangeParser(total, rangeHeader)
+      : undefined
+    if (ranges === -1) {
+      // Only an unsatisfiable range answers 416 with the total size. Malformed
+      // (-2) and unknown-unit or multi-range headers are ignored per RFC 9110
+      // and get the full 200 body below.
       const headers = { ...BASE_HEADERS, 'Content-Range': `bytes */${total}` }
       return new Response(null, { status: 416, headers })
     }
     // Only a single range is honored; a multi-range header gets the full body.
-    const slice = ranges?.length === 1 ? ranges[0] : undefined
+    const slice = Array.isArray(ranges) && ranges.length === 1 ? ranges[0] : undefined
     const { start, end } = slice ?? { start: 0, end: total - 1 }
     const headers: Record<string, string> = {
       ...BASE_HEADERS,
diff --git a/packages/api/session-controller/tests/media-references.host.spec.ts b/packages/api/session-controller/tests/media-references.host.spec.ts
index 6b8cb90ab2..b90f2e3e5e 100644
--- a/packages/api/session-controller/tests/media-references.host.spec.ts
+++ b/packages/api/session-controller/tests/media-references.host.spec.ts
@@ -162,14 +162,25 @@ describe('SessionMediaReferences /api/file', () => {
     expect(await responseBytes(clamped)).toEqual(PNG_BYTES.slice(6))
   })
 
-  it('answers unsatisfiable and malformed ranges with 416 and the total size', async () => {
+  it('answers unsatisfiable ranges with 416 and the total size', async () => {
     const route = await mount()
     const path = join(root, 'graph.png')
     await writeFile(path, PNG_BYTES)
-    for (const range of ['bytes=999-', 'bytes=abc']) {
+    const response = await route.call(path, { headers: { range: 'bytes=999-' } })
+    expect(response.status).toBe(416)
+    expect(response.headers.get('content-range')).toBe(`bytes */${PNG_BYTES.length}`)
+  })
+
+  it('ignores malformed and unknown-unit ranges for a full 200 body', async () => {
+    const route = await mount()
+    const path = join(root, 'graph.png')
+    await writeFile(path, PNG_BYTES)
+    for (const range of ['bytes=abc', 'items=0-0']) {
       const response = await route.call(path, { headers: { range } })
-      expect(response.status, range).toBe(416)
-      expect(response.headers.get('content-range')).toBe(`bytes */${PNG_BYTES.length}`)
+      expect(response.status, range).toBe(200)
+      expect(response.headers.get('content-range')).toBeNull()
+      expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
+      expect(await responseBytes(response), range).toEqual(PNG_BYTES)
     }
   })
 
@@ -250,14 +261,20 @@ describe('SessionMediaReferences /api/file', () => {
     expect(await response.text()).toBe('not a regular file')
   })
 
-  it('serves files when the registered workspace is the filesystem root', async () => {
-    const route = await mount(sep)
-    const path = join(root, 'graph.png')
-    await writeFile(path, PNG_BYTES)
-    const response = await route.call(path)
-    expect(response.status).toBe(200)
-    expect(await responseBytes(response)).toEqual(PNG_BYTES)
-  })
+  // A POSIX filesystem root is the separator itself; the Windows drive-root
+  // spelling cannot be produced portably, so the case stays POSIX-only. The
+  // containment code treats any separator-terminated root the same way.
+  it.skipIf(process.platform === 'win32')(
+    'serves files when the registered workspace is the filesystem root',
+    async () => {
+      const route = await mount(sep)
+      const path = join(root, 'graph.png')
+      await writeFile(path, PNG_BYTES)
+      const response = await route.call(path)
+      expect(response.status).toBe(200)
+      expect(await responseBytes(response)).toEqual(PNG_BYTES)
+    },
+  )
 
   it('follows symlinks for the containment check', async () => {
     const route = await mount()

From 67c5136c7ea1c2a7c1088797d8db2eeeef1c05cf Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 7 Sep 2026 18:04:07 +0800
Subject: [PATCH 11/35] fix(api): refuse non-regular files before open and
 bound full streams

- A media-named FIFO or device node is refused before the open would
  block on it (pre-open isFile check); POSIX FIFO regression test added.
- The full-body stream is bounded to the stat'ed size so concurrent
  appends cannot exceed the declared Content-Length.
- Error responses carry no body for HEAD requests.
- Docs no longer overclaim the replacement race: the stat-identity
  comparison narrows (does not fully close) the replacement window, and
  the earlier realpath-to-stat window is acknowledged. Pairs re-recorded.
---
 ...ession-prose-local-media-display.i18n.yaml |  4 +-
 ...09-07-session-prose-local-media-display.md |  2 +-
 ...07-session-prose-local-media-display.zh.md |  2 +-
 .../api/session-controller/README.i18n.yaml   |  4 +-
 packages/api/session-controller/README.md     |  2 +-
 packages/api/session-controller/README.zh.md  |  2 +-
 .../src/media-references.ts                   | 51 ++++++++++++-------
 .../tests/media-references.host.spec.ts       | 24 +++++++++
 8 files changed, 66 insertions(+), 25 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
index 04132eddc5..b3ccacf68f 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.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 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
-2026-09-07-session-prose-local-media-display.md: fb277ebde175fbf3b331c65d5413400287b2443c
-2026-09-07-session-prose-local-media-display.zh.md: 6e68482db993d9667348560cd522e686ddb657d9
+2026-09-07-session-prose-local-media-display.md: bd898e6ced09dd55a6d6eeaee7e73b9187cded9d
+2026-09-07-session-prose-local-media-display.zh.md: 80ebe968f86022f3261ac5d2929b71dc68dc7f67
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
index fb277ebde1..bd898e6ced 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
@@ -14,7 +14,7 @@ Local media paths in session prose render through one same-origin file route, wi
 
 - **Renderer seam (`ui-primitives`)**: `MarkdownText` gained a `MarkdownPathImages` vocabulary (`pathImages` prop) with the same settled-only gate as `fileMentions`: while a message streams, frozen cached blocks never bake in a vocabulary handler; the settled pass rewrites image destinations that fail the remote-URL allowlist, and a rewritten destination is emitted only when it is an absolute `http(s)`/`blob`/`data` URL. Without a vocabulary the renderer output is byte-identical to before.
 - **Chat wiring (`ui-chat`)**: `AssistantMarkdown` supplies a page-stable vocabulary (`localPathMediaUrl`, module-private in the same file) mapping absolute POSIX paths to same-origin `/api/file?path=…` GETs; non-HTTP transports (Electron `file://`) and relative/protocol-relative destinations stay inert. Windows-style host paths (`C:\...`) are deliberately inert on the client side and are recorded as a limitation in Consequences.
-- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its MIME type must belong to the served categories image/video/audio (resolved by the `mime-types` package, excluding `image/svg+xml`); media bytes are never sniffed on this route. Validation and reading bind to the same opened file: the pre-open and opened stat identities are compared, so a replacement or re-linking race is refused instead of followed. Responses stream with HTTP range support parsed by the `range-parser` package: single-range `bytes` requests answer 206, malformed/unknown-unit/multi-range headers are ignored for a full 200 body, HEAD never opens a file stream, and an aborted client destroys the stream. Responses carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
+- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its MIME type must belong to the served categories image/video/audio (resolved by the `mime-types` package, excluding `image/svg+xml`); media bytes are never sniffed on this route. Regular-file checks run before opening (a named pipe or device node is refused instead of blocking the open); reading binds to the opened file, and a stat-identity comparison with the pre-open stat narrows, but does not fully close, a concurrent replacement window. Responses stream with HTTP range support parsed by the `range-parser` package: single-range `bytes` requests answer 206, malformed/unknown-unit/multi-range headers are ignored for a full 200 body, HEAD never opens a file stream, and an aborted client destroys the stream. Responses carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
 
 The route is presentational and stateless: it never writes, follows no redirects, and returns 400/403/404/415/416 instead of approximating another file-serving behavior.
 
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
index 6e68482db9..80ebe968f8 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
@@ -14,7 +14,7 @@ Assistant 正文有时用本地文件系统路径引用图片（markdown `![](/U
 
 - **渲染缝（`ui-primitives`）**：`MarkdownText` 新增 `MarkdownPathImages` 词表（`pathImages` prop），与 `fileMentions` 同用 settled-only 门：消息流式期间冻结的缓存块绝不烘入词表处理器；落定渲染把未通过远程 URL 白名单的图片目标重写为可展示 URL，且只有结果是绝对 `http(s)`/`blob`/`data` URL 时才发射。不提供词表时渲染输出与之前逐字节一致。
 - **聊天接线（`ui-chat`）**：`AssistantMarkdown` 提供页面级稳定的词表（`localPathMediaUrl`，与组件同文件的模块私有函数），把绝对 POSIX 路径映射为同源 `GET /api/file?path=…`；非 HTTP 载体（Electron `file://`）与相对/协议相对目标保持惰性。Windows 风格 Host 路径（`C:\...`）在客户端侧刻意保持惰性，作为局限记录于 Consequences。
-- **Host 路由（`session-controller`）**：`SessionMediaReferences` 是与 `SessionFileReferences` 并列注册的插件贡献，把 `GET|HEAD /api/file` 挂到共享鉴权 `connection.fetch` 通道（与 `/api` RPC 同一 trust fence 与浏览器认证）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace 的情况）、文件必须是常规文件、其 MIME 类型（由 `mime-types` 解析）必须属于受服务类别 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。校验与读取绑定同一个已打开文件：比较打开前后 stat 身份，替换/重链接竞态被拒绝而非跟随。响应由 `range-parser` 解析 Range 后流式输出：单段 `bytes` 请求回 206，畸形/未知单位/多段 Range 被忽略并回完整 200，HEAD 从不打开文件流，客户端中止即销毁流；响应携带 `private, no-store` 与 `nosniff`。该贡献只在 `connection` 与 `workspaceRegistry` 均被组合时激活（pending-until-composed，与包内其它可选贡献一致）。
+- **Host 路由（`session-controller`）**：`SessionMediaReferences` 是与 `SessionFileReferences` 并列注册的插件贡献，把 `GET|HEAD /api/file` 挂到共享鉴权 `connection.fetch` 通道（与 `/api` RPC 同一 trust fence 与浏览器认证）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace 的情况）、文件必须是常规文件、其 MIME 类型（由 `mime-types` 解析）必须属于受服务类别 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。常规文件检查在打开前执行（命名管道与设备节点会被拒绝而不是阻塞打开）；读取绑定已打开文件，并与打开前的 stat 做身份比较，收窄（而非完全消除）并发替换窗口。响应由 `range-parser` 解析 Range 后流式输出：单段 `bytes` 请求回 206，畸形/未知单位/多段 Range 被忽略并回完整 200，HEAD 从不打开文件流，客户端中止即销毁流；响应携带 `private, no-store` 与 `nosniff`。该贡献只在 `connection` 与 `workspaceRegistry` 均被组合时激活（pending-until-composed，与包内其它可选贡献一致）。
 
 该路由纯呈现且无状态：从不写入、不跟随重定向，失败返回 400/403/404/415/416，不近似其它文件服务行为。
 
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index a66cbc1301..97a859db57 100644
--- a/packages/api/session-controller/README.i18n.yaml
+++ b/packages/api/session-controller/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/api/session-controller/README.md
-README.md: c108687ac712dcc7603d0bfdcac11bdc71826357
-README.zh.md: 336734ebf4eb677f853a905443e035b8c8fb909a
+README.md: c7ecb98b4f9a791c65b8915e57e710e4038a90de
+README.zh.md: 74f70f167454a0ac76b18cc272c0133b427ca223
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index c108687ac7..c7ecb98b4f 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -36,7 +36,7 @@ The Session object also carries local submission echoes: `session.beginSubmissio
 <a id="session-media-references"></a>
 ## Session media references
 
-`SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when both `connection` and `workspaceRegistry` are composed, so conversation prose can display workspace-contained local media (images today; video/audio later) in the browser. Per request the route fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its `mime-types` category must be image/video/audio (excluding `image/svg+xml`); media bytes are never sniffed. Validation and reading bind to the same opened file, so a replacement or re-linking race is refused. Single-range `bytes` requests stream a 206 slice parsed by `range-parser`; malformed, unknown-unit, and multi-range headers are ignored for a full 200 body; HEAD never opens a file stream; an aborted client destroys it. Responses carry `private, no-store` and `nosniff`; failures answer 400/403/404/415/416. The client-side rewrite vocabulary lives in `ui-chat` (`AssistantMarkdown`); this package owns only the serving contract.
+`SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when both `connection` and `workspaceRegistry` are composed, so conversation prose can display workspace-contained local media (images today; video/audio later) in the browser. Per request the route fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its `mime-types` category must be image/video/audio (excluding `image/svg+xml`); media bytes are never sniffed. Regular-file checks run before opening, so named pipes and device nodes are refused instead of blocking the open; reading binds to the opened file, and a stat-identity comparison with the pre-open stat narrows (does not fully close) a concurrent replacement window. Single-range `bytes` requests stream a 206 slice parsed by `range-parser`; malformed, unknown-unit, and multi-range headers are ignored for a full 200 body; HEAD never opens a file stream; an aborted client destroys it. Responses carry `private, no-store` and `nosniff`; failures answer 400/403/404/415/416. The client-side rewrite vocabulary lives in `ui-chat` (`AssistantMarkdown`); this package owns only the serving contract.
 
 -----
 
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index 336734ebf4..74f70f1674 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -36,7 +36,7 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 <a id="session-media-references"></a>
 ## 会话媒体引用
 
-当 `connection` 与 `workspaceRegistry` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`，使会话正文可以引用 workspace 内的本地媒体（图片今天可用；视频/音频后续同一条 URL）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace）、文件必须是常规文件、其 `mime-types` 类别必须属于 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。校验与读取绑定同一个已打开文件，替换/重链接竞态会被拒绝。单段 `bytes` Range 请求由 `range-parser` 解析后流式返回 206 分片；畸形、未知单位与多段 Range 头被忽略并返回完整 200；HEAD 从不打开文件流；客户端中止即销毁流。响应携带 `private, no-store` 与 `nosniff`；失败返回 400/403/404/415/416。客户端侧的重写词表位于 `ui-chat`（`AssistantMarkdown`）；本包只拥有服务契约。
+当 `connection` 与 `workspaceRegistry` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`，使会话正文可以引用 workspace 内的本地媒体（图片今天可用；视频/音频后续同一条 URL）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace）、文件必须是常规文件、其 `mime-types` 类别必须属于 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。常规文件检查在打开前执行，命名管道与设备节点会被拒绝而不是阻塞打开；读取绑定已打开文件，并与打开前的 stat 做身份比较，收窄（而非完全消除）并发替换窗口。单段 `bytes` Range 请求由 `range-parser` 解析后流式返回 206 分片；畸形、未知单位与多段 Range 头被忽略并返回完整 200；HEAD 从不打开文件流；客户端中止即销毁流。响应携带 `private, no-store` 与 `nosniff`；失败返回 400/403/404/415/416。客户端侧的重写词表位于 `ui-chat`（`AssistantMarkdown`）；本包只拥有服务契约。
 
 -----
 
diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
index 2da56f758f..136559a51a 100644
--- a/packages/api/session-controller/src/media-references.ts
+++ b/packages/api/session-controller/src/media-references.ts
@@ -12,10 +12,11 @@
  * - its MIME type (resolved by `mime-types`) must belong to the served
  *   categories image/video/audio, excluding `image/svg+xml`; media bytes are
  *   never sniffed here, and a corrupt payload fails in the browser;
- * - the file must exist and be a regular file; validation and reading bind to
- *   the same opened file (a replacement or re-linking race between the
- *   containment check and the read is detected by comparing the pre-open and
- *   opened stat identities and refused);
+ * - the file must exist and be a regular file (checked before opening, so a
+ *   named pipe or device node is refused instead of blocking the open);
+ *   reading binds to the opened file, and comparing its stat identity with
+ *   the pre-open stat narrows (does not fully close) a concurrent
+ *   replacement window;
  * - multi-range requests are answered with the full 200 body (no Range is
  *   honored) rather than a mislabeled single-segment 206;
  * - responses are private, uncached, sniff-proof, and stream with HTTP range
@@ -58,44 +59,57 @@ async function serveMediaReference(
   request: Request,
   roots: readonly { path: string }[],
 ): Promise<Response> {
+  // Error responses carry a text body for GET debugging; HEAD responses must
+  // never carry one.
+  const fail = (status: number, text: string): Response =>
+    new Response(request.method === 'HEAD' ? null : text, { status })
   const path = new URL(request.url).searchParams.get('path')
-  if (path === null || path.length === 0) return new Response('missing path', { status: 400 })
+  if (path === null || path.length === 0) return fail(400, 'missing path')
   if (path.includes('\0') || !isAbsolute(path)) {
-    return new Response('absolute path required', { status: 400 })
+    return fail(400, 'absolute path required')
   }
   let canonical: string
   try {
     canonical = await realpath(path)
   } catch {
-    return new Response('not found', { status: 404 })
+    return fail(404, 'not found')
   }
   // Containment compares path components; a filesystem root already ends in
   // the separator and prefixes every absolute path.
   const contained = roots.some(({ path: root }) =>
     canonical === root || canonical.startsWith(root.endsWith(sep) ? root : root + sep))
-  if (!contained) return new Response('outside workspace roots', { status: 403 })
+  if (!contained) return fail(403, 'outside workspace roots')
   const mediaType = mime.lookup(canonical)
   if (mediaType === false || mediaType === 'image/svg+xml' || !SERVED_MEDIA_TYPE.test(mediaType)) {
-    return new Response('not an allowlisted media type', { status: 415 })
+    return fail(415, 'not an allowlisted media type')
   }
-  // The stat identity of the validated path is compared with the identity of
-  // the file actually opened, so a replacement or re-linking race between the
-  // containment check and the read is refused instead of followed.
+  // Open only after proving the validated path is a regular file: opening a
+  // FIFO or device node first would block or read unbounded data.
   let before
-  let handle
   try {
     before = await stat(canonical)
+  } catch {
+    /* v8 ignore next 1 -- the path cannot vanish between the realpath above and this stat except in a concurrent deletion race */
+    return fail(404, 'not found')
+  }
+  if (!before.isFile()) return fail(403, 'not a regular file')
+  let handle
+  try {
     handle = await open(canonical, 'r')
   } catch {
-    return new Response('not found', { status: 404 })
+    return fail(404, 'not found')
   }
   let streamed = false
   try {
     const after = await handle.stat()
-    if (!after.isFile()) return new Response('not a regular file', { status: 403 })
+    /* v8 ignore next 1 -- only a concurrent replacement could make the opened file non-regular after the pre-open check */
+    if (!after.isFile()) return fail(403, 'not a regular file')
+    // The opened handle's identity must match the validated stat; this only
+    // narrows a replacement race between the stat and the open, it does not
+    // eliminate the earlier realpath-to-stat window.
     /* v8 ignore next 2 -- the replacement race cannot be produced deterministically; this arm refuses it when it happens */
     if (after.dev !== before.dev || after.ino !== before.ino) {
-      return new Response('file changed during validation', { status: 403 })
+      return fail(403, 'file changed during validation')
     }
     const total = after.size
     const rangeHeader = request.headers.get('range')?.trim() ?? null
@@ -129,7 +143,10 @@ async function serveMediaReference(
       return new Response(null, { status, headers })
     }
     streamed = true
-    const source = addAbortSignal(request.signal, handle.createReadStream(slice))
+    // Bound the full-body stream to the stat'ed size so concurrent appends
+    // cannot push the payload past the declared Content-Length.
+    const stream = handle.createReadStream(slice ?? { start: 0, end: total - 1 })
+    const source = addAbortSignal(request.signal, stream)
     return new Response(Readable.toWeb(source) as ReadableStream<Uint8Array>, { status, headers })
   } finally {
     if (!streamed) await handle.close()
diff --git a/packages/api/session-controller/tests/media-references.host.spec.ts b/packages/api/session-controller/tests/media-references.host.spec.ts
index b90f2e3e5e..da4a22d42d 100644
--- a/packages/api/session-controller/tests/media-references.host.spec.ts
+++ b/packages/api/session-controller/tests/media-references.host.spec.ts
@@ -212,6 +212,13 @@ describe('SessionMediaReferences /api/file', () => {
     expect(ranged.body).toBeNull()
   })
 
+  it('answers HEAD errors without a body', async () => {
+    const route = await mount()
+    const response = await route.raw('http://127.0.0.1:3080/api/file', { method: 'HEAD' })
+    expect(response.status).toBe(400)
+    expect(response.body).toBeNull()
+  })
+
   it('denies malformed, missing, empty, and uncontained requests', async () => {
     const route = await mount()
     expect((await route.raw('http://127.0.0.1:3080/api/file')).status).toBe(400)
@@ -234,6 +241,23 @@ describe('SessionMediaReferences /api/file', () => {
     }
   })
 
+  // A FIFO would block a plain open; the pre-open regular-file check refuses
+  // it first. POSIX-only because Windows has no named-pipe path construction
+  // here.
+  it.skipIf(process.platform === 'win32')(
+    'refuses a FIFO named as media without blocking on the open',
+    async () => {
+      const route = await mount()
+      const pipe = join(root, 'stream.png')
+      const { execFile } = await import('node:child_process')
+      const { promisify } = await import('node:util')
+      await promisify(execFile)('mkfifo', [pipe])
+      const response = await route.call(pipe)
+      expect(response.status).toBe(403)
+      expect(await response.text()).toBe('not a regular file')
+    },
+  )
+
   it('answers 404 when an existing file cannot be opened for reading', async () => {
     // A permission-less file passes realpath/stat but fails the open; the
     // route treats the unreadable file like a missing one. chmod has no

From b52966922a29e08ebd82312adf75b2251e1d6a11 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 12:06:11 +0800
Subject: [PATCH 12/35] fix(api): serve bounded files through the filesystem
 provider

---
 ...ession-prose-local-media-display.i18n.yaml |   4 +-
 ...09-07-session-prose-local-media-display.md |  41 +-
 ...07-session-prose-local-media-display.zh.md |  41 +-
 ...-file-display-through-filesystem.i18n.yaml |   6 +
 ...6-09-08-file-display-through-filesystem.md |  35 ++
 ...9-08-file-display-through-filesystem.zh.md |  35 ++
 THIRD_PARTY_NOTICES.md                        |   2 -
 docs/config-catalog.i18n.yaml                 |   4 +-
 docs/config-catalog.md                        |   4 +
 docs/config-catalog.zh.md                     |   4 +
 .../api/session-controller/README.i18n.yaml   |   4 +-
 packages/api/session-controller/README.md     |   6 +-
 packages/api/session-controller/README.zh.md  |   6 +-
 packages/api/session-controller/package.json  |   7 +-
 packages/api/session-controller/src/index.ts  |  10 +-
 .../src/media-references.ts                   | 194 ++------
 .../tests/media-references.host.spec.ts       | 462 ++++++------------
 .../api/session-controller/tsconfig.host.json |   1 +
 pnpm-lock.yaml                                |  12 +-
 19 files changed, 367 insertions(+), 511 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md
 create mode 100644 .agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.zh.md

diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
index b3ccacf68f..c52f0a47a2 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.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 .agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
-2026-09-07-session-prose-local-media-display.md: bd898e6ced09dd55a6d6eeaee7e73b9187cded9d
-2026-09-07-session-prose-local-media-display.zh.md: 80ebe968f86022f3261ac5d2929b71dc68dc7f67
+2026-09-07-session-prose-local-media-display.md: ed740acd0d0d6eaf7f8834dc8d6280a33305aecd
+2026-09-07-session-prose-local-media-display.zh.md: de8a7f99d7aabc4474f525f9f37f50a465a80840
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
index bd898e6ced..ed740acd0d 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.md
@@ -6,37 +6,38 @@ English | [中文](2026-09-07-session-prose-local-media-display.zh.md)
 
 ## Problem
 
-Assistant prose sometimes references an image by its local filesystem path (markdown `![](/Users/.../x.png)`). The Web renderer only allowed absolute HTTP(S) image destinations, so such references fell back to inert alt text: the browser cannot read Host files, and nothing served them. Searches of the formal and external issue trackers found no existing record, and issue #3662 logged the gap (Web cannot display local-path images referenced by agent answers).
+Assistant prose can reference an image by its filesystem path, but browsers cannot read Host files. A renderer limited to absolute HTTP(S) destinations leaves those references as inert alt text. Issue #3662 records this display gap.
 
 ## Decision
 
-Local media paths in session prose render through one same-origin file route, with the rewrite vocabulary and the serving policy each owned where the repo's seams say they belong.
+Local media paths in Session prose render through a same-origin file route. This note owns the renderer vocabulary and its placement; [authenticated filesystem reads](2026-09-08-file-display-through-filesystem.md) owns the current serving policy and supersedes the workspace/media restrictions described below.
 
-- **Renderer seam (`ui-primitives`)**: `MarkdownText` gained a `MarkdownPathImages` vocabulary (`pathImages` prop) with the same settled-only gate as `fileMentions`: while a message streams, frozen cached blocks never bake in a vocabulary handler; the settled pass rewrites image destinations that fail the remote-URL allowlist, and a rewritten destination is emitted only when it is an absolute `http(s)`/`blob`/`data` URL. Without a vocabulary the renderer output is byte-identical to before.
-- **Chat wiring (`ui-chat`)**: `AssistantMarkdown` supplies a page-stable vocabulary (`localPathMediaUrl`, module-private in the same file) mapping absolute POSIX paths to same-origin `/api/file?path=…` GETs; non-HTTP transports (Electron `file://`) and relative/protocol-relative destinations stay inert. Windows-style host paths (`C:\...`) are deliberately inert on the client side and are recorded as a limitation in Consequences.
-- **Host route (`session-controller`)**: `SessionMediaReferences`, a plugin contribution registered beside `SessionFileReferences`, mounts `GET|HEAD /api/file` on the shared authenticated `connection.fetch` channel (same trust fence and browser authentication as `/api` RPC). Per request it fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its MIME type must belong to the served categories image/video/audio (resolved by the `mime-types` package, excluding `image/svg+xml`); media bytes are never sniffed on this route. Regular-file checks run before opening (a named pipe or device node is refused instead of blocking the open); reading binds to the opened file, and a stat-identity comparison with the pre-open stat narrows, but does not fully close, a concurrent replacement window. Responses stream with HTTP range support parsed by the `range-parser` package: single-range `bytes` requests answer 206, malformed/unknown-unit/multi-range headers are ignored for a full 200 body, HEAD never opens a file stream, and an aborted client destroys the stream. Responses carry `private, no-store` and `nosniff`. The contribution activates only where `connection` and `workspaceRegistry` are composed (pending-until-composed, like the package's other optional contributions).
+`ui-primitives` owns the `MarkdownPathImages` vocabulary on `MarkdownText`. Like `fileMentions`, it applies only after a message settles so frozen streaming blocks cannot cache a vocabulary handler. The settled pass rewrites image destinations outside the remote-URL allowlist and emits only absolute `http(s)`, `blob`, or `data` results. Without a vocabulary, local destinations retain inert alt text. Failed loads replace the image with authored alt text, or its original destination when alt is empty; a different source can load again.
 
-The route is presentational and stateless: it never writes, follows no redirects, and returns 400/403/404/415/416 instead of approximating another file-serving behavior.
+`ui-chat` supplies a page-stable `localPathMediaUrl` vocabulary through `AssistantMarkdown`. It maps absolute POSIX paths to `/api/file?path=…` on the page's origin. Relative and protocol-relative paths, Windows-style paths, and non-HTTP page transports such as Electron `file://` remain inert.
+
+`session-controller` owns the `SessionMediaReferences` contribution beside `SessionFileReferences`. It registers through `connection.fetch`, which applies the same browser authentication and trust checks as `/api` RPC. The fixed same-origin endpoint gives the synchronous renderer a stable URL without an asynchronous capability negotiation.
 
 ## Alternatives considered
 
-- **Register on the Typert gateway**: the gateway owns Remote RPC dispatch (endpoint claims, WebSocket mux, forwarded events), not file serving; placing the route there put HTTP presentation of workspace files into the RPC transport layer. Rejected and fully reverted.
-- **Register under `workspace-controller`**: that package owns workspace registry lifecycle (CRUD, ordering, feed), and shares only the registry as a policy data source. Rejected and fully reverted.
-- **Fetch bytes over the session RPC and show blob/data URLs**: attachment images already do this, but markdown rewriting needs a deterministic synchronous URL at render time (streaming freeze caches, memoization); an async round trip cannot be the render seam. Rejected.
-- **A per-image or image-only route**: media types share one path-and-contain policy; video/audio need range streaming anyway. One `/api/file` route with an extension allowlist covers all current and next media types. Rejected as narrower alternatives.
-- **Byte-signature checks on image extensions**: rejected. The identical check already ships inside `fs/tool-fs`'s `read_image` tool, the repository's cross-file duplication gate forbids cloning it here, and no shared owner exists without widening the attachment package's public API for one helper. The extension allowlist already keeps non-media content out, and a corrupt image payload fails in the browser, not on the route.
-- **Per-request interactive authorization, client-negotiated endpoints, or arbitrary host paths**: the rewrite is presentation; the route re-validates every request and limits readable bytes to registered workspace roots and allowlisted media, and the same-origin endpoint is a fixed channel contract rather than a negotiated capability. Rejected for security and determinism reasons.
+**Typert gateway or workspace controller ownership.** The gateway owns Remote RPC dispatch, while the workspace controller owns registry lifecycle. Neither owns file-byte presentation; Session Controller is the consumer serving Session prose.
+
+**Session RPC followed by blob/data URLs.** Attachment images can use an asynchronous fetch, but this Markdown vocabulary must synchronously resolve a destination during a memoized render pass.
+
+**Image-only endpoints.** One file route can serve images, audio, and video without separate URL vocabularies. The current implementation returns complete bounded files; Markdown audio/video player nodes remain independent work.
+
+**Byte-signature validation in the route.** The model-facing `read_image` tool owns image admission checks. Display responses describe content by MIME lookup and let browser decoding reject corrupt payloads, avoiding a duplicate signature checker.
+
+**Workspace/media-only access (superseded).** The original policy restricted canonical paths to registered workspace roots and allowed image/video/audio MIME categories except SVG. Regular-file checks before opening rejected pipes and devices; an opened-handle identity comparison narrowed replacement races. These restrictions bounded authenticated access and avoided a per-request interactive authorization flow. They also excluded temporary screenshots and remote files; the successor note records the replacement policy and why those restrictions are not retained.
 
 ## Consequences
 
-- Assistant prose that references workspace-contained image files now displays them in Web chat; previously inert alt text disappears only where the host can serve the bytes.
-- Policy is enforced host-side per request; the client vocabulary never expands what the route allows. Media typing trusts the MIME category allowlist; byte-signature validation stays with the `read_image` tool that owns it.
-- Existence disclosure: an authenticated same-origin client can tell an existing-but-outside-workspace path (403) from a nonexistent one (404). Readable bytes stay confined to workspace roots, so the impact is limited to existence probing, and the distinct statuses are kept intentionally.
-- Windows-host limitation: the client vocabulary rewrites only absolute POSIX paths, so a Windows-style `C:\...` destination stays inert alt text even though the route's own `isAbsolute` would accept it; serving such references is deferred.
-- Scope is deliberately narrow: only files under registered workspace roots with allowlisted media types are served; anything else keeps the authored fallback. Trajectory and tool-card markdown consumers do not pass a vocabulary yet, and video/audio markdown nodes are not rendered as `<video>`/`<audio>` yet — the URL layer already supports them.
-- The client hardcodes the `/api/file` endpoint as a same-origin channel contract; this is stable by construction because the page is served by the same host that mounts the route.
-- Related history: the archived note [model-readable image paths](../../archived/feature/2026-08-21-model-readable-image-paths.md) decided the model-facing side of local image paths; this note owns the user-facing display side and does not supersede it.
+The Client vocabulary cannot bypass Host authentication or the filesystem provider. The original restricted route distinguished an existing outside-workspace path from an absent path, exposing existence even while refusing its bytes; the successor policy instead permits ordinary provider-readable files.
+
+Windows-style authored paths remain unsupported by the Client vocabulary. Trajectory and tool-card Markdown consumers do not supply this vocabulary, and audio/video Markdown nodes do not render players. These are renderer limitations, independent of the file route's readable MIME types.
+
+The archived [model-readable image paths](../../archived/feature/2026-08-21-model-readable-image-paths.md) note owns the model-facing behavior; this note owns user-facing display and does not supersede it.
 
 ## Testing
 
-Unit coverage: the renderer seam (settled and streaming gates, reference-style images, protocol re-checks), the chat vocabulary and component wiring, and the host route policy exercised through the registered route (containment incl. symlinks and filesystem-root workspaces, MIME category allowlist, single/multi-range and 416 answers, HEAD without a stream, client-abort destruction, unregister-on-dispose). `media-references.ts` sits at 100% statements/branches/functions/lines. Local gates at this state: typecheck, oxlint, duplication, translation pairing, and the touched suites all pass. Deferred to the PR follow-up: keyless recorded-session replay for the end-to-end GUI path and the browser demo GIF the GUI PR evidence chain requires.
+Renderer tests cover settled and streaming gates, reference-style images, protocol rechecks, failed-load fallback, and replacement sources. Chat tests cover the vocabulary and component wiring. The browser scenario in `apps/web/tests/markdown-images.e2e.ts` boots the shipped Web composition with a seeded Session and checks actual loading and fallback text. A model-driven recorded Session round trip remains separate from this UI expectation; the successor note names current route coverage.
diff --git a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
index 80ebe968f8..de8a7f99d7 100644
--- a/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-07-session-prose-local-media-display.zh.md
@@ -6,37 +6,38 @@ Status: implemented
 
 ## Problem
 
-Assistant 正文有时用本地文件系统路径引用图片（markdown `![](/Users/.../x.png)`）。Web 渲染器只允许绝对 HTTP(S) 图片目标，这类引用只能回退为惰性 alt 文本：浏览器读不到 Host 文件，也没有任何东西提供这些字节。检索正式与外部 Issue 仓库均无既有记录，issue #3662 记录了这一缺口（Web 无法显示 Agent 回答引用的本地路径图片）。
+Assistant 正文可能通过文件系统路径引用图片，但浏览器无法读取 Host 文件。仅允许绝对 HTTP(S) 目标的渲染器会把这些引用保留为静态 alt 文本。Issue #3662 记录了这一展示缺口。
 
 ## Decision
 
-会话正文中的本地媒体路径通过一条同源文件路由渲染；重写词表与服务政策分别归属于仓库现有缝对应的位置。
+Session 正文中的本地媒体路径通过同源文件路由渲染。本记录拥有渲染器词表及其归属；[鉴权文件系统读取](2026-09-08-file-display-through-filesystem.zh.md)拥有当前文件服务策略，并取代下文的工作区与媒体限制。
 
-- **渲染缝（`ui-primitives`）**：`MarkdownText` 新增 `MarkdownPathImages` 词表（`pathImages` prop），与 `fileMentions` 同用 settled-only 门：消息流式期间冻结的缓存块绝不烘入词表处理器；落定渲染把未通过远程 URL 白名单的图片目标重写为可展示 URL，且只有结果是绝对 `http(s)`/`blob`/`data` URL 时才发射。不提供词表时渲染输出与之前逐字节一致。
-- **聊天接线（`ui-chat`）**：`AssistantMarkdown` 提供页面级稳定的词表（`localPathMediaUrl`，与组件同文件的模块私有函数），把绝对 POSIX 路径映射为同源 `GET /api/file?path=…`；非 HTTP 载体（Electron `file://`）与相对/协议相对目标保持惰性。Windows 风格 Host 路径（`C:\...`）在客户端侧刻意保持惰性，作为局限记录于 Consequences。
-- **Host 路由（`session-controller`）**：`SessionMediaReferences` 是与 `SessionFileReferences` 并列注册的插件贡献，把 `GET|HEAD /api/file` 挂到共享鉴权 `connection.fetch` 通道（与 `/api` RPC 同一 trust fence 与浏览器认证）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace 的情况）、文件必须是常规文件、其 MIME 类型（由 `mime-types` 解析）必须属于受服务类别 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。常规文件检查在打开前执行（命名管道与设备节点会被拒绝而不是阻塞打开）；读取绑定已打开文件，并与打开前的 stat 做身份比较，收窄（而非完全消除）并发替换窗口。响应由 `range-parser` 解析 Range 后流式输出：单段 `bytes` 请求回 206，畸形/未知单位/多段 Range 被忽略并回完整 200，HEAD 从不打开文件流，客户端中止即销毁流；响应携带 `private, no-store` 与 `nosniff`。该贡献只在 `connection` 与 `workspaceRegistry` 均被组合时激活（pending-until-composed，与包内其它可选贡献一致）。
+`ui-primitives` 拥有 `MarkdownText` 上的 `MarkdownPathImages` 词表。与 `fileMentions` 一样，它只在消息稳定后生效，使冻结的流式块无法缓存词表处理函数。稳定渲染过程重写远程 URL 白名单之外的图片目标，并只输出绝对 `http(s)`、`blob` 或 `data` 结果。没有词表时，本地目标保留静态 alt 文本。加载失败会把图片替换为作者提供的 alt 文本；alt 为空时显示原始目标路径；不同来源仍可重新加载。
 
-该路由纯呈现且无状态：从不写入、不跟随重定向，失败返回 400/403/404/415/416，不近似其它文件服务行为。
+`ui-chat` 通过 `AssistantMarkdown` 提供页面稳定的 `localPathMediaUrl` 词表。它把绝对 POSIX 路径映射到页面同源的 `/api/file?path=…`。相对路径、协议相对路径、Windows 风格路径，以及 Electron `file://` 等非 HTTP 页面传输保持静态回退。
+
+`session-controller` 在 `SessionFileReferences` 旁拥有 `SessionMediaReferences` 贡献。它通过 `connection.fetch` 注册；该通道执行与 `/api` RPC 相同的浏览器鉴权和信任检查。固定同源端点让同步渲染器获得稳定 URL，无需异步能力协商。
 
 ## Alternatives considered
 
-- **注册到 Typert gateway**：gateway 负责 Remote RPC 分发（endpoint 认领、WebSocket mux、转发事件），不负责文件服务；把路由放那里等于把 workspace 文件的 HTTP 呈现塞进 RPC 传输层。否决并完整回滚。
-- **注册到 `workspace-controller`**：该包负责 workspace 注册表生命周期（CRUD、排序、feed），与文件呈现只共享 registry 这一政策数据源。否决并完整回滚。
-- **经会话 RPC 取字节后显示 blob/data URL**：附件图片已如此工作，但 markdown 重写需要渲染时确定性同步 URL（流式冻结缓存、memo 化）；异步往返不能成为渲染缝。否决。
-- **逐图片或仅图片专用路由**：媒体类型共享同一条「路径 + 包含」政策，视频/音频本就需要 Range 流式；一条 `/api/file` 路由加扩展名 allowlist 即可覆盖现有与后续媒体类型。作为更窄的方案被否决。
-- **手写 MIME 表、Range 解析与图片签名校验**：否决，改用维护中的包（`mime-types`、`range-parser`）且不做嗅探。其中字节签名校验被否决的理由是：相同检查已在 `fs/tool-fs` 的 `read_image` 工具内实现，仓库的跨文件克隆门禁止在此复制，而为单个辅助函数加宽 attachment 包公开 API 没有共享归属。扩展名 allowlist 已把非媒体内容挡在门外，损坏的图片载荷失败发生在浏览器侧而不是路由上。
-- **每请求交互授权、客户端协商端点或任意 Host 路径**：重写只是呈现；路由对每次请求复验，可读字节限制在注册 workspace 根与 allowlist 媒体内；同源端点是固定通道契约而非协商能力。出于安全与确定性否决。
+**由 Typert gateway 或 workspace controller 拥有。** gateway 拥有 Remote RPC 分发，workspace controller 拥有注册表生命周期。两者都不拥有文件字节展示；Session Controller 是服务 Session 正文的消费方。
+
+**先经 Session RPC 获取，再使用 blob/data URL。** 附件图片可以异步获取，但此 Markdown 词表必须在记忆化渲染过程中同步解析目标。
+
+**图片专用端点。** 单一文件路由即可服务图片、音频和视频，无需独立 URL 词表。当前实现返回有界完整文件；Markdown 音视频播放器节点仍是独立工作。
+
+**路由中的字节签名校验。** 面向模型的 `read_image` 工具拥有图片准入检查。展示响应通过 MIME 查询描述内容，由浏览器解码拒绝损坏载荷，避免重复实现签名检查器。
+
+**仅限工作区与媒体的访问（已取代）。** 原策略把规范路径限制在已注册工作区根目录内，并允许除 SVG 外的 image/video/audio MIME 类别。打开前的普通文件检查拒绝管道与设备；已打开句柄的身份比较收窄替换竞态。这些限制约束了鉴权后的访问范围，并避免每次请求的交互授权流程。它们也排除了临时截图与远程文件；后续记录说明替代策略及不保留这些限制的理由。
 
 ## Consequences
 
-- 引用 workspace 内图片文件的 Assistant 正文现在可在 Web 聊天中显示；原先惰性的 alt 文本只在 Host 无法提供字节时保留。
-- 政策在 Host 端每次请求强制；客户端词表不会扩大路由放行的范围。媒体类型判定信任 MIME 类别 allowlist；字节签名校验保留在其所有者 `read_image` 工具中。
-- 存在性泄露：已鉴权同源客户端可区分「存在但在 workspace 外」（403）与「不存在」（404）。可读字节仍被限定在 workspace 根内，影响仅限于存在性探测，保留不同状态码是有意决定。
-- Windows Host 局限：客户端词表只重写绝对 POSIX 路径，Windows 风格 `C:\...` 目标保持惰性 alt 文本（尽管路由侧 `isAbsolute` 本可接受）；服务此类引用留待后续。
-- 范围刻意收窄：只服务注册 workspace 根内、媒体 allowlist 内的文件；其它一律保持作者原样的回退。Trajectory 与工具卡片等 markdown 消费方尚未传词表，视频/音频 markdown 节点也尚未渲染为 `<video>`/`<audio>`——URL 层已为它们准备好。
-- 客户端把 `/api/file` 硬编码为同源通道契约；由于页面与挂载路由的 Host 同源，该契约按构造稳定。
-- 相关历史：已归档笔记 [model-readable image paths](../../archived/feature/2026-08-21-model-readable-image-paths.md) 决定本地图片路径面向模型的一侧；本笔记拥有面向用户展示的一侧，不构成对其的取代。
+客户端词表无法绕过 Host 鉴权或文件系统提供方。原受限路由区分了工作区外已存在路径与缺失路径，即使拒绝其字节仍暴露存在性；后续策略则允许提供方可读的普通文件。
+
+客户端词表仍不支持作者提供的 Windows 风格路径。轨迹与工具卡片 Markdown 消费方不提供此词表，音视频 Markdown 节点也不渲染播放器。这些属于渲染器限制，与文件路由可读的 MIME 类型无关。
+
+已归档的[模型可读图片路径](../../archived/feature/2026-08-21-model-readable-image-paths.md)记录拥有模型侧行为；本记录拥有用户侧展示，不取代它。
 
 ## Testing
 
-单元覆盖：渲染缝（落定与流式门、引用式图片、协议复检）、聊天词表与组件接线、以及经注册路由施加的 Host 路由政策（包含关系含符号链接与文件系统根 workspace、MIME 类别 allowlist、单/多段 Range 与 416 应答、HEAD 不开流、客户端中止即销毁、释放即注销）。`media-references.ts` 语句/分支/函数/行覆盖率均为 100%。当前状态本地门禁：typecheck、oxlint、duplication、translation pairing 与受影响套件全部通过。推迟到 PR 后续：端到端 GUI 路径的 keyless 录播回放，以及 GUI PR 证据链要求的浏览器演示 GIF。
+渲染器测试覆盖稳定与流式门禁、引用式图片、协议复查、加载失败回退和来源替换。聊天测试覆盖词表与组件连接。`apps/web/tests/markdown-images.e2e.ts` 浏览器场景使用已播种 Session 启动交付的 Web 组合，检查实际加载与回退文本。模型驱动的记录 Session 往返仍独立于此 UI 期望；后续记录说明当前路由覆盖。
diff --git a/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.i18n.yaml b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.i18n.yaml
new file mode 100644
index 0000000000..e88fd1e0e8
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 .agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md
+2026-09-08-file-display-through-filesystem.md: 6ff0c855ff0286c7ca7602ed2442a0fae6245c92
+2026-09-08-file-display-through-filesystem.zh.md: 5f8754ce91b53d964bdde03fb067dca858d3551a
diff --git a/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md
new file mode 100644
index 0000000000..6ff0c855ff
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md
@@ -0,0 +1,35 @@
+# Agent Note: Authenticated file display reuses filesystem byte reads
+
+Status: implemented
+
+English | [中文](2026-09-08-file-display-through-filesystem.zh.md)
+
+## Problem
+
+Session prose can reference screenshots in temporary directories or files stored by a remote filesystem provider. A Host-local workspace allowlist cannot serve those paths. An image response without a byte limit can also make the browser download a 1 GiB image before attempting to decode it.
+
+## Decision
+
+The authenticated `/api/file` route reads ordinary files through `ctx.fs`. Authentication and the composed provider's read policy govern access; directory and MIME allowlists do not. This supersedes the serving policy in [the local-media display note](2026-09-07-session-prose-local-media-display.md), which retains renderer ownership and its rationale.
+
+GET calls the existing `readBytes(target, signal, maxBytes)`: providers reject known oversized files before content I/O and enforce the limit while reading. HEAD uses metadata without reading content. `FS_TOO_LARGE` becomes 413. MIME lookup supplies response metadata without sniffing file contents; unknown extensions use `application/octet-stream`. A sandbox CSP prevents directly opened HTML/SVG from executing with the authenticated API origin.
+
+`maxImageBytes` bounds images; `maxFileBytes` independently bounds audio, video, and other files. Both configuration overrides default to the resolved attachment image limit, normally 20 MiB. Separate overrides let deployments raise the non-image limit without weakening image admission. All responses contain complete files; Range is ignored and no range support is advertised.
+
+## Alternatives considered
+
+**Workspace and media allowlists.** They limit which authenticated bytes can be read, but exclude ordinary screenshot locations and remote files. The chosen policy permits every regular file the composed provider can read.
+
+**A new filesystem byte-stream API.** Efficient large-file delivery and audio/video seeking would require implementations in every provider, including remote range handling. Complete bounded reads satisfy the current display scope without widening that interface. Streaming and Range can be added when those use cases justify the provider work.
+
+**Duplicate size checks in the route.** GET needs no additional stat/read loop: `readBytes` already owns preflight limits, growth detection, and cancellation. HEAD checks size separately because it must not read the body.
+
+## Consequences
+
+Temporary and remote files use the same filesystem provider as `read_image`, without adding model-facing events. The local sandbox provider constrains mutations and permits reads; an authenticated client therefore has broader access than registered workspace roots. Files remain subject to the provider's permissions and the route's byte limits.
+
+Each GET buffers the complete file in Host memory. Audio/video work as complete responses without incremental transfer or guaranteed seeking. Encoded byte limits do not bound decoded pixel dimensions. Failed image loads show authored alt text or the original destination when alt is empty.
+
+## Testing
+
+Route tests cover sparse 1 GiB rejection before content I/O, post-stat growth, separate byte limits, ordinary MIME types, temporary paths and symlinks, opaque remote targets, provider failures, metadata-only HEAD, ignored Range, and disposal. Browser expectations cover rendered images, 413/404 and corrupt-image fallbacks, and an image outside the workspace. Remote byte transfer remains owned by the existing filesystem provider tests.
diff --git a/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.zh.md b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.zh.md
new file mode 100644
index 0000000000..5f8754ce91
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 鉴权文件展示复用文件系统字节读取
+
+Status: implemented
+
+[English](2026-09-08-file-display-through-filesystem.md) | 中文
+
+## Problem
+
+会话正文可能引用临时目录中的截图或远程文件系统提供方中的文件。Host 本地工作区白名单无法提供这些路径。没有字节上限的图片响应还可能让浏览器先下载一张 1 GiB 图片，再尝试解码。
+
+## Decision
+
+鉴权 `/api/file` 路由通过 `ctx.fs` 读取普通文件。鉴权和所组合提供方的读取策略决定访问权限；目录与 MIME 白名单不参与准入。这取代了[本地媒体展示记录](2026-09-07-session-prose-local-media-display.zh.md)中的文件服务策略；该记录保留渲染器归属及其理由。
+
+GET 调用现有 `readBytes(target, signal, maxBytes)`：提供方在内容 I/O 前拒绝已知超限文件，并在读取过程中执行上限。HEAD 使用元数据，不读取内容。`FS_TOO_LARGE` 转换为 413。MIME 查询提供响应元数据，不嗅探文件内容；未知扩展名使用 `application/octet-stream`。sandbox CSP 阻止直接打开的 HTML/SVG 以鉴权 API 源身份执行脚本。
+
+`maxImageBytes` 限制图片；`maxFileBytes` 独立限制音视频及其他文件。两个配置覆盖项均默认使用已解析的附件图片上限，通常为 20 MiB。独立覆盖项让部署可以提高非图片上限而不削弱图片准入。所有响应均包含完整文件；忽略 Range，也不声明支持 Range。
+
+## Alternatives considered
+
+**工作区和媒体白名单。** 它们限制鉴权后能读取哪些字节，却排除了常见截图位置和远程文件。所选策略允许读取所组合提供方可读的任意普通文件。
+
+**新增文件系统字节流 API。** 高效的大文件传输和音视频跳转需要每个提供方实现，包括远端 Range 处理。有界完整读取满足当前展示范围，无需扩展该接口。相关用例足以支持这项提供方工作时，可以加入流式传输与 Range。
+
+**在路由重复实现大小检查。** GET 无需额外的 stat/read 循环：`readBytes` 已经负责读取前上限、增长检测和取消。HEAD 单独检查大小，因为它不能读取正文。
+
+## Consequences
+
+临时与远程文件使用与 `read_image` 相同的文件系统提供方，不增加模型可见事件。本地沙箱提供方约束变更操作并允许读取，因此鉴权客户端的访问范围大于已注册工作区根目录。文件仍受提供方权限和路由字节上限约束。
+
+每个 GET 都会在 Host 内存中缓存完整文件。音视频使用完整响应，不支持增量传输，也不保证跳转播放。编码字节上限不限制解码后的像素尺寸。图片加载失败后展示作者提供的 alt 文本；alt 为空时展示原始目标路径。
+
+## Testing
+
+路由测试覆盖内容 I/O 前拒绝稀疏 1 GiB 文件、stat 后增长、独立字节上限、普通 MIME 类型、临时路径与符号链接、不透明远程目标、提供方失败、仅元数据 HEAD、忽略 Range 和释放。浏览器期望覆盖图片渲染、413/404 及损坏图片回退，以及工作区之外的图片。远程字节传输仍由现有文件系统提供方测试负责。
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index c0000c969f..43e8ae8ddb 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -95,7 +95,6 @@ External packages that a workspace package resolves at runtime. The tier covers
 | [`node-pty`](https://github.com/microsoft/node-pty) | MIT |
 | [`open`](https://github.com/sindresorhus/open) | MIT |
 | [`picomatch`](https://github.com/micromatch/picomatch) | MIT |
-| [`range-parser`](https://github.com/jshttp/range-parser) | MIT |
 | [`react`](https://github.com/facebook/react) | MIT |
 | [`react-dom`](https://github.com/facebook/react) | MIT |
 | [`readable-stream`](https://github.com/nodejs/readable-stream) | MIT |
@@ -158,7 +157,6 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`@types/negotiator`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/node`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/picomatch`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
-| [`@types/range-parser`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/react-dom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/readable-stream`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 54a5407c82..995a4d8fb0 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: 058f3880c33097015d4b3472a1f94af38a965b2f
-config-catalog.zh.md: 0f63a6edfeaf9bd1d08cdb6615238519a0909a66
+config-catalog.md: 200c474cc5538151eacfe1c8765d08f2beb0e4e3
+config-catalog.zh.md: 679dab21acf005e3cdffce46305b172c9c69707a
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 058f3880c3..200c474cc5 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -210,6 +210,10 @@ Requires: `agentDefaultModel` · `agents` · `attachments` · `fileUploads` · `
 export interface Config {
   /** Override platform desktop-opener detection. */
   readonly nativeOpen?: boolean
+  /** Inclusive byte limit for images served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
+  readonly maxImageBytes?: number
+  /** Inclusive byte limit for other files served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
+  readonly maxFileBytes?: number
 }
 ```
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 0f63a6edfe..679dab21ac 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -212,6 +212,10 @@ export interface Config {
 export interface Config {
   /** Override platform desktop-opener detection. */
   readonly nativeOpen?: boolean
+  /** Inclusive byte limit for images served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
+  readonly maxImageBytes?: number
+  /** Inclusive byte limit for other files served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
+  readonly maxFileBytes?: number
 }
 ```
 
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index 97a859db57..bf13fd18a2 100644
--- a/packages/api/session-controller/README.i18n.yaml
+++ b/packages/api/session-controller/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/api/session-controller/README.md
-README.md: c7ecb98b4f9a791c65b8915e57e710e4038a90de
-README.zh.md: 74f70f167454a0ac76b18cc272c0133b427ca223
+README.md: 319e9a31b32e1a7421ade6a644fb0affd2757c64
+README.zh.md: 481f7311600fd3acd88aa83b5a776f5135867326
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index c7ecb98b4f..319e9a31b3 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -36,7 +36,7 @@ The Session object also carries local submission echoes: `session.beginSubmissio
 <a id="session-media-references"></a>
 ## Session media references
 
-`SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when both `connection` and `workspaceRegistry` are composed, so conversation prose can display workspace-contained local media (images today; video/audio later) in the browser. Per request the route fail-closes: the path must be absolute, its `realpath` must lie inside a registered workspace root (path-component containment, including a filesystem-root workspace), the file must be regular, and its `mime-types` category must be image/video/audio (excluding `image/svg+xml`); media bytes are never sniffed. Regular-file checks run before opening, so named pipes and device nodes are refused instead of blocking the open; reading binds to the opened file, and a stat-identity comparison with the pre-open stat narrows (does not fully close) a concurrent replacement window. Single-range `bytes` requests stream a 206 slice parsed by `range-parser`; malformed, unknown-unit, and multi-range headers are ignored for a full 200 body; HEAD never opens a file stream; an aborted client destroys it. Responses carry `private, no-store` and `nosniff`; failures answer 400/403/404/415/416. The client-side rewrite vocabulary lives in `ui-chat` (`AssistantMarkdown`); this package owns only the serving contract.
+`SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when `connection`, `fs`, and `attachments` are composed. It reads ordinary files through `ctx.fs`, including temporary paths outside registered workspaces and files in remote providers. Neither directory containment nor MIME categories restrict access; `mime-types` supplies the response type, with `application/octet-stream` for unknown extensions. GET reuses `readBytes` for preflight and ongoing byte limits; HEAD reads metadata only. Images use `maxImageBytes`, while audio, video, and other files use `maxFileBytes`; exceeding the applicable limit returns 413. Responses contain the complete file, ignore Range, and carry `private, no-store`, `nosniff`, and a sandbox CSP so directly opened HTML/SVG cannot execute with the API origin. The Client rewrite lives in `ui-chat` (`AssistantMarkdown`); audio/video responses are available, while Markdown audio/video player nodes remain separate work.
 
 -----
 
@@ -46,6 +46,8 @@ The Session object also carries local submission echoes: `session.beginSubmissio
 | Field | Default | Meaning |
 |---|---:|---|
 | `nativeOpen` | platform-detected | Whether Session workspace paths can be handed to a native desktop opener |
+| `maxImageBytes` | attachment image limit (normally 20 MiB) | Inclusive byte cap for image responses; positive safe integer |
+| `maxFileBytes` | attachment image limit (normally 20 MiB) | Independent inclusive byte cap for audio, video, and other complete-file responses; positive safe integer |
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-session-controller) is the exhaustive source for accepted fields and their JSDoc.
 
@@ -64,6 +66,8 @@ No direct effect; model requests remain owned by the Agent and LLM packages.
 
 <a id="known-limitations-and-deferred-work"></a>
 
+- Media reads use Host files under registered workspace roots. Temporary files outside those roots return 403; files available only in a remote filesystem provider cannot be served. The route does not use `ctx.fs`; its read permissions differ from `read_image`.
+- The image byte cap does not validate decoded dimensions or pixel count.
 - Control baselines represent process-local state and therefore cannot reconstruct jobs after a Host restart.
 - A failed follow resumption remains visible to the caller instead of retrying indefinitely.
 - The raw browser upload is one streaming HTTP request without resumable offsets; a retry sends the file again from byte zero.
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index 74f70f1674..481f731160 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -36,7 +36,7 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 <a id="session-media-references"></a>
 ## 会话媒体引用
 
-当 `connection` 与 `workspaceRegistry` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`，使会话正文可以引用 workspace 内的本地媒体（图片今天可用；视频/音频后续同一条 URL）。每次请求 fail-closed：路径必须绝对、其 `realpath` 必须落在已注册 workspace 根内（按路径组件判定包含，含文件系统根目录作为 workspace）、文件必须是常规文件、其 `mime-types` 类别必须属于 image/video/audio（排除 `image/svg+xml`）；该路由从不嗅探媒体字节。常规文件检查在打开前执行，命名管道与设备节点会被拒绝而不是阻塞打开；读取绑定已打开文件，并与打开前的 stat 做身份比较，收窄（而非完全消除）并发替换窗口。单段 `bytes` Range 请求由 `range-parser` 解析后流式返回 206 分片；畸形、未知单位与多段 Range 头被忽略并返回完整 200；HEAD 从不打开文件流；客户端中止即销毁流。响应携带 `private, no-store` 与 `nosniff`；失败返回 400/403/404/415/416。客户端侧的重写词表位于 `ui-chat`（`AssistantMarkdown`）；本包只拥有服务契约。
+当 `connection`、`fs` 与 `attachments` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`。它通过 `ctx.fs` 读取普通文件，包括已注册工作区之外的临时路径与远程提供方中的文件。目录包含关系与 MIME 类别均不限制访问；`mime-types` 提供响应类型，未知扩展名使用 `application/octet-stream`。GET 复用 `readBytes` 执行读取前及读取中的字节限制；HEAD 只读取元数据。图片使用 `maxImageBytes`，音视频及其他文件使用 `maxFileBytes`；超过对应上限返回 413。响应包含完整文件，忽略 Range，并携带 `private, no-store`、`nosniff` 与 sandbox CSP，使直接打开的 HTML/SVG 无法以 API 源身份执行脚本。客户端重写位于 `ui-chat`（`AssistantMarkdown`）；音视频文件响应已可用，Markdown 音视频播放器节点仍是独立工作。
 
 -----
 
@@ -46,6 +46,8 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 | 字段 | 默认值 | 含义 |
 |---|---:|---|
 | `nativeOpen` | 平台探测 | 是否能把 Session 工作区路径交给原生桌面打开器 |
+| `maxImageBytes` | 附件图片上限（通常 20 MiB） | 图片响应的字节上限（含等值）；正安全整数 |
+| `maxFileBytes` | 附件图片上限（通常 20 MiB） | 音视频及其他完整文件响应的独立字节上限（含等值）；正安全整数 |
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-session-controller)是所有受支持字段及其 JSDoc 的完整来源。
 
@@ -64,6 +66,8 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 
 <a id="known-limitations-and-deferred-work"></a>
 
+- 媒体读取使用已注册 workspace 根内的 Host 文件。根外临时文件返回 403；仅存在于远程文件系统提供方中的文件无法提供。该路由不使用 `ctx.fs`，其读取权限与 `read_image` 不同。
+- 图片字节上限不校验解码后的尺寸或像素数。
 - Control baseline 表示进程本地状态，因此 Host 重启后无法重建 jobs。
 - follow 恢复失败会对调用方可见，而不会无限重试。
 - 浏览器原始字节上传使用一次不带断点续传偏移的流式 HTTP 请求；重试会从第一个字节重新传输整个文件。
diff --git a/packages/api/session-controller/package.json b/packages/api/session-controller/package.json
index 2b3d08e98a..d62e56243f 100644
--- a/packages/api/session-controller/package.json
+++ b/packages/api/session-controller/package.json
@@ -72,7 +72,6 @@
     "@deepseek-ai/dsh-deque": "workspace:^",
     "@deepseek-ai/schemastery": "workspace:^",
     "mime-types": "^3.0.2",
-    "range-parser": "^1.3.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -86,6 +85,7 @@
     "@deepseek-ai/dsh-client-file-upload": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-file-reference": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
     "@deepseek-ai/dsh-jobs": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-native-command": "workspace:^",
@@ -127,6 +127,8 @@
     "@deepseek-ai/dsh-client-store": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-file-reference": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-jobs": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-native-command": "workspace:^",
@@ -149,7 +151,6 @@
     "@deepseek-ai/dsh-util-time": "workspace:^",
     "@deepseek-ai/dsh-util-workspace-path": "workspace:^",
     "@deepseek-ai/dsh-workspace": "workspace:^",
-    "@types/mime-types": "^3.0.1",
-    "@types/range-parser": "^1.2.7"
+    "@types/mime-types": "^3.0.1"
   }
 }
diff --git a/packages/api/session-controller/src/index.ts b/packages/api/session-controller/src/index.ts
index 9cc93be179..0e24b15f10 100644
--- a/packages/api/session-controller/src/index.ts
+++ b/packages/api/session-controller/src/index.ts
@@ -70,6 +70,10 @@ declare module '@deepseek-ai/cordis' {
 export interface Config {
   /** Override platform desktop-opener detection. */
   readonly nativeOpen?: boolean
+  /** Inclusive byte limit for images served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
+  readonly maxImageBytes?: number
+  /** Inclusive byte limit for other files served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
+  readonly maxFileBytes?: number
 }
 
 /** Host integrations replaceable by direct unit tests. */
@@ -97,6 +101,8 @@ export class SessionController extends TypertRemoteService {
 
   static Config: z<Config> = z.object({
     nativeOpen: z.boolean(),
+    maxImageBytes: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER),
+    maxFileBytes: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER),
   })
 
   private readonly agents: ApiSessionAgentController
@@ -110,7 +116,7 @@ export class SessionController extends TypertRemoteService {
 
   /**
    * @param ctx - Host context containing the Session capability assembly.
-   * @param config - native-opener deployment policy.
+   * @param config - native-opener and media-read deployment policy.
    * @param internals - host integrations replaceable by direct unit tests.
    */
   constructor(ctx: Context, config: Config, internals: SessionControllerInternals = {}) {
@@ -135,7 +141,7 @@ export class SessionController extends TypertRemoteService {
     this.canOpenPath = internals.canOpenPath
       ?? (() => config.nativeOpen ?? (internals.openPath !== undefined || canOpenNativePath()))
     ctx.plugin(SessionFileReferences)
-    ctx.plugin(SessionMediaReferences)
+    ctx.plugin(SessionMediaReferences, config)
     ctx.plugin(SessionSkillCatalog)
 
     ctx.on('session/created', (session) => {
diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
index 136559a51a..bacc0a8b71 100644
--- a/packages/api/session-controller/src/media-references.ts
+++ b/packages/api/session-controller/src/media-references.ts
@@ -1,177 +1,79 @@
 /**
- * GET/HEAD /api/file — same-origin media bytes for a local path authored in
- * conversation prose. Browsers cannot read Host files, so local media
- * destinations (images today; video/audio the same way) are rewritten to this
- * one route; the route re-validates every request because the rewrite itself
- * proves nothing.
- *
- * Policy (enforced per request, fail-closed):
- * - the requested path must be one absolute filesystem path;
- * - its canonical location must lie inside a registered workspace root
- *   (`ctx.workspaceRegistry`); no other directory is readable;
- * - its MIME type (resolved by `mime-types`) must belong to the served
- *   categories image/video/audio, excluding `image/svg+xml`; media bytes are
- *   never sniffed here, and a corrupt payload fails in the browser;
- * - the file must exist and be a regular file (checked before opening, so a
- *   named pipe or device node is refused instead of blocking the open);
- *   reading binds to the opened file, and comparing its stat identity with
- *   the pre-open stat narrows (does not fully close) a concurrent
- *   replacement window;
- * - multi-range requests are answered with the full 200 body (no Range is
- *   honored) rather than a mislabeled single-segment 206;
- * - responses are private, uncached, sniff-proof, and stream with HTTP range
- *   support (parsed by `range-parser`) so `<video>`/`<audio>` can seek; the
- *   file stream is destroyed when the client aborts, and HEAD never opens
- *   one.
- *
- * The route is deliberately presentational: it never writes and follows no
- * redirects, returning 400/403/404/415/416 instead of falling back to any
- * other file-serving behavior.
- *
- * Only the plugin contribution below is exported: package-internal policy
- * helpers stay module-private and are exercised through the registered route.
+ * Authenticated GET/HEAD /api/file reads bounded file responses through
+ * the composed filesystem provider. Paths and MIME types do not restrict access;
+ * the connection service authenticates requests before this handler.
  * @module @deepseek-ai/dsh-api-session-controller/media-references
  */
 
-import { open, realpath, stat } from 'node:fs/promises'
-import { isAbsolute, sep } from 'node:path'
-import { Readable, addAbortSignal } from 'node:stream'
+import { isAbsolute } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
-// Cordis `ctx.connection` typing and the fetch-route contract.
 import type {} from '@deepseek-ai/dsh-client-connection'
-// Cordis `ctx.workspaceRegistry` typing.
-import type {} from '@deepseek-ai/dsh-workspace'
+import type {} from '@deepseek-ai/dsh-attachment'
+import { FsError, type FileSystem } from '@deepseek-ai/dsh-fs'
 import mime from 'mime-types'
-import rangeParser from 'range-parser'
 
-/** MIME categories this route serves; `image/svg+xml` is refused separately because SVG can carry script. */
-const SERVED_MEDIA_TYPE = /^(?:image|video|audio)\//
-/** Headers every response carries: private, uncached, sniff-proof. */
-const BASE_HEADERS = { 'Cache-Control': 'private, no-store', 'X-Content-Type-Options': 'nosniff' }
+const BASE_HEADERS = {
+  'Cache-Control': 'private, no-store',
+  'X-Content-Type-Options': 'nosniff',
+  // HTML and SVG files may be opened directly on the authenticated API origin.
+  'Content-Security-Policy': "sandbox; default-src 'none'",
+}
 
-/**
- * Serve one workspace-contained media file over the shared API channel.
- * @param request - Authenticated fetch-route request (GET or HEAD).
- * @param roots - Registered workspace root directories.
- * @returns A streaming media response or a fail-closed status.
- */
-async function serveMediaReference(
-  request: Request,
-  roots: readonly { path: string }[],
-): Promise<Response> {
-  // Error responses carry a text body for GET debugging; HEAD responses must
-  // never carry one.
+async function serveFile(request: Request, fs: FileSystem, limits: { image: number; file: number }): Promise<Response> {
   const fail = (status: number, text: string): Response =>
-    new Response(request.method === 'HEAD' ? null : text, { status })
+    new Response(request.method === 'HEAD' ? null : text, { status, headers: BASE_HEADERS })
   const path = new URL(request.url).searchParams.get('path')
   if (path === null || path.length === 0) return fail(400, 'missing path')
-  if (path.includes('\0') || !isAbsolute(path)) {
-    return fail(400, 'absolute path required')
-  }
-  let canonical: string
+  if (path.includes('\0') || !isAbsolute(path)) return fail(400, 'absolute path required')
   try {
-    canonical = await realpath(path)
-  } catch {
-    return fail(404, 'not found')
-  }
-  // Containment compares path components; a filesystem root already ends in
-  // the separator and prefixes every absolute path.
-  const contained = roots.some(({ path: root }) =>
-    canonical === root || canonical.startsWith(root.endsWith(sep) ? root : root + sep))
-  if (!contained) return fail(403, 'outside workspace roots')
-  const mediaType = mime.lookup(canonical)
-  if (mediaType === false || mediaType === 'image/svg+xml' || !SERVED_MEDIA_TYPE.test(mediaType)) {
-    return fail(415, 'not an allowlisted media type')
-  }
-  // Open only after proving the validated path is a regular file: opening a
-  // FIFO or device node first would block or read unbounded data.
-  let before
-  try {
-    before = await stat(canonical)
-  } catch {
-    /* v8 ignore next 1 -- the path cannot vanish between the realpath above and this stat except in a concurrent deletion race */
-    return fail(404, 'not found')
-  }
-  if (!before.isFile()) return fail(403, 'not a regular file')
-  let handle
-  try {
-    handle = await open(canonical, 'r')
-  } catch {
-    return fail(404, 'not found')
-  }
-  let streamed = false
-  try {
-    const after = await handle.stat()
-    /* v8 ignore next 1 -- only a concurrent replacement could make the opened file non-regular after the pre-open check */
-    if (!after.isFile()) return fail(403, 'not a regular file')
-    // The opened handle's identity must match the validated stat; this only
-    // narrows a replacement race between the stat and the open, it does not
-    // eliminate the earlier realpath-to-stat window.
-    /* v8 ignore next 2 -- the replacement race cannot be produced deterministically; this arm refuses it when it happens */
-    if (after.dev !== before.dev || after.ino !== before.ino) {
-      return fail(403, 'file changed during validation')
-    }
-    const total = after.size
-    const rangeHeader = request.headers.get('range')?.trim() ?? null
-    // range-parser never validates the range unit, so only a `bytes` header is
-    // parsed here; malformed, unknown-unit, and multi-range headers are ignored
-    // per RFC 9110 and get the full 200 body below.
-    const ranges = rangeHeader !== null && rangeHeader.toLowerCase().startsWith('bytes=')
-      ? rangeParser(total, rangeHeader)
-      : undefined
-    if (ranges === -1) {
-      // Only an unsatisfiable range answers 416 with the total size. Malformed
-      // (-2) and unknown-unit or multi-range headers are ignored per RFC 9110
-      // and get the full 200 body below.
-      const headers = { ...BASE_HEADERS, 'Content-Range': `bytes */${total}` }
-      return new Response(null, { status: 416, headers })
-    }
-    // Only a single range is honored; a multi-range header gets the full body.
-    const slice = Array.isArray(ranges) && ranges.length === 1 ? ranges[0] : undefined
-    const { start, end } = slice ?? { start: 0, end: total - 1 }
+    const target = await fs.resolve(path, { signal: request.signal })
+    const mediaType = mime.lookup(target.displayPath) || 'application/octet-stream'
+    const maxBytes = mediaType.startsWith('image/') ? limits.image : limits.file
     const headers: Record<string, string> = {
       ...BASE_HEADERS,
       'Content-Type': mediaType,
-      'Content-Length': String(end - start + 1),
-      'Accept-Ranges': 'bytes',
     }
-    if (slice !== undefined) headers['Content-Range'] = `bytes ${start}-${end}/${total}`
-    const status = slice === undefined ? 200 : 206
-    // HEAD never opens a stream; an already-aborted client cannot receive a
-    // body either, and the handle closes through the finally below.
-    if (request.method === 'HEAD' || request.signal.aborted) {
-      return new Response(null, { status, headers })
+    if (request.method === 'HEAD') {
+      const info = await fs.stat(target, request.signal)
+      if (info === undefined) return fail(404, 'not found')
+      if (info.type !== 'file') return fail(403, 'not a regular file')
+      if (info.size !== undefined) {
+        if (info.size > maxBytes) return fail(413, 'file exceeds byte limit')
+        headers['Content-Length'] = String(info.size)
+      }
+      return new Response(null, { headers })
     }
-    streamed = true
-    // Bound the full-body stream to the stat'ed size so concurrent appends
-    // cannot push the payload past the declared Content-Length.
-    const stream = handle.createReadStream(slice ?? { start: 0, end: total - 1 })
-    const source = addAbortSignal(request.signal, stream)
-    return new Response(Readable.toWeb(source) as ReadableStream<Uint8Array>, { status, headers })
-  } finally {
-    if (!streamed) await handle.close()
+    const bytes = await fs.readBytes(target, request.signal, maxBytes)
+    headers['Content-Length'] = String(bytes.byteLength)
+    return new Response(bytes.slice(), { headers })
+  } catch (error: unknown) {
+    if (!(error instanceof FsError)) throw error
+    const statuses: Partial<Record<FsError['code'], number>> = {
+      FS_NOT_FOUND: 404,
+      FS_NOT_REGULAR_FILE: 403,
+      FS_PERMISSION_DENIED: 403,
+      FS_SANDBOX_DENIED: 403,
+      FS_TOO_LARGE: 413,
+      FS_ABORTED: 499,
+    }
+    return fail(statuses[error.code] ?? 500, error.code)
   }
 }
 
 /**
- * `/api/file` fetch-route contribution, the media counterpart of
- * `SessionFileReferences`: that contribution lets the GUI discover the files
- * a Session references, this one lets it display referenced local media
- * paths as same-origin bytes. Declared injects gate activation: a host
- * composition without a connection service (or a workspace registry) never
- * activates this plugin, so the route simply does not exist there — the same
- * pending-until-composed posture the package's other optional contributions
- * use. The channel's trust fence and browser authentication apply before any
- * request reaches the handler.
+ * File-display contribution. The connection service supplies authentication;
+ * `ctx.fs` supplies the execution world's paths, reads, and access policy.
  */
 export const SessionMediaReferences = {
-  inject: ['connection', 'workspaceRegistry'],
-  apply(ctx: Context): void {
+  inject: ['connection', 'fs', 'attachments'],
+  apply(ctx: Context, config: { maxImageBytes?: number; maxFileBytes?: number }): void {
+    const defaults = ctx.attachments.imageLimits.maxImageBytes
+    const limits = { image: config.maxImageBytes ?? defaults, file: config.maxFileBytes ?? defaults }
     ctx.effect(() => ctx.connection.fetch.register({
       path: '/api/file',
       methods: ['GET', 'HEAD'],
       requestBody: 'buffered',
-      fetch: request => serveMediaReference(request, ctx.workspaceRegistry.list()),
+      fetch: request => serveFile(request, ctx.fs, limits),
     }), 'session-controller: /api/file')
   },
 }
diff --git a/packages/api/session-controller/tests/media-references.host.spec.ts b/packages/api/session-controller/tests/media-references.host.spec.ts
index da4a22d42d..187b802efe 100644
--- a/packages/api/session-controller/tests/media-references.host.spec.ts
+++ b/packages/api/session-controller/tests/media-references.host.spec.ts
@@ -1,34 +1,25 @@
-import { mkdir, mkdtemp, open, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { appendFile, mkdir, mkdtemp, open, realpath, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join, sep } from 'node:path'
+import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
+import { FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
 import { SessionMediaReferences } from '../src/media-references.ts'
+import { SessionController } from '../src/index.ts'
 
-const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3, 4, 5, 6, 7, 8])
-const TEXT_BYTES = new Uint8Array([1, 2, 3, 4])
-const MP4_BYTES = new TextEncoder().encode('....ftypmp42....moov....')
+const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3, 4])
+const DEFAULT_LIMIT = 20 * 1024 * 1024
 
 async function responseBytes(response: Response): Promise<Uint8Array> {
   return new Uint8Array(await response.arrayBuffer())
 }
 
-/** One mounted plugin contribution with its registered `/api/file` handler. */
-interface MountedRoute {
-  /** GET/HEAD helper for one local path. */
-  call(path: string, init?: RequestInit): Promise<Response>
-  /** Direct request access (custom URLs and headers). */
-  raw(url: string, init?: RequestInit): Promise<Response>
-  unregister: ReturnType<typeof vi.fn>
-  dispose(): Promise<void>
-}
-
 describe('SessionMediaReferences /api/file', () => {
   let root: string
   const contexts: Context[] = []
 
   beforeEach(async () => {
-    // Real workspace roots are canonical; tmpdir may sit behind a symlink.
     root = await realpath(await mkdtemp(join(tmpdir(), 'dsh-media-references-')))
   })
 
@@ -37,7 +28,7 @@ describe('SessionMediaReferences /api/file', () => {
     await rm(root, { recursive: true, force: true })
   })
 
-  async function mount(workspaceRoot: string = root): Promise<MountedRoute> {
+  async function mount(config: { maxImageBytes?: number; maxFileBytes?: number } = {}, defaultLimit = DEFAULT_LIMIT) {
     const ctx = new Context()
     contexts.push(ctx)
     let handler: ((request: Request) => Promise<Response>) | undefined
@@ -50,336 +41,199 @@ describe('SessionMediaReferences /api/file', () => {
         },
       },
     } as never)
-    ctx.provide('workspaceRegistry', {
-      list: () => [{ path: workspaceRoot }],
-    } as never)
-    await ctx.plugin(SessionMediaReferences).await()
-    const fetchFile = (request: Request) => {
+    ctx.provide('attachments', { imageLimits: { maxImageBytes: defaultLimit } } as never)
+    await ctx.plugin(LocalFileSystem, { cwd: root }).await()
+    await ctx.plugin(SessionMediaReferences, config).await()
+    const raw = (url: string, init?: RequestInit) => {
       if (handler === undefined) throw new Error('route not registered')
-      return handler(request)
+      return handler(new Request(url, init))
     }
     return {
-      call: (path, init) => {
-        const url = `http://127.0.0.1:3080/api/file?path=${encodeURIComponent(path)}`
-        return fetchFile(new Request(url, init))
-      },
-      raw: (url, init) => fetchFile(new Request(url, init)),
+      call: (path: string, init?: RequestInit) => raw(`http://127.0.0.1/api/file?path=${encodeURIComponent(path)}`, init),
+      raw,
+      fs: ctx.fs as LocalFileSystem,
       unregister,
-      dispose: () => ctx.fiber.dispose().then(() => {
-        const index = contexts.indexOf(ctx)
-        if (index >= 0) contexts.splice(index, 1)
-      }),
+      dispose: () => ctx.fiber.dispose(),
     }
   }
 
-  it('serves images from the workspace root and nested directories', async () => {
+  it('inherits attachment limits unless configured and rejects invalid overrides', async () => {
+    expect(SessionController.Config({}).maxImageBytes).toBeUndefined()
+    expect(SessionController.Config({}).maxFileBytes).toBeUndefined()
+    for (const field of ['maxImageBytes', 'maxFileBytes']) {
+      expect(SessionController.Config({ [field]: 1 })).toMatchObject({ [field]: 1 })
+      for (const value of [0, -1, 1.5, Infinity, NaN, Number.MAX_SAFE_INTEGER + 1]) {
+        expect(() => SessionController.Config({ [field]: value })).toThrow()
+      }
+    }
+    const route = await mount({}, PNG_BYTES.length - 1)
+    const path = join(root, 'image.png')
+    await writeFile(path, PNG_BYTES)
+    expect((await route.call(path)).status).toBe(413)
+  })
+
+  it('serves the inclusive image cap and refuses larger images for GET, HEAD and Range', async () => {
+    const route = await mount({ maxImageBytes: PNG_BYTES.length })
+    const path = join(root, 'bounded.png')
+    await writeFile(path, PNG_BYTES)
+    expect(await responseBytes(await route.call(path))).toEqual(PNG_BYTES)
+    await appendFile(path, new Uint8Array(1))
+    expect((await route.call(path)).status).toBe(413)
+    expect((await route.call(path, { headers: { range: 'bytes=0-0' } })).status).toBe(413)
+    const head = await route.call(path, { method: 'HEAD' })
+    expect(head.status).toBe(413)
+    expect(head.body).toBeNull()
+  })
+
+  it('rejects a sparse 1 GiB image before content I/O', async () => {
     const route = await mount()
-    const direct = join(root, 'graph.png')
-    await writeFile(direct, PNG_BYTES)
-    const response = await route.call(direct)
+    const inspect = vi.fn()
+    route.fs.internals.inspectReadBytesAfterStat = inspect
+    const path = join(root, 'huge.png')
+    const handle = await open(path, 'w')
+    try {
+      await handle.truncate(1024 * 1024 * 1024)
+    } finally {
+      await handle.close()
+    }
+    expect((await route.call(path)).status).toBe(413)
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('uses the filesystem byte reader to reject post-stat image growth', async () => {
+    const route = await mount({ maxImageBytes: PNG_BYTES.length })
+    const path = join(root, 'growing.png')
+    await writeFile(path, PNG_BYTES)
+    route.fs.internals.inspectReadBytesAfterStat = async () => {
+      await appendFile(path, new Uint8Array(1))
+    }
+    expect((await route.call(path)).status).toBe(413)
+  })
+
+  it.each([
+    ['png', 'image/png'], ['svg', 'image/svg+xml'], ['mp4', 'video/mp4'], ['mp3', 'audio/mpeg'],
+    ['txt', 'text/plain'], ['html', 'text/html'], ['bin', 'application/octet-stream'], ['', 'application/octet-stream'],
+  ])('serves .%s files with their MIME type and response protections', async (extension, mediaType) => {
+    const route = await mount()
+    const path = join(root, `file${extension === '' ? '' : `.${extension}`}`)
+    await writeFile(path, PNG_BYTES)
+    const response = await route.call(path)
     expect(response.status).toBe(200)
-    expect(response.headers.get('content-type')).toBe('image/png')
+    expect(response.headers.get('content-type')).toBe(mediaType)
     expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
-    expect(response.headers.get('accept-ranges')).toBe('bytes')
     expect(response.headers.get('cache-control')).toBe('private, no-store')
     expect(response.headers.get('x-content-type-options')).toBe('nosniff')
+    expect(response.headers.get('content-security-policy')).toBe("sandbox; default-src 'none'")
     expect(await responseBytes(response)).toEqual(PNG_BYTES)
-
-    const nestedDir = join(root, 'shots', 'deep')
-    await mkdir(nestedDir, { recursive: true })
-    const nested = join(nestedDir, 'x.png')
-    await writeFile(nested, PNG_BYTES)
-    expect((await route.call(nested)).status).toBe(200)
   })
 
-  it('serves every allowlisted media category by extension', async () => {
-    const route = await mount()
-    const video = join(root, 'clip.mp4')
-    await writeFile(video, MP4_BYTES)
-    const videoResponse = await route.call(video)
-    expect(videoResponse.status).toBe(200)
-    expect(videoResponse.headers.get('content-type')).toBe('video/mp4')
-
-    const audio = join(root, 'song.mp3')
-    await writeFile(audio, TEXT_BYTES)
-    const audioResponse = await route.call(audio)
-    expect(audioResponse.status).toBe(200)
-    expect(audioResponse.headers.get('content-type')).toBe('audio/mpeg')
-  })
-
-  it('serves allowlisted image extensions regardless of payload bytes', async () => {
-    // Media bytes are never sniffed on this route: a corrupt payload fails
-    // in the browser, not here.
-    const route = await mount()
-    const fake = join(root, 'fake.png')
-    await writeFile(fake, TEXT_BYTES)
-    const response = await route.call(fake)
-    expect(response.status).toBe(200)
-    expect(response.headers.get('content-type')).toBe('image/png')
-  })
-
-  it('refuses non-media, unknown, and denied content types', async () => {
-    const route = await mount()
-    const cases: ReadonlyArray<[string, Uint8Array]> = [
-      ['note.txt', TEXT_BYTES],
-      ['run.exe', TEXT_BYTES],
-      ['logo.svg', TEXT_BYTES],
-      ['data.bin', TEXT_BYTES],
-      ['README', TEXT_BYTES],
-    ]
-    for (const [name, bytes] of cases) {
-      const path = join(root, name)
-      await writeFile(path, bytes)
-      const response = await route.call(path)
-      expect(response.status, name).toBe(415)
-      expect(await response.text()).toBe('not an allowlisted media type')
-    }
-  })
-
-  it('answers bounded, open-ended, suffix, and clamped range requests', async () => {
-    const route = await mount()
-    const path = join(root, 'graph.png')
+  it.each(['mp4', 'mp3', 'bin'])('allows a separate byte cap for .%s files', async (extension) => {
+    const route = await mount({ maxImageBytes: 1, maxFileBytes: PNG_BYTES.length })
+    const path = join(root, `file.${extension}`)
     await writeFile(path, PNG_BYTES)
-    const total = PNG_BYTES.length
-
-    const bounded = await route.call(path, { headers: { range: 'bytes=0-3' } })
-    expect(bounded.status).toBe(206)
-    expect(bounded.headers.get('content-range')).toBe(`bytes 0-3/${total}`)
-    expect(bounded.headers.get('content-length')).toBe('4')
-    expect(await responseBytes(bounded)).toEqual(PNG_BYTES.slice(0, 4))
-
-    const suffix = await route.call(path, { headers: { range: 'bytes=-4' } })
-    expect(suffix.status).toBe(206)
-    expect(await responseBytes(suffix)).toEqual(PNG_BYTES.slice(-4))
-
-    const openEnded = await route.call(path, { headers: { range: 'bytes=4-' } })
-    expect(openEnded.status).toBe(206)
-    expect(await responseBytes(openEnded)).toEqual(PNG_BYTES.slice(4))
-
-    const clamped = await route.call(path, { headers: { range: 'bytes=6-999' } })
-    expect(clamped.status).toBe(206)
-    expect(clamped.headers.get('content-range')).toBe(`bytes 6-${total - 1}/${total}`)
-    expect(await responseBytes(clamped)).toEqual(PNG_BYTES.slice(6))
+    expect(await responseBytes(await route.call(path))).toEqual(PNG_BYTES)
+    await appendFile(path, new Uint8Array(1))
+    expect((await route.call(path)).status).toBe(413)
+    expect((await route.call(path, { method: 'HEAD' })).status).toBe(413)
   })
 
-  it('answers unsatisfiable ranges with 416 and the total size', async () => {
+  it('ignores Range headers and returns complete bodies without advertising ranges', async () => {
     const route = await mount()
-    const path = join(root, 'graph.png')
+    const path = join(root, 'clip.mp4')
     await writeFile(path, PNG_BYTES)
-    const response = await route.call(path, { headers: { range: 'bytes=999-' } })
-    expect(response.status).toBe(416)
-    expect(response.headers.get('content-range')).toBe(`bytes */${PNG_BYTES.length}`)
-  })
-
-  it('ignores malformed and unknown-unit ranges for a full 200 body', async () => {
-    const route = await mount()
-    const path = join(root, 'graph.png')
-    await writeFile(path, PNG_BYTES)
-    for (const range of ['bytes=abc', 'items=0-0']) {
+    for (const range of ['bytes=0-3', 'bytes=-4', 'bytes=999-', 'bytes=abc', 'items=0-0', 'bytes=0-1,3-4']) {
       const response = await route.call(path, { headers: { range } })
-      expect(response.status, range).toBe(200)
-      expect(response.headers.get('content-range')).toBeNull()
-      expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
-      expect(await responseBytes(response), range).toEqual(PNG_BYTES)
-    }
-  })
-
-  it('ignores multi-range headers and serves the full 200 body', async () => {
-    const route = await mount()
-    const path = join(root, 'graph.png')
-    await writeFile(path, PNG_BYTES)
-    const response = await route.call(path, { headers: { range: 'bytes=0-1,3-4' } })
-    expect(response.status).toBe(200)
-    expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
-    expect(response.headers.get('content-range')).toBeNull()
-    expect(await responseBytes(response)).toEqual(PNG_BYTES)
-  })
-
-  it('answers HEAD without a body', async () => {
-    const route = await mount()
-    const path = join(root, 'graph.png')
-    await writeFile(path, PNG_BYTES)
-    const response = await route.call(path, { method: 'HEAD' })
-    expect(response.status).toBe(200)
-    expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
-    expect(response.headers.get('content-range')).toBeNull()
-    expect(response.body).toBeNull()
-
-    const ranged = await route.call(path, { method: 'HEAD', headers: { range: 'bytes=0-3' } })
-    expect(ranged.status).toBe(206)
-    expect(ranged.headers.get('content-range')).toBe(`bytes 0-3/${PNG_BYTES.length}`)
-    expect(ranged.headers.get('content-length')).toBe('4')
-    expect(ranged.body).toBeNull()
-  })
-
-  it('answers HEAD errors without a body', async () => {
-    const route = await mount()
-    const response = await route.raw('http://127.0.0.1:3080/api/file', { method: 'HEAD' })
-    expect(response.status).toBe(400)
-    expect(response.body).toBeNull()
-  })
-
-  it('denies malformed, missing, empty, and uncontained requests', async () => {
-    const route = await mount()
-    expect((await route.raw('http://127.0.0.1:3080/api/file')).status).toBe(400)
-    expect((await route.raw('http://127.0.0.1:3080/api/file?path=')).status).toBe(400)
-    expect((await route.raw(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent('x.png')}`)).status)
-      .toBe(400)
-    expect((await route.raw(`http://127.0.0.1:3080/api/file?path=${encodeURIComponent('/a\0b.png')}`)).status)
-      .toBe(400)
-    expect((await route.call(join(root, 'missing.png'))).status).toBe(404)
-
-    const outside = await realpath(await mkdtemp(join(tmpdir(), 'dsh-media-references-out-')))
-    const path = join(outside, 'x.png')
-    await writeFile(path, PNG_BYTES)
-    try {
-      const denied = await route.call(path)
-      expect(denied.status).toBe(403)
-      expect(await denied.text()).toBe('outside workspace roots')
-    } finally {
-      await rm(outside, { recursive: true, force: true })
-    }
-  })
-
-  // A FIFO would block a plain open; the pre-open regular-file check refuses
-  // it first. POSIX-only because Windows has no named-pipe path construction
-  // here.
-  it.skipIf(process.platform === 'win32')(
-    'refuses a FIFO named as media without blocking on the open',
-    async () => {
-      const route = await mount()
-      const pipe = join(root, 'stream.png')
-      const { execFile } = await import('node:child_process')
-      const { promisify } = await import('node:util')
-      await promisify(execFile)('mkfifo', [pipe])
-      const response = await route.call(pipe)
-      expect(response.status).toBe(403)
-      expect(await response.text()).toBe('not a regular file')
-    },
-  )
-
-  it('answers 404 when an existing file cannot be opened for reading', async () => {
-    // A permission-less file passes realpath/stat but fails the open; the
-    // route treats the unreadable file like a missing one. chmod has no
-    // effect on Windows, where this case is skipped.
-    if (process.platform === 'win32') return
-    const route = await mount()
-    const path = join(root, 'locked.png')
-    await writeFile(path, PNG_BYTES)
-    const { chmod } = await import('node:fs/promises')
-    await chmod(path, 0o000)
-    try {
-      const response = await route.call(path)
-      expect(response.status).toBe(404)
-    } finally {
-      await chmod(path, 0o600)
-    }
-  })
-
-  it('refuses a directory even when its name carries a media extension', async () => {
-    const route = await mount()
-    const directory = join(root, 'frames.png')
-    await mkdir(directory)
-    const response = await route.call(directory)
-    expect(response.status).toBe(403)
-    expect(await response.text()).toBe('not a regular file')
-  })
-
-  // A POSIX filesystem root is the separator itself; the Windows drive-root
-  // spelling cannot be produced portably, so the case stays POSIX-only. The
-  // containment code treats any separator-terminated root the same way.
-  it.skipIf(process.platform === 'win32')(
-    'serves files when the registered workspace is the filesystem root',
-    async () => {
-      const route = await mount(sep)
-      const path = join(root, 'graph.png')
-      await writeFile(path, PNG_BYTES)
-      const response = await route.call(path)
       expect(response.status).toBe(200)
+      expect(response.headers.get('accept-ranges')).toBeNull()
+      expect(response.headers.get('content-range')).toBeNull()
       expect(await responseBytes(response)).toEqual(PNG_BYTES)
-    },
-  )
+    }
+  })
 
-  it('follows symlinks for the containment check', async () => {
+  it('answers HEAD without reading content and reports missing and non-regular files', async () => {
     const route = await mount()
-    const real = join(root, 'real.png')
-    await writeFile(real, PNG_BYTES)
-    const link = join(root, 'link.png')
-    await symlink(real, link)
-    expect((await route.call(link)).status).toBe(200)
+    const path = join(root, 'image.png')
+    await writeFile(path, PNG_BYTES)
+    const read = vi.spyOn(route.fs, 'readBytes')
+    const response = await route.call(path, { method: 'HEAD', headers: { range: 'bytes=0-3' } })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-length')).toBe(String(PNG_BYTES.length))
+    expect(response.body).toBeNull()
+    expect(read).not.toHaveBeenCalled()
+    expect((await route.call(join(root, 'missing'), { method: 'HEAD' })).status).toBe(404)
+    expect((await route.call(root, { method: 'HEAD' })).status).toBe(403)
+    vi.spyOn(route.fs, 'stat').mockResolvedValue({ type: 'file', version: FsVersion('v1') })
+    expect((await route.call(path, { method: 'HEAD' })).headers.get('content-length')).toBeNull()
+  })
 
-    // The escaping target lives in a private directory so concurrent test
-    // processes can never share or delete it.
-    const outside = await realpath(await mkdtemp(join(tmpdir(), 'dsh-media-references-target-')))
-    const outsideTarget = join(outside, 'secret.png')
-    await writeFile(outsideTarget, PNG_BYTES)
+  it('rejects malformed paths, absent files, and directories', async () => {
+    const route = await mount()
+    expect((await route.raw('http://127.0.0.1/api/file')).status).toBe(400)
+    for (const path of ['', 'relative.png', '/a\0b.png']) {
+      expect((await route.call(path)).status).toBe(400)
+    }
+    const head = await route.call('', { method: 'HEAD' })
+    expect(head.status).toBe(400)
+    expect(head.body).toBeNull()
+    expect((await route.call(join(root, 'missing.png'))).status).toBe(404)
+    await mkdir(join(root, 'frames.png'))
+    expect((await route.call(join(root, 'frames.png'))).status).toBe(403)
+  })
+
+  it('reads files and symlink targets outside the default cwd without a workspace registry', async () => {
+    const route = await mount()
+    const outside = await mkdtemp(join(tmpdir(), 'dsh-media-outside-'))
     try {
-      const escaping = join(root, 'escape.png')
-      await symlink(outsideTarget, escaping)
-      const denied = await route.call(escaping)
-      expect(denied.status).toBe(403)
-      expect(await denied.text()).toBe('outside workspace roots')
+      const path = join(outside, 'image.png')
+      await writeFile(path, PNG_BYTES)
+      expect(await responseBytes(await route.call(path))).toEqual(PNG_BYTES)
+      const link = join(root, 'linked.png')
+      await symlink(path, link)
+      expect(await responseBytes(await route.call(link))).toEqual(PNG_BYTES)
     } finally {
       await rm(outside, { recursive: true, force: true })
     }
   })
 
-  it('streams a slice of a large sparse file without buffering it whole', async () => {
+  it.skipIf(process.platform === 'win32')('rejects a FIFO before opening it', async () => {
     const route = await mount()
-    const path = join(root, 'huge.mp4')
-    const handle = await open(path, 'w')
-    try {
-      await handle.truncate(256 * 1024 * 1024)
-    } finally {
-      await handle.close()
-    }
-    const response = await route.call(path, { headers: { range: 'bytes=0-9' } })
-    expect(response.status).toBe(206)
-    expect(response.headers.get('content-length')).toBe('10')
-    expect((await responseBytes(response)).length).toBe(10)
+    const path = join(root, 'stream.png')
+    const { execFile } = await import('node:child_process')
+    const { promisify } = await import('node:util')
+    await promisify(execFile)('mkfifo', [path])
+    expect((await route.call(path)).status).toBe(403)
   })
 
-  it('closes the file stream when the client aborts mid-response', async () => {
+  it('reads opaque remote targets through ctx.fs and preserves provider failures', async () => {
     const route = await mount()
-    const path = join(root, 'huge.mp4')
-    const handle = await open(path, 'w')
-    try {
-      await handle.truncate(64 * 1024 * 1024)
-    } finally {
-      await handle.close()
+    const target = { targetKey: FsTargetKey('opaque-remote-id'), displayPath: '/remote/photo.png' }
+    vi.spyOn(route.fs, 'resolve').mockResolvedValue(target)
+    const read = vi.spyOn(route.fs, 'readBytes').mockResolvedValue(PNG_BYTES)
+    expect(await responseBytes(await route.call('/remote/photo.png'))).toEqual(PNG_BYTES)
+    expect(read).toHaveBeenCalledWith(target, expect.any(AbortSignal), DEFAULT_LIMIT)
+    for (const [code, status] of [
+      ['FS_PERMISSION_DENIED', 403], ['FS_SANDBOX_DENIED', 403], ['FS_NOT_FOUND', 404],
+      ['FS_NOT_REGULAR_FILE', 403], ['FS_TOO_LARGE', 413], ['FS_IO_ERROR', 500],
+    ] as const) {
+      read.mockRejectedValueOnce(new FsError('provider rejected read', code))
+      expect((await route.call('/remote/photo.png')).status).toBe(status)
     }
-    const controller = new AbortController()
-    const response = await route.call(path, { signal: controller.signal })
-    expect(response.status).toBe(200)
-    const reader = response.body?.getReader()
-    expect(reader).toBeDefined()
-    await reader?.read()
-    controller.abort()
-    // The abort listener destroys the underlying file stream; reading the web
-    // stream then fails instead of draining the remaining 64 MiB.
-    await expect(reader?.read()).rejects.toBeTruthy()
+    read.mockRejectedValueOnce(new Error('provider bug'))
+    await expect(route.call('/remote/photo.png')).rejects.toThrow('provider bug')
   })
 
-  it('destroys the stream immediately for an already-aborted request', async () => {
+  it('serves an empty file and respects an aborted request', async () => {
     const route = await mount()
-    const path = join(root, 'huge.mp4')
-    const handle = await open(path, 'w')
-    try {
-      await handle.truncate(16 * 1024 * 1024)
-    } finally {
-      await handle.close()
-    }
-    const controller = new AbortController()
-    controller.abort()
-    const response = await route.call(path, { signal: controller.signal })
-    expect(response.status).toBe(200)
-    // No stream is opened for a client that is already gone.
-    expect(response.body).toBeNull()
+    const path = join(root, 'empty.png')
+    await writeFile(path, '')
+    const response = await route.call(path)
+    expect(response.headers.get('content-length')).toBe('0')
+    expect(await response.text()).toBe('')
+    expect((await route.call(path, { signal: AbortSignal.abort() })).status).toBe(499)
   })
 
-  it('unregisters the route when the contribution is disposed', async () => {
+  it('unregisters the route on disposal', async () => {
     const route = await mount()
-    expect(route.unregister).not.toHaveBeenCalled()
     await route.dispose()
     expect(route.unregister).toHaveBeenCalledTimes(1)
   })
diff --git a/packages/api/session-controller/tsconfig.host.json b/packages/api/session-controller/tsconfig.host.json
index 60a7775804..b775c833cf 100644
--- a/packages/api/session-controller/tsconfig.host.json
+++ b/packages/api/session-controller/tsconfig.host.json
@@ -34,6 +34,7 @@
     { "path": "../../client/connection/tsconfig.host.json" },
     { "path": "../../interaction/permission-presets" },
     { "path": "../../jobs/jobs" },
+    { "path": "../../fs/fs" },
     { "path": "../../llm/llm" },
     { "path": "../../util/deque" },
     { "path": "../../util/native-command" },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8c403b166e..121ea24c4a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -852,9 +852,6 @@ importers:
       mime-types:
         specifier: ^3.0.2
         version: 3.0.2
-      range-parser:
-        specifier: ^1.3.0
-        version: 1.3.0
       zod:
         specifier: ^4.4.3
         version: 4.4.3
@@ -892,6 +889,12 @@ importers:
       '@deepseek-ai/dsh-file-reference':
         specifier: workspace:^
         version: link:../../context/file-reference
+      '@deepseek-ai/dsh-fs':
+        specifier: workspace:^
+        version: link:../../fs/fs
+      '@deepseek-ai/dsh-fs-local':
+        specifier: workspace:^
+        version: link:../../fs/fs-local
       '@deepseek-ai/dsh-jobs':
         specifier: workspace:^
         version: link:../../jobs/jobs
@@ -961,9 +964,6 @@ importers:
       '@types/mime-types':
         specifier: ^3.0.1
         version: 3.0.1
-      '@types/range-parser':
-        specifier: ^1.2.7
-        version: 1.2.7
 
   packages/api/settings-controller:
     dependencies:

From 88ab8e91332f0a1a868bf1a899190c22ed1f0351 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 12:06:43 +0800
Subject: [PATCH 13/35] fix(ui): show authored text when markdown images fail

---
 .../expected/markdown-images/ui.expected.md   |  7 ++
 apps/web/tests/markdown-images.e2e.ts         | 92 ++++++++++++++++---
 .../client/ui-primitives/README.i18n.yaml     |  4 +-
 packages/client/ui-primitives/README.md       |  2 +-
 packages/client/ui-primitives/README.zh.md    |  2 +-
 .../ui-primitives/src/markdown/render.tsx     | 13 ++-
 .../markdown-path-images.client.spec.tsx      | 23 ++++-
 7 files changed, 120 insertions(+), 23 deletions(-)

diff --git a/apps/web/tests/expected/markdown-images/ui.expected.md b/apps/web/tests/expected/markdown-images/ui.expected.md
index f26dfd8214..49affa78a9 100644
--- a/apps/web/tests/expected/markdown-images/ui.expected.md
+++ b/apps/web/tests/expected/markdown-images/ui.expected.md
@@ -14,6 +14,13 @@
 - paragraph:
   - img "Remote test image"
 - paragraph: Local test image
+- paragraph:
+  - img "Workspace test image"
+- paragraph: Oversized image
+- paragraph:
+  - img "Outside workspace image"
+- paragraph: Missing image
+- paragraph: {{cwd}}/corrupt.png
 - paragraph: REMOTE_IMAGE_DONE
 - button "Copy":
   - img
diff --git a/apps/web/tests/markdown-images.e2e.ts b/apps/web/tests/markdown-images.e2e.ts
index 54ac8ddc9e..b8f18c6c67 100644
--- a/apps/web/tests/markdown-images.e2e.ts
+++ b/apps/web/tests/markdown-images.e2e.ts
@@ -1,8 +1,7 @@
-// Web e2e scenario: absolute HTTP(S) Markdown images. A validated session
-// assembled through the Session API is seeded cold into the real web
-// composition, then a separate image origin proves that the browser receives
-// a real network image while local-path Markdown remains inert alt text.
+// Real browser image loading and failure fallbacks through the shipped Web composition.
+import { open, writeFile } from 'node:fs/promises'
 import { createServer, type Server } from 'node:http'
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
@@ -32,6 +31,7 @@ const MODE = webSnapshotMode()
 const SEED_ID = 'markdown-images-web-e2e'
 const REMOTE_ALT = 'Remote test image'
 const LOCAL_ALT = 'Local test image'
+const WORKSPACE_ALT = 'Workspace test image'
 const PNG = Buffer.from(
   'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=',
   'base64',
@@ -81,7 +81,7 @@ async function stopServer(server: Server): Promise<void> {
 }
 
 /** Build one closed, invariant-checked session fixture with remote and local image Markdown. */
-function markdownImageFixture(remoteUrl: string): string {
+function markdownImageFixture(remoteUrl: string, outsidePath: string): string {
   const session = Session.create(SessionId('markdown-image-source'))
   const eventTimeOrigin = new Date().setHours(12, 0, 0, 0)
   session.append('turn/start', { turn: 1 })
@@ -110,6 +110,16 @@ function markdownImageFixture(remoteUrl: string): string {
           '',
           `![${LOCAL_ALT}](./local-image.png)`,
           '',
+          `![${WORKSPACE_ALT}]({{cwd}}/valid.png)`,
+          '',
+          '![Oversized image]({{cwd}}/oversized.png)',
+          '',
+          `![Outside workspace image](${outsidePath})`,
+          '',
+          '![Missing image]({{cwd}}/missing.png)',
+          '',
+          '![]({{cwd}}/corrupt.png)',
+          '',
           'REMOTE_IMAGE_DONE',
         ].join('\n'),
       }],
@@ -142,20 +152,38 @@ function markdownImageFixture(remoteUrl: string): string {
   ].join('\n')
 }
 
-describe('web e2e: remote Markdown image rendering', () => {
+describe('web e2e: Markdown image rendering', () => {
   let scaffold: WebScaffold
   let imageOrigin: ImageOrigin
   let browser: Browser
   let page: Page
   let tripwire: ReturnType<typeof watchConsole>
+  const mediaResponses = new Map<string, number>()
 
   beforeAll(async () => {
     imageOrigin = await startImageOrigin()
     scaffold = await launchWebScaffold({})
-    await seedSession(scaffold, markdownImageFixture(imageOrigin.url), SEED_ID)
+    await writeFile(join(scaffold.workspaceCwd, 'valid.png'), PNG)
+    await writeFile(join(scaffold.workspaceCwd, 'corrupt.png'), 'invalid image')
+    const oversized = await open(join(scaffold.workspaceCwd, 'oversized.png'), 'w')
+    try {
+      await oversized.truncate(20 * 1024 * 1024 + 1)
+    } finally {
+      await oversized.close()
+    }
+    const outsidePath = join(scaffold.persistenceRoot, 'outside.png')
+    await writeFile(outsidePath, PNG)
+    await writeFile(join(scaffold.workspaceCwd, 'active.html'), '<p>File preview</p><script>document.body.dataset.scriptRan = "yes"</script>')
+    await seedSession(scaffold, markdownImageFixture(imageOrigin.url, outsidePath), SEED_ID)
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
     tripwire = watchConsole(page)
+    page.on('response', (response) => {
+      const url = new URL(response.url())
+      if (url.pathname !== '/api/file') return
+      const path = url.searchParams.get('path')
+      if (path !== null) mediaResponses.set(path, response.status())
+    })
     await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
   }, 120_000)
@@ -163,17 +191,30 @@ describe('web e2e: remote Markdown image rendering', () => {
   afterAll(async () => {
     await browser?.close()
     await scaffold?.close()
-    await stopServer(imageOrigin.server)
+    if (imageOrigin !== undefined) await stopServer(imageOrigin.server)
   })
 
-  it.skipIf(MODE === 'record')('loads only the remote image and matches the conversation golden', async () => {
+  it('authenticates file requests and isolates directly opened active content', async () => {
+    const path = `/api/file?path=${encodeURIComponent(join(scaffold.workspaceCwd, 'active.html'))}`
+    const unauthenticated = await fetch(new URL(path, scaffold.baseUrl))
+    expect(unauthenticated.status).toBe(401)
+    await unauthenticated.body?.cancel()
+    const preview = await newEnglishPage(browser)
+    await preview.context().addCookies(await page.context().cookies())
+    try {
+      const response = await preview.goto(new URL(path, scaffold.baseUrl).href)
+      expect(response?.status()).toBe(200)
+      await preview.getByText('File preview', { exact: true }).waitFor()
+      expect(await preview.locator('body').getAttribute('data-script-ran')).toBeNull()
+    } finally {
+      await preview.close()
+    }
+  })
+
+  it.skipIf(MODE === 'record')('loads permitted images and shows authored text for failures', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-markdown-images'))
-    const groupRow = page.locator('[role="treeitem"]').first()
-    await groupRow.waitFor({ timeout: 15_000 })
-    await groupRow.click()
-    const sessionRow = page.locator('[role="treeitem"]').nth(1)
-    await sessionRow.waitFor({ timeout: 10_000 })
-    await sessionRow.click()
+    await page.getByRole('treeitem').first().click()
+    await page.getByRole('treeitem').nth(1).click()
     await expect.poll(() => page.getByText('REMOTE_IMAGE_DONE', { exact: true }).count(), {
       timeout: 15_000,
     }).toBe(1)
@@ -203,6 +244,27 @@ describe('web e2e: remote Markdown image rendering', () => {
     expect(await page.getByText(LOCAL_ALT, { exact: true }).count()).toBe(1)
     expect(imageOrigin.requests).toEqual([{ path: '/image.png', referer: undefined }])
 
+    const workspaceImage = page.getByRole('img', { name: WORKSPACE_ALT })
+    await expect.poll(() => mediaResponses.get(join(scaffold.workspaceCwd, 'valid.png'))).toBe(200)
+    await expect.poll(() => workspaceImage.evaluate(element => (element as HTMLImageElement).naturalWidth, undefined, {
+      timeout: 1_000,
+    }))
+      .toBe(1)
+    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()
+      expect(await page.getByRole('img', { name: alt }).count()).toBe(0)
+    }
+    await page.getByText(join(scaffold.workspaceCwd, 'corrupt.png'), { exact: true }).waitFor()
+    expect(mediaResponses).toEqual(new Map([
+      [join(scaffold.workspaceCwd, 'valid.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],
+    ]))
+
     const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
       .split(SEED_ID).join('{{seededId}}')
     await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 7d7ed48693..5778442c7c 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: 026b3a7258f3fe0e659e52e104e8ffa24ac8ad74
-README.zh.md: b08ada245692a7a57aae64d80da95e1ced1d970c
+README.md: 2a64ac8614ecac9005e85fbea08ffb0c291faa60
+README.zh.md: ae142907be4ff091d9481b8b098f6760c40b39a3
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 026b3a7258..2a64ac8614 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -68,7 +68,7 @@ The catalog above lists what each export is for; this section covers the behavio
 
 ### Rendering agent output
 
-`MarkdownText` renders untrusted GFM and TeX math, blocks unsafe links and images, and can turn resolved file mentions into explicit controls. 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 the output is byte-identical. 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.
+`MarkdownText` renders untrusted GFM and TeX math, blocks unsafe links and images, and can turn resolved file mentions into explicit controls. 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.
 
 
 ### Localizing copy
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index b08ada2456..ae142907be 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -68,7 +68,7 @@ kind: "package-library"
 
 ### 渲染 agent 输出
 
-`MarkdownText` 渲染不可信的 GFM 与 TeX 公式、阻止不安全的链接与图片，并可把已解析的文件提及转换为显式控件。当 owner 传入 `pathImages` 词表时，本地媒体路径的图片目标只在落定渲染阶段重写为可展示 URL（与 file mentions 相同的流式门）；不传词表时输出逐字节不变。回复流式输出时，它冻结已完成的块、按已完成行推进顶层未闭合 fence，并从保存的 Shiki grammar state 为该 fence 增量高亮。已完成的 token 行进入固定大小的 React 分组，后续分片只 reconcile 正在增长的分组；最终全量解析解决跨文档语法时，未变化的 fence 会保留该 DOM。`TerminalBlock`、`ReadBlock`、`DiffBlock`、`SearchBlock` 与 `WebBlock` 把对应的工具结果意图渲染为带复制控件、溢出处理及适用时 ANSI 处理的卡片。`JsonTree` 与 `JsonBlock` 以只读方式检查 JSON 值；`projectUserText` 把已发送的用户文本投影为行内普通文本段与引用 chip，供消息气泡和排队行使用。
+`MarkdownText` 渲染不可信的 GFM 与 TeX 公式、阻止不安全的链接与图片，并可把已解析的文件提及转换为显式控件。当 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，供消息气泡和排队行使用。
 
 
 ### 本地化文案
diff --git a/packages/client/ui-primitives/src/markdown/render.tsx b/packages/client/ui-primitives/src/markdown/render.tsx
index 565280440a..4d7805553b 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 } from 'react'
+import { Fragment, createElement, useState } from 'react'
 import type { Key, ReactNode } from 'react'
 import clsx from 'clsx'
 import type * as Md from 'mdast'
@@ -567,12 +567,19 @@ function renderImage(url: string, alt: string, key: Key, context: MarkdownRender
   if (imageSrc === undefined) {
     return <span key={key} className={css.imageAlt}>{alt}</span>
   }
+  return <MarkdownImage key={`${key}:${imageSrc}`} src={imageSrc} alt={alt} destination={url} />
+}
+
+/** 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 {
+  const [failed, setFailed] = useState(false)
+  if (failed) return <span className={css.imageAlt}>{alt || destination}</span>
   return (
     <img
-      key={key}
       className={css.image}
-      src={imageSrc}
+      src={src}
       alt={alt}
+      onError={() => { setFailed(true) }}
       loading="lazy"
       decoding="async"
       referrerPolicy="no-referrer"
diff --git a/packages/client/ui-primitives/tests/markdown-path-images.client.spec.tsx b/packages/client/ui-primitives/tests/markdown-path-images.client.spec.tsx
index 4e75dfb0fe..fdad05bbf2 100644
--- a/packages/client/ui-primitives/tests/markdown-path-images.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-path-images.client.spec.tsx
@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-import { cleanup, render, screen } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it } from 'vitest'
 import { MarkdownText } from './markdown-test-components.tsx'
 import type { MarkdownPathImages } from '../src/markdown/MarkdownText.tsx'
@@ -26,6 +26,27 @@ describe('MarkdownText local-path images', () => {
     expect(image?.getAttribute('alt')).toBe('diagram')
   })
 
+  it.each(['diagram', ''])('shows authored text after an image fails with alt %j', (alt) => {
+    const pathImages: MarkdownPathImages = { resolve: mapping }
+    const { container } = render(
+      <MarkdownText text={`![${alt}](/tmp/graph.png)`} pathImages={pathImages} />,
+    )
+    fireEvent.error(screen.getByAltText(alt))
+    expect(container.querySelector('img')).toBeNull()
+    expect(container.textContent).toBe(alt || '/tmp/graph.png')
+  })
+
+  it('loads a replacement destination after the preceding image failed', () => {
+    const pathImages: MarkdownPathImages = { resolve: value => `https://example.com${value}` }
+    const { container, rerender } = render(
+      <MarkdownText text={LOCAL_IMAGE} pathImages={pathImages} />,
+    )
+    fireEvent.error(screen.getByRole('img'))
+    rerender(<MarkdownText text="![](/tmp/replacement.png)" pathImages={pathImages} />)
+    expect(container.querySelector('img')?.getAttribute('src'))
+      .toBe('https://example.com/tmp/replacement.png')
+  })
+
   it('keeps the alt fallback when the vocabulary misses', () => {
     const pathImages: MarkdownPathImages = { resolve: () => undefined }
     const { container } = render(<MarkdownText text={LOCAL_IMAGE} pathImages={pathImages} />)

From 40c5ef4fc3c8e4adac8e0bd8a1c442d41dcdc3d4 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 12:55:57 +0800
Subject: [PATCH 14/35] refactor(api): reuse attachment limits for file
 responses

---
 ...-file-display-through-filesystem.i18n.yaml |  4 +--
 ...6-09-08-file-display-through-filesystem.md |  4 +--
 ...9-08-file-display-through-filesystem.zh.md |  4 +--
 docs/config-catalog.i18n.yaml                 |  4 +--
 docs/config-catalog.md                        |  4 ---
 docs/config-catalog.zh.md                     |  4 ---
 .../api/session-controller/README.i18n.yaml   |  4 +--
 packages/api/session-controller/README.md     |  4 +--
 packages/api/session-controller/README.zh.md  |  4 +--
 packages/api/session-controller/src/index.ts  | 10 ++-----
 .../src/media-references.ts                   | 10 +++----
 .../tests/media-references.host.spec.ts       | 30 +++++--------------
 12 files changed, 25 insertions(+), 61 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.i18n.yaml b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.i18n.yaml
index e88fd1e0e8..0817dcd4f1 100644
--- a/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.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 .agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md
-2026-09-08-file-display-through-filesystem.md: 6ff0c855ff0286c7ca7602ed2442a0fae6245c92
-2026-09-08-file-display-through-filesystem.zh.md: 5f8754ce91b53d964bdde03fb067dca858d3551a
+2026-09-08-file-display-through-filesystem.md: b1f93f8c9fbd245ad69bc732b2a599c6e0abeb0d
+2026-09-08-file-display-through-filesystem.zh.md: faa3fdb757c9a3fc60cae37692a559158e02ceee
diff --git a/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md
index 6ff0c855ff..b1f93f8c9f 100644
--- a/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md
+++ b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.md
@@ -14,7 +14,7 @@ The authenticated `/api/file` route reads ordinary files through `ctx.fs`. Authe
 
 GET calls the existing `readBytes(target, signal, maxBytes)`: providers reject known oversized files before content I/O and enforce the limit while reading. HEAD uses metadata without reading content. `FS_TOO_LARGE` becomes 413. MIME lookup supplies response metadata without sniffing file contents; unknown extensions use `application/octet-stream`. A sandbox CSP prevents directly opened HTML/SVG from executing with the authenticated API origin.
 
-`maxImageBytes` bounds images; `maxFileBytes` independently bounds audio, video, and other files. Both configuration overrides default to the resolved attachment image limit, normally 20 MiB. Separate overrides let deployments raise the non-image limit without weakening image admission. All responses contain complete files; Range is ignored and no range support is advertised.
+All files use the resolved `ctx.attachments.imageLimits.maxImageBytes` limit, normally 20 MiB. The attachment service owns this deployment setting. All responses contain complete files; Range is ignored and no range support is advertised.
 
 ## Alternatives considered
 
@@ -32,4 +32,4 @@ Each GET buffers the complete file in Host memory. Audio/video work as complete
 
 ## Testing
 
-Route tests cover sparse 1 GiB rejection before content I/O, post-stat growth, separate byte limits, ordinary MIME types, temporary paths and symlinks, opaque remote targets, provider failures, metadata-only HEAD, ignored Range, and disposal. Browser expectations cover rendered images, 413/404 and corrupt-image fallbacks, and an image outside the workspace. Remote byte transfer remains owned by the existing filesystem provider tests.
+Route tests cover sparse 1 GiB rejection before content I/O, post-stat growth, the shared attachment byte limit, ordinary MIME types, temporary paths and symlinks, opaque remote targets, provider failures, metadata-only HEAD, ignored Range, and disposal. Browser expectations cover rendered images, 413/404 and corrupt-image fallbacks, and an image outside the workspace. Remote byte transfer remains owned by the existing filesystem provider tests.
diff --git a/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.zh.md b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.zh.md
index 5f8754ce91..faa3fdb757 100644
--- a/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-08-file-display-through-filesystem.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 GET 调用现有 `readBytes(target, signal, maxBytes)`：提供方在内容 I/O 前拒绝已知超限文件，并在读取过程中执行上限。HEAD 使用元数据，不读取内容。`FS_TOO_LARGE` 转换为 413。MIME 查询提供响应元数据，不嗅探文件内容；未知扩展名使用 `application/octet-stream`。sandbox CSP 阻止直接打开的 HTML/SVG 以鉴权 API 源身份执行脚本。
 
-`maxImageBytes` 限制图片；`maxFileBytes` 独立限制音视频及其他文件。两个配置覆盖项均默认使用已解析的附件图片上限，通常为 20 MiB。独立覆盖项让部署可以提高非图片上限而不削弱图片准入。所有响应均包含完整文件；忽略 Range，也不声明支持 Range。
+所有文件均使用已解析的 `ctx.attachments.imageLimits.maxImageBytes` 上限，通常为 20 MiB。附件服务拥有此部署配置。所有响应均包含完整文件；忽略 Range，也不声明支持 Range。
 
 ## Alternatives considered
 
@@ -32,4 +32,4 @@ GET 调用现有 `readBytes(target, signal, maxBytes)`：提供方在内容 I/O
 
 ## Testing
 
-路由测试覆盖内容 I/O 前拒绝稀疏 1 GiB 文件、stat 后增长、独立字节上限、普通 MIME 类型、临时路径与符号链接、不透明远程目标、提供方失败、仅元数据 HEAD、忽略 Range 和释放。浏览器期望覆盖图片渲染、413/404 及损坏图片回退，以及工作区之外的图片。远程字节传输仍由现有文件系统提供方测试负责。
+路由测试覆盖内容 I/O 前拒绝稀疏 1 GiB 文件、stat 后增长、共用附件字节上限、普通 MIME 类型、临时路径与符号链接、不透明远程目标、提供方失败、仅元数据 HEAD、忽略 Range 和释放。浏览器期望覆盖图片渲染、413/404 及损坏图片回退，以及工作区之外的图片。远程字节传输仍由现有文件系统提供方测试负责。
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 995a4d8fb0..54a5407c82 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: 200c474cc5538151eacfe1c8765d08f2beb0e4e3
-config-catalog.zh.md: 679dab21acf005e3cdffce46305b172c9c69707a
+config-catalog.md: 058f3880c33097015d4b3472a1f94af38a965b2f
+config-catalog.zh.md: 0f63a6edfeaf9bd1d08cdb6615238519a0909a66
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 200c474cc5..058f3880c3 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -210,10 +210,6 @@ Requires: `agentDefaultModel` · `agents` · `attachments` · `fileUploads` · `
 export interface Config {
   /** Override platform desktop-opener detection. */
   readonly nativeOpen?: boolean
-  /** Inclusive byte limit for images served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
-  readonly maxImageBytes?: number
-  /** Inclusive byte limit for other files served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
-  readonly maxFileBytes?: number
 }
 ```
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 679dab21ac..0f63a6edfe 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -212,10 +212,6 @@ export interface Config {
 export interface Config {
   /** Override platform desktop-opener detection. */
   readonly nativeOpen?: boolean
-  /** Inclusive byte limit for images served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
-  readonly maxImageBytes?: number
-  /** Inclusive byte limit for other files served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
-  readonly maxFileBytes?: number
 }
 ```
 
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index bf13fd18a2..d7e2e717c7 100644
--- a/packages/api/session-controller/README.i18n.yaml
+++ b/packages/api/session-controller/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/api/session-controller/README.md
-README.md: 319e9a31b32e1a7421ade6a644fb0affd2757c64
-README.zh.md: 481f7311600fd3acd88aa83b5a776f5135867326
+README.md: 1c199007ad92751240102ffcb168de93e95dca50
+README.zh.md: 5ce39d5d73e43953971a000881acec81378793f9
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index 319e9a31b3..1c199007ad 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -36,7 +36,7 @@ The Session object also carries local submission echoes: `session.beginSubmissio
 <a id="session-media-references"></a>
 ## Session media references
 
-`SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when `connection`, `fs`, and `attachments` are composed. It reads ordinary files through `ctx.fs`, including temporary paths outside registered workspaces and files in remote providers. Neither directory containment nor MIME categories restrict access; `mime-types` supplies the response type, with `application/octet-stream` for unknown extensions. GET reuses `readBytes` for preflight and ongoing byte limits; HEAD reads metadata only. Images use `maxImageBytes`, while audio, video, and other files use `maxFileBytes`; exceeding the applicable limit returns 413. Responses contain the complete file, ignore Range, and carry `private, no-store`, `nosniff`, and a sandbox CSP so directly opened HTML/SVG cannot execute with the API origin. The Client rewrite lives in `ui-chat` (`AssistantMarkdown`); audio/video responses are available, while Markdown audio/video player nodes remain separate work.
+`SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when `connection`, `fs`, and `attachments` are composed. It reads ordinary files through `ctx.fs`, including temporary paths outside registered workspaces and files in remote providers. Neither directory containment nor MIME categories restrict access; `mime-types` supplies the response type, with `application/octet-stream` for unknown extensions. GET reuses `readBytes` for preflight and ongoing byte limits; HEAD reads metadata only. All files use `ctx.attachments.imageLimits.maxImageBytes` (normally 20 MiB); exceeding this limit returns 413. Responses contain the complete file, ignore Range, and carry `private, no-store`, `nosniff`, and a sandbox CSP so directly opened HTML/SVG cannot execute with the API origin. The Client rewrite lives in `ui-chat` (`AssistantMarkdown`); audio/video responses are available, while Markdown audio/video player nodes remain separate work.
 
 -----
 
@@ -46,8 +46,6 @@ The Session object also carries local submission echoes: `session.beginSubmissio
 | Field | Default | Meaning |
 |---|---:|---|
 | `nativeOpen` | platform-detected | Whether Session workspace paths can be handed to a native desktop opener |
-| `maxImageBytes` | attachment image limit (normally 20 MiB) | Inclusive byte cap for image responses; positive safe integer |
-| `maxFileBytes` | attachment image limit (normally 20 MiB) | Independent inclusive byte cap for audio, video, and other complete-file responses; positive safe integer |
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-session-controller) is the exhaustive source for accepted fields and their JSDoc.
 
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index 481f731160..5ce39d5d73 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -36,7 +36,7 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 <a id="session-media-references"></a>
 ## 会话媒体引用
 
-当 `connection`、`fs` 与 `attachments` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`。它通过 `ctx.fs` 读取普通文件，包括已注册工作区之外的临时路径与远程提供方中的文件。目录包含关系与 MIME 类别均不限制访问；`mime-types` 提供响应类型，未知扩展名使用 `application/octet-stream`。GET 复用 `readBytes` 执行读取前及读取中的字节限制；HEAD 只读取元数据。图片使用 `maxImageBytes`，音视频及其他文件使用 `maxFileBytes`；超过对应上限返回 413。响应包含完整文件，忽略 Range，并携带 `private, no-store`、`nosniff` 与 sandbox CSP，使直接打开的 HTML/SVG 无法以 API 源身份执行脚本。客户端重写位于 `ui-chat`（`AssistantMarkdown`）；音视频文件响应已可用，Markdown 音视频播放器节点仍是独立工作。
+当 `connection`、`fs` 与 `attachments` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`。它通过 `ctx.fs` 读取普通文件，包括已注册工作区之外的临时路径与远程提供方中的文件。目录包含关系与 MIME 类别均不限制访问；`mime-types` 提供响应类型，未知扩展名使用 `application/octet-stream`。GET 复用 `readBytes` 执行读取前及读取中的字节限制；HEAD 只读取元数据。所有文件均使用 `ctx.attachments.imageLimits.maxImageBytes`（通常为 20 MiB）；超过此上限返回 413。响应包含完整文件，忽略 Range，并携带 `private, no-store`、`nosniff` 与 sandbox CSP，使直接打开的 HTML/SVG 无法以 API 源身份执行脚本。客户端重写位于 `ui-chat`（`AssistantMarkdown`）；音视频文件响应已可用，Markdown 音视频播放器节点仍是独立工作。
 
 -----
 
@@ -46,8 +46,6 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 | 字段 | 默认值 | 含义 |
 |---|---:|---|
 | `nativeOpen` | 平台探测 | 是否能把 Session 工作区路径交给原生桌面打开器 |
-| `maxImageBytes` | 附件图片上限（通常 20 MiB） | 图片响应的字节上限（含等值）；正安全整数 |
-| `maxFileBytes` | 附件图片上限（通常 20 MiB） | 音视频及其他完整文件响应的独立字节上限（含等值）；正安全整数 |
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-session-controller)是所有受支持字段及其 JSDoc 的完整来源。
 
diff --git a/packages/api/session-controller/src/index.ts b/packages/api/session-controller/src/index.ts
index 0e24b15f10..9cc93be179 100644
--- a/packages/api/session-controller/src/index.ts
+++ b/packages/api/session-controller/src/index.ts
@@ -70,10 +70,6 @@ declare module '@deepseek-ai/cordis' {
 export interface Config {
   /** Override platform desktop-opener detection. */
   readonly nativeOpen?: boolean
-  /** Inclusive byte limit for images served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
-  readonly maxImageBytes?: number
-  /** Inclusive byte limit for other files served by `/api/file`. Defaults to `ctx.attachments.imageLimits.maxImageBytes`. */
-  readonly maxFileBytes?: number
 }
 
 /** Host integrations replaceable by direct unit tests. */
@@ -101,8 +97,6 @@ export class SessionController extends TypertRemoteService {
 
   static Config: z<Config> = z.object({
     nativeOpen: z.boolean(),
-    maxImageBytes: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER),
-    maxFileBytes: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER),
   })
 
   private readonly agents: ApiSessionAgentController
@@ -116,7 +110,7 @@ export class SessionController extends TypertRemoteService {
 
   /**
    * @param ctx - Host context containing the Session capability assembly.
-   * @param config - native-opener and media-read deployment policy.
+   * @param config - native-opener deployment policy.
    * @param internals - host integrations replaceable by direct unit tests.
    */
   constructor(ctx: Context, config: Config, internals: SessionControllerInternals = {}) {
@@ -141,7 +135,7 @@ export class SessionController extends TypertRemoteService {
     this.canOpenPath = internals.canOpenPath
       ?? (() => config.nativeOpen ?? (internals.openPath !== undefined || canOpenNativePath()))
     ctx.plugin(SessionFileReferences)
-    ctx.plugin(SessionMediaReferences, config)
+    ctx.plugin(SessionMediaReferences)
     ctx.plugin(SessionSkillCatalog)
 
     ctx.on('session/created', (session) => {
diff --git a/packages/api/session-controller/src/media-references.ts b/packages/api/session-controller/src/media-references.ts
index bacc0a8b71..9da80029f5 100644
--- a/packages/api/session-controller/src/media-references.ts
+++ b/packages/api/session-controller/src/media-references.ts
@@ -19,7 +19,7 @@ const BASE_HEADERS = {
   'Content-Security-Policy': "sandbox; default-src 'none'",
 }
 
-async function serveFile(request: Request, fs: FileSystem, limits: { image: number; file: number }): Promise<Response> {
+async function serveFile(request: Request, fs: FileSystem, maxBytes: number): Promise<Response> {
   const fail = (status: number, text: string): Response =>
     new Response(request.method === 'HEAD' ? null : text, { status, headers: BASE_HEADERS })
   const path = new URL(request.url).searchParams.get('path')
@@ -28,7 +28,6 @@ async function serveFile(request: Request, fs: FileSystem, limits: { image: numb
   try {
     const target = await fs.resolve(path, { signal: request.signal })
     const mediaType = mime.lookup(target.displayPath) || 'application/octet-stream'
-    const maxBytes = mediaType.startsWith('image/') ? limits.image : limits.file
     const headers: Record<string, string> = {
       ...BASE_HEADERS,
       'Content-Type': mediaType,
@@ -66,14 +65,13 @@ async function serveFile(request: Request, fs: FileSystem, limits: { image: numb
  */
 export const SessionMediaReferences = {
   inject: ['connection', 'fs', 'attachments'],
-  apply(ctx: Context, config: { maxImageBytes?: number; maxFileBytes?: number }): void {
-    const defaults = ctx.attachments.imageLimits.maxImageBytes
-    const limits = { image: config.maxImageBytes ?? defaults, file: config.maxFileBytes ?? defaults }
+  apply(ctx: Context): void {
+    const maxBytes = ctx.attachments.imageLimits.maxImageBytes
     ctx.effect(() => ctx.connection.fetch.register({
       path: '/api/file',
       methods: ['GET', 'HEAD'],
       requestBody: 'buffered',
-      fetch: request => serveFile(request, ctx.fs, limits),
+      fetch: request => serveFile(request, ctx.fs, maxBytes),
     }), 'session-controller: /api/file')
   },
 }
diff --git a/packages/api/session-controller/tests/media-references.host.spec.ts b/packages/api/session-controller/tests/media-references.host.spec.ts
index 187b802efe..61572ab0be 100644
--- a/packages/api/session-controller/tests/media-references.host.spec.ts
+++ b/packages/api/session-controller/tests/media-references.host.spec.ts
@@ -6,7 +6,6 @@ import { Context } from '@deepseek-ai/cordis'
 import { FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
 import { SessionMediaReferences } from '../src/media-references.ts'
-import { SessionController } from '../src/index.ts'
 
 const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3, 4])
 const DEFAULT_LIMIT = 20 * 1024 * 1024
@@ -28,7 +27,7 @@ describe('SessionMediaReferences /api/file', () => {
     await rm(root, { recursive: true, force: true })
   })
 
-  async function mount(config: { maxImageBytes?: number; maxFileBytes?: number } = {}, defaultLimit = DEFAULT_LIMIT) {
+  async function mount(maxBytes = DEFAULT_LIMIT) {
     const ctx = new Context()
     contexts.push(ctx)
     let handler: ((request: Request) => Promise<Response>) | undefined
@@ -41,9 +40,9 @@ describe('SessionMediaReferences /api/file', () => {
         },
       },
     } as never)
-    ctx.provide('attachments', { imageLimits: { maxImageBytes: defaultLimit } } as never)
+    ctx.provide('attachments', { imageLimits: { maxImageBytes: maxBytes } } as never)
     await ctx.plugin(LocalFileSystem, { cwd: root }).await()
-    await ctx.plugin(SessionMediaReferences, config).await()
+    await ctx.plugin(SessionMediaReferences).await()
     const raw = (url: string, init?: RequestInit) => {
       if (handler === undefined) throw new Error('route not registered')
       return handler(new Request(url, init))
@@ -57,23 +56,8 @@ describe('SessionMediaReferences /api/file', () => {
     }
   }
 
-  it('inherits attachment limits unless configured and rejects invalid overrides', async () => {
-    expect(SessionController.Config({}).maxImageBytes).toBeUndefined()
-    expect(SessionController.Config({}).maxFileBytes).toBeUndefined()
-    for (const field of ['maxImageBytes', 'maxFileBytes']) {
-      expect(SessionController.Config({ [field]: 1 })).toMatchObject({ [field]: 1 })
-      for (const value of [0, -1, 1.5, Infinity, NaN, Number.MAX_SAFE_INTEGER + 1]) {
-        expect(() => SessionController.Config({ [field]: value })).toThrow()
-      }
-    }
-    const route = await mount({}, PNG_BYTES.length - 1)
-    const path = join(root, 'image.png')
-    await writeFile(path, PNG_BYTES)
-    expect((await route.call(path)).status).toBe(413)
-  })
-
   it('serves the inclusive image cap and refuses larger images for GET, HEAD and Range', async () => {
-    const route = await mount({ maxImageBytes: PNG_BYTES.length })
+    const route = await mount(PNG_BYTES.length)
     const path = join(root, 'bounded.png')
     await writeFile(path, PNG_BYTES)
     expect(await responseBytes(await route.call(path))).toEqual(PNG_BYTES)
@@ -101,7 +85,7 @@ describe('SessionMediaReferences /api/file', () => {
   })
 
   it('uses the filesystem byte reader to reject post-stat image growth', async () => {
-    const route = await mount({ maxImageBytes: PNG_BYTES.length })
+    const route = await mount(PNG_BYTES.length)
     const path = join(root, 'growing.png')
     await writeFile(path, PNG_BYTES)
     route.fs.internals.inspectReadBytesAfterStat = async () => {
@@ -127,8 +111,8 @@ describe('SessionMediaReferences /api/file', () => {
     expect(await responseBytes(response)).toEqual(PNG_BYTES)
   })
 
-  it.each(['mp4', 'mp3', 'bin'])('allows a separate byte cap for .%s files', async (extension) => {
-    const route = await mount({ maxImageBytes: 1, maxFileBytes: PNG_BYTES.length })
+  it.each(['mp4', 'mp3', 'bin'])('applies the attachment byte cap to .%s files', async (extension) => {
+    const route = await mount(PNG_BYTES.length)
     const path = join(root, `file.${extension}`)
     await writeFile(path, PNG_BYTES)
     expect(await responseBytes(await route.call(path))).toEqual(PNG_BYTES)

From cb3df20cf3cdcd06d32aa9f221238d48d116b2f0 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 14:25:50 +0800
Subject: [PATCH 15/35] docs(api): remove obsolete media path restrictions

---
 packages/api/session-controller/README.i18n.yaml | 4 ++--
 packages/api/session-controller/README.md        | 1 -
 packages/api/session-controller/README.zh.md     | 1 -
 3 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index 504fbe0603..156a15aa1a 100644
--- a/packages/api/session-controller/README.i18n.yaml
+++ b/packages/api/session-controller/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/api/session-controller/README.md
-README.md: deeade0dee6602c0f5e75e0d9321b4b5223d0f24
-README.zh.md: 143774977e5cf62db57c00ad22e1a52467592b42
+README.md: 7d0785c77395f9eae55656708a15a842a27f079b
+README.zh.md: b39a6a512b82cef45550d11660b7a87b2cd0b035
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index deeade0dee..7d0785c773 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -64,7 +64,6 @@ No direct effect; model requests remain owned by the Agent and LLM packages.
 
 <a id="known-limitations-and-deferred-work"></a>
 
-- Media reads use Host files under registered workspace roots. Temporary files outside those roots return 403; files available only in a remote filesystem provider cannot be served. The route does not use `ctx.fs`; its read permissions differ from `read_image`.
 - The image byte cap does not validate decoded dimensions or pixel count.
 - Control baselines represent process-local state and therefore cannot reconstruct jobs after a Host restart.
 - A failed follow resumption remains visible to the caller instead of retrying indefinitely.
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index 143774977e..b39a6a512b 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -64,7 +64,6 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 
 <a id="known-limitations-and-deferred-work"></a>
 
-- 媒体读取使用已注册 workspace 根内的 Host 文件。根外临时文件返回 403；仅存在于远程文件系统提供方中的文件无法提供。该路由不使用 `ctx.fs`，其读取权限与 `read_image` 不同。
 - 图片字节上限不校验解码后的尺寸或像素数。
 - Control baseline 表示进程本地状态，因此 Host 重启后无法重建 jobs。
 - follow 恢复失败会对调用方可见，而不会无限重试。

From a189104d812c416fe23c5196904bc1e43677c6cb Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 15:36:55 +0800
Subject: [PATCH 16/35] docs: refresh session controller module dependencies

---
 docs/module-graph.i18n.yaml | 4 ++--
 docs/module-graph.md        | 3 ++-
 docs/module-graph.zh.md     | 3 ++-
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index 7789f3c308..fa254b9d2a 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.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/module-graph.md
-module-graph.md: ecb72f02bc7a27a75318e8abf56c20f9915831ea
-module-graph.zh.md: 5c94c866d10e81948dd69089210cd4b08ded7531
+module-graph.md: f0ebb388318ed4a0aa8896a8040a5539f5477037
+module-graph.zh.md: 0cc8ff7b9a7601102f8d708b8ebb2d17c7bb0612
diff --git a/docs/module-graph.md b/docs/module-graph.md
index ecb72f02bc..f0ebb38831 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -1070,6 +1070,7 @@ flowchart TD
   pkg_api_session_controller --> pkg_client_file_upload
   pkg_api_session_controller --> pkg_commands
   pkg_api_session_controller --> pkg_file_reference
+  pkg_api_session_controller --> pkg_fs
   pkg_api_session_controller --> pkg_jobs
   pkg_api_session_controller --> pkg_llm
   pkg_api_session_controller --> pkg_native_command
@@ -1419,7 +1420,7 @@ flowchart TD
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
+| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
 | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) |
 | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index 5c94c866d1..0cc8ff7b9a 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -1072,6 +1072,7 @@ flowchart TD
   pkg_api_session_controller --> pkg_client_file_upload
   pkg_api_session_controller --> pkg_commands
   pkg_api_session_controller --> pkg_file_reference
+  pkg_api_session_controller --> pkg_fs
   pkg_api_session_controller --> pkg_jobs
   pkg_api_session_controller --> pkg_llm
   pkg_api_session_controller --> pkg_native_command
@@ -1421,7 +1422,7 @@ flowchart TD
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
+| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
 | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) |
 | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |

From 8932b8670e0282cef4716ac3300cf0819c5a678a Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 15:36:59 +0800
Subject: [PATCH 17/35] test(ci): make Lefthook lock replacement deterministic

---
 scripts/install-lefthook.spec.ts | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)

diff --git a/scripts/install-lefthook.spec.ts b/scripts/install-lefthook.spec.ts
index fa4cad967e..b6b2831fb6 100644
--- a/scripts/install-lefthook.spec.ts
+++ b/scripts/install-lefthook.spec.ts
@@ -91,6 +91,8 @@ try {
 }
 const delay = Number(process.env.DSH_TEST_LEFTHOOK_DELAY_MS ?? 0)
 if (delay > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay)
+const replaceLockPath = process.env.DSH_TEST_LEFTHOOK_REPLACE_LOCK_PATH
+if (replaceLockPath !== undefined) writeFileSync(replaceLockPath, 'replacement owner\\n')
 const shouldFail = process.env.DSH_TEST_LEFTHOOK_FAIL === '1'
 if (!shouldFail) {
   const binary = join(root, 'node_modules', '.bin', process.platform === 'win32' ? 'lefthook.cmd' : 'lefthook')
@@ -532,21 +534,14 @@ describe('worktree-local Lefthook installer', { timeout: 90_000 }, () => {
   it('does not release an installer lock whose ownership changed', async () => {
     const fixture = createFixture()
     const lockPath = installLockPath(fixture)
-    const runningPath = join(hooksPath(fixture, fixture.main), '.fake-lefthook-running')
-    const install = runInstaller(fixture, fixture.main, { DSH_TEST_LEFTHOOK_DELAY_MS: '250' })
-    try {
-      await waitForPath(runningPath)
-    } catch (error) {
-      await install
-      throw error
-    }
-    const replacementRecord = 'replacement owner\n'
-    writeFileSync(lockPath, replacementRecord)
+    // The fake child replaces the record while the installer holds the lock.
+    const result = await runInstaller(fixture, fixture.main, {
+      DSH_TEST_LEFTHOOK_REPLACE_LOCK_PATH: lockPath,
+    })
 
-    const result = await install
     expect(result.status).toBe(1)
     expect(result.stderr).toContain('installer lock ownership changed')
-    expect(readFileSync(lockPath, 'utf8')).toBe(replacementRecord)
+    expect(readFileSync(lockPath, 'utf8')).toBe('replacement owner\n')
   })
 
   it.skipIf(process.platform === 'win32')('preserves trailing spaces in worktree paths', async () => {

From e33834f5228a301c4551ccf61d5c529c3276e6d5 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 16:12:14 +0800
Subject: [PATCH 18/35] test(web): await session and responsive layout
 readiness

---
 apps/web/tests/github-ready-review.e2e.ts  |  6 ++--
 apps/web/tests/queue-actions.e2e.ts        | 41 ++++++++++++----------
 apps/web/tests/workspace-management.e2e.ts |  5 +++
 3 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/apps/web/tests/github-ready-review.e2e.ts b/apps/web/tests/github-ready-review.e2e.ts
index 1530c35c80..9c44a90e04 100644
--- a/apps/web/tests/github-ready-review.e2e.ts
+++ b/apps/web/tests/github-ready-review.e2e.ts
@@ -140,8 +140,10 @@ describe.skipIf(MODE === 'record')('web e2e: GitHub ready-for-review', () => {
       },
     }
     expect((await send(webhookOrigin, 'ready', payload)).status).toBe(202)
-    await vi.waitFor(() => { expect(scaffold.ctx.agents.list()).toHaveLength(before + 1) })
-    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    // HTTP 202 acknowledges ingress; the model request follows durable
+    // Workspace and Session creation by the asynchronous webhook rule.
+    await expect.poll(() => adapter.requests.length, { timeout: 30_000 }).toBe(1)
+    expect(scaffold.ctx.agents.list()).toHaveLength(before + 1)
 
     const agent = scaffold.ctx.agents.list().find(candidate => candidate.session.header.cwd === scaffold.workspaceCwd)
     expect(agent).toBeDefined()
diff --git a/apps/web/tests/queue-actions.e2e.ts b/apps/web/tests/queue-actions.e2e.ts
index 086bbce416..14a7e92804 100644
--- a/apps/web/tests/queue-actions.e2e.ts
+++ b/apps/web/tests/queue-actions.e2e.ts
@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
-import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
+import { afterEach, describe, expect, it, onTestFailed, vi } from 'vitest'
 import { deriveReplayScript, parseSessionLog, type ReplayEntry } from '@deepseek-ai/dsh-llm-replay'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import {
@@ -147,23 +147,28 @@ describe('web e2e: queue row actions', () => {
     ).toBe(2)
 
     await page.setViewportSize({ width: 640, height: 1000 })
-    const queueBox = await page.locator('[data-queue-dock]').boundingBox()
-    const composerBox = await page.locator('[data-composer-card]').boundingBox()
-    expect(queueBox).not.toBeNull()
-    expect(composerBox).not.toBeNull()
-    expect(queueBox!.x).toBeGreaterThanOrEqual(composerBox!.x)
-    expect(queueBox!.x + queueBox!.width)
-      .toBeLessThanOrEqual(composerBox!.x + composerBox!.width)
-    const queueLeftInset = queueBox!.x - composerBox!.x
-    const queueRightInset = composerBox!.x + composerBox!.width - queueBox!.x - queueBox!.width
-    const composerMetrics = await page.locator('[data-composer-card]').evaluate((element) => {
-      const style = getComputedStyle(element)
-      return {
-        dockInset: Number.parseFloat(style.getPropertyValue('--dsh-composer-dock-inset')),
-      }
-    })
-    expect(queueLeftInset).toBeCloseTo(composerMetrics.dockInset, 1)
-    expect(queueRightInset).toBeCloseTo(composerMetrics.dockInset, 1)
+    await page.locator('[data-sidebar-collapsed="true"]').waitFor()
+    // The responsive sidebar and composer settle independently; sample both
+    // rectangles in one browser task so the comparison uses one layout.
+    await vi.waitFor(async () => {
+      const metrics = await page.evaluate(() => {
+        const queue = document.querySelector('[data-queue-dock]')
+        const composer = document.querySelector('[data-composer-card]')
+        if (queue === null || composer === null) return undefined
+        const queueBox = queue.getBoundingClientRect()
+        const composerBox = composer.getBoundingClientRect()
+        return {
+          leftInset: queueBox.left - composerBox.left,
+          rightInset: composerBox.right - queueBox.right,
+          dockInset: Number.parseFloat(getComputedStyle(composer).getPropertyValue('--dsh-composer-dock-inset')),
+        }
+      })
+      expect(metrics).toBeDefined()
+      expect(metrics!.leftInset).toBeGreaterThanOrEqual(0)
+      expect(metrics!.rightInset).toBeGreaterThanOrEqual(0)
+      expect(metrics!.leftInset).toBeCloseTo(metrics!.dockInset, 1)
+      expect(metrics!.rightInset).toBeCloseTo(metrics!.dockInset, 1)
+    }, { timeout: 10_000 })
     await page.setViewportSize({ width: 1680, height: 1000 })
 
     const editRow = page.locator('[data-queue-dock] li', { hasText: EDIT })
diff --git a/apps/web/tests/workspace-management.e2e.ts b/apps/web/tests/workspace-management.e2e.ts
index d591dbe3b0..99bce35b56 100644
--- a/apps/web/tests/workspace-management.e2e.ts
+++ b/apps/web/tests/workspace-management.e2e.ts
@@ -77,6 +77,11 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
       () => scaffold.ctx.workspaceRegistry.resolveByPath(join(parent, name)),
       { timeout: 10_000 },
     ).not.toBeUndefined()
+    // Adoption also opens a blank Session. Its selected row must reach the
+    // browser before a later workspace action can depend on the row positions.
+    const row = page.getByRole('treeitem').filter({ hasText: name }).first()
+    const section = row.locator('xpath=ancestor::*[contains(@class, "groupSection")][1]')
+    await section.locator('[role="treeitem"][aria-selected="true"]').waitFor({ timeout: 10_000 })
   }
 
   /**

From 3aee29c657c0a5e304645cdaf2c461216c217ee6 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 16:35:01 +0800
Subject: [PATCH 19/35] test(lsp): hold queued source reads behind a response
 barrier

---
 .../lsp/lsp-stdio/tests/fixture-server.ts     | 20 +++-----
 .../lsp/lsp-stdio/tests/lifecycle.spec.ts     | 48 ++++++++++++++-----
 2 files changed, 44 insertions(+), 24 deletions(-)

diff --git a/packages/lsp/lsp-stdio/tests/fixture-server.ts b/packages/lsp/lsp-stdio/tests/fixture-server.ts
index e6b3800916..fc4491507f 100644
--- a/packages/lsp/lsp-stdio/tests/fixture-server.ts
+++ b/packages/lsp/lsp-stdio/tests/fixture-server.ts
@@ -12,7 +12,6 @@
  * - LSP_FAKE_CRASH_ON_OPEN: "1" exits the process when a didOpen arrives (crash test).
  * - LSP_FAKE_EXIT_AFTER_REPLY: "1" exits the process right after answering a textDocument/* request,
  *   simulating a server that dies while idle so the pool holds a dead instance (eviction test).
- * - LSP_FAKE_REPLY_DELAY_MS: delays each textDocument/* response by this many milliseconds.
  * - LSP_FAKE_OPEN_MARKER: appends each didOpen document text as one JSON line to this path.
  * - LSP_FAKE_INITIALIZED_MARKER: records when the initialized notification is received.
  * - LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED: "1" stops consuming stdin after initialized.
@@ -34,7 +33,6 @@ const extraCaps: unknown = process.env.LSP_FAKE_CAPS !== undefined ? JSON.parse(
 const hang = process.env.LSP_FAKE_HANG === '1'
 const crashOnOpen = process.env.LSP_FAKE_CRASH_ON_OPEN === '1'
 const exitAfterReply = process.env.LSP_FAKE_EXIT_AFTER_REPLY === '1'
-const replyDelayMs = Number(process.env.LSP_FAKE_REPLY_DELAY_MS ?? 0)
 const openMarker = process.env.LSP_FAKE_OPEN_MARKER
 const initializedMarker = process.env.LSP_FAKE_INITIALIZED_MARKER
 const pauseStdinAfterInitialized = process.env.LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED === '1'
@@ -153,18 +151,14 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul
   if (method === 'textDocument/didClose') return
   if (method?.startsWith('textDocument/')) {
     if (hang) return
-    const reply = (): void => {
-      if (errorReply) {
-        send({ id, error: { code: -32000, message: 'server refused the request' } })
-      } else {
-        send({ id, result: resultFor(method) })
-      }
-      // Simulate an idle death: answer this request, then exit before the next one arrives so the
-      // pool is left holding a dead instance.
-      if (exitAfterReply) setTimeout(() => process.exit(0), 20)
+    if (errorReply) {
+      send({ id, error: { code: -32000, message: 'server refused the request' } })
+    } else {
+      send({ id, result: resultFor(method) })
     }
-    if (replyDelayMs > 0) setTimeout(reply, replyDelayMs)
-    else reply()
+    // Simulate an idle death: answer this request, then exit before the next one arrives so the
+    // pool is left holding a dead instance.
+    if (exitAfterReply) setTimeout(() => process.exit(0), 20)
     return
   }
   // Unknown request with an id: answer null so the client never stalls.
diff --git a/packages/lsp/lsp-stdio/tests/lifecycle.spec.ts b/packages/lsp/lsp-stdio/tests/lifecycle.spec.ts
index e368e2d952..9cedab10d5 100644
--- a/packages/lsp/lsp-stdio/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-stdio/tests/lifecycle.spec.ts
@@ -299,21 +299,47 @@ describe('lsp-stdio end to end over a fake server', () => {
 
   it('reads a queued query source only when its lifecycle starts', async () => {
     const marker = join(root, 'opened.jsonl')
+    let provider: LspProvider | undefined
     const ctx = await mount({
       LSP_FAKE_DEF: 'null',
-      LSP_FAKE_REPLY_DELAY_MS: '300',
       LSP_FAKE_OPEN_MARKER: marker,
+    }, {}, (registered) => { provider = registered })
+    const release = Promise.withResolvers<undefined>()
+    const request = Object.getOwnPropertyDescriptor(LspConnection.prototype, 'request')?.value as LspConnection['request']
+    let holdFirst = true
+    const requestSpy = vi.spyOn(LspConnection.prototype, 'request').mockImplementation(async function (this: LspConnection, method, params) {
+      const hold = method === 'textDocument/definition' && holdFirst
+      if (hold) holdFirst = false
+      const result = await request.call(this, method, params)
+      if (hold) await release.promise
+      return result
     })
-    const first = ctx.lsp.query(query('goToDefinition'))
-    await waitFor(async () => (await markerLines(marker)).length === 1)
-    const second = ctx.lsp.query(query('goToDefinition'))
-    await writeFile(join(ws, 'a.ts'), 'const changed = 2\n')
-    await Promise.all([first, second])
-    expect(await markerLines(marker)).toEqual([
-      'const x = 1\nconst y = x\n',
-      'const changed = 2\n',
-    ])
-    await ctx.fiber.dispose()
+    const pending: Promise<unknown>[] = []
+    try {
+      const first = ctx.lsp.query(query('goToDefinition'))
+      pending.push(Promise.allSettled([first]))
+      await waitFor(async () => (await markerLines(marker)).length === 1)
+      // The changed tail proves the second query entered the provider queue
+      // while the first response is held, before the source rewrite starts.
+      const queues = (provider as unknown as { queues: ReadonlyMap<unknown, Promise<void>> }).queues
+      const firstTail = [...queues.values()][0]
+      expect(firstTail).toBeDefined()
+      const second = ctx.lsp.query(query('goToDefinition'))
+      pending.push(Promise.allSettled([second]))
+      await vi.waitFor(() => { expect([...queues.values()][0]).not.toBe(firstTail) }, { timeout: 3000 })
+      await writeFile(join(ws, 'a.ts'), 'const changed = 2\n')
+      release.resolve(undefined)
+      await Promise.all([first, second])
+      expect(await markerLines(marker)).toEqual([
+        'const x = 1\nconst y = x\n',
+        'const changed = 2\n',
+      ])
+    } finally {
+      release.resolve(undefined)
+      await Promise.all(pending)
+      requestSpy.mockRestore()
+      await ctx.fiber.dispose()
+    }
   })
 
   it('aborts an in-flight query when the signal fires', async () => {

From 839a6fa995349ed8bbabc076958ffab952909434 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 16:35:16 +0800
Subject: [PATCH 20/35] test(web): await mutation replies before capturing
 settled UI

---
 apps/web/tests/queue-actions.e2e.ts                   | 11 +++++++++--
 apps/web/tests/seeded-history.e2e.ts                  |  3 +++
 .../web/queue-actions/preserved-expanded.expected.md  |  1 -
 snapshots/web/queue-actions/preserved.expected.md     |  1 -
 4 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/apps/web/tests/queue-actions.e2e.ts b/apps/web/tests/queue-actions.e2e.ts
index 14a7e92804..e38e6a35fe 100644
--- a/apps/web/tests/queue-actions.e2e.ts
+++ b/apps/web/tests/queue-actions.e2e.ts
@@ -175,6 +175,8 @@ describe('web e2e: queue row actions', () => {
     await editRow.getByRole('button', { name: 'Edit queued message' }).click()
     const editor = page.getByRole('textbox', { name: 'Edit queued message' })
     await editor.fill(EDITED)
+    await page.getByRole('button', { name: 'Save queued message' }).hover()
+    await page.getByRole('tooltip', { name: 'Save queued message', exact: true }).waitFor()
     const editingSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(EDITING_EXPECTED, editingSnapshot, MODE)
     await page.getByRole('button', { name: 'Save queued message' }).click()
@@ -183,6 +185,11 @@ describe('web e2e: queue row actions', () => {
     const removeRow = page.locator('[data-queue-dock] li', { hasText: REMOVE })
     await removeRow.getByRole('button', { name: 'Remove queued message' }).click()
     await expect.poll(() => page.getByText(REMOVE, { exact: true }).count()).toBe(0)
+    // The queue stream can remove the row before the mutation reply clears busy.
+    const remainingEdit = page.getByRole('button', { name: 'Edit queued message', exact: true })
+    await expect.poll(() => remainingEdit.isEnabled(), { timeout: 10_000 }).toBe(true)
+    await remainingEdit.hover()
+    await page.getByRole('tooltip', { name: 'Edit queued message', exact: true }).waitFor()
 
     const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
@@ -227,9 +234,9 @@ describe('web e2e: queue row actions', () => {
     await expect.poll(() => page.getByRole('button', { name: 'Remove queued message' }).count())
       .toBe(2)
 
-    // Stop becomes Send under the pointer; dismiss its hover tooltip before capture.
+    // Stop becomes Send under the pointer; capture the idle queue with tooltips dismissed.
     await page.mouse.move(0, 0)
-    await expect.poll(() => page.getByRole('tooltip').filter({ hasText: 'Send message' }).count()).toBe(0)
+    await expect.poll(() => page.getByRole('tooltip').count()).toBe(0)
     const preservedSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(PRESERVED_EXPECTED, preservedSnapshot, MODE)
     const expanded = await captureExpandedTurnProcessAria(
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index 2f59edc165..a6ab6adf15 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -501,6 +501,9 @@ describe('web e2e: seeded history renders through cold resume', () => {
       const userId = userLine?.match(/^Anonymous user: ([0-9a-f-]+)/i)?.[1]
       if (userId === undefined) throw new Error('feedback command omitted the user id')
 
+      // command/done can arrive before the submit reply releases the composer.
+      await expect.poll(() => input.textContent(), { timeout: 10_000 }).toBe('')
+      await expect.poll(() => page.getByRole('button', { name: 'Add attachment' }).isEnabled(), { timeout: 10_000 }).toBe(true)
       const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
         .split(SEED_ID).join('{{seededId}}')
         .split(userId).join('{{userId}}')
diff --git a/snapshots/web/queue-actions/preserved-expanded.expected.md b/snapshots/web/queue-actions/preserved-expanded.expected.md
index 6e9d8c1134..55fb2e4783 100644
--- a/snapshots/web/queue-actions/preserved-expanded.expected.md
+++ b/snapshots/web/queue-actions/preserved-expanded.expected.md
@@ -45,7 +45,6 @@
     - text: Edited queue item
     - button "Edit queued message":
       - img
-    - tooltip "Edit queued message"
     - button "Remove queued message":
       - img
     - button "Steer queued message" [disabled]:
diff --git a/snapshots/web/queue-actions/preserved.expected.md b/snapshots/web/queue-actions/preserved.expected.md
index a4547ed17d..1fbeabd838 100644
--- a/snapshots/web/queue-actions/preserved.expected.md
+++ b/snapshots/web/queue-actions/preserved.expected.md
@@ -41,7 +41,6 @@
     - text: Edited queue item
     - button "Edit queued message":
       - img
-    - tooltip "Edit queued message"
     - button "Remove queued message":
       - img
     - button "Steer queued message" [disabled]:

From ef8f166ccc4002b708b3faf913659ddde5ba9626 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 17:00:41 +0800
Subject: [PATCH 21/35] test(ci): preserve the lane budget for invariant
 verifier children

---
 .../verify-built-package-invariants.spec.ts   | 28 +++++++++++--------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/scripts/verify-built-package-invariants.spec.ts b/scripts/verify-built-package-invariants.spec.ts
index b01fd45628..6d5739f8ed 100644
--- a/scripts/verify-built-package-invariants.spec.ts
+++ b/scripts/verify-built-package-invariants.spec.ts
@@ -47,52 +47,56 @@ function fixture(options: {
   return { root, loaderUrl: pathToFileURL(loaderPath).href }
 }
 
-function verify(root: string, loaderUrl: string) {
-  return spawnSync(process.execPath, [
+function verify(root: string, loaderUrl: string, timeout: number) {
+  const result = spawnSync(process.execPath, [
     verifier,
     '--packages-root', root,
     '--loader-url', loaderUrl,
   ], {
     encoding: 'utf8',
-    timeout: 5_000,
+    // Plain-Node startup and staged imports share the runner's platform budget.
+    timeout,
   })
+  expect(result.error).toBeUndefined()
+  expect(result.signal, result.stderr).toBeNull()
+  return result
 }
 
 describe('built package invariant verifier', () => {
-  it('loads the staged compiled self-reference through plain Node and Loader normalization', () => {
+  it('loads the staged compiled self-reference through plain Node and Loader normalization', ({ task }) => {
     const { root, loaderUrl } = fixture()
-    const result = verify(root, loaderUrl)
+    const result = verify(root, loaderUrl, task.timeout)
     expect(result.status, result.stderr).toBe(0)
     expect(result.stdout).toContain('1 compiled companion(s) passed plain-Node Loader checks')
   })
 
-  it('accepts packages that do not publish a companion', () => {
+  it('accepts packages that do not publish a companion', ({ task }) => {
     const { root, loaderUrl } = fixture({ companion: false })
-    const result = verify(root, loaderUrl)
+    const result = verify(root, loaderUrl, task.timeout)
     expect(result.status, result.stderr).toBe(0)
     expect(result.stdout).toContain('0 compiled companion(s) passed plain-Node Loader checks')
   })
 
-  it('rejects a default export and a broken invariant export map', () => {
+  it('rejects a default export and a broken invariant export map', ({ task }) => {
     const withDefault = fixture({
       invariantSource: "export default {}\nexport const name = 'probe-invariant'\nexport const inject = ['invariants']\nexport const apply = () => {}\n",
     })
-    const defaultResult = verify(withDefault.root, withDefault.loaderUrl)
+    const defaultResult = verify(withDefault.root, withDefault.loaderUrl, task.timeout)
     expect(defaultResult.status).toBe(1)
     expect(defaultResult.stderr).toContain('companion has a default export')
 
     const brokenExport = fixture({ invariantExport: './lib/missing.js' })
-    const exportResult = verify(brokenExport.root, brokenExport.loaderUrl)
+    const exportResult = verify(brokenExport.root, brokenExport.loaderUrl, task.timeout)
     expect(exportResult.status).toBe(1)
     expect(exportResult.stderr).toContain('@deepseek-ai/dsh-probe')
   })
 
-  it('rejects an invariant bundle that needs an unstaged runtime chunk', () => {
+  it('rejects an invariant bundle that needs an unstaged runtime chunk', ({ task }) => {
     const { root, loaderUrl } = fixture({
       invariantSource: "export * from './chunk.js'\n",
       runtimeChunk: "export const name = 'probe-invariant'\nexport const inject = ['invariants']\nexport const apply = () => {}\n",
     })
-    const result = verify(root, loaderUrl)
+    const result = verify(root, loaderUrl, task.timeout)
     expect(result.status).toBe(1)
     expect(result.stderr).toContain('chunk.js')
   })

From f7c9170b3bf0732dac877f9769dc990788820fb7 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 17:21:13 +0800
Subject: [PATCH 22/35] fix(web): dismiss tooltips when composer actions become
 disabled

---
 apps/web/tests/live-interactions.e2e.ts        |  6 +++++-
 apps/web/tests/queue-actions.e2e.ts            |  8 +++++---
 .../client/ui-conversation/README.i18n.yaml    |  4 ++--
 packages/client/ui-conversation/README.md      |  2 +-
 packages/client/ui-conversation/README.zh.md   |  2 +-
 .../src/client/skeleton/InputBar.tsx           |  8 +++++---
 .../tests/input-bar.client.spec.tsx            | 18 ++++++++++++++++++
 7 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/apps/web/tests/live-interactions.e2e.ts b/apps/web/tests/live-interactions.e2e.ts
index 3f6f192507..a72723de46 100644
--- a/apps/web/tests/live-interactions.e2e.ts
+++ b/apps/web/tests/live-interactions.e2e.ts
@@ -182,7 +182,10 @@ describe('web e2e: live-turn interactions (cancel / error / retry)', () => {
     await queuedRow.getByRole('button', { name: 'Remove queued message' }).click()
     await expect.poll(() => queuedRow.count(), { timeout: 10_000 }).toBe(0)
 
-    await page.getByRole('button', { name: 'Stop generating' }).click()
+    const stopButton = page.getByRole('button', { name: 'Stop generating' })
+    await stopButton.hover()
+    await page.getByRole('tooltip', { name: 'Stop generating', exact: true }).waitFor()
+    await stopButton.click()
     await settled
     expect(turnEndReasons(sessionEvents).at(-1)).toBe('aborted')
     // Composer recovered; no streaming node lingers. The host settled first
@@ -190,6 +193,7 @@ describe('web e2e: live-turn interactions (cancel / error / retry)', () => {
     // frozen-partial swap is eventually consistent, so poll rather than count.
     await expect.poll(() => page.locator('[data-composer-input]').first().isEnabled(), { timeout: 10_000 }).toBe(true)
     await expect.poll(() => page.locator('[data-streaming="true"]').count(), { timeout: 10_000 }).toBe(0)
+    await expect.poll(() => page.getByRole('tooltip').count()).toBe(0)
     // Golden of the aborted end-state: the prompt bubble plus the frozen
     // partial ('partial' is the hang entry's replayed prefix) and no more.
     const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold!.workspaceCwd)
diff --git a/apps/web/tests/queue-actions.e2e.ts b/apps/web/tests/queue-actions.e2e.ts
index e38e6a35fe..65f646187a 100644
--- a/apps/web/tests/queue-actions.e2e.ts
+++ b/apps/web/tests/queue-actions.e2e.ts
@@ -227,15 +227,17 @@ describe('web e2e: queue row actions', () => {
       { timeout: 10_000 },
     ).toBe(2)
 
-    await page.getByRole('button', { name: 'Stop generating' }).click()
+    const stopButton = page.getByRole('button', { name: 'Stop generating' })
+    await stopButton.hover()
+    await page.getByRole('tooltip', { name: 'Stop generating', exact: true }).waitFor()
+    await stopButton.click()
     await firstSettled
     await expect.poll(() => page.getByRole('button', { name: 'Stop generating' }).count())
       .toBe(0)
     await expect.poll(() => page.getByRole('button', { name: 'Remove queued message' }).count())
       .toBe(2)
 
-    // Stop becomes Send under the pointer; capture the idle queue with tooltips dismissed.
-    await page.mouse.move(0, 0)
+    // The disabled Send button must dismiss the active Stop tooltip without mouseleave.
     await expect.poll(() => page.getByRole('tooltip').count()).toBe(0)
     const preservedSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(PRESERVED_EXPECTED, preservedSnapshot, MODE)
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index d93d7d7dc5..79765da08c 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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-conversation/README.md
-README.md: e06270a339a23fa17fb9d51642317fcf2aec6c0f
-README.zh.md: 315fd3d7798145df7dbb6f504fe7b89c64827024
+README.md: 06667e15dd44c4bcaaea9212d52bb0eda8867c6e
+README.zh.md: ce2b183e6fffcf00485856c8eed777368b446ac6
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index e06270a339..06667e15dd 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -48,7 +48,7 @@ Default sends commit optimistically: Enter clears the draft, occurrence table, a
 
 Queued submission echoes show “Sending…” beside disabled edit, remove, and steer buttons; a collapsed dock keeps the sending status in its header. A matching Host queue row replaces the echo and enables each action according to its normal text-content and running-state requirements. Prompt acknowledgement alone does not enable queue actions. A failed submission removes its echo and displays an error; the composer restores the failed draft when it is empty or still contains the previous automatic restoration, preserving subsequently typed text.
 
-While a normal composer is running, its primary pointer action remains Stop when the draft is empty or input is unavailable. Actionable text or attachments switch the same seat to Send; clearing or successfully submitting the draft restores Stop. The busy-Enter setting selects the Queue or Steer delivery for ordinary Sessions and continuable children, and the running Send button delivers through the same mode plain Enter resolves to; while it is enabled (no upload pending) over a plain message draft its label names that mode (Queue message or Steer message), so the setting governs Enter and the button together while Cmd/Ctrl+Enter still uses the other mode, and idle sessions, empty drafts, and `/` command lines keep the plain Send label ([decision](../../../.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.md)). Their QueueDock rows share Edit, Remove, and Steer, and an empty draft shares the steer-all chord. One-shot children remain read-only. Plan mode and active goals do not change attachment intake. Continuable children keep separate Send and Stop actions but expose no paperclip, paste, or drop intake; if their parent is offline, Send and the composer gestures lock while QueueDock controls for the live inbox remain available ([decisions](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md), [inbox controls](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md)).
+Disabled Send and Stop buttons suppress their tooltips, including a Stop button that becomes a disabled Send button when the turn ends. While a normal composer is running, its primary pointer action remains Stop when the draft is empty or input is unavailable. Actionable text or attachments switch the same seat to Send; clearing or successfully submitting the draft restores Stop. The busy-Enter setting selects the Queue or Steer delivery for ordinary Sessions and continuable children, and the running Send button delivers through the same mode plain Enter resolves to; while it is enabled (no upload pending) over a plain message draft its label names that mode (Queue message or Steer message), so the setting governs Enter and the button together while Cmd/Ctrl+Enter still uses the other mode, and idle sessions, empty drafts, and `/` command lines keep the plain Send label ([decision](../../../.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.md)). Their QueueDock rows share Edit, Remove, and Steer, and an empty draft shares the steer-all chord. One-shot children remain read-only. Plan mode and active goals do not change attachment intake. Continuable children keep separate Send and Stop actions but expose no paperclip, paste, or drop intake; if their parent is offline, Send and the composer gestures lock while QueueDock controls for the live inbox remain available ([decisions](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md), [inbox controls](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md)).
 
 <a id="temporary-composer-entries"></a>
 ## Temporary composer entries
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 315fd3d779..ce2b183e6f 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -48,7 +48,7 @@ Session 首次绑定或缓存的 Session 成为 current 时，shell 会在渲染
 
 排队提交的本地回显在禁用的编辑、删除、插话按钮旁显示“发送中…”；折叠后的队列在标题栏保留发送状态。匹配的 Host 队列行替换回显后，各操作按原有的纯文本内容和运行状态要求启用。仅收到 prompt 确认不会启用队列操作。提交失败会移除回显并显示错误；输入框为空或仍保留上一次自动恢复的内容时，composer 恢复失败草稿，保留用户随后输入的文字。
 
-普通 composer 运行时，如果草稿为空或输入不可用，主指针操作保持为 Stop。可提交的文字或附件会把同一位置切换为 Send；清空或成功提交草稿后恢复 Stop。繁忙态 Enter 设置为普通 Session 与可继续 child 选择 Queue 或 Steer 投递，运行中的 Send 按钮按 plain Enter 解析出的同一模式投递；当它在普通消息草稿上可用（没有待上传文件）时，其标签以该模式命名（排队发送或插话发送），因此该设置同时约束 Enter 与按钮，而 Cmd/Ctrl+Enter 仍使用另一模式；空闲会话、空草稿与 `/` 命令行保留普通的 Send 标签（[决策](../../../.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.zh.md)）。它们的 QueueDock 行共享 Edit、Remove 与 Steer，空草稿也共享 steer-all 组合键。One-shot child 继续只读。Plan Mode 与 active goal 不改变附件入口。可继续 child 保留独立的 Send 与 Stop 操作，但不提供回形针、粘贴或拖放入口；parent 离线时，Send 与 composer 手势锁定，但在线 inbox 的 QueueDock 控制仍可使用（[决策](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md)、[inbox 控制](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.zh.md)）。
+Send 和 Stop 按钮禁用时不显示提示气泡，轮次结束后由 Stop 切换成禁用 Send 的按钮也遵循此规则。普通 composer 运行时，如果草稿为空或输入不可用，主指针操作保持为 Stop。可提交的文字或附件会把同一位置切换为 Send；清空或成功提交草稿后恢复 Stop。繁忙态 Enter 设置为普通 Session 与可继续 child 选择 Queue 或 Steer 投递，运行中的 Send 按钮按 plain Enter 解析出的同一模式投递；当它在普通消息草稿上可用（没有待上传文件）时，其标签以该模式命名（排队发送或插话发送），因此该设置同时约束 Enter 与按钮，而 Cmd/Ctrl+Enter 仍使用另一模式；空闲会话、空草稿与 `/` 命令行保留普通的 Send 标签（[决策](../../../.agents/notes/implemented/bug-fix/2026-09-04-busy-send-button-follows-enter-setting.zh.md)）。它们的 QueueDock 行共享 Edit、Remove 与 Steer，空草稿也共享 steer-all 组合键。One-shot child 继续只读。Plan Mode 与 active goal 不改变附件入口。可继续 child 保留独立的 Send 与 Stop 操作，但不提供回形针、粘贴或拖放入口；parent 离线时，Send 与 composer 手势锁定，但在线 inbox 的 QueueDock 控制仍可使用（[决策](../../../.agents/notes/archived/bug-fix/2026-08-20-running-draft-primary-send.md)、[inbox 控制](../../../.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.zh.md)）。
 
 <a id="temporary-composer-entries"></a>
 ## 临时 composer entry
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index aa37b85ecf..3025bbe691 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -344,6 +344,8 @@ export const InputBar = memo(function InputBar({
   // state keeps plain Send. A continuable child keeps Send primary and
   // exposes Stop independently.
   const primaryStops = running && subagent === null && (empty || blocked !== undefined)
+  // Disabled native buttons may omit mouseleave; their tooltip must close from state.
+  const primaryDisabled = primaryStops ? stop === undefined : empty || disabled || machineBusy || uploadsPending
   const interruptible = running && continuable
   const primarySubmitMode = resolveSubmitMode(busyEnter, running, 'enter', steeringAvailable)
   const plainMessageDraft = !empty && input?.phase === 'plain' && !draft.trimStart().startsWith('/')
@@ -526,7 +528,7 @@ export const InputBar = memo(function InputBar({
             {sessionId === undefined ? null : renderSlot('conversation.input.model', { locked: modelSeatLocked })}
             <ContextMeter useProjection={useProjection} t={t} />
             {interruptible && (
-              <Tooltip label={t('input.stop')} side="top" delayMs={500}>
+              <Tooltip label={t('input.stop')} side="top" delayMs={500} disabled={stop === undefined}>
                 <button
                   type="button"
                   className={css.primary}
@@ -541,12 +543,12 @@ export const InputBar = memo(function InputBar({
                 </button>
               </Tooltip>
             )}
-            <Tooltip label={primaryLabel} side="top" delayMs={500}>
+            <Tooltip label={primaryLabel} side="top" delayMs={500} disabled={primaryDisabled}>
               <button
                 type="button"
                 className={css.primary}
                 aria-label={primaryLabel}
-                disabled={primaryStops ? stop === undefined : empty || disabled || machineBusy || uploadsPending}
+                disabled={primaryDisabled}
                 onMouseDown={keepFocus}
                 onClick={onPrimary}
               >
diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
index 15353a765f..051aa295e3 100644
--- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
@@ -738,6 +738,24 @@ describe('Enter semantics', () => {
 })
 
 describe('running and lock semantics', () => {
+  it('dismisses the Stop tooltip when an empty composer becomes idle', () => {
+    vi.useFakeTimers()
+    try {
+      const { button, view, session } = bench({ running: true })
+      fireEvent.mouseEnter(button)
+      act(() => { vi.advanceTimersByTime(500) })
+      expect(view.getByRole('tooltip').textContent).toBe('停止生成')
+
+      // Disabling a hovered native button need not deliver mouseleave.
+      act(() => { session.set(snapshotOf({ running: false })) })
+      expect(button.disabled).toBe(true)
+      expect(button.getAttribute('aria-label')).toBe('发送消息')
+      expect(view.queryByRole('tooltip')).toBeNull()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('running switches the primary between Stop and Queue Send with the draft', async () => {
     const { textarea, button, stop, sink, shell } = bench({ running: true })
     expect(textarea.getAttribute('aria-disabled')).not.toBe('true')

From f7ef7103f38d06edd1fdadcf3febb3fe791fe838 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 17:27:52 +0800
Subject: [PATCH 23/35] test(subagent): await the image capability read before
 draining

---
 .../subagent/tests/continuation.spec.ts       | 47 +++++++++++++------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/packages/subagent/subagent/tests/continuation.spec.ts b/packages/subagent/subagent/tests/continuation.spec.ts
index a99ac93e71..4ca915b77e 100644
--- a/packages/subagent/subagent/tests/continuation.spec.ts
+++ b/packages/subagent/subagent/tests/continuation.spec.ts
@@ -659,17 +659,26 @@ describe('continuable image Queue prompts', () => {
     const started = await ctx.subagents.startContinuable(startSpec(parent))
     await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
     const capability = Promise.withResolvers<{ inputModalities: string[] }>()
-    const resolve = vi.spyOn(ctx.llm, 'resolveModelInfo').mockReturnValue(capability.promise as never)
+    const readingCapability = Promise.withResolvers<undefined>()
+    vi.spyOn(ctx.llm, 'resolveModelInfo').mockImplementation(() => {
+      readingCapability.resolve(undefined)
+      return capability.promise as never
+    })
 
     const delivery = queuePrompt(ctx, parent, started.childId, [imageBlock])
-    delivery.catch(() => undefined)
-    await vi.waitFor(() => { expect(resolve).toHaveBeenCalled() })
-    releaseFirst.resolve(undefined)
-    const draining = drainManager(ctx)
-    capability.resolve({ inputModalities: ['text', 'image'] })
+    try {
+      await Promise.race([readingCapability.promise, delivery])
+      releaseFirst.resolve(undefined)
+      const draining = drainManager(ctx)
+      capability.resolve({ inputModalities: ['text', 'image'] })
 
-    await expect(delivery).rejects.toMatchObject({ code: 'DRAINING' })
-    await draining
+      await expect(delivery).rejects.toMatchObject({ code: 'DRAINING' })
+      await draining
+    } finally {
+      releaseFirst.resolve(undefined)
+      capability.resolve({ inputModalities: ['text', 'image'] })
+      await Promise.allSettled([delivery, drainManager(ctx)])
+    }
   })
 
   it('rejects a materialized image follow-up whose capability read raced a drain', async () => {
@@ -677,16 +686,24 @@ describe('continuable image Queue prompts', () => {
     const started = await ctx.subagents.startContinuable(startSpec(parent))
     await waitNoActivation(ctx, started.childId)
     const capability = Promise.withResolvers<{ inputModalities: string[] }>()
-    const resolve = vi.spyOn(ctx.llm, 'resolveModelInfo').mockReturnValue(capability.promise as never)
+    const readingCapability = Promise.withResolvers<undefined>()
+    vi.spyOn(ctx.llm, 'resolveModelInfo').mockImplementation(() => {
+      readingCapability.resolve(undefined)
+      return capability.promise as never
+    })
 
     const delivery = queuePrompt(ctx, parent, started.childId, [imageBlock])
-    delivery.catch(() => undefined)
-    await vi.waitFor(() => { expect(resolve).toHaveBeenCalled() })
-    const draining = drainManager(ctx)
-    capability.resolve({ inputModalities: ['text', 'image'] })
+    try {
+      await Promise.race([readingCapability.promise, delivery])
+      const draining = drainManager(ctx)
+      capability.resolve({ inputModalities: ['text', 'image'] })
 
-    await expect(delivery).rejects.toMatchObject({ code: 'ACTIVATION_CLOSING' })
-    await draining
+      await expect(delivery).rejects.toMatchObject({ code: 'ACTIVATION_CLOSING' })
+      await draining
+    } finally {
+      capability.resolve({ inputModalities: ['text', 'image'] })
+      await Promise.allSettled([delivery, drainManager(ctx)])
+    }
     const loaded = await loadStoredSession(ctx.sessionPersistence, started.childId)
     expect(loaded.events.some(event => event.type === 'user/message'
       && event.data.content.some(block => block.type === 'image'))).toBe(false)

From 180bdede47fa83dd5aa75134cf975b566ff62cd0 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 17:27:59 +0800
Subject: [PATCH 24/35] fix(test): retain child turn diagnostics when log reads
 time out

---
 .../session-snapshot/README.i18n.yaml         |  4 +--
 .../test-support/session-snapshot/README.md   |  1 +
 .../session-snapshot/README.zh.md             |  1 +
 .../session-snapshot/src/harness.ts           | 27 +++++++++-------
 .../session-snapshot/tests/harness.spec.ts    | 32 +++++++++++++++++++
 5 files changed, 52 insertions(+), 13 deletions(-)

diff --git a/packages/test-support/session-snapshot/README.i18n.yaml b/packages/test-support/session-snapshot/README.i18n.yaml
index 46d058dadf..7653583147 100644
--- a/packages/test-support/session-snapshot/README.i18n.yaml
+++ b/packages/test-support/session-snapshot/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/test-support/session-snapshot/README.md
-README.md: f1126920969cead7844712ad3b2c7213cce19ed9
-README.zh.md: 65e04f252a13c22351b450da2df44f244d484811
+README.md: 6e88270dc3be31b135534097d30fb2b67a37ebde
+README.zh.md: 57cf86dcda198ac939c6e82c56cd3c9c3b473baa
diff --git a/packages/test-support/session-snapshot/README.md b/packages/test-support/session-snapshot/README.md
index f112692096..6e88270dc3 100644
--- a/packages/test-support/session-snapshot/README.md
+++ b/packages/test-support/session-snapshot/README.md
@@ -88,6 +88,7 @@ A scenario requiring a non-Windows host declares `posixOnly`, which skips its ru
 
 ### What can go wrong
 
+- **A child turn wait fails** — `waitForSubagentTurnEnd` identifies the child, requested turn, and deadline even when the first log harvest exceeds that deadline, and retains the underlying failure as the error cause.
 - **A fixture guard rejects the committed files** — orphan scenario dirs, missing files, multiple pins for one header class, duplicate sidecar content, unscrubbed JSONL headers, and malformed pinning headers all fail the suite before comparisons run.
 - **The session harvest needs raw JSONL mode** — snapshot configs set the JSONL backend's `compression: 'none'`; compressed JSONL has no snapshot-harvest path.
 - **Built mode needs current artifacts** — run `pnpm run build` before selecting `DSH_EXAMPLE_MODE=lib`; source mode remains the zero-build path.
diff --git a/packages/test-support/session-snapshot/README.zh.md b/packages/test-support/session-snapshot/README.zh.md
index 65e04f252a..57cf86dcda 100644
--- a/packages/test-support/session-snapshot/README.zh.md
+++ b/packages/test-support/session-snapshot/README.zh.md
@@ -88,6 +88,7 @@ Spill 场景通过真实本地 provider 保存到私有临时根目录。夹具
 
 ### 可能出什么问题
 
+- **子会话轮次等待失败**——即使首次日志收集就超过期限，`waitForSubagentTurnEnd` 也会指出子会话、目标轮次与等待期限，并通过错误的 cause 保留底层失败。
 - **fixture 保护拒绝已提交文件**——遗留场景目录、缺失文件、一个 header 类别包含多个 pin、重复的伴随文件内容、未擦除的 JSONL header 与格式错误的 pin header 都会在比较运行前使套件失败。
 - **会话收集需要原始 JSONL mode**——快照配置使用 JSONL 后端的 `compression: 'none'`；压缩 JSONL 没有快照收集路径。
 - **构建 mode 需要当前产物**——选择 `DSH_EXAMPLE_MODE=lib` 前先运行 `pnpm run build`；源 mode 仍是零构建路径。
diff --git a/packages/test-support/session-snapshot/src/harness.ts b/packages/test-support/session-snapshot/src/harness.ts
index cd54f516ae..691cb1dc8b 100644
--- a/packages/test-support/session-snapshot/src/harness.ts
+++ b/packages/test-support/session-snapshot/src/harness.ts
@@ -67,7 +67,8 @@ const WAIT_POLL_INTERVAL_MS = 10
  * `waitForInboxMessage` waits for inserted inbox text containing a scenario marker.
  * `waitForSubagentTurnEnd` waits until one background child has persisted a
  * closed model-work turn after its own descriptor; child progress has no ACP
- * update to wait on.
+ * update to wait on. Failures identify the child, turn, and deadline even if
+ * the first log read is still pending; the underlying failure is retained as cause.
  * `waitForTitleAfterTurnEnd` additionally waits for a later durable title.
  * `waitForEventAfterTurnEnd` waits until a complete record of the given event
  * type follows the latest closed turn — for scenarios whose asserted state
@@ -608,16 +609,20 @@ async function waitForPersistedChildTurnEnd(
   timeoutMs = DEFAULT_WAIT_TIMEOUT_MS,
   minimumTurn = 1,
 ): Promise<void> {
-  await vi.waitFor(async () => {
-    const log = (await harvestSessionLogs(root))[child]
-    if (log === undefined || !latestTurnIsClosed(log.content)
-      || !hasRequestHeaderAfterDescriptor(log.content)
-      || !hasClosedTurn(log.content, minimumTurn)) {
-      throw new Error(
-        `snapshot-harness: subagent child #${child} did not persist closed turn ${minimumTurn} within ${timeoutMs}ms`,
-      )
-    }
-  }, { interval: WAIT_POLL_INTERVAL_MS, timeout: timeoutMs })
+  const message = `snapshot-harness: subagent child #${child} did not persist closed turn ${minimumTurn} within ${timeoutMs}ms`
+  try {
+    await vi.waitFor(async () => {
+      const log = (await harvestSessionLogs(root))[child]
+      if (log === undefined || !latestTurnIsClosed(log.content)
+        || !hasRequestHeaderAfterDescriptor(log.content)
+        || !hasClosedTurn(log.content, minimumTurn)) {
+        throw new Error(message)
+      }
+    }, { interval: WAIT_POLL_INTERVAL_MS, timeout: timeoutMs })
+  } catch (cause) {
+    // The deadline can precede the first harvest, before the callback names the missing turn.
+    throw new Error(message, { cause })
+  }
 }
 
 /** Whether a raw session log contains the requested closed turn. */
diff --git a/packages/test-support/session-snapshot/tests/harness.spec.ts b/packages/test-support/session-snapshot/tests/harness.spec.ts
index 089b68526c..0a23c326c6 100644
--- a/packages/test-support/session-snapshot/tests/harness.spec.ts
+++ b/packages/test-support/session-snapshot/tests/harness.spec.ts
@@ -1,4 +1,5 @@
 import { mkdir, mkdtemp, readFile, readdir, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import * as fsPromises from 'node:fs/promises'
 import { once } from 'node:events'
 import { tmpdir } from 'node:os'
 import { delimiter, join, relative, sep } from 'node:path'
@@ -984,6 +985,37 @@ describe('runScenario', () => {
     )).rejects.toThrow(/did not persist goal phase "blocked" within 20ms/)
   })
 
+  it('identifies the child wait when its first log harvest outlasts the deadline', async () => {
+    const { fixtureFile } = await scenario({})
+    const reading = Promise.withResolvers<undefined>()
+    const release = Promise.withResolvers<undefined>()
+    let pendingRead: Promise<unknown> | undefined
+    const originalReaddir = readdir
+    const spy = vi.spyOn(fsPromises, 'readdir').mockImplementation(async (...args) => {
+      if (pendingRead === undefined && String(args[0]).includes('acp-snap-sessions-')) {
+        const read = release.promise.then(() => originalReaddir(...args))
+        pendingRead = read
+        reading.resolve(undefined)
+        return await read
+      }
+      return await originalReaddir(...args)
+    })
+    const run = runScenario(
+      { steps: [...boot, { op: 'waitForSubagentTurnEnd', child: 2, timeoutMs: 20 }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    const rejected = expect(run).rejects.toThrow(/subagent child #2 did not persist closed turn 1 within 20ms/)
+    try {
+      await Promise.race([reading.promise, rejected])
+      expect(pendingRead).toBeDefined()
+      await rejected
+    } finally {
+      release.resolve(undefined)
+      await Promise.allSettled([pendingRead, run, rejected])
+      spy.mockRestore()
+    }
+  })
+
   it('waitForSubagentTurnEnd requires a closed child work turn', { timeout: 20_000 }, async () => {
     const closed = await scenario({
       prompt: 'hang-until-cancel',

From 19d87778a1647b209f887b4a111861299b9b67de Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 17:55:48 +0800
Subject: [PATCH 25/35] test(web): hold workflow children through live
 navigation checks

---
 apps/web/tests/workflow-run.e2e.ts | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/apps/web/tests/workflow-run.e2e.ts b/apps/web/tests/workflow-run.e2e.ts
index 08f4c5e193..952c5a34d6 100644
--- a/apps/web/tests/workflow-run.e2e.ts
+++ b/apps/web/tests/workflow-run.e2e.ts
@@ -7,7 +7,7 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
-import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed, onTestFinished } from 'vitest'
 import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import {
   assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
@@ -32,6 +32,7 @@ describe.skipIf(MODE === 'record')('web e2e: durable workflow run in Chat', () =
   let page: Page
   let tripwire: ReturnType<typeof watchConsole>
   let prompt: string
+  const releaseChild = Promise.withResolvers<undefined>()
 
   const waitForParentSettlement = (): Promise<SessionId> => new Promise((resolve, reject) => {
     let dispose = (): void => {}
@@ -53,9 +54,14 @@ describe.skipIf(MODE === 'record')('web e2e: durable workflow run in Chat', () =
     scaffold = await launchWebScaffold({
       replayFixture: PARENT_FIXTURE,
       replayChildFixtures: [CHILD_FIXTURE],
-      paceMs: 50,
       compareReplaySession: false,
     })
+    // Keep the live child available throughout disclosure, layout, and navigation checks.
+    scaffold.ctx.on('llm/stream', async function* (options, next) {
+      const session = options.sessionId === undefined ? undefined : scaffold.ctx.sessions.get(options.sessionId)
+      if (session?.header.origin === 'subagent') await releaseChild.promise
+      yield* next()
+    }, { prepend: true })
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
     tripwire = watchConsole(page)
@@ -65,6 +71,7 @@ describe.skipIf(MODE === 'record')('web e2e: durable workflow run in Chat', () =
   }, 120_000)
 
   afterAll(async () => {
+    releaseChild.resolve(undefined)
     await browser?.close()
     await scaffold?.close()
   })
@@ -72,6 +79,10 @@ describe.skipIf(MODE === 'record')('web e2e: durable workflow run in Chat', () =
   it('shows the live member, opens its local child, then retains the settled record beside the tool row', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-workflow-run-live'))
     const settled = waitForParentSettlement()
+    onTestFinished(async () => {
+      releaseChild.resolve(undefined)
+      await settled
+    })
     const input = page.locator('[data-composer-input]').first()
     await input.fill(prompt)
     await input.press('Enter')
@@ -160,6 +171,7 @@ describe.skipIf(MODE === 'record')('web e2e: durable workflow run in Chat', () =
 
     const sessions = page.getByRole('tree', { name: 'Sessions' })
     await sessions.getByRole('treeitem', { name: /Use the workflow tool exactly/ }).click()
+    releaseChild.resolve(undefined)
     await settled
     await expandTurnProcesses(page)
     await page.locator('[data-workflow-run][data-run-status="completed"]').waitFor()

From 3ec2191246b59a55d560fe80a5f46aa9353d4d75 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 17:55:54 +0800
Subject: [PATCH 26/35] test(web): await feedback submit replies before
 snapshots

---
 apps/web/tests/feedback-command.e2e.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/apps/web/tests/feedback-command.e2e.ts b/apps/web/tests/feedback-command.e2e.ts
index 9e4a7be60e..e531e133a4 100644
--- a/apps/web/tests/feedback-command.e2e.ts
+++ b/apps/web/tests/feedback-command.e2e.ts
@@ -81,6 +81,8 @@ describe('web e2e: /feedback command acknowledgement', () => {
     await input.press('Enter')
     await page.getByText(/Feedback recorded for session/).waitFor({ timeout: 10_000 })
     expect(await page.getByText(/Anonymous user: [0-9a-f-]+\.$/i).count()).toBe(1)
+    await expect.poll(() => input.textContent(), { timeout: 10_000 }).toBe('')
+    await expect.poll(() => page.getByRole('button', { name: 'Add attachment' }).isEnabled(), { timeout: 10_000 }).toBe(true)
     const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(ACK_EXPECTED, snapshot, MODE)
     const expanded = await captureExpandedTurnProcessAria(

From 7627622c7abb1b0c994c67464b39a683a19d1661 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 17:56:00 +0800
Subject: [PATCH 27/35] test(session): await durable cold projection cache
 writes

---
 .../tests/cache.spec.ts                       | 20 +++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/packages/session/session-projection-cache/tests/cache.spec.ts b/packages/session/session-projection-cache/tests/cache.spec.ts
index 9bfd91680d..b38f49eec1 100644
--- a/packages/session/session-projection-cache/tests/cache.spec.ts
+++ b/packages/session/session-projection-cache/tests/cache.spec.ts
@@ -665,6 +665,14 @@ describe('SessionProjectionCache cold-read seeding', () => {
     })
     const { cache, ctx } = await harness({ root })
     const apply = vi.fn((_state: number, _event: SessionEvent) => 1)
+    const whenWritten = (id: SessionId): Promise<void> => new Promise((resolve) => {
+      const dispose = ctx.on('domain/changed', (change) => {
+        if (change.domain !== projectionCacheDomainSpec.name
+          || change.table !== 'sessions' || change.key !== id || change.operation !== 'put') return
+        dispose()
+        resolve()
+      })
+    })
     ctx.sessionProjections.register({
       key: 'cache-test/count',
       stateSchema: z.number().int().nonnegative(),
@@ -676,6 +684,7 @@ describe('SessionProjectionCache cold-read seeding', () => {
     const events = Array.from({ length: 5 }, (_, seq) => ({
       type: 'cache-test/mark', seq: SessionSeq(seq), time: seq, data: { marks: [`m${seq}`] },
     })) as SessionEvent[]
+    const refreshed = whenWritten(meta.id)
     const snapshot = cache.coldSnapshot(meta, SessionLogOffset(0), events)
     // The full log was traversed, but the fold applied only seqs 3 and 4.
     expect(apply).toHaveBeenCalledTimes(2)
@@ -684,17 +693,16 @@ describe('SessionProjectionCache cold-read seeding', () => {
     // Host-only unit: folded but not served; the refreshed row is written
     // back (fail-soft, fire-and-forget) once the write lands.
     expect(Object.keys(snapshot.values)).not.toContain('cache-test/count')
-    await vi.waitFor(async () => {
-      expect((await storedRows(root, meta.id))?.['cache-test/count']?.seq).toBe(4)
-    })
+    await refreshed
+    expect((await storedRows(root, meta.id))?.['cache-test/count']?.seq).toBe(4)
     // No cached row yet: the first cold read folds from init over the full
     // log and creates the cache row (the `?? {}` seed path).
     const fresh = headerOf(SessionId('cold-fresh'), 10)
+    const created = whenWritten(fresh.id)
     cache.coldSnapshot(fresh, SessionLogOffset(0), events)
     expect(apply).toHaveBeenCalledTimes(7) // 2 tail + 5 full
-    await vi.waitFor(async () => {
-      expect((await storedRows(root, fresh.id))?.['cache-test/count']?.seq).toBe(4)
-    })
+    await created
+    expect((await storedRows(root, fresh.id))?.['cache-test/count']?.seq).toBe(4)
   })
 
   it('coldSnapshot write-back is fail-soft: a failed durable write logs and never throws', async () => {

From 0f9d944f98630f0623ef5a8324f811814907d8ee Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 17:57:44 +0800
Subject: [PATCH 28/35] test(worker): account for the dockkit browser CSS entry

---
 .../webworker-runtime/tests/compile/transform-corpus-check.ts    | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/experimental/webworker-runtime/tests/compile/transform-corpus-check.ts b/packages/experimental/webworker-runtime/tests/compile/transform-corpus-check.ts
index 6c041b93c1..1ca7371ad7 100644
--- a/packages/experimental/webworker-runtime/tests/compile/transform-corpus-check.ts
+++ b/packages/experimental/webworker-runtime/tests/compile/transform-corpus-check.ts
@@ -34,6 +34,7 @@ const repositoryRoot = fileURLToPath(new URL('../../../../../', import.meta.url)
  * import re-registers koffi's type names and fails as the second load.
  */
 const BASELINE_EXEMPT: ReadonlyMap<string, string> = new Map([
+  ['packages/client/ui-dockkit/lib/index.js', 'imports .css, which bare Node cannot load'],
   ['packages/client/ui-primitives/lib/index.js', 'imports .css, which bare Node cannot load'],
   ['packages/client/web/lib/index.js', 'imports .css, which bare Node cannot load'],
   ['packages/subprocess/win32-process/lib/index.js', 'koffi type-name collision on a second load'],

From e186c218c0fd903965f0cd8b872b26dd9fb28322 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 18:04:56 +0800
Subject: [PATCH 29/35] test(web): release workflow gates after failed
 submissions

---
 apps/web/tests/workflow-run.e2e.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/apps/web/tests/workflow-run.e2e.ts b/apps/web/tests/workflow-run.e2e.ts
index 952c5a34d6..5001232549 100644
--- a/apps/web/tests/workflow-run.e2e.ts
+++ b/apps/web/tests/workflow-run.e2e.ts
@@ -79,9 +79,8 @@ describe.skipIf(MODE === 'record')('web e2e: durable workflow run in Chat', () =
   it('shows the live member, opens its local child, then retains the settled record beside the tool row', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-workflow-run-live'))
     const settled = waitForParentSettlement()
-    onTestFinished(async () => {
+    onTestFinished(() => {
       releaseChild.resolve(undefined)
-      await settled
     })
     const input = page.locator('[data-composer-input]').first()
     await input.fill(prompt)

From a433eec5e7c3dcc946fa59142c58f9a708cc15f2 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 18:24:32 +0800
Subject: [PATCH 30/35] test(web): await editor credential state before
 snapshots

---
 apps/web/tests/onboarding-deepseek-config.e2e.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts
index ebaec71502..97cf82cd19 100644
--- a/apps/web/tests/onboarding-deepseek-config.e2e.ts
+++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts
@@ -212,6 +212,10 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
     await settings.getByLabel('上下文窗口 3').fill('131072')
     await settings.getByLabel('最大输出 token 数 3').fill('64K')
 
+    await expect.poll(
+      () => settings.getByLabel('API 密钥', { exact: true }).getAttribute('placeholder'),
+      { timeout: 10_000 },
+    ).toBe('已配置——输入新值可替换')
     const modelEditor = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(MODELS_EXPECTED, modelEditor, MODE)
     await settings.getByRole('button', { name: '保存', exact: true }).click()

From b76a6d9963451104695d4fac721eedc16b247c61 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 18:27:12 +0800
Subject: [PATCH 31/35] fix(web): keep animated connection dots hidden on hover

---
 apps/web/tests/lifecycle-chrome.e2e.ts                    | 8 ++++++++
 packages/client/ui-primitives/README.i18n.yaml            | 4 ++--
 packages/client/ui-primitives/README.md                   | 2 +-
 packages/client/ui-primitives/README.zh.md                | 2 +-
 .../ui-primitives/src/ConnectionIndicator.module.css      | 8 ++++----
 5 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index cac81f2bb0..c189c982a7 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -349,6 +349,14 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
       expect(await connecting.innerText()).toMatch(/^Reconnecting\.{1,3}$/)
       const connectingGeometry = await connectionIndicatorGeometry(connecting)
       expect(await connectionIndicatorTextAlignment(connecting)).toBe('left')
+      // Animated dots must remain hidden with their state label during hover.
+      await connecting.evaluate((element) => {
+        for (const animation of element.getAnimations({ subtree: true })) {
+          if (!(animation instanceof CSSAnimation)) continue
+          animation.pause()
+          animation.currentTime = 1_250
+        }
+      })
       await connecting.hover()
       expect(await connecting.innerText()).toBe('Reconnect now')
       expect(await connectionIndicatorGeometry(connecting)).toEqual(connectingGeometry)
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index efbd0c05fc..4bda8cc5f7 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: 5bb645b196ab6c3d73f9efdfc87217a62bc78c4a
-README.zh.md: b534868574d35e9c0794752a286bd11c8abcc00b
+README.md: 18b136c78539d8ba6da3b17239112967faf63602
+README.zh.md: f91435e44a5ca79b245fde3dd025a732d35e54e9
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 5bb645b196..18b136c785 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -64,7 +64,7 @@ Writing your own component in your own package is fine when the need is genuinel
 
 ### Controls and icons
 
-The catalog above lists what each export is for; this section covers the behavior that props alone do not show. The `ic_ds_*` icon set and `FishLogo`/`BrandWordmark` marks fill brand and inline-icon slots. `LinkIcon` draws the leading category glyph for clickable artifact links — globe, folder, code, image, document, or plain paper, all riding `currentColor` — and `classifyLinkPath` derives a file path's category from its extension. `ConnectionIndicator` renders a warning-colored disconnected action, a connecting label whose one-to-three dots advance every 500ms independently of retry timing, or a success-colored recovered status. Every state reserves the widest supplied label and uses fixed icon and text columns, so copy changes do not move or resize the control. Its owner supplies visibility, the recovery hold, localized labels, and the immediate-reconnect callback; the primitive uses no native title tooltip. `useAnchoredPosition` and `useAnchoredMaxHeight` keep floating panels and bottom-anchored overlays clamped to the viewport and following their anchor. `HoverCard` keeps its portaled preview reachable across the anchor gap and can expose a copy button through the `copyText` prop. `Toast` holds for the window its owner names through `holdMs`, because how long a banner has to stay depends on how much there is to read; the same value drives its unmount timer and the stylesheet's fade delay, so the two cannot disagree. `rankByName` is the `/` menu's shared candidate ranker for the command and skill sources: the query must be a case-insensitive ordered subsequence of the name; prefix hits rank first, then alignment score, then source order.
+The catalog above lists what each export is for; this section covers the behavior that props alone do not show. The `ic_ds_*` icon set and `FishLogo`/`BrandWordmark` marks fill brand and inline-icon slots. `LinkIcon` draws the leading category glyph for clickable artifact links — globe, folder, code, image, document, or plain paper, all riding `currentColor` — and `classifyLinkPath` derives a file path's category from its extension. `ConnectionIndicator` renders a warning-colored disconnected action, a connecting label whose one-to-three dots advance every 500ms independently of retry timing, or a success-colored recovered status. Hover or keyboard focus shows only the reconnect action label, including while the connecting dots animate. Every state reserves the widest supplied label and uses fixed icon and text columns, so copy changes do not move or resize the control. Its owner supplies visibility, the recovery hold, localized labels, and the immediate-reconnect callback; the primitive uses no native title tooltip. `useAnchoredPosition` and `useAnchoredMaxHeight` keep floating panels and bottom-anchored overlays clamped to the viewport and following their anchor. `HoverCard` keeps its portaled preview reachable across the anchor gap and can expose a copy button through the `copyText` prop. `Toast` holds for the window its owner names through `holdMs`, because how long a banner has to stay depends on how much there is to read; the same value drives its unmount timer and the stylesheet's fade delay, so the two cannot disagree. `rankByName` is the `/` menu's shared candidate ranker for the command and skill sources: the query must be a case-insensitive ordered subsequence of the name; prefix hits rank first, then alignment score, then source order.
 
 ### Rendering agent output
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index b534868574..f91435e44a 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -64,7 +64,7 @@ kind: "package-library"
 
 ### 控件与图标
 
-上面的目录说明每个导出的用途；本节讲 props 本身看不出来的行为。`ic_ds_*` 图标集与 `FishLogo`/`BrandWordmark` 标记填充品牌与行内图标 slot。`LinkIcon` 为可点击产物链接绘制前置分类图形——地球、文件夹、代码、图片、文档或纸张，全部随 `currentColor`——`classifyLinkPath` 按扩展名推导文件路径的类别。`ConnectionIndicator` 可渲染警告色的断联操作、以独立于 retry 时序的 500ms 节奏推进一至三个点的连接中状态，或成功色的恢复状态。所有状态都为最长的输入 label 预留空间，并使用固定的图标列和文字列，因此文案变化不会移动控件或改变其宽度。它的 owner 提供可见性、恢复驻留时间、本地化 label 与立即重连回调；该原语不使用原生 title tooltip。`useAnchoredPosition` 与 `useAnchoredMaxHeight` 让浮动面板与底部锚定浮层始终钳制在视口内并跟随锚点。`HoverCard` 通过指针离开宽限期让采用 portal 的预览在跨过锚点间隙时仍可触及，并可通过 `copyText` prop 提供复制按钮。 `Toast` 的停留时长由使用方通过 `holdMs` 指定，因为横幅该留多久取决于有多少内容要读；同一个值同时驱动它的卸载定时器与样式表的淡出延迟，两者不可能再错位。 `rankByName` 是 `/` 菜单命令源与 skill 源共享的候选排序器：查询必须是名字的不区分大小写的有序子序列；前缀命中排最前，其次按对齐分数，再按来源顺序。
+上面的目录说明每个导出的用途；本节讲 props 本身看不出来的行为。`ic_ds_*` 图标集与 `FishLogo`/`BrandWordmark` 标记填充品牌与行内图标 slot。`LinkIcon` 为可点击产物链接绘制前置分类图形——地球、文件夹、代码、图片、文档或纸张，全部随 `currentColor`——`classifyLinkPath` 按扩展名推导文件路径的类别。`ConnectionIndicator` 可渲染警告色的断联操作、以独立于 retry 时序的 500ms 节奏推进一至三个点的连接中状态，或成功色的恢复状态。悬停或键盘聚焦时只显示重连操作文案，连接中的圆点动画也保持隐藏。所有状态都为最长的输入 label 预留空间，并使用固定的图标列和文字列，因此文案变化不会移动控件或改变其宽度。它的 owner 提供可见性、恢复驻留时间、本地化 label 与立即重连回调；该原语不使用原生 title tooltip。`useAnchoredPosition` 与 `useAnchoredMaxHeight` 让浮动面板与底部锚定浮层始终钳制在视口内并跟随锚点。`HoverCard` 通过指针离开宽限期让采用 portal 的预览在跨过锚点间隙时仍可触及，并可通过 `copyText` prop 提供复制按钮。 `Toast` 的停留时长由使用方通过 `holdMs` 指定，因为横幅该留多久取决于有多少内容要读；同一个值同时驱动它的卸载定时器与样式表的淡出延迟，两者不可能再错位。 `rankByName` 是 `/` 菜单命令源与 skill 源共享的候选排序器：查询必须是名字的不区分大小写的有序子序列；前缀命中排最前，其次按对齐分数，再按来源顺序。
 
 ### 渲染 agent 输出
 
diff --git a/packages/client/ui-primitives/src/ConnectionIndicator.module.css b/packages/client/ui-primitives/src/ConnectionIndicator.module.css
index 9fe904c712..bf0e653740 100644
--- a/packages/client/ui-primitives/src/ConnectionIndicator.module.css
+++ b/packages/client/ui-primitives/src/ConnectionIndicator.module.css
@@ -90,13 +90,13 @@
 }
 
 @keyframes reveal-second-dot {
-  0%, 33.32% { visibility: hidden; }
-  33.33%, 100% { visibility: visible; }
+  0%, 33.32% { opacity: 0; }
+  33.33%, 100% { opacity: 1; }
 }
 
 @keyframes reveal-third-dot {
-  0%, 66.65% { visibility: hidden; }
-  66.66%, 100% { visibility: visible; }
+  0%, 66.65% { opacity: 0; }
+  66.66%, 100% { opacity: 1; }
 }
 
 @media (prefers-reduced-motion: reduce) {

From 71e96aebae6518ad6ebe97ccfc65b93629e15ff5 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 18:56:50 +0800
Subject: [PATCH 32/35] test(subagent): preserve ACP readiness budgets and
 teardown ownership

---
 .../subagent-acp/tests/subagent-acp.spec.ts   | 68 ++++++++++++-------
 1 file changed, 43 insertions(+), 25 deletions(-)

diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
index caf75f0308..d88856a13e 100644
--- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
@@ -74,9 +74,10 @@ function expectedPermission(policy: 'allow' | 'reject', requestKind: string, dec
  * Poll until `file` exists (the mock touches it once its prompt is in flight),
  * so a cancel test waits on a CONDITION rather than an arbitrary timeout — the
  * subprocess cold-start is variable, and a fixed sleep both flakes and
- * slows the suite. Fails loud if the child never signals readiness.
+ * slows the suite. The caller supplies its effective test budget so child
+ * startup retains the lane's allowance under concurrent coverage.
  */
-async function waitForFile(file: string, timeoutMs = 5000): Promise<void> {
+async function waitForFile(file: string, timeoutMs: number): Promise<void> {
   const deadline = Date.now() + timeoutMs
   while (!existsSync(file)) {
     if (Date.now() > deadline) throw new Error(`mock child never became ready (${file})`)
@@ -724,7 +725,7 @@ describe('dsh-subagent-acp', () => {
     await run.dispose()
   })
 
-  it('aborting the required signal cancels a running child', async () => {
+  it('aborting the required signal cancels a running child', async ({ task }) => {
     const tmp = mkdtempSync(join(tmpdir(), 'acp-cancel-'))
     const readyFile = join(tmp, 'ready')
     try {
@@ -733,7 +734,7 @@ describe('dsh-subagent-acp', () => {
       const run = await ctx.subagents.start('acp', request('p', controller.signal))
       // Wait until the child's prompt is in flight (condition, not a sleep),
       // then cancel — so we exercise the mid-run session/cancel path.
-      await waitForFile(readyFile)
+      await waitForFile(readyFile, task.timeout)
       controller.abort('test')
       const result = await run.result
       expect(result.stopReason).toBe('aborted')
@@ -900,7 +901,7 @@ describe('dsh-subagent-acp', () => {
     await realChild?.done
   })
 
-  it('reports only the safe teardown failure when cancelled startup rollback fails', async () => {
+  it('reports only the safe teardown failure when cancelled startup rollback fails', async ({ task }) => {
     const tmp = mkdtempSync(join(tmpdir(), 'acp-cancelled-rollback-'))
     const ready = join(tmp, 'ready')
     const go = join(tmp, 'go')
@@ -923,7 +924,7 @@ describe('dsh-subagent-acp', () => {
         },
         onError: (error) => { errors.push(error.message) },
       })
-      await waitForFile(ready)
+      await waitForFile(ready, task.timeout)
       controller.abort()
       writeFileSync(go, 'go')
       const error = await starting.catch((cause: unknown) => cause)
@@ -940,7 +941,7 @@ describe('dsh-subagent-acp', () => {
     }
   })
 
-  it('dispose escalates SIGTERM → SIGKILL for a child that traps SIGTERM (bounded quiescence)', async () => {
+  it('dispose escalates SIGTERM → SIGKILL for a child that traps SIGTERM (bounded quiescence)', async ({ task }) => {
     // The child traps SIGTERM and keeps its event loop alive, so a graceful
     // term alone would hang dispose forever. With a short grace, dispose must
     // escalate to SIGKILL and return once the process is actually gone.
@@ -964,7 +965,7 @@ describe('dsh-subagent-acp', () => {
       // Wait until the child has BOOTED AND ARMED THE TRAP (a condition, not a
       // sleep) — otherwise SIGTERM races the trap install and the default handler
       // terminates the child, never exercising the escalation.
-      await waitForFile(ready)
+      await waitForFile(ready, task.timeout)
       // Don't await result (the child hangs). Dispose must still return promptly
       // via the SIGKILL escalation — bound it so a regression (no escalation)
       // fails loud instead of hanging the suite.
@@ -977,7 +978,7 @@ describe('dsh-subagent-acp', () => {
     }
   })
 
-  it('dispose gives the child an EOF window that outlasts the SIGTERM grace (graceful flush)', async () => {
+  it('dispose gives the child an EOF window that outlasts the SIGTERM grace (graceful flush)', async ({ task }) => {
     // The real acp-agent flushes ASYNCHRONOUSLY on stdin EOF (its bridge tears
     // down on connection close, NOT on a signal) — and it has no SIGTERM handler.
     // Its EOF teardown can itself await a signal-trapping grandchild (a bash
@@ -1011,7 +1012,7 @@ describe('dsh-subagent-acp', () => {
       const run = await startAcpRun(request(), spec)
       // Wait until the child is fully booted with its prompt in flight (its ACP
       // stdin reader is attached), so dispose's stdin EOF reaches a live child.
-      await waitForFile(ready)
+      await waitForFile(ready, task.timeout)
       await run.dispose()
       // dispose returned via the natural-exit tier — the EOF-driven flush landed
       // despite taking longer than the SIGTERM grace.
@@ -1021,7 +1022,7 @@ describe('dsh-subagent-acp', () => {
     }
   })
 
-  it('terminates a child that ignores EOF using the host platform semantics', async () => {
+  it('terminates a child that ignores EOF using the host platform semantics', async ({ task }) => {
     // POSIX uses the catchable SIGTERM tier and records the marker. Windows has
     // no distinct graceful signal, so disposal skips directly to forced exit.
     const tmp = mkdtempSync(join(tmpdir(), 'acp-ignore-eof-'))
@@ -1048,7 +1049,7 @@ describe('dsh-subagent-acp', () => {
         },
       }
       run = await startAcpRun(request(), spec)
-      await waitForFile(ready)
+      await waitForFile(ready, task.timeout)
       await run.dispose()
       const outcome = await child!.done
       expect(outcome.signal).toBeNull()
@@ -1071,7 +1072,7 @@ describe('dsh-subagent-acp', () => {
     }
   })
 
-  it('rejects after cleanup when the signal aborts during newSession', async () => {
+  it('rejects after cleanup when the signal aborts during newSession', async ({ task }) => {
     // Gate the child at newSession: it signals `ready` and blocks until `go`.
     // We cancel WHILE newSession is pending (sessionId still undefined, so the
     // backend cannot send session/cancel) — the `cancelled` flag alone must
@@ -1083,23 +1084,40 @@ describe('dsh-subagent-acp', () => {
       const ctx = await setup({ MOCK_NEWSESSION_READY: ready, MOCK_NEWSESSION_GO: go, MOCK_TEXT: 'should not run' })
       const controller = new AbortController()
       const starting = ctx.subagents.start('acp', request('p', controller.signal))
-      await waitForFile(ready) // newSession is now in flight, sessionId undefined
-      controller.abort('early')
-      writeFileSync(go, 'go') // let newSession resolve
-      await expect(starting).rejects.toThrow('aborted before the ACP child started')
+      // Observe rejection before readiness; cleanup still owns an unpublished
+      // child if readiness or an assertion fails.
+      const settled = starting.then(
+        run => ({ kind: 'started' as const, run }),
+        (error: unknown) => ({ kind: 'failed' as const, error }),
+      )
+      try {
+        await waitForFile(ready, task.timeout) // newSession is now in flight, sessionId undefined
+        controller.abort('early')
+        writeFileSync(go, 'go') // let newSession resolve
+        await expect(starting).rejects.toThrow('aborted before the ACP child started')
+      } finally {
+        controller.abort('test cleanup')
+        writeFileSync(go, 'go')
+        try {
+          const outcome = await settled
+          if (outcome.kind === 'started') await outcome.run.dispose()
+        } finally {
+          await ctx.fiber.dispose()
+        }
+      }
     } finally {
       rmSync(tmp, { recursive: true, force: true })
     }
   })
 
-  it('bridges the request signal to a session/cancel mid-run', async () => {
+  it('bridges the request signal to a session/cancel mid-run', async ({ task }) => {
     const tmp = mkdtempSync(join(tmpdir(), 'acp-signal-'))
     const readyFile = join(tmp, 'ready')
     try {
       const controller = new AbortController()
       const ctx = await setup({ MOCK_TEXT: 'partial', MOCK_HANG: '1', MOCK_READY_FILE: readyFile })
       const run = await ctx.subagents.start('acp', request('p', controller.signal))
-      await waitForFile(readyFile)
+      await waitForFile(readyFile, task.timeout)
       controller.abort()
       const result = await run.result
       expect(result.stopReason).toBe('aborted')
@@ -1357,7 +1375,7 @@ describe('dsh-subagent-acp', () => {
     expect(errors).toEqual([rawMessage])
   })
 
-  it.skipIf(process.platform === 'win32')('plugin-config dispose graces reach the run (SIGKILL escalation through the provider)', async () => {
+  it.skipIf(process.platform === 'win32')('plugin-config dispose graces reach the run (SIGKILL escalation through the provider)', async ({ task }) => {
     // Same trap scenario as the direct startAcpRun escalation test, but the
     // graces arrive via the PLUGIN CONFIG through the registered provider — so a
     // regression that stops threading config into AcpRunSpec (falling back to
@@ -1379,7 +1397,7 @@ describe('dsh-subagent-acp', () => {
         disposeGraceMs: 150,
       })
       const run = await ctx.subagents.start('acp', request())
-      await waitForFile(ready)
+      await waitForFile(ready, task.timeout)
       await expect(Promise.race([
         run.dispose(),
         new Promise((_r, reject) => { setTimeout(() => { reject(new Error('dispose did not return — config graces not threaded to the run')) }, 4000) }),
@@ -1587,7 +1605,7 @@ describe('dsh-subagent-acp', () => {
     await run.dispose()
   })
 
-  it('settles aborted when the child crashes (tears the pipe) AFTER a cancel', async () => {
+  it('settles aborted when the child crashes (tears the pipe) AFTER a cancel', async ({ task }) => {
     // The child hangs, we cancel, and instead of answering the child exits hard
     // — the pending prompt RPC rejects. With a cancel already requested, the
     // backend's catch path must settle `aborted` (the failure is the cancel
@@ -1598,7 +1616,7 @@ describe('dsh-subagent-acp', () => {
       const ctx = await setup({ MOCK_TEXT: 'partial', MOCK_HANG: '1', MOCK_CRASH_ON_CANCEL: '1', MOCK_READY_FILE: ready })
       const controller = new AbortController()
       const run = await ctx.subagents.start('acp', request('p', controller.signal))
-      await waitForFile(ready)
+      await waitForFile(ready, task.timeout)
       controller.abort('crash it')
       const result = await run.result
       expect(result.stopReason).toBe('aborted')
@@ -1609,7 +1627,7 @@ describe('dsh-subagent-acp', () => {
     }
   })
 
-  it('settles aborted on signal even when the child IGNORES session/cancel', async () => {
+  it('settles aborted on signal even when the child IGNORES session/cancel', async ({ task }) => {
     // The signal contract requires `result` to settle `aborted`. A child that hangs
     // its prompt AND ignores session/cancel must not wedge the parent — the
     // backend's own cancel-settle path resolves `aborted` without the child's
@@ -1620,7 +1638,7 @@ describe('dsh-subagent-acp', () => {
       const ctx = await setup({ MOCK_TEXT: 'partial', MOCK_HANG: '1', MOCK_IGNORE_CANCEL: '1', MOCK_READY_FILE: ready })
       const controller = new AbortController()
       const run = await ctx.subagents.start('acp', request('p', controller.signal))
-      await waitForFile(ready)
+      await waitForFile(ready, task.timeout)
       controller.abort('test')
       // Bound it: a regression (cancel only notifies the child, which ignores it)
       // would hang result forever — fail loud instead of stalling the suite.

From 939e6907da3b95db17d28f85d7d953e0ec6d2499 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 18:59:04 +0800
Subject: [PATCH 33/35] test(shell): gate consuming PowerShell reads on parent
 acknowledgement

---
 .../shell/pwsh-local/tests/executor.spec.ts   | 45 ++++++++++++-------
 1 file changed, 29 insertions(+), 16 deletions(-)

diff --git a/packages/shell/pwsh-local/tests/executor.spec.ts b/packages/shell/pwsh-local/tests/executor.spec.ts
index f46fd1f4a2..f4dc5b6df6 100644
--- a/packages/shell/pwsh-local/tests/executor.spec.ts
+++ b/packages/shell/pwsh-local/tests/executor.spec.ts
@@ -13,7 +13,7 @@ import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSyn
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { afterAll, afterEach, describe, expect, it } from 'vitest'
+import { afterAll, afterEach, describe, expect, it, onTestFinished } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { PwshLocalExecutor, ENCODING_PREAMBLE, candidatePwshPaths, resolvePwshPath } from '@deepseek-ai/dsh-pwsh-local'
 import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local'
@@ -64,15 +64,13 @@ async function setup(config: ConstructorParameters<typeof PwshLocalExecutor>[1]
  * `expected`; returns the accumulation (reads never re-deliver, so the caller
  * gets everything produced up to the match).
  */
-async function readUntil(proc: ShellProcess, expected: string, timeoutMs = 5_000): Promise<string> {
-  const deadline = Date.now() + timeoutMs
+async function readUntil(proc: ShellProcess, expected: string, timeoutMs: number): Promise<string> {
   let all = ''
-  while (Date.now() < deadline) {
+  await expect.poll(() => {
     all += proc.readOutput().delta
-    if (lf(all).includes(expected)) return lf(all)
-    await new Promise(resolve => setTimeout(resolve, 20))
-  }
-  throw new Error(`process output did not include ${JSON.stringify(expected)}; accumulated ${JSON.stringify(lf(all))}`)
+    return lf(all)
+  }, { timeout: timeoutMs }).toContain(expected)
+  return lf(all)
 }
 
 describe('resolvePwshPath and candidatePwshPaths (pure, every platform)', () => {
@@ -414,7 +412,7 @@ describe.skipIf(!hasPwsh)('PwshLocalExecutor.start (background process handles)'
     expect(proc.exitCode).toBe(0)
   })
 
-  it('threads stdin and extra env into a background process', async () => {
+  it('threads stdin and extra env into a background process', async ({ task }) => {
     const { bash } = await setup()
     const proc = bash.start(bash.resolve({
       command: '$s = ([Console]::In.ReadToEnd()).TrimEnd(); Write-Output $s; Write-Output "[$env:BG_VAR][$env:DSH_BG_VAR]"',
@@ -422,19 +420,34 @@ describe.skipIf(!hasPwsh)('PwshLocalExecutor.start (background process handles)'
       env: { BG_VAR: 'bg-env' },
       dshEnv: { DSH_BG_VAR: 'bg-dsh-env' },
     }))
-    const partialOutput = await readUntil(proc, '[bg-env][bg-dsh-env]')
+    const partialOutput = await readUntil(proc, '[bg-env][bg-dsh-env]', task.timeout)
     await proc.done
     const output = partialOutput + lf(proc.readOutput().delta)
     expect(output).toBe('bg-stdin\n[bg-env][bg-dsh-env]\n')
     expect(proc.exitCode).toBe(0)
   })
 
-  it('readOutput is consuming: increments are never re-delivered, and reads stay valid after exit', async () => {
-    const { bash } = await setup()
-    const proc = bash.start(bash.resolve({ command: 'Write-Output first; Start-Sleep -Seconds 1; Write-Output second' }))
-    const first = await readUntil(proc, 'first\n')
+  it('readOutput is consuming: increments are never re-delivered, and reads stay valid after exit', async ({ task }) => {
+    const { ctx, bash } = await setup()
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-pwsh-read-'))
+    onTestFinished(async () => {
+      await ctx.fiber.dispose()
+      rmSync(dir, { recursive: true, force: true })
+    })
+    const releasePath = join(dir, 'release')
+    // The second write cannot race the host's first consuming read.
+    const proc = bash.start(bash.resolve({
+      command: 'Write-Output first; [Console]::Out.Flush(); while (-not [System.IO.File]::Exists($env:DSH_PWSH_RELEASE)) { Start-Sleep -Milliseconds 20 }; Write-Output second',
+      env: { DSH_PWSH_RELEASE: releasePath },
+    }))
+    const first = await readUntil(proc, 'first\n', task.timeout)
     expect(lf(first)).toBe('first\n')
+    expect(proc.status).toBe('running')
+    expect(proc.readOutput().delta).toBe('')
+    writeFileSync(releasePath, '')
     await proc.done
+    expect(proc.status).toBe('completed')
+    expect(proc.exitCode).toBe(0)
     // Read-after-exit returns the remaining buffered output — once.
     const second = proc.readOutput()
     expect(lf(second.delta)).toBe('second\n')
@@ -530,7 +543,7 @@ describe.skipIf(!hasPwsh)('PwshLocalExecutor.start (background process handles)'
 })
 
 describe.skipIf(!hasPwsh)('process lifecycle ownership (the subprocess service, not the executor)', () => {
-  it('a background process survives executor-fiber disposal and dies with the subprocess service', async () => {
+  it('a background process survives executor-fiber disposal and dies with the subprocess service', async ({ task }) => {
     const ctx = new Context()
     const managerFiber = await ctx.plugin(LocalSubprocessRuntime)
     ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir }
@@ -540,7 +553,7 @@ describe.skipIf(!hasPwsh)('process lifecycle ownership (the subprocess service,
     // The child prints its own pid so the test can probe liveness through the
     // public read surface alone.
     const proc = bash.start(bash.resolve({ command: 'Write-Output $PID; Start-Sleep -Seconds 60' }))
-    const pid = Number((await readUntil(proc, '\n')).trim())
+    const pid = Number((await readUntil(proc, '\n', task.timeout)).trim())
     expect(Number.isInteger(pid) && pid > 0).toBe(true)
 
     // Executor reload/disposal leaves background work running — the

From 404097f813e8f7062896f8692ca8bfd4f8d844a1 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 18:59:11 +0800
Subject: [PATCH 34/35] test(subagent): reap SDK startup before readiness
 fixture cleanup

---
 .../tests/subagent-dsh-sdk.spec.ts            | 32 +++++++++++++------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
index aab61bdfd6..b9fa8c55c0 100644
--- a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
+++ b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
@@ -8,7 +8,7 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -113,9 +113,9 @@ function expectedFailure(fields: string): string {
 /**
  * Poll until `file` exists (the fake touches it once the probed state is
  * reached), so cancel tests wait on a CONDITION rather than an arbitrary
- * timeout. Fails loud if the child never signals readiness.
+ * timeout. The caller supplies the lane's effective test budget.
  */
-async function waitForFile(file: string, timeoutMs = 5000): Promise<void> {
+async function waitForFile(file: string, timeoutMs: number): Promise<void> {
   const deadline = Date.now() + timeoutMs
   while (!existsSync(file)) {
     if (Date.now() > deadline) throw new Error(`fake runtime never became ready (${file})`)
@@ -524,7 +524,7 @@ describe('dsh-subagent-dsh-sdk provider', () => {
     await ctx.fiber.dispose()
   })
 
-  it('cancelling between handshake and publish rejects start after reap', async () => {
+  it('cancelling between handshake and publish rejects start after reap', async ({ task }) => {
     // The abort lands while the child is INSIDE initialize (ready-file
     // handshake window): the fake touches READY, we abort, then GO lets the
     // handshake complete — so the post-race `flags.cancelled` recheck must
@@ -532,6 +532,8 @@ describe('dsh-subagent-dsh-sdk provider', () => {
     const tmp = mkdtempSync(join(tmpdir(), 'subagent-dsh-sdk-midcancel-'))
     const ready = join(tmp, 'ready')
     const go = join(tmp, 'go')
+    const createHarness = runInternals.createHarness.bind(runInternals)
+    runInternals.createHarness = options => createHarness({ ...options, initializeTimeoutMs: task.timeout })
     try {
       const controller = new AbortController()
       const spec: SdkRunSpec = {
@@ -547,12 +549,24 @@ describe('dsh-subagent-dsh-sdk provider', () => {
         disposeGraceMs: 200,
       }
       const pending = startSdkRun(request('p', controller.signal), spec)
-      await waitForFile(ready)
-      controller.abort('mid-handshake')
-      const { writeFileSync } = await import('node:fs')
-      writeFileSync(go, 'go\n')
-      await expect(pending).rejects.toThrow('aborted before the SDK child started')
+      // Observe failed startup while readiness is pending; rollback owns the child.
+      const settled = pending.then(
+        run => ({ kind: 'started' as const, run }),
+        (error: unknown) => ({ kind: 'failed' as const, error }),
+      )
+      try {
+        await waitForFile(ready, task.timeout)
+        controller.abort('mid-handshake')
+        writeFileSync(go, 'go\n')
+        await expect(pending).rejects.toThrow('aborted before the SDK child started')
+      } finally {
+        controller.abort('test cleanup')
+        writeFileSync(go, 'go\n')
+        const outcome = await settled
+        if (outcome.kind === 'started') await outcome.run.dispose()
+      }
     } finally {
+      runInternals.createHarness = createHarness
       rmSync(tmp, { recursive: true, force: true })
     }
   })

From 44008a79cae91552cbbb0830156a3c0eed01877b Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Tue, 8 Sep 2026 19:22:33 +0800
Subject: [PATCH 35/35] test(team): await mailbox acknowledgement flushes
 before teardown

---
 .../agent-team/tests/persistence.spec.ts      | 53 ++++++++++++++++---
 1 file changed, 45 insertions(+), 8 deletions(-)

diff --git a/packages/experimental/agent-team/tests/persistence.spec.ts b/packages/experimental/agent-team/tests/persistence.spec.ts
index 6ff838ddf0..5237fc0301 100644
--- a/packages/experimental/agent-team/tests/persistence.spec.ts
+++ b/packages/experimental/agent-team/tests/persistence.spec.ts
@@ -4,7 +4,7 @@ import { rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
@@ -14,6 +14,7 @@ import SubagentService, { snapshotSubagentDescriptor } from '@deepseek-ai/dsh-su
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn-in-process'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import TeamService, { TeamId, TeamMessageId } from '../src/index.ts'
+import type { TeamMailbox } from '../src/mailbox.ts'
 import { teamProjectionDefinition } from '../src/projection.ts'
 import type { TeamMemberSnapshot, TeamMessageSnapshot, TeamTaskSnapshot } from '../src/index.ts'
 import { TestSessionQuery } from './test-session-query.ts'
@@ -50,6 +51,12 @@ async function storedEvents(ctx: Context, id: SessionId): Promise<readonly Sessi
   }
 }
 
+/** Await mailbox acknowledgements through their flush and dispatch completion. */
+async function settleMailbox(ctx: Context): Promise<void> {
+  const { mailbox } = ctx.agentTeams as unknown as { readonly mailbox: TeamMailbox }
+  await Promise.all(mailbox.pendingDispatches())
+}
+
 async function disposeContext(ctx: Context): Promise<void> {
   try {
     await ctx.fiber.dispose()
@@ -360,9 +367,8 @@ for (const backend of backends) {
         },
       }), { surfaceOp: 'append' })
       await first.ctx.sessions.flush(targetHandle.agent.session)
-      // Let the pre-queue acknowledgement observer prove there is no mailbox
-      // row yet before authoring the simulated crash prefix below.
-      await new Promise<void>((resolve) => { setTimeout(resolve, 0) })
+      // Finish the target observer before writing the crash-only queued prefix.
+      await settleMailbox(first.ctx)
       await targetHandle.dispose()
 
       const queued: TeamMessageSnapshot = {
@@ -382,11 +388,41 @@ for (const backend of backends) {
       await first.dispose()
 
       const second = await stack(backend, storageRoot, [])
-      const rootHandle = await second.ctx.agents.resume({
-        resumeSessionId: rootId,
-        agentOptions: { provider: 'mock', model: 'mock' },
+      const { mailbox } = second.ctx.agentTeams as unknown as { readonly mailbox: TeamMailbox }
+      const flush = second.ctx.sessions.flush.bind(second.ctx.sessions)
+      const checkpointEntered = Promise.withResolvers<undefined>()
+      const releaseCheckpoint = Promise.withResolvers<undefined>()
+      const delayedCheckpoint = vi.spyOn(second.ctx.sessions, 'flush').mockImplementation(async (session) => {
+        if (session.id === rootId && session.snapshotEvents().some(event =>
+          event.type === 'team/message/delivered' && event.data.messageId === messageId)) {
+          checkpointEntered.resolve(undefined)
+          await releaseCheckpoint.promise
+        }
+        return await flush(session)
       })
-      await vi.waitFor(() => { expect(durable(rootHandle.agent).pendingMessages).toEqual([]) })
+      let rootHandle: AgentHandle
+      try {
+        rootHandle = await second.ctx.agents.resume({
+          resumeSessionId: rootId,
+          agentOptions: { provider: 'mock', model: 'mock' },
+        })
+        await checkpointEntered.promise
+        expect(durable(rootHandle.agent).pendingMessages).toEqual([])
+        expect(mailbox.pendingDispatches().length).toBeGreaterThan(0)
+        let settled = false
+        const settlement = settleMailbox(second.ctx).then(() => { settled = true })
+        await Promise.resolve()
+        expect(settled).toBe(false)
+        releaseCheckpoint.resolve(undefined)
+        await settlement
+      } finally {
+        releaseCheckpoint.resolve(undefined)
+        try {
+          await settleMailbox(second.ctx)
+        } finally {
+          delayedCheckpoint.mockRestore()
+        }
+      }
       expect(second.ctx.agents.get(started.member.id)).toBeUndefined()
       expect(second.adapter.requests).toEqual([])
 
@@ -461,6 +497,7 @@ for (const backend of backends) {
       await vi.waitFor(() => {
         expect(durable(rootHandle.agent).pendingMessages).toEqual([])
       })
+      await settleMailbox(second.ctx)
       expect(second.adapter.requests).toEqual([])
       expect(second.ctx.agents.get(childId)).toBeUndefined()
       const stored = await storedEvents(second.ctx, childId)