Proposal + tested PoC: keep DSH bootable when an optional plugin bundle is incompatible

[franksong2702]

While maintaining an out-of-tree plugin (Codex Connect), we encountered the worst failure mode after a DSH upgrade: an incompatible plugin could prevent the DSH Web application shell from mounting, which also removed the settings/plugin-management path needed to diagnose or remove that plugin.

I built a narrow local proof of concept against deepseek-ai/deepseek-harness@b150a551b8d465e31e418e1b2eaf5e79bbb7d28e before proposing a Core change:

• Branch: https://github.com/franksong2702/deepseek-harness/tree/franksong2702/recoverable-bundle-failures-poc
• Commit: franksong2702@c601d5a861
• Proposed Agent Note: https://github.com/franksong2702/deepseek-harness/blob/franksong2702/recoverable-bundle-failures-poc/.agents/notes/proposed/architecture/2026-08-23-recoverable-profile-bundle-startup.md

Proposed ownership model

This should not be an official-vs-third-party distinction, and a plugin should not declare itself optional. The profile that assembles the application knows whether that deployment requires a bundle.

dsh.profile.bundles remains the ordered layer list. An optional recoverableBundles subset selects failure handling:

• explicit subset: authoritative;
• legacy profile with no subset: dependency-managed bundles default recoverable, installation-owned bundles remain required;
• dsh plugin add: records a newly installed out-of-tree bundle as recoverable;
• an unlisted recoverable name: invalid configuration and fails before startup.

Host behavior in the PoC

Each bundle patch layer is applied as a separate root Include/Loader transaction.

• A required layer rejection preserves the current fail-loud behavior and disposes the complete tree.
• A recoverable layer rejection keeps the preceding committed tree, records a structured fault, and continues with later layers.
• Only accepted bundle patches become the base for live user-patch recomposition, so HMR does not silently retry an isolated layer.
• Rows inserted by an accepted layer carry profile-owned startup provenance.

The activation audit also contains a marked row that imports unsuccessfully, rejects activation, or remains pending. An unmarked row remains fatal.

Browser behavior in the PoC

The Host client-module graph projects only failurePolicy: "recoverable"; absence means required. Browser boot records a marked import/apply/pending failure and continues to mount the required uiRenderer. Required client failures keep the existing fatal boot page.

If the same client package has multiple qualifying Host instances, any required instance wins, including when that instance appears later through lifecycle updates.

Why this still fits “everything is a plugin”

The distinction is not plugin versus core. The application shell, graph composer, UI renderer, and feature packages remain plugins or composition machinery over plugins. The new distinction is required versus recoverable membership selected by the profile that assembles one application. Core only provides the isolation and reporting mechanism.

Verification performed

• focused Host/client suites: 5 files, 130 tests passed;
• follow-up regression suites after self-review fixes: 2 files, 78 tests passed;
• built CLI acceptance: 2 passed, 16 unrelated tests skipped by the name filter;
• repository build: exit 0;
• Host and Client TypeScript project checks: exit 0;
• documentation gates: 27/28 passed in the aggregate run; the sole JSDoc prose failure was fixed and its exact verify-export-jsdoc gate then passed;
• staged lint, translation pairing, whitespace, vendor guard, and pre-push typecheck: passed.

Deliberately deferred

This is a proof of concept, not a claim that the public format is finished. It does not yet define:

• an in-product recovery center or persistent fault history;
• pre-upgrade compatibility checks or automatic rollback;
• ownership when a recoverable layer modifies a row introduced by an earlier required layer;
• UX for a recoverable provider that a required consumer depends on (the required consumer correctly remains fatal, but diagnostics need design);
• unloading a healthy Host half when only its browser half failed.

Questions for maintainers:

1. Does profile-owned required/recoverable policy match the intended composition model?
2. Is one Include update per bundle layer an acceptable transactional seam, or should Loader expose a more explicit startup transaction API?
3. Should recoverable startup faults be a durable Core service/event before any recovery UI is designed?

[franksong2702]

提案 + 已测试 PoC：当可选插件 Bundle 不兼容时，仍让 DSH 保持可启动

在维护一个仓库外插件（Codex Connect）时，我们遇到了 DSH 升级后最糟糕的故障模式：不兼容的插件可能导致 DSH Web 应用外壳无法挂载，同时也让用户失去用于诊断或移除该插件的设置页和插件管理入口。

因此，在提出 Core 修改建议之前，我基于 deepseek-ai/deepseek-harness@b150a551b8d465e31e418e1b2eaf5e79bbb7d28e 实现了一个范围较窄的本地概念验证：

• 分支：https://github.com/franksong2702/deepseek-harness/tree/franksong2702/recoverable-bundle-failures-poc
• 提交：franksong2702@c601d5a861
• 提议中的 Agent Note：https://github.com/franksong2702/deepseek-harness/blob/franksong2702/recoverable-bundle-failures-poc/.agents/notes/proposed/architecture/2026-08-23-recoverable-profile-bundle-startup.md

建议的归属模型

这不应该是官方插件与第三方插件之间的区别，插件也不应该自行声明自己是否可选。负责组装应用的 Profile 才知道当前部署是否依赖某个 Bundle。

dsh.profile.bundles 继续作为有序的层列表。可选的 recoverableBundles 子集用于选择故障处理方式：

• 显式配置的子集具有最终决定权；
• 旧 Profile 没有该字段时，由 dependencies 管理的 Bundle 默认可恢复，由 DSH 安装本身提供的 Bundle 仍为必需；
• dsh plugin add 会把新安装的仓库外 Bundle 记录为可恢复；
• 如果 recoverableBundles 中出现未列入 bundles 的名称，则视为无效配置，并在启动前明确失败。

PoC 中的 Host 行为

每个 Bundle patch 层都会作为一次独立的根 Include/Loader 事务来应用。

• 必需层被拒绝时，保留现有的 fail-loud 行为并释放整棵插件树。
• 可恢复层被拒绝时，保留此前已提交的插件树，记录结构化故障，并继续应用后续层。
• 只有已接受的 Bundle patch 才会成为用户 patch 实时重组的基础，因此 HMR 不会在下一次文件变化时悄悄重试已经隔离的层。
• 已接受层插入的配置项会携带由 Profile 决定的启动来源和策略。

启动后的激活审计同样会隔离已标记但导入失败、激活失败或仍处于 pending 状态的配置项。未标记的配置项仍然是致命错误。

PoC 中的浏览器行为

Host 的 client-module graph 只投射 failurePolicy: "recoverable" 标记；字段缺失就表示必需。浏览器启动过程会记录已标记配置项的导入、apply 或 pending 故障，然后继续挂载必需的 uiRenderer。必需 client 插件失败时，仍保留现有的致命启动页面。

如果同一个 client 包对应多个符合条件的 Host 实例，只要其中任何一个实例是必需的，最终就按必需处理；这也适用于该实例稍后通过生命周期更新出现的情况。

为什么这仍然符合“everything is a plugin”

这里区分的不是插件与 Core。应用外壳、graph composer、UI renderer 和功能包仍然都是插件，或者是建立在插件之上的组装机制。新增的区别是：由负责组装当前应用的 Profile 决定某个成员是必需还是可恢复。Core 只提供隔离和报告机制。

已执行的验证

• Host/client 定向测试：5 个文件，130 项测试通过；
• 自审修复后的回归测试：2 个文件，78 项测试通过；
• 构建产物 CLI 验收：2 项通过，另有 16 项与本次名称过滤条件无关的测试被跳过；
• 仓库构建：exit 0；
• Host 与 Client TypeScript 项目检查：exit 0；
• 文档门禁：聚合执行时 27/28 通过；唯一的 JSDoc 说明文字问题修复后，对应的 verify-export-jsdoc 门禁通过；
• staged lint、翻译配对、whitespace、vendor guard 和 pre-push typecheck：全部通过。

有意推迟的工作

这是一个概念验证，并不是说公开格式已经定型。目前还没有定义：

• 产品内恢复中心或跨重启保存的故障历史；
• 升级前兼容性检查或自动回滚；
• 当可恢复层修改了此前必需层引入的配置项时，如何判定所有权；
• 当必需 consumer 依赖可恢复 provider 时的用户体验——必需 consumer 继续导致致命错误是正确行为，但诊断方式仍需设计；
• 只有浏览器侧失败时，是否卸载仍然健康的 Host 侧插件。

想请维护者讨论三个问题：

1. 由 Profile 决定 required/recoverable 策略，是否符合 DSH 预期的组装模型？
2. 每个 Bundle 层执行一次 Include 更新，是否是合适的事务切入点，还是应该由 Loader 提供更明确的启动事务 API？
3. 在设计恢复 UI 之前，可恢复启动故障是否应该先成为一个持久化的 Core service/event？