dsh update broke my plugins: drift and rollback

After a dsh update, do not reinstall first. Most broken plugins come from version drift, an unreloaded profile, or inconsistent dependencies; identify the layer, then roll back from cheapest to most expensive.

Separate three kinds of updates

"Update" means three different things in DeepSeek Harness.

A core update changes the foundation. When the core version moves, a plugin's declared compatibility range may no longer hold; the symptom is usually a load failure, not odd behavior.

A plugin update changes one package. It may add dependencies or change settings; an old configuration no longer applies and the plugin is present but inactive.

A Hub update only affects discovery and installation. It should not change installed plugin behavior; if it does, suspect the index or profile instead.

Recommended order: core, then plugins, then Hub. Reversing it lets a plugin require a newer core before you upgrade.

Three causes

Three causes cover most cases, each with observable signals.

1. Version drift. The plugin depends on a core version that does not match, so loading skips or core packages duplicate; logs show version conflicts or resolution failures.
2. Profile not reloaded. Configuration changed but the running process still uses the old composition; the symptom is "changed but no effect."
3. Dependency mismatch. New dependencies conflict, or build scripts did not run and output is incomplete; symptoms are load failures or runtime errors.

The external symptoms look alike, but the log locations differ. Drift appears in package resolution, profile issues in reload records, dependencies in install and build stages.

Reinstalling does not cover all three. It may fix dependencies, but not drift or profile structure; read logs before choosing.

Step one: confirm the scope

Decide whether all plugins fail or one plugin fails.

1. Run dsh plugin --profile web list and see whether plugins remain.
2. Listed but failing to load points to drift or dependencies; missing from the list points to profile or installation location.
3. Test in a new session to rule out old-session cache.
4. Read the load stage in system logs and record the first failure.

"All plugins" suggests the core or profile. "One plugin" suggests that plugin's version or dependencies.

The first failure is more useful than the last error. Later errors are often cascading; diagnosis starts at the first.

Step two: three-step rollback

Roll back by cost, starting with changes that do not affect data.

1. Reload the profile. After configuration changes, reload or restart to rule out "not applied"; cheapest step.
2. Roll back the plugin. Pin the recently updated plugin to its previous version, restart, verify.
3. Roll back the core. Only if the first two fail; record current version and plugin list before doing so.

Roll back one layer at a time. Rolling back both core and plugin hides which layer fixed it, so the next incident repeats the guesswork.

Verify after rollback. Run the smallest function of the same plugin and session; startup alone is not enough.

Step three: three signals

Rollback success is not just "it starts."

1. List signal: the plugin is listed at the expected version.
2. Config signal: dsh --dump-config contains the plugin section and no duplicate core package.
3. Function signal: the plugin's entry or command works and a minimal function passes.

The signals build from bottom to top. Listed but not working means loaded without registration; duplicate core packages mean drift remains.

Record the rollback. Version, three signals, and result; compare before the next update.

Prevention: snapshot before updating

Five minutes of snapshotting beats an hour of rollback.

1. Record versions: core and plugin list with versions, exported as text.
2. Back up configuration: copy the profile configuration and key settings with a date.
3. Back up data: copy DSH_HOME as a whole, not just sessions.
4. Record update order: what was updated first and next, so rollback can reverse it.

The point is reversibility, not full archival. Version list, configuration copy, and data directory are enough to return to pre-update state.

Verify a minimal function right after updating. Do not wait a day; test one plugin and one session so problems surface early.

When to roll back everything

Three situations need a full return to the previous state.

1. Multiple plugins fail and single rollbacks do not help. The core or profile structure changed.
2. Rolling back a plugin still produces compatibility errors. The compatibility range is broken; roll back the core.
3. Data read or write is abnormal. Sessions will not open or configuration is lost; restore data and versions first.

Stop the service before a full rollback. Running rollback produces half-written files; stop, restore, start, in that order.

Review after rollback. Record which combination works and which update introduced the problem; the next update can follow that record.

Next steps

Separate update targets, then roll back by layer. For update commands, read How to update DSH. For upgrade order, read Hub versus Harness upgrade order. For version drift, read Core package version drift.

Sources: DeepSeek Harness Releases, dsh CLI README, DeepSeek Harness docs - Plugins and lifecycle, DeepSeek Harness docs