dsh-claude-move 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [SemVer](https://semver.org/).
 
+## [0.4.0] - 2026-09-04
+
+### Added
+
+- Dual-baseline `sessionPersistence` runtime shim in `index.mjs` (feature-detected by API shape, never by version): the published legacy API (`create`/`append`/`readFrom`, `list()` returning headers) and the unreleased checkout handle seam (`create` returning a `SessionHandle`, `list()`/`stat()` returning snapshots) both work. On the handle path every append is followed by `flush()` (durability barrier) and a paired `close()` (single-writer ownership, released in `finally` on failure); headers are stamped with the backend's current format version (backend-declared `generationFormat.currentVersion`, falling back to a lazy `@deepseek-ai/dsh-session` `SESSION_FORMAT_VERSION` import — never hardcoded) plus an explicit `isSeeded: false`, and missing assistant model sources fall back to the provider string (the checkout backend refuses to read v-mismatched headers or empty model sources — found and fixed by checkout round-trip verification). The legacy path keeps the exact 0.3.x call sequence with no normalization. `lib/` is untouched.
+- Guard against silently clearing `imports.json`: `annotateImports` now resolves `header.id` from both header and snapshot list elements, and throws loudly (skipping `cleanStale`) when an element cannot be resolved — on the handle baseline the old code read `header.id` as `undefined` and `cleanStale` would have wiped every mapping.
+- Dual test suites: a handle-shape `sessionPersistence` mock (create→handle with `read`/`append`/`flush`/`close`, `open(id, access)`, snapshot `list()`) covering the full import/incremental/force/streamed/export flows, paired close (no handle leaks), single-writer conflict loud failures, flush ordering, and header/model normalization; plus legacy-shape regression tests for the mis-clear mapping guard.
+
+### Changed
+
+- `compat.yml` profile pins moved from `0.1.1-rc.2` to `0.1.2-rc.1`, with a workflow note that no published version carries the handle seam, so the handle path can only be verified against a local checkout.
+
+### Notes
+
+- No data-format changes: `index.json`/`imports.json`/`move.json` caches and imported session logs stay interoperable; no re-import needed; the Config schema is unchanged.
+
 ## [0.3.3] - 2026-09-02
 
 ### Changed

package/README.es.md

@@ -25,6 +25,7 @@
 
 - Dirigido a `dsh 0.1.2-alpha.5` (perfil web); las dependencias peer requieren `>=0.1.0-rc.8 <0.2.0`. Node `^22.19 || >=24`.
 0.1.2-alpha.5 (adaptado el 2026-09-02): el sobre de sesión conserva su campo ignorable solo para compatibilidad de lectura de logs almacenados - Session.append aún no puede estamparlo, por lo que el comportamiento de la puerta no cambia.
+- 0.4.0 incluye un shim de doble línea base para `sessionPersistence` en tiempo de ejecución, detectado por la forma de la API (nunca por versión): funcionan tanto la API heredada publicada (`create`/`append`/`readFrom`, `list()` devolviendo cabeceras) como la costura de handle del checkout aún no publicado (`create` devolviendo un `SessionHandle`, `list()`/`stat()` devolviendo instantáneas). En la ruta handle, cada append va seguido de `flush()` (barrera de durabilidad) y un `close()` emparejado (propiedad de escritor único); las cabeceras se sellan con la versión de formato actual del backend y un `isSeeded` explícito, y las fuentes de modelo de asistente ausentes caen al provider — verificado contra el backend real 0.1.3-alpha.1 del checkout. La limpieza del escaneo de importación se niega a ejecutarse cuando el `header.id` de un elemento listado no se puede resolver, por lo que `imports.json` nunca se vacía en silencio. Ninguna versión publicada lleva la costura de handle, así que la ruta handle solo se verifica contra un checkout local (el workflow de compatibilidad cubre la línea publicada).
 - Última verificación con una instalación nueva desde tarball: escaneo real, importación por lotes real (reimportación idempotente), adjuntado al workspace y artefactos de persistencia confirmados; macOS/Linux cubiertos por la matriz de CI.
 
 ### Matriz de compatibilidad (solo costuras públicas)
@@ -32,7 +33,8 @@
 | Superficie | Uso | Respaldo cuando falta |
 |---|---|---|
 | Servicios de host (`tools` / `sessionPersistence` / `workspaceRegistry` / `commands` / `systemPrompt` / `skills` / `webServer`) | obligatorio donde se indica | los servicios opcionales se registran reactivamente; la falta de `fs` falla en voz alta |
-| `sessionPersistence.listSnapshots` / `readFrom` / `fs` con capacidad `streamText` / `ctx.jobs` / `ctx.agents.resume` | detectado por característica | `list()` / lectura de archivo completo con rechazo en voz alta / mapa de jobs propio / inyección de traspaso |
+| `sessionPersistence` doble línea base: heredada `listSnapshots` / `readFrom` / `append` frente a handle `open` / `stat` / `list()` de instantáneas | detectado por característica en tiempo de ejecución (forma de API, nunca versión) | la guarda de resolución de `header.id` aborta el escaneo en voz alta en vez de vaciar `imports.json` en silencio |
+| `fs` con capacidad `streamText` / `ctx.jobs` / `ctx.agents.resume` | detectado por característica | lectura de archivo completo con rechazo en voz alta / mapa de jobs propio / inyección de traspaso |
 | Servicios de shell del cliente (`sessions.refresh/open`, `workspaces.refresh`) | detectado por característica al aplicar el panel | recarga completa de la página |
 | Las capacidades de plataforma más nuevas nunca son requisitos estrictos — el plugin sigue arrancando en rc.8. | | |
 
@@ -308,6 +310,10 @@ Este proyecto es uno de los [33 complementos de DeepSeek Harness](https://github
 | **[dsh-dsh-test-drive](https://github.com/PerryLink/dsh-dsh-test-drive)** | Pruebas de instalación y humo aisladas para plugins de DeepSeek Harness. | |
 | **[dsh-dsh-translate](https://github.com/PerryLink/dsh-dsh-translate)** | Traducción de parámetros entre proveedores y reparación determinista de JSON para DeepSeek Harness. | |
 
+### Instalar desde el mercado de DSH Desktop
+
+Todos los plugins de PerryLink pueden explorarse en el mercado integrado de DSH Desktop: **Market → Sources → add source → pegar** `https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json` **→ seleccionarlo**. La instalación sigue pasando por la verificación de identidad npm del mercado y tu confirmación.
+
 ## Licencia
 
 [Apache License 2.0](LICENSE) © 2026 dsh-claude-move contributors

package/README.hi.md

@@ -25,6 +25,7 @@
 
 - `dsh 0.1.2-alpha.5` (web profile) को लक्षित करता है; peer निर्भरताएँ `>=0.1.0-rc.8 <0.2.0` चाहिए। Node `^22.19 || >=24`।
 0.1.2-alpha.5 (2026-09-02 को अनुकूलित): सत्र लिफ़ाफ़ा अपना ignorable फ़ील्ड केवल संग्रहीत-लॉग पठन संगतता के लिए रखता है - Session.append अभी भी इसे स्टैम्प नहीं कर सकता, इसलिए गेट व्यवहार अपरिवर्तित है।
+- 0.4.0 में `sessionPersistence` के लिए दोहरी-बेसलाइन रनटाइम shim शामिल है, जिसे API आकार से पहचाना जाता है (संस्करण से कभी नहीं): प्रकाशित लीगेसी API (`create`/`append`/`readFrom`, `list()` हेडर लौटाता है) और अप्रकाशित checkout की हैंडल सीम (`create` एक `SessionHandle` लौटाता है, `list()`/`stat()` स्नैपशॉट लौटाते हैं) दोनों काम करते हैं। हैंडल पथ पर हर append के बाद `flush()` (स्थायित्व अवरोध) और युग्मित `close()` (एकल-लेखक स्वामित्व) होता है; हेडर पर बैकएंड का वर्तमान प्रारूप संस्करण और स्पष्ट `isSeeded` अंकित होता है, तथा अनुपस्थित assistant model स्रोत provider पर गिरते हैं — वास्तविक 0.1.3-alpha.1 बैकएंड के विरुद्ध checkout-सत्यापित। जब किसी सूचीबद्ध तत्व का `header.id` हल नहीं हो पाता तो आयात-स्कैन की सफ़ाई चलने से मना कर देती है, इसलिए `imports.json` कभी चुपचाप खाली नहीं होता। किसी भी प्रकाशित संस्करण में हैंडल सीम नहीं है, इसलिए हैंडल पथ केवल स्थानीय checkout के विरुद्ध सत्यापित होता है (compat वर्कफ़्लो प्रकाशित लाइन को कवर करता है)।
 - अंतिम बार एक ताज़ा tarball इंस्टॉल के विरुद्ध सत्यापित: वास्तविक स्कैन, वास्तविक बैच आयात (आइडेम्पोटेंट पुनः-आयात), workspace जुड़ाव और पर्सिस्टेंस आर्टिफैक्ट की पुष्टि; macOS/Linux CI मैट्रिक्स द्वारा कवर हैं।
 
 ### अनुकूलता मैट्रिक्स (केवल सार्वजनिक सीम)
@@ -32,7 +33,8 @@
 | सतह | उपयोग | अनुपस्थित होने पर फ़ॉलबैक |
 |---|---|---|
 | Host सेवाएँ (`tools` / `sessionPersistence` / `workspaceRegistry` / `commands` / `systemPrompt` / `skills` / `webServer`) | जहाँ सूचीबद्ध वहाँ आवश्यक | वैकल्पिक सेवाएँ प्रतिक्रियात्मक रूप से पंजीकृत होती हैं; `fs` अनुपस्थित होने पर ज़ोर से विफल |
-| `sessionPersistence.listSnapshots` / `readFrom` / `streamText`-सक्षम `fs` / `ctx.jobs` / `ctx.agents.resume` | फ़ीचर-डिटेक्टेड | `list()` / पूरी फ़ाइल पढ़ना और ज़ोर से अस्वीकार / स्वयं का job map / हैंडऑफ़ इंजेक्ट |
+| `sessionPersistence` दोहरी बेसलाइन: लीगेसी `listSnapshots` / `readFrom` / `append` बनाम हैंडल `open` / `stat` / स्नैपशॉट `list()` | रनटाइम पर फ़ीचर-डिटेक्टेड (API आकार, संस्करण कभी नहीं) | `header.id` रिज़ॉल्यूशन गार्ड स्कैन को ज़ोर से रोक देता है, `imports.json` चुपचाप खाली करने के बजाय |
+| `streamText`-सक्षम `fs` / `ctx.jobs` / `ctx.agents.resume` | फ़ीचर-डिटेक्टेड | पूरी फ़ाइल पढ़ना और ज़ोर से अस्वीकार / स्वयं का job map / हैंडऑफ़ इंजेक्ट |
 | Client shell सेवाएँ (`sessions.refresh/open`, `workspaces.refresh`) | पैनल apply पर फ़ीचर-डिटेक्टेड | पूर्ण-पृष्ठ रीलोड |
 | नई प्लेटफ़ॉर्म क्षमताएँ कभी कठोर आवश्यकताएँ नहीं होतीं — प्लगइन rc.8 पर बूट होने योग्य रहता है। | | |
 
@@ -308,6 +310,10 @@ CI GitHub Actions ([test.yml](.github/workflows/test.yml)) के माध्
 | **[dsh-dsh-test-drive](https://github.com/PerryLink/dsh-dsh-test-drive)** | DeepSeek Harness प्लगिनों के लिए पृथक इंस्टॉल-एंड-स्मोक टेस्ट ड्राइव। | |
 | **[dsh-dsh-translate](https://github.com/PerryLink/dsh-dsh-translate)** | DeepSeek Harness के लिए वेंडर पैरामीटर अनुवाद और नियतात्मक JSON मरम्मत। | |
 
+### DSH Desktop मार्केट से इंस्टॉल करें
+
+सभी PerryLink प्लगइन DSH Desktop के बिल्ट-इन मार्केट में देखे जा सकते हैं: **Market → Sources → add source → पेस्ट करें** `https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json` **→ चुनें**। इंस्टॉलेशन मार्केट के npm-identity सत्यापन और आपकी पुष्टि से ही होता है।
+
 ## लाइसेंस
 
 [Apache License 2.0](LICENSE) © 2026 dsh-claude-move contributors

package/README.md

@@ -26,6 +26,7 @@
 
 - Targets `dsh 0.1.2-alpha.5` (web profile); peer dependencies require `>=0.1.0-rc.8 <0.2.0`. Node `^22.19 || >=24`.
 0.1.2-alpha.5 (adapted 2026-09-02): the session envelope keeps its ignorable field for stored-log read compatibility only - Session.append still cannot stamp it, so audit-gate behavior is unchanged.
+- 0.4.0 ships a dual-baseline `sessionPersistence` runtime shim, feature-detected by API shape (never by version): the published legacy API (`create`/`append`/`readFrom`, `list()` returning headers) and the unreleased checkout handle seam (`create` returning a `SessionHandle`, `list()`/`stat()` returning snapshots) both work. On the handle path every append is followed by `flush()` (durability barrier) and a paired `close()` (single-writer ownership); headers are stamped with the backend's current format version plus an explicit `isSeeded`, and missing assistant model sources fall back to the provider — checkout-verified against the real 0.1.3-alpha.1 backend. Import-scan cleanup refuses to run when a listed element's `header.id` cannot be resolved, so `imports.json` is never silently cleared. No published version carries the handle seam, so the handle path is verified against a local checkout only (the compat workflow covers the published line).
 - Last verified against a fresh tarball install: real scan, real batch import (idempotent re-import), workspace attach and persistence artifacts confirmed; macOS/Linux covered by the CI matrix.
 
 ### Compatibility matrix (public seams only)
@@ -33,7 +34,8 @@
 | Surface | Used | Fallback when absent |
 |---|---|---|
 | Host services (`tools` / `sessionPersistence` / `workspaceRegistry` / `commands` / `systemPrompt` / `skills` / `webServer`) | required where listed | optional services register reactively; missing `fs` fails loud |
-| `sessionPersistence.listSnapshots` / `readFrom` / `streamText`-capable `fs` / `ctx.jobs` / `ctx.agents.resume` | feature-detected | `list()` / whole-file read with loud rejection / own job map / handoff inject |
+| `sessionPersistence` dual baseline: legacy `listSnapshots` / `readFrom` / `append` vs handle `open` / `stat` / snapshot `list()` | feature-detected at runtime (API shape, never version) | the `header.id` resolution guard aborts the scan loudly instead of silently clearing `imports.json` |
+| `streamText`-capable `fs` / `ctx.jobs` / `ctx.agents.resume` | feature-detected | whole-file read with loud rejection / own job map / handoff inject |
 | Client shell services (`sessions.refresh/open`, `workspaces.refresh`) | feature-detected at panel apply | full-page reload |
 | Newer platform capabilities are never hard requirements — the plugin stays bootable on rc.8. | | |
 
@@ -309,6 +311,10 @@ This project is one of the [33 DeepSeek Harness plugins](https://github.com/Perr
 | **[dsh-dsh-test-drive](https://github.com/PerryLink/dsh-dsh-test-drive)** | Isolated install-and-smoke test drives for DeepSeek Harness plugins. | |
 | **[dsh-dsh-translate](https://github.com/PerryLink/dsh-dsh-translate)** | Vendor parameter translation and deterministic JSON repair for DeepSeek Harness. | |
 
+### Install from the DSH Desktop Market
+
+All PerryLink plugins are browsable in the built-in DSH Desktop Market: **Market → Sources → add source → paste** `https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json` **→ select it**. Installation still goes through the Market's npm-identity verification and your confirmation.
+
 ## License
 
 [Apache License 2.0](LICENSE) © 2026 dsh-claude-move contributors

package/README.pt.md

@@ -25,6 +25,7 @@
 
 - Direcionado a `dsh 0.1.2-alpha.5` (perfil web); dependências peer exigem `>=0.1.0-rc.8 <0.2.0`. Node `^22.19 || >=24`.
 0.1.2-alpha.5 (adaptado em 2026-09-02): o envelope de sessão mantém seu campo ignorable apenas para compatibilidade de leitura de logs armazenados - o Session.append ainda não consegue estampá-lo, então o comportamento da porta não muda.
+- A 0.4.0 inclui um shim de linha de base dupla para `sessionPersistence` em tempo de execução, detectado pela forma da API (nunca pela versão): funcionam tanto a API legada publicada (`create`/`append`/`readFrom`, `list()` retornando cabeçalhos) quanto a costura de handle do checkout ainda não publicado (`create` retornando um `SessionHandle`, `list()`/`stat()` retornando snapshots). No caminho handle, todo append é seguido de `flush()` (barreira de durabilidade) e um `close()` pareado (propriedade de escritor único); os cabeçalhos são carimbados com a versão de formato atual do backend e um `isSeeded` explícito, e fontes de modelo de assistente ausentes caem para o provider — verificado contra o backend real 0.1.3-alpha.1 do checkout. A limpeza da varredura de importação se recusa a executar quando o `header.id` de um elemento listado não pode ser resolvido, então `imports.json` nunca é esvaziado silenciosamente. Nenhuma versão publicada tem a costura de handle, então o caminho handle só é verificado contra um checkout local (o fluxo de compatibilidade cobre a linha publicada).
 - Última verificação contra uma instalação nova de tarball: varredura real, importação em lote real (reimportação idempotente), anexo ao workspace e artefatos de persistência confirmados; macOS/Linux cobertos pela matriz de CI.
 
 ### Matriz de compatibilidade (somente costuras públicas)
@@ -32,7 +33,8 @@
 | Superfície | Uso | Fallback quando ausente |
 |---|---|---|
 | Serviços de host (`tools` / `sessionPersistence` / `workspaceRegistry` / `commands` / `systemPrompt` / `skills` / `webServer`) | obrigatório onde listado | serviços opcionais registram reativamente; `fs` ausente falha em voz alta |
-| `sessionPersistence.listSnapshots` / `readFrom` / `fs` com capacidade `streamText` / `ctx.jobs` / `ctx.agents.resume` | detectado por recurso | `list()` / leitura de arquivo inteiro com rejeição em voz alta / mapa de jobs próprio / injeção de handoff |
+| `sessionPersistence` linha de base dupla: legada `listSnapshots` / `readFrom` / `append` versus handle `open` / `stat` / `list()` de snapshots | detectado por recurso em tempo de execução (forma da API, nunca versão) | a guarda de resolução de `header.id` aborta a varredura em voz alta em vez de esvaziar `imports.json` silenciosamente |
+| `fs` com capacidade `streamText` / `ctx.jobs` / `ctx.agents.resume` | detectado por recurso | leitura de arquivo inteiro com rejeição em voz alta / mapa de jobs próprio / injeção de handoff |
 | Serviços de shell do cliente (`sessions.refresh/open`, `workspaces.refresh`) | detectado por recurso ao aplicar o painel | recarga completa da página |
 | Capacidades de plataforma mais novas nunca são requisitos rígidos — o plugin continua inicializável no rc.8. | | |
 
@@ -308,6 +310,10 @@ Este projeto é um dos [33 plugins de DeepSeek Harness](https://github.com/Perry
 | **[dsh-dsh-test-drive](https://github.com/PerryLink/dsh-dsh-test-drive)** | Test drives isolados de instalação e smoke para plugins de DeepSeek Harness. | |
 | **[dsh-dsh-translate](https://github.com/PerryLink/dsh-dsh-translate)** | Tradução de parâmetros entre fornecedores e reparo determinístico de JSON para DeepSeek Harness. | |
 
+### Instalar a partir do mercado do DSH Desktop
+
+Todos os plugins PerryLink podem ser explorados no mercado integrado do DSH Desktop: **Market → Sources → add source → colar** `https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json` **→ selecionar**. A instalação continua passando pela verificação de identidade npm do mercado e pela sua confirmação.
+
 ## Licença
 
 [Apache License 2.0](LICENSE) © 2026 dsh-claude-move contributors

package/README.zh.md

@@ -25,6 +25,7 @@
 
 - 面向 `dsh 0.1.2-alpha.5`（web profile）；peer 依赖要求 `>=0.1.0-rc.8 <0.2.0`。Node `^22.19 || >=24`。
 0.1.2-alpha.5（2026-09-02 已适配）：会话信封保留 ignorable 字段但仅用于存量日志读取兼容——Session.append 仍无法盖章，门控行为不变。
+- 0.4.0 内置 `sessionPersistence` 双基线运行时 shim，按 API 形状特性探测（绝不按版本号猜测）：已发布旧 API（`create`/`append`/`readFrom`，`list()` 返回会话头）与未发布 checkout 的 handle seam（`create` 返回 `SessionHandle`，`list()`/`stat()` 返回快照）都能工作。handle 路径上每次 append 之后必须 `flush()`（耐久屏障）并成对 `close()`（单写所有权）；header 盖上后端当前格式版本并显式补 `isSeeded`，缺失的 assistant model 来源回退 provider——已对照真实 0.1.3-alpha.1 后端做 checkout 实测。导入扫描的清理在列表元素的 `header.id` 无法解析时拒绝执行，绝不静默清空 `imports.json`。任何已发布版本都没有 handle seam，因此 handle 路径只能对照本地 checkout 验证（compat workflow 覆盖已发布线）。
 - 最近针对全新 tarball 安装验证：真实扫描、真实批量导入（幂等重导入）、工作区挂载与持久化产物均已确认；macOS/Linux 由 CI 矩阵覆盖。
 
 ### 兼容性矩阵（仅公开接缝）
@@ -32,7 +33,8 @@
 | 接缝 | 使用 | 缺失时的回退 |
 |---|---|---|
 | Host 服务（`tools` / `sessionPersistence` / `workspaceRegistry` / `commands` / `systemPrompt` / `skills` / `webServer`） | 所列之处必需 | 可选服务响应式注册；缺失 `fs` 大声失败 |
-| `sessionPersistence.listSnapshots` / `readFrom` / 支持 `streamText` 的 `fs` / `ctx.jobs` / `ctx.agents.resume` | 特性探测 | `list()` / 整文件读取并大声拒绝 / 自有 job map / 交接注入 |
+| `sessionPersistence` 双基线：旧 API（`listSnapshots` / `readFrom` / `append`）或 handle（`open` / `stat`、快照 `list()`） | 运行时按 API 形状特性探测 | `header.id` 解析守卫：解析失败大声中止扫描，绝不静默清空 `imports.json` |
+| 支持 `streamText` 的 `fs` / `ctx.jobs` / `ctx.agents.resume` | 特性探测 | 整文件读取并大声拒绝 / 自有 job map / 交接注入 |
 | Client shell 服务（`sessions.refresh/open`、`workspaces.refresh`） | 面板 apply 时特性探测 | 整页刷新 |
 | 较新的平台能力从不是硬性要求 —— 插件在 rc.8 上始终保持可启动。 | | |
 
@@ -308,6 +310,10 @@ CI 通过 GitHub Actions（[test.yml](.github/workflows/test.yml)）在 Linux/ma
 | **[dsh-dsh-test-drive](https://github.com/PerryLink/dsh-dsh-test-drive)** | DeepSeek Harness 插件的隔离试装冒烟。 | |
 | **[dsh-dsh-translate](https://github.com/PerryLink/dsh-dsh-translate)** | DeepSeek Harness 的厂商参数翻译与确定性 JSON 修复。 | |
 
+### 从 DSH Desktop 市场安装
+
+所有 PerryLink 插件均可在 DSH Desktop 内置市场中浏览：**市场 → 来源 → 添加来源 → 粘贴** `https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json` **→ 选中**。安装仍需通过市场的 npm 身份校验与你的确认。
+
 ## 许可证
 
 [Apache License 2.0](LICENSE) © 2026 dsh-claude-move contributors

package/index.mjs

@@ -10,6 +10,8 @@
 //
 // 只消费公开服务：tools / systemPrompt / skills / sessionPersistence /
 // workspaceRegistry / commands / webServer / approval（后几者经 ctx.get 可选读取）。
+// sessionPersistence 走 0.4.0 双基线运行时 shim（handle 基线 / 旧 API，见下方
+// "双基线运行时 shim" 段），任何已发布 dsh 与 checkout HEAD 均可工作。
 // 源文件只读，缓存只写 resolveCacheDir()；迁移落点只写 $DSH_HOME/skills、
 // $DSH_HOME/AGENTS.md 与 imports 工作区目录。
 
@@ -63,6 +65,205 @@ export const name = 'claude-move'
 
 export const inject = ['tools']
 
+// ── sessionPersistence 双基线运行时 shim（0.4.0）──────────────────────────────
+//
+// 宿主 master（0.1.3-alpha.1，bec6805d6a refactor）把 sessionPersistence 改成
+// handle 化：create 返回 SessionHandle（read/append/flush/close；close 释放
+// 单写所有权），服务级 append/readFrom/locate/listSnapshots 移除，list()/stat()
+// 返回快照对象（{ header, revision, eventCount?, sizeBytes? }）。任何已发布
+// 版本（≤0.1.2-rc.1）都没有该 seam，仍是旧 API：create 返回 void、服务级
+// append/readFrom、list() 返回 SessionHeader、listSnapshots 返回 { header }。
+// 两个基线一律按运行时 API 形状探测（create 返回值 / 服务成员 / list 元素），
+// 绝不按版本号猜测。handle 路径上每次 append 后必须 flush()（耐久屏障）并
+// 成对 close()（单写所有权），header/事件经 normalizeHandleHeader /
+// normalizeHandleEvents 规范化到后端当前格式（checkout 实测：版本戳与
+// isSeeded 缺一不可，model source 必须非空）；旧路径的调用序列与 0.3.x
+// 逐字节一致，不做任何规范化。
+
+const persistenceShapeCache = new WeakMap()
+
+/** create 返回值是否 SessionHandle（handle 基线的最权威判定）。 */
+function isSessionHandle(value) {
+  return value !== null && typeof value === 'object'
+    && typeof value.read === 'function'
+    && typeof value.append === 'function'
+    && typeof value.flush === 'function'
+    && typeof value.close === 'function'
+}
+
+/**
+ * 探测服务基线（API 形状，非版本号）：有 open（旧 API 无）→ handle；
+ * 有 readFrom/append（handle 化后均无）→ legacy；其余未知。create 实测结果
+ * 可经 notePersistenceShape 覆写缓存。
+ * @param sp - sessionPersistence 服务。
+ * @returns 'handle' | 'legacy' | null。
+ */
+function detectPersistenceShape(sp) {
+  if (!sp) return null
+  const cached = persistenceShapeCache.get(sp)
+  if (cached !== undefined) return cached
+  if (typeof sp.open === 'function') return 'handle'
+  if (typeof sp.readFrom === 'function' || typeof sp.append === 'function') return 'legacy'
+  return null
+}
+
+/** 记录实测基线（create 返回值判定优先，供后续 append/read 调用复用）。 */
+function notePersistenceShape(sp, shape) {
+  if (sp && (shape === 'handle' || shape === 'legacy')) persistenceShapeCache.set(sp, shape)
+}
+
+/** 列表元素无法解析 header.id 的哨兵错误：annotateImports 用它响亮失败并跳过清理。 */
+class StoredSessionIdResolutionError extends Error {}
+
+/**
+ * 从 list()/listSnapshots() 元素解析存储会话 id：handle 基线的快照对象取
+ * header.id，旧基线的 SessionHeader 取 id。两者都解析不出 → null。
+ * @param element - 列表元素。
+ * @returns 会话 id 或 null。
+ */
+function storedSessionIdOf(element) {
+  if (element !== null && typeof element === 'object') {
+    if (element.header !== null && typeof element.header === 'object'
+      && typeof element.header.id === 'string' && element.header.id.length > 0) {
+      return element.header.id
+    }
+    if (typeof element.id === 'string' && element.id.length > 0) return element.id
+  }
+  return null
+}
+
+/**
+ * 列表元素序列 → id 数组。任一元素无法解析 header.id 即响亮抛出——这是
+ * cleanStale 误清空防线：id 集合必须完整可解析，绝不允许把 undefined 塞进
+ * 集合让「映射指向已不存在会话」全量误判。
+ * @param elements - list()/listSnapshots() 返回的元素序列。
+ * @returns id 数组。
+ */
+function idsOfListedElements(elements) {
+  return elements.map((element) => {
+    const id = storedSessionIdOf(element)
+    if (id === null) {
+      throw new StoredSessionIdResolutionError(
+        'sessionPersistence 列表元素无法解析 header.id（既非 SessionHeader 也非快照对象）：'
+        + 'claude-move 拒绝继续，防止 imports.json 导入映射被误清空')
+    }
+    return id
+  })
+}
+
+/**
+ * 读一份已存储会话的完整事件与头（双基线）：handle 路径 open(id, 'read') →
+ * read(0) → close（读句柄绝不持有写所有权）；旧路径 readFrom(id, 0)。
+ * 基线无法判定返回 null；会话不存在时抛出后端错误。
+ * @param sp - sessionPersistence 服务。
+ * @param id - 会话 id。
+ * @returns `{ meta, events }` 或 null。
+ */
+async function readStoredEvents(sp, id) {
+  const shape = detectPersistenceShape(sp)
+  if (shape === 'handle') {
+    const handle = await sp.open(id, 'read')
+    try {
+      const events = await handle.read(0)
+      return { meta: handle.header, events }
+    } finally {
+      await handle.close()
+    }
+  }
+  if (shape === 'legacy' && typeof sp.readFrom === 'function') {
+    const suffix = await sp.readFrom(id, 0)
+    return { meta: suffix?.meta, events: suffix?.events }
+  }
+  return null
+}
+
+// handle 基线 header/事件规范化（0.4.0 checkout 实测）：checkout 后端给所有
+// 产物盖当前格式版本的文件名，并要求 header.version 等于后端当前
+// SESSION_FORMAT_VERSION、isSeeded 显式给出；读取时还会按当前格式语义校验
+// assistant/message 的 model source 必须是非空字符串。旧基线不需要这些，
+// 规范化只发生在 handle 路径。
+
+const handleFormatVersionCache = new WeakMap()
+
+/**
+ * 惰性读取 handle 基线的当前会话格式版本（绝无硬编码、绝不按版本号猜测）：
+ * 首选后端实例自报的 generationFormat.currentVersion（checkout JSONL 后端
+ * 公开字段），回退宿主 `@deepseek-ai/dsh-session` 的 SESSION_FORMAT_VERSION
+ * 导出。两者都不可得返回 null（header 保持原样，后端读取时响亮拒绝，绝不
+ * 静默写坏）。
+ * @param sp - sessionPersistence 服务。
+ * @returns 当前格式版本号或 null。
+ */
+async function currentHandleFormatVersion(sp) {
+  const cached = handleFormatVersionCache.get(sp)
+  if (cached !== undefined) return cached
+  let version = null
+  const backend = sp?.generationFormat
+  if (backend !== null && typeof backend === 'object'
+    && Number.isSafeInteger(backend.currentVersion) && backend.currentVersion >= 0) {
+    version = backend.currentVersion
+  } else {
+    try {
+      const sessionMod = await import('@deepseek-ai/dsh-session')
+      if (Number.isSafeInteger(sessionMod.SESSION_FORMAT_VERSION) && sessionMod.SESSION_FORMAT_VERSION >= 0) {
+        version = sessionMod.SESSION_FORMAT_VERSION
+      }
+    } catch {
+      // 宿主 session 包不可解析：保持原 header（读取时响亮失败，绝不静默）。
+    }
+  }
+  handleFormatVersionCache.set(sp, version)
+  return version
+}
+
+/**
+ * handle 基线 header 规范化：version 盖为后端当前格式版本；isSeeded 缺省时
+ * 显式置 false（后端序列化会丢弃 undefined，缺 key 的产物不可读）。
+ * @param sp - sessionPersistence 服务。
+ * @param meta - 原 SessionHeader。
+ * @returns 规范化后的新 header 对象（原对象不变）。
+ */
+async function normalizeHandleHeader(sp, meta) {
+  const header = { ...meta }
+  const version = await currentHandleFormatVersion(sp)
+  if (typeof version === 'number' && version >= 0) header.version = version
+  if (header.isSeeded === undefined) header.isSeeded = false
+  return header
+}
+
+/**
+ * handle 基线的事件批规范化：当前格式语义要求 assistant/message 的 model
+ * source 是非空字符串；缺 model 的源记录（真实 Claude transcript 恒有
+ * message.model，仅防御合成/历史记录）回退 provider 字符串，避免落盘出
+ * 无法读取的会话。未改动时原样返回调用方数组。
+ * @param events - 事件批。
+ * @returns 规范化后的事件批。
+ */
+function normalizeHandleEvents(events) {
+  let changed = false
+  const out = events.map((event) => {
+    if (event?.type !== 'assistant/message') return event
+    const source = event.data?.message?.source
+    if (source !== null && typeof source === 'object'
+      && source.kind === 'model'
+      && (typeof source.model !== 'string' || source.model.length === 0)) {
+      changed = true
+      return {
+        ...event,
+        data: {
+          ...event.data,
+          message: {
+            ...event.data.message,
+            source: { ...source, model: typeof source.provider === 'string' && source.provider.length > 0 ? source.provider : 'claude-code' },
+          },
+        },
+      }
+    }
+    return event
+  })
+  return changed ? out : events
+}
+
 /** 批量导入「读取 + 转换」阶段的默认并发上限（落盘阶段保持串行，保证幂等确定性）。 */
 export const DEFAULT_IMPORT_CONCURRENCY = 4
 
@@ -350,7 +551,10 @@ export async function annotateSettings(index) {
 
 /**
  * 用 sessionPersistence 列表 + imports 映射标注每个会话的导入状态（F4 幂等基础）。
- * 优先 `listSnapshots()`（更便宜的 header+revision 快照），回退 `list()`。
+ * 双基线（0.4.0）：listSnapshots 优先（快照 .header.id），回退 list()——
+ * handle 基线 list() 返回快照对象（header.id），旧基线返回 SessionHeader（id），
+ * 统一经 storedSessionIdOf 解析；任一元素解析不出 header.id 时响亮抛出并
+ * 跳过 cleanStale，绝不把 undefined 计入集合导致 imports.json 被误清空。
  * `cleanStale`（全量扫描时）惰性清理「映射指向已不存在会话」的残留记录并
  * 报告清理条数（B4：用户在 UI 删除导入会话后映射不再残留）。
  * @param ctx - Cordis 上下文。
@@ -366,14 +570,16 @@ export async function annotateImports(ctx, cacheDir, index, cleanStale = false)
   if (sp) {
     try {
       if (typeof sp.listSnapshots === 'function') {
-        for (const snap of await sp.listSnapshots()) imported.add(snap.header.id)
-        listSucceeded = true
+        for (const id of idsOfListedElements(await sp.listSnapshots())) imported.add(id)
       } else if (typeof sp.list === 'function') {
-        for (const header of await sp.list()) imported.add(header.id)
-        listSucceeded = true
+        for (const id of idsOfListedElements(await sp.list())) imported.add(id)
       }
-    } catch {
+      listSucceeded = true
+    } catch (err) {
+      // 元素无法解析 header.id：响亮抛出（cleanStale 随之中止，绝不静默清空映射）。
+      if (err instanceof StoredSessionIdResolutionError) throw err
       // 持久化不可读：全部按未导入处理，也不做清理。
+      console.error('[claude-move] sessionPersistence 列表读取失败：', String((err && err.message) || err))
       listSucceeded = false
     }
   }
@@ -521,13 +727,14 @@ export function resolveImportTarget(raw, claudeHome) {
   return path.resolve(expanded)
 }
 
-/** 已持久化会话 id 集合（批量导入一次快照，避免逐文件 O(n) 列表）。 */
+/** 已持久化会话 id 集合（批量导入一次快照，避免逐文件 O(n) 列表；双基线快照/头解析）。 */
 async function listPersistedIds(ctx) {
   const sp = ctx.get('sessionPersistence')
   if (!sp || typeof sp.list !== 'function') return new Set()
   try {
-    return new Set((await sp.list()).map((h) => h.id))
-  } catch {
+    return new Set(idsOfListedElements(await sp.list()))
+  } catch (err) {
+    if (err instanceof StoredSessionIdResolutionError) throw err
     return new Set()
   }
 }
@@ -752,12 +959,12 @@ function unwrapImport(entry) {
   return null
 }
 
-/** 读取已存储日志的事件数（服务支持 readFrom 时）；不可用返回 null。 */
+/** 读取已存储日志的事件数（双基线 readFrom / open+read）；不可用返回 null。 */
 async function storedEventCount(ctx, dshId) {
   const sp = ctx.get('sessionPersistence')
-  if (!sp || typeof sp.readFrom !== 'function') return null
+  if (!sp || detectPersistenceShape(sp) === null) return null
   try {
-    const read = await sp.readFrom(dshId, 0)
+    const read = await readStoredEvents(sp, dshId)
     return Array.isArray(read?.events) ? read.events.length : null
   } catch {
     return null
@@ -769,7 +976,8 @@ async function storedEventCount(ctx, dshId) {
  * 复制式语义，绝不删除/改写既有内容：
  * - 首次导入：目标 id 由「显式 sessionId > 源 sessionId > 文件名 slug」确定，
  *   若目标 id 已被占用则后缀避让（import-<src>-<n>），绝不静默丢弃历史；
- *   落盘 = create + append（append-only），随后按 cwd 挂接工作区。
+ *   落盘 = create + append（append-only；handle 基线 append 后 flush + close，
+ *   见双基线 shim），随后按 cwd 挂接工作区。
  * - 重复导入且源文件已增长（turns 变多）：把新增轮次以连续 seq 续写到同一
  *   DSH 会话（增量同步），旧事件一个字节不动。
  * - force：为同一源文件创建一份**新的**完整副本（新 id），旧副本原样保留。
@@ -793,9 +1001,9 @@ export async function persistConverted(ctx, converted, args, persisted, sourcePa
 /** 探测同名持久化会话是否为空日志（上次 create 成功、append 失败残留）；无法确定返回 false。 */
 async function isEmptyStoredSession(ctx, dshId) {
   const sp = ctx.get('sessionPersistence')
-  if (!sp || typeof sp.readFrom !== 'function') return false
+  if (!sp || detectPersistenceShape(sp) === null) return false
   try {
-    const read = await sp.readFrom(dshId, 0)
+    const read = await readStoredEvents(sp, dshId)
     return Array.isArray(read?.events) && read.events.length === 0
   } catch {
     // 读不到/读失败：按「非空」处理，走保守路径。
@@ -872,11 +1080,7 @@ async function persistConvertedInner(ctx, converted, args, persisted, sourcePath
       }
       const tail = tailSessionEvents(converted, { fromTurn: known.turns + 1, fromSeq })
       if (tail.events.length > 0) {
-        const sp = ctx.get('sessionPersistence')
-        if (!sp || typeof sp.append !== 'function') {
-          throw new Error('会话持久化服务（sessionPersistence）不可用：claude-move 增量续写需要该服务')
-        }
-        await sp.append(knownId, tail.events)
+        await spAppend(ctx, knownId, tail.events)
       }
       await rememberImport(ctx, sourcePath, {
         dshId: knownId, turns: turns.length, events: fromSeq + tail.events.length,
@@ -949,22 +1153,66 @@ async function persistConvertedInner(ctx, converted, args, persisted, sourcePath
   }
 }
 
-/** append 一份事件批次；服务缺失响亮抛出。 */
+/**
+ * append 一份事件批次（双基线）；服务缺失响亮抛出。handle 路径
+ * open(id, 'write') 独占单写所有权，append 后必须 flush()（耐久屏障）并
+ * 成对 close()（释放所有权）；事件批经 normalizeHandleEvents 规范化。
+ * 已被他人持有时 open 响亮拒绝（单写冲突）。
+ */
 async function spAppend(ctx, id, events) {
   const sp = ctx.get('sessionPersistence')
-  if (!sp || typeof sp.append !== 'function') {
+  if (!sp) {
+    throw new Error('会话持久化服务（sessionPersistence）不可用：claude-move 导入需要该服务')
+  }
+  if (detectPersistenceShape(sp) === 'handle') {
+    if (typeof sp.open !== 'function') {
+      throw new Error('会话持久化服务（sessionPersistence）不可用：claude-move 增量续写需要该服务')
+    }
+    const handle = await sp.open(id, 'write')
+    try {
+      await handle.append(normalizeHandleEvents(events))
+      await handle.flush()
+    } finally {
+      await handle.close()
+    }
+    return
+  }
+  if (typeof sp.append !== 'function') {
     throw new Error('会话持久化服务（sessionPersistence）不可用：claude-move 导入需要该服务')
   }
   await sp.append(id, events)
 }
 
-/** create + append 一份完整会话日志；服务缺失/落盘失败响亮抛出。 */
+/**
+ * create + append 一份完整会话日志（双基线）；服务缺失/落盘失败响亮抛出。
+ * handle 路径：按服务形状先探测（有 open 即 handle），create 前经
+ * normalizeHandleHeader 盖当前格式版本与 isSeeded（checkout 后端要求），
+ * create 返回值实测判定（isSessionHandle），append 后 flush() 并在 finally
+ * 成对 close()——任何失败路径都释放单写所有权；空事件批次（流式导入的首个
+ * create）只 flush 物化空会话。旧路径 create+append 调用序列与 0.3.x 逐字节
+ * 一致（header/事件不做任何规范化）。
+ */
 async function spPersist(ctx, meta, events) {
   const sp = ctx.get('sessionPersistence')
-  if (!sp || typeof sp.create !== 'function' || typeof sp.append !== 'function') {
+  if (!sp || typeof sp.create !== 'function') {
+    throw new Error('会话持久化服务（sessionPersistence）不可用：claude-move 导入需要该服务')
+  }
+  const header = detectPersistenceShape(sp) === 'handle' ? await normalizeHandleHeader(sp, meta) : meta
+  const created = await sp.create(header)
+  if (isSessionHandle(created)) {
+    notePersistenceShape(sp, 'handle')
+    try {
+      if (events.length > 0) await created.append(normalizeHandleEvents(events))
+      await created.flush()
+    } finally {
+      await created.close()
+    }
+    return
+  }
+  notePersistenceShape(sp, 'legacy')
+  if (typeof sp.append !== 'function') {
     throw new Error('会话持久化服务（sessionPersistence）不可用：claude-move 导入需要该服务')
   }
-  await sp.create(meta)
   await sp.append(meta.id, events)
 }
 
@@ -1580,9 +1828,9 @@ export function resolveExportTarget(raw, sessionId, config) {
 }
 
 /**
- * 执行一次回迁导出：读 DSH 会话日志（sessionPersistence.readFrom）→ 反向折叠为
- * Claude 可 resume JSONL → 写入目标文件。只读源会话、只写导出落点文件，绝不
- * 改写 DSH 会话日志。会话不可读/无可导出内容时大声失败。
+ * 执行一次回迁导出：读 DSH 会话日志（sessionPersistence 双基线 readFrom /
+ * open+read）→ 反向折叠为 Claude 可 resume JSONL → 写入目标文件。只读源会话、
+ * 只写导出落点文件，绝不改写 DSH 会话日志。会话不可读/无可导出内容时大声失败。
  * @param ctx - Cordis 上下文。
  * @param config - 插件配置。
  * @param args - 工具参数 `{ sessionId, path? }`。
@@ -1591,7 +1839,7 @@ export function resolveExportTarget(raw, sessionId, config) {
  */
 export async function runExport(ctx, config, args, signal) {
   const sp = ctx.get('sessionPersistence')
-  if (!sp || typeof sp.readFrom !== 'function') {
+  if (!sp || (typeof sp.readFrom !== 'function' && typeof sp.open !== 'function')) {
     throw new Error('会话持久化服务（sessionPersistence）不可用：claude-move 回迁导出需要该服务')
   }
   const sessionId = typeof args?.sessionId === 'string' ? args.sessionId.trim() : ''
@@ -1599,7 +1847,10 @@ export async function runExport(ctx, config, args, signal) {
   signal?.throwIfAborted()
   let read
   try {
-    read = await sp.readFrom(sessionId, 0)
+    read = await readStoredEvents(sp, sessionId)
+    if (read === null) {
+      throw new Error('sessionPersistence 基线无法判定（既无 readFrom 也无 open 形状）')
+    }
   } catch (err) {
     throw new Error(`读取会话 ${sessionId} 失败（不存在或不可读）：${String((err && err.message) || err)}`)
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-claude-move",
   "description": "Four-source migration wizard: copy Claude Code, Codex, OpenCode and Hermes sessions, memories, skills, instructions and slash commands into DeepSeek Harness as resumable sessions 鈥?copy-only, approval-gated, idempotent",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
@@ -110,8 +110,8 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/cordis-plugin-include": "^1.0.6",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
     "@deepseek-ai/dsh-agent": "0.1.2-alpha.5",
     "@deepseek-ai/dsh-attachment": "0.1.2-alpha.5",
     "@deepseek-ai/dsh-brand": "0.1.2-alpha.5",
@@ -121,6 +121,7 @@
     "@deepseek-ai/dsh-llm": "0.1.2-alpha.5",
     "@deepseek-ai/dsh-scope": "0.1.2-alpha.5",
     "@deepseek-ai/dsh-session": "0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session-projection": "0.1.2-alpha.5",
     "@deepseek-ai/dsh-system-prompt": "0.1.2-alpha.5",
     "@deepseek-ai/dsh-timeout": "0.1.2-alpha.5",
     "@deepseek-ai/dsh-tools": "0.1.2-alpha.5",