@deepseek-ai/dsh-app-boot 0.2.1-rc.4 → 0.2.2-alpha.2

package/README.i18n.yaml

@@ -21,11 +21,11 @@
   en: 2fdfe02f2ed4a258
   zh: d748228ece579c4a
 /deepseek-ai-dsh-app-boot/use-this-package/starting-the-app:
-  en: 4a424cd401556f20
-  zh: 0b34dd18e0db6cea
+  en: 65bf2834b81f87da
+  zh: c864ac60a3005b99
 /deepseek-ai-dsh-app-boot/use-this-package/profiles:
-  en: d2d520668668292c
-  zh: b7deeab27032a3ad
+  en: a9c82cd220ae8d59
+  zh: 8c7c1c97efcdfc25
 /deepseek-ai-dsh-app-boot/use-this-package/previewing-the-effective-configuration:
   en: 646a0ccdd7881ad1
   zh: e3696acb1573dd7b
@@ -33,8 +33,8 @@
   en: c4a301652b851ce9
   zh: 784871e19cd9db0a
 /deepseek-ai-dsh-app-boot/use-this-package/reading-plugin-display-metadata:
-  en: a9afb263b03d112c
-  zh: 31f5e797cd953c15
+  en: 91d80c444ac0cfe5
+  zh: e7db496043528ffb
 /deepseek-ai-dsh-app-boot/use-this-package/startup-and-reload-failures:
   en: dc13dfa1f79292e4
   zh: d51682ced7a18ac2
@@ -42,8 +42,8 @@
   en: f4a2695cb4c8a570
   zh: 89837235d2f376cf
 /deepseek-ai-dsh-app-boot/understand-the-implementation/design-notes:
-  en: 9ecb744556705fd1
-  zh: d83aaf2ebb91d0fc
+  en: 6eba01e24a2a68ab
+  zh: 64af424489087ec7
 /deepseek-ai-dsh-app-boot/understand-the-implementation/helper-behavior:
   en: 6fa850d1bb000d0e
   zh: aa83a40a9d3db295

package/README.md

@@ -40,7 +40,7 @@ installFailLoud('dsh')
 const ctx = await boot('dsh', resolveConfigPath(argv[2], process.env.DSH_SNAPSHOT))
 ```
 
-`installFailLoud` writes one labelled `util.inspect` diagnostic to stderr for an unhandled rejection or an uncaught exception, awaits the surface's release hook under a fixed timeout, and exits 1; control never returns to the failed operation, because only the throw site knows which state is intact, and the event loop runs only until the release settles or times out. With that entry point, startup keeps every plugin that can activate. An enabled failed plugin produces a labelled warning. A failed required entry makes startup dispose the whole app and exit nonzero; required ids absent from a profile and disabled required entries do not affect startup. The global required list covers shared Agent execution, application endpoints, and Web bootstrap/transport: `agent-loop`, `webserver`, `web-runtime`, `modules`, `connection`, `headless-runner`, `acp`, and `sdk-jsonrpc-server`.
+`installFailLoud` writes one labelled `util.inspect` diagnostic to stderr for an unhandled rejection or an uncaught exception, awaits the surface's release hook under a fixed timeout, and exits 1; control never returns to the failed operation, because only the throw site knows which state is intact, and the event loop runs only until the release settles or times out. With that entry point, startup keeps every plugin that can activate. An enabled failed plugin produces a labelled warning. A failed required entry makes startup dispose the whole app and exit nonzero; required ids absent from a profile and disabled required entries do not affect startup. The global required list covers shared Agent execution, application endpoints, and Web bootstrap/transport: `agent-loop`, `tool-executor-native`, `tool-executor-ptc`, `webserver`, `web-runtime`, `modules`, `connection`, `headless-runner`, `acp`, and `sdk-jsonrpc-server`.
 
 <a id="profiles"></a>
 ### Profiles
@@ -53,7 +53,9 @@ Before a profile imports a plugin, DSH checks its declared DSH requirement again
 
 Admission happens only at composition boundaries DSH owns, and a denied row is denied in the launcher's own copy of the composition: no profile patch layer, dependency manifest, or bundle list changes. `prepareProfilePatches` composes over the launcher's empty profile root and runs while the root Include is mounted and on every profile recomposition, so a denied plugin never imports its module. `prepareProfileEntries` does the same for a preset's rows. A denied ordinary row becomes a detached `disabled: true` row; a native group stays mounted and its denied children do not load; a native Include that reaches a denied plugin is omitted whole, because its file is never rewritten. A row denied by policy keeps its configured `disabled` value in the profile, and every refusal is reported with the package, versions, and risk. A bundle is not a row, so `loadProfileDirectory` checks each bundle's own DSH requirement when it loads the profile's bundle layers, at startup and on every recomposition; an incompatible bundle without an exemption is skipped like an unreadable one and listed in `skippedBundles`. These boundaries do not cover plugins another embedder mounts through its own `ctx.plugin` call. Two edits made directly to files during a session are judged only at the next recomposition or startup: a running plugin's own `package.json` DSH requirement, and an entry-list file the Loader reads itself, such as the launcher's root config or a nested `cordis:include` file. `--dump-config` reports the configured composition, so a denied plugin row still appears there while a denied bundle contributes no rows, and `--dump-config-schema` imports each composed module to read its schema; run it only against a profile whose plugins you already trust.
 
-Exact-version exemptions live in the profile's own `compatibility.json`, not in its `package.json`, so an exemption write never touches the dependency manifest, the bundle list, or Cordis patch files. It maps exact `package-name@version` keys to lists of exact DSH runtime versions; neither a plugin upgrade nor a DSH upgrade inherits permission. A missing file means no exemptions. A malformed one never stops the profile from starting: records the reader accepts still apply, each rejected record is reported on stderr beside the plugin denials, and the file is then treated as read-only, so a grant or revocation refuses and asks the user to repair it by hand instead of overwriting their content. [Plugin Manager](../plugin-manager/README.md#version-compatibility-and-exemptions) owns the grant, revocation, and risk confirmation each change requires.
+Exact-version exemptions live in the profile's own `compatibility.json`, not in its `package.json`, so an exemption write never touches the dependency manifest, the bundle list, or Cordis patch files. It maps exact `package-name@version` keys to lists of exact DSH runtime versions; neither a plugin upgrade nor a DSH upgrade inherits permission. A missing file means no exemptions. A malformed one never stops the profile from starting: records the reader accepts still apply, each rejected record is reported on stderr beside the plugin denials, and the file is then treated as read-only, so a grant or revocation refuses and asks the user to repair it by hand instead of overwriting their content. [Plugin Manager](../plugin-manager/README.md#version-compatibility-and-exemptions) owns the grant, revocation, and risk confirmation each change requires. `validatePluginVersionExemption(packageVersion, runtimeVersion)` validates canonical exact identities without granting permission; invalid identities throw.
+
+A bundle may declare `dsh.bundle.platforms` as a nonempty list of Node Host platform names, such as `["darwin"]`. The launcher validates this declaration before reading the bundle patch. An unsupported Host skips the entire layer, retains its saved selection, and reports the reason through `skippedBundles`; other layers remain effective. Omission permits every platform. Values must be Node platform names; aliases such as `macos` are invalid. Browser clients do not determine Host support.
 
 Your machine-local preferences also live in the Harness home:
 
@@ -64,7 +66,7 @@ The enabled `dsh-hmr` plugin watches the profile manifest and both user patch fi
 
 Inserted plugin names may be absolute filesystem paths, file URLs, or package specifiers. Patch loading converts absolute paths and patch-relative `./` or `../` paths to file URLs within `insert` rows and their nested groups; existing-entry name assertions and replacement `config` values remain literal.
 
-Before mounting profile rows, the `dsh` launcher computes one immutable runtime resolution from the installation and ordered bundle dependency graphs. Every profile launcher uses runtime resolution, including plain Node, packaged executables, and the Electron Host. It installs the runtime resolution through Node's ESM and CommonJS resolvers without creating fallback links.
+Before mounting profile rows, the `dsh` launcher computes one immutable runtime resolution from the installation and ordered bundle dependency graphs. Every profile launcher uses runtime resolution, including plain Node, packaged executables, and the Electron Host. It installs the runtime resolution through Node's ESM and CommonJS resolvers without creating fallback links. Traversal includes installed optional dependencies and skips those absent from the target installation.
 
 `sanitizeProfile(binName, profileDir, bundles)` provides filesystem recovery without loading plugins or parsing patches. Desktop uses it for native fatal recovery. Call it only after stopping the profile and excluding concurrent profile writes. It renames the profile’s `cordis.patch.yml` to a unique `.bak-<timestamp>` sibling and restores the supplied bundle list, preserving installed packages and other manifest fields. The timestamp is Unix time in milliseconds; collisions append an ordinal (`-1`, `-2`, …) without changing it. It returns the backup path, or `undefined` when no patch exists; missing profiles remain absent. Profile initialization recreates an empty patch on the next launch. The home-level patch is unchanged. Invalid profile JSON fails before mutation; later errors propagate and retain completed changes for retry.
 
@@ -86,7 +88,7 @@ The projector preserves native omission behavior by checking literal defaults ag
 
 Use `readPluginMeta(specifier, parentURL)` or `ctx.pluginPackages.metaOf(specifier, parentURL)` to read installed package display text without importing or activating the plugin. Lookup uses the complete package specifier and the caller's resolution base, respecting Node exports. File paths and file URLs return no metadata without resolving resources. For a package-root specifier, missing locale fields fall back to the accessible `package.json`; a subpath specifier never reads a `package.json`. Malformed metadata returns an `error` diagnostic. Results retain translations for Client-side language selection. The reader also loads an image data URL, even when locale text is complete: a package root uses its manifest `icon`, or `<package>/icon` when that field is omitted; a subpath uses `<specifier>/icon`. An icon error preserves valid text alongside the diagnostic. See [Plugin display metadata](../../../docs/cookbook/adding-a-package.md#plugin-display-metadata) for the author format.
 
-`ON_DEMAND_BUNDLES` names the public Official packages installed only on request. `OFFICIAL_ON_DEMAND_CATALOG` embeds their package-owned localized metadata and icons for offline discovery; `pnpm gen-official-bundle-catalog` explicitly updates generated content, and `verify-official-bundle-catalog` checks resource completeness and freshness; builds consume the committed catalog without importing provider code. The catalog contains no install target: [Plugin Manager](../plugin-manager/README.md#use-this-package) derives it from the running version and installation and uses the ordinary bundle installer. The [product-use check](../../../scripts/verify-product-use.ts) composes shipped and on-demand selections against Web without executing providers.
+The profile templates, installation-owned profile tuples, and retired bundle list that app-boot applies live in [`@deepseek-ai/dsh-official-bundles`](../../util/official-bundles/README.md), together with the installation's default, optional, and on-demand bundle lists.
 
 <a id="startup-and-reload-failures"></a>
 ### Startup and reload failures
@@ -143,7 +145,9 @@ This section explains how the outcomes above are realized and points at the code
 - **One rejection checkpoint.** `inactiveEntries` keeps the exact reasons it folds into the boot diagnostic visible through the next process rejection checkpoint, so `installFailLoud` coalesces Loader's duplicate notification while unrelated unhandled rejections remain fatal.
 - **Two-stage failure labels.** Outside startup audit failures, `boot()` distinguishes `host preparation failed` — `prepare` threw before any config-tree entry mounted — from `plugin tree failed to load`, and appends the deepest plugin error's stack. Plugin diagnostics retain nested causes and aggregate member failures; cyclic causes stop traversal without replacing the original error.
 
-The startup error also retains inactive-entry metadata and raw startup warning/error records without retaining the Loader tree. Its `entries` and `startup` fields are non-enumerable: direct access and full diagnostic reports retain them, while ordinary error inspection omits them. Pending-only failures have no `cause`; failures with recorded errors retain their original values in an `AggregateError`. Import errors are collected through the logger before the Loader mounts because no failed Fiber exists for those imports. The temporary exporter is removed when boot settles.
+The startup error also retains inactive-entry metadata and raw startup warning/error records without retaining the Loader tree. Its `entries`, `startup`, and `composition` fields are non-enumerable: direct access and full diagnostic reports retain them, while ordinary error inspection omits them. Pending-only failures have no `cause`; failures with recorded errors retain their original values in an `AggregateError`. Import errors are collected through the logger before the Loader mounts because no failed Fiber exists for those imports. The temporary exporter is removed when boot settles.
+
+The package exports `StartupCompositionDiagnostic`, `StartupPluginState`, and `StartupServiceState` for typed consumers. Before disposal, `composition` captures up to 256 configured plugin rows and 256 missing-service observations, with omission counts. Rows include module, available package version, state and Loader source URL; configuration values are excluded. Registered providers include their state and whether their scope matches the consumer. An empty provider list means ownership is unknown: disabled or failed plugins may never have registered. The Loader source does not identify which overlay last changed a row. Metadata lookup failures leave the version unknown; snapshot failure preserves the original startup error.
 
 ### Helper behavior
 

package/README.zh.md

@@ -40,7 +40,7 @@ installFailLoud('dsh')
 const ctx = await boot('dsh', resolveConfigPath(argv[2], process.env.DSH_SNAPSHOT))
 ```
 
-`installFailLoud` 会为未处理 rejection 或未捕获异常向 stderr 写一条带标签的 `util.inspect` 诊断，在固定超时内等待界面的 release 钩子，然后以 1 退出；控制流不会回到失败的操作，因为只有抛出点知道哪些状态仍然完整，事件循环只运行到 release 结束或超时。有了这个入口，启动会保留所有能够激活的插件。启用但失败的插件会产生带标签的警告。required entry 失败时，启动会拆卸整个应用并以非零码退出；profile 中不存在的 required id 和已禁用的 required entry 不影响启动。全局 required list 覆盖共享 Agent 执行、应用 endpoint，以及 Web 启动与传输：`agent-loop`、`webserver`、`web-runtime`、`modules`、`connection`、`headless-runner`、`acp` 和 `sdk-jsonrpc-server`。
+`installFailLoud` 会为未处理 rejection 或未捕获异常向 stderr 写一条带标签的 `util.inspect` 诊断，在固定超时内等待界面的 release 钩子，然后以 1 退出；控制流不会回到失败的操作，因为只有抛出点知道哪些状态仍然完整，事件循环只运行到 release 结束或超时。有了这个入口，启动会保留所有能够激活的插件。启用但失败的插件会产生带标签的警告。required entry 失败时，启动会拆卸整个应用并以非零码退出；profile 中不存在的 required id 和已禁用的 required entry 不影响启动。全局 required list 覆盖共享 Agent 执行、应用 endpoint，以及 Web 启动与传输：`agent-loop`、`tool-executor-native`、`tool-executor-ptc`、`webserver`、`web-runtime`、`modules`、`connection`、`headless-runner`、`acp` 和 `sdk-jsonrpc-server`。
 
 <a id="profiles"></a>
 ### Profile
@@ -53,7 +53,9 @@ profile 导入插件前，DSH 会将其声明的 DSH 版本要求与 `getDshRunt
 
 检查只发生在 DSH 自己持有的组合入口，改写的是启动器自己的那份组合：profile 的 patch 层、依赖清单与组合包列表都不会改变。`prepareProfilePatches` 在启动器的空 profile 根之上组合，并在挂载根 Include 时以及每次 profile 重新组合时执行，因此被拒绝的插件永远不会导入其模块；`prepareProfileEntries` 对 preset 行做同样的事。被拒绝的普通行会变成游离的 `disabled: true` 行；原生 group 保持挂载，其被拒绝的子行不会加载；若某个原生 Include 会到达被拒绝的插件，则整体省略该 Include，因为它的文件不会被改写。被策略拒绝的行在 profile 中保留其配置的 `disabled` 值，每次拒绝都会报告包名、版本与风险。组合包本身不是行，因此 `loadProfileDirectory` 在启动和每次重新组合加载 profile 的组合包层时，检查每个组合包自己声明的 DSH 版本要求；没有豁免的不兼容组合包会像无法读取的组合包一样被跳过，并列入 `skippedBundles`。这些入口不覆盖其他嵌入方通过自己的 `ctx.plugin` 调用挂载的插件。会话中直接改文件的两类编辑只在下一次重新组合或启动时才被判定：正在运行的插件自己的 `package.json` DSH 版本要求，以及 Loader 自己读取的入口清单文件（如启动器的根配置或嵌套的 `cordis:include` 文件）。`--dump-config` 报告的是配置出的组合，因此被拒绝的插件行仍会出现在其中，而被拒绝的组合包不提供任何行；`--dump-config-schema` 会导入每个组合模块以读取其 schema，请只对已经信任其插件的 profile 运行。
 
-精确版本豁免保存在 profile 自己的 `compatibility.json` 中，而不是 `package.json`，因此写豁免不会触及依赖清单、组合包列表或 Cordis patch 文件。它把精确的 `package-name@version` 键映射到精确 DSH 运行时版本列表；插件升级和 DSH 升级都不继承授权。文件缺失表示没有豁免。文件损坏绝不会阻止 profile 启动：读取器接受的记录仍然生效，每条被拒绝的记录会与插件拒绝信息一起输出到 stderr，此后该文件被视为只读，因此授予或撤销会拒绝执行并要求用户手工修复，而不是覆盖用户的内容。[插件管理器](../plugin-manager/README.zh.md#version-compatibility-and-exemptions)负责每次变更所需的授权、撤销与风险确认。
+精确版本豁免保存在 profile 自己的 `compatibility.json` 中，而不是 `package.json`，因此写豁免不会触及依赖清单、组合包列表或 Cordis patch 文件。它把精确的 `package-name@version` 键映射到精确 DSH 运行时版本列表；插件升级和 DSH 升级都不继承授权。文件缺失表示没有豁免。文件损坏绝不会阻止 profile 启动：读取器接受的记录仍然生效，每条被拒绝的记录会与插件拒绝信息一起输出到 stderr，此后该文件被视为只读，因此授予或撤销会拒绝执行并要求用户手工修复，而不是覆盖用户的内容。[插件管理器](../plugin-manager/README.zh.md#version-compatibility-and-exemptions)负责每次变更所需的授权、撤销与风险确认。`validatePluginVersionExemption(packageVersion, runtimeVersion)` 校验规范的精确身份而不授予权限；身份非法时抛出错误。
+
+组合包可以用 `dsh.bundle.platforms` 声明非空的 Node Host 平台名称列表，例如 `["darwin"]`。启动器在读取组合包 patch 前验证此声明。Host 不受支持时会跳过整个配置层，保留已保存的选择，并通过 `skippedBundles` 报告原因；其他配置层继续生效。省略此字段时允许所有平台。值必须是 Node 平台名，`macos` 等别名无效。浏览器所在机器的平台不决定 Host 是否受支持。
 
 你的机器本地偏好同样位于 harness home 中：
 
@@ -64,7 +66,7 @@ profile 导入插件前，DSH 会将其声明的 DSH 版本要求与 `getDshRunt
 
 插入条目的插件名可以是绝对文件系统路径、文件 URL 或包标识符。patch 加载会把 `insert` 条目及其嵌套分组中的绝对路径以及相对于 patch 文件的 `./` 或 `../` 路径转换为文件 URL；对已有条目名称的断言及替换用的 `config` 值保持原样。
 
-挂载 profile 条目前，`dsh` launcher 会从安装依赖图与有序 bundle 依赖图计算一份不可变的 runtime resolution。普通 Node、打包可执行文件与 Electron Host 等所有 profile 启动器都使用 runtime 解析，将 runtime resolution 安装到 Node 的 ESM 与 CommonJS 解析器中，不创建 fallback 链接。
+挂载 profile 条目前，`dsh` launcher 会从安装依赖图与有序 bundle 依赖图计算一份不可变的 runtime resolution。普通 Node、打包可执行文件与 Electron Host 等所有 profile 启动器都使用 runtime 解析，将 runtime resolution 安装到 Node 的 ESM 与 CommonJS 解析器中，不创建 fallback 链接。依赖遍历包含已安装的可选依赖，跳过目标安装中缺席的包。
 
 `sanitizeProfile(binName, profileDir, bundles)` 提供文件恢复，无需加载插件或解析 patch。Desktop 在原生致命错误恢复中调用它。调用前必须停止 profile 并排除并发 profile 写入。它将 profile 的 `cordis.patch.yml` 重命名为带唯一 `.bak-<timestamp>` 后缀的同目录备份，并恢复调用方指定的 bundle 列表，保留已安装包和其他 manifest 字段。时间戳为 Unix 毫秒数；同名备份已存在时追加序号（`-1`、`-2`、……），时间戳保持不变。返回值为备份路径；patch 不存在时返回 `undefined`，缺失的 profile 不会被创建。下次启动的 profile 初始化会重新创建空 patch。home 级 patch 不变。无效 profile JSON 在修改前报错；后续错误向调用方抛出，保留已完成的修改供重试。
 
@@ -86,7 +88,7 @@ profile 导入插件前，DSH 会将其声明的 DSH 版本要求与 `getDshRunt
 
 使用 `readPluginMeta(specifier, parentURL)` 或 `ctx.pluginPackages.metaOf(specifier, parentURL)` 读取已安装包的展示文本，无需导入或激活插件。查询使用完整包标识与调用方的解析基准，并遵循 Node exports。文件路径与文件 URL 不解析资源，直接返回无元信息。包根标识缺失的 locale 字段回退到可访问的 `package.json`；子路径标识从不读取 `package.json`。格式错误的元信息返回 `error` 诊断。结果保留翻译，由 Client 选择语言。即使 locale 文本完整，读取器也会加载图片 data URL：包根使用清单 `icon`，省略该字段时使用 `<包名>/icon`；子路径使用 `<标识>/icon`。图标出错时，保留有效文本并附上诊断。作者格式见[插件展示元信息](../../../docs/cookbook/adding-a-package.zh.md#plugin-display-metadata)。
 
-`ON_DEMAND_BUNDLES` 列出仅按需安装的官方公开包。`OFFICIAL_ON_DEMAND_CATALOG` 内嵌这些包拥有的本地化元信息和图标，支持离线发现；`pnpm gen-official-bundle-catalog` 显式更新生成内容，`verify-official-bundle-catalog` 检查资源完整性与新鲜度；构建只读取已提交的目录，不导入提供者代码。目录不保存安装目标；[插件管理器](../plugin-manager/README.zh.md#use-this-package)根据当前版本和安装位置确定目标，并使用普通组合包安装器。[产品用途检查](../../../scripts/verify-product-use.ts)将随附和按需选择与 Web 组合，但不执行提供者。
+app-boot 应用的 profile 模板、安装方拥有的 profile 组合包元组和已退役组合包列表位于 [`@deepseek-ai/dsh-official-bundles`](../../util/official-bundles/README.zh.md)，安装方的默认、可选和按需组合包列表也在该包中。
 
 <a id="startup-and-reload-failures"></a>
 ### 启动与重载失败
@@ -143,7 +145,9 @@ Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如
 - **单一 rejection 检查点。** `inactiveEntries` 把折入启动诊断的确切原因保持到下一个进程级 rejection 检查点可见，使 `installFailLoud` 能合并 Loader 的重复通知，而所有无关的未处理 rejection 仍然致命。
 - **两阶段失败标签。** 除启动审计失败外，`boot()` 区分 `host preparation failed`（`prepare` 在任何配置树条目挂载前抛出）与 `plugin tree failed to load`，并追加最深层插件错误的堆栈。插件诊断保留嵌套原因和聚合错误中的各项失败；原因链出现循环时会停止遍历，但不会替换原始错误。
 
-启动错误还保留未激活条目的元数据和原始启动警告、错误记录，不保留 Loader tree。其 `entries` 和 `startup` 字段不可枚举：直接访问和完整诊断报告保留这些字段，常规错误检查输出则省略它们。只有等待条目时没有 `cause`；存在已记录错误时，`AggregateError` 保留其原始值。收集器在 Loader 挂载前通过 logger 收集导入错误，因为这些导入尚无 failed Fiber。启动结算后会移除临时 exporter。
+启动错误还保留未激活条目的元数据和原始启动警告、错误记录，不保留 Loader tree。其 `entries`、`startup` 和 `composition` 字段不可枚举：直接访问和完整诊断报告保留这些字段，常规错误检查输出则省略它们。只有等待条目时没有 `cause`；存在已记录错误时，`AggregateError` 保留其原始值。收集器在 Loader 挂载前通过 logger 收集导入错误，因为这些导入尚无 failed Fiber。启动结算后会移除临时 exporter。
+
+包导出 `StartupCompositionDiagnostic`、`StartupPluginState` 和 `StartupServiceState`，供消费者按名引用。释放前，`composition` 捕获最多 256 个配置插件条目和 256 个缺失服务观测，并记录省略数量。条目包含模块、可取得的包版本、状态和 Loader 来源 URL，不含配置值。已注册提供者包含其状态及作用域是否与消费者一致。提供者列表为空表示归属未知：被禁用或失败的插件可能从未注册服务。Loader 来源不代表最后修改该条目的 overlay。元数据查询失败时版本标为未知；快照失败保留原始启动错误。
 
 ### Helper 行为
 

package/lib/index.js

@@ -2,20 +2,104 @@ import { createRequire, isBuiltin } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import fs, { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { inspect, parseEnv } from "node:util";
+import { Context, Service } from "@deepseek-ai/cordis";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep, win32 } from "node:path";
 import * as yaml from "js-yaml";
 import { load } from "js-yaml";
-import { Context, Service } from "@deepseek-ai/cordis";
 import Loader, { EntryGroup, EntryTree, ModuleLoader, isJsExpr } from "@deepseek-ai/cordis-plugin-loader";
 import { access, constants, mkdir, readFile, realpath, rename, writeFile } from "node:fs/promises";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import Group from "@deepseek-ai/cordis-plugin-group";
 import { dshHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { createLaunchEnvironmentSnapshot } from "@deepseek-ai/dsh-launch-environment";
+import { INSTALLATION_OWNED_PROFILE_TUPLES, PROFILE_TEMPLATES, RETIRED_BUNDLES } from "@deepseek-ai/dsh-official-bundles";
 import semver, { parse } from "semver";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { getEnvironmentData, setEnvironmentData } from "node:worker_threads";
 import { imports } from "resolve.exports";
+//#region lib/types/startup-diagnostics.js
+/** Configuration-free snapshots captured before a failed startup disposes its plugins. */
+function stateName(state) {
+	return {
+		0: "pending",
+		1: "loading",
+		2: "active",
+		3: "failed",
+		4: "disposed",
+		5: "unloading"
+	}[state];
+}
+function pluginState(ctx, entry) {
+	let state;
+	try {
+		state = entry.disabled ? "disabled" : entry.fiber === void 0 ? "failed" : stateName(entry.fiber.state);
+	} catch (_error) {
+		state = "failed";
+	}
+	let version = "unknown";
+	const source = entry.parent.tree.ctx.baseUrl;
+	try {
+		if (source !== void 0) version = ctx.get("pluginPackages")?.packageOf(entry.options.name, source)?.version ?? "unknown";
+	} catch (_error) {}
+	const fiber = entry.fiber;
+	return {
+		id: entry.id,
+		module: entry.options.name,
+		version,
+		state,
+		source: source ?? "unknown",
+		missing: state === "pending" && fiber !== void 0 ? Object.keys(fiber.inject).filter((name) => fiber.ctx.get(name) === void 0) : []
+	};
+}
+/**
+* Capture Loader state and registered service ownership before teardown.
+* Providers that never registered cannot be inferred from their package names.
+* @param ctx - Live application context with its Loader still mounted.
+* @returns At most 256 plugin rows and 256 missing-service observations, with omission counts.
+*/
+function captureStartupComposition(ctx) {
+	const rows = [...ctx.loader.entries()].map((entry) => ({
+		entry,
+		state: pluginState(ctx, entry)
+	}));
+	rows.sort((a, b) => Number(a.state.state === "active") - Number(b.state.state === "active"));
+	const services = [];
+	let omittedServices = 0;
+	const store = ctx.reflect.store;
+	for (const { entry, state } of rows) {
+		const fiber = entry.fiber;
+		if (fiber === void 0) continue;
+		for (const service of state.missing) {
+			if (services.length === 256) {
+				omittedServices++;
+				continue;
+			}
+			const scope = fiber.ctx[Context.isolate][service];
+			const providers = [];
+			for (const key of Object.getOwnPropertySymbols(store)) {
+				const impl = store[key];
+				if (impl?.name !== service) continue;
+				providers.push({
+					entry: impl.fiber.entry?.id ?? "unknown",
+					state: stateName(impl.fiber.state),
+					visibility: key === scope ? "same-scope" : "other-scope"
+				});
+			}
+			services.push({
+				consumer: state.id,
+				service,
+				providers
+			});
+		}
+	}
+	return {
+		plugins: rows.slice(0, 256).map((row) => row.state),
+		services,
+		omittedPlugins: Math.max(0, rows.length - 256),
+		omittedServices
+	};
+}
+//#endregion
 //#region ../../../vendor/include/src/index.ts
 const JsExpr = new yaml.Type("tag:yaml.org,2002:js", {
 	kind: "scalar",
@@ -248,6 +332,44 @@ var Include = class extends EntryTree {
 	}
 };
 //#endregion
+//#region lib/types/bundle-platform.js
+/** Host operating-system admission for optional bundle layers. */
+const NODE_PLATFORMS = Object.freeze([
+	"aix",
+	"android",
+	"darwin",
+	"freebsd",
+	"haiku",
+	"linux",
+	"openbsd",
+	"sunos",
+	"win32",
+	"cygwin",
+	"netbsd"
+]);
+/** A valid bundle declaration excludes the operating system running DSH. */
+var UnsupportedBundlePlatformError = class extends Error {
+	/**
+	* @param platforms Node platform names supported by the bundle.
+	* @param platform Operating system of the DSH Host.
+	*/
+	constructor(platforms, platform) {
+		super(`Bundle supports Host platforms ${platforms.join(", ")}; the DSH Host is running ${platform}`);
+		this.name = "UnsupportedBundlePlatformError";
+	}
+};
+/**
+* Validate package metadata and reject an unsupported Host before selecting or composing a bundle.
+* @param platforms The optional `dsh.bundle.platforms` field read from package.json.
+* @param platform Operating system of the DSH Host, from Node's `process.platform`.
+* @throws When the declaration is malformed or excludes the Host; omission allows every platform.
+*/
+function assertBundlePlatform(platforms, platform) {
+	if (platforms === void 0) return;
+	if (!Array.isArray(platforms) || platforms.length === 0 || !platforms.every((value) => typeof value === "string" && NODE_PLATFORMS.includes(value))) throw new Error("dsh.bundle.platforms must be a nonempty list of Node platform names");
+	if (!platforms.includes(platform)) throw new UnsupportedBundlePlatformError(platforms, platform);
+}
+//#endregion
 //#region lib/types/plugin-compatibility.js
 /** Evaluate plugin dsh requirements (`engines.dsh`, else dsh peers) without importing plugin code. */
 function objectOf$1(value, field) {
@@ -547,49 +669,6 @@ function resolveProfileDir(name, home = resolveDshHome()) {
 	if (name === "" || name.includes("/") || name.includes("\\") || name === "." || name === ".." || name === "node_modules") throw new Error(`dsh: invalid profile name ${JSON.stringify(name)}`);
 	return join(home, PROFILES_DIR, name);
 }
-/** The shipped profile templates auto-initialized on first use, by name. */
-const PROFILE_TEMPLATES = {
-	acp: { bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-acp-app"] },
-	web: { bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app"] },
-	headless: { bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-headless"] },
-	sdk: { bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-sdk-app"] },
-	"sdk-minimal": { bundles: ["@deepseek-ai/dsh-sdk-minimal"] }
-};
-/** Installation-owned bundle tuples normalized to the shipped template. */
-const INSTALLATION_OWNED_PROFILE_TUPLES = { headless: [
-	"@deepseek-ai/dsh-base",
-	"@deepseek-ai/dsh-web-app",
-	"@deepseek-ai/dsh-headless"
-] };
-/**
-* Bundles an earlier release shipped and the installation no longer carries;
-* {@link loadProfileDirectory} removes them from the profile's bundle list.
-*/
-const RETIRED_BUNDLES = new Set(["@deepseek-ai/dsh-experimental-schedule-bundle"]);
-/** The bundle list a `dsh plugin` init uses for a name with no shipped template. */
-const DEFAULT_PROFILE_BUNDLES = ["@deepseek-ai/dsh-base"];
-/**
-* The bundles the dsh installation ships for a person to switch on: each a
-* runtime dependency of the installation that declares `dsh.bundle.patch`,
-* an `icon`, and `./locale/*.json` display metadata, selected by no shipped
-* template, and offered switched off by the plugin manager
-* ([rationale](../../../../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md),
-* [admission](../../../../.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.md)).
-*/
-const OPTIONAL_BUNDLES = [
-	"@deepseek-ai/dsh-experimental-session-search",
-	"@deepseek-ai/dsh-experimental-ralph-bundle",
-	"@deepseek-ai/dsh-experimental-terminal-bundle",
-	"@deepseek-ai/dsh-experimental-badge-skill-bundle",
-	"@deepseek-ai/dsh-experimental-session-titles-bundle",
-	"@deepseek-ai/dsh-experimental-agent-team-profile",
-	"@deepseek-ai/dsh-experimental-voice-input-bundle",
-	"@deepseek-ai/dsh-experimental-cot-translation-bundle",
-	"@deepseek-ai/dsh-experimental-auto-review",
-	"@deepseek-ai/dsh-experimental-inspector-profile",
-	"@deepseek-ai/dsh-experimental-plugin-market-bundle",
-	"@deepseek-ai/dsh-experimental-tool-worktree"
-];
 const PROFILE_PATCH_TEMPLATE = `# Your patch layer for this dsh profile, applied after every bundle layer:
 # a top-level YAML array of loader patch entries (id-targeted config
 # overrides, disables, and insert lists; \`!!js\` expressions allowed).
@@ -710,7 +789,11 @@ function readPackageManifest(anchor) {
 }
 /** Return dependency names that may be imported by a loader-visible plugin. */
 function profileDependencyNames(manifest) {
-	return [...Object.keys(manifest.dependencies ?? {}), ...Object.keys(manifest.peerDependencies ?? {})];
+	return [
+		...Object.keys(manifest.dependencies ?? {}),
+		...Object.keys(manifest.peerDependencies ?? {}),
+		...Object.keys(manifest.optionalDependencies ?? {})
+	];
 }
 /** Resolve the installation packages that the runtime resolver supplies to every profile. */
 function collectInstallationScopePackages(installAnchor, skippedBundles) {
@@ -1004,7 +1087,8 @@ function resolveBundleDir(binName, packageName, installAnchor, profileDir) {
 * the shared Harness home. This is used by application-owned profiles whose
 * package project and lifecycle belong to that application.
 * Retired bundles are removed from the stored bundle list first, rewriting the
-* manifest when it listed one. Unreadable bundles, and bundles whose own dsh requirements the profile does not exempt, are skipped
+* manifest when it listed one. Unreadable bundles, unsupported Host platforms, and bundles whose own dsh requirements
+* the profile does not exempt are skipped
 * without changing the manifest and listed in `skippedBundles`; nothing is printed.
 * @param binName - the diagnostic prefix on thrown errors.
 * @param dir - absolute profile package directory.
@@ -1022,6 +1106,7 @@ function loadProfileDirectory(binName, dir, installAnchor, options = {}) {
 		const bundleManifest = readProfileManifest(binName, packageDir);
 		const bundle = bundleManifest.dsh?.bundle;
 		if (bundle === void 0) throw new Error(`${binName}: profile bundle ${JSON.stringify(packageName)} declares no dsh.bundle in its package.json`);
+		assertBundlePlatform(bundle.platforms, process.platform);
 		const issue = evaluatePluginCompatibility(bundleManifest, exemptions);
 		if (issue !== void 0 && !issue.exempted) throw new Error(pluginCompatibilityWarning(issue));
 		const patchPaths = bundlePatchPaths(packageDir, bundle);
@@ -1051,8 +1136,8 @@ function loadProfileDirectory(binName, dir, installAnchor, options = {}) {
 }
 /**
 * Load a profile: resolve every `dsh.profile.bundles` entry to its patch
-* layer and parse the profile's own patch file. Unreadable or incompatible bundles
-* are skipped and listed in `skippedBundles`; profile manifest and user patch errors still throw.
+* layer and parse the profile's own patch file. Unreadable bundles, unsupported Host platforms,
+* and incompatible bundles are skipped and listed in `skippedBundles`; profile manifest and user patch errors still throw.
 * @param binName - the diagnostic prefix on thrown errors.
 * @param name - the profile name.
 * @param installAnchor - absolute path of the dsh app's package.json (first resolution anchor).
@@ -1205,6 +1290,8 @@ function writeProfileBundles(profileDir, manifest, bundles) {
 * template entries retain their order and duplicates. New bundle dependencies activate automatically.
 * @param options - location, inventory captured before pnpm, and whether explicitly disabled bundles remain disabled.
 * @returns updated inventory and newly added ordinary dependencies for caller-owned warnings.
+* @throws If a new selection has invalid platform metadata or excludes the Host. Installed dependencies
+* remain; no bundle selection changes are written.
 */
 function reconcileProfilePlugins(options) {
 	const after = readProfilePlugins(options);
@@ -1214,7 +1301,10 @@ function reconcileProfilePlugins(options) {
 	const disabled = new Set(options.preserveDisabled ? options.before.dependencies.filter((dependency) => dependency.bundle && !dependency.enabled).map((dependency) => dependency.name) : []);
 	const previous = after.manifest.dsh?.profile?.bundles ?? [];
 	const bundles = previous.filter((name) => !(beforeNames.has(name) || afterNames.has(name)) || bundleNames.has(name));
-	for (const dependency of after.dependencies) if (dependency.bundle && !disabled.has(dependency.name) && !bundles.includes(dependency.name)) bundles.push(dependency.name);
+	for (const dependency of after.dependencies) if (dependency.bundle && !disabled.has(dependency.name) && !bundles.includes(dependency.name)) {
+		assertBundlePlatform(bundleManifest(options, dependency.name)?.dsh?.bundle?.platforms, process.platform);
+		bundles.push(dependency.name);
+	}
 	return {
 		plugins: {
 			manifest: bundles.length !== previous.length || bundles.some((name, index) => name !== previous[index]) ? writeProfileBundles(options.profileDir, after.manifest, bundles) : after.manifest,
@@ -1785,7 +1875,7 @@ function internalModules() {
 	const esmResolve = addon.requireBuiltin("internal/modules/esm/resolve");
 	const esm = esmModule.getOrInitializeCascadedLoader();
 	const modern = "getOrCreateModuleJob" in esm;
-	/* v8 ignore start -- the supported Node 22/24/26 matrix validates each available Internal interface */
+	/* v8 ignore start -- the supported Node 24/26 matrix validates each available Internal interface */
 	if (typeof esm.resolveSync !== "function" || typeof Reflect.get(esm, modern ? "getOrCreateModuleJob" : "getModuleJobForImport") !== "function" || !modern && typeof Reflect.get(esm, "resolve") !== "function" || typeof cjsModule.Module._resolveFilename !== "function" || typeof cjsHelpers.getCjsConditions !== "function" || typeof esmUtils.getDefaultConditions !== "function" || typeof esmResolve.defaultResolve !== "function") throw new Error("profile resolution: unsupported Node module loader");
 	/* v8 ignore stop */
 	return {
@@ -1861,7 +1951,7 @@ function installRuntimeInterception(resolution) {
 				let expected;
 				try {
 					expected = adapted(target.specifier, target.parentURL, attributes);
-					/* v8 ignore next -- Node 24+ resolves synchronously; the Node 22 matrix covers its Promise result */
+					/* v8 ignore next -- the current loader resolves synchronously; the private interface also permits Promise results */
 					if (expected instanceof Promise) expected = expected.catch(restoreImporter);
 				} catch (error) {
 					return restoreImporter(error);
@@ -1890,7 +1980,7 @@ function installRuntimeInterception(resolution) {
 				} catch (error) {
 					return restoreImporter(error);
 				}
-				/* v8 ignore next -- Node 24+ resolves synchronously; the Node 22 matrix covers its Promise result */
+				/* v8 ignore next -- the current loader resolves synchronously; the private interface also permits Promise results */
 				if (result instanceof Promise) return result.catch(restoreImporter);
 				if (cacheable) state.esm = result;
 				return result;
@@ -1912,12 +2002,12 @@ function installRuntimeInterception(resolution) {
 		};
 		return (request, parent, attributes) => {
 			const result = adapted(request, parent, attributes);
-			/* v8 ignore next -- Node 24+ resolves synchronously; the Node 22 matrix covers its Promise result */
+			/* v8 ignore next -- the current loader resolves synchronously; the private interface also permits Promise results */
 			return result instanceof Promise ? result.then((resolved) => relocate(resolved, parent)) : relocate(result, parent);
 		};
 	};
 	let restoreEsm;
-	/* v8 ignore else -- CI coverage runs Node 24 v2; the Node 22 matrix exercises the v1 adapter */
+	/* v8 ignore else -- CI coverage runs Node 24 v2; the Node 24.0 matrix exercises the v1 adapter */
 	if (modern) {
 		const loader = esm;
 		const original = Reflect.get(loader, "resolveSync");
@@ -2401,42 +2491,6 @@ function prepareProfilePatches(ctx, patches, parentURL, binName = "dsh") {
 	return rows.length === 0 ? [] : [{ insert: rows }];
 }
 //#endregion
-//#region lib/types/official-bundle-packages.js
-/** Package admission shared by offline catalog generation and release ordering. */
-/** Public DSH release members available through the ordinary on-demand bundle installer. */
-const ON_DEMAND_BUNDLES = ["@deepseek-ai/dsh-subagent-claude-code", "@deepseek-ai/dsh-subagent-codex"];
-//#endregion
-//#region lib/types/official-bundles.generated.js
-/** Generated offline Official bundle metadata. Run pnpm gen-official-bundle-catalog; do not edit. */
-/** Official on-demand entries, independent of installed packages and registry availability. */
-const OFFICIAL_ON_DEMAND_CATALOG = [{
-	packageName: "@deepseek-ai/dsh-subagent-claude-code",
-	meta: {
-		title: {
-			"en": "Claude Code subagent",
-			"zh": "Claude Code 子智能体"
-		},
-		description: {
-			"en": "Delegate one task to Claude Code using its native authentication and settings.",
-			"zh": "使用 Claude Code 原生认证和设置委派单个任务。"
-		},
-		icon: "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzYiIGhlaWdodD0iMzYiIHZpZXdCb3g9IjAgMCAzNiAzNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB4PSIxNC45ODkzIiB5PSIxNS4xODc3IiB3aWR0aD0iMTIuMjM2NSIgaGVpZ2h0PSIxMi4yMzY1IiByeD0iMiIgZmlsbD0idXJsKCNkc2hfcGx1Z2luX2FydF9SMGEpIiBmaWxsLW9wYWNpdHk9IjAuOCI+PC9yZWN0PjxyZWN0IHg9IjguODcxMDkiIHk9IjkuMDY5NyIgd2lkdGg9IjEyLjIzNjUiIGhlaWdodD0iMTIuMjM2NSIgcng9IjIiIGZpbGw9InVybCgjZHNoX3BsdWdpbl9hcnRfUjBiKSIgZmlsbC1vcGFjaXR5PSIwLjgiPjwvcmVjdD48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImRzaF9wbHVnaW5fYXJ0X1IwYSIgeDE9IjIxLjEwNzUiIHkxPSIxNS4xODc3IiB4Mj0iMjEuMTA3NSIgeTI9IjI3LjQyNDMiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBzdG9wLWNvbG9yPSIjNDVFN0E0Ij48L3N0b3A+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjMDU5MDlEIj48L3N0b3A+PC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9ImRzaF9wbHVnaW5fYXJ0X1IwYiIgeDE9IjE0Ljk4OTQiIHkxPSI5LjA2OTciIHgyPSIxNC45ODk0IiB5Mj0iMjEuMzA2MyIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiM2OUI5RkYiPjwvc3RvcD48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiMzMjRERTIiPjwvc3RvcD48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48L3N2Zz4K"
-	}
-}, {
-	packageName: "@deepseek-ai/dsh-subagent-codex",
-	meta: {
-		title: {
-			"en": "Codex subagent",
-			"zh": "Codex 子智能体"
-		},
-		description: {
-			"en": "Delegate one task to Codex using its native authentication and settings.",
-			"zh": "使用 Codex 原生认证和设置委派单个任务。"
-		},
-		icon: "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzYiIGhlaWdodD0iMzYiIHZpZXdCb3g9IjAgMCAzNiAzNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB4PSIxNC45ODkzIiB5PSIxNS4xODc3IiB3aWR0aD0iMTIuMjM2NSIgaGVpZ2h0PSIxMi4yMzY1IiByeD0iMiIgZmlsbD0idXJsKCNkc2hfcGx1Z2luX2FydF9SMGEpIiBmaWxsLW9wYWNpdHk9IjAuOCI+PC9yZWN0PjxyZWN0IHg9IjguODcxMDkiIHk9IjkuMDY5NyIgd2lkdGg9IjEyLjIzNjUiIGhlaWdodD0iMTIuMjM2NSIgcng9IjIiIGZpbGw9InVybCgjZHNoX3BsdWdpbl9hcnRfUjBiKSIgZmlsbC1vcGFjaXR5PSIwLjgiPjwvcmVjdD48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImRzaF9wbHVnaW5fYXJ0X1IwYSIgeDE9IjIxLjEwNzUiIHkxPSIxNS4xODc3IiB4Mj0iMjEuMTA3NSIgeTI9IjI3LjQyNDMiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBzdG9wLWNvbG9yPSIjNDVFN0E0Ij48L3N0b3A+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjMDU5MDlEIj48L3N0b3A+PC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9ImRzaF9wbHVnaW5fYXJ0X1IwYiIgeDE9IjE0Ljk4OTQiIHkxPSI5LjA2OTciIHgyPSIxNC45ODk0IiB5Mj0iMjEuMzA2MyIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiM2OUI5RkYiPjwvc3RvcD48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiMzMjRERTIiPjwvc3RvcD48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48L3N2Zz4K"
-	}
-}];
-//#endregion
 //#region lib/types/config-schema/native.js
 /** Identity checks at the plugin-export and lazy-builder boundaries. */
 /**
@@ -4269,6 +4323,8 @@ const FIBER_DISPOSED = 4;
 */
 const requiredStartupEntryIds = new Set([
 	"agent-loop",
+	"tool-executor-native",
+	"tool-executor-ptc",
 	"webserver",
 	"web-runtime",
 	"modules",
@@ -4298,6 +4354,8 @@ function formatActivationError(error, stacks = true) {
 /** Startup audit failure with non-enumerable metadata and original failures as its cause. */
 var StartupError = class extends Error {
 	entries;
+	/** Plugin states captured before disposal, excluding configuration values. */
+	composition;
 	/** Root configuration and startup logs, attached by boot after disposal. */
 	startup;
 	/**
@@ -4310,7 +4368,8 @@ var StartupError = class extends Error {
 		this.entries = entries;
 		Object.defineProperties(this, {
 			entries: { enumerable: false },
-			startup: { enumerable: false }
+			startup: { enumerable: false },
+			composition: { enumerable: false }
 		});
 	}
 };
@@ -4541,6 +4600,11 @@ async function boot(binName, absoluteConfigPath, patches, prepare, bareModuleBas
 		await auditStartupEntries(ctx, binName);
 		return ctx;
 	} catch (cause) {
+		if (cause instanceof StartupError) try {
+			cause.composition = captureStartupComposition(ctx);
+		} catch (error) {
+			ctx.logger.warn("Startup composition diagnostic unavailable", error);
+		}
 		await ctx.fiber.dispose();
 		if (cause instanceof StartupError) {
 			cause.startup = {
@@ -4563,4 +4627,4 @@ async function boot(binName, absoluteConfigPath, patches, prepare, bareModuleBas
 	}
 }
 //#endregion
-export { DEFAULT_PROFILE_BUNDLES, FAIL_LOUD_RELEASE_TIMEOUT_MS, LOADER_EXPRESSION_SCHEMA, OFFICIAL_ON_DEMAND_CATALOG, ON_DEMAND_BUNDLES, OPTIONAL_BUNDLES, PROFILES_DIR, PROFILE_COMPATIBILITY_FILENAME, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, ProfileRuntimeResolution, ResolutionRestartRequired, StartupError, auditStartupEntries, boot, bundlePatchFiles, bundlePatchPaths, composeEntries, createConfigProjector, createRuntimeResolution, evaluatePluginCompatibility, generateConfigSchema, getDshRuntimeVersion, initProfile, installFailLoud, isNativeConfigSchema, loadEnv, loadLayeredEnv, loadOptionalPatches, loadOverlayPatches, loadProfile, loadProfileDirectory, mountRootInclude, pluginCompatibilityWarning, prepareProfileEntries, prepareProfilePatches, readBundlePatches, readPluginMeta, readProfileCompatibility, readProfileManifest, readProfilePatches, readProfilePlugins, readProfileVersionExemptions, recomposeProfile, reconcileProfilePatches, reconcileProfilePlugins, removeLinkProjections, renderConfigDump, reportSkippedBundles, resolveBundleDir, resolveConfigPath, resolvePluginResource, resolveProfileDir, resolveTelemetryPatch, sanitizeProfile, setProfileVersionExemption, writeProfileBundles, writeProfileManifest };
+export { FAIL_LOUD_RELEASE_TIMEOUT_MS, LOADER_EXPRESSION_SCHEMA, PROFILES_DIR, PROFILE_COMPATIBILITY_FILENAME, PROFILE_PATCH_FILENAME, PluginPackages, ProfileRuntimeResolution, ResolutionRestartRequired, StartupError, UnsupportedBundlePlatformError, assertBundlePlatform, auditStartupEntries, boot, bundlePatchFiles, bundlePatchPaths, composeEntries, createConfigProjector, createRuntimeResolution, evaluatePluginCompatibility, generateConfigSchema, getDshRuntimeVersion, initProfile, installFailLoud, isNativeConfigSchema, loadEnv, loadLayeredEnv, loadOptionalPatches, loadOverlayPatches, loadProfile, loadProfileDirectory, mountRootInclude, pluginCompatibilityWarning, prepareProfileEntries, prepareProfilePatches, readBundlePatches, readPluginMeta, readProfileCompatibility, readProfileManifest, readProfilePatches, readProfilePlugins, readProfileVersionExemptions, recomposeProfile, reconcileProfilePatches, reconcileProfilePlugins, removeLinkProjections, renderConfigDump, reportSkippedBundles, resolveBundleDir, resolveConfigPath, resolvePluginResource, resolveProfileDir, resolveTelemetryPatch, sanitizeProfile, setProfileVersionExemption, validatePluginVersionExemption, writeProfileBundles, writeProfileManifest };

package/lib/types/bundle-platform.d.ts

@@ -0,0 +1,17 @@
+/** Host operating-system admission for optional bundle layers. */
+/** A valid bundle declaration excludes the operating system running DSH. */
+export declare class UnsupportedBundlePlatformError extends Error {
+    /**
+     * @param platforms Node platform names supported by the bundle.
+     * @param platform Operating system of the DSH Host.
+     */
+    constructor(platforms: readonly string[], platform: string);
+}
+/**
+ * Validate package metadata and reject an unsupported Host before selecting or composing a bundle.
+ * @param platforms The optional `dsh.bundle.platforms` field read from package.json.
+ * @param platform Operating system of the DSH Host, from Node's `process.platform`.
+ * @throws When the declaration is malformed or excludes the Host; omission allows every platform.
+ */
+export declare function assertBundlePlatform(platforms: unknown, platform: string): void;
+//# sourceMappingURL=bundle-platform.d.ts.map

package/lib/types/index.d.ts

@@ -5,6 +5,8 @@
  * config expressions, and drive the Cordis Loader against a leaf `cordis.yml` until the tree settles.
  * @module @deepseek-ai/dsh-app-boot
  */
+import { type StartupCompositionDiagnostic } from './startup-diagnostics.ts';
+export type { StartupCompositionDiagnostic, StartupPluginState, StartupServiceState } from './startup-diagnostics.ts';
 import { Context, type FiberState } from '@deepseek-ai/cordis';
 import { type Entry } from '@deepseek-ai/cordis-plugin-loader';
 import { type PatchOptions } from '@deepseek-ai/cordis-plugin-include';
@@ -13,10 +15,9 @@ import { type LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environm
 export { readBundlePatches, readProfilePatches, resolveTelemetryPatch, type ProfileContext, type ProfilePnpmInvocation } from './profile-context.ts';
 export { sanitizeProfile } from './profile-sanitize.ts';
 export { getDshRuntimeVersion, evaluatePluginCompatibility, pluginCompatibilityWarning, type PluginCompatibility } from './plugin-compatibility.ts';
-export { PROFILE_COMPATIBILITY_FILENAME, readProfileCompatibility, readProfileVersionExemptions, setProfileVersionExemption, type ProfileCompatibility, } from './profile-compatibility.ts';
+export { PROFILE_COMPATIBILITY_FILENAME, readProfileCompatibility, readProfileVersionExemptions, setProfileVersionExemption, validatePluginVersionExemption, type ProfileCompatibility, } from './profile-compatibility.ts';
 export { prepareProfileEntries, prepareProfilePatches } from './compatibility-preflight.ts';
 export { readPluginMeta, resolvePluginResource } from './package-meta.ts';
-export { ON_DEMAND_BUNDLES, OFFICIAL_ON_DEMAND_CATALOG, type OfficialBundleCatalogEntry } from './official-bundles.ts';
 export { generateConfigSchema, type ConfigSchemaDump, type NativeConfigSchema } from './config-schema/index.ts';
 export { createConfigProjector, LOADER_EXPRESSION_SCHEMA, type ConfigProjection } from './config-schema/projector.ts';
 export { isNativeConfigSchema } from './config-schema/native.ts';
@@ -35,7 +36,8 @@ declare module '@deepseek-ai/cordis' {
         'app-boot/config-reload'(): void;
     }
 }
-export { composeEntries, createRuntimeResolution, ProfileRuntimeResolution, DEFAULT_PROFILE_BUNDLES, OPTIONAL_BUNDLES, bundlePatchFiles, bundlePatchPaths, initProfile, removeLinkProjections, loadProfile, loadProfileDirectory, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PROFILES_DIR, readProfileManifest, reportSkippedBundles, resolveBundleDir, resolveProfileDir, writeProfileManifest, type Profile, type ProfileLayer, type SkippedBundle, type ProfileManifest, type LinkedRoot, type RuntimeResolutionOptions, type RuntimeResolutionEntry, type RuntimeResolution, type ProfileTemplate, } from './profile.ts';
+export { assertBundlePlatform, UnsupportedBundlePlatformError } from './bundle-platform.ts';
+export { composeEntries, createRuntimeResolution, ProfileRuntimeResolution, bundlePatchFiles, bundlePatchPaths, initProfile, removeLinkProjections, loadProfile, loadProfileDirectory, PROFILE_PATCH_FILENAME, PROFILES_DIR, readProfileManifest, reportSkippedBundles, resolveBundleDir, resolveProfileDir, writeProfileManifest, type Profile, type ProfileLayer, type SkippedBundle, type ProfileManifest, type LinkedRoot, type RuntimeResolutionOptions, type RuntimeResolutionEntry, type RuntimeResolution, } from './profile.ts';
 export { PluginPackages, type PluginPackage, type PluginPackagesConfig, } from './profile-resolution/service.ts';
 export { ResolutionRestartRequired } from './profile-resolution/resolver.ts';
 /**
@@ -285,6 +287,8 @@ interface StartupLogRecord {
 /** Startup audit failure with non-enumerable metadata and original failures as its cause. */
 export declare class StartupError extends Error {
     readonly entries: readonly StartupEntryDiagnostic[];
+    /** Plugin states captured before disposal, excluding configuration values. */
+    composition?: StartupCompositionDiagnostic;
     /** Root configuration and startup logs, attached by boot after disposal. */
     startup?: {
         configurationPath: string;

package/lib/types/profile-plugins.d.ts

@@ -52,6 +52,8 @@ export declare function writeProfileBundles(profileDir: string, manifest: Profil
  * template entries retain their order and duplicates. New bundle dependencies activate automatically.
  * @param options - location, inventory captured before pnpm, and whether explicitly disabled bundles remain disabled.
  * @returns updated inventory and newly added ordinary dependencies for caller-owned warnings.
+ * @throws If a new selection has invalid platform metadata or excludes the Host. Installed dependencies
+ * remain; no bundle selection changes are written.
  */
 export declare function reconcileProfilePlugins(options: ProfilePluginLocation & {
     readonly before: ProfilePluginInventory;

package/lib/types/profile.d.ts

@@ -27,11 +27,6 @@ import type { DshBundleManifest, DshPackageManifest } from '@deepseek-ai/dsh-pac
 export declare const PROFILES_DIR = "profiles";
 /** The user patch layer inside a profile directory (hot-reloaded on long-lived surfaces). */
 export declare const PROFILE_PATCH_FILENAME = "cordis.patch.yml";
-/** Installation-owned defaults used when a shipped profile is first opened. */
-export interface ProfileTemplate {
-    /** Ordered bundle layer list. */
-    bundles: readonly string[];
-}
 /** Package metadata accepted by the profile reader; local profiles need no published identity. */
 export type ProfileManifest = Partial<DshPackageManifest>;
 /**
@@ -132,19 +127,6 @@ export interface RuntimeResolution {
  * @returns the absolute profile directory (which may not exist yet).
  */
 export declare function resolveProfileDir(name: string, home?: string): string;
-/** The shipped profile templates auto-initialized on first use, by name. */
-export declare const PROFILE_TEMPLATES: Record<string, ProfileTemplate>;
-/** The bundle list a `dsh plugin` init uses for a name with no shipped template. */
-export declare const DEFAULT_PROFILE_BUNDLES: readonly string[];
-/**
- * The bundles the dsh installation ships for a person to switch on: each a
- * runtime dependency of the installation that declares `dsh.bundle.patch`,
- * an `icon`, and `./locale/*.json` display metadata, selected by no shipped
- * template, and offered switched off by the plugin manager
- * ([rationale](../../../../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md),
- * [admission](../../../../.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-optional-bundles.md)).
- */
-export declare const OPTIONAL_BUNDLES: readonly string[];
 /**
  * Initialize a profile directory: manifest, empty user patch layer, and the
  * pnpm settings out-of-tree plugins need. Existing files are never touched,
@@ -237,7 +219,8 @@ export declare function resolveBundleDir(binName: string, packageName: string, i
  * the shared Harness home. This is used by application-owned profiles whose
  * package project and lifecycle belong to that application.
  * Retired bundles are removed from the stored bundle list first, rewriting the
- * manifest when it listed one. Unreadable bundles, and bundles whose own dsh requirements the profile does not exempt, are skipped
+ * manifest when it listed one. Unreadable bundles, unsupported Host platforms, and bundles whose own dsh requirements
+ * the profile does not exempt are skipped
  * without changing the manifest and listed in `skippedBundles`; nothing is printed.
  * @param binName - the diagnostic prefix on thrown errors.
  * @param dir - absolute profile package directory.
@@ -250,8 +233,8 @@ export declare function loadProfileDirectory(binName: string, dir: string, insta
 }): Profile;
 /**
  * Load a profile: resolve every `dsh.profile.bundles` entry to its patch
- * layer and parse the profile's own patch file. Unreadable or incompatible bundles
- * are skipped and listed in `skippedBundles`; profile manifest and user patch errors still throw.
+ * layer and parse the profile's own patch file. Unreadable bundles, unsupported Host platforms,
+ * and incompatible bundles are skipped and listed in `skippedBundles`; profile manifest and user patch errors still throw.
  * @param binName - the diagnostic prefix on thrown errors.
  * @param name - the profile name.
  * @param installAnchor - absolute path of the dsh app's package.json (first resolution anchor).

package/lib/types/startup-diagnostics.d.ts

@@ -0,0 +1,38 @@
+/** Configuration-free snapshots captured before a failed startup disposes its plugins. */
+import { Context } from '@deepseek-ai/cordis';
+/** One configured entry at the time startup failed. */
+export interface StartupPluginState {
+    readonly id: string;
+    readonly module: string;
+    readonly version: string;
+    readonly state: 'disabled' | 'active' | 'pending' | 'failed' | 'disposed' | 'loading' | 'unloading';
+    /** Loader source URL; individual overlay ownership may be unavailable. */
+    readonly source: string;
+    readonly missing: readonly string[];
+}
+/** Observed registrations for one service missing from a consumer. */
+export interface StartupServiceState {
+    readonly consumer: string;
+    readonly service: string;
+    /** Empty means no registration was observed, not that no configured plugin can provide it. */
+    readonly providers: readonly {
+        readonly entry: string;
+        readonly state: string;
+        readonly visibility: 'same-scope' | 'other-scope';
+    }[];
+}
+/** Bounded startup state without plugin config, service values, or logger arguments. */
+export interface StartupCompositionDiagnostic {
+    readonly plugins: readonly StartupPluginState[];
+    readonly services: readonly StartupServiceState[];
+    readonly omittedPlugins: number;
+    readonly omittedServices: number;
+}
+/**
+ * Capture Loader state and registered service ownership before teardown.
+ * Providers that never registered cannot be inferred from their package names.
+ * @param ctx - Live application context with its Loader still mounted.
+ * @returns At most 256 plugin rows and 256 missing-service observations, with omission counts.
+ */
+export declare function captureStartupComposition(ctx: Context): StartupCompositionDiagnostic;
+//# sourceMappingURL=startup-diagnostics.d.ts.map

package/lib/worker/profile-resolution-bootstrap.js

@@ -569,7 +569,7 @@ function internalModules() {
 	const esmResolve = addon.requireBuiltin("internal/modules/esm/resolve");
 	const esm = esmModule.getOrInitializeCascadedLoader();
 	const modern = "getOrCreateModuleJob" in esm;
-	/* v8 ignore start -- the supported Node 22/24/26 matrix validates each available Internal interface */
+	/* v8 ignore start -- the supported Node 24/26 matrix validates each available Internal interface */
 	if (typeof esm.resolveSync !== "function" || typeof Reflect.get(esm, modern ? "getOrCreateModuleJob" : "getModuleJobForImport") !== "function" || !modern && typeof Reflect.get(esm, "resolve") !== "function" || typeof cjsModule.Module._resolveFilename !== "function" || typeof cjsHelpers.getCjsConditions !== "function" || typeof esmUtils.getDefaultConditions !== "function" || typeof esmResolve.defaultResolve !== "function") throw new Error("profile resolution: unsupported Node module loader");
 	/* v8 ignore stop */
 	return {
@@ -645,7 +645,7 @@ function installRuntimeInterception(resolution) {
 				let expected;
 				try {
 					expected = adapted(target.specifier, target.parentURL, attributes);
-					/* v8 ignore next -- Node 24+ resolves synchronously; the Node 22 matrix covers its Promise result */
+					/* v8 ignore next -- the current loader resolves synchronously; the private interface also permits Promise results */
 					if (expected instanceof Promise) expected = expected.catch(restoreImporter);
 				} catch (error) {
 					return restoreImporter(error);
@@ -674,7 +674,7 @@ function installRuntimeInterception(resolution) {
 				} catch (error) {
 					return restoreImporter(error);
 				}
-				/* v8 ignore next -- Node 24+ resolves synchronously; the Node 22 matrix covers its Promise result */
+				/* v8 ignore next -- the current loader resolves synchronously; the private interface also permits Promise results */
 				if (result instanceof Promise) return result.catch(restoreImporter);
 				if (cacheable) state.esm = result;
 				return result;
@@ -696,12 +696,12 @@ function installRuntimeInterception(resolution) {
 		};
 		return (request, parent, attributes) => {
 			const result = adapted(request, parent, attributes);
-			/* v8 ignore next -- Node 24+ resolves synchronously; the Node 22 matrix covers its Promise result */
+			/* v8 ignore next -- the current loader resolves synchronously; the private interface also permits Promise results */
 			return result instanceof Promise ? result.then((resolved) => relocate(resolved, parent)) : relocate(result, parent);
 		};
 	};
 	let restoreEsm;
-	/* v8 ignore else -- CI coverage runs Node 24 v2; the Node 22 matrix exercises the v1 adapter */
+	/* v8 ignore else -- CI coverage runs Node 24 v2; the Node 24.0 matrix exercises the v1 adapter */
 	if (modern) {
 		const loader = esm;
 		const original = Reflect.get(loader, "resolveSync");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-app-boot",
   "description": "Shared boot glue for the app bins: .env loading, fail-loud Loader guards, snapshot-aware config resolution, and the Loader boot sequence",
-  "version": "0.2.1-rc.4",
+  "version": "0.2.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,8 +32,9 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/dsh-atomic-write": "0.2.1-rc.4",
-    "@deepseek-ai/dsh-package-manifest": "0.2.1-rc.4",
+    "@deepseek-ai/dsh-atomic-write": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-official-bundles": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-package-manifest": "0.2.2-alpha.2",
     "@eslint-community/regexpp": "^4.12.2",
     "ajv": "^8.20.0",
     "js-yaml": "^4.3.2",
@@ -42,24 +43,24 @@
     "semver": "^7.8.5"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis-plugin-group": "~1.0.5",
-    "@deepseek-ai/cordis-plugin-include": "~1.0.10",
-    "@deepseek-ai/cordis-plugin-loader": "~1.0.6",
-    "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.4",
-    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.4",
-    "@deepseek-ai/cordis": "~4.0.5"
+    "@deepseek-ai/cordis-plugin-group": "~1.0.6-alpha.1",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.11-alpha.1",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.7-alpha.1",
+    "@deepseek-ai/dsh-launch-environment": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-home-paths": "0.2.2-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.6-alpha.1"
   },
   "devDependencies": {
-    "@deepseek-ai/schemastery": "~3.18.5",
-    "@deepseek-ai/cordis-plugin-group": "~1.0.5",
-    "@deepseek-ai/cordis-plugin-include": "~1.0.10",
-    "@deepseek-ai/cordis-plugin-loader": "~1.0.6",
-    "@deepseek-ai/cordis-plugin-timer": "~1.1.7",
-    "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.4",
-    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.4",
-    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.4",
+    "@deepseek-ai/schemastery": "~3.18.6-alpha.1",
+    "@deepseek-ai/cordis-plugin-group": "~1.0.6-alpha.1",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.11-alpha.1",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.7-alpha.1",
+    "@deepseek-ai/cordis-plugin-timer": "~1.1.8-alpha.1",
+    "@deepseek-ai/dsh-launch-environment": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-home-paths": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.2",
     "@types/js-yaml": "^4.0.9",
     "@types/semver": "^7.8.0",
-    "@deepseek-ai/cordis": "~4.0.5"
+    "@deepseek-ai/cordis": "~4.0.6-alpha.1"
   }
 }

package/lib/types/official-bundle-packages.d.ts

@@ -1,4 +0,0 @@
-/** Package admission shared by offline catalog generation and release ordering. */
-/** Public DSH release members available through the ordinary on-demand bundle installer. */
-export declare const ON_DEMAND_BUNDLES: readonly string[];
-//# sourceMappingURL=official-bundle-packages.d.ts.map

package/lib/types/official-bundles.d.ts

@@ -1,12 +0,0 @@
-/** Official bundles offered without installing their provider runtimes in the DSH distribution. */
-import type { PluginLocalizedMeta } from '@deepseek-ai/dsh-package-manifest';
-export { ON_DEMAND_BUNDLES } from './official-bundle-packages.ts';
-/** Offline discovery metadata; installation state and the requested version belong to the running host. */
-export interface OfficialBundleCatalogEntry {
-    /** Exact npm package name accepted by the existing bundle installer. */
-    readonly packageName: string;
-    /** Package-owned localized text and a self-contained icon, embedded without provider code. */
-    readonly meta: Required<Pick<PluginLocalizedMeta, 'title' | 'description' | 'icon'>>;
-}
-export { OFFICIAL_ON_DEMAND_CATALOG } from './official-bundles.generated.ts';
-//# sourceMappingURL=official-bundles.d.ts.map

package/lib/types/official-bundles.generated.d.ts

@@ -1,5 +0,0 @@
-/** Generated offline Official bundle metadata. Run pnpm gen-official-bundle-catalog; do not edit. */
-import type { OfficialBundleCatalogEntry } from './official-bundles.ts';
-/** Official on-demand entries, independent of installed packages and registry availability. */
-export declare const OFFICIAL_ON_DEMAND_CATALOG: readonly OfficialBundleCatalogEntry[];
-//# sourceMappingURL=official-bundles.generated.d.ts.map