dsh-workspace-mover 2.2.0 → 2.3.0

package/docs/ARCHITECTURE.md

@@ -35,6 +35,7 @@ Single logical channel `/workspace-mover` via `ctx.connection.rpc.handle('/works
 | `mover.status` | Capability report (detected services / degraded items) plus `storageLayout`, `degradedFeatures`, and the `unarchiveApi` / `setTitleApi` flags |
 | `mover.workspaces` | List workspaces |
 | `mover.move` | Single-session true move |
+| `mover.preview` | Read-only migration preview: source/target, collision, running state, adapter and estimated new snapshot bytes; `backup.reused` identifies an existing matching snapshot |
 | `mover.moveMany` | Bulk move (≤ `batchLimit`, default 50) |
 | `mover.scan` | Classified rescue scan (parses the newest `scanLimit`, default 400; reports `scanned` vs `scannedParsed`) |
 | `mover.repair` | Attach / relink / home one item |
@@ -47,8 +48,10 @@ Single logical channel `/workspace-mover` via `ctx.connection.rpc.handle('/works
 | `mover.openFolder` | Open group directory in OS file manager |
 | `mover.session.delete` | Session → recycle bin; optional `purgeBackups: true` also deletes that session's migration backups |
 | `mover.trash.list` / `mover.trash.restore` / `mover.trash.purge` | Recycle bin; `purge` accepts optional `purgeBackups: true` |
-| `mover.backups.list` / `mover.backups.restore` / `mover.backups.deleteOne` | Backup management; `list` reports `orphan` per group plus `orphanGroups` / `orphanBytes` |
+| `mover.backups.list` / `mover.backups.restore` / `mover.backups.deleteOne` | Recovery-snapshot management; `list` reports `orphan` per group, physical `count`, plus `orphanGroups` / `orphanBytes` |
 | `mover.tasks.list` / `mover.tasks.retry` / `mover.tasks.forget` | Migration task center |
+| `mover.migrations.enqueue` / `mover.migrations.list` / `mover.migrations.retry` / `mover.migrations.cancel` | Persistent busy-session queue; `retry` accepts one `taskId` or a `taskIds` batch, with per-item failure isolation |
+| `mover.bundle.export` / `mover.bundle.inspect` / `mover.bundle.import` | Portable Bundle export, dry-run inspection, and import through the adapter/backup pipeline |
 | `mover.data.cleanup` | Dry-run and clean aged plugin data (default age = `cleanupDays`) |
 
 ### Tunable policies
@@ -57,7 +60,7 @@ Single logical channel `/workspace-mover` via `ctx.connection.rpc.handle('/works
 
 | Policy | Default | Environment override |
 | --- | --- | --- |
-| backup retention per session | 20 | `DSH_WORKSPACE_MOVER_BACKUP_KEEP` |
+| physical snapshot retention per session | 20 | `DSH_WORKSPACE_MOVER_BACKUP_KEEP` |
 | move history length | 100 | `DSH_WORKSPACE_MOVER_HISTORY_LIMIT` |
 | batch cap (move / repair) | 50 | `DSH_WORKSPACE_MOVER_BATCH_LIMIT` |
 | repoint cap | 200 | `DSH_WORKSPACE_MOVER_REPOINT_LIMIT` |
@@ -102,25 +105,30 @@ When the host provides the `tools` service, `apply()` registers four plain (zero
 - `exec.signal` propagates into the RPC layer; cancellation lets the in-flight step finish rolling back to a consistent state.
 - Hosts without `dsh-tools` skip registration silently; `mover.status` reports the `agentTools` flag.
 
-## Session archives (v3)
+## Session archives and storage adapter
 
-- Naming: `session.v3.jsonl.zstd` or `session.v3.jsonl` (highest generation wins).
-- Mixed compression in one persistence root is rejected explicitly.
+- The fallback filesystem adapter recognizes names `session.jsonl[.zstd]` and `session.vN.jsonl[.zstd]`; it selects the highest generation without rewriting older files to v3.
+- A mixed plain/Zstd directory and a file whose compression differs from the host's configured mode are rejected explicitly. Mixed compression elsewhere under the same root is diagnosed per session, not by a root-wide scan.
+- v3/v4 filenames are recognized, but a v4 runtime fixture has not yet been verified. Filename/header mismatch is rejected only when the header contains one of the generation fields currently recognized by the adapter.
 - True move keeps the session id and all frames; only the header `cwd` (first frame) is rewritten; other frames stay byte-identical. Publish via temp file + atomic rename.
 
 ### The storage-layout assumption, and its self-check
 
-The whole pipeline rests on two **undocumented** assumptions: that `persistence.root` exists (`SessionPersistence`'s documented surface is `create`/`open`/`stat`/`list`), and that the on-disk directory layout equals this plugin's local port of `projectKey` / `encodeSegment`. If a host changes either, `sessionDir()` silently points at a path that does not exist — presenting as "every session is unfindable" with no diagnostic.
+The adapter first reports the public `list` / `stat` / `open` surface. When a provider also exposes a physical root, the plugin uses the legacy directory adapter as a visible `filesystem-fallback`; when only official handles are available it stays read/diagnostic capable and marks physical moves as `unsupported` instead of guessing a path.
 
 `verifyStorageLayout(ctx)` closes that gap: it takes up to five real headers from `persistence.list()`, reverse-derives each session's directory with this plugin's own encoding, and confirms an archive is actually there. Result states are `ok` / `degraded` / `empty` (no sessions to verify) / `unavailable`. It is exposed as `mover.status.capabilities.storageLayout` plus a `data-layout` check in `mover_doctor`, is strictly read-only, and never throws (any error degrades to a warning).
 
+`mover.status.capabilities.storageAdapter` is `filesystem-fallback`, `official-handle`, or `unavailable`; `storageApi`, `physicalPath`, and `migrationQueueState` expose the exact degradation and queue state. `mover_doctor` reports the same adapter under `storage-adapter` and checks the durable migration records under `data-migrations`.
+
+Portable Bundles contain `manifest.json`, `sessions/`, `attachments/`, `checksums.json`, and `workspace-metadata.json`. Import defaults to dry-run and reports id conflicts, missing attachments, compression incompatibilities, required/free space, and recoverable files. Execution refuses a blocked plan, backs up each artifact, verifies the rewritten header, and isolates failures per session. Attachment files are preserved and copied into the imported session directory; the bundle report calls out any missing file.
+
 ## Move pipeline
 
 Order of operations for a cross-workspace move:
 
 1. **Running check** — reject only mid-turn sessions (`agents.get(id)?.status === 'running'`); idle resident sessions may move.
 2. **Read authority header** from disk; verify target ≠ source.
-3. **Byte backup** to `$DSH_HOME/workspace-mover/backups/` (rolling `backupKeep` per session, default 20) **before any side effect** — a backup failure aborts with `backup-failed` and nothing has been touched.
+3. **Recovery snapshot** to `$DSH_HOME/workspace-mover/backups/` (up to `backupKeep` distinct physical files per session, default 20) **before any side effect**. The content fingerprint ignores the migration-only header `cwd`, so a move back and forth reuses the existing snapshot. A backup failure aborts with `backup-failed` and nothing has been touched.
 4. **Preflight** — dual-accounting detect, target writability probe, disk-space hint.
 5. **Rewrite first frame** (header cwd) only.
 6. **Move directory** (Windows: exponential-backoff retry on EPERM; fallback copy+delete).
@@ -129,7 +137,7 @@ Order of operations for a cross-workspace move:
 9. **Verify** — read archive back; id + cwd must match or the move fails.
 10. **Rollback on any failure** — restore live header + index snapshot → original bytes back to source dir → reattach source workspace.
 
-Concurrency: same session / same target workspace try-acquire a lock; concurrent ops return `busy` (never queue). Bulk moves de-duplicate first.
+Concurrency: same session / same target workspace try-acquire a lock. A running session returns `busy` to the transaction layer and is persisted in `migrations.json` as `waiting-for-idle`; the queue wakes every few seconds and on the next plugin start. Bulk moves de-duplicate first and isolate each result.
 
 If “rollback also failed”, a durable recovery record is written and shown as a red manual-recovery row. Session files and backups stay in place — never auto-deleted.
 
@@ -151,7 +159,7 @@ All plugin metadata lives under `$DSH_HOME/workspace-mover/` and never overwrite
 
 | Path | Use |
 | --- | --- |
-| `backups/` | Byte-level pre-move backups |
+| `backups/` | Byte-level recovery snapshots; new files include a SHA-256 content fingerprint, while legacy timestamp-only names remain readable |
 | `history.json` | Last 100 cross-workspace moves |
 | trash / task / recovery files | Recycle bin manifest, task center, recovery ledger |
 

package/docs/compatibility/dsh-0.2.0-rc.2-2026-10-04.md

@@ -0,0 +1,39 @@
+# DSH 兼容性实测报告：0.2.0-rc.2 · 2026-10-04
+
+> 本插件的兼容性验收记录。每适配一个 DSH 版本新增一份带日期的报告；README 的 "DSH tested" 徽章链接到最新一份。
+> 插件版本：**2.1.0**（npm + GitHub tag v2.1.0）· 运行环境：Windows 10.0.26200 x64 · Node ≥22
+
+## 验证范围
+
+| 场景 | DSH 版本 | 结论 |
+| --- | --- | --- |
+| **桌面客户端**（Electron 44 壳，`E:\DeepSeekHarness\desktop`） | 0.2 线（0.2.0-rc.2 内核） | ✅ 已实测通过 |
+| **web profile** | 0.2.0-rc.2 | ⏳ 与桌面版同内核、同一代码路径，启动器已切换，回归待跑 |
+
+## 桌面版实测项（2026-10-04）
+
+| 项目 | 结果 | 说明 |
+| --- | --- | --- |
+| 数据家共享（`DSH_HOME` 指向既有 `data\`） | ✅ | 会话、工作区、投影缓存全部直接可见，无格式迁移（会话文件保持旧命名） |
+| 桌面 profile 插件安装 | ✅ | 应用内「插件」页安装，profile 与 web 相互独立 |
+| 拖拽跨工作区迁移 | ✅ | 会话行 → 工作区标题行，确认后真迁移 |
+| 确认框渲染 | ✅ | 修复后为不透明卡片（0.2 主题的 `--dsw-specific-menu` 为半透明玻璃色） |
+| 插件热重载后的移动 | ✅ | 修复了旧 fiber 失活导致的 `inactive context` 报错（connection 实例在 apply 时捕获） |
+| agent 工具（dsh-tools 注册） | ✅ | dsh-base 在 web/桌面共享 `tools` 行；三个工具 + 审批门就绪 |
+| `mover.status` 能力位 | ✅ | `agentTools` 标志如实汇报 |
+
+## 已知事项（非本插件缺陷）
+
+- **遗留 Agent 预设**：0.2 不再读取 `$DSH_HOME\.agent-presets\<id>\` 旧格式目录，旧会话恢复会报 `Unknown agent preset`。迁移步骤：[docs/dsh-0.2-preset-migration.md](../dsh-0.2-preset-migration.md)。
+- **web profile 回归**：拖拽 / 面板 / agent 工具在 web 0.2 场景按同一代码路径适配，尚未单独实测；完成后本报告将更新。
+
+## 测试基线
+
+- `npm run check`（语法 + 105 用例 + pack dry-run）全绿；
+- CI：ubuntu / windows / macos × Node 22/24 矩阵通过（v2.1.0 tag 构建）。
+
+## 历史
+
+| 日期 | DSH 版本 | 报告 |
+| --- | --- | --- |
+| 2026-10-04 | 0.2.0-rc.2（桌面） | 本文件 |

package/docs/compatibility/dsh-0.2.0-rc.2-2026-10-13.md

@@ -0,0 +1,45 @@
+# DSH compatibility report: 0.2.0-rc.2 · 2026-10-13
+
+Release: 2.3.0. Desktop results below are user-reported partial verification; they do not claim a full real-runtime smoke pass.
+
+## Matrix
+
+| Environment | Node | Result | Scope |
+| --- | --- | --- | --- |
+| DSH Desktop 0.2.0-rc.2 | pending | partial: user confirmed idle-session migration and snapshot reuse; initial return-preview failures and corrections are documented below | adapter status, v4 move, preview; queue resume still pending |
+| DSH Web 0.2.0-rc.2 | pending | pending user verification | same smoke flow on web connection |
+| Local sandbox fixtures | 22.23.2 | passed: `npm run check`, 171/171 tests, `npm pack --dry-run` | v3/v4 Zstd, plain JSONL, format diagnostics, rollback, queue state transitions, return preview, drop-target identity, explicit target selection, snapshot deduplication |
+| Node 24 fixtures | 24 | not run | CI/runtime matrix remains pending |
+
+## Implemented checks
+
+- `filesystem-fallback`, `official-handle`, and `unavailable` adapter modes are reported through `mover.status` and `mover_doctor`.
+- Physical operations fail with a stable `unsupported` error when the provider exposes no raw-byte path.
+- A running session is persisted in `migrations.json` as `waiting-for-idle`; the queue drains after idle and after plugin re-mount. Process-restart validation remains pending.
+- `mover.preview` reports source, target, collision, running state, adapter mode, warnings, and estimated new snapshot bytes; a matching snapshot is reported as reused.
+- Recovery snapshots use a SHA-256 fingerprint of session content with migration-only `cwd` normalized. Legacy timestamp-only backup names remain readable. Each migration still records its source, target, and snapshot reference in history.
+- Mixed compression is rejected explicitly; no format upgrade is performed. Header-generation mismatch detection only applies when the header declares a recognized generation field.
+- The local queue test covers plugin re-mount. A full DSH process restart with a waiting task has not been exercised yet.
+- The user confirmed snapshot reuse for an old idle session after moving it; local fixtures cover Zstd, plain JSONL, round trips, and content changes.
+
+## Still requiring a real DSH run
+
+- Official-runtime plain JSONL and v3/v4 fixtures, including mismatch and mixed-layout diagnostics. The local sandbox fixtures are not official DSH runtime evidence.
+- Desktop and Web smoke flow with a real session: create, preview, move, verify id/cwd/events, conflict, attach failure and byte-exact rollback.
+- Restart DSH while a queue item is waiting, then verify it completes after the session becomes idle.
+
+The next report should replace the pending rows with the exact DSH build, Node version, successful scenarios, and known limits.
+
+## Desktop feedback and correction
+
+The user restarted Desktop and reported all doctor checks passing except the expected filesystem adapter warning. A session moved from `E:\DeepSeekHarness` to `E:\VSCode_Project\quant_research`. Read-only inspection found one `session.v4.jsonl.zstd` primary archive at the destination (419,562 bytes) and no primary archive for that ID at the source. The return preview nevertheless showed both source and target as `quant_research` and incorrectly labelled the session's own archive as a conflict.
+
+The candidate now resolves drop targets from the rendered `data-row-key` workspace ID before React group props and unique text evidence. It refreshes workspace data at drop time and rejects ambiguous text matches. Same-workspace previews distinguish existing membership from an unregistered archive, and report no recovery backup for those operations. Doctor adapter explanations and preview notices are localized; the recovery backup copy is explicitly described as separate from the registered primary session.
+
+The user retested after restart and still received a same-workspace return preview. The exact Desktop event target has not been captured, so the identity-based correction alone is not considered verified. Further changes remove the stale last-hover fallback when dropping outside a header and clear the hover target when leaving a header. Single-session confirmation now offers an explicit workspace selector, refreshes the preview for the selected target and fork scope, and keeps execution disabled while loading or on preview failure. Late preview responses are ignored. These flows have DOM regression coverage; The latest user feedback confirms migration and snapshot reuse, but does not separately document every selector/drag scenario.
+
+## Release checks
+
+- Version 2.3.0: local Node 22.23.2 checks passed, 171/171 tests, syntax checks and npm pack dry-run.
+- Regression coverage now includes newest/default versus explicitly selected backup restoration, attachment space estimates, and insufficient-space import refusal before writing.
+- README_EN.md and CHANGELOG.md are included in the npm package.