Advisory: the plugin-install path needs guardrails — consolidated from #1404/#1197/#1486/#1415/#1413

[moonquake2004]

Advisory: the plugin-install path needs guardrails

Audience: DeepSeek Harness maintainers
Background: consolidated from five GitHub Discussions on 2026-08-14 (#1404, #1197, #1486, #1415, #1413), several independently reproduced against the real packages (0.1.0-rc.6).
Core conclusion: the plugin ecosystem (dsh plugin + pnpm + cordis loader) is currently "fragile by install" — a single dsh plugin add can take down the whole profile at boot or at runtime, and there is no effective diagnostic. This is not a set of one-off bugs; it is a class of missing guardrails around one shared surface.

---

1. Failure inventory (by severity)

P0 · Boot crashes — the entire profile fails to start

#	Discussion	Symptom	Root cause
1	#1404	dsh web dies with duplicate loader entry id: <id>; every plugin goes down with it	dsh plugin add's reconcile promotes every dsh.bundle-declaring dependency (including pre-existing ones) into the bundle stack, but never cleans up the now-redundant inserts in the user patch (cordis.patch.yml) — the same entry id is inserted twice
2	#1197	Boot fails with ERR_MODULE_NOT_FOUND; whole plugin tree dies	Two-anchor resolution (install anchor → profile dir) applies only to dsh.profile.bundles, not to name: in patch inserts; combined with vanished file: links / packages not on the profile's resolution chain — no validation, no degradation

Common thread: the loader composes without validation and without degradation — duplicate ids and resolution failures both throw the entire tree (Promise.allSettled → throw first failure). And dsh --profile web --dump-config never mounts the loader / never imports entries, so it is a false-positive check (verified: it exits 0 with the profile in a state that crashes on real boot).

P0 · Runtime crashes — boots fine, core functionality dies

#	Discussion	Symptom	Root cause
3	#1486	After installing third-party plugins, every model tool call fails: Cannot read properties of undefined (reading 'prepare'), UI shows "本轮运行失败"	pnpm hoists the plugin's transitive @deepseek-ai/* deps into the profile's top-level node_modules → two module instances of e.g. dsh-tools in one process; module-local Symbol('x') is not equal across instances → ctx.tools[symbol] is undefined
4	#1415	Session resume fails: Host Cordis inspect provider "Service" is already registered; conversation unrecoverable until restart	CordisInspectRegistryService is a process-global singleton but register() is not idempotent; two sessions mounting dsh-tool-cordis in one process collide (abnormal teardown leaks the ids — disposers only run on clean teardown). Independently reproduced against the real packages

P1 · Ecosystem & diagnostics gaps

#	Gap	Note
5	No dsh doctor / dsh check	Two independent reporters (#1197 and #1404) arrived at the same need: an offline profile scan (dangling references, duplicate entries, stale file: links)
6	Unfriendly pnpm-missing message	dsh plugin only says "pnpm not found on PATH" without concrete commands (corepack enable pnpm / npm i -g pnpm)
7	No verify/rollback flow around installs	Users install → restart → hope; on failure it's manual YAML archaeology

---

2. Root causes (six)

1. dsh plugin/pnpm mutate profile state without guardrails — reconcile scans the whole installed state (not the diff), pnpm hoisting is uncontrolled, file: links have no lifecycle management;
2. The loader does not validate or degrade — one bad entry kills the whole tree;
3. Two different resolution paths — bundles get two-anchor resolution, patch inserts get single-anchor;
4. No dedupe of @deepseek-ai/* — framework install and profile node_modules copies can both load;
5. Process-global singletons/registries are not idempotent — mounting the same plugin/service twice throws;
6. No diagnostics — --dump-config is insufficient; there is no offline check.

---

3. Recommendations (by priority)

P0 · Stop the bleeding — "install a plugin" should never brick the profile

1. Reconcile must be aware of the user patch (fixes #1404)

• After promoting bundles, diff bundle-patch insert ids against user-patch inserts:
  • either auto-remove the redundant user-patch entries (keep a .bak, as a human fix did), or
  • fail at install time with an actionable message naming the exact file/entries to remove.
• Cleanest: the diff-aware reconcile proposed by argszero in dsh plugin add promotes pre-existing bundle-declaring deps into the bundle stack and breaks the next boot with "duplicate loader entry id" #1404 — drive the bundle list only from this invocation's dependency changes (mirroring how the removal loop already uses beforeDeps); pre-existing deps keep their current loading mechanism.

2. Loader: prevent + report (fixes #1404/#1197)

• Prevent: guard at install time (recommendation 1);
• Report: on duplicate id / resolution failure at boot, emit an actionable error (source file + entry id), not a bare TypeError;
• Degrade: evaluate skip-and-warn — but be careful with duplicate ids (may mask real config conflicts); prefer "prevent at install + clear error at boot".

3. Use the global symbol registry across the framework (fixes #1486)

• Replace module-local Symbol('@deepseek-ai/...') with Symbol.for(...) in every @deepseek-ai/* package (dsh-tools TOOL_RUNTIME_SCHEDULER, cosmokit, dsh-llm, dsh-settings, schemastery, …). Minimal and robust.

4. Idempotent registration/mounting (fixes #1415)

• Make CordisInspectRegistryService.register() idempotent (reference-counted, or replace-and-return-disposer), or register the first-party inspect providers once on the host plane;
• Failure messages should name the holder of the provider (Session resume fails: Host Cordis inspect provider "Service" is already registered (process-singleton registry collides between preset mounts) #1415 author's suggestion #4).

P1 · Diagnostics & experience — let users self-check and self-heal

5. Add dsh doctor / dsh check — offline profile scan reporting:

• (a) id collisions between bundle patches and user-patch inserts (dsh plugin add promotes pre-existing bundle-declaring deps into the bundle stack and breaks the next boot with "duplicate loader entry id" #1404 class);
• (b) resolvability of every user-patch name: from the profile anchor (dsh web fails to boot: unresolvable plugin reference in profile patch (cordis.patch.yml) #1197 class);
• (c) top-level @deepseek-ai/* packages duplicated against the framework (Tool layer fails with "Cannot read properties of undefined (reading 'prepare')" after installing third-party plugins #1486 class);
• (d) consistency of file: deps with the lockfile/disk (dsh web fails to boot: unresolvable plugin reference in profile patch (cordis.patch.yml) #1197 class).

A community seed already exists: the check-dsh-profile.mjs script shared in #1404/#1197 implements (a); the authors are happy to contribute and extend it to (b)–(d).

6. --dump-config --verify-import — actually mount the loader / import every entry, turning the false-positive dump into a real check (both #1197 and #1404 reporters were misled by a passing dump).

7. Install UX

• Concrete pnpm install commands when missing (corepack enable pnpm / npm i -g pnpm) — dshmarket already does this;
• After dsh plugin add, tell the user it needs a restart to take effect, and how to verify (dsh doctor / real boot).

P2 · Architecture (long-term)

8. Unify resolution (fixes #1197) — give patch-insert name: the same two-anchor resolution as bundles (install anchor → profile dir), so identical references resolve identically.

9. Prevent @deepseek-ai/* duplication (fixes #1486) — prefer the framework copy in the loader/dsh plugin flow, or dedupe on install; at minimum document that plugins must not directly depend on framework-internal packages (e.g. @deepseek-ai/dsh-tools), and have dsh doctor detect it.

10. Install → verify → rollback — after dsh plugin add, run an automated verification (real boot or equivalent); on failure, offer a rollback command. The plugin-market UI can do the same (validate after one-click install).

Tests

11. Regression matrix — each case asserts "profile still boots clean after the install":

• dsh plugin add promotes pre-existing bundle-declaring deps into the bundle stack and breaks the next boot with "duplicate loader entry id" #1404: profile with a bundle-declaring dep loaded only via user-patch insert + dsh plugin add <other> → dep is NOT promoted, boot stays clean;
• dsh web fails to boot: unresolvable plugin reference in profile patch (cordis.patch.yml) #1197: dangling file: link + patch insert → skip-and-warn or clear error;
• Tool layer fails with "Cannot read properties of undefined (reading 'prepare')" after installing third-party plugins #1486: install a plugin depending on @deepseek-ai/dsh-tools → tool calls still work (single-instance assertion).

---

4. Community assets ready to adopt

Asset	Source	Use
check-dsh-profile.mjs pre-boot checker	us (#1404/#1197)	seed for dsh doctor, covers (a)
diff-aware reconcile patch draft	argszero (#1404)	implementation of recommendation 1
dsh-tool-cordis idempotent-registration patch	MasterToycode (#1415, gist)	reference for recommendation 4
Symbol.for fix direction	dj1113969731-cloud (#1486)	implementation of recommendation 3

---

5. Closing

"Everything is a Plugin" is a great vision, and the ecosystem is clearly taking off (plugin market, community handbook, active discussions). But right now the cost of a failed install is too high: one dsh plugin add can take down the whole workspace, and recovery means hand-editing YAML. The goal of these recommendations is deliberately modest — make installing plugins safe, diagnosable, and rollback-able. We'd be glad to help test and contribute seed implementations as the team works through P0 → P1 → P2.

Consolidated from: #1404, #1197, #1486, #1415, #1413 (deepseek-ai/deepseek-harness Discussions).

[Electricitysheep]

插件安装路径缺护栏——合并 5 帖的系统性梳理很有价值（悬空引用/静默禁用/无验证安装）。

这和我们在第 13 章整理的"插件安全审计清单"是同一主题的两端：官方做安装护栏（技术防线），用户侧做装前检查（dsh-plugin-doctor 这类工具 + 审计习惯）。

第 13 章清单：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/13-security.md

[moonquake2004]

Thanks — the "official install guardrails (technical line) + user-side pre-install checks (tooling + audit habits)" framing is a good split, and the two genuinely complement each other.

One user-side tool that fits the "dsh-plugin-doctor" niche already exists: the offline pre-boot checker check-dsh-profile.mjs shared in #1404/#1197. It currently detects id collisions between bundle patches and user-patch inserts (#1404 class — run it before installing, and you'll know whether the next boot crashes), and is structured to extend to dangling references / resolution failures (#1197 class) and top-level @deepseek-ai/* duplication (#1486 class).

It complements, rather than conflicts with, a future official dsh doctor — user-side first, official-side later.

[Electricitysheep]

感谢补充——check-dsh-profile.mjs 这个定位很清晰：装前跑一次就知道下次 boot 会不会崩，比事后排障划算得多。"用户侧先行、官方侧后续"这个节奏我也认同，官方 dsh doctor 值得做，但社区的 check 工具能先把坑填上。

已把这个工具收录进手册第 13 章（插件安全审计的配套工具）——顺带建议：如果方便的话把检测覆盖写成文档（当前 #1404 类 → 计划扩展 #1197 悬空引用/#1486 宿主重复），方便其他人接着扩展。https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/13-security.md

[moonquake2004]

Thanks for including it! Done as suggested — the detection coverage is now documented in the script's header comment (it travels with the script, so anyone extending it sees it directly):

• Implemented (dsh plugin add promotes pre-existing bundle-declaring deps into the bundle stack and breaks the next boot with "duplicate loader entry id" #1404 class): id-collision detection between bundle-layer patches and user-patch inserts;
• Planned extensions: dsh web fails to boot: unresolvable plugin reference in profile patch (cordis.patch.yml) #1197 class (resolvability of insert name: from the profile anchor / dangling file: links), Tool layer fails with "Cannot read properties of undefined (reading 'prepare')" after installing third-party plugins #1486 class (top-level @deepseek-ai/* duplication against the framework install);
• How to extend: the script is organized as "bundle resolution → patch parsing → user-patch parsing → comparison", so a new check class is just one more parse function.

Will implement (b)/(c) when I get a chance. Keep up the great work on the handbook — chapter 13 is solid!