dsh-manage-session 0.3.3 → 0.5.1

package/CHANGELOG.md

@@ -1,261 +1,341 @@
-# Changelog
-
-## 0.1.0-alpha.6
-
-### 修复 —— 图标与文案间距收紧；窄栏下不再挤掉邻居
-
-- **间距 8px → 4px**：`🧭` 与「会话管家」之间的空隙按实测收紧（用户反馈「icon 文字间隔小点」）。
-  同时把自身内边距从 `0 12px 0 10px` 收到 `0 10px 0 8px`，与相邻「搜索」胶囊的左右内边距一致。
-- **自己会缩，不再把邻居挤扁**：`.dss_entryWrap` 由 `flex:none` 改为 `flex:0 1 auto; min-width:0`，
-  外层前距 `8px → 6px`。它此前从不让位，缺口全落在搜索胶囊上，把对方标签挤成一个字；
-  现在空间不足时先由自己承担（标签带省略号收尾）。
-- **轨道尺寸回到 28×28**：轨道内容盒只有 36px（56px 轨道 − 2×10px 内边距），两个入口同处一行装不下
-  两个 36px 控制盒（实测 36+28=64px，溢出 14px）。取 28+28=56px，比改动前的 32+28=60px 还窄。
-- **协同边界未变**：依旧只动自己的 CSS，不引用搜索索引任何值，也不假设其是否安装；
-  两者都装时整行自然宽度 217px，单独存在时各占整行。
-
-## 0.1.0-alpha.5
-
-### 变更 —— 侧边栏入口带文案，与「搜索索引」同行自适应
-
-- **入口有名字了**：脚部入口原先是 28×28 的单个图标圆钮（🧭），既没有文案，也说不清点开是什么。
-  宽栏下改为 42px 行控件：**🧭 会话管家**，与相邻的「搜索」胶囊同高、同圆角（12px）、同字号。
-- **同一行的几何协同**：搜索入口声明 `flex:1;min-width:0` 后不再独占整行，两个入口作为
-  `sidebar.footer.action` 的兄弟项共处一行；本入口在宽栏加 `margin-left:8px` 让出间距
-  （对照官方 `ui-settings-general` 的 `.triggerRow{gap:8px}`）。本插件不知道对方是否存在、也不引用对方任何值——
-  协同只发生在各自的 CSS 上。
-- **收起轨道退化**：`wide=false` 时按钮走 `.dss_footerEntryRail`（36×36 圆、不带文案），与 Figma 轨道规范
-  （56px 轨道 / 10px 内边距 / 36×36 控制盒）及官方轨道控件一致；文案与宽栏同条件出现。
-- **文案归属修正**：组件里硬编码的 `'会话管家'` 兜底已删除，入口文案与面板标题同源（字典 `panel.title`），
-  词典仍是唯一出处。
-
-### 变更 —— 一个动词拆成两个：「取消归档状态」与「清理归档文件」
-
-**问题不是措辞，是语义**。此前面板只有一个操作，按钮却叫「删除选中」——
-它既不是删除（一个字节都没删），也不只做一件事（改了数组，就宣称「删除」）。
-于是同一个动作被叫成三个名字（删除 / 清理 / 移除），玩家和实现者对不上。
-
-现在拆成两个**独立路由、独立按钮、独立确认弹窗**的操作：
-
-| | 取消归档状态 | 清理归档文件 |
-|---|---|---|
-| 路由 | `session-history-prune` | **`session-history-purge`**（新增） |
-| 改什么 | 只改 `global.archivedSessionIds` | 删磁盘实体 **+** 改两处 id |
-| 磁盘文件 | 原样不动 | **消失** |
-| 会话去向 | 回到侧边栏原工作区 | 从世界上消失 |
-| 可逆 | ✅ 重启即生效 | ❌ **不可逆** |
-
-「清理归档文件」一次动 4 处：
-
-1. `~/.dsh/sessions/<工作区>/<会话id>/` —— **整个目录**。实测 3 个目录里同时存在
-   `session.jsonl.zstd` 与旧格式 `session.v3.jsonl.zstd`，只删当前格式那份会留下垃圾。
-2. `~/.dsh/storages/session_projcache/sessions/<会话id>.json` —— 逐条投影缓存。
-   > 注意另有一个 `storages/session_projcache.json`（整份布局，99.4 MB，最后写入停留在
-   > 09-11）：那是布局迁移留下的**化石**，宿主早已不写它，本插件也不碰它。
-   > 活的投影缓存是 `session_projcache/sessions/`（实测 143.4 MB / 275 条，今天仍在写）。
-3. `workspace.json` → `global.archivedSessionIds`
-4. `workspace.json` → `tables.workspaces.*.sessionIds`
-
-**清理必须连带取消归档**：文件删了、id 还留在数组里就是僵尸归档 ——
-侧边栏看不见它，一旦被取消归档又会冒出一个打不开的空会话。
-
-**执行顺序是「先改文件、后删实体」**：改文件是原子的且可整体中止
-（存储文件不可用时**一个字节都不删**）；反过来先删实体再改文件，中途失败会留下僵尸 id。
-
-**破坏性操作的护栏**：
-
-- 缺 `dshHome` 直接拒绝执行 —— 不接受猜测的路径；
-- 删除前用 `isSafeChild` 断言目标是预期 root 的**指定层数**子项
-  （拼错一层就是删掉整个 `sessions` 根）；
-- 逐条独立，失败只记不抛，返回 `failures` 明细，面板逐条列出；
-- 沿用一个写入口 `editWorkspaceDocument`（备份 + 同目录临时写入 + 原子改名）。
-
-### 变更 —— 体积按「勾选单元」算，不给总量
-
-单条会话的占用差异极大（实测：某条投影缓存 23.47 MB 而转录只有 0.07 MB；
-也有 0 字节的）。因此：
-
-- **每一行**显示自己的 `转录 6.2 MB · 缓存 2.3 MB`；
-- 列表头显示 `共 72 条 · 占 98.6 MB`；
-- 按钮显示**所选小计**：`清理归档文件 (3) · 释放 38.2 MB`；
-- 确认弹窗逐条列体积 + 合计。
-
-### 修复 —— 养老院清理后「没反应」：读的人和写的人不是同一份数据
-
-**症状**：编辑模式勾选归档会话 → `confirm` → 提示清理成功，但列表**一条没少**、
-面板也没有任何可见变化，看起来完全没生效。
-
-**根因**：两个路由各认一份数据，且**互不相通**。
-
-| 路由 | 认的那份 |
-|---|---|
-| `session-history-prune` | 存储文件 `~/.dsh/storages/workspace.json` 的 `global.archivedSessionIds`（备份 + 原子替换） |
-| `session-history-list` | **宿主内存 `workspaceRegistry.archivedSessionIds` 优先**（只有文件读不到才回退） |
-
-`registry` 是宿主**启动时**载入的快照，直接编辑文件不会回写它。于是：
-
-- 文件真的在瘦身（实测 166 → 159 → 151 → 103 → 72 → 71，每次确认都留下 `.bak-*` 备份）；
-- 列表却永远返回同一批 —— 用户按同一顺序勾选，每次都在删「列表里的头几条」，
-  而列表压根不变，所以观感是「点了确认，什么都没发生」。
-
-**修法**：让列表与 prune **同源**。
-
-- `readArchiveSet` 改为**存储文件优先**，`registry` 退居文件缺失时的兜底；
-  registry 仍被读取，但只作为诊断面（`registryIds`）返回。
-- `session-history-list` 新增 `pendingRestart`：registry 里**有**、文件里**没有**的 id 数
-  —— 即「已清理落盘、但本进程仍生效」的悬挂项。面板据此显示黄色提示，
-  并标出列表总条数，让「少了一条」肉眼可验。
-- `pruneHistory` 增加**写后校验**：写回后重新读文件确认目标 id 确实消失，
-  否则如实报错，不再出现「面板说成功、文件其实没变」。
-
-### 已知风险 —— 宿主会把整份内存快照写回，清理可能被「复活」
-
-存储层（`dsh-storage-json`）是**全量重写、内存为准**：每次写都用内存状态
-`serialize` 整份文档覆盖文件，且没有独立的关停 flush。所以清理之后、重启之前，
-**任何一次归档或工作区改动都会把旧的 `archivedSessionIds` 整份写回**，本次清理归零。
-
-这不是本插件的 bug（官方没有 unarchive 端点，文件是唯一可写面），
-但必须让用户知道 —— 已在 confirm 弹窗与成功提示里写明：**清理后请立刻重启 DSH**。
-
-## 0.1.0-alpha.4
-
-设置卡补回抽屉形态：此前只剩裸行，在「插件」设置分区里与其它插件不一致。
-
-### 修复
-
-- **设置卡缺少抽屉外壳（重要）**：DSH 的「插件」设置分区（`dsh-client-ui-settings-plugins`）
-  只做一件事——按 settings 命名空间分发 `settings.plugin.item`：
-
-      renderSlot('settings.plugin.item', {}, { entryKey: ns })
-
-  它**不提供任何外壳**：卡片的标题、说明、展开/收起全归插件自己所有。
-  本插件此前只渲染了裸行，于是有两处不对：
-  1. 在分区里与其它插件的「可折叠抽屉」形态不一致；
-  2. `card.title`（会话管家）与 `card.desc`（历史文件 · 健康检查）**定义了却从未被渲染**，
-     成了死文案——这正是「漏加的抽屉项」。
-
-  现在补回头部（标题 + 说明 + chevron，整块可点切换），主体默认收起，
-  与同分区其它卡片一致；`aria-expanded` 同步反映展开态。
-- **设置服务不可用时的表现**：原先整个卡片退化成一行「设置服务不可用」，
-  并因此**连标题一起丢掉**；现在抽屉头照常渲染，只在主体里说明原因——
-  这个插件不会在分区里彻底消失。
-
-### 变更
-
-- 展开态切换与 chevron 旋转遵循 `prefers-reduced-motion`。
-
-## 0.1.0-alpha.3
-
-体检结果缓存：关面板再打开零延迟出内容，且处置后只更新那一行。
-
-### 新增
-
-- **体检结果缓存（进程内）**：一次完整扫描（分批走满整个语料）后结果留在宿主进程里，
-  面板再次打开直接渲染缓存，不再全量重扫。缓存**只在走满一遍语料后才成型**——
-  扫到一半关掉面板不会留下半份结果冒充完整结论。
-- **`resume` 纯读探测**：`session-health-scan` 新增 `resume: true`，**只读缓存、不做任何扫描**。
-  面板挂载时用它零成本探一次：命中就出内容，不命中就什么都不做
-  （挂载即干重活是上一版被诟病的地方）。同时捎回当前语料总数。
-- **生成时间与刷新入口**：命中缓存时面板显示「结果来自缓存 · N 分钟前」并给出「刷新」
-  （强制全量重扫）。旧结果绝不冒充刚扫的。
-- **语料变化提示**：缓存的语料总数与当前不一致时提示「语料已变化（a → b），建议刷新」。
-  这条对账只做目录枚举，很便宜——所以它不构成新的缓存失效策略。
-
-### 变更
-
-- **单条就地回写**：单会话体检与可逆处置后不再依赖重扫——处置本就重算了 `after` 报告，
-  直接写回缓存；面板退回列表时该行已是最新档位（转好的行从此消失，与「只列问题」一致）。
-- 缓存**不落盘**：DSH 重启即失效。落盘需要失效策略，而判断失效的代价（枚举语料、
-  比对日志 mtime/size）已接近重扫本身，本切片取 YAGNI。
-
-### 测试
-
-- 新增 `tests/cache.spec.ts`（19 例）：成型规则（未走满 / 走满 / 空语料 / 中途中断 / `clear`）、
-  单条回写全分支（新增 / 替换 / 转好移出 / no-op），以及 `handleMethod` 接线
-  （`resume` 不扫描、分批走满后命中、`onlyProblems=false` 不污染缓存、
-  处置后回写的对象身份、缺 cache 的运行时仍可用）。
-
-## 0.1.0-alpha.2
-
-处置（处方）的判定与呈现修正：不再对「无从判定」的门开方，并明确给出处置后的结论。
-
-### 修复
-
-- **对 `skipped` 误开处方（重要）**：`prescribe()` 原先用 `level !== 'ok'` 判断投影缓存是否需要隔离，
-  于是「本门无从判定」也被当成「投影缓存未对齐」，对着自己的证据输出自相矛盾的处方，
-  并建议隔离一条**并不存在**的记录。抽出共享谓词 `isActionable()`（仅 `warn` / `fail` 可处置）统一收口，
-  `gates.ts` 的档位标准与 `repair.ts` 的处置标准自此是同一件事。
-- **「四门全绿」误报**：无处置项时固定回「四门全绿」。当门是 `skipped`（无从判定，而非绿）时该文案不成立；
-  现在改为「无可处置项（N 门无从判定，非异常）：<门 id 列表>」。
-- **处置后仍显示异常，无从判断处置是否生效**：面板只渲染「处置前 / 处置后」两个档位，
-  两者都是异常时无法区分「处置失败」与「处置与病灶无关」。
-  宿主新增 `assessRepair({ before, after, repair })`，判定为五档之一并附人读说明：
-  `nothing-to-do`（四门全绿）/ `repaired`（已恢复）/ `repaired-with-residual`（已隔离缓存，
-  但仍有与该缓存无关的异常，如会话日志的 open step）/ `not-applicable`（当前异常无可逆处置项）/
-  `failed`（处置自身失败）。面板按档位配色渲染结论横幅。
-
-### 说明
-
-- **处置能力未变**：仍是「只隔离投影缓存记录、复制后移动、不改会话日志」，本次只修正**判定**与**呈现**。
-  典型场景是「仅 `cold-read` 异常（会话存在未结算的 open step）」——这类异常本就不该由本插件修复，
-  现在会明确判为 `not-applicable` 并说明原因，而不是静默显示成「处置后还是异常」。
-
-### 测试
-
-- 新增 `tests/repair.spec.ts`（12 例）：覆盖 `isActionable` 的四档、`prescribe` 不再开空方，
-  以及 `assessRepair` 五档判定的分支。
-
-## 0.1.0-alpha.1
-
-体检面板的判定与反馈修正：修掉「注意」全量误报，并补上扫描进度与行内原因。
-
-### 修复
-
-- **「注意」全量误报（重要）**：`lossless-json` / `projection-cache` / `cold-read` 三门在
-  **无从判定**时（冷态会话没有热态投影、缓存记录尚未生成、日志里没有 turn/end）返回 `warn`，
-  导致**所有未加载的会话恒为「注意」**，真信号被淹没。
-  新增中性档 `skipped`（面板文案「未检查」）承载「无从观测」，**不参与总判聚合**。
-  固化的判定标准：`warn` = 观测到异常现象（有据）；`skipped` = 无从观测/无从判定（无据）。
-  实测：30 条会话由「30×注意」变为「26 正常 / 3 注意 / 1 异常」。
-- **列表行不显示触发原因**：体检结果列表只渲染聚合档位，行与行之间不可区分。
-  现在行内列出非 ok 的「门·档位」摘要（如 `可接续性·注意`），无需逐条点开详情。
-
-### 新增
-
-- **体检扫描进度**：`session-health-scan` 支持 `offset` 分批调用并返回 `total`；
-  面板按小批次连续调用、自行累计**真实进度**（`n/total · 已用 Xs`）。
-  首批未拿到分母时走不确定态动画。宿主保持无状态，同步扫描循环无需改异步。
-- **处置忙碌反馈**：可逆处置按钮加 spinner 并保持禁用，避免点击后界面静止。
-
-### 变更
-
-- **页签改名**：`病案室` → `养老院`（英文 `Records Room` → `Retirement Home`），
-  与「体检 / 处方 / 出院」的隐喻统一。
-
-## 0.1.0-alpha.0
-
-首个 alpha 版本：会话管家（历史文件 + 健康检查）。
-
-### 新增
-
-- **会话历史文件（病案室）**：从 `dsh-session-search-toggle` 迁入官方归档集合的读取与清理实现，
-  行为与迁移前等价（备份 + 同目录临时写 + 原子替换；显式编辑模式才允许清理）。
-  差异：列表来源改为**官方归档集合真值**（registry 优先、存储文件回退），因为独立索引已随搜索索引包离开；
-  标题等元数据为尽力而为（`sessionQuery` 标题快照 → 投影缓存 title → 空）。
-- **健康检查（体检 → 处方 → 出院）**：四个可独立测试的 gate
-  （`log-integrity` / `projection-cache` / `lossless-json` / `cold-read`），
-  统一输出 `{ id, level, evidence, attribution, detail }`；聚合为 `SessionHealthReport`。
-- **归属索引**：静态扫描 profile 的 `node_modules/<pkg>/lib/*.js`，建立「投影 key → 包名」，
-  把失败 gate 指回具体插件与字段路径；扫不到时如实标 `unknown`。
-- **可逆处方**：隔离损坏的投影缓存记录（先复制备份，再移动到 `.quarantine-<ts>`）+ 命令清单。
-  **禁止**改写会话日志、改历史数据、静默丢弃字段。
-- **两个 feature gate**：`historyFiles` / `healthCheck`，关闭时对应子域整域不注册（显式 disabled 错误），
-  客户端也不渲染对应页签。
-- **路由**：`/session-steward/api/*`，方法名一律 `session-*`，与搜索索引的 `/switch-search/api` 的 `index-*` 完全隔离。
-
-### 已知限制
-
-- `lossless-json` gate 依赖宿主暴露 `sessionProjections`（热态）才能给出确定判定；
-  拿不到时如实降级为 `warn`，不臆测。
-- 健康扫描默认只列最近 30 个非健康会话（`limit` 上限 200），不做全库遍历的默认行为。
-- 客户端面板为最小实现（列表 + 详情 + 三步按钮），未做虚拟滚动与批量操作。
+# Changelog
+
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+- [Français changelog](./CHANGELOG.fr.md)
+- [Deutsch changelog](./CHANGELOG.de.md)
+- [Italiano changelog](./CHANGELOG.it.md)
+- [Русский changelog](./CHANGELOG.ru.md)
+- [Español changelog](./CHANGELOG.es.md)
+
+## 0.5.1 —— 侧栏 footer 收紧行距并强制居中（含第三方入口矫正）
+
+- **容器行**：`sidebar.footer.action` 槽位公约升级——`justify-content:center` 统一居中行内所有入口（含第三方），`row-gap` 2px → 0。
+- **本插件入口**：按钮高 42px → 32px（上下裕度 10px → 5px），左右 padding 对称化 `0 10px`（消除整行居中时的 1px 视觉偏心）。两行 footer 总高 86px → 64px；收起轨道形态不变。
+- **第三方矫正**：dsh-context「上下文洞察」（`.lc-ov-entry`，按独占整行设计、内容靠左）以 `!important` 强制对齐公约：独占一行、行内居中、32px 高；`:not(.lc-ov-entry-rail)` 排除收起轨道的 36px 圆钮。类名为 dsh-context 源码硬编码、跨版本稳定（实测 0.56.1 / 0.60.0）。
+
+## 0.5.0
+
+### 适配 —— DSH 0.2.0 线（compat/0.2.0 分支，纯元数据适配，代码零修改）
+
+- **宿主换代**：peer 5 项（dsh-client-locale / dsh-client-ui-settings / dsh-client-ui-settings-general /
+  dsh-client-ui-slots / dsh-session）与两处 `engines.dsh`（package.json + dsh.plugin.json）统一换代为
+  `>=0.2.0-rc.1 <0.2.1-0`（rc 窗口锁线，0.2.1 起重新适配）；npm dist-tag `dsh-0.2.0`。
+- **零代码实证**（三处硬耦合点逐项对照 0.2.0-rc.1 实包/宿主源码核验）：
+  1. `dsh-session-format-v3-to-v4@0.2.0-rc.1` 的两张第一方名单（`RENAMED_PRODUCERS` 5 项 +
+     `RELEASED_SAME_NAME_PRODUCERS` 25 项）与本仓逐字照录版**逐项一致**；
+  2. `dsh-session@0.2.0-rc.1` 导出面：`decodeSeqRanges` 仍在；`decodeStorageRecord` 在
+     0.1.7-rc.2 与 0.2.0-rc.1 均**未导出**（软加载守卫按可选面处理，回落本地等价实现，两线行为一致）；
+  3. 归档目录契约未变：`session.jsonl.zstd`/`session.v3.jsonl.zstd` 双份命名方案两线同一函数、
+     `storages/session_projcache` 与 `workspace.json`（`global.archivedSessionIds` +
+     `tables.workspaces.*.sessionIds`）两处 id 名单均在。
+- **devDependencies**：`dsh-client-ui-slots` / `dsh-session` 去 caret，精确钉 `0.2.0-rc.1`
+  （有意不追 rc.2，与宿主基线 4878cdabd8 对齐；收益在 vitest/运行时软加载解析到 0.2.0 实包）。
+- **依赖树刷新**：删 node_modules 与 package-lock.json 重生提交；删除陈旧的
+  pnpm-lock.yaml（钉 0.1.0-rc.8 线）与 pnpm-workspace.yaml，随 npm 线单一化。
+- **版本与发布纪律**：0.4.8 → **0.5.0**；dsh.plugin.json version 0.4.1 → 0.5.0（治愈基线漂移）；
+  `publishConfig.tag` → `dsh-0.2.0`；`release:015` 改名 `release:020`（`--tag dsh-0.2.0`）；
+  双语 description「0.1.5 专线」文案随版更新。
+- 验证：install / build / typecheck / test 全绿（167 测试），`npm ls` 无 peer 冲突，node_modules 实装
+  dsh-session / dsh-client-ui-slots 均 0.2.0-rc.1。
+
+## 0.4.8
+
+### 修复 —— ST1：转换对第一方生产者名与宿主分叉
+
+- `migrateSessionSourceKind` 逐行查 `isFirstPartyLegacyProducer`（两张表逐字照录宿主
+  `dsh-session-format-v3-to-v4@0.1.7-rc.2` lib/index.js:51-84，实测 5+25=**30** 个第一方名），
+  命中即跳过该行并以 `skippedFirstParty` 如实上报——第一方名走宿主改名表/同名裸 kind
+  （含 role 敏感分支），无条件加前缀会写出宿主永不产出的 kind，静默损坏归因。
+  只含第一方旧行时不写盘。新增 30 名对照测试与宿主官方解码器读回断言（161 测试全绿）。
+
+### 加固 —— R2：purge 侧识别署名转换备份
+
+- 归档统计与清理两路识别 `*.pre-sourcemigrate-<ts>` 备份（后缀常量
+  `SOURCE_MIGRATE_BACKUP_SUFFIX` 已在 0.4.7 导出，本次接线）：
+  - **统计**：`locateSessionUsage` / `session-history-list` 每行新增 `backupBytes` /
+    `backupCount`——备份是 `bytes` 的子集，单列出来免得被当作日志体积误读；
+  - **清理**：`session-history-purge` 结果新增 `backupsRemoved`（整目录删除本就连带
+    备份，此处置个数让「备份一并处置」如实上报，不再是黑箱）。
+- 新增 6 条回归（后缀判定、统计单列、如实 0、清理上报、连带保留、列表带出），全套 167 测试。
+
+## 0.4.7
+
+### 新增 —— 插件署名格式体检门（source-kind）与旧署名转换
+
+- **背景**：宿主 0.1.7-rc.1 起（会话格式 v4）拒绝裸 `source: { kind: 'plugin', plugin }` 署名
+  （SessionFormatError，整轮失败）；genui 之外的未适配插件（session-guard、prime-memory 等）
+  已按清单修写路径，但存量日志里由它们写入的旧署名行仍在——未适配插件的读回判断会失配。
+- **检测（只读）**：体检新增第 6 门 `source-kind`，按日志 header 的格式代次分线：
+  - **版本依赖表**（详见 `src/host/health/source-kind.ts` 头注）：v1/v2 早期线（未考证）与
+    v3（0.1.6 时代，待考证）旧行合法、不动（宿主 v3→v4 迁移负责）；**v4（≥0.1.7-rc.1）拒绝
+    旧署名**，观测到即 warn。
+  - v4 之前的版本线记 ok 不抬档——不越权处理宿主迁移契约内的数据（防过度操作）。
+- **转换（显式触发）**：新增 API `session-health-source-migrate` 与体检面板「转换旧署名」按钮
+  （仅 source-kind 门 warn 时出现）。把 `{ kind: 'plugin', plugin: N }` 改写为
+  `{ kind: 'plugin:N' }`（删除 plugin 字段），其余字节原样保留。
+- **红线三闸**：只动 source 署名字段；改前整文件备份（`*.pre-sourcemigrate-<ts>`，可回退）；
+  完整性不合格（撕裂尾帧/解码失败/seq 缺口）或 header.version < 4 时拒绝执行。这是
+  「禁止改写会话日志」红线的唯一显式例外，经用户逐会话触发。
+- genui 不在掌控范围，本插件不做也不会替它转换（其历史行转换后由其读回判断自行失配与否自负）。
+
+## 0.1.0-alpha.6
+
+### 修复 —— 图标与文案间距收紧；窄栏下不再挤掉邻居
+
+- **间距 8px → 4px**：`🧭` 与「会话管家」之间的空隙按实测收紧（用户反馈「icon 文字间隔小点」）。
+  同时把自身内边距从 `0 12px 0 10px` 收到 `0 10px 0 8px`，与相邻「搜索」胶囊的左右内边距一致。
+- **自己会缩，不再把邻居挤扁**：`.dss_entryWrap` 由 `flex:none` 改为 `flex:0 1 auto; min-width:0`，
+  外层前距 `8px → 6px`。它此前从不让位，缺口全落在搜索胶囊上，把对方标签挤成一个字；
+  现在空间不足时先由自己承担（标签带省略号收尾）。
+- **轨道尺寸回到 28×28**：轨道内容盒只有 36px（56px 轨道 − 2×10px 内边距），两个入口同处一行装不下
+  两个 36px 控制盒（实测 36+28=64px，溢出 14px）。取 28+28=56px，比改动前的 32+28=60px 还窄。
+- **协同边界未变**：依旧只动自己的 CSS，不引用搜索索引任何值，也不假设其是否安装；
+  两者都装时整行自然宽度 217px，单独存在时各占整行。
+
+## 0.1.0-alpha.5
+
+### 变更 —— 侧边栏入口带文案，与「搜索索引」同行自适应
+
+- **入口有名字了**：脚部入口原先是 28×28 的单个图标圆钮（🧭），既没有文案，也说不清点开是什么。
+  宽栏下改为 42px 行控件：**🧭 会话管家**，与相邻的「搜索」胶囊同高、同圆角（12px）、同字号。
+- **同一行的几何协同**：搜索入口声明 `flex:1;min-width:0` 后不再独占整行，两个入口作为
+  `sidebar.footer.action` 的兄弟项共处一行；本入口在宽栏加 `margin-left:8px` 让出间距
+  （对照官方 `ui-settings-general` 的 `.triggerRow{gap:8px}`）。本插件不知道对方是否存在、也不引用对方任何值——
+  协同只发生在各自的 CSS 上。
+- **收起轨道退化**：`wide=false` 时按钮走 `.dss_footerEntryRail`（36×36 圆、不带文案），与 Figma 轨道规范
+  （56px 轨道 / 10px 内边距 / 36×36 控制盒）及官方轨道控件一致；文案与宽栏同条件出现。
+- **文案归属修正**：组件里硬编码的 `'会话管家'` 兜底已删除，入口文案与面板标题同源（字典 `panel.title`），
+  词典仍是唯一出处。
+
+### 变更 —— 一个动词拆成两个：「取消归档状态」与「清理归档文件」
+
+**问题不是措辞，是语义**。此前面板只有一个操作，按钮却叫「删除选中」——
+它既不是删除（一个字节都没删），也不只做一件事（改了数组，就宣称「删除」）。
+于是同一个动作被叫成三个名字（删除 / 清理 / 移除），玩家和实现者对不上。
+
+现在拆成两个**独立路由、独立按钮、独立确认弹窗**的操作：
+
+| | 取消归档状态 | 清理归档文件 |
+|---|---|---|
+| 路由 | `session-history-prune` | **`session-history-purge`**（新增） |
+| 改什么 | 只改 `global.archivedSessionIds` | 删磁盘实体 **+** 改两处 id |
+| 磁盘文件 | 原样不动 | **消失** |
+| 会话去向 | 回到侧边栏原工作区 | 从世界上消失 |
+| 可逆 | ✅ 重启即生效 | ❌ **不可逆** |
+
+「清理归档文件」一次动 4 处：
+
+1. `~/.dsh/sessions/<工作区>/<会话id>/` —— **整个目录**。实测 3 个目录里同时存在
+   `session.jsonl.zstd` 与旧格式 `session.v3.jsonl.zstd`，只删当前格式那份会留下垃圾。
+2. `~/.dsh/storages/session_projcache/sessions/<会话id>.json` —— 逐条投影缓存。
+   > 注意另有一个 `storages/session_projcache.json`（整份布局，99.4 MB，最后写入停留在
+   > 09-11）：那是布局迁移留下的**化石**，宿主早已不写它，本插件也不碰它。
+   > 活的投影缓存是 `session_projcache/sessions/`（实测 143.4 MB / 275 条，今天仍在写）。
+3. `workspace.json` → `global.archivedSessionIds`
+4. `workspace.json` → `tables.workspaces.*.sessionIds`
+
+**清理必须连带取消归档**：文件删了、id 还留在数组里就是僵尸归档 ——
+侧边栏看不见它，一旦被取消归档又会冒出一个打不开的空会话。
+
+**执行顺序是「先改文件、后删实体」**：改文件是原子的且可整体中止
+（存储文件不可用时**一个字节都不删**）；反过来先删实体再改文件，中途失败会留下僵尸 id。
+
+**破坏性操作的护栏**：
+
+- 缺 `dshHome` 直接拒绝执行 —— 不接受猜测的路径；
+- 删除前用 `isSafeChild` 断言目标是预期 root 的**指定层数**子项
+  （拼错一层就是删掉整个 `sessions` 根）；
+- 逐条独立，失败只记不抛，返回 `failures` 明细，面板逐条列出；
+- 沿用一个写入口 `editWorkspaceDocument`（备份 + 同目录临时写入 + 原子改名）。
+
+### 变更 —— 体积按「勾选单元」算，不给总量
+
+单条会话的占用差异极大（实测：某条投影缓存 23.47 MB 而转录只有 0.07 MB；
+也有 0 字节的）。因此：
+
+- **每一行**显示自己的 `转录 6.2 MB · 缓存 2.3 MB`；
+- 列表头显示 `共 72 条 · 占 98.6 MB`；
+- 按钮显示**所选小计**：`清理归档文件 (3) · 释放 38.2 MB`；
+- 确认弹窗逐条列体积 + 合计。
+
+### 修复 —— 养老院清理后「没反应」：读的人和写的人不是同一份数据
+
+**症状**：编辑模式勾选归档会话 → `confirm` → 提示清理成功，但列表**一条没少**、
+面板也没有任何可见变化，看起来完全没生效。
+
+**根因**：两个路由各认一份数据，且**互不相通**。
+
+| 路由 | 认的那份 |
+|---|---|
+| `session-history-prune` | 存储文件 `~/.dsh/storages/workspace.json` 的 `global.archivedSessionIds`（备份 + 原子替换） |
+| `session-history-list` | **宿主内存 `workspaceRegistry.archivedSessionIds` 优先**（只有文件读不到才回退） |
+
+`registry` 是宿主**启动时**载入的快照，直接编辑文件不会回写它。于是：
+
+- 文件真的在瘦身（实测 166 → 159 → 151 → 103 → 72 → 71，每次确认都留下 `.bak-*` 备份）；
+- 列表却永远返回同一批 —— 用户按同一顺序勾选，每次都在删「列表里的头几条」，
+  而列表压根不变，所以观感是「点了确认，什么都没发生」。
+
+**修法**：让列表与 prune **同源**。
+
+- `readArchiveSet` 改为**存储文件优先**，`registry` 退居文件缺失时的兜底；
+  registry 仍被读取，但只作为诊断面（`registryIds`）返回。
+- `session-history-list` 新增 `pendingRestart`：registry 里**有**、文件里**没有**的 id 数
+  —— 即「已清理落盘、但本进程仍生效」的悬挂项。面板据此显示黄色提示，
+  并标出列表总条数，让「少了一条」肉眼可验。
+- `pruneHistory` 增加**写后校验**：写回后重新读文件确认目标 id 确实消失，
+  否则如实报错，不再出现「面板说成功、文件其实没变」。
+
+### 已知风险 —— 宿主会把整份内存快照写回，清理可能被「复活」
+
+存储层（`dsh-storage-json`）是**全量重写、内存为准**：每次写都用内存状态
+`serialize` 整份文档覆盖文件，且没有独立的关停 flush。所以清理之后、重启之前，
+**任何一次归档或工作区改动都会把旧的 `archivedSessionIds` 整份写回**，本次清理归零。
+
+这不是本插件的 bug（官方没有 unarchive 端点，文件是唯一可写面），
+但必须让用户知道 —— 已在 confirm 弹窗与成功提示里写明：**清理后请立刻重启 DSH**。
+
+## 0.1.0-alpha.4
+
+设置卡补回抽屉形态：此前只剩裸行，在「插件」设置分区里与其它插件不一致。
+
+### 修复
+
+- **设置卡缺少抽屉外壳（重要）**：DSH 的「插件」设置分区（`dsh-client-ui-settings-plugins`）
+  只做一件事——按 settings 命名空间分发 `settings.plugin.item`：
+
+      renderSlot('settings.plugin.item', {}, { entryKey: ns })
+
+  它**不提供任何外壳**：卡片的标题、说明、展开/收起全归插件自己所有。
+  本插件此前只渲染了裸行，于是有两处不对：
+  1. 在分区里与其它插件的「可折叠抽屉」形态不一致；
+  2. `card.title`（会话管家）与 `card.desc`（历史文件 · 健康检查）**定义了却从未被渲染**，
+     成了死文案——这正是「漏加的抽屉项」。
+
+  现在补回头部（标题 + 说明 + chevron，整块可点切换），主体默认收起，
+  与同分区其它卡片一致；`aria-expanded` 同步反映展开态。
+- **设置服务不可用时的表现**：原先整个卡片退化成一行「设置服务不可用」，
+  并因此**连标题一起丢掉**；现在抽屉头照常渲染，只在主体里说明原因——
+  这个插件不会在分区里彻底消失。
+
+### 变更
+
+- 展开态切换与 chevron 旋转遵循 `prefers-reduced-motion`。
+
+## 0.1.0-alpha.3
+
+体检结果缓存：关面板再打开零延迟出内容，且处置后只更新那一行。
+
+### 新增
+
+- **体检结果缓存（进程内）**：一次完整扫描（分批走满整个语料）后结果留在宿主进程里，
+  面板再次打开直接渲染缓存，不再全量重扫。缓存**只在走满一遍语料后才成型**——
+  扫到一半关掉面板不会留下半份结果冒充完整结论。
+- **`resume` 纯读探测**：`session-health-scan` 新增 `resume: true`，**只读缓存、不做任何扫描**。
+  面板挂载时用它零成本探一次：命中就出内容，不命中就什么都不做
+  （挂载即干重活是上一版被诟病的地方）。同时捎回当前语料总数。
+- **生成时间与刷新入口**：命中缓存时面板显示「结果来自缓存 · N 分钟前」并给出「刷新」
+  （强制全量重扫）。旧结果绝不冒充刚扫的。
+- **语料变化提示**：缓存的语料总数与当前不一致时提示「语料已变化（a → b），建议刷新」。
+  这条对账只做目录枚举，很便宜——所以它不构成新的缓存失效策略。
+
+### 变更
+
+- **单条就地回写**：单会话体检与可逆处置后不再依赖重扫——处置本就重算了 `after` 报告，
+  直接写回缓存；面板退回列表时该行已是最新档位（转好的行从此消失，与「只列问题」一致）。
+- 缓存**不落盘**：DSH 重启即失效。落盘需要失效策略，而判断失效的代价（枚举语料、
+  比对日志 mtime/size）已接近重扫本身，本切片取 YAGNI。
+
+### 测试
+
+- 新增 `tests/cache.spec.ts`（19 例）：成型规则（未走满 / 走满 / 空语料 / 中途中断 / `clear`）、
+  单条回写全分支（新增 / 替换 / 转好移出 / no-op），以及 `handleMethod` 接线
+  （`resume` 不扫描、分批走满后命中、`onlyProblems=false` 不污染缓存、
+  处置后回写的对象身份、缺 cache 的运行时仍可用）。
+
+## 0.1.0-alpha.2
+
+处置（处方）的判定与呈现修正：不再对「无从判定」的门开方，并明确给出处置后的结论。
+
+### 修复
+
+- **对 `skipped` 误开处方（重要）**：`prescribe()` 原先用 `level !== 'ok'` 判断投影缓存是否需要隔离，
+  于是「本门无从判定」也被当成「投影缓存未对齐」，对着自己的证据输出自相矛盾的处方，
+  并建议隔离一条**并不存在**的记录。抽出共享谓词 `isActionable()`（仅 `warn` / `fail` 可处置）统一收口，
+  `gates.ts` 的档位标准与 `repair.ts` 的处置标准自此是同一件事。
+- **「四门全绿」误报**：无处置项时固定回「四门全绿」。当门是 `skipped`（无从判定，而非绿）时该文案不成立；
+  现在改为「无可处置项（N 门无从判定，非异常）：<门 id 列表>」。
+- **处置后仍显示异常，无从判断处置是否生效**：面板只渲染「处置前 / 处置后」两个档位，
+  两者都是异常时无法区分「处置失败」与「处置与病灶无关」。
+  宿主新增 `assessRepair({ before, after, repair })`，判定为五档之一并附人读说明：
+  `nothing-to-do`（四门全绿）/ `repaired`（已恢复）/ `repaired-with-residual`（已隔离缓存，
+  但仍有与该缓存无关的异常，如会话日志的 open step）/ `not-applicable`（当前异常无可逆处置项）/
+  `failed`（处置自身失败）。面板按档位配色渲染结论横幅。
+
+### 说明
+
+- **处置能力未变**：仍是「只隔离投影缓存记录、复制后移动、不改会话日志」，本次只修正**判定**与**呈现**。
+  典型场景是「仅 `cold-read` 异常（会话存在未结算的 open step）」——这类异常本就不该由本插件修复，
+  现在会明确判为 `not-applicable` 并说明原因，而不是静默显示成「处置后还是异常」。
+
+### 测试
+
+- 新增 `tests/repair.spec.ts`（12 例）：覆盖 `isActionable` 的四档、`prescribe` 不再开空方，
+  以及 `assessRepair` 五档判定的分支。
+
+## 0.1.0-alpha.1
+
+体检面板的判定与反馈修正：修掉「注意」全量误报，并补上扫描进度与行内原因。
+
+### 修复
+
+- **「注意」全量误报（重要）**：`lossless-json` / `projection-cache` / `cold-read` 三门在
+  **无从判定**时（冷态会话没有热态投影、缓存记录尚未生成、日志里没有 turn/end）返回 `warn`，
+  导致**所有未加载的会话恒为「注意」**，真信号被淹没。
+  新增中性档 `skipped`（面板文案「未检查」）承载「无从观测」，**不参与总判聚合**。
+  固化的判定标准：`warn` = 观测到异常现象（有据）；`skipped` = 无从观测/无从判定（无据）。
+  实测：30 条会话由「30×注意」变为「26 正常 / 3 注意 / 1 异常」。
+- **列表行不显示触发原因**：体检结果列表只渲染聚合档位，行与行之间不可区分。
+  现在行内列出非 ok 的「门·档位」摘要（如 `可接续性·注意`），无需逐条点开详情。
+
+### 新增
+
+- **体检扫描进度**：`session-health-scan` 支持 `offset` 分批调用并返回 `total`；
+  面板按小批次连续调用、自行累计**真实进度**（`n/total · 已用 Xs`）。
+  首批未拿到分母时走不确定态动画。宿主保持无状态，同步扫描循环无需改异步。
+- **处置忙碌反馈**：可逆处置按钮加 spinner 并保持禁用，避免点击后界面静止。
+
+### 变更
+
+- **页签改名**：`病案室` → `养老院`（英文 `Records Room` → `Retirement Home`），
+  与「体检 / 处方 / 出院」的隐喻统一。
+
+## 0.1.0-alpha.0
+
+首个 alpha 版本：会话管家（历史文件 + 健康检查）。
+
+### 新增
+
+- **会话历史文件（病案室）**：从 `dsh-session-search-toggle` 迁入官方归档集合的读取与清理实现，
+  行为与迁移前等价（备份 + 同目录临时写 + 原子替换；显式编辑模式才允许清理）。
+  差异：列表来源改为**官方归档集合真值**（registry 优先、存储文件回退），因为独立索引已随搜索索引包离开；
+  标题等元数据为尽力而为（`sessionQuery` 标题快照 → 投影缓存 title → 空）。
+- **健康检查（体检 → 处方 → 出院）**：四个可独立测试的 gate
+  （`log-integrity` / `projection-cache` / `lossless-json` / `cold-read`），
+  统一输出 `{ id, level, evidence, attribution, detail }`；聚合为 `SessionHealthReport`。
+- **归属索引**：静态扫描 profile 的 `node_modules/<pkg>/lib/*.js`，建立「投影 key → 包名」，
+  把失败 gate 指回具体插件与字段路径；扫不到时如实标 `unknown`。
+- **可逆处方**：隔离损坏的投影缓存记录（先复制备份，再移动到 `.quarantine-<ts>`）+ 命令清单。
+  **禁止**改写会话日志、改历史数据、静默丢弃字段。
+- **两个 feature gate**：`historyFiles` / `healthCheck`，关闭时对应子域整域不注册（显式 disabled 错误），
+  客户端也不渲染对应页签。
+- **路由**：`/session-steward/api/*`，方法名一律 `session-*`，与搜索索引的 `/switch-search/api` 的 `index-*` 完全隔离。
+
+### 已知限制
+
+- `lossless-json` gate 依赖宿主暴露 `sessionProjections`（热态）才能给出确定判定；
+  拿不到时如实降级为 `warn`，不臆测。
+- 健康扫描默认只列最近 30 个非健康会话（`limit` 上限 200），不做全库遍历的默认行为。
+- 客户端面板为最小实现（列表 + 详情 + 三步按钮），未做虚拟滚动与批量操作。