Pin DSH plugin versions and roll back: DeepSeek Harness

Whether to pin DSH plugin versions is a choice between reproducibility and automatic currency — you cannot have both. Pinning tells you exactly which version ran last time and gives rollback a target, at the cost of manual, group-wise upgrades. This guide covers three strategies, a three-step rollback, and an automatic-update decision table.

Why DSH plugin versions deserve pinning in DeepSeek Harness

Bottom line: three concrete costs — irreproducibility, hard rollback, and overnight upgrades that cascade.

1. Irreproducible: it worked yesterday and fails today, and you cannot say what changed. DSH plugin packages release independently, so following latest wires upstream cadence into your environment.
2. Hard rollback: without a known previous version, rollback becomes guesswork.
3. Cascading failures: plugins may require specific versions of each other, and a CLI upgrade also affects plugin compatibility.
4. See the cost too: pinning means you stay on an older version until you upgrade deliberately.

Option A: pin at install time (smallest change)

Bottom line: switch from "install latest" to "install this version" and prevent later automatic upgrades. Smallest change, immediate effect.

1. Install with an explicit version:

dsh plugin add <plugin-package>@<version>
# expected: the install output shows the version you specified

2. Verify immediately:

dsh plugin            # expected: the plugin appears at the pinned version

3. Check whether your entry point has automatic updates enabled and decide per the decision table.
4. Record it: package name, version and date — three columns is enough, and it is your rollback reference.

Option B: manifest plus scheduled upgrades (best for teams)

Bottom line: write the plugin list to a file and make upgrading an explicit action. You keep reproducibility without freezing forever.

1. Maintain a manifest:

# dsh-plugins.txt
<plugin-package>@<version>
<plugin-package>@<version>

2. Install and upgrade by reading it, so every machine and every rebuild gets the same set:

set -euo pipefail
while read -r pkg; do
  [ -n "$pkg" ] && dsh plugin add "$pkg"
done < dsh-plugins.txt
dsh plugin        # archive this output as the state snapshot

3. Upgrade by editing the manifest, re-running, and recording what changed and why.
4. Upgrade in groups when dependencies are involved, not one plugin at a time.
5. Choose candidates in DSH Plugin Hub so decisions are based on version notes rather than trial and error.

Option C: images carry pinned DSH plugin versions (fleet-wide)

Bottom line: pin the plugin set into an image or distribution artifact so machines only consume it. This is the most drift-resistant approach at scale.

1. Install the manifest during the image build (see Path C in installing DeepSeek Harness in Docker).
2. Tag by version and document the distribution path; upgrading means publishing a new tag.
3. Keep old tags so rollback is a tag switch rather than per-machine edits.
4. Separate program from data: the plugin set lives in the image while user configuration and sessions live in DSH_HOME, so upgrades never touch data.

Rollback and three-step verification for DSH plugin

Bottom line: rollback is not uninstall and reinstall; it is installing the last known-good version and verifying. With a manifest it is a one-line change.

1. Approach one (manifest, fastest): revert the line and re-run the install script.
2. Approach two (single plugin): install the specific older version, useful when only one plugin broke.
3. Approach three (whole set): switch back to the previous image tag or manifest snapshot when several plugins fail together.
4. Verify three steps: the list shows the right version, restart the actual entry point so it takes effect, and call the plugin core function. Installed is not verified.
5. Record the outcome: which version broke and which version you rolled back to.
6. Compatibility breakage uses the other guide: when a plugin is incompatible with a new CLI version rather than mispinned, follow plugin version rollback and downgrade.

Decision table: automatic DSH plugin updates

Bottom line: want reproducibility, turn automatic updates off; want always-newest, keep them and record versions.

1. Test question: "If it upgrades tonight and breaks, how fast can I recover tomorrow?" If you cannot answer, turn it off.
2. Do not forget to upgrade: set an explicit cadence, for example along with CLI upgrades, so you do not sit on old versions missing fixes.

DSH plugin troubleshooting around pinning

Bottom line: two lines of inquiry — is this the version I intended, and can I get back to the previous one. Get both solid before optimizing.

1. Record the manifest after every change; this underpins all rollback capability.
2. Verify function, not just installation.
3. Treat plugin dependencies as groups to avoid single-point pins blocking upgrades.
4. Separate CLI version from plugin version — both affect compatibility (CLI side: updating DeepSeek Harness in CI).
5. At fleet scale, pin in artifacts rather than editing each machine (see aligning DeepSeek Harness across machines).
6. Repair status, stated honestly: these options follow the official CLI's plugin subcommands and npm version pinning. Whether dsh plugin exposes an automatic-update switch depends on your version — confirm with dsh plugin --help.

For choosing a version or understanding rc builds, see version selection and pinned installs.

Sources: apps/cli/README.md, docs/user/develop/basic/publish.md, npm Docs · package.json.