Recoverable startup mode for incompatible optional plugins

[overact]

Motivation

DeepSeek Harness is evolving quickly, and compatibility-breaking changes are expected during the developer-preview phase. Optional and third-party plugins can therefore become temporarily incompatible with a newer DSH release.

Today, if one of those plugins prevents the application from starting, DSH cannot help diagnose or repair itself because its own UI and agent are unavailable. Recovery requires manually editing configuration or switching to another agent/tool. That is especially inconvenient for users who rely on DSH as their primary development environment.

Could DSH provide a built-in recoverable startup mode for failures caused by optional plugins?

Proposed behavior

1. Always attempt the formal profile normally first.
2. If startup fails before reaching readiness, preserve the original error and leave the formal configuration untouched.
3. Build an ephemeral shadow profile from the same package and patch layers.
4. Keep mandatory/core layers fixed and isolate only optional plugin bundles or user patch entries.
5. Start DSH with the largest known-good optional set.
6. Show a prominent safe-mode notice containing:
   • which optional entries were skipped;
   • the redacted original startup error;
   • an explicit action to retry the formal profile.
7. On the next launch, retry the formal profile first instead of making the degraded profile permanent.

An opt-in flag such as dsh web --recover-optional-plugins could be a reasonable first version before considering automatic recovery by default.

Safety boundaries

• Never skip core runtime, sandbox, permission, authentication, or other security-critical layers.
• If a mandatory layer fails, stop and report the failure normally.
• Never delete, rewrite, disable, upgrade, or reinstall entries in the user's formal profile.
• Keep the degraded profile clearly visible; do not silently present it as a normal startup.
• Redact credentials and credential-bearing URLs from captured diagnostics.
• Bound all readiness probes with timeouts and terminate probe processes cleanly.

Why this belongs in the launcher/profile-boot layer

A normal plugin cannot implement this reliably: when plugin loading prevents startup, the recovery plugin may never load either. The supervisor needs to live outside the profile it is supervising, while an optional browser plugin can render the notice after the shadow profile becomes ready.

Conceptually:

const normal = await runDsh({ home: formalHome, timeout: readyTimeout })
if (normal.ready) return normal.wait()

const failure = redact(normal.output)
const candidate = await buildShadowProfile({
  source: formalHome,
  mandatory: coreEntries,
  optional: optionalEntries,
  probe: (profile) => runDsh({
    home: profile,
    port: 0,
    timeout: probeTimeout,
  }),
})

await writeStatusAtomically({
  mode: 'safe',
  skipped: candidate.skipped,
  originalError: failure,
})

return runDsh({ home: candidate.home }).wait()

The shadow-profile builder can test optional bundles and atomized user patch entries, cache the accepted set by a fingerprint of the DSH version plus profile inputs, and invalidate that cache whenever packages, patches, or local plugin code change.

Expected benefit

This would keep DSH available as the tool used to inspect and repair its own optional-plugin compatibility problems, while preserving a fail-closed boundary for core and security-sensitive functionality.

Would this recovery model fit the intended profile-boot architecture? If so, I would be happy to help refine the behavior and safety contract.

[overact]

Additional recovery boundary: client-side plugin boot

One additional boundary is worth accounting for in the recovery model: there are two different notions of startup readiness.

1. Host readiness: the DSH web process is alive and has announced/listened on its URL.
2. Client readiness: the browser shell has imported, materialized, and applied the required client loader entries.

A supervisor that treats host readiness as final readiness can miss failures in the second phase. The server process may remain healthy while the browser is already showing Failed to load plugins; because there is no process exit or pre-readiness failure, process-level safe mode is never triggered.

This does not change the original proposal, but it tightens the readiness contract and suggests a complementary implementation path:

• Let the browser shell own a structured client-boot state such as loading | settled | failed, including the loader entry, owning plugin, whether it is mandatory, and a redacted error.
• Report that state to the launcher through a local status endpoint, IPC channel, or one-time boot handshake.
• Do not mark normal startup as fully ready until client boot reports settled (or a bounded timeout expires).
• For an optional client entry failure, let the loader/shell quarantine that entry only for the ephemeral recovery run, then continue or reload with the reduced optional set.
• Keep core, authentication, permission, sandbox, and security-sensitive entries fail-closed.

This recovery component can still be plugin-shaped, but it needs to be a first-class boot/shell plugin that is statically loaded before profile plugins and excluded from the optional set it supervises. An ordinary third-party client plugin cannot reliably provide recovery because it is itself imported through the failing loader and may never execute.

A small loader extension point—for example, an onEntryError hook plus structured client-boot status—would make this modular without requiring downstream users to monkey-patch or fork the client loader. The launcher/profile supervisor could then handle process/profile recovery, while the shell-level component handles failures that only become visible after the browser starts.

[Fable-Forge]

支持这个提案。补充一份确定性复现和现场堆栈，希望能让它更可落地 ——
我们这两天正好被这个问题卡了一整天。

确定性复现（不依赖任何特殊环境）

关键点是：包体本身完好，只是它的清单读不到。

# stock 安装下 node-pty 包根目录没有 index.js，所以移开 package.json
# 就足以让 ESM 解析失败
$d = "$env:LOCALAPPDATA\npm-cache\_npx\<hash>\node_modules\node-pty"
Rename-Item "$d\package.json" "package.json.bak"

dsh web --host 127.0.0.1 --port 3081

结果：进程约 1~2 秒后以 code=1 退出，端口只短暂 listening 过一瞬：

t=+1s http=000 listening=1
t=+2s http=000 listening=0     <- 进程已死

Error: dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include):
       failed to import loader entry subprocess (@deepseek-ai/dsh-subprocess-local):
       Cannot find package '...\node_modules\node-pty\index.js' imported from
       ...\node_modules\@deepseek-ai\dsh-subprocess-local\lib\index.js
    at legacyMainResolve (node:internal/modules/esm/resolve:201:26)
    at Entry._init (@deepseek-ai/cordis-plugin-loader/lib/index.js:519:10)
    at async EntryGroup.create (@deepseek-ai/cordis-plugin-loader/lib/index.js:55:4)
    at async Promise.allSettled (index 22)
    at async EntryGroup.update (@deepseek-ai/cordis-plugin-loader/lib/index.js:87:21)
    at async Include._apply (@deepseek-ai/dsh-app-boot/lib/index.js:238:3)
    at boot (@deepseek-ai/dsh-app-boot/lib/index.js:1186:9)
    at async runProfile (@deepseek-ai/dsh/lib/profile-boot-*.js:247:14)
  { code: 'ERR_MODULE_NOT_FOUND' }

把 package.json 改回来，同一条命令 0 错误、正常服务。

环境：@deepseek-ai/dsh@0.1.0-rc.6、cordis-plugin-loader@1.0.2、
node-pty@1.1.0、Node.js v24.19.0、Windows 11 (10.0.26200)。

一个观察：Discussions 里已有十几贴其实是同一个根因

搜 node-pty / plugin tree failed / ERR_MODULE_NOT_FOUND 能看到大量帖子，
症状各不相同，但结局都一样 —— 某一个插件或它的某个依赖出问题，整个后端起不来：

• node-pty 没有 linux-x64 预编译版本，也没有构建回退（Ernest-su）
• npx @deepseek-ai/dsh web 使用 node-pty 失败（杯赛）
• npm 全局安装后 dsh web 启动失败：node-pty 原生模块 pty.node 失败（尼诺莫里亚蒂）
• Bug: Git 安装插件未 build（無 dist/）導致 plugin tree 崩潰、backend 無法啟動（kenchioua）
• Globally installed dsh cannot boot any profile: every plugin import fails with
  ERR_MODULE_NOT_FOUND（mylastfree）
• [Bug] dsh web --port accepts out-of-range values and fails with a plugin-tree
  stack trace（kermars39-web）
• dsh web fails to boot: unresolvable plugin reference in profile patch
  (cordis.patch.yml)（boyin111-1）
• [Bug] web profile 缺省依赖 dsh-plugin-store 导致 ERR_MODULE_NOT_FOUND（xx-1-a）
• Bug: 安装插件时 npm 删除 dsh 核心包导致 dsh web 启动失败（Beihaisir）
• dsh-skill-filesystem: fatal process exit on ELOOP caused by circular junctions
  in user skill directory（q1023240585-code）
• 以及若干 "install failed" / "大佬求教，安装不上了" / ArchLinux、Ubuntu 装不上

也就是说：这个提案不只是"锦上添花的安全模式"，
而是能一次性把上面这一大类"装不上/起不来"报告的杀伤力降下来的改动。
现在的情况是每个用户都得自己定位到"是哪个插件的哪个依赖坏了"才能自救，
而错误信息通常指不到那一层。

关于实现位置的一点具体建议

堆栈里 EntryGroup.update 已经用了 Promise.allSettled，
但失败最终仍被 Include._apply 向上抛出并终止 boot()。所以可能不需要
"影子 profile" 那么大的改动，先在 entry 粒度上吞掉导入异常就能拿到大部分收益：

• cordis-plugin-loader/lib/index.js：Entry._init（:514 / :519）与
  updateError（:299）—— 失败时把该 entry 置为 error 状态，不向上传播
• dsh-app-boot/lib/index.js：Include._apply（:238）—— 汇总失败项后继续
• 保留一个 --strict-plugins 之类的开关给 CI 用，维持"任一失败即中止"

另外很同意作者关于"透明展示降级状态"的原则。建议把失败的 entry 直接显示在 Web UI 上
（例如「终端功能不可用：subprocess 插件加载失败」），
用户看到这句话就能自己去查，而不是只看到进程退出。

补充：我们这次的真实触发原因

不是手动删文件。是公司统管电脑上的透明加密 DLP（文件层过滤驱动）
把 node_modules 里 6 个 .js/.json 处理成了不可读状态
（加密过程被关机打断，留下 0 字节容器），其中一个正好是 node-pty/package.json。

同类触发还有：磁盘坏块、杀软误隔离、npm 缓存被清一半、容器镜像层损坏、
Git 装的插件没 build。这类"环境把某个文件弄坏了"在真实世界里是常态，
不该等价于"整个产品不可用"。

[taltara]

Strongly in favor, and I want to add evidence for why a recoverable startup mode cannot be replaced by a better error screen.

There are two failure severities here, and they are usually discussed as one:

1. The client bundle of a plugin fails to register. The GUI is replaced by the fatal "Failed to load plugins" screen, but the process is alive - host routes still serve, the CLI still works. "Failed to load plugins" fatal screen offers no recovery action #2229 proposes recovery actions on that screen, and that is achievable precisely because something is still running to render them.
2. A host-side row names a module the profile cannot load. Cordis fails module resolution during boot and the process exits. There is no screen, no degraded mode, no UI to put a button on. Recovery is hand-editing YAML or restoring a backup.

I hit both while building tooling that writes overlays. For the second I deliberately inserted a row naming a package that was not installed, expecting one dead entry I could then inspect - and instead got no harness at all. That is the case this proposal addresses and the error screen cannot.

What a recoverable startup mode would need to survive that, from the outside looking in: the decision to skip has to happen before the failing entry is imported, since the import is what kills the process. A skip-and-warn that runs after the tree is composed is too late for exactly the entries that matter most.

Two things that already exist and are worth wiring into the design rather than inventing:

• dsh --profile <name> --dump-default-config deliberately skips the profile and home user layers, so it still answers when the user layer is what broke. I confirmed that on rc.7: a row written into a profile's cordis.patch.yml appears in --dump-config and is absent from --dump-default-config. That makes it a usable bundle-only probe for "would this profile compose without my overlay", which is close to the question a recovery mode has to answer.
• The four community dsh doctor implementations in 💡 Idea: Add 'dsh doctor' CLI command for environment & dependency diagnostics #1719 already detect dangling plugin references offline. A recoverable startup mode and a pre-boot checker are the same predicate on either side of the boot.

Until isolation exists, tools that write config are stuck implementing refusal instead - mine will not write a row whose package is not present in the profile, because after the write there is no running harness left to warn in, and the check is extracted as dsh-overlay-check for anyone else with the same problem. That is a workaround each of us has to build separately, which is a decent argument that the platform should own it.

Also relevant from the operator side: @ylwl1997 reported in #2229 that from their catalog's install telemetry, many "Failed to load plugins" cases are one bad third-party plugin rather than a broken harness - which is the population this proposal would rescue.