Make the upgrade path one command: 0.1.5-rc.1 to 0.1.7-rc.1 dropped a legacy preset and left both versions unbootable

[dqiaok]

Summary

Upgrading a running deployment from 0.1.5-rc.1 to 0.1.7-rc.1 left it in a state where neither version could boot, and where the agent itself could not be restored because its preset no longer existed. Both are recoverable by hand, but only from outside the product — which is exactly the "you need an expert" experience this report is about.

I run dsh web from a source checkout as a daily-driver agent with a user-authored preset (18 plugin rows). Two concrete traps made the upgrade much harder than "replace the binary":

1. Legacy directory presets are dropped with no migration and no warning. In 0.1.5 a preset was a directory: $DSH_HOME/.agent-presets/<id>/agent.cordis.yml. 0.1.7 replaced that with declarative @deepseek-ai/dsh-agent-preset rows. The old directory is now silently ignored. Because a session log records the preset id and recovery "rejects a missing definition", every existing session — including the agent's own — refused to restore. The process was up and healthy; the agent was gone. Nothing in the upgrade output mentioned presets at all.

2. A half-written user-layer patch file takes down BOTH versions. $DSH_HOME/cordis.patch.yml must be a top-level YAML array. An interrupted upgrade left the file containing only its header comment:

   # dsh home layer: machine-local overrides applied after every profile layer.

   Every subsequent boot — 0.1.7 and the 0.1.5 rollback target — throws while parsing it, so the deployment stays down and rollback cannot help. The error names the file, but nothing says "this file must be an array" or how to recover.

Two smaller surprises:

3. 0.1.7 renamed a plugin (dsh-workflow-worker-thread → dsh-workflow-ptc). A preset row naming the old package leaves the whole preset broken; the roster reports the reason (good), but nothing says what the new name is.
4. settings.yaml is imported once into the profile patch and then renamed to settings.yaml.imported. Reasonable in itself, but it silently rewrites a user-owned file during an upgrade.

Reproduction

1. Source checkout, dsh web running, user preset as a directory under $DSH_HOME/.agent-presets/<id>/, agent-presets.default: <id> in settings.yaml.
2. Upgrade: git merge --ff-only origin/master → pnpm install → pnpm run clean → pnpm run build → restart dsh web.
3. Result: the server answers, the roster no longer contains your preset, and every session that recorded it fails to restore.
4. Interrupt step 2 between creating $DSH_HOME/cordis.patch.yml and filling it in: the deployment no longer boots on either version.

Current behavior

• Legacy directory presets vanish silently; sessions referencing them cannot be restored; the agent is unusable while the deployment looks healthy ("port answers" ≠ "agent works").
• A user-layer patch file that is not a top-level array is fatal for every version, including the one you would roll back to.
• No migration note for renamed plugins or for the preset format change in the release; the only path is reading the source/notes.

Expected behavior

• The upgrade migrates legacy directory presets to declarative ones, or at least warns loudly: "preset <id> is a directory preset; 0.1.7 reads declarations only — see ".
• A malformed user-layer file fails with a diagnostic that says what is wrong and how to recover, and ideally never leaves the previous version unbootable.
• Release notes carry an explicit "action required" section for schema changes: preset format, session format, plugin renames.
• One supported command for the whole upgrade (dsh upgrade or equivalent), with a post-upgrade check that verifies the deployment, not just the port — e.g. "preset <id> declared and healthy", "the agent's session restores".

Environment

• dsh 0.1.5-rc.1 → 0.1.7-rc.1, Windows 11, source checkout (not a packaged install), launched as dsh web from the checkout.
• User-authored preset with 18 plugin rows plus local skills; agent-presets.default set to that preset.

Why I am filing this

The promise "an agent is a tool for people, not for experts" holds everywhere except the upgrade path. Everything else in dsh is discoverable from the model; the upgrade requires knowing about --ff-only, clean before build, the home-layer patch rules, the declaration format, and the session-format migration — and getting one of them wrong costs a working agent. A single command that either succeeds or rolls back, plus release notes that name the schema changes, would remove all of it.

Two things I can contribute if useful: the exact acceptance check we ended up writing (it asks the Host for the agent-preset roster and fails when the preset is missing or broken, which is what "the port answers" cannot tell you), and the declarative conversion of an 18-row preset from the old directory format.