[Bug] Web UI stuck on "HARNESS Loading plugins…" — profile module fallback fails to resolve pnpm workspace symlinks (Windows)

[AlexHuangB]

Summary

Running dsh web from a source checkout (pnpm workspace monorepo) on Windows, the browser page at http://127.0.0.1:3080 stays on the boot screen "HARNESS / Loading plugins…" forever. There is no error in the browser console, no failed JS exception, and the server-side boot spinner reaches 100% — the page just never mounts.

Root cause: packageDirFromAnchor() in packages/boot/app-boot/src/profile.ts does not resolve symlinks before computing Node module lookup paths, so packages linked by pnpm's isolated symlink layout via transitive workspace dependencies are never discovered by healProfilesModuleFallback(). As a result the client boot manifest is missing UI plugins — including @deepseek-ai/dsh-client-ui-renderer — and mountApp() hangs forever waiting for the uiRenderer service that is never provided.

Environment

• OS: Windows 11 (should affect any OS using pnpm's default symlink-based isolated node_modules)
• Node: v22.22.2
• pnpm: 11.x (isolated linker, default)
• DSH: 0.1.0-rc.8 (built from source: pnpm install && pnpm run build)
• Command: pnpm dsh web

Symptom

• dsh web starts normally, server listens on 127.0.0.1:3080.
• Browser shows the boot page with "HARNESS / Loading plugins…" indefinitely.
• The spinner arc reaches 288° (ratio = 1.0, i.e. all plugins activated server-side) — so page.fail() is never triggered and no failure message is shown.
• Browser console: no errors, no exceptions.
• Network: all requests return 200 except these plugin bundle requests, which return 404:
  • /plugins/@deepseek-ai/dsh-client-ui-renderer/client.js
  • /plugins/@deepseek-ai/dsh-client-ui-brand-official/client.js
  • /plugins/@deepseek-ai/dsh-client-ui-reference/client.js
• window.__DSH_BOOT__ in the served index.html is missing those packages even though they are declared in packages/bundle/web-app/cordis.patch.yml.

Root cause analysis

The chain, step by step:

1. Fallback healing walks the dependency closure. On every start, healProfilesModuleFallback() (packages/boot/app-boot/src/profile.ts) BFS-walks the dependency closure starting from the apps/cli install anchor and creates flat symlinks under $DSH_HOME/profiles/node_modules/ so that the profile directory (used as ctx.baseUrl) can resolve every composed plugin.

2. pnpm links workspace packages as symlinks. apps/cli/node_modules/@deepseek-ai/dsh-web-app is a symlink to packages/bundle/web-app/.

3. packageDirFromAnchor() uses the symlink path as-is. When the BFS visits dsh-web-app, it calls createRequire(anchor).resolve.paths(packageName) where anchor is the symlink path. Node's resolve.paths() computes lookup paths from the literal path — it does not resolve symlinks — so the returned paths climb up from apps/cli/node_modules/... and never include packages/bundle/web-app/node_modules/, which is where dsh-web-app's own dependencies (@deepseek-ai/dsh-client-ui-*) are actually linked.

4. Transitive UI plugins are never discovered. Consequently the symlinks for dsh-client-ui-renderer, dsh-client-ui-brand-official, and dsh-client-ui-reference are missing from $DSH_HOME/profiles/node_modules/@deepseek-ai/. (In my case dsh-client-ui-attachment happened to be reachable through another dependency chain, which is why only 3–4 of the UI plugins go missing.)

5. Boot manifest excludes the plugins. ClientModuleRegistry.resolveMeta() (packages/client/modules/src/index.ts) resolves each plugin's package.json anchored at ctx.baseUrl (the profile directory). For the missing packages the require.resolve fails, so they are silently excluded from window.__DSH_BOOT__.

6. mountApp() hangs forever. In packages/client/web/src/boot.ts, mountApp() does ctx.inject(['uiRenderer'], ...). Since the ui-renderer client bundle 404s, the uiRenderer service is never provided and the injection never resolves — the boot page stays at "Loading plugins…" indefinitely, with no error surfaced to the user.

Suggested fix

Resolve the symlink before computing lookup paths in packageDirFromAnchor():

 import { createRequire } from 'node:module'
 import {
-  existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync,
+  existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, symlinkSync, unlinkSync, writeFileSync,
 } from 'node:fs'

 function packageDirFromAnchor(anchor: string, packageName: string): string | undefined {
+  let realAnchor: string
+  try {
+    realAnchor = realpathSync(anchor)
+  } catch {
+    realAnchor = anchor
+  }
   /* v8 ignore next */
-  for (const searchPath of createRequire(anchor).resolve.paths(packageName) ?? []) {
+  for (const searchPath of createRequire(realAnchor).resolve.paths(packageName) ?? []) {
     const candidate = join(searchPath, packageName)
     if (existsSync(join(candidate, 'package.json'))) return candidate
   }

Full patch attached.

Verification

After applying the fix:

• healProfilesModuleFallback() creates all missing symlinks under $DSH_HOME/profiles/node_modules/@deepseek-ai/.
• window.__DSH_BOOT__ contains all 42 client plugins (previously 38–39).
• /plugins/@deepseek-ai/dsh-client-ui-renderer/client.js: 404 → 200 (39,268 bytes). All 42 plugin bundles + main entry return 200.
• The page mounts normally past "Loading plugins…".

Standalone repro of the lookup-path bug (no DSH needed):

import { createRequire } from 'node:module'
const anchor = 'apps/cli/node_modules/@deepseek-ai/dsh-web-app/package.json' // a pnpm symlink
createRequire(anchor).resolve.paths('x')
// -> lookup paths based on apps/cli/..., does NOT include packages/bundle/web-app/node_modules

Extra observation

Because the failure mode is "a service that is never provided" rather than an error, the boot page gives zero feedback. It might be worth making mountApp() (or ctx.inject for uiRenderer) time out and surface a diagnostic message — "required client plugin X did not load" — which would have saved hours of debugging.
fix-profile-symlink-resolution.patch

[denial123789]

This report matches the rc.8 ownership chain: healProfilesModuleFallback() is supposed to mirror the app/bundle dependency closure into the Host-owned profile fallback, while the client registry can only advertise packages it resolves from that profile base. Comparing the literal pnpm anchor with its realpath is therefore the decisive test; server activation reaching 100% is not evidence that the client graph is complete.

One extra safety boundary: avoid repairing the missing client rows with a broad install inside the profile. A nearer copy of Cordis, Agent, Session, or Tools can make Web boot appear fixed while splitting core service identity and breaking native/MCP tool calls. For a source-owned fix, rebuild the fallback in a fresh DSH_HOME and require a regression fixture whose dependency exists only under the symlink target realpath.

I turned the full four-layer proof (bundle roster → fallback link → __DSH_BOOT__ row → bundle HTTP response), recovery branches, regression test, and rollback checklist into a source-backed runbook:

https://sandbaseai.github.io/deepseek-harness-handbook/web-loading-plugins-pnpm.html

[AlexHuangB]

Thanks for confirming the rc.8 ownership chain — that's a useful framing. A couple of notes on the specifics:

On the realpath test being decisive. Agreed, and that's exactly what the attached .patch does: packageDirFromAnchor() now calls realpathSync(anchor) before createRequire(anchor).resolve.paths(...), so lookup paths are computed from the real package directory rather than the pnpm symlink's literal path. After applying it, healProfilesModuleFallback() links all four UI plugins (ui-renderer, ui-brand-official, ui-attachment, ui-reference) into $DSH_HOME/profiles/node_modules/, __DSH_BOOT__ lists all 42 client entries, and /plugins/.../client.js flips 404 → 200 for the previously missing ones. Worth flagging: the activation spinner hitting 288° (ratio 1.0) server-side was the exact thing that masked this — all plugins activated, the client just couldn't resolve them, so page.fail() never fired.

On the "broad install inside the profile" caution. Seconded — I deliberately avoided repairing the missing rows with an ad-hoc pnpm install under $DSH_HOME/profiles/ for the reason you describe: a nearer copy of Cordis/Agent/Session/Tools would make Web appear fixed while splitting core service identity and silently breaking native/MCP tool calls. The fix belongs upstream in packageDirFromAnchor(), not in the profile dir.

On the fresh DSH_HOME rebuild + regression fixture. Solid follow-up for whoever picks this up. Concretely, the regression test would assert that a package which only exists under a workspace package's real node_modules (i.e. resolvable only via the realpath, not the symlink literal) still appears in the fallback closure — that's the invariant the current code violates.

I'll hold off on third-party runbooks for now and keep this thread anchored to the in-repo fix + patch.