@deepseek-ai/dsh-app-boot 0.1.7-alpha.1 → 0.1.7-rc.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
-README.md: 5bbe75d641eeeaf3b87c31221b3491ad1408934e
-README.zh.md: b3ac89c1cb082880622175b494d540888b19e804
+README.md: c32f8e4dd9065897a7dcbe4b7a2fd2e067b25e46
+README.zh.md: 0bbdab2a5d51deeb6b63bf972e6550f9b4034db1

package/README.md

@@ -40,7 +40,7 @@ installFailLoud('dsh')
 const ctx = await boot('dsh', resolveConfigPath(argv[2], process.env.DSH_SNAPSHOT))
 ```
 
-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`, `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`, `webserver`, `modules`, `connection`, `headless-runner`, `acp`, and `sdk-jsonrpc-server`.
 
 <a id="profiles"></a>
 ### Profiles
@@ -49,6 +49,12 @@ Import profile and bundle declaration types from [`@deepseek-ai/dsh-package-mani
 
 A profile is how one dsh installation ships different app surfaces: `web`, `headless`, `acp`, `sdk`, and `sdk-minimal` start distinct compositions from the same launcher. A profile lives at `$DSH_HOME/profiles/<name>` and combines installable bundles with its own `cordis.patch.yml`. A bundle's `dsh.bundle.patch` names one patch file or an ordered list of files; `bundlePatchFiles` validates the declaration and `bundlePatchPaths` resolves it to absolute paths; the layer concatenates their patch lists in that order. The YAML composition enables or disables HMR. The shipped `web` template uses live reload, while the other shipped templates apply patches only at startup. `sdk-minimal` names only its standalone bundle; the other templates retain base-plus-mode stacks. `dsh --profile <name> --from-default-profile <template>` creates a custom profile at a new non-shipped name from one shipped template, while `dsh plugin` initializes a base-backed profile and manages its installed bundles. Bundle resolution, manifest, and patch-loading failures print a diagnostic and skip that bundle without changing its selection. Remaining bundles keep their order; profile and user-patch errors still fail startup. Skipping a bundle does not guarantee that the remaining composition can provide the required services. Application-owned npm projects, such as Electron's reserved Desktop profile, use `loadProfileDirectory` to load an already initialized directory without exposing it through CLI profile lookup.
 
+Before a profile imports a plugin, DSH checks its `peerDependencies` on `@deepseek-ai/dsh` and `@deepseek-ai/dsh-*` against the single runtime version returned by `getDshRuntimeVersion()`. Every declared range must match; prereleases participate in range matching. Source-workspace `workspace:^`, `workspace:~`, and `workspace:*` refer to that same runtime. Missing DSH peers impose no constraint; invalid ranges are incompatible. These checks use peer declarations, not `engines.dsh`, and are not a sandbox against malicious package code.
+
+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 peers 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. 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` peer declaration, 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.
+
 Your machine-local preferences also live in the Harness home:
 
 - **`.env`** — your ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. Variables that decide how the process starts (`PATH`, `DSH_*`, `XDG_*` and similar) are rejected from files: export them instead. The four proxy names (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`) are accepted from the Harness-home file only, never from the invoking directory's, which arrives with a clone. For a non-product bin that just wants one directory's `.env`, a missing file is fine and an unloadable one prints one labelled warning line.
@@ -97,6 +103,7 @@ After the Loader settles, app-boot warns when only optional entries are inactive
 | An injected service is unavailable | Warn; continue while the entry waits for its dependencies | Stop startup | Keep the entry waiting; adding the missing provider can activate it |
 | HTTP port binding fails | Warn; continue without that endpoint | Stop startup | Keep the process running without the failed endpoint; corrected config can restore it |
 | Detached asynchronous work outside the `apply()` return Promise produces an unhandled rejection | Fatal: dispose the app and exit nonzero | Fatal: dispose the app and exit nonzero | Fatal: dispose the app and exit nonzero, regardless of entry id |
+| A synchronous callback (a stream `'data'` listener, a timer) throws an uncaught exception at any point in the process lifetime | Fatal: dispose the app and exit nonzero; the failed operation is not resumed | Fatal: dispose the app and exit nonzero; the failed operation is not resumed | Fatal: dispose the app and exit nonzero, regardless of entry id |
 | Entry is absent or explicitly disabled | Ignore it | Ignore it | Do not activate it; no required-startup audit |
 
 The required list above includes `modules` and `connection`; Web startup cannot succeed when either enabled entry fails. Failure of an optional provider can also prevent a required consumer from activating. Schema rejection before an existing entry updates is not a transactional rollback of sibling changes.
@@ -121,6 +128,7 @@ This section explains how the outcomes above are realized and points at the code
 
 ### Design notes
 
+- **Runtime version.** `getDshRuntimeVersion()` reads this package's manifest through a filesystem path, including the executable's virtual filesystem; missing or invalid versions fail rather than bypassing compatibility checks.
 - **Profile launch data.** `ctx.profileContext` contains only profile locations, startup bundle names, parsed invocation overlays and the telemetry opt-out value. `readProfilePatches()` composes the supplied startup profile or reads current files at those locations; callers schedule and apply the result.
 - **Process-local module resolution.** The launcher installs the runtime resolution on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer. Explicit CommonJS `paths` always retain native lookup, including paths inside profiles.
 - **Linked directories.** A profile link to an external directory admits its importers to peer-aware ancestor lookup, even without its own `package.json`. At each `D/node_modules` position, current `D/package.json` peer names present in the runtime table use the runtime package; other names use the physical candidate. A nearer physical package precedes a later peer declaration, and a peer position needs no physical `node_modules`. Installation-scope package directories are excluded from linked interception; overlapping roots do not change the importer's lookup order ([rule](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md)).
@@ -191,7 +199,7 @@ These limits describe when this boot library is a poor fit or needs special care
 
 - **Runtime resolution depends on Node internals** — supported Node versions require the native builtin-access addon and executable compatibility coverage. Only built Harness-owned Workers receive the runtime resolution bootstrap; third-party Workers and custom `vm` linkers keep native resolution.
 - **Relinking a profile package needs a restart** — Node caches real paths, so changing the target of a profile link or a dependency link requires a process restart.
-- **Linked scope follows recorded real directories** — a hoisted dependency outside every linked root uses native Node. Current peer reads do not invalidate Node caches, watch files, or validate peer version ranges.
+- **Linked scope follows recorded real directories** — a hoisted dependency outside every linked root uses native Node. A peer read never invalidates Node caches or changes which files are watched.
 - **Source launches use an ESM-only hook** — CommonJS requests still need the JavaScript files selected by package exports; resolution does not supply missing build outputs.
 - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
 - **Environment discovery is launch-scoped** — `loadLayeredEnv` reads only the invocation directory and Harness home once; it does not search parents or follow a workspace selected later. `loadEnv` remains the one-directory helper for non-product bins.

package/README.zh.md

@@ -40,7 +40,7 @@ installFailLoud('dsh')
 const ctx = await boot('dsh', resolveConfigPath(argv[2], process.env.DSH_SNAPSHOT))
 ```
 
-有了这个入口，启动会保留所有能够激活的插件。启用但失败的插件会产生带标签的警告。required entry 失败时，启动会拆卸整个应用并以非零码退出；profile 中不存在的 required id 和已禁用的 required entry 不影响启动。全局 required list 覆盖共享 Agent 执行、应用 endpoint，以及 Web 启动与传输：`agent-loop`、`webserver`、`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`、`webserver`、`modules`、`connection`、`headless-runner`、`acp` 和 `sdk-jsonrpc-server`。
 
 <a id="profiles"></a>
 ### Profile
@@ -49,6 +49,12 @@ Profile 与组合包的声明类型从 [`@deepseek-ai/dsh-package-manifest`](../
 
 profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`headless`、`acp`、`sdk` 与 `sdk-minimal` 从同一 launcher 启动不同组合。profile 位于 `$DSH_HOME/profiles/<name>`，由可安装组合包和自身 `cordis.patch.yml` 组成。组合包的 `dsh.bundle.patch` 指定一个 patch 文件或一个有序的文件列表；`bundlePatchFiles` 校验该声明，`bundlePatchPaths` 把它解析为绝对路径；该层按此顺序拼接各文件的 patch 列表。YAML 组合决定是否启用 HMR。随产品交付的 `web` 模板实时重载，其他随附模板只在启动时应用 patch。`sdk-minimal` 只列出自身的独立组合包，其他模板保留 base 加模式的组合包栈。`dsh --profile <name> --from-default-profile <template>` 从一个随附模板，在新的非内置名称处创建自定义 profile；`dsh plugin` 则初始化以 base 为基础的 profile，并管理其中安装的组合包。组合包解析、manifest 读取或 patch 加载失败时会输出诊断并跳过该组合包，不改变其选择状态。其余组合包保持原顺序；profile 和用户 patch 错误仍会导致启动失败。跳过组合包不保证剩余组合能够提供所需服务。由应用持有的 npm 项目（例如 Electron 保留的 Desktop profile）通过 `loadProfileDirectory` 加载已经初始化的目录，而不会将它暴露给 CLI profile 查找。
 
+profile 导入插件前，DSH 会检查其 `peerDependencies` 中对 `@deepseek-ai/dsh` 和 `@deepseek-ai/dsh-*` 的依赖，与 `getDshRuntimeVersion()` 返回的唯一运行时版本比较。每个声明的版本范围都必须匹配；预发布版本参与范围匹配。源码工作区的 `workspace:^`、`workspace:~` 和 `workspace:*` 指向同一个运行时。未声明 DSH peer 时不施加版本约束；无效范围视为不兼容。这些检查使用 peer 声明，而不是 `engines.dsh`，也不是防范恶意包代码的沙箱。
+
+检查只发生在 DSH 自己持有的组合入口，改写的是启动器自己的那份组合：profile 的 patch 层、依赖清单与组合包列表都不会改变。`prepareProfilePatches` 在启动器的空 profile 根之上组合，并在挂载根 Include 时以及每次 profile 重新组合时执行，因此被拒绝的插件永远不会导入其模块；`prepareProfileEntries` 对 preset 行做同样的事。被拒绝的普通行会变成游离的 `disabled: true` 行；原生 group 保持挂载，其被拒绝的子行不会加载；若某个原生 Include 会到达被拒绝的插件，则整体省略该 Include，因为它的文件不会被改写。被策略拒绝的行在 profile 中保留其配置的 `disabled` 值，每次拒绝都会报告包名、版本与风险。组合包本身不是行，因此 `loadProfileDirectory` 在启动和每次重新组合加载 profile 的组合包层时，检查每个组合包自己声明的 DSH peer；没有豁免的不兼容组合包会像无法读取的组合包一样被跳过。这些入口不覆盖其他嵌入方通过自己的 `ctx.plugin` 调用挂载的插件。会话中直接改文件的两类编辑只在下一次重新组合或启动时才被判定：正在运行的插件自己的 `package.json` peer 声明，以及 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)负责每次变更所需的授权、撤销与风险确认。
+
 你的机器本地偏好同样位于 harness home 中：
 
 - **`.env`**——你的普通环境层：调用目录的文件优先于 harness home 的文件，两者都低于继承环境。在文件中设置的进程启动变量（如 `PATH`、`DSH_*`、`XDG_*`）会被拒绝：请改为导出这些变量。四个代理名（`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY`）只从 harness home 的文件接受，绝不从调用目录的文件接受——后者随 clone 一起到来。对于只想加载某个目录 `.env` 的非产品 bin，文件缺失不影响启动，文件无法加载时输出一行带标签的警告。
@@ -97,6 +103,7 @@ Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如
 | 注入的服务不可用 | 警告；继续，条目等待依赖 | 终止启动 | 条目继续等待；补上缺失的提供方后可以激活 |
 | HTTP 端口绑定失败 | 警告；继续，但该端点不可用 | 终止启动 | 进程继续运行，但失败的端点不可用；修正配置后可以恢复 |
 | 脱离 `apply()` 返回 Promise 的异步任务产生未处理 rejection | 致命错误：释放应用并以非零码退出 | 致命错误：释放应用并以非零码退出 | 致命错误：释放应用并以非零码退出，与条目 id 无关 |
+| 同步回调（流的 `'data'` 监听器、定时器）在进程生命周期任一时刻抛出未捕获异常 | 致命错误：释放应用并以非零码退出；失败的操作不会被恢复 | 致命错误：释放应用并以非零码退出；失败的操作不会被恢复 | 致命错误：释放应用并以非零码退出，与条目 id 无关 |
 | 条目缺失或被显式禁用 | 忽略 | 忽略 | 不激活该条目；不执行 required 启动审计 |
 
 上面的 required 列表包含 `modules` 与 `connection`；只要其中一个已启用条目失败，Web 就无法成功启动。Optional 提供方失败也可能使 required 消费方无法激活。现有条目的新配置在更新前被 schema 校验拒绝，并不等于对兄弟插件的变更做事务回滚。
@@ -121,6 +128,7 @@ Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如
 
 ### 设计说明
 
+- **运行时版本。** `getDshRuntimeVersion()` 通过文件系统路径读取本包清单，也支持可执行文件内的虚拟文件系统；版本缺失或无效时会失败，而不会绕过兼容性检查。
 - **Profile 启动数据。** `ctx.profileContext` 只包含 profile 位置、启动时组合包名称、已解析的调用级 overlay 与遥测退出值。`readProfilePatches()` 组合传入的启动 profile，或读取这些位置上的当前文件；调用方负责调度和应用结果。
 - **进程内模块解析。** launcher 在挂载 profile 条目前，将 runtime resolution 安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、子路径、模块缓存和错误码仍由 Node 负责；路由后的 ESM 失败报告原始 importer。显式 CommonJS `paths` 始终保留原生查询，包括指向 profile 内的路径。
 - **链接目录。** profile 链接到树外目录时，其下的 importer 参与逐层 peer 查询，即使目标没有自身的 `package.json`。在每个 `D/node_modules` 位置，当前 `D/package.json` 的 peer 包名若存在于运行时表，就使用运行时包；其他包名查询物理候选。更近的物理包先于后续 peer 声明，peer 位置无需物理 `node_modules`。installation 作用域包目录不参与 linked 拦截，重叠 root 不改变 importer 的查询顺序（[规则](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md)）。
@@ -191,7 +199,7 @@ Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如
 
 - **运行时解析依赖 Node 内部机制**——受支持的 Node 版本需要 native builtin access addon 和可执行兼容验证。只有构建后的 Harness 自有 Worker 接收 runtime resolution bootstrap；第三方 Worker 与自定义 `vm` linker 保持原生解析。
 - **重新链接 profile 包需要重启**——Node 缓存真实路径，因此改变 profile 链接或依赖链接的目标需要重启进程。
-- **链接作用域以记录的真实目录为准**——提升后的依赖若在所有 linked root 之外，就使用原生 Node。实时读取 peer 不会使 Node 缓存失效、监视文件或校验 peer 版本范围。
+- **链接作用域以记录的真实目录为准**——提升后的依赖若在所有 linked root 之外，就使用原生 Node。每次读取 peer 都不会使 Node 缓存失效，也不会改变被监视的文件。
 - **源码启动只安装 ESM 钩子**——CommonJS 请求仍需要 package exports 选中的 JavaScript 文件，解析器不会补出缺失的构建产物。
 - **快照回放替换仅识别特定 basename**——只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
 - **环境发现以启动为界**——`loadLayeredEnv` 只读取一次调用目录与 harness home 中的 `.env`；它不搜索父目录，也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。

package/lib/index.js

@@ -1,16 +1,19 @@
 import { createRequire, isBuiltin } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { parseEnv } from "node:util";
+import fs, { existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { inspect, parseEnv } from "node:util";
 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, readFile, realpath, rename, writeFile } from "node:fs/promises";
+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 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 ../../../vendor/include/src/index.ts
@@ -245,6 +248,198 @@ var Include = class extends EntryTree {
 	}
 };
 //#endregion
+//#region lib/types/plugin-compatibility.js
+/** Evaluate plugin dsh peer requirements without importing plugin code. */
+function objectOf$1(value, field) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${field} must be an object`);
+	return value;
+}
+function runtimeVersionOf(value) {
+	if (typeof value !== "string" || semver.valid(value) === null) throw new Error(`Invalid dsh runtime version: ${JSON.stringify(value)}; expected a semantic version`);
+	return value;
+}
+function identityField(manifest, field) {
+	const value = Object.hasOwn(manifest, field) ? manifest[field] : void 0;
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`Plugin manifest ${field} must be a non-empty string when dsh peers are incompatible`);
+	return value;
+}
+/**
+* Read this app-boot package's version in both source and bundled installations.
+* @returns the validated runtime semantic version, preserving its exact spelling.
+* @throws if package.json cannot be read or its version is missing or invalid.
+*/
+function getDshRuntimeVersion() {
+	const filename = fileURLToPath(new URL("../package.json", import.meta.url));
+	const manifest = objectOf$1(JSON.parse(fs.readFileSync(filename, "utf8")), "app-boot package.json");
+	return runtimeVersionOf(Object.hasOwn(manifest, "version") ? manifest.version : void 0);
+}
+/**
+* Check every @deepseek-ai/dsh or @deepseek-ai/dsh-* peer against the runtime.
+* Prereleases participate in ranges. workspace:^, workspace:~, and workspace:*
+* refer to the current runtime; other invalid ranges are incompatible.
+* @param manifest - parsed plugin package.json; inherited fields are ignored.
+* @param exemptions - exact plugin name@version keys mapped to exact runtime versions.
+* @param runtimeVersion - running dsh version, defaulting to this app-boot package.
+* @returns incompatible peers and exemption status, or undefined when none are incompatible.
+* @throws for malformed manifest peer fields, invalid runtime versions, or missing identity on a mismatch.
+*/
+function evaluatePluginCompatibility(manifest, exemptions = {}, runtimeVersion = getDshRuntimeVersion()) {
+	runtimeVersionOf(runtimeVersion);
+	const fields = objectOf$1(manifest, "Plugin manifest");
+	if (!Object.hasOwn(fields, "peerDependencies")) return void 0;
+	const dependencies = objectOf$1(fields.peerDependencies, "Plugin manifest peerDependencies");
+	const peers = {};
+	for (const [name, range] of Object.entries(dependencies)) {
+		if (typeof range !== "string") throw new Error(`Plugin manifest peerDependencies[${JSON.stringify(name)}] must be a string`);
+		if (name !== "@deepseek-ai/dsh" && !name.startsWith("@deepseek-ai/dsh-")) continue;
+		const requirement = [
+			"workspace:^",
+			"workspace:~",
+			"workspace:*"
+		].includes(range) ? runtimeVersion : range;
+		if (requirement.trim() === "" || !semver.satisfies(runtimeVersion, requirement, { includePrerelease: true })) peers[name] = range;
+	}
+	if (Object.keys(peers).length === 0) return void 0;
+	const name = identityField(fields, "name");
+	const version = identityField(fields, "version");
+	const key = `${name}@${version}`;
+	return {
+		name,
+		version,
+		runtimeVersion,
+		peers,
+		exempted: (Object.hasOwn(exemptions, key) ? exemptions[key] : void 0)?.includes(runtimeVersion) === true
+	};
+}
+/**
+* Describe incompatible peers, their risk, and the exact-version remedy.
+* Surfaces with their own grant mechanism or locale render the structured result themselves.
+* @param issue - incompatible plugin/runtime result, including exempted mismatches.
+* @returns an English diagnostic for logs and stderr.
+*/
+function pluginCompatibilityWarning(issue) {
+	const key = `${issue.name}@${issue.version}`;
+	return `Plugin ${key} is incompatible with dsh ${issue.runtimeVersion}: peerDependencies ${JSON.stringify(issue.peers)}. Running it may cause crashes or data loss. Update the plugin or install a plugin version compatible with this dsh runtime. To accept this risk explicitly, grant the exact-version exemption for ${key} on dsh ${issue.runtimeVersion} with \`dsh plugin allow-version\` or the plugin manager, then retry the installation or restart dsh. Exact-version exemption: ${issue.exempted ? "active" : "not active"}.`;
+}
+//#endregion
+//#region lib/types/profile-compatibility.js
+/** Profile-local compatibility permissions readable before any Cordis plugins load. */
+/** Independent profile metadata; neither package manifests nor Cordis patches carry grants. */
+const PROFILE_COMPATIBILITY_FILENAME = "compatibility.json";
+/** Published and scoped npm package names, as npm accepts them in a manifest dependency key. */
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/** Whether a decoded record accepts only exact DSH versions. */
+function isVersionList(value) {
+	return Array.isArray(value) && value.every((version) => typeof version === "string" && isExactPluginVersion(version));
+}
+/** Test whether an exemption names a canonical exact SemVer, including build metadata.
+* @param value Version supplied by a manifest or user.
+* @returns False for ranges, prefixes, whitespace, and malformed versions.
+*/
+function isExactPluginVersion(value) {
+	const parsed = parse(value);
+	return parsed !== null && value === `${parsed.version}${parsed.build.length === 0 ? "" : `+${parsed.build.join(".")}`}`;
+}
+/** Validate one explicit exemption without granting it.
+* @param packageVersion Exact npm package-name@version, never an installation spec or range.
+* @param runtimeVersion Exact DSH version, including prerelease and build metadata.
+* @throws When either identity is not canonical.
+*/
+function validatePluginVersionExemption(packageVersion, runtimeVersion) {
+	const separator = packageVersion.lastIndexOf("@");
+	if (separator <= 0 || !PACKAGE_NAME.test(packageVersion.slice(0, separator)) || !isExactPluginVersion(packageVersion.slice(separator + 1)) || !isExactPluginVersion(runtimeVersion)) throw new Error("Version exemptions require an exact npm package-name@version and an exact DSH runtime version");
+}
+/** Read the profile's independent compatibility file without loading plugins.
+* A missing file authorizes nothing. An unreadable or unparsable file authorizes nothing and is
+* reported instead of failing, so a bad file can never make the profile unusable; rejected records
+* are skipped while the remaining valid ones still apply.
+* @param profileDir Absolute profile directory.
+* @returns Accepted exemptions plus every problem found; no manifest fallback is used.
+*/
+function readProfileCompatibility(profileDir) {
+	const filename = join(profileDir, PROFILE_COMPATIBILITY_FILENAME);
+	const unreadable = (reason) => ({
+		exemptions: {},
+		warnings: [`${filename} ${reason}; treating the profile as having no exemptions`],
+		rewritable: false
+	});
+	let text;
+	try {
+		text = readFileSync(filename, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return {
+			exemptions: {},
+			warnings: [],
+			rewritable: true
+		};
+		return unreadable(`cannot be read (${String(error)})`);
+	}
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch (error) {
+		return unreadable(`is not valid JSON (${String(error)})`);
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return unreadable("must map exact package@version keys to DSH version lists");
+	const exemptions = {};
+	const warnings = [];
+	for (const [key, versions] of Object.entries(value)) {
+		const separator = key.lastIndexOf("@");
+		if (separator <= 0 || !PACKAGE_NAME.test(key.slice(0, separator)) || !isExactPluginVersion(key.slice(separator + 1))) {
+			warnings.push(`${filename}: ${JSON.stringify(key)} is not an exact package-name@version key; the record is ignored`);
+			continue;
+		}
+		if (!isVersionList(versions)) {
+			warnings.push(`${filename}: ${key} must contain a list of exact DSH versions; the record is ignored`);
+			continue;
+		}
+		exemptions[key] = versions;
+	}
+	return {
+		exemptions,
+		warnings,
+		rewritable: warnings.length === 0
+	};
+}
+/** Read only the accepted exemptions of a profile.
+* @param profileDir Absolute profile directory.
+* @returns Exact package-name@version keys mapped to their allowed DSH versions.
+*/
+function readProfileVersionExemptions(profileDir) {
+	return readProfileCompatibility(profileDir).exemptions;
+}
+/** Persist one informed grant or revocation under the compatibility file's own lock.
+* @param profileDir Profile directory; no package manifest is created or modified.
+* @param packageVersion Exact manifest package-name@version.
+* @param runtimeVersion Exact DSH version; grants must name the current runtime, revocations may name historical ones.
+* @param enabled Whether to grant rather than revoke.
+* @param acceptRisk Required true for grants after explicit acknowledgement of possible crashes or data loss.
+* @returns After the atomic write. Existing plugin instances are not reloaded by this operation.
+* @throws For invalid identities, missing consent, a stale runtime, or a file the reader rejected,
+* which the user must repair by hand because rewriting it would discard their content.
+*/
+async function setProfileVersionExemption(profileDir, packageVersion, runtimeVersion, enabled, acceptRisk) {
+	validatePluginVersionExemption(packageVersion, runtimeVersion);
+	if (enabled && !acceptRisk) throw new Error("Incompatible plugins may cause crashes or data loss. To grant this exact-version exemption, explicitly acknowledge the risk with --accept-risk (acceptRisk: true).");
+	const current = getDshRuntimeVersion();
+	if (enabled && runtimeVersion !== current) throw new Error(`Cannot approve DSH ${runtimeVersion}: this application runs DSH ${current}. Use --dsh-version ${current}.`);
+	await mkdir(profileDir, { recursive: true });
+	const filename = join(profileDir, PROFILE_COMPATIBILITY_FILENAME);
+	await withFileLock(filename, async () => {
+		const current = readProfileCompatibility(profileDir);
+		if (!current.rewritable) throw new Error(`${PROFILE_COMPATIBILITY_FILENAME} must be repaired before exemptions change:\n${current.warnings.join("\n")}`);
+		const exemptions = current.exemptions;
+		const versions = exemptions[packageVersion] ?? [];
+		if (enabled) exemptions[packageVersion] = [...new Set([...versions, runtimeVersion])];
+		else {
+			const retained = versions.filter((version) => version !== runtimeVersion);
+			if (retained.length) exemptions[packageVersion] = retained;
+			else Reflect.deleteProperty(exemptions, packageVersion);
+		}
+		await writeFileAtomic(filename, JSON.stringify(exemptions, void 0, 2) + "\n", { mode: 384 });
+	});
+}
+//#endregion
 //#region lib/types/profile-resolution/legacy-links.js
 /** Package directory canonicalization through the active runtime carrier's filesystem. */
 /**
@@ -710,7 +905,8 @@ function resolveBundleDir(binName, packageName, installAnchor, profileDir) {
 * Load an already initialized profile directory without resolving it through
 * the shared Harness home. This is used by application-owned profiles whose
 * package project and lifecycle belong to that application.
-* Unreadable bundles are reported on stderr and skipped without changing the manifest.
+* Unreadable bundles, and bundles whose own dsh peers the profile does not exempt, are reported
+* on stderr and skipped without changing the manifest.
 * @param binName - the diagnostic prefix on thrown errors.
 * @param dir - absolute profile package directory.
 * @param installAnchor - absolute path of the owning dsh app's package.json.
@@ -720,10 +916,14 @@ function resolveBundleDir(binName, packageName, installAnchor, profileDir) {
 function loadProfileDirectory(binName, dir, installAnchor, options = {}) {
 	const bundles = readProfileManifest(binName, dir).dsh?.profile?.bundles ?? [];
 	const layers = [];
+	const exemptions = bundles.length === 0 ? {} : readProfileVersionExemptions(dir);
 	for (const packageName of bundles) try {
 		const packageDir = resolveBundleDir(binName, packageName, installAnchor, dir);
-		const bundle = readProfileManifest(binName, packageDir).dsh?.bundle;
+		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`);
+		const issue = evaluatePluginCompatibility(bundleManifest, exemptions);
+		if (issue !== void 0 && !issue.exempted) throw new Error(pluginCompatibilityWarning(issue));
 		const patchPaths = bundlePatchPaths(packageDir, bundle);
 		const patches = patchPaths.flatMap((patchPath) => loadOverlayPatches(binName, patchPath));
 		layers.push({
@@ -747,8 +947,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 bundles are reported
-* on stderr and skipped; profile manifest and user patch errors still throw.
+* layer and parse the profile's own patch file. Unreadable or incompatible bundles
+* are reported on stderr and skipped; 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).
@@ -1779,6 +1979,161 @@ function readPluginMeta(specifier, parentURL) {
 	}
 }
 //#endregion
+//#region lib/types/compatibility-preflight.js
+/** Compatibility checks at the composition entry points DSH owns; no Loader instrumentation. */
+function readManifest(filename) {
+	return JSON.parse(readFileSync(filename, "utf8"));
+}
+/** Render the patch wording an Include would report, through the profile's logger. */
+function patchWarning(ctx) {
+	return (message, ...args) => {
+		let index = 0;
+		ctx.logger.warn(message.replace(/%C/g, () => JSON.stringify(args[index++])));
+	};
+}
+function manifestOf(ctx, name, parentURL) {
+	if (name.startsWith("cordis:")) return void 0;
+	const specifier = name.startsWith("#") ? resolvePluginResource(name, parentURL) : name;
+	const packages = ctx.get("pluginPackages");
+	const pkg = packages?.packageOf(specifier, parentURL);
+	if (pkg !== void 0) return readManifest(pkg.manifestPath);
+	const bare = barePackageName(specifier);
+	if (bare !== void 0 && packages === void 0) for (const path of createRequire(parentURL).resolve.paths(bare)) {
+		const filename = join(path, bare, "package.json");
+		if (existsSync(filename)) return readManifest(filename);
+	}
+	if (!isAbsolute(specifier) && !specifier.startsWith(".") && !specifier.startsWith("file:")) return void 0;
+	const url = isAbsolute(specifier) ? pathToFileURL(specifier) : new URL(specifier, parentURL);
+	let dir;
+	try {
+		dir = dirname(realpathSync(fileURLToPath(url)));
+	} catch (error) {
+		if ([
+			"ENOENT",
+			"ENOTDIR",
+			"EISDIR"
+		].includes(String(error.code))) return void 0;
+		throw error;
+	}
+	while (true) try {
+		return readManifest(join(dir, "package.json"));
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+}
+/** Prepare profile or preset rows before the owning DSH caller passes them to Loader.
+* Only a compatibility conflict denies a row: an entry whose manifest cannot be resolved keeps
+* the Loader's own import failure. A denied ordinary row gains `disabled`; a native Include that
+* reaches a denied plugin is denied as a whole, because its file is never rewritten.
+* @param ctx Context carrying launcher-owned profile facts; non-profile contexts retain their rows.
+* @param entries Complete effective entry list, after patch composition.
+* @param parentURL Resolution base of the tree that will import these rows.
+* @param binName Diagnostic prefix for a denied row; defaults to `dsh`.
+* @returns Detached rows with incompatible entries denied; reads the profile compatibility file once.
+* @throws For malformed compatibility permissions or a profile composition without a resolution base.
+*/
+function prepareProfileEntries(ctx, entries, parentURL, binName = "dsh") {
+	return preflight(ctx, entries, parentURL, (row, reason) => {
+		const label = typeof row.id === "string" ? `row ${JSON.stringify(row.id)}` : row.name;
+		process.stderr.write(`${binName}: disabling profile plugin ${label}: ${reason}\n`);
+	}).rows;
+}
+function preflight(ctx, entries, parentURL, report) {
+	const rows = structuredClone(entries);
+	const profile = ctx.get("profileContext");
+	if (profile === void 0) return {
+		rows,
+		blocked: false
+	};
+	if (parentURL === void 0) throw new Error("Profile compatibility preflight requires a resolution base");
+	const { exemptions, warnings } = readProfileCompatibility(profile.dir);
+	for (const warning of warnings) process.stderr.write(`${warning}\n`);
+	const includes = /* @__PURE__ */ new Set();
+	/** Only a compatibility conflict denies a row; every other failure keeps the Loader's own diagnosis. */
+	const denial = (row, base) => {
+		try {
+			const manifest = manifestOf(ctx, row.name, base);
+			if (manifest === void 0) return void 0;
+			const issue = evaluatePluginCompatibility(manifest, exemptions);
+			return issue === void 0 || issue.exempted ? void 0 : pluginCompatibilityWarning(issue);
+		} catch (error) {
+			return `its declared peer dependencies cannot be validated: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	};
+	const deny = (row, reason) => {
+		row.disabled = true;
+		if (row.group) row.group = false;
+		report(row, reason);
+	};
+	const check = (rows, base) => {
+		let blocked = false;
+		for (const row of rows) {
+			if (row.disabled === true && !row.group) continue;
+			const conflict = denial(row, base);
+			if (conflict !== void 0) {
+				deny(row, conflict);
+				blocked = true;
+				continue;
+			}
+			if ((row.group === true || row.name === "cordis:group" || row.name === "@deepseek-ai/cordis-plugin-group") && Array.isArray(row.config) && check(row.config, base)) blocked = true;
+			if (row.name !== "cordis:include" && row.name !== "@deepseek-ai/cordis-plugin-include") continue;
+			const reached = includedConflicts(row, base);
+			if (reached !== void 0) {
+				deny(row, reached);
+				blocked = true;
+			}
+		}
+		return blocked;
+	};
+	/** Whether a native Include reaches a denied plugin; an unreadable one has no compatibility opinion. */
+	const includedConflicts = (row, base) => {
+		const config = row.config;
+		if (typeof config?.path !== "string" || ![
+			".yml",
+			".yaml",
+			".json"
+		].includes(extname(config.path))) return;
+		const requested = isAbsolute(config.path) ? config.path : fileURLToPath(new URL(config.path, base));
+		const filename = existsSync(requested) ? realpathSync(requested) : requested;
+		if (includes.has(filename)) return void 0;
+		includes.add(filename);
+		try {
+			let data;
+			try {
+				data = load(readFileSync(filename, "utf8"), { schema: entryListSchema });
+			} catch (error) {
+				if (error.code !== "ENOENT" || config.initial === void 0) return void 0;
+				data = config.initial;
+			}
+			if (!Array.isArray(data)) return void 0;
+			return check(applyEntryPatches(data, config.patches, patchWarning(ctx)), pathToFileURL(filename).href) ? `its included file ${filename} reaches an incompatible plugin, and that file is never rewritten` : void 0;
+		} finally {
+			includes.delete(filename);
+		}
+	};
+	return {
+		rows,
+		blocked: check(rows, parentURL)
+	};
+}
+/** Apply compatibility policy to the complete patch composition over a profile's empty root.
+* The caller passes every patch layer of the profile, because this returns one insertion patch for
+* that empty root: a non-empty root config would lose the caller's override patches by id.
+* @param ctx Profile context prepared by the launcher.
+* @param patches Original ordered profile patches; these remain unchanged.
+* @param parentURL Root Include's resolution base.
+* @param binName Diagnostic prefix for a denied row; defaults to `dsh`.
+* @returns One prepared insertion patch for profiles, or the original patches for non-profile callers.
+*/
+function prepareProfilePatches(ctx, patches, parentURL, binName = "dsh") {
+	if (ctx.get("profileContext") === void 0) return patches;
+	const rows = prepareProfileEntries(ctx, applyEntryPatches([], patches, patchWarning(ctx)), parentURL, binName);
+	return rows.length === 0 ? [] : [{ insert: rows }];
+}
+//#endregion
 //#region lib/types/config-schema/native.js
 /** Identity checks at the plugin-export and lazy-builder boundaries. */
 /**
@@ -3107,9 +3462,11 @@ async function reconcileProfilePatches(ctx, patches, binName, requiredIds = [])
 		failed: row.fiber.state === FIBER_FAILED || row.fiber.state === FIBER_DISPOSED
 	}]);
 	const { patches: _previous, ...includeConfig } = entry.options.config;
+	const parentURL = new URL(".", new URL(includeConfig.path, entry.parent.tree.ctx.baseUrl)).href;
+	const prepared = prepareProfilePatches(ctx, patches, parentURL, binName);
 	await entry.update({ config: {
 		...includeConfig,
-		patches
+		patches: prepared
 	} });
 	const results = await Promise.allSettled(previousFibers.map(({ fiber }) => fiber.await()));
 	await ctx.loader.await();
@@ -3196,14 +3553,15 @@ function parsePatchList(binName, file, content, label) {
 	return anchorInsertedPluginNames(parsed, file);
 }
 /**
-* Compose the effective entry list exactly as `boot()` would mount it: parse
-* the base config file with the include's entry-list dialect, apply every
-* layer's patches as ONE flattened list through the include's own patch
-* algorithm (`applyEntryPatches`) — the same single call `boot()` makes, so
-* even patch-visibility corner cases (a later layer targeting a group child a
-* plain config replacement introduced, which the single-pass id index never
-* sees) compose identically — then render the result as YAML in the same
-* dialect (`!!js` expressions print verbatim, unevaluated).
+* Compose the configured entry list: parse the base config file with the
+* include's entry-list dialect, apply every layer's patches as ONE flattened
+* list through the include's own patch algorithm (`applyEntryPatches`) — the
+* same call `boot()` makes, so even patch-visibility corner cases (a later
+* layer targeting a group child a plain config replacement introduced, which
+* the single-pass id index never sees) compose identically — then render the
+* result as YAML in the same dialect (`!!js` expressions print verbatim,
+* unevaluated). Row admission is a later stage: a plugin row the compatibility
+* policy denies still appears here, while a denied bundle contributes no layer.
 *
 * Every run of rows from the same file and patch layers is preceded by a `# ==` comment
 * naming the file that contributed the rows and any layers that patched them,
@@ -3308,11 +3666,12 @@ function groupedDump(composed, entryOrigins) {
 * @param patches - initial app and user patches, applied in order.
 * @param bareModuleBaseUrl - optional installed-host base for bare package
 * names; relative names continue to resolve beside the configuration file.
+* @param binName - diagnostic prefix for a profile plugin denied by compatibility policy; defaults to `dsh`.
 * @returns the created root Include entry, or `undefined` when a surface
 * disposed the whole tree (taking the Loader service with it) while the
 * entry creation was in flight.
 */
-async function mountRootInclude(ctx, absoluteConfigPath, patches = [], bareModuleBaseUrl) {
+async function mountRootInclude(ctx, absoluteConfigPath, patches = [], bareModuleBaseUrl, binName = "dsh") {
 	ctx.loader.builtins.include = bareModuleBaseUrl === void 0 ? Include : class HostResolvedRootInclude extends Include {
 		import(name, getOuterStack) {
 			const specifier = isAbsolute(name) ? pathToFileURL(name).href : name;
@@ -3325,12 +3684,13 @@ async function mountRootInclude(ctx, absoluteConfigPath, patches = [], bareModul
 		}
 	};
 	ctx.loader.builtins.group = Group;
+	const prepared = prepareProfilePatches(ctx, [...patches], pathToFileURL(dirname(absoluteConfigPath)).href + "/", binName);
 	const rootInclude = {
 		id: "include",
 		name: "cordis:include",
 		config: {
 			path: pathToFileURL(absoluteConfigPath).href,
-			...patches.length > 0 ? { patches: [...patches] } : {}
+			...prepared.length > 0 ? { patches: prepared } : {}
 		}
 	};
 	const includeId = await ctx.loader.create(rootInclude);
@@ -3363,11 +3723,22 @@ async function observeLoaderRejectionCheckpoint(reasons) {
 */
 const FAIL_LOUD_RELEASE_TIMEOUT_MS = 2e3;
 /**
-* Install before boot to turn a late unhandled plugin-init rejection into one
-* labelled stderr diagnostic and `exit(1)`. A rejection already included by
-* {@link auditStartupEntries} is ignored during its process checkpoint;
-* every other rejection remains fatal. Stdout remains untouched for ACP; the
-* returned function removes the handler.
+* Install before boot to turn an unhandled rejection or an uncaught exception,
+* at any point in the process lifetime, into one labelled stderr diagnostic and
+* `exit(1)`. A rejection already included by {@link auditStartupEntries} is
+* ignored during its process checkpoint; every other rejection and every
+* uncaught exception remains fatal. Control never returns to the failed
+* operation after either: only the throw site knows which state is intact, and
+* a listener that threw mid-update (a stream `'data'` handler, a half-applied
+* registry write) leaves silently wrong results behind if it were resumed. The
+* event loop keeps running only until the release hook settles or times out.
+* Stdout remains untouched for ACP; the returned function removes both handlers.
+*
+* The diagnostic is `util.inspect(err)`, not `err.stack`: a `node:fs` error's
+* `code`, `syscall`, and `path` and any `cause` chain are enumerable properties
+* that the stack line omits, and they are what a crash report needs. Once a
+* handler is installed Node prints nothing of its own, so this line is the
+* only record of the failure.
 *
 * The Loader mounts entries concurrently, so a surface that owns the terminal
 * can already hold it when a sibling entry rejects. Exiting straight from the
@@ -3389,15 +3760,17 @@ const FAIL_LOUD_RELEASE_TIMEOUT_MS = 2e3;
 * @param release - optional teardown awaited before exit, used by a
 *   terminal-owning surface to restore the terminal. Its own failure is
 *   swallowed because the pending fatal exit already owns the outcome.
-* @returns the uninstaller that removes the rejection handler.
+* @returns the uninstaller that removes both handlers.
 */
 function installFailLoud(binName, proc = process, release) {
 	let exiting = false;
-	const handler = (err) => {
-		if (assembledActivationRejections.has(err)) return;
+	const report = (err, label) => {
 		if (exiting) return;
 		exiting = true;
-		proc.stderr.write(`${binName}: fatal load failure: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+		proc.stderr.write(`${binName}: ${label}: ${inspect(err, {
+			depth: 4,
+			maxArrayLength: 50
+		})}\n`);
 		if (release === void 0) {
 			proc.exit(1);
 			return;
@@ -3413,8 +3786,19 @@ function installFailLoud(binName, proc = process, release) {
 			proc.exit(1);
 		})();
 	};
-	const uninstall = () => void proc.off("unhandledRejection", handler);
-	proc.on("unhandledRejection", handler);
+	const onRejection = (err) => {
+		if (assembledActivationRejections.has(err)) return;
+		report(err, "fatal load failure");
+	};
+	const onException = (err) => {
+		report(err, "fatal uncaught exception");
+	};
+	const uninstall = () => {
+		proc.off("unhandledRejection", onRejection);
+		proc.off("uncaughtException", onException);
+	};
+	proc.on("unhandledRejection", onRejection);
+	proc.on("uncaughtException", onException);
 	return uninstall;
 }
 /**
@@ -3679,7 +4063,7 @@ async function boot(binName, absoluteConfigPath, patches, prepare, bareModuleBas
 		await ctx.plugin(Loader);
 		await prepare?.(ctx);
 		stage = "plugin tree failed to load";
-		await mountRootInclude(ctx, absoluteConfigPath, patches, bareModuleBaseUrl);
+		await mountRootInclude(ctx, absoluteConfigPath, patches, bareModuleBaseUrl, binName);
 		await ctx.get("loader")?.await();
 		if (ctx.get("loader") === void 0) return ctx;
 		await auditStartupEntries(ctx, binName);
@@ -3733,4 +4117,4 @@ function addHarnessSourceSection(ctx, sourceRoot) {
 	});
 }
 //#endregion
-export { DEFAULT_PROFILE_BUNDLES, FAIL_LOUD_RELEASE_TIMEOUT_MS, HARNESS_SOURCE_SECTION, LOADER_EXPRESSION_SCHEMA, OPTIONAL_BUNDLES, PROFILES_DIR, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, StartupError, addHarnessSourceSection, auditStartupEntries, boot, bundlePatchFiles, bundlePatchPaths, composeEntries, createConfigProjector, createRuntimeResolution, generateConfigSchema, initProfile, installFailLoud, isNativeConfigSchema, loadEnv, loadLayeredEnv, loadOptionalPatches, loadOverlayPatches, loadProfile, loadProfileDirectory, mountRootInclude, readPluginMeta, readProfileManifest, readProfilePatches, readProfilePlugins, reconcileProfilePatches, reconcileProfilePlugins, removeLinkProjections, renderConfigDump, resolveBundleDir, resolveConfigPath, resolveProfileDir, resolveTelemetryPatch, sanitizeProfile, writeProfileBundles, writeProfileManifest };
+export { DEFAULT_PROFILE_BUNDLES, FAIL_LOUD_RELEASE_TIMEOUT_MS, HARNESS_SOURCE_SECTION, LOADER_EXPRESSION_SCHEMA, OPTIONAL_BUNDLES, PROFILES_DIR, PROFILE_COMPATIBILITY_FILENAME, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, StartupError, addHarnessSourceSection, auditStartupEntries, boot, bundlePatchFiles, bundlePatchPaths, composeEntries, createConfigProjector, createRuntimeResolution, evaluatePluginCompatibility, generateConfigSchema, getDshRuntimeVersion, initProfile, installFailLoud, isNativeConfigSchema, loadEnv, loadLayeredEnv, loadOptionalPatches, loadOverlayPatches, loadProfile, loadProfileDirectory, mountRootInclude, pluginCompatibilityWarning, prepareProfileEntries, prepareProfilePatches, readPluginMeta, readProfileCompatibility, readProfileManifest, readProfilePatches, readProfilePlugins, readProfileVersionExemptions, reconcileProfilePatches, reconcileProfilePlugins, removeLinkProjections, renderConfigDump, resolveBundleDir, resolveConfigPath, resolveProfileDir, resolveTelemetryPatch, sanitizeProfile, setProfileVersionExemption, writeProfileBundles, writeProfileManifest };

package/lib/types/compatibility-preflight.d.ts

@@ -0,0 +1,26 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader';
+import { type PatchOptions } from '@deepseek-ai/cordis-plugin-include';
+/** Prepare profile or preset rows before the owning DSH caller passes them to Loader.
+ * Only a compatibility conflict denies a row: an entry whose manifest cannot be resolved keeps
+ * the Loader's own import failure. A denied ordinary row gains `disabled`; a native Include that
+ * reaches a denied plugin is denied as a whole, because its file is never rewritten.
+ * @param ctx Context carrying launcher-owned profile facts; non-profile contexts retain their rows.
+ * @param entries Complete effective entry list, after patch composition.
+ * @param parentURL Resolution base of the tree that will import these rows.
+ * @param binName Diagnostic prefix for a denied row; defaults to `dsh`.
+ * @returns Detached rows with incompatible entries denied; reads the profile compatibility file once.
+ * @throws For malformed compatibility permissions or a profile composition without a resolution base.
+ */
+export declare function prepareProfileEntries(ctx: Context, entries: readonly EntryOptions[], parentURL: string | undefined, binName?: string): EntryOptions[];
+/** Apply compatibility policy to the complete patch composition over a profile's empty root.
+ * The caller passes every patch layer of the profile, because this returns one insertion patch for
+ * that empty root: a non-empty root config would lose the caller's override patches by id.
+ * @param ctx Profile context prepared by the launcher.
+ * @param patches Original ordered profile patches; these remain unchanged.
+ * @param parentURL Root Include's resolution base.
+ * @param binName Diagnostic prefix for a denied row; defaults to `dsh`.
+ * @returns One prepared insertion patch for profiles, or the original patches for non-profile callers.
+ */
+export declare function prepareProfilePatches(ctx: Context, patches: PatchOptions[], parentURL: string, binName?: string): PatchOptions[];
+//# sourceMappingURL=compatibility-preflight.d.ts.map

package/lib/types/index.d.ts

@@ -12,6 +12,9 @@ import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
 import { type LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment';
 export { 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 { prepareProfileEntries, prepareProfilePatches } from './compatibility-preflight.ts';
 export { readPluginMeta } from './package-meta.ts';
 export { generateConfigSchema, type ConfigSchemaDump, type NativeConfigSchema } from './config-schema/index.ts';
 export { createConfigProjector, LOADER_EXPRESSION_SCHEMA, type ConfigProjection } from './config-schema/projector.ts';
@@ -101,14 +104,15 @@ export interface ConfigDumpLayer {
     patches: PatchOptions[];
 }
 /**
- * Compose the effective entry list exactly as `boot()` would mount it: parse
- * the base config file with the include's entry-list dialect, apply every
- * layer's patches as ONE flattened list through the include's own patch
- * algorithm (`applyEntryPatches`) — the same single call `boot()` makes, so
- * even patch-visibility corner cases (a later layer targeting a group child a
- * plain config replacement introduced, which the single-pass id index never
- * sees) compose identically — then render the result as YAML in the same
- * dialect (`!!js` expressions print verbatim, unevaluated).
+ * Compose the configured entry list: parse the base config file with the
+ * include's entry-list dialect, apply every layer's patches as ONE flattened
+ * list through the include's own patch algorithm (`applyEntryPatches`) — the
+ * same call `boot()` makes, so even patch-visibility corner cases (a later
+ * layer targeting a group child a plain config replacement introduced, which
+ * the single-pass id index never sees) compose identically — then render the
+ * result as YAML in the same dialect (`!!js` expressions print verbatim,
+ * unevaluated). Row admission is a later stage: a plugin row the compatibility
+ * policy denies still appears here, while a denied bundle contributes no layer.
  *
  * Every run of rows from the same file and patch layers is preceded by a `# ==` comment
  * naming the file that contributed the rows and any layers that patched them,
@@ -139,18 +143,21 @@ export declare function renderConfigDump(binName: string, absoluteConfigPath: st
  * @param patches - initial app and user patches, applied in order.
  * @param bareModuleBaseUrl - optional installed-host base for bare package
  * names; relative names continue to resolve beside the configuration file.
+ * @param binName - diagnostic prefix for a profile plugin denied by compatibility policy; defaults to `dsh`.
  * @returns the created root Include entry, or `undefined` when a surface
  * disposed the whole tree (taking the Loader service with it) while the
  * entry creation was in flight.
  */
-export declare function mountRootInclude(ctx: Context, absoluteConfigPath: string, patches?: readonly PatchOptions[], bareModuleBaseUrl?: string): Promise<Entry | undefined>;
+export declare function mountRootInclude(ctx: Context, absoluteConfigPath: string, patches?: readonly PatchOptions[], bareModuleBaseUrl?: string, binName?: string): Promise<Entry | undefined>;
+/** The two process events {@link installFailLoud} turns into a fatal exit. */
+export type FailLoudEvent = 'unhandledRejection' | 'uncaughtException';
 /**
  * The slice of `process` {@link installFailLoud} needs — injectable so tests
  * exercise the handler without registering on (or exiting) the real process.
  */
 export interface FailLoudProcess {
-    on(event: 'unhandledRejection', handler: (err: unknown) => void): unknown;
-    off(event: 'unhandledRejection', handler: (err: unknown) => void): unknown;
+    on(event: FailLoudEvent, handler: (err: unknown) => void): unknown;
+    off(event: FailLoudEvent, handler: (err: unknown) => void): unknown;
     stderr: {
         write(chunk: string): unknown;
     };
@@ -167,11 +174,22 @@ export interface FailLoudProcess {
  */
 export declare const FAIL_LOUD_RELEASE_TIMEOUT_MS = 2000;
 /**
- * Install before boot to turn a late unhandled plugin-init rejection into one
- * labelled stderr diagnostic and `exit(1)`. A rejection already included by
- * {@link auditStartupEntries} is ignored during its process checkpoint;
- * every other rejection remains fatal. Stdout remains untouched for ACP; the
- * returned function removes the handler.
+ * Install before boot to turn an unhandled rejection or an uncaught exception,
+ * at any point in the process lifetime, into one labelled stderr diagnostic and
+ * `exit(1)`. A rejection already included by {@link auditStartupEntries} is
+ * ignored during its process checkpoint; every other rejection and every
+ * uncaught exception remains fatal. Control never returns to the failed
+ * operation after either: only the throw site knows which state is intact, and
+ * a listener that threw mid-update (a stream `'data'` handler, a half-applied
+ * registry write) leaves silently wrong results behind if it were resumed. The
+ * event loop keeps running only until the release hook settles or times out.
+ * Stdout remains untouched for ACP; the returned function removes both handlers.
+ *
+ * The diagnostic is `util.inspect(err)`, not `err.stack`: a `node:fs` error's
+ * `code`, `syscall`, and `path` and any `cause` chain are enumerable properties
+ * that the stack line omits, and they are what a crash report needs. Once a
+ * handler is installed Node prints nothing of its own, so this line is the
+ * only record of the failure.
  *
  * The Loader mounts entries concurrently, so a surface that owns the terminal
  * can already hold it when a sibling entry rejects. Exiting straight from the
@@ -193,7 +211,7 @@ export declare const FAIL_LOUD_RELEASE_TIMEOUT_MS = 2000;
  * @param release - optional teardown awaited before exit, used by a
  *   terminal-owning surface to restore the terminal. Its own failure is
  *   swallowed because the pending fatal exit already owns the outcome.
- * @returns the uninstaller that removes the rejection handler.
+ * @returns the uninstaller that removes both handlers.
  */
 export declare function installFailLoud(binName: string, proc?: FailLoudProcess, release?: () => Promise<void> | void): () => void;
 interface InactiveEntry {

package/lib/types/plugin-compatibility.d.ts

@@ -0,0 +1,35 @@
+/** Evaluate plugin dsh peer requirements without importing plugin code. */
+/** Incompatible dsh peers and the exact plugin/runtime exemption decision. */
+export interface PluginCompatibility {
+    name: string;
+    version: string;
+    runtimeVersion: string;
+    /** Only peer requirements not satisfied by the running dsh version. */
+    peers: Record<string, string>;
+    exempted: boolean;
+}
+/**
+ * Read this app-boot package's version in both source and bundled installations.
+ * @returns the validated runtime semantic version, preserving its exact spelling.
+ * @throws if package.json cannot be read or its version is missing or invalid.
+ */
+export declare function getDshRuntimeVersion(): string;
+/**
+ * Check every @deepseek-ai/dsh or @deepseek-ai/dsh-* peer against the runtime.
+ * Prereleases participate in ranges. workspace:^, workspace:~, and workspace:*
+ * refer to the current runtime; other invalid ranges are incompatible.
+ * @param manifest - parsed plugin package.json; inherited fields are ignored.
+ * @param exemptions - exact plugin name@version keys mapped to exact runtime versions.
+ * @param runtimeVersion - running dsh version, defaulting to this app-boot package.
+ * @returns incompatible peers and exemption status, or undefined when none are incompatible.
+ * @throws for malformed manifest peer fields, invalid runtime versions, or missing identity on a mismatch.
+ */
+export declare function evaluatePluginCompatibility(manifest: object, exemptions?: Readonly<Record<string, readonly string[]>>, runtimeVersion?: string): PluginCompatibility | undefined;
+/**
+ * Describe incompatible peers, their risk, and the exact-version remedy.
+ * Surfaces with their own grant mechanism or locale render the structured result themselves.
+ * @param issue - incompatible plugin/runtime result, including exempted mismatches.
+ * @returns an English diagnostic for logs and stderr.
+ */
+export declare function pluginCompatibilityWarning(issue: PluginCompatibility): string;
+//# sourceMappingURL=plugin-compatibility.d.ts.map

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

@@ -0,0 +1,50 @@
+/** Independent profile metadata; neither package manifests nor Cordis patches carry grants. */
+export declare const PROFILE_COMPATIBILITY_FILENAME = "compatibility.json";
+/** Test whether an exemption names a canonical exact SemVer, including build metadata.
+ * @param value Version supplied by a manifest or user.
+ * @returns False for ranges, prefixes, whitespace, and malformed versions.
+ */
+export declare function isExactPluginVersion(value: string): boolean;
+/** Validate one explicit exemption without granting it.
+ * @param packageVersion Exact npm package-name@version, never an installation spec or range.
+ * @param runtimeVersion Exact DSH version, including prerelease and build metadata.
+ * @throws When either identity is not canonical.
+ */
+export declare function validatePluginVersionExemption(packageVersion: string, runtimeVersion: string): void;
+/** What one profile's compatibility file currently authorizes, and what is wrong with it. */
+export interface ProfileCompatibility {
+    /** Accepted exact package-name@version keys mapped to their allowed DSH versions. */
+    readonly exemptions: Record<string, string[]>;
+    /** Human-readable problems; empty when every record was accepted. */
+    readonly warnings: string[];
+    /**
+     * Whether the file holds nothing this reader rejected, so a grant or revocation may rewrite it.
+     * A false value means writing would discard content the user must repair by hand.
+     */
+    readonly rewritable: boolean;
+}
+/** Read the profile's independent compatibility file without loading plugins.
+ * A missing file authorizes nothing. An unreadable or unparsable file authorizes nothing and is
+ * reported instead of failing, so a bad file can never make the profile unusable; rejected records
+ * are skipped while the remaining valid ones still apply.
+ * @param profileDir Absolute profile directory.
+ * @returns Accepted exemptions plus every problem found; no manifest fallback is used.
+ */
+export declare function readProfileCompatibility(profileDir: string): ProfileCompatibility;
+/** Read only the accepted exemptions of a profile.
+ * @param profileDir Absolute profile directory.
+ * @returns Exact package-name@version keys mapped to their allowed DSH versions.
+ */
+export declare function readProfileVersionExemptions(profileDir: string): Record<string, string[]>;
+/** Persist one informed grant or revocation under the compatibility file's own lock.
+ * @param profileDir Profile directory; no package manifest is created or modified.
+ * @param packageVersion Exact manifest package-name@version.
+ * @param runtimeVersion Exact DSH version; grants must name the current runtime, revocations may name historical ones.
+ * @param enabled Whether to grant rather than revoke.
+ * @param acceptRisk Required true for grants after explicit acknowledgement of possible crashes or data loss.
+ * @returns After the atomic write. Existing plugin instances are not reloaded by this operation.
+ * @throws For invalid identities, missing consent, a stale runtime, or a file the reader rejected,
+ * which the user must repair by hand because rewriting it would discard their content.
+ */
+export declare function setProfileVersionExemption(profileDir: string, packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk: boolean): Promise<void>;
+//# sourceMappingURL=profile-compatibility.d.ts.map

package/lib/types/profile.d.ts

@@ -196,7 +196,8 @@ export declare function resolveBundleDir(binName: string, packageName: string, i
  * Load an already initialized profile directory without resolving it through
  * the shared Harness home. This is used by application-owned profiles whose
  * package project and lifecycle belong to that application.
- * Unreadable bundles are reported on stderr and skipped without changing the manifest.
+ * Unreadable bundles, and bundles whose own dsh peers the profile does not exempt, are reported
+ * on stderr and skipped without changing the manifest.
  * @param binName - the diagnostic prefix on thrown errors.
  * @param dir - absolute profile package directory.
  * @param installAnchor - absolute path of the owning dsh app's package.json.
@@ -208,8 +209,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 bundles are reported
- * on stderr and skipped; profile manifest and user patch errors still throw.
+ * layer and parse the profile's own patch file. Unreadable or incompatible bundles
+ * are reported on stderr and skipped; 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/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.1.7-alpha.1",
+  "version": "0.1.7-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -37,27 +37,30 @@
     "js-yaml": "^4.2.0",
     "node-addon-require-builtin": "^0.1.6",
     "resolve.exports": "^2.0.3",
-    "@deepseek-ai/dsh-package-manifest": "^0.1.7-alpha.1"
+    "semver": "^7.8.5",
+    "@deepseek-ai/dsh-atomic-write": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-package-manifest": "0.1.7-rc.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis-plugin-include": "^1.0.8",
-    "@deepseek-ai/cordis-plugin-group": "^1.0.3",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.7-alpha.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.7-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.3",
-    "@deepseek-ai/dsh-home-paths": "^0.1.7-alpha.1",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.4"
+    "@deepseek-ai/cordis-plugin-include": "~1.0.9",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
+    "@deepseek-ai/dsh-launch-environment": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-home-paths": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.1",
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/cordis-plugin-group": "~1.0.4"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@deepseek-ai/schemastery": "^3.18.3",
-    "@deepseek-ai/cordis-plugin-group": "^1.0.3",
-    "@deepseek-ai/cordis-plugin-include": "^1.0.8",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.4",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.7-alpha.1",
-    "@deepseek-ai/cordis-plugin-timer": "^1.1.5",
-    "@deepseek-ai/dsh-home-paths": "^0.1.7-alpha.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.7-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.3"
+    "@types/semver": "^7.8.0",
+    "@deepseek-ai/schemastery": "~3.18.4",
+    "@deepseek-ai/cordis-plugin-group": "~1.0.4",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
+    "@deepseek-ai/cordis-plugin-timer": "~1.1.6",
+    "@deepseek-ai/dsh-launch-environment": "0.1.7-rc.1",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.9",
+    "@deepseek-ai/dsh-home-paths": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.1",
+    "@deepseek-ai/cordis": "~4.0.4"
   }
 }