dsh web fails to boot: unresolvable plugin reference in profile patch (cordis.patch.yml)

[boyin111-1]

TL;DR

dsh web fails to boot when the profile patch layer references a package that does not exist on npm. The loader applies the reference without validation, and a single dangling entry kills the entire plugin tree — no skip-and-warn, no graceful degradation. This may be related to reports of "plugins missing after restart".

Environment

• dsh: 0.1.0-rc.6 (installed via npm)
• OS: Ubuntu 26.04, Node v24.18.0
• Profile: default web profile

Reproduction

Run dsh web. Observed output:

[plugin-session-export] registered "export_session" — listed=true
Error: dsh: plugin tree failed to load: failed to apply loader entry include
(cordis:include): failed to import loader entry dev-workbench
(@dsh-user/dev-workbench): Cannot find package '@dsh-user/dev-workbench'
imported from /home/boyin/.dsh/profiles/web/
Error [ERR_MODULE_NOT_FOUND]: ...

Root cause

~/.dsh/profiles/web/cordis.patch.yml contains:

- insert:
    - id: dev-workbench
      name: '@dsh-user/dev-workbench'

• @dsh-user/dev-workbench does not exist on npm (npm view → 404).
• It is not declared in the profile's package.json dependencies, and not present in node_modules.
• Nothing validates the reference before the loader tries to import it at boot → hard crash.

Impact

• One dangling reference blocks the entire profile; all other valid plugins fail to load.
• No graceful degradation — unresolvable entries are not skipped with a warning.
• Recovery requires manual YAML editing.

Suggested fixes

1. Validate references before they become boot blockers: resolve name: at write time in the plugin manager / UI (reject 404s immediately), or at minimum validate at boot and surface the exact file/line/entry id.
2. Fail soft: skip unresolvable loader entries with a warning instead of aborting the whole plugin tree.
3. Add a diagnostic command (e.g. dsh doctor / dsh check) that scans profiles for dangling plugin references and undeclared dependencies — this case would have been caught in seconds.

Workaround (applied)

Backed up cordis.patch.yml, removed the dangling insert block. dsh web boots normally afterwards.

[boyin111-1]

A more precise root cause from the author's actual setup (verified against loader source)

To clarify: the package was not missing in the strict sense — it existed in the dsh global installation at …/@deepseek-ai/dsh/node_modules/@dsh-user/dev-workbench/, and createRequire from the loader's own location resolved it fine (which is exactly why my earlier "validation" passed). The real issue is an asymmetric resolution base:

• The loader's baseUrl is the profile directory (the dsh-app-boot source comment says verbatim: "The Loader's baseUrl is the profile directory"). Entry._init() imports via this.parent.tree.import(name, …), and Node's parent-directory walk for a bare specifier starts at the profile dir and climbs its node_modules chain.
• The two-anchor resolution (install anchor → profile dir) applies only to bundle names in dsh.profile.bundles, not to the name of entries inserted via cordis.patch.yml (- insert: blocks). A package placed under the global installation is unreachable from the profile dir's parent walk.
• dsh --dump-config only composes the patch lists — it never actually imports the entries — so a "passing" dump is a false positive for loadability. The reliable check is cd <profile-dir> && node --input-type=module -e "await import('<pkg>')".

Fix that works (matches the dsh plugin add mechanism):

cd ~/.dsh/profiles/web
pnpm add "file:/path/to/your-package"   # or install it into the profile's node_modules normally

Suggestions for the loader, in addition to the great dsh doctor idea:

1. Apply the same two-anchor resolution to patch-inserted name entries as bundles get (install anchor → profile dir), making the behavior symmetric — or document the asymmetry explicitly near the profile docs.
2. On ERR_MODULE_NOT_FOUND for an inserted entry, append a hint like: run 'dsh plugin --profile <name> add <pkg>' or install the package into the profile's node_modules, mirroring the existing bundle-resolution error message.
3. Give --dump-config an opt-in --verify-import that actually imports every entry and reports which ones would fail at boot.

Happy to provide the full repro profile + package if useful.

[boyin111-1]

Upvoting to bring to the team's attention per CONTRIBUTING. Ping @tianyicui @LegGasai — happy to provide the full profile tree or more logs if helpful for reproducing this class of failure.

[boyin111-1]

Update: root cause fully traced — it's a broken file: link, not a missing package

I initially reported this as "package does not exist on npm" — that was wrong. The full chain is now clear:

The real chain

1. @dsh-user/dev-workbench is a bundled plugin inside the dsh install (at <dsh-install>/node_modules/@dsh-user/dev-workbench) — it is not an npm registry package, which is why npm view → 404 is expected, not evidence of absence.
2. It was previously installed into the profile via a file: dependency (pnpm add file:<dsh-install>/.../@dsh-user/dev-workbench). pnpm-lock.yaml still records this.
3. At some point the node_modules link disappeared (the classic "plugins go missing after restart"). The reference in cordis.patch.yml remained, but the package was no longer resolvable from the profile's node_modules chain.
4. The loader resolves bare specifiers with the profile directory as the resolution anchor (cordis-plugin-loader/lib/index.js:264: internal.import(name, this.ctx.baseUrl)). Node's parent-walk goes up the ancestor chain (profile → ~ → /), which can never reach the dsh install directory's nested node_modules — those are sibling branches, not ancestors. Hence ERR_MODULE_NOT_FOUND imported from .../profiles/web/.
5. One dangling entry → Promise.allSettled failure → throw failures[0] in vendor/loader/src/config/group.ts:79 → the whole plugin tree dies.

Three false positives that misled diagnosis

Check	Why it passes but means nothing
npm view @dsh-user/dev-workbench → 404	It's a bundled plugin, not an npm package
createRequire(<loader base>) resolves it	The base sits inside the dsh install, so the parent-walk reaches the nested node_modules — different anchor than the profile
dsh --dump-config passes	It only composes the patch list, never imports entries (Entry._init never runs)

Fix applied (verified)

cd ~/.dsh/profiles/web
pnpm add file:<dsh-install>/node_modules/@dsh-user/dev-workbench
# restore the insert in cordis.patch.yml

Putting the package back into the profile's node_modules puts it on the resolution anchor's parent chain — same mechanism dsh plugin add uses. dsh web boots normally again, plugin restored.

What this case says about the loader

The bug isn't really "a bad reference" — it's that the loader has no way to tell you why resolution failed and no way to degrade. A dangling file: link, a renamed package, a broken hoist — all produce the same opaque ERR_MODULE_NOT_FOUND that bricks the whole tree. Diagnostics like dsh doctor (scan profiles for dangling references / stale file: deps against lockfile) would turn this class of incident from a boot-crash + manual YAML archaeology into a one-command report.

[Electricitysheep]

patch 层引用不存在的包就整包 boot 失败——loader 不做引用校验这个设计确实是隐患，一个悬空引用拖垮整个 profile。

排查思路：看 boot 日志定位是哪个 insert 引用的包解析失败，先在 cordis.patch.yml 里注释掉那一行确认能起来，再决定是补依赖还是删引用。这类依赖/挂载坑第 3 章整理了不少：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/03-profiles.md

[moonquake2004]

Great root-cause tracing — the broken file: link + asymmetric resolution base is exactly right, and the three-false-positives table is the most useful part (it explains why --dump-config passing misled everyone, myself included).

This is the complementary half of what I hit in #1404: same loader, two failure modes from the same design gap.

• dsh plugin add promotes pre-existing bundle-declaring deps into the bundle stack and breaks the next boot with "duplicate loader entry id" #1404 (mine): user patch insert collides with a promoted bundle layer → EntryGroup.update throws duplicate loader entry id at mount. Cause: dsh plugin add's reconcile promotes every dsh.bundle-declaring dep into the bundle stack without cleaning the now-redundant user-patch inserts.
• dsh web fails to boot: unresolvable plugin reference in profile patch (cordis.patch.yml) #1197 (yours): user patch insert references a package unresolvable from the profile anchor → Entry._init import fails with ERR_MODULE_NOT_FOUND, group.ts rethrows the first failure, whole tree dies.

Both share the same three properties:

1. The loader validates neither duplicate ids nor resolvability — one bad entry bricks the entire profile with no skip-and-warn.
2. --dump-config is a false positive in both cases: it composes patch lists but never mounts the loader / imports entries, so the failure only shows on a real boot.
3. Recovery is manual YAML archaeology.

On the dsh doctor idea — strong +1, and it already has a seed: I wrote a small offline pre-boot checker for the #1404 class (compares bundle-patch insert ids against user-patch inserts and flags collisions before boot; it correctly catches the exact crash state). Extending it to also verify that every name: in a user-patch insert resolves from the profile anchor (your #1197 class, via createRequire from the profile dir) turns it into the dsh doctor scan you describe — duplicates, dangling references, and stale file: deps in one report. Happy to share the script and collaborate on the design if you or the team want it.

[boyin111-1]

Update: fix implemented and tested — ready to submit when external PRs open

Per CONTRIBUTING ("cannot accept external pull requests at the moment"), I've prepared the fix on a fork and will submit it as soon as external PRs are accepted. Sharing the implementation here so the team can review or adopt it directly:

What it does

On boot failure (stage === 'plugin tree failed to load'), append an actionable diagnostic to the error: which insert-referenced plugins cannot be resolved from the profile directory (the loader's own resolution anchor), plus a fix hint. No behavior change on the success path; diagnostics are best-effort (wrapped in try/catch so they never mask the original error).

Changes

• packages/boot/app-boot/src/index.ts
  • new diagnoseUnresolvablePlugins(patches, profileDir) — resolves insert-referenced names from the profile dir, returns unresolvable ones (deduplicated, patch order, package-shaped names only)
  • boot() catch path wires it in when the plugin tree fails
• packages/boot/app-boot/tests/diagnose.spec.ts — 5 unit tests (empty / all-resolvable / dangling / mixed+dedup+order / non-package names skipped)

All green locally: pnpm vitest run packages/boot/app-boot/tests/diagnose.spec.ts (5/5), pnpm run typecheck (clean).

Resulting error (instead of bare ERR_MODULE_NOT_FOUND)

dsh: plugin tree failed to load: ... Cannot find package '@ghost-org/never-existed' ...

Unresolvable plugin references (from ~/.dsh/profiles/web):
  - @ghost-org/never-existed
Fix: re-link file: dependencies with `pnpm add file:<path>`, or remove the dangling insert from cordis.patch.yml.

Fork branch: boyin111-1/deepseek-harness → feat/boot-dangling-plugin-diagnostics. Happy to rebase/adjust once external PRs are open — or the team is welcome to take the approach directly (it's small and self-contained).

[boyin111-1]

Same root cause, multiple failure modes — a map of related reports

Thanks @moonquake2004 for linking #1404 — and @Electricitysheep for consolidating into #1496. Searching the forum, this design gap (plugin state coordination without validation/diagnostics) shows up repeatedly, in both directions:

#	Symptom	Direction
#1197 (this)	dangling reference → ERR_MODULE_NOT_FOUND boot crash	unresolvable → dropped (crash)
#1404	plugin add promotes bundle-declaring dep → duplicate loader entry id boot crash	resolvable → silently promoted
#1479	two plugins sharing one id → web boot error	duplicate id (same EntryTree collision)
#1483	shipped preset references non-existent cordis_mount	dangling reference, second instance
#1496	consolidated advisory: plugin-install path needs guardrails	the meta-report

What this says

All of these are the loader/plugin-manager reconciling state blindly: reconcilePlugins (apps/cli/src/plugin.ts) promotes/silently handles entries with no validation, and the loader (group.ts:79) fails the whole tree on any entry error with no diagnostic. A dsh doctor-style check (scan profile patch refs + lockfile file: links + bundle promotion consistency) would have caught every one of these in seconds — the diagnostic approach in my fix (comment above) covers the boot-failure half; guardrails on the install path (per #1496) cover the write half.

Community tooling

For users hitting this now: a standalone dsh-doctor check exists (scans profile patch refs and file: link integrity — zero deps, runs before boot). Happy to share details in this thread if useful.

[boyin111-1]

dsh-doctor is now public — https://github.com/boyin111-1/dsh-doctor

The standalone pre-boot checker mentioned above is released as a GitHub repo (no npm publish needed; dsh users already have Node):

npx --yes github:boyin111-1/dsh-doctor

Checks: dangling plugin refs (from the profile dir anchor), broken file: links, duplicate entry ids (#1404/#1479 class), dual @deepseek-ai instances (#1486 class). Open to issues/PRs there — and happy to fold any of it into #1496 if the team wants it.