dsh CLI on Windows: entry import failures — invisible on 0.1.5-rc.2, downgraded to a warning but still opaque on 0.2.0-rc.2

[jilian-dsh]

中文摘要（先看这一段即可，英文正文在其后）

现象（0.1.5-rc.2 实测）

在 Windows 上，用 npm 装的 dsh CLI 启动时会无声失败：它先正常打印出一个带临时口令（token）的网址，然后进程直接退出、退出码 1。屏幕上唯一的提示是：

dsh: plugin tree failed to load: dsh: plugin(s) failed to load: @deepseek-ai/dsh-sandbox-local;
Cordis startup failed because these plugin(s) could not be resolved (see the error(s) logged above)

而那句"see the error(s) logged above（见上文记录的错误）"所指的上文——从未出现过。任何 profile 都一样：新造的 profile 和机器上原有的 web profile 都起不来；官方桌面版不受影响。

现象（0.2.0-rc.2 实测，同一支探针）

同一支"导入期必抛错"的插件，在 0.2.0-rc.2 上不再拖垮启动：进程继续运行并正常提供网页服务（有网址、HTTP 303、观察窗内未退出），只在 stderr 留两行：

dsh: warning: 1 entry did not activate
<探针插件> (file:///…/probe-import-throw.mjs): failed to import

但抛出的真实错误原文，两个版本都看不到。

真正的病因（一句话）

一个名为 @deepseek-ai/dsh-win32-process 的零件包，在本机那棵既有的 0.1.5-rc.2 安装树里被放下了四份一模一样的副本（实测）。其中两份会在同一个进程里先后被加载，而每一份在被加载的那一刻都会去 koffi（一个调用 Windows 系统接口的底层库）的全机唯一登记簿上登记一个名字 DSH_STARTUPINFOW：
（限定：这是"某棵树的既有状态"，不是该版本的必然产物——把全新的 0.1.5-rc.2 装进空目录时，本机实测只有 1 份副本。）

打个比方：装零件时要在一本全机唯一的登记簿上登记一次名字。同一个零件被两个仓库各送来一份，第二份去登记时系统发现名字已被占用，当场拒收——可这张拒收单只被塞进了内部记录本，墙上没贴告示，所以外面只看到"这个插件没装上"，看不到为什么。

第二次登记被驳回时抛出的错误正是：Error: Duplicate type name 'DSH_STARTUPINFOW'。抛错位置：…\dsh-sandbox-local\node_modules\@deepseek-ai\dsh-sandbox-windows-acl\node_modules\@deepseek-ai\dsh-win32-process\lib\index.js:35。

为什么使用者看不到原因（第二个独立缺陷，两个版本各有其形）

Cordis 的插件加载器在 Entry._init() 里这样写（cordis-plugin-loader\lib\index.js:448-462）：

try { exports = await this.parent.tree.import(this.options.name, this.getOuterStack) }
catch (error) { this.ctx.logger.error(error); return }   // ← 只记内部日志，不往外抛

类比：fiber ＝ 插件在启动队列里分到的座位。加载出错时它 return 了——等于连座位号都没发出去就退出，于是这条插件永远"没有座位"。

在 0.1.5-rc.2（实测）：随后 dsh-app-boot 的 assertEntriesLoaded（该版 :1434-1440）只检查"有没有座位"，把这条报成"无法解析"（could not be resolved）——措辞本身是误导，因为解析其实没问题（下面有反证）；而本该解释清楚的另一段检查 assertEntriesActivated（该版 :1465-1488，它会打印"在等哪个服务"）永远轮不到执行，因为它被前面那句抢先抛错中断了。再加上 --dump-config（只做静态检查、不真正启动）能通过，所以静态闸也拦不住。

在 0.2.0-rc.2（实测 + 读码）：这套检查已被改写。assertEntriesLoaded / assertEntriesActivated 连同 could not be resolved、see the error(s) logged above 这两句措辞，在该版 dsh-app-boot 里已不存在；取而代之的 auditStartupEntries（:4009-4020）按一张必需名单 requiredStartupEntryIds（:3836-3844，仅含 agent-loop、webserver、modules、connection、headless-runner、acp、sdk-jsonrpc-server）判定致命性：名单内条目失败才 throw，其余只 warn，并明确"让成功的兄弟条目继续运行"。提示语也改为点名式：N entry did not activate + <id> (<name>): failed to import。
代价是：inactiveEntries 对"没有座位"这一情形写的是硬编码字符串 "failed to import"（该版 :3905-3913），不携带被 Entry._init() 吞掉的那条异常——所以错误原文依旧不可见（实测：注入的标记在 stdout / stderr 均未出现）。

关键反证（说明"解析"没问题）

检查	结果
在全新进程里 import 这个包	✅ 成功
在最小 Cordis 环境里加载它	✅ 成功激活（座位已分到）
createRequire(profileDir).resolve(...)	✅ 能解析到
独立跑 --dump-config	✅ 通过

也就是说：单独看它没问题，放进完整启动树里才炸。

怎么把被吞掉的错误挖出来（手法可复用）

用 --patch 临时挂一个自己写的小诊断插件（不落盘、不改 profile），在它的 apply() 里做两件事：

1. 把 ctx.logger.error 包一层，让它同时写到 stderr；
2. 直接调用 ctx.loader.import(name, () => [])——这个入口会把错误抛给调用者，不吞。

一试即得 Duplicate type name 'DSH_STARTUPINFOW'。
（注意：--patch 是 dsh 的主命令选项，必须排在透传给 web app 的 --port/--no-open 之前，否则会报 unknown option。）

问题现状与建议（据 0.2.0-rc.2 实测更新）

#	建议	现状与理由
1	入口 import 失败必须让使用者看得见	部分已解决（0.2.0-rc.2 实测）：已做到条目级可见（点名哪一条失败）且不再拖垮启动（降级为 warning，成功的兄弟条目继续服务）。仍未解决：失败原因只是硬编码的 failed to import，不携带真实异常——使用者知道"某条没起来"，仍不知道"为什么"。建议把 Entry._init() 捕获到的那条错误一并带出（重抛，或至少在 warning 里附上原文）。
2	发布依赖图去重，让 @deepseek-ai/dsh-win32-process 只有一份物理副本（提升到顶层，或让两个依赖方共用一份）	多副本不是版本固有、而是安装树的历史状态（补测）：本机把全新的 0.1.5-rc.2 与 0.2.0-rc.2 各装进空目录，两者都只有 1 份副本；出问题的是一棵既有的 0.1.5-rc.2 树（4 份，疑由多轮安装累积）。因此建议：把"单个安装树内 dsh-win32-process 副本数必须为 1"作为安装/升级后的自检项，并在出现多副本时给出可执行的修复指引。
3	让 koffi 的结构登记变幂等或惰性（首次使用时才登记，或先查再登记）	不变：防御性建议——将来任何重复副本、双路径导入、热重载都可能让"全机唯一登记簿"再次撞名。

另需提醒使用者的一个副作用：0.2.0-rc.2 的降级策略意味着非必需插件会静默降级——实例照常服务、界面照常可用，若不看 stderr 就会以为一切正常，而实际上某条插件（例如沙箱能力）并没有起来。建议在文档或 CLI 提示里明确"warning 需要留意"，或提供一个查询"当前有哪些条目未激活"的命令。

环境

项	值（实测）
操作系统	Windows 11
Node	v24.19.0
包	@deepseek-ai/dsh；版本 0.1.5-rc.2（既有树 + 全新装各一次）、0.2.0-rc.2（全新装）
安装根	<npm 全局前缀>\node_modules\@deepseek-ai\dsh
副本读数	既有 0.1.5-rc.2 树 4 份；全新 0.1.5-rc.2 1 份；全新 0.2.0-rc.2 1 份（均为落盘后 glob 实测）
受影响（既有 0.1.5-rc.2 树）	任何 profile（新建的与既有的都失败）
受影响（0.2.0-rc.2）	启动不受影响；失败条目仅告警——这正是需要留意的新形态
未受影响	官方桌面版实测不受本故障影响（原因未核实：其依赖树打包在 app.asar 归档内，我们没有在该归档内部核对副本数，故不对成因作断言）

---

English body

Summary

On Windows, an npm-installed dsh can fail to boot with no error text at all — and the behaviour differs by version, as measured on this machine:

• 0.1.5-rc.2 (existing install tree): the process prints its web URL, then exits with code 1. The only message is the one quoted below — and nothing was "logged above". The real cause is a Duplicate type name 'DSH_STARTUPINFOW' thrown while importing @deepseek-ai/dsh-sandbox-local, and the loader swallows it.
• 0.2.0-rc.2 (fresh install): the same failing entry no longer takes startup down — the instance keeps serving (URL printed, HTTP 303) and only two stderr lines appear: dsh: warning: 1 entry did not activate plus <id> (<name>): failed to import. The thrown exception itself is still not shown.

Two separate problems are worth fixing upstream: (1) a dependency-tree defect — on the affected existing 0.1.5-rc.2 tree, @deepseek-ai/dsh-win32-process exists as four physical copies, and loading two of them in the same process collides in koffi's global type registry; (2) a diagnosability defect — a failed entry import() leaves the loader entry with no fiber and its exception goes only to ctx.logger.error, so on 0.1.5-rc.2 it surfaces as "could not be resolved", and on 0.2.0-rc.2 as a bare failed to import with no reason.

1. Reproduction

Precondition — this is a property of the install tree, not of the version. The failure was observed on an existing 0.1.5-rc.2 tree on this machine, in which @deepseek-ai/dsh-win32-process exists in four physical copies. To separate the two variables we also measured fresh installs into empty directories:

Install on this machine	Packages added	@deepseek-ai/dsh-win32-process copies (globbed after install)
existing 0.1.5-rc.2 tree	(accumulated)	4
fresh npm install @deepseek-ai/dsh@0.1.5-rc.2 --prefix <fresh-dir>	520	1
fresh npm install @deepseek-ai/dsh@0.2.0-rc.2 --prefix <fresh-dir>	536	1

So: a fresh 0.1.5-rc.2 install does not reproduce the four copies; the affected tree appears to have accumulated them over multiple installs/upgrades.

# on the affected (existing) tree
node <existing-0.1.5-rc.2-install>/node_modules/@deepseek-ai/dsh/lib/bin.js --profile web --port <port> --no-open

Observed there: prints dsh web: http://127.0.0.1:<port>/?token=…, then exits code=1 with the message quoted above. No profile-specific configuration is involved — a brand-new profile created with --from-default-profile web fails identically, and so does the pre-existing web profile.

To isolate the diagnosability behaviour from the dependency-tree defect, we mounted a trivial plugin that simply throws at import time (top-level throw new Error(...)) via a --patch overlay, and ran it against both versions:

Reading	0.1.5-rc.2	0.2.0-rc.2
exit code	1	none (process stayed alive)
URL printed	never	yes
HTTP probe	—	303
stderr	Error: dsh: plugin tree failed to load: … plugin(s) failed to load: @deepseek-ai/dsh-sandbox-local, <probe>; Cordis startup failed because these plugin(s) could not be resolved (see the error(s) logged above)	dsh: warning: 1 entry did not activate + <probe> (file:///…): failed to import
thrown error text visible?	no	no

2. Root cause: duplicate dsh-win32-process copies → koffi type collision

@deepseek-ai/dsh-win32-process/lib/index.js registers a koffi struct at module evaluation time:

import koffi from "koffi";
const STARTUPINFOW = koffi.struct("DSH_STARTUPINFOW", { cb: "uint32", ... });   // line 35

koffi's type registry is process-global. On the affected existing 0.1.5-rc.2 tree, this package exists at four paths (measured with a glob over that install tree):

…/@deepseek-ai/dsh-base/node_modules/@deepseek-ai/dsh-subprocess-local/node_modules/@deepseek-ai/dsh-win32-process
…/@deepseek-ai/dsh-base/node_modules/@deepseek-ai/dsh-sandbox-local/node_modules/@deepseek-ai/dsh-sandbox-windows-acl/node_modules/@deepseek-ai/dsh-win32-process
…/@deepseek-ai/dsh-sdk-minimal/node_modules/@deepseek-ai/dsh-subprocess-local/node_modules/@deepseek-ai/dsh-win32-process
…/@deepseek-ai/dsh-sdk-minimal/node_modules/@deepseek-ai/dsh-sandbox-local/node_modules/@deepseek-ai/dsh-sandbox-windows-acl/node_modules/@deepseek-ai/dsh-win32-process

Two distinct copies therefore evaluate in the same process, and the second one throws:

Error: Duplicate type name 'DSH_STARTUPINFOW'
    at …/dsh-sandbox-local/node_modules/@deepseek-ai/dsh-sandbox-windows-acl/node_modules/@deepseek-ai/dsh-win32-process/lib/index.js:35:28
    at async Entry._init (cordis-plugin-loader/lib/index.js:451:14)
    at async EntryGroup.create (cordis-plugin-loader/lib/index.js:62:3)
    at async Promise.all (index 30)

dsh-sandbox-local statically imports dsh-sandbox-windows-acl, which statically imports dsh-win32-process, so the sandbox row always pulls in one copy; whichever path pulls in another copy first determines the outcome. We could not pin down the exact second loader: disabling the subprocess row did not prevent the collision, because that package is also reachable through ordinary import chains.

Both fresh installs measured here contained exactly one copy (see the table in §1), at <install-root>/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-win32-process (0.1.5-rc.2) respectively <install-root>/node_modules/@deepseek-ai/dsh-win32-process (0.2.0-rc.2) — i.e. this is a tree-state problem, not a version-inherent one.

3. Why the user sees nothing: the loader swallows the exception

@deepseek-ai/cordis-plugin-loader/lib/index.js (Entry._init, lines 448–462):

async _init() {
  let exports;
  try { exports = await this.parent.tree.import(this.options.name, this.getOuterStack) }
  catch (error) { this.ctx.logger.error(error); return }   // ← logged only, never rethrown
  finally { this._initTask = void 0 }
  ...
  this.fiber = this.ctx.registry.plugin(...).ctx.fiber     // ← unreachable on failure ⇒ entry keeps no fiber
}

On 0.1.5-rc.2 (measured): @deepseek-ai/dsh-app-boot then audits the settled tree (assertEntriesLoaded, lines 1434–1440) and reports every entry with fiber === undefined && !disabled as "could not be resolved". The message points at "the error(s) logged above", but ctx.logger.error output never reached stdout/stderr — and the follow-up audit that would explain things (assertEntriesActivated, lines 1465–1488, which reports pending entries' missing services) is never reached, because assertEntriesLoaded throws first. --dump-config passes, so static checks cannot catch it either.

On 0.2.0-rc.2 (measured + source): that audit has been rewritten. assertEntriesLoaded / assertEntriesActivated, along with the strings could not be resolved and see the error(s) logged above, no longer exist in this version; auditStartupEntries (:4009-4020) instead decides fatality from a required list requiredStartupEntryIds (:3836-3844 — only agent-loop, webserver, modules, connection, headless-runner, acp, sdk-jsonrpc-server): entries in that list failing cause a throw; everything else only produces a warning, and successful siblings keep running. The wording became per-entry: N entry did not activate + <id> (<name>): failed to import. The cost: for the "no fiber" case inactiveEntries writes a hard-coded string "failed to import" (:3905-3913) and does not carry the exception swallowed by Entry._init() — which is exactly why the thrown message is still invisible (measured: our injected marker appeared in neither stdout nor stderr).

4. How we got the real error (workaround others can reuse)

Mount a tiny diagnostic plugin via --patch and, inside its apply(): (1) wrap ctx.logger.error to also write to stderr; (2) call ctx.loader.import(name, () => []) directly — that entry point rethrows instead of swallowing. That immediately surfaced Duplicate type name 'DSH_STARTUPINFOW'. (--patch is a top-level dsh option and must precede the pass-through web-app flags.)

5. Suggested fixes (upstream) — updated against 0.2.0-rc.2

1. Surface entry import failures — partially done in 0.2.0-rc.2: failures are now per-entry visible and no longer fatal. Still missing: the warning states only the hard-coded failed to import, without the real exception. Please propagate the error Entry._init() catches (rethrow it, or at least append it to the warning), so "which plugin" and "why" are both visible.
2. Keep @deepseek-ai/dsh-win32-process to a single physical copy per install tree — the multi-copy state is not version-inherent (measured): fresh installs of both 0.1.5-rc.2 and 0.2.0-rc.2 into empty directories each contained exactly one copy, while the affected tree had accumulated four. Suggest an install/upgrade self-check for "copies of dsh-win32-process in this tree == 1", with actionable repair guidance when it fails.
3. Make Koffi struct registration idempotent / lazy — unchanged; defensive against any future duplicate copy, dual-import path, or hot reload.

One side effect worth documenting: 0.2.0-rc.2's policy means non-required plugins degrade silently — the instance serves normally, so a user who does not read stderr will assume everything is fine while some capability (e.g. the sandbox) is not actually up. Consider marking these warnings as attention-worthy in the CLI, or exposing a way to query which entries are inactive.

6. Environment details

Item	Value (measured)
OS	Windows 11
Node	v24.19.0
Package	@deepseek-ai/dsh; 0.1.5-rc.2 (existing tree + one fresh install) and 0.2.0-rc.2 (fresh install)
Install root	<npm global prefix>\node_modules\@deepseek-ai\dsh
Copy readings	existing 0.1.5-rc.2 tree: 4; fresh 0.1.5-rc.2: 1; fresh 0.2.0-rc.2: 1 (all globbed from disk after install)
Affected (existing 0.1.5-rc.2 tree)	any profile — a freshly created profile and the pre-existing web profile both fail
Affected (0.2.0-rc.2)	startup unaffected; failing entries only warn — the new form to watch
Not affected	the official desktop build was measured to be unaffected; the reason is not verified — its dependency tree is packed inside the app.asar archive and we did not inspect copy counts inside that archive, so no claim is made about the cause

[argszero]

Where the reason goes, and a seam a plugin can use today

Your second defect reproduces as described, and on the loader side it is one line. I traced it on d743267388 and built a ~20-line probe for the part that looks unreachable.

Why inactiveEntries cannot carry the text

vendor/loader/src/config/entry.ts:223-229:

private async _init() {
  let moduleNamespace: unknown
  try {
    moduleNamespace = await this.parent.tree.import(this.options.name, this.getOuterStack)
  } catch (error) {
    this.ctx.logger.error(error)
    return        // <- no fiber is created
  }
  ...
}

The entry never gets a seat, so entry.fiber === undefined is the only trace left behind, and packages/boot/app-boot/src/index.ts:839 fills exactly that branch with a literal:

if (fiber === undefined) {
  failures.push({ entry, outcome: { kind: 'failed', error: 'failed to import' } })
  continue
}

Note the asymmetry one branch above it (:834): disabled expression failed carries the real error object, because that catch is in the same frame. The import case cannot — the exception died inside the loader.

The seam: ctx.logger.exporter() sees it, and a late-mounted plugin can still recover it

vendor/cordis/src/logger.ts:232 (LoggerService.exporter) registers a sink. Child contexts come from Context#extend (vendor/cordis/src/context.ts:99) via Object.create(...), and the LoggerService instance is constructed once on the root (context.ts:81), so the exporter map is shared: an exporter registered from any context receives messages logged from every context — including entry.ctx.logger.error(error) at entry.ts:228 (an entry's ctx is loader.ctx.extend(...) at entry.ts:59).

Three probe results (cordis 4.0.4 + cordis-plugin-loader 1.0.6-alpha.1):

1. Scope. An exporter registered on a child context saw 5/5 messages logged from the root, another child and a grandchild. root.logger === child.logger is false (each read is a fresh view), but the sink lives on the shared instance.
2. The swallowed error arrives intact. With a real Loader and an entry whose module throws at import, the exporter received { type: 'error', name: 'loader', args: [Error] } with args[0] instanceof Error === true, message Error: BOOM-from-module-import: ..., and a stack that still points at the failing module (at file:///.../boom.mjs:1:7).
3. Mount order is not a problem. LoggerService also keeps a built-in ring buffer (logger.ts:195-196, 213-221, 1000 messages). A context created after the failure read the error back out of ctx.logger.buffer — so a profile entry mounted later still sees earlier failures instead of missing them.

That is a plugin-shaped way to stop the text from being lost, and it is the same idea your --patch probe used (wrap the logger), expressed as a supported API instead of a patch.

Honest boundaries of that route. It recovers what the process logged, not a structured entry-to-error link: attributing a captured error to a specific entry is by specifier/URL (present in the stack) and by time, not by an authoritative field, because no such field exists today. The buffer is bounded (1000 messages), so on a very noisy boot the earliest ones can be evicted, and anything a plugin writes straight to the process's stderr instead of through the cordis logger is invisible to it.

The real fix is still core

Carry the error where it already exists: have Entry._init's catch record the rejection on the entry (or hand it to the tree), so inactiveEntries can report it instead of the literal 'failed to import' — the shape disabled expression failed already uses at :834. Until then the diagnostics above are a workaround for the symptom, not a substitute for the message.

[jilian-dsh]

@argszero — this is the answer we were hoping for, and the exporter() seam is more than we expected to get.

Confirming your trace independently

We reproduced the two structural facts on 0.2.1-rc.2 as well:

• entry.ts's catch logs and returns without creating a fiber, so entry.fiber === undefined is the only residue the entry leaves behind;
• app-boot fills exactly that branch with the literal 'failed to import', while the sibling branch above it (:834) carries the real error object because that catch sits in the same frame.

Your framing — "the exception died inside the loader" — is precisely what we observed, and we had been reading the literal as "the error was never available" rather than "it is available one layer down".

What we'll try with the seam

The part that matters for us is that LoggerService is constructed once on the root and shared through Context#extend, so an exporter registered from any context sees entry.ctx.logger.error(error) from entry.ts:228. We're going to register an exporter from a late-mounted plugin context and see whether we can attribute the swallowed import error back to a specific entry — turning 'failed to import' into an actionable message without patching the loader. If it works we'll post the minimal probe and the plugin here.

A related shape in the same class

Separately, we had a case where a preset's skill list came back completely empty and the only user-visible symptom was the word unknown against every skill name — no error anywhere in the UI or the logs. Same family as your point: the exception dies in an intermediate layer and the outer layer can only report an absence. That is why we think keeping the error object on the inactive entry — even as a non-serializable field or through a side channel — belongs upstream rather than being left for each consumer to rediscover via the exporter.

Thanks again; the probe is a clean piece of work.