From 0.1.5 to 0.1.7: an upgrade recovery checklist — back up, pin, roll back

[nanami-0713]

The 0.1.7 line shipped alpha.1 → alpha.2 → rc.1 in three days, and the forum has filled with "upgraded and now nothing works / my settings are gone / my session history is missing" posts. Individual bugs are being reported well and quickly — this post is not another one. It's a recovery checklist compiled from those threads, for people who just want their working setup back. Everything is community-verified where linked; check on a copy before touching real data. (#7373 covered the earlier 0.1.6-alpha wave — this extends that checklist to 0.1.7.)

0. Version map right now (updated 2026-09-27)

Version	Released	From an upgrader's perspective
0.1.5-rc.3	npm tag only	⚠️ no release notes (#7584); subpackages pinned to it were initially unpublished (#7465, #7500) but are now all on npm (72/72, recount by @mengge237) — with zero release notes, still treat as unmapped territory
0.1.6-alpha.2	Sep 17	last 0.1.6 build; the rollback target most people land on
0.1.7-alpha.1 / .2	Sep 22	rough: multiple read-time migration refusals (#7576, #7617), settings import losses (#7534), settingsScope removed (#7445)
0.1.7-rc.1	Sep 23	regressions reported (#7646, #7635)
0.1.7-rc.2	Sep 24	current next; installs clean into a temp prefix (verified by @xiaoshenming); fresh damage: Windows data-dir re-init (#7921), rollback to 0.1.5-rc.2 wipes the session list via a shared persist key (#7983)

1. Before you upgrade (or before you retry)

1. Back up ~/.dsh first — at minimum profiles/, your session store, settings.yaml, and locally installed plugins. Several of this week's failure modes consume or drop config on a failed boot ([Bug] 0.1.7-alpha.1 and alpha.2: a failed startup still consumes settings.yaml - legacy sections import into a disposed context and are lost permanently #7534, Orphaned profile writer lock silently drops the legacy settings.yaml migration (settings lost, welcome notice cannot be acknowledged) #7634); the copy taken before the upgrade is the only reliable undo. Note that the legacy settings.yaml import renames the original file before its sections land (settings.yaml legacy import: file is renamed before sections are imported, so a failed import silently loses all settings #7453) — keep one copy outside ~/.dsh.
2. Write down the exact version you were on and keep a way to run it directly: npx @deepseek-ai/dsh@<exact-version>.
3. Don't upgrade mid-session.

2. Already broken? Match your symptom

Won't install / won't launch

• npm 11 launcher failures — v0.1.5-rc2使用npm 11 无法启动 #7559
• cordis version conflict after a partial upgrade — latest新版打包导致了cordis版本冲突直接无法打开 #7603
• Windows: two physical copies of @deepseek-ai/dsh-win32-process → koffi "Duplicate type name" — [Bug] Windows + npm global install: dsh web cannot boot — duplicate physical copies of @deepseek-ai/dsh-win32-process trigger koffi "Duplicate type name 'DSH_STARTUPINFOW'", and a create-then-check HMR race exits right after printing the URL #7593, [Windows] profile 同时加载 dsh-subprocess-local 与 dsh-sandbox-local 时启动崩溃：dsh-win32-process 双副本共享 koffi 导致原生类型重复注册 #7578
• ETARGET on 0.1.5-rc.3 — the tag exists on npm but release notes never followed, and some internal subpackages pinned to rc.3 were never published (npx @deepseek-ai/dsh web fails with ETARGET — @deepseek-ai/dsh-client-ui-sidebar-documentpreview@0.1.5-rc.3 was never published #7465, [Bug] npx install fails with ETARGET: missing documentpreview@0.1.5-rc.3 #7500, 为啥npmjs上已经有了v0.1.5-rc.3，但是却迟迟没有发布release notes？ #7584). Pin an exact version that actually has a release.
• If you retry, keep a single source of truth: one global install or the npx cache, not both.

Settings lost / reset

• Orphaned profile writer lock silently drops the settings.yaml migration — Orphaned profile writer lock silently drops the legacy settings.yaml migration (settings lost, welcome notice cannot be acknowledged) #7634
• Failed startup still consumes settings.yaml; sections land in a disposed context — [Bug] 0.1.7-alpha.1 and alpha.2: a failed startup still consumes settings.yaml - legacy sections import into a disposed context and are lost permanently #7534
• settingsScope removed silently; third-party plugins hang on boot — 0.1.7-alpha.1: legacy client service settingsScope silently removed — third-party plugins hang on boot and the failure surfaces as a misleading client-half failed #7445
  Recovery: restore from your pre-upgrade copy. The loss happens at import/boot time, not on disk.

Session history missing / refuses to open

• Sidebar history gone, no matching entry — # [Bug] Sidebar history sessions and workspaces completely lost, and current session has no corresponding entry (Data loss risk) #7637
• Read-time migration refuses released subagent/descriptor v2 sessions (fix posted in thread) — 0.1.7 read-time migration refuses released subagent/descriptor v2 sessions (fix available) #7576
• v3→v4 migration refuses sessions with unresolved tool calls inside closed steps — v3→v4 read-time migration refuses sessions with unresolved tool calls inside closed steps (damage from #7228's crash window) #7617
  Recovery: don't delete anything. In the linked threads the session files themselves are intact on disk — the refusal is in the read/migration layer.

New (step 4, proposed by @xiaoshenming): refused ≠ broken — repair beats rollback. The migrator leaves the v0 artifact byte-identical, and the refusals so far are a small set of released-writer shapes (extra members on permission/preset — #6189; subagent/descriptor < 3 — #6151; plugin-source form vs summary — #6194; chunk provenance — #6348/#6175; missing id/role — #6559) that normalize in place without dropping events or renumbering. dsh-session-surgeon implements exactly this: dry-run first, .bak.<utc> before any write, shapes checked against the real migration stages of 0.1.7-rc.1/rc.2. Stop the writers first; keep the original until the session opens.

Plugins stopped working

• rc.1 no longer heals profiles/node_modules, so child processes die — [Bug] 0.1.7-rc.1 no longer heals $DSH_HOME/profiles/node_modules (0.1.6 did) — profiles with locally installed plugins break every child process: run_code and voice input die with "subprocess scope exited before its bootstrap consumed the launch request" #7635. Workaround that has worked for link/local plugin installs: run npm install inside the plugin directory so the bundled peer gets materialized locally.
• One stale typert manifest withdraws every typert definition — [Bug] One plugin with a pre-e459e32637 typert manifest withdraws every typert definition — web UI unusable (session/control: definition-unavailable) #7630
• Peer conflict between cordis-plugin-hmr and dsh-acp-app — @deepseek-ai/dsh: internal peer dependency conflict between cordis-plugin-hmr and dsh-acp-app #7610

Windows sandbox / ACL

• rc.1: every shell command fails at the ACL grant, sticky across restarts (manual fix in thread) — [Bug] Windows: after upgrading to 0.1.7-rc.1 every shell command fails at the ACL grant with `SetNamedSecurityInfoW failed (Win32 5): grantWrite(<workspace>)` / 升级到 0.1.7 后所有 shell 命令在沙箱授权阶段立即失败（粘性，需手工修 ACL） #7646
• Approval storm after alpha.2 — 0.1.7-alpha2 版本 Sandbox ACL failure失败需要审批次数太多了是什么原因呢 #7564
• Workspace at user home breaks all commands, then the agent repeats the same failing call ~150 times — 【Bug】[Windows] Workspace at user home dir breaks all shell commands ("Windows ACL temp root must be outside the workspace") and the agent then repeats one identical failing tool call 150 times with no circuit breaker #7583

Compaction / oversized sessions

• Compaction request itself exceeds the provider request-size limit (HTTP 413) — Compaction cannot rescue an oversized session — the summarization request itself exceeds the provider request-size limit (HTTP 413) #7626
• Context at 100% but auto-compaction never triggers — [BUG] Reaching context window 100% and not triggering auto-compaction #7650
• Overflow misclassified as a normal API error; 124 attempts, 102 failures, session stuck — [bug] 上下文超长被误判成普通 API 错误：自动压缩 124 次失败 102 次，会话永久卡死 #7632

3. The habit that avoids this whole class of problem

Pin an exact version (npx @deepseek-ai/dsh@0.1.6-alpha.2 or your runner's equivalent) and move only on release checkpoints you chose — never chase a tag that has no release notes (#7584). The longer-form proposal for version pinning + long-run reliability assertions is #6542; if you'd rather see an in-product migration path, vote in #7492.

If your symptom isn't listed, comment with your from/to versions and the failing step — verified cases will be folded into this checklist.

---

中文版

0.1.7 线三天内连发 alpha.1 → alpha.2 → rc.1，论坛上挤满了「升级后跑不起来 / 设置丢了 / 会话历史不见了」。单个 bug 已有人报得又快又好——这份帖不是 bug 报告，而是一份升级恢复清单，整理自下方这些帖子，给只想把环境救回来的人。有链接的均已社区验证；动真实数据前请先在副本上确认。（#7373 整理过 0.1.6-alpha 那一波，本帖把清单延伸到 0.1.7。）

0. 当前版本地图（2026-09-27 更新）

版本	发布	升级者视角
0.1.5-rc.3	仅 npm tag	⚠️ 无 release notes（#7584）；钉到它的子包一度未发布（#7465、#7500），现已全部在架（72/72，@mengge237 复算）——但零 release notes，仍当未知地带处理
0.1.6-alpha.2	9-17	0.1.6 线最后一版，多数人回退的落点
0.1.7-alpha.1 / .2	9-22	崎岖：多起读取时迁移拒绝（#7576、#7617）、设置导入丢失（#7534）、settingsScope 被移除（#7445）
0.1.7-rc.1	9-23	已报出回归（#7646、#7635）
0.1.7-rc.2	9-24	当前 next；临时前缀安装验证通过（@xiaoshenming）；新伤：Windows 数据目录重初始化（#7921）、回退 0.1.5-rc.2 因共用 persist key 清空会话列表（#7983）

1. 升级前（或重试前）

1. 先备份 ~/.dsh——至少 profiles/、会话库、settings.yaml、本地装的插件。本周多个故障形态会在启动失败时消费或丢掉配置（[Bug] 0.1.7-alpha.1 and alpha.2: a failed startup still consumes settings.yaml - legacy sections import into a disposed context and are lost permanently #7534、Orphaned profile writer lock silently drops the legacy settings.yaml migration (settings lost, welcome notice cannot be acknowledged) #7634）；升级前留的副本是唯一可靠的后悔药。注意旧版 settings.yaml 导入会先把原文件改名、再导入分节（settings.yaml legacy import: file is renamed before sections are imported, so a failed import silently loses all settings #7453）——在 ~/.dsh 之外另留一份。
2. 记下你原来跑的确切版本，保留直接运行它的方式：npx @deepseek-ai/dsh@<精确版本>。
3. 不要在会话进行中升级。

2. 已经坏了？按症状对号入座

装不上 / 起不来

• npm 11 启动失败 — v0.1.5-rc2使用npm 11 无法启动 #7559
• 升级不彻底导致 cordis 版本冲突 — latest新版打包导致了cordis版本冲突直接无法打开 #7603
• Windows：@deepseek-ai/dsh-win32-process 双物理副本 → koffi "Duplicate type name" — [Bug] Windows + npm global install: dsh web cannot boot — duplicate physical copies of @deepseek-ai/dsh-win32-process trigger koffi "Duplicate type name 'DSH_STARTUPINFOW'", and a create-then-check HMR race exits right after printing the URL #7593、[Windows] profile 同时加载 dsh-subprocess-local 与 dsh-sandbox-local 时启动崩溃：dsh-win32-process 双副本共享 koffi 导致原生类型重复注册 #7578
• ETARGET 打在 0.1.5-rc.3 上——npm 有 tag 但 release notes 一直没出，部分钉 rc.3 的内部子包从未发布（npx @deepseek-ai/dsh web fails with ETARGET — @deepseek-ai/dsh-client-ui-sidebar-documentpreview@0.1.5-rc.3 was never published #7465、[Bug] npx install fails with ETARGET: missing documentpreview@0.1.5-rc.3 #7500、为啥npmjs上已经有了v0.1.5-rc.3，但是却迟迟没有发布release notes？ #7584）。钉一个真实有 release 的精确版本。
• 重试时保持单一来源：全局装一份或走 npx 缓存，别混。

设置丢失 / 被重置

• 孤儿 profile 写锁静默丢掉 settings.yaml 迁移 — Orphaned profile writer lock silently drops the legacy settings.yaml migration (settings lost, welcome notice cannot be acknowledged) #7634
• 启动失败仍消费 settings.yaml，分节落进已销毁的上下文 — [Bug] 0.1.7-alpha.1 and alpha.2: a failed startup still consumes settings.yaml - legacy sections import into a disposed context and are lost permanently #7534
• settingsScope 被静默移除，三方插件启动挂死 — 0.1.7-alpha.1: legacy client service settingsScope silently removed — third-party plugins hang on boot and the failure surfaces as a misleading client-half failed #7445
  恢复：从升级前副本还原。丢的是导入/启动时的事，磁盘上没坏。

会话历史不见了 / 打不开

• 侧栏历史全丢、无对应条目 — # [Bug] Sidebar history sessions and workspaces completely lost, and current session has no corresponding entry (Data loss risk) #7637
• 读取时迁移拒绝已发布的 subagent/descriptor v2 会话（帖内已有修法）— 0.1.7 read-time migration refuses released subagent/descriptor v2 sessions (fix available) #7576
• v3→v4 迁移拒绝 closed steps 里含未闭合工具调用的会话 — v3→v4 read-time migration refuses sessions with unresolved tool calls inside closed steps (damage from #7228's crash window) #7617
  恢复：什么都别删。相关帖子里会话文件在磁盘上完好，被拒的是读取/迁移层。

**新增（第 4 步，@xiaoshenming 提议）：被拒 ≠ 坏了——修复优于回滚。**迁移器对 v0 原件字节级不动，目前所有拒绝都属于一小撮「已发布写入器」形态（permission/preset 多余成员 #6189、subagent/descriptor < 3 #6151、插件源 form vs summary #6194、chunk 溯源 #6348/#6175、缺 id/role #6559），可原位归一：不丢事件、不改序号。dsh-session-surgeon 就是按这个做的：先 dry-run、写前留 .bak.<utc>、每个形态对照 0.1.7-rc.1/rc.2 真实迁移阶段验证。先停写入器；会话打开前保留原件。

插件失效

• rc.1 不再自愈 profiles/node_modules，子进程随之死 — [Bug] 0.1.7-rc.1 no longer heals $DSH_HOME/profiles/node_modules (0.1.6 did) — profiles with locally installed plugins break every child process: run_code and voice input die with "subprocess scope exited before its bootstrap consumed the launch request" #7635。对 link/本地安装的插件，实测有效的 workaround：进插件目录跑一次 npm install，让捆绑 peer 在本地物化。
• 一个过期 typert manifest 撤销全部 typert 定义 — [Bug] One plugin with a pre-e459e32637 typert manifest withdraws every typert definition — web UI unusable (session/control: definition-unavailable) #7630
• cordis-plugin-hmr 与 dsh-acp-app 的 peer 冲突 — @deepseek-ai/dsh: internal peer dependency conflict between cordis-plugin-hmr and dsh-acp-app #7610

Windows 沙箱 / ACL

• rc.1：所有 shell 命令在 ACL 授权阶段失败且粘性（帖内有手工修法）— [Bug] Windows: after upgrading to 0.1.7-rc.1 every shell command fails at the ACL grant with `SetNamedSecurityInfoW failed (Win32 5): grantWrite(<workspace>)` / 升级到 0.1.7 后所有 shell 命令在沙箱授权阶段立即失败（粘性，需手工修 ACL） #7646
• alpha.2 后的审批风暴 — 0.1.7-alpha2 版本 Sandbox ACL failure失败需要审批次数太多了是什么原因呢 #7564
• 工作区在用户主目录导致全部命令失败，agent 还会把同一个失败调用重复约 150 次 — 【Bug】[Windows] Workspace at user home dir breaks all shell commands ("Windows ACL temp root must be outside the workspace") and the agent then repeats one identical failing tool call 150 times with no circuit breaker #7583

压缩 / 超长会话

• 压缩请求本身超出 provider 请求上限（HTTP 413）— Compaction cannot rescue an oversized session — the summarization request itself exceeds the provider request-size limit (HTTP 413) #7626
• 上下文 100% 但自动压缩不触发 — [BUG] Reaching context window 100% and not triggering auto-compaction #7650
• 超长被误判成普通 API 错误：124 次尝试失败 102 次、会话卡死 — [bug] 上下文超长被误判成普通 API 错误：自动压缩 124 次失败 102 次，会话永久卡死 #7632

3. 一劳永逸的习惯

钉住精确版本（npx @deepseek-ai/dsh@0.1.6-alpha.2 或你所用运行器的等价物），只在你自己选定的 release 检查点上移动——不追没有 release notes 的 tag（#7584）。钉版本+长跑可靠性的完整提案见 #6542；想要产品内迁移路径的，去 #7492 投票。

你的症状不在列？评论留下「从哪个版本升到哪个版本 + 卡在哪一步」，验证过的案例会合并进这份清单。

[xiaoshenming]

One addition from the repair side, worth a step 4 next to pin / roll back: a session that is already refused usually does not need a rollback. The v0 artifact is left byte-identical by the migrator, and the refusals seen so far are a small set of released-writer shapes that can be normalized in place — without dropping events, inventing seqs, or changing the generation:

• extra members on permission/preset ([BUG] 0.1.5-rc.1 会话历史永久无法加载:v0→v1 拒绝已发布的 v0 形状(permission/preset 带 origin) #6189), subagent/descriptor version < 3 (升级到 0.1.5 后，以前的一些老会话打不开了 #6151), plugin-source form vs summary/sections (session-format-v0-to-v1 converter refuses loadable v0 sessions over cosmetic fields (history load breaks after upgrade to 0.1.5-rc.1) #6194), assistant/message chunk provenance after manual renumbering (# [BUG] 升级 dsh 0.1.5 后，此前手工重编号修复过的会话无法加载（chunk 溯源校验拒绝） #6348 / 更新0.1.5-rc.1后大部分会话打不开 #6175), retired source kinds and agent/inbox/spliced messages missing id/role (0.1.5-rc.1: v0→v3 迁移有三道 fail-closed 闸门 —— 49/123 之前的会话点不开（含没人报过的 inbox/spliced 一类），附已验证的修复配方 0/49→49/49 #6559).

dsh-session-surgeon applies those specific fixes only, with a dry-run first and a .bak.<utc> before any write; each shape is checked against the real sessionFormatV0ToV1 / sessionFormatV2ToV3 stages of 0.1.7-rc.1 (refused before, accepted after). Stop the writers before applying and keep the original file until the session opens again. Version map nit for your table: next is now 0.1.7-rc.1 (2026-09-23) and latest is 0.1.5-rc.3 (2026-09-22).

[mengge237]

对表一条，纯事实，不影响清单里任何建议（备份、钉精确版本、别在会话中升级这三条我都同意）。

第 0 节版本地图里 0.1.5-rc.3 那一格可以改了：逐个查 npm registry，它的 72 个依赖全部存在、缺失 0，包括昨天把所有人卡在 ETARGET 的 @deepseek-ai/dsh-client-ui-sidebar-documentpreview@0.1.5-rc.3（现已发布）；0.1.7-rc.1 的 80 个同样缺失 0。所以这一格现在准确的写法是"tag 完整、仍无 release notes（#7584）"，而不是"子包没发布"。

复算口径（09-24 本机）：取伞包 manifest 里该版本的 dependencies 逐包去 registry 查那个精确版本在不在，算的是"在架/总数"—— rc.3 为 72/72、rc.1 为 80/80，缺失列表均为空。

边界照旧：这只说明"装得上"，不涉及装完后 v4 代次对旧宿主 list() 的可见性——你清单第 2 节的症状对号仍然有效。

[nanami-0713]

对表收到，已照改。rc.3 行现在写的是「tag 在、无 release notes（#7584）；钉它的子包现已全部在架（72/72，@mengge237 复算）」，旧的「子包未发布」说法删了；next 也推进到 rc.2（依据是下方 @xiaoshenming 的临时前缀安装验证 + 本窗口 #7921/#7983 两起新伤）。

你这套「在架/总数、按精确版本逐个查 registry」的口径，正是这份清单想要的证据标准——比「有人装上了」硬得多。感谢。

[xiaoshenming]

版本表再走一格：next 现在是 0.1.7-rc.2（我们写那条清单时还是 rc.1）。

顺带回一句可用性验证，比逐包查在架更进一步：把伞包真正装进临时前缀 npm install @deepseek-ai/dsh@0.1.7-rc.2 —— 解析与安装全过、无缺失，四个相关子包（dsh-session-format-v0-to-v1 / v1-to-v2 / v3-to-v4、dsh-session-persistence-jsonl）都装上了。我们在这套 rc.2 上重跑了会话修复的五条对照路径，与 rc.1 逐行一致（两个 migration stage 接受；v2/v4 的 restore 拒；读一份已存的 v4 日志也拒）。

[nanami-0713]

Accepted on both counts — both are now in the post: the version map carries rc.2 as next (with your temp-prefix install verification, plus this window's fresh rc.1→rc.2 damage reports #7921/#7983), and your step-4 framing is folded into the "session refuses to open" block, credited, with the shape list and the dry-run/.bak discipline.

On the substance I agree, and would state the principle as: rollback fixes the writer, not the artifact — and for sessions the migrator left byte-identical, in-place normalization of known released-writer shapes is strictly less destructive than rolling onto a host that may refuse v4 anyway. The one guardrail I'd add for checklist readers: normalize only after the writers are stopped and on the same host version that refused the session — your rc.1↔rc.2 stage-by-stage comparison is what makes that check cheap now.