Pitfall map for DSH plugin authors: the 'reading prepare' crash is a duplicate @deepseek-ai/* copy — three guards that would catch it

[leether]

Follow-up to #2078. After the version-skew reply and a full root-cause pass, we've revised our position: Symbol.for is a defensive stopgap with side effects, not the fix. The crash isn't a bug in the code or a mistake by the author — it's two reasonable defaults colliding (private-identity Symbol() vs the npm-default dependencies), with nothing documenting, checking, or diagnosing the collision. The gap is three feedback loops that were never closed.

Root-cause map and the three unclosed loops

The crash, restated

Two physical @deepseek-ai/dsh-tools copies → two module-local Symbol() keys → ctx.tools[TOOL_RUNTIME_SCHEDULER] is undefined → Cannot read properties of undefined (reading 'prepare').

Two trade-offs colliding — not a bug in either place

• Symbol() is a deliberate trade-off: private identity (safe and hidden) in exchange for failing hard when a duplicate exists. The crash is that trade-off's cost, delivered with a useless message.
• dependencies is the author's reasonable default: "import X → dependencies" is the npm norm; peer is the exception, and that exception is never surfaced to third-party authors — the "never plain dependencies" rule lives only in a profile.ts source comment, not in publish.md.

Neither choice is unreasonable. Two sensible defaults collide, and the collision was never documented, checked, or diagnosed — so each new author re-derives it the hard way (for us, ~a dozen isolated instances and five rounds of instrumentation).

Three feedback loops that were never closed

Loop	What's missing
Documentation	publish.md shows a zero-dependency plugin; it never says "host packages must be peerDependencies"
Install-time check	dsh plugin is a bare pnpm forwarder; it silently accepts a plain @deepseek-ai/* dependency
Diagnosis	the crash reports undefined, not "two physical copies: one from the host, one from plugin X"

The five ways a duplicate appears (and which loop catches each)

Path	~share*	Caught by
1. plain dependencies	~40–50%	install check (pre-flight)
3. stale peer range (rc.1 vs rc.6)	~25–35%	install check (pre-flight, warn)
2. transitive hoist	~5–10%	install check (post-install scan)
5. manual pnpm install in the profile	~5–10%	boot-time fail-loud
4. vendored copy inside a plugin	~2–5%	boot-time fail-loud

* estimates from discussion frequency, not measurements.

Our revised position on Symbol.for (self-correction)

Symbol.for makes the key global so duplicates no longer crash. It's a stopgap with four side effects — semi-public key (breaks @internal), the key string frozen forever, cross-version copies silently cross-wire (the version-skew reply was right), and it removes the only signal (undefined becomes silent success / silent cross-wire). In a single-instance world preserved by relink + a check, Symbol() is strictly better. We still carry the change on our fork (fix/tool-runtime-scheduler-symbol), but now treat it as a local unblocker, not a proposal.

Open for discussion — weighing the trade-offs, not requesting a patch

• Which loop is the core? Documentation, install-time check, and diagnosis are three different trade-offs (prevention vs detection vs explanation); each alone helps, and each has a different cost to maintain. Which does the team see as the intended direction?
• The host-singleton boundary. cordis / dsh-tools / schemastery / cosmokit, or all @deepseek-ai/*? Where's the line — and is it ever legitimate for a third-party plugin to pin a different host version?

The community already covered the pieces

• Bug: 每次工具调用崩溃 reading 'prepare' — profile 内独立 dsh-tools 副本分裂 Symbol #1418 — relinkHostPackages (relink profile copies to host)
• [BUG] Plugin peer-dep creates duplicate dsh-tools instance -> tool scheduling crashes (prepare undefined) #1849 — install-time uniqueness check
• ToolRuntime scheduler lookup silently returns `undefined` when multiple physical copies of `@deepseek-ai/dsh-tools` exist in one process (Symbol-key mismatch) #572 — fail-loud duplicate-module detection
• Community plugins resolving a second @deepseek-ai/dsh-tools copy crash the tool scheduler with Cannot read properties of undefined (reading 'prepare') #1337 — guard the lookup; the version-skew variant
• Fix: `reading 'prepare'` crash from duplicate `@deepseek-ai/dsh-tools` copies (Symbol-key mismatch) — a one-line `Symbol.for` fix #2078 — our original report + zoahdev's version-skew reply

This post just assembles them into one map and opens the trade-off discussion.

[MrColder666]

after deleting the dependencies and placing them into peerdependencies, this happened
package.json
PS C:\Users\chent> dsh web
file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:1186
throw new Error(${binName}: ${stage}: ${detail}${stack}, { cause });
^

Error: dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include): failed to import loader entry ui-deepseek-pet (@deepseek-ai/dsh-client-ui-deepseek-pet): Cannot find package '@deepseek-ai/dsh-client-ui-deepseek-pet' imported from C:\Users\chent.dsh\profiles\web
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@deepseek-ai/dsh-client-ui-deepseek-pet' imported from C:\Users\chent.dsh\profiles\web
at Object.getPackageJSONURL (node:internal/modules/package_json_reader:316:9)
at packageResolve (node:internal/modules/esm/resolve:768:81)
at moduleResolve (node:internal/modules/esm/resolve:858:18)
at defaultResolve (node:internal/modules/esm/resolve:990:11)
at #cachedDefaultResolve (node:internal/modules/esm/loader:737:20)
at ModuleLoader.resolve (node:internal/modules/esm/loader:714:38)
at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:293:38)
at onImport.tracePromise.proto (node:internal/modules/esm/loader:665:36)
at TracingChannel.tracePromise (node:diagnostics_channel:350:14)
at ModuleLoader.import (node:internal/modules/esm/loader:664:21)
at boot (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:1186:9)
at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
at async runProfile (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/lib/profile-boot-DG5t9aNs.js:247:14)
at async file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/lib/bin.js:133:3 {
[cause]: Error: failed to apply loader entry include (cordis:include): failed to import loader entry ui-deepseek-pet (@deepseek-ai/dsh-client-ui-deepseek-pet): Cannot find package '@deepseek-ai/dsh-client-ui-deepseek-pet' imported from C:\Users\chent.dsh\profiles\web
at updateError (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/cordis-plugin-loader/lib/index.js:299:9)
at Entry._init (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/cordis-plugin-loader/lib/index.js:519:10)
at process.processTicksAndRejections (node:internal/process/task_queues:103:5) {
[cause]: Error: failed to import loader entry ui-deepseek-pet (@deepseek-ai/dsh-client-ui-deepseek-pet): Cannot find package '@deepseek-ai/dsh-client-ui-deepseek-pet' imported from C:\Users\chent.dsh\profiles\web
at updateError (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/cordis-plugin-loader/lib/index.js:299:9)
at Entry._init (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/cordis-plugin-loader/lib/index.js:514:10)
at async Entry.init (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/cordis-plugin-loader/lib/index.js:495:4)
at async Entry.update (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/cordis-plugin-loader/lib/index.js:416:37)
at async EntryGroup.create (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/cordis-plugin-loader/lib/index.js:55:4)
at async Promise.allSettled (index 133)
at async EntryGroup.update (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/cordis-plugin-loader/lib/index.js:87:21)
at async Include._apply (file:///C:/Users/chent/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-app-boot/lib/index.js:238:3) {
[cause]: Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@deepseek-ai/dsh-client-ui-deepseek-pet' imported from C:\Users\chent.dsh\profiles\web
at Object.getPackageJSONURL (node:internal/modules/package_json_reader:316:9)
at packageResolve (node:internal/modules/esm/resolve:768:81)
at moduleResolve (node:internal/modules/esm/resolve:858:18)
at defaultResolve (node:internal/modules/esm/resolve:990:11)
at #cachedDefaultResolve (node:internal/modules/esm/loader:737:20)
at ModuleLoader.resolve (node:internal/modules/esm/loader:714:38)
at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:293:38)
at onImport.tracePromise.proto (node:internal/modules/esm/loader:665:36)
at TracingChannel.tracePromise (node:diagnostics_channel:350:14)
at ModuleLoader.import (node:internal/modules/esm/loader:664:21) {
code: 'ERR_MODULE_NOT_FOUND'
}
}
}
}

Node.js v24.11.1
PS C:\Users\chent>