@khorsheed/dsh-file-preview 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 变更记录
 
+## 0.2.0（2026-09-10）
+
+适配宿主 0.1.2 线。
+
+- **BREAKING**：minHost 前移至 `0.1.2-rc.1`；宿主 `0.1.0-rc.6` ~ `0.1.1-rc.2` 的用户请停留在 0.1.x 线（末版 `0.1.1`）
+- 会话事件读取走 `Session.snapshotEvents()`（`session.events` 已随宿主移除）
+- 嵌套 dispatch 事件按名探测（feature detection，非版本判断）：同时识别 Code Mode 的 `tool/code-dispatch` 与 PTC 更名后的 `tool/ptc-dispatch`
+
+## 0.1.1（2026-08-23）
+
+- 修复：随包 skill 在目录里可见、调用即炸——宿主在 load 时才校验注册的 `source` 字段，之前没传；已补 `source: 'runtime'`，并加了真实 SkillRegistry 往返测试（list + load）防回归
+
 ## 0.1.0（2026-08-22）
 
 首个公开发布。

package/README.en.md

@@ -2,29 +2,31 @@
 
 English | [中文](README.md)
 
-Host service for dsh's file-preview surface: lists every file a session's tool calls touched — each write/edit change's diff included — and serves any file's current content for preview. Pair it with `@khorsheed/dsh-client-ui-file-preview` and the web GUI gains a Produced-files tab with inline previews and reveal-in-folder.
+Every file the agent touched, on one page: what changed, and what it looks like now.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview1.png" width="480" alt="the companion client's file-preview pane: file list and inline markdown preview">
+This package is the host half of file preview. Install it together with the companion client, and the web GUI gains a Produced-files tab: every file the session read, wrote, or edited is listed there, each write/edit change comes with its diff, and clicking any file shows its current content. Files the agent happened to write through bash (heredocs, redirects, and the like) are collected too. The whole service is read-only — it looks at files, never touches them.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview2.png" width="480" alt="per-artifact change history: pageable per-turn diffs">
-
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview3.png" width="480" alt="the Produced tab: every file the session wrote, at a glance">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview1.png" width="640" alt="the Produced tab's file preview: file list and inline markdown preview">
 
 ## Features
 
 - **Session file list** — every file the session's `read`/`write`/`edit` calls touched, with each write/edit change's diff attached.
-- **Content reads** — current text, capped and flagged when truncated; images as browser-loadable URLs on web hosts; binary, missing, and oversized files answer classified notices.
+- **Content reads** — current text, capped and flagged when truncated; images as browser-loadable URLs on web hosts; binary, missing, and oversized files answer classified notices instead of errors.
 - **Bash-write capture** — files written through `bash` (heredocs, redirects, `tee`, `sed -i`) merged into the list, stat-verified and rebuilt after a host restart.
 - **Reveal in folder** — opens the file's folder with the file selected, on macOS, Windows, WSL, and desktop Linux.
 - **Read-only by design** — no session state, no writes; a restarted host loses nothing.
 
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview2.png" width="640" alt="per-artifact change history: pageable per-turn diffs">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview3.png" width="640" alt="the Produced tab: every file the session wrote, at a glance">
+
 ## Install
 
 ```sh
 dsh plugin --profile web add @khorsheed/dsh-file-preview
 ```
 
-Host half only — install the companion client for the visible surface (Produced tab, preview drawer, per-turn change card):
+Host half only — the visible surface (Produced tab, preview drawer, per-turn change card) lives in the companion client:
 
 ```sh
 dsh plugin --profile web add @khorsheed/dsh-client-ui-file-preview
@@ -51,8 +53,10 @@ dsh plugin --profile web remove @khorsheed/dsh-file-preview
 
 ## Compatibility
 
-- npm release line (`@deepseek-ai/dsh@0.1.1-rc.2`): ✅ full — the rc.8→0.1.1-rc.1 API audit (2026-08-21) confirms every surface this plugin consumes is unchanged or additive (the ProjectionDefinition restructure, cacheHitPercent return-type change, and the credentials/updated event rename do not touch this package); no source change was needed; re-audited for rc.2 (2026-08-22): consumed surface unchanged, full build+test green.
-- source line (deepseek-harness master): ✅
+- npm release line (`@deepseek-ai/dsh@0.1.2-rc.1`): ✅ full — baseline moved to the 0.1.2-rc.1 API surface (single-arm 0.1.2 API consumption; the 0.1.1-rc.2 runtime arm is retired), full build+test green; minHost moves up to 0.1.2-rc.1 — older hosts stay on the previous release line.
+- source line (deepseek-harness master): ✅ (verifiedHost: 0.1.2-rc.1)
+
+**Version line mapping**: 0.2.0 and up support host `0.1.2-rc.1` and later; hosts on `0.1.0-rc.6` ~ `0.1.1-rc.2` stay on the 0.1.x release line (last release `0.1.1`).
 
 ## Known Limitations
 
@@ -66,10 +70,10 @@ dsh plugin --profile web remove @khorsheed/dsh-file-preview
 
 `ctx.filePreview` (wire namespace `filePreview`) exposes four generated Remote methods:
 
-- `list(agent)` — a pure fold over `agent.session.events`: `read`/`write`/`edit` `tool/call`s contribute display paths, as do settled nested Code Mode `tool/code-dispatch`es for those tools (failed dispatches record nothing; entries borrow the root call's turn/step). A `write`/`edit` `tool/result` carrying `diffs` meta appends each change to the entry in event order, `lastDiff` kept as the final one. The response carries the entries, the last scanned seq, and whether `maxFiles` was hit. No filesystem access in the fold; with `captureBashWrites` on, entries merge with the collector's verified bash-written paths.
+- `list(agent)` — a pure fold over `agent.session.events`: `read`/`write`/`edit` `tool/call`s contribute display paths, as do settled nested Code Mode `tool/code-dispatch`es for those tools (failed dispatches record nothing; entries borrow the root call's turn/step). A `write`/`edit` `tool/result` carrying `diffs` meta appends each change to the entry in event order, `lastDiff` kept as the final one. The response carries the entries, the last scanned seq, and whether `maxFiles` was hit. No filesystem access in the fold; with `captureBashWrites` on, entries merge with the collector's verified bash-written paths. Before returning, each path is resolved against the session cwd and `stat`-ed, keeping only those that still exist as a regular file — the log fold is history, the product list reflects disk state (a temp script a turn wrote then cleaned up is no longer a product); existence is probed fresh per call (not cached with the log fold).
 - `read(agent, path, signal)` — resolves `path` against the session cwd and serves `kind: 'text'` (capped at `maxReadBytes`, flagged `truncated`), or `kind: 'image'` with a browser-loadable URL on web hosts — bytes ride a dedicated `/file-preview-image/<sessionId>/<path>` route, registered only when the optional `webServer` and `agents` services are composed; headless hosts answer `binary` — or a classified notice: `binary` (binary extension or NUL bytes; never read), `missing`, `too-large`, or `error` (message included).
 - `reveal(agent, path, signal)` — opens the file's folder with the file selected, shell-free through `@deepseek-ai/dsh-native-command`: macOS `open -R`, Windows `explorer /select,<path>`, WSL via `wslpath`, desktop Linux tries `nautilus`/`dolphin`/`nemo --select` in order. Answers `{ revealed: true }`, or `false` with `reason: 'missing'` (no such target) or `'select-failed'` (no capable file manager — the caller then opens the parent folder, so the gesture always lands somewhere visible). Writes nothing.
-- `turnFiles(agent)` — every turn's file mutations for the turn-tail card, the same single source of truth as `list` but NOT deduped: a file touched in two turns appears in both groups, so each card lists exactly what that turn mutated. Line deltas are summed from result diffs; the fold is cached per session and invalidated by the log watermark, which the response carries for the client's own cache.
+- `turnFiles(agent)` — every turn's file mutations for the turn-tail card, the same single source of truth as `list` but NOT deduped: a file touched in two turns appears in both groups, so each card lists exactly what that turn mutated. Line deltas are summed from result diffs; the fold is cached per session and invalidated by the log watermark, which the response carries for the client's own cache. Like `list`, it probes existence against the session cwd before returning and keeps only files that still exist (a cleaned-up temp script does not occupy a card).
 
 Bash-write collector: watches each session's bash `tool/call`/`tool/result` pairs, extracts high-precision write targets (`cat > path` heredocs, single `>` redirects, `tee` non-append, `sed -i`), expands `$VAR`/`~`/relative paths against the host environment and session cwd, and records only paths `fs.stat` confirms as files (a miss beats a false positive). Captures live in a per-session in-memory registry rebuilt by replaying the session's own history on `session/created`, so a restarted host regains them; the session log itself is never mutated (the official `Session.append` cannot mark a plugin event `ignorable` — see the S2 seam in `docs/upstream-seam-registry.md`). Bash-captured files carry no diff history; previews read current content through `read`.
 

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/file-preview/README.en.md
-packages/file-preview/README.en.md: 244347bb89f3796d687220bfdb44c3daf7d68a5a
-packages/file-preview/README.md: 3131fafedb08f02e90323172cfd4d087e3ce77a6
+packages/file-preview/README.en.md: ef4c3a913fe23a474cb4d05114fb9f080ff641d1
+packages/file-preview/README.md: a34ba31610e054fd3f82c9b2d5c3635e04a970ed

package/README.md

@@ -2,21 +2,23 @@
 
 [English](README.en.md) | 中文
 
-dsh 文件预览界面的宿主服务:列出会话工具调用触碰过的每个文件——附每次 write/edit 改动的 diff——并提供任一文件的当前内容用于预览。与 `@khorsheed/dsh-client-ui-file-preview` 成对安装,web GUI 即获得「产物」tab:内联预览与"在文件夹中打开"。
+agent 碰过的文件一页看全：改了什么、现在长什么样。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview1.png" width="480" alt="配套客户端的文件预览:文件列表与内联 markdown 预览">
+这是文件预览的宿主半。装上它和配套的界面包，web GUI 会多一个「产物」tab：会话里 agent 读过、写过、改过的每个文件都列在里面，每次 write/edit 改动附 diff，点开任一文件就能看到当前内容。agent 用 bash 顺手写的文件（heredoc、重定向之类）也一样收进来。整个服务只读——它只看文件，从不动文件。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview2.png" width="480" alt="每个产物的改动记录:逐轮 diff 可翻页回看">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview1.png" width="640" alt="「产物」tab 的文件预览：文件列表与内联 markdown 预览">
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview3.png" width="480" alt="「产物」tab:会话写过的全部文件一览">
+## 功能
 
-## 特性
+- **会话文件清单**——会话 `read`/`write`/`edit` 调用触碰过的每个文件，每次 write/edit 改动附 diff。
+- **内容读取**——文件当前文本，超限截断并标记；web 宿主上图片返回浏览器可加载的 URL；二进制、不存在、超限的文件返回分类提示而不是报错。
+- **bash 写入采集**——经 `bash` 写入的文件（heredoc、重定向、`tee`、`sed -i`）并入清单，经 stat 验证，宿主重启后自动重建。
+- **在文件夹中打开**——在宿主文件管理器中打开所在文件夹并选中文件，支持 macOS、Windows、WSL、桌面 Linux。
+- **只读设计**——无会话状态、无写入；宿主重启不丢任何东西。
 
-- **会话文件清单**——会话 `read`/`write`/`edit` 调用触碰过的每个文件,每次 write/edit 改动附 diff。
-- **内容读取**——文件当前文本,超限截断并标记;web 宿主上图片返回浏览器可加载的 URL;二进制、不存在、超限文件返回分类提示。
-- **bash 写入采集**——经 `bash` 写入的文件(heredoc、重定向、`tee`、`sed -i`)并入清单,经 stat 验证,宿主重启后重建。
-- **在文件夹中打开**——在宿主文件管理器中打开所在文件夹并选中文件,支持 macOS、Windows、WSL、桌面 Linux。
-- **只读设计**——无会话状态、无写入;宿主重启不丢任何东西。
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview2.png" width="640" alt="每个产物的改动记录：逐轮 diff 可翻页回看">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/file-preview3.png" width="640" alt="「产物」tab：会话写过的全部文件一览">
 
 ## 安装
 
@@ -24,13 +26,13 @@ dsh 文件预览界面的宿主服务:列出会话工具调用触碰过的每个
 dsh plugin --profile web add @khorsheed/dsh-file-preview
 ```
 
-仅宿主半——可见界面(「产物」tab、预览抽屉、回合变更卡片)在配套客户端里:
+仅宿主半——可见界面（「产物」tab、预览抽屉、回合变更卡片）在配套客户端里：
 
 ```sh
 dsh plugin --profile web add @khorsheed/dsh-client-ui-file-preview
 ```
 
-卸载;残留的客户端半降级为空态而非报错:
+卸载；残留的客户端半降级为空态而非报错：
 
 ```sh
 dsh plugin --profile web remove @khorsheed/dsh-file-preview
@@ -47,41 +49,43 @@ dsh plugin --profile web remove @khorsheed/dsh-file-preview
     captureBashWrites: true
 ```
 
-`maxReadBytes` 限制单次 `read`(超限返回 `too-large`),`maxFiles` 限制 `list` 折叠结果——均为正整数,默认 512 KiB 与 500——`captureBashWrites`(默认 `true`)开关 bash 写入采集器。
+`maxReadBytes` 限制单次 `read`（超限返回 `too-large`），`maxFiles` 限制 `list` 折叠结果——均为正整数，默认 512 KiB 与 500——`captureBashWrites`（默认 `true`）开关 bash 写入采集器。
 
 ## Compatibility
 
-- npm 发布线(`@deepseek-ai/dsh@0.1.1-rc.2`):✅ 完整——rc.8→0.1.1-rc.1 API 审计(2026-08-21)确认本插件消费的所有面无变化或纯增量(ProjectionDefinition 重构、cacheHitPercent 返回值变更、credentials/updated 事件改名均不涉及本包),无需改动源码；rc.1→rc.2 复核(2026-08-22):消费面无变化,全量构建测试通过。
-- 源码线(deepseek-harness master):✅
+- npm 发布线（`@deepseek-ai/dsh@0.1.2-rc.1`）：✅ 完整——基线迁移至 0.1.2-rc.1 API 面（单臂消费 0.1.2 API，0.1.1-rc.2 运行臂已退役），全量构建测试通过；minHost 前移至 0.1.2-rc.1，旧宿主请停留在旧发布线。
+- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.2-rc.1）
+
+**版本线对照**：0.2.0 起支持宿主 `0.1.2-rc.1` 及以后；宿主 `0.1.0-rc.6` ~ `0.1.1-rc.2` 的用户请停留在 0.1.x 发布线（末版 `0.1.1`）。
 
-## 已知限制
+## Known Limitations
 
-- **列表是时间点折叠**——没有推送通道;客户端通过重新调用 `list` 刷新。
+- **列表是时间点折叠**——没有推送通道；客户端通过重新调用 `list` 刷新。
 - **不提供二进制预览内容**——非图片二进制文件只返回 `kind: 'binary'` 及大小。
 
 ## 实现原理
 
 <details>
-<summary>内部结构(点击展开)</summary>
+<summary>内部结构（点击展开）</summary>
 
-`ctx.filePreview`(wire 命名空间 `filePreview`)暴露四个生成的 Remote 方法:
+`ctx.filePreview`（wire 命名空间 `filePreview`）暴露四个生成的 Remote 方法：
 
-- `list(agent)`——对 `agent.session.events` 的纯折叠:`read`/`write`/`edit` 的 `tool/call` 贡献展示路径,这些工具的已完结嵌套 Code Mode `tool/code-dispatch` 同样计入(失败的派发不记录;条目借用根调用的 turn/step)。携带 `diffs` 元数据的 `write`/`edit` `tool/result` 把每次改动按事件序追加进条目,`lastDiff` 保留为最后一次。响应携带条目、最后扫描的 seq,以及是否触达 `maxFiles`。折叠本身不访问文件系统;`captureBashWrites` 开启时并入采集器验证过的 bash 写入路径。
-- `read(agent, path, signal)`——以会话 cwd 为基准解析 `path`,返回 `kind: 'text'`(超过 `maxReadBytes` 截断并标记 `truncated`);web 宿主上图片返回 `kind: 'image'` 及浏览器可加载 URL——字节走专门的 `/file-preview-image/<sessionId>/<path>` 路由,仅当组合了可选的 `webServer` 与 `agents` 服务时注册;无 web 宿主返回 `binary`——否则返回分类提示:`binary`(二进制扩展名或 NUL 字节;绝不读取)、`missing`、`too-large`、`error`(含消息)。
-- `reveal(agent, path, signal)`——在宿主文件管理器中打开文件所在文件夹并选中它,全程无 shell,走 `@deepseek-ai/dsh-native-command`:macOS `open -R`、Windows `explorer /select,<path>`、WSL 经 `wslpath`、桌面 Linux 依次尝试 `nautilus`/`dolphin`/`nemo --select`。选中返回 `{ revealed: true }`,否则 `false` 及 `reason: 'missing'`(目标不存在)或 `'select-failed'`(无可用文件管理器——调用方改开父文件夹,手势总能落在可见处)。不写入任何东西。
-- `turnFiles(agent)`——每个回合的文件变更,回合卡片与 `list` 同源但**不**去重:同一文件在两个回合改过,两个分组都有它——每张卡片精确列出该回合改了什么。行数增减由 result diff 求和;折叠按会话缓存、由日志水位线失效,响应携带水位线供客户端自缓存。
+- `list(agent)`——对 `agent.session.events` 的纯折叠：`read`/`write`/`edit` 的 `tool/call` 贡献展示路径，这些工具的已完结嵌套 Code Mode `tool/code-dispatch` 同样计入（失败的派发不记录；条目借用根调用的 turn/step）。携带 `diffs` 元数据的 `write`/`edit` `tool/result` 把每次改动按事件序追加进条目，`lastDiff` 保留为最后一次。响应携带条目、最后扫描的 seq，以及是否触达 `maxFiles`。折叠本身不访问文件系统；`captureBashWrites` 开启时并入采集器验证过的 bash 写入路径。返回前按会话 cwd 解析每条路径并 `stat`，只保留当前仍存在的常规文件——日志折叠是历史，产物列表只看磁盘现状（某回合写后又清理的临时脚本不再是产物）；存在性每次调用都现查（不随日志折叠缓存）。
+- `read(agent, path, signal)`——以会话 cwd 为基准解析 `path`，返回 `kind: 'text'`（超过 `maxReadBytes` 截断并标记 `truncated`）；web 宿主上图片返回 `kind: 'image'` 及浏览器可加载 URL——字节走专门的 `/file-preview-image/<sessionId>/<path>` 路由，仅当组合了可选的 `webServer` 与 `agents` 服务时注册；无 web 宿主返回 `binary`——否则返回分类提示：`binary`（二进制扩展名或 NUL 字节；绝不读取）、`missing`、`too-large`、`error`（含消息）。
+- `reveal(agent, path, signal)`——在宿主文件管理器中打开文件所在文件夹并选中它，全程无 shell，走 `@deepseek-ai/dsh-native-command`：macOS `open -R`、Windows `explorer /select,<path>`、WSL 经 `wslpath`、桌面 Linux 依次尝试 `nautilus`/`dolphin`/`nemo --select`。选中返回 `{ revealed: true }`，否则 `false` 及 `reason: 'missing'`（目标不存在）或 `'select-failed'`（无可用文件管理器——调用方改开父文件夹，手势总能落在可见处）。不写入任何东西。
+- `turnFiles(agent)`——每个回合的文件变更，回合卡片与 `list` 同源但**不**去重：同一文件在两个回合改过，两个分组都有它——每张卡片精确列出该回合改了什么。行数增减由 result diff 求和；折叠按会话缓存、由日志水位线失效，响应携带水位线供客户端自缓存。与 `list` 一样，返回前按会话 cwd 校验存在性，只保留当前仍存在的文件（被清理的临时脚本不占卡片）。
 
-bash 写入采集器:监听每个会话的 bash `tool/call`/`tool/result` 配对,提取高精度写入目标(`cat > path` heredoc、单 `>` 重定向、`tee` 非追加、`sed -i`),按宿主环境与会话 cwd 展开 `$VAR`/`~`/相对路径,只记录 `fs.stat` 确认为文件的路径(宁缺毋滥)。采集结果存于按会话的内存登记表,`session/created` 时重放会话自身历史重建——宿主重启后不丢;会话日志本身绝不被改动(官方 `Session.append` 无法给插件事件标 `ignorable`——见 `docs/upstream-seam-registry.md` 的 S2 条目)。bash 采集的文件没有 diff 历史;预览与普通条目一样通过 `read` 读当前内容。
+bash 写入采集器：监听每个会话的 bash `tool/call`/`tool/result` 配对，提取高精度写入目标（`cat > path` heredoc、单 `>` 重定向、`tee` 非追加、`sed -i`），按宿主环境与会话 cwd 展开 `$VAR`/`~`/相对路径，只记录 `fs.stat` 确认为文件的路径（宁缺毋滥）。采集结果存于按会话的内存登记表，`session/created` 时重放会话自身历史重建——宿主重启后不丢；会话日志本身绝不被改动（官方 `Session.append` 无法给插件事件标 `ignorable`——见 `docs/upstream-seam-registry.md` 的 S2 条目）。bash 采集的文件没有 diff 历史；预览与普通条目一样通过 `read` 读当前内容。
 
-信任与状态:受信任的只读能力——能读取 `ctx.fs` 允许会话访问的一切,组合它即授予对会话文件系统视图的预览权限;它不是安全边界。不产生会话事件;仅有的按会话状态是回合折叠缓存与 bash 采集器的已验证写入登记表。
+信任与状态：受信任的只读能力——能读取 `ctx.fs` 允许会话访问的一切，组合它即授予对会话文件系统视图的预览权限；它不是安全边界。不产生会话事件；仅有的按会话状态是回合折叠缓存与 bash 采集器的已验证写入登记表。
 
-分享:纯宿主侧增量——一个 Remote 服务,由浏览器半经官方的 `ctx.remote.$mount` 通道挂载。浏览器半(`@khorsheed/dsh-client-ui-file-preview`)同样纯增量;两个包独立分发,零改动组合进原版 dsh 核心。
+分享：纯宿主侧增量——一个 Remote 服务，由浏览器半经官方的 `ctx.remote.$mount` 通道挂载。浏览器半（`@khorsheed/dsh-client-ui-file-preview`）同样纯增量；两个包独立分发，零改动组合进原版 dsh 核心。
 
 </details>
 
 ## 开发
 
-隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo(`packages/file-preview`)。问题与贡献请移步该仓库。
+隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo（`packages/file-preview`）。问题与贡献请移步该仓库。
 
 ## 变更记录
 

package/lib/index.js

@@ -271,7 +271,7 @@ var BashWriteCollector = class {
 	#replay(session) {
 		this.#pending.set(session.id, /* @__PURE__ */ new Map());
 		this.#captured.set(session.id, /* @__PURE__ */ new Map());
-		for (const event of session.events) this.#onEvent(session, event);
+		for (const event of session.snapshotEvents()) this.#onEvent(session, event);
 	}
 	#onEvent(session, event) {
 		if (event.type === "tool/call") {
@@ -330,6 +330,14 @@ const FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
 	"write",
 	"edit"
 ]);
+/**
+* Settled nested-dispatch event names, matched by name (feature detection,
+* never a version check): `tool/code-dispatch` is the Code Mode name every
+* host through 0.1.2-rc.1 emits; `tool/ptc-dispatch` is the PTC rename later
+* 0.1.2 seats move to. Both carry the same settled-dispatch payload, so one
+* branch serves either.
+*/
+const DISPATCH_EVENT_NAMES = /* @__PURE__ */ new Set(["tool/code-dispatch", "tool/ptc-dispatch"]);
 /** The argument key carrying the touched path (shared by all three file tools). */
 const FILE_PATH_ARGUMENT = "file_path";
 /**
@@ -381,7 +389,8 @@ function diffsFromResultMeta(meta) {
 * first-seen order and deduplicated by display path; a later occurrence
 * refreshes the entry's op and location without moving it, and each write/edit
 * tool result appends its change's diff to the entry's `diffs` in event order.
-* Nested Code Mode file dispatches (`tool/code-dispatch` events) count too —
+* Nested Code Mode file dispatches (`tool/code-dispatch` events, or
+* `tool/ptc-dispatch` on seats running the PTC rename) count too —
 * they carry no turn/step of their own, so the entry borrows the enclosing
 * root call's location.
 * @param events - the session's events in ascending seq order.
@@ -424,15 +433,16 @@ function foldFilePreview(events, maxFiles) {
 			record(target, event.seq, event.data.turn, event.data.step);
 			continue;
 		}
-		if (event.type === "tool/code-dispatch") {
-			if (event.data.isError) continue;
-			const target = targetFromArguments(event.data.name, event.data.arguments);
+		if (DISPATCH_EVENT_NAMES.has(event.type)) {
+			const dispatch = event;
+			if (dispatch.data.isError) continue;
+			const target = targetFromArguments(dispatch.data.name, dispatch.data.arguments);
 			if (target === void 0) continue;
-			const site = callSites.get(String(event.data.rootCallId)) ?? {
+			const site = callSites.get(String(dispatch.data.rootCallId)) ?? {
 				turn: 0,
 				step: 0
 			};
-			record(target, event.seq, site.turn, site.step);
+			record(target, dispatch.seq, site.turn, site.step);
 			continue;
 		}
 		if (event.type === "tool/result") {
@@ -508,11 +518,12 @@ function resultCallFacts(message) {
 * single source of truth. Unlike {@link foldFilePreview}, this does NOT dedupe
 * a path to its last occurrence: a file touched in two turns appears in BOTH
 * turn maps, so each turn's card lists exactly what that turn mutated.
-* write/edit calls register with their own turn; nested Code Mode dispatches
-* borrow the enclosing root call's turn (dispatch events carry none); a
-* `tool/result` whose presentation meta carries diffs registers its paths (the
-* render-intent vocabulary) with the result's turn, and per-turn line deltas
-* are summed from the diffs. A `write` whose result carries no diffs is a
+* Reads leave no card entry (the card is the mutation vocabulary — write/edit
+* only), so a pure-read call never registers; write/edit calls register with
+* their own turn; nested Code Mode dispatches borrow the enclosing root call's
+* turn (dispatch events carry none); a `tool/result` whose presentation meta
+* carries diffs registers its paths (the render-intent vocabulary) with the
+* result's turn, and per-turn line deltas are summed from the diffs. A `write` whose result carries no diffs is a
 * create (the write tool records no diffs when the file had no prior content):
 * its full written content — read from the call arguments, which the log keeps
 * — is the added-line count, once per file per turn.
@@ -609,6 +620,7 @@ function foldFilePreviewByTurn(events) {
 			});
 			const target = pathFromToolCall(event.data.name, event.data.arguments);
 			if (target === void 0) continue;
+			if (target.op === "read") continue;
 			if (target.op === "write") {
 				const content = contentFromWriteCall(event.data.arguments);
 				if (content !== void 0) {
@@ -624,16 +636,18 @@ function foldFilePreviewByTurn(events) {
 			recordLocation(target.path, event.data.turn, event.seq, event.data.step);
 			continue;
 		}
-		if (event.type === "tool/code-dispatch") {
-			if (event.data.isError) continue;
-			const target = targetFromArguments(event.data.name, event.data.arguments);
+		if (DISPATCH_EVENT_NAMES.has(event.type)) {
+			const dispatch = event;
+			if (dispatch.data.isError) continue;
+			const target = targetFromArguments(dispatch.data.name, dispatch.data.arguments);
 			if (target === void 0) continue;
-			const site = callSites.get(String(event.data.rootCallId)) ?? {
+			if (target.op === "read") continue;
+			const site = callSites.get(String(dispatch.data.rootCallId)) ?? {
 				turn: 0,
 				step: 0
 			};
 			sessionSeen.add(target.path);
-			recordContribution(target.path, site.turn, event.seq, site.step, void 0, void 0, true);
+			recordContribution(target.path, site.turn, dispatch.seq, site.step, void 0, void 0, true);
 			continue;
 		}
 		if (event.type === "tool/result") {
@@ -790,7 +804,8 @@ function registerArtifactSkill(ctx) {
 		return;
 	}
 	try {
-		const skillFile = join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "3d-artifact", "SKILL.md");
+		const skillDir = join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "3d-artifact");
+		const skillFile = join(skillDir, "SKILL.md");
 		const raw = readFileSync(skillFile, "utf8");
 		const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(raw);
 		const name = /^name: (.+)$/m.exec(match?.[1] ?? "")?.[1]?.trim();
@@ -803,7 +818,9 @@ function registerArtifactSkill(ctx) {
 		ctx.effect(() => skills.register({
 			name,
 			description,
-			content
+			content,
+			source: "runtime",
+			provider: "file-preview"
 		}));
 	} catch (error) {
 		ctx.logger.warn(`file-preview: shipped SKILL.md unreadable (${String(error)}) — the 3d-artifact skill is not registered`);
@@ -899,8 +916,9 @@ function readErrorMessage(error) {
 }
 /**
 * The `filePreview` Remote service: session-scoped read-only file inspection
-* for web surfaces. `list` is a pure fold over the session log (no filesystem
-* access); `read` resolves the path against the session cwd and serves current
+* for web surfaces. `list` is a fold over the session log, then filtered to the
+* paths that still exist on disk (resolved against the session cwd and stat-ed
+* per call); `read` resolves the path against the session cwd and serves current
 * text content through `ctx.fs` (or a browser URL for images), capped by
 * config. Image bytes ride a dedicated host route so the browser loads them
 * natively without bloating the RPC channel.
@@ -1103,35 +1121,64 @@ let FilePreviewService = (() => {
 			});
 			res.end(Buffer.from(bytes));
 		}
+		/** Resolve the session's recorded display paths against its cwd and keep only
+		*  those that currently exist as a regular file. The products surfaces fold
+		*  the session log (which is history, not disk state): a path the log wrote
+		*  may have been cleaned up since (a temp script the turn deleted), and such
+		*  a path is not a product to list. Existence is checked fresh on every call
+		*  (never cached), so a deletion that lands after a fold is visible on the
+		*  next fetch. Unresolvable/unstat-able paths are treated as absent.
+		* @param agent - owning live agent; its session cwd anchors relative paths.
+		* @param paths - the display paths to probe.
+		* @returns the subset that resolves to an existing regular file.
+		*/
+		async retainExisting(agent, paths) {
+			if (paths.length === 0) return /* @__PURE__ */ new Set();
+			const cwd = agent.session.header.cwd;
+			const existing = /* @__PURE__ */ new Set();
+			for (const path of paths) {
+				if (existing.has(path)) continue;
+				try {
+					const target = await this.fs.resolve(path, cwd === void 0 ? {} : { cwd });
+					if ((await this.fs.stat(target))?.type === "file") existing.add(path);
+				} catch {}
+			}
+			return existing;
+		}
 		/**
 		* List the files one session wrote or edited: the log fold plus any
 		* bash-written files the collector verified (the S2 seam), merged so a
-		* captured path the fold already knows keeps its log-derived entry.
+		* captured path the fold already knows keeps its log-derived entry. Only
+		* paths that currently exist on disk are returned — a file the session
+		* wrote and later deleted is history, not a product.
 		* @param agent - owning live agent; its session log is the data source.
-		* @returns first-seen files capped by `maxFiles`, with the log watermark.
+		* @returns existing first-seen files capped by `maxFiles`, with the log watermark.
 		*/
-		list(agent) {
-			const folded = foldFilePreview(agent.session.events, this.resolved.maxFiles);
+		async list(agent) {
+			const folded = foldFilePreview(agent.session.snapshotEvents(), this.resolved.maxFiles);
 			const captured = this.collector?.captured(agent.session.id);
-			if (captured === void 0 || captured.size === 0) return folded;
-			const seen = new Set(folded.entries.map((entry) => entry.path));
-			const extra = [];
-			for (const [path, write] of captured) {
-				if (seen.has(path) || folded.entries.length + extra.length >= this.resolved.maxFiles) continue;
-				extra.push({
-					path,
-					op: "write",
-					seq: write.seq,
-					turn: write.turn,
-					step: write.step,
-					diffs: []
-				});
+			let entries = folded.entries;
+			if (captured !== void 0 && captured.size > 0) {
+				const seen = new Set(entries.map((entry) => entry.path));
+				const extra = [];
+				for (const [path, write] of captured) {
+					if (seen.has(path) || entries.length + extra.length >= this.resolved.maxFiles) continue;
+					extra.push({
+						path,
+						op: "write",
+						seq: write.seq,
+						turn: write.turn,
+						step: write.step,
+						diffs: []
+					});
+				}
+				entries = [...entries, ...extra];
 			}
-			if (extra.length === 0) return folded;
+			const existing = await this.retainExisting(agent, entries.map((entry) => entry.path));
 			return {
-				entries: [...folded.entries, ...extra],
+				entries: entries.filter((entry) => existing.has(entry.path)),
 				asOfSeq: folded.asOfSeq,
-				truncated: folded.truncated || folded.entries.length + extra.length >= this.resolved.maxFiles
+				truncated: folded.truncated || entries.length >= this.resolved.maxFiles
 			};
 		}
 		/**
@@ -1142,13 +1189,16 @@ let FilePreviewService = (() => {
 		* result diff meta) and merging the collector's bash-written captures by
 		* their own turn. The fold is cached per session and invalidated by the log
 		* watermark, so repeated card fetches do not refold. A path touched in two
-		* turns appears in BOTH turn groups — per-turn attribution is exact.
+		* turns appears in BOTH turn groups — per-turn attribution is exact. Only
+		* paths that currently exist on disk are returned (a deleted temp script is
+		* history, not a product); existence is probed fresh on every call, so the
+		* cached fold is filtered per request rather than cached.
 		* @param agent - owning live agent; its session log is the data source.
-		* @returns per-turn file groups plus the scanned watermark.
+		* @returns existing per-turn file groups plus the scanned watermark.
 		*/
-		turnFiles(agent) {
+		async turnFiles(agent) {
 			const session = agent.session;
-			const events = session.events;
+			const events = session.snapshotEvents();
 			const asOfSeq = events.length === 0 ? -1 : events[events.length - 1].seq;
 			const cached = this.turnCache.get(session.id);
 			let byTurn;
@@ -1181,8 +1231,12 @@ let FilePreviewService = (() => {
 					files: files.sort((a, b) => a.seq - b.seq)
 				});
 			}
+			const existing = await this.retainExisting(agent, turns.flatMap((group) => group.files.map((file) => file.path)));
 			return {
-				turns,
+				turns: turns.map((group) => ({
+					turn: group.turn,
+					files: group.files.filter((file) => existing.has(file.path))
+				})).filter((group) => group.files.length > 0),
 				asOfSeq
 			};
 		}