Fix ERESOLVE: DeepSeek Harness npm "latest" stuck on rc

A DeepSeek Harness plugin install that fails with ERESOLVE unable to resolve dependency tree or ERR_PNPM_FETCH_404 almost always traces back to the official npm dist-tags: most @deepseek-ai/dsh-* packages still point latest at the first public release 0.0.1-rc.1, and that stale line's peer metadata references pre-rename packages that return 404 on npm. Any resolver that walks that line ends up mixing two version lines or hitting a missing package. Pin the whole family to one current line, and use pnpm.overrides for profiles you already created.

What the DeepSeek Harness install failure looks like

One root cause surfaces as three different errors depending on the entry point; recognizing the shape first saves most of the trial and error. From community reproductions (#2763, #984):

1. ERESOLVE tree conflict: a bare install of @deepseek-ai/dsh-agent-spine-demo and friends in a fresh project reports npm error ERESOLVE unable to resolve dependency tree, with a detail line reading peer @deepseek-ai/dsh-bash-env@"^0.0.1-rc.1" from @deepseek-ai/[email protected] — the peer declaration from the old line. @deepseek-ai/dsh-bash-env does not exist on npm at all (npm view returns 404).
2. pnpm hard 404: ERR_PNPM_FETCH_404 GET https://registry.npmjs.org/@deepseek-ai%2Fdsh-type-meta: Not Found. The missing package is pulled in transitively through the peer chain of dsh-tools / dsh-session; @deepseek-ai/dsh-tasks and @deepseek-ai/[email protected] fail the same way.
3. Old version installed, package "missing": dsh plugin --profile <name> add @deepseek-ai/dsh-base installs what latest resolves to — 0.0.1-rc.1 — and then reports the package as unpublished or nonexistent. The package exists; the tag points elsewhere.

One telltale signal: npm install succeeds while pnpm always fails. npm resolves loosely, while pnpm validates peer ranges strictly and re-resolves the entire tree, so the same repository gives opposite verdicts depending on the package manager.

Why npm latest is frozen on the rc line in a DSH plugin install: dist-tags and the publish chain

latest does not mean "newest version"; it is a tag that can sit still for months, and the official release script never advances it for prereleases — those go to alpha / next only, so latest stays on the early rc line. Two layers explain it:

1. Tag layer: which version latest, next, or alpha points at changes only when someone runs an explicit operation such as npm dist-tag add (npm docs). In the 13-package sample, dsh-agent-spine-demo, dsh-tool-bash, dsh-llm, and dsh-session all had latest = 0.0.1-rc.1 while only dsh-agent and dsh-app-boot were on the current line; next pointed at the current line across the board — an inconsistent family, so bare installs mix lines.
2. Metadata layer: the 0.0.1-rc.1 line declares peers using pre-rename names (dsh-bash → dsh-shell, dsh-tasks → dsh-jobs, dsh-bash-env → dsh-shell-env). Those old names were never published, so the 404 is unavoidable. By contrast, the current line's metadata is correct — the only question is where latest points.
3. pnpm version differences amplify it: initProfile writes autoInstallPeers: false into pnpm-workspace.yaml, a key only pnpm ≥10 reads. On pnpm 9.x (still common via corepack and CI images) it is silently ignored, pnpm falls back to auto-installing peers, and the whole peer tree — 404 names included — gets resolved (#984 mechanism note).
4. Release pacing adds the mirror-image gap: npm publish runs before the release branch merges and tags, producing windows where npm has a package that no dsh-v* tag shows. While latest is frozen, npm i -g @deepseek-ai/dsh also lands several lines behind the repository (#5417).

How to align a DSH plugin install with npm tags: one line, @alpha, and pnpm.overrides

The core move is one sentence: read the tags, then pin the entire package family to a single current line instead of trusting default resolution. Steps verified by the community:

1. Read the tags: npm view @deepseek-ai/dsh-tools dist-tags shows where latest, next, and alpha each point. npm view <package> version reports only the latest line and is easy to misread.
2. Pin the whole family: declare every @deepseek-ai/* package you use at the same current line in your package.json (a fresh project pinned to ^0.1.0-rc.6 resolved 81 packages and ran a full tool-calling turn end to end). Pinning a few packages and letting the rest resolve by default still mixes lines.
3. Pick a line on purpose: track the development line with @alpha (in the measured window @deepseek-ai/dsh@alpha was 0.1.2-alpha.5), or stay on the latest rc line for stability. To match repository code exactly, use the GitHub dsh-v* tags as the reference — alpha can lead them by half a day.
4. Existing profiles do not need rebuilding: set an available version for the stuck package in the profile's pnpm.overrides. Measured case: [email protected] declares @deepseek-ai/dsh-tool-subagent": "*", "*" resolved to 0.0.1-rc.1, which pulled the 404 dsh-tasks; overriding it to 0.1.0-rc.6 (the first version without that peer) restored installs.
5. Installing from a local checkout also sidesteps it: with dsh plugin --profile <name> add ., @deepseek-ai/* resolves through the harness installation's fallback node_modules, so the missing peer never has to be fetched (#984); other install-time dependency failures are covered in plugin dependency install failures.
6. The durable fix belongs upstream: realigning every family member's latest to the current line (or at least to next) removes the majority of default-install failures; the community's quantified baseline was 160 of 325 npm-installable plugins affected, with 100 recoverable from a single family-wide tag move. For end users, installing through DSH Plugin Hub (Settings → Plugin Marketplace) is safer: a failed install rolls the manifest back, so the profile is never left polluted — only blocked.

Version drift produces a different symptom family (an old core package installed into the profile makes tool calls crash with reading 'prepare'); related mechanism, separate diagnosis: core package version drift.

DSH plugin troubleshooting notes

Never read latest as "the current version", and never pin only part of the family — mixing lines is worse than lagging behind. Five points:

1. Do not treat npm install @deepseek-ai/dsh-*@latest as "the current version." latest can lag two lines behind; npm view <package> dist-tags is the complete picture.
2. Mixing lines is worse than lagging. Pinning only some packages resolves two incompatible peer ranges at once, so the conflict is deterministic rather than intermittent.
3. Do not force-install the 404 names. dsh-type-meta, dsh-tasks, and dsh-bash-env are pre-rename history with no registry counterpart; either wait for the publish chain or move to the current names.
4. pnpm.overrides is a stopgap. It unblocks the current profile but does not repair upstream metadata; remove it once the official tags are realigned so you are not pinned to an old version indefinitely.
5. After a failed install, confirm the profile is intact. pnpm aborts the whole tree on failure and the marketplace rolls the manifest back, but if you edited the profile by hand, open a fresh session afterwards and verify tool calls still work.

Sources: Discussion #2763, Discussion #984, Discussion #5417, npm dist-tag docs.