feat: configure repository plugins from DSH home

packages/ui/app-boot/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/ui/app-boot/README.md
-README.md: e82d378f9cabd24d0f8b3069237f142c1885191f
-README.zh.md: 5d749531e48a502291491e6d047b45cd8a505544
+README.md: 2eb9e904d574df39b0884558fc0a53f9dc04cdc1
+README.zh.md: 78bd99943fcadebf42a5d772d49f3bfcf6a8790a

packages/ui/app-boot/README.md

@@ -13,6 +13,8 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 | `assertEntriesActivated(ctx, binName)` | Include the `assertEntriesLoaded` check, then await every enabled entry after the Loader settles; throw with each failed plugin's original stack or each pending plugin's unresolved services |
 | `loadPersonalPatches(binName, dir?)` | Parse the optional `config.yaml` in the Harness home (default [`resolveDshHome()`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws |
 | `loadOverlayPatches(binName, file)` | Parse a required patch-list file with the same shape as personal config; read or parse failures throw a labelled error |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | Mount the statically imported Include builtin and retain the exact root entry used by personal-config HMR |
+| `watchPersonalPatches(ctx, options)` | Register `$DSH_HOME/config.yaml` with the existing Cordis HMR service; each add/change/removal transactionally recomposes the full patch list through the caller's `compose` closure (app-owned layers around the current personal overlay) and returns an async disposer |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, expose `dshHomePath(...segments)` to Loader `!!js` config expressions, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots such as [`MAIN_SESSION_ID_KEY`](../tui/README.md)), then mount and await the include tree, assert entries loaded and activated, and return the root context — or dispose the partial context and reject a labelled error |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline — the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts — and render YAML with `!!js` expressions verbatim; each run of same-provenance rows is preceded by a `# ==` comment naming the contributing file and the layers that patched it, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), read/parse/shape failures throw |
 | `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to the DSH implementation checkout while warning it not to infer the current working directory from that path and to use `pwd` instead; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
@@ -26,11 +28,13 @@ This package carries no loader hooks and no dev-mode surface. The [`dsh` app](..
 
 ## Personal config
 
-A developer's machine-local preferences live outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves), consumed by the official `dsh` surfaces ([`apps/cli`](../../../apps/cli/README.md)); the demo bins boot their committed trees verbatim. Two optional files:
+A developer's machine-local preferences live outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves), consumed by the `dsh` CLI's TUI, Web, and headless surfaces ([`apps/cli`](../../../apps/cli/README.md)); the demo bins boot their committed trees verbatim. Two optional files:
 
 - **`.env`** — the credential store of [`dsh-credentials-local`](../../credentials/credentials-local/README.md), read by that provider alone. No surface hoists it into `process.env`: doing so would make every stored key look like a read-only launch override on the next run, blocking rotation from the TUI and the web page. The environment layers are the ambient one and the invoking directory's `.env` (loaded by the bin; `process.loadEnvFile` never overrides), and a composition without the credential provider keeps resolving keys from those alone.
 - **`config.yaml`** — loader overlay patches applied over the shipped default config, with the same semantics as the shipped surface overlays: an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount. A patch naming an entry id absent from the booted tree is a silent no-op. An empty or comments-only file throws (it parses to nothing, not to a list); disable the overlay with `[]` or by deleting the file.
 
+The TUI and Web keep `config.yaml` live through `watchPersonalPatches`; one-shot headless runs read only the startup value. The watcher targets the exact personal path even when the file or immediate parent does not exist, serializes bursts, and recomposes the personal patches inside the caller's layer order (surface overlay below, app-generated patches above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
+
 Subprocess test launchers point `DSH_HOME` at an isolated per-test directory so a developer's personal overlay can never leak into fixtures.
 
 ## Model Experience

packages/ui/app-boot/README.zh.md

@@ -13,6 +13,8 @@
 | `assertEntriesActivated(ctx, binName)` | 先执行 `assertEntriesLoaded` 检查，再在 Loader 结算后等待每个已启用配置项；抛出的错误包含每个失败插件的原始错误堆栈，或每个等待中插件尚未解析的服务 |
 | `loadPersonalPatches(binName, dir?)` | 解析 Harness home 中可选的 `config.yaml`（默认使用 [`resolveDshHome()`](../../util/paths/README.md)：先取 `$DSH_HOME`，否则取 `~/.dsh`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
 | `loadOverlayPatches(binName, file)` | 解析一份必需的 patch 列表文件，其形状与个人配置相同；读取或解析失败时抛出带标签的错误 |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 挂载静态导入的 Include builtin，并保留个人配置 HMR（热模块替换）使用的确切根配置项 |
+| `watchPersonalPatches(ctx, options)` | 向现有 Cordis HMR 服务注册 `$DSH_HOME/config.yaml`；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前个人 overlay）以事务方式重新组合完整 patch 列表，并返回异步 disposer |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽，例如 [`MAIN_SESSION_ID_KEY`](../tui/README.md)），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
@@ -26,11 +28,13 @@ Loader 结算会在导入或生命周期失败时 reject，并携带失败的配
 
 ## 个人配置
 
-开发者的机器本地偏好位于所有仓库之外的 Harness home 中（默认 `~/.dsh`，可由 `$DSH_HOME` 覆盖；统一由根级 [`resolveDshHome`](../../util/paths/README.md) 解析），并由官方 `dsh` 界面（[`apps/cli`](../../../apps/cli/README.md)）使用；demo bin 会原样启动仓库中提交的树。这里有两个可选文件：
+开发者的机器本地偏好位于所有仓库之外的 Harness home 中（默认 `~/.dsh`，可由 `$DSH_HOME` 覆盖；统一由根级 [`resolveDshHome`](../../util/paths/README.md) 解析），并由 `dsh` CLI（命令行界面）的 TUI、Web 和无头界面（[`apps/cli`](../../../apps/cli/README.md)）使用；demo bin 会原样启动仓库中提交的树。这里有两个可选文件：
 
 - **`.env`**：[`dsh-credentials-local`](../../credentials/credentials-local/README.md) 的凭据存储，只由该 provider 读取。没有任何表层会把它提升进 `process.env`：那样做会让每个已存密钥在下次运行时看起来都像只读的启动时覆盖，从而阻断从 TUI 与 Web 页面轮换密钥。环境层次由环境中的值与调用目录的 `.env` 构成（由 bin 加载；`process.loadEnvFile` 从不覆盖已有值），没有凭据 provider 的组合仍然只从这两者解析密钥。
 - **`config.yaml`**：在发布的默认配置上应用 Loader overlay patch，语义与交付的 surface overlay 相同：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在已启动树中，则静默不执行任何操作。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用 overlay，请使用 `[]` 或删除该文件。
 
+TUI 和 Web 会持续应用 `config.yaml` 的变更，具体由 `watchPersonalPatches` 负责；一次性无头运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切的个人配置路径；它会串行处理突发变更，并按调用方的层次顺序重新组合个人 patch（surface overlay 在下、应用生成的 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
+
 子进程测试 launcher 会把 `DSH_HOME` 指向逐测试隔离的目录，确保开发者的个人 overlay 不会泄漏到 fixture（测试前置数据）中。
 
 ## 模型体验

packages/ui/app-boot/package.json

@@ -30,6 +30,7 @@
     "js-yaml": "^4.2.0"
   },
   "peerDependencies": {
+    "@cordisjs/plugin-hmr": "^1.0.15",
     "@cordisjs/plugin-include": "^1.0.4",
     "@cordisjs/plugin-loader": "^1.0.0-rc.5",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
@@ -37,6 +38,11 @@
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "peerDependenciesMeta": {
+    "@cordisjs/plugin-hmr": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@cordisjs/plugin-hmr": "workspace:^",
     "@cordisjs/plugin-include": "workspace:^",

packages/ui/app-boot/src/index.ts

@@ -11,9 +11,10 @@ import { readFileSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
 import { Context, type FiberState } from 'cordis'
-import Loader, { type EntryOptions } from '@cordisjs/plugin-loader'
+import Loader, { type Entry, type EntryOptions } from '@cordisjs/plugin-loader'
 import Include, { applyEntryPatches, entryListSchema, type PatchOptions } from '@cordisjs/plugin-include'
 import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-paths'
+import type {} from '@cordisjs/plugin-hmr'
 // Side-effect type import: resolves `ctx.get('systemPrompt')` to the service.
 import type {} from '@deepseek-ai/dsh-system-prompt'
 
@@ -67,6 +68,8 @@ export function loadEnv(
 /** File inside the Harness home holding the personal loader overlay patches. */
 export const PERSONAL_CONFIG_FILENAME = 'config.yaml'
 
+const bootstrapIncludes = new WeakMap<Context, Entry>()
+
 // The include's YAML dialect (`!!js` scalars become expression nodes the
 // Loader interpolates against each entry's context at mount time), imported
 // from the include itself so patch parsing and config dumping can never drift
@@ -287,6 +290,86 @@ function groupedDump(
   return lines.join('\n') + '\n'
 }
 
+/** Options for live personal-config reconciliation. */
+export interface PersonalPatchWatchOptions {
+  /** Diagnostic prefix used by {@link loadPersonalPatches}. */
+  binName: string
+  /** Harness home containing `config.yaml`; defaults to {@link resolveDshHome}. */
+  dir?: string
+  /**
+   * Compose the full patch list for a fresh personal-overlay generation —
+   * the same composition the app booted with, so a reload can interleave the
+   * new personal patches between app-owned layers (surface overlay below,
+   * profile/flag patches above). Identity when omitted: the personal overlay
+   * is the whole patch list.
+   */
+  compose?: (personalPatches: PatchOptions[]) => PatchOptions[]
+}
+
+/**
+ * Watch the personal overlay through Cordis HMR and transactionally reapply it to the boot include.
+ * @param ctx - settled app context containing the root Include and an active HMR service.
+ * @param options - diagnostic, Harness-home, and patch-composition inputs.
+ * @returns an asynchronous disposer after the exact-path watcher is ready.
+ * @throws when HMR or the root Include is absent, watcher setup fails, or initial path resolution fails.
+ */
+export async function watchPersonalPatches(
+  ctx: Context,
+  options: PersonalPatchWatchOptions,
+): Promise<() => Promise<void>> {
+  const { binName, dir = resolveDshHome(), compose = (patches: PatchOptions[]) => patches } = options
+  const hmr = ctx.get('hmr')
+  if (hmr === undefined) throw new Error(`${binName}: personal config watching requires the Cordis HMR service`)
+  const entry = bootstrapIncludes.get(ctx)
+  if (entry === undefined) throw new Error(`${binName}: personal config watching requires the root Include entry`)
+  const filename = join(dir, PERSONAL_CONFIG_FILENAME)
+  const { patches: _initialPatches, ...includeConfig } = entry.options.config as Include.Config
+  return hmr.registerConfig(filename, async () => {
+    const personalPatches = loadPersonalPatches(binName, dir) ?? []
+    const patches = compose(personalPatches)
+    await entry.update({
+      config: {
+        ...includeConfig,
+        patches,
+      },
+    })
+  })
+}
+
+/**
+ * Mount and remember the exact root Include entry used by app boot and personal-config HMR.
+ * @param ctx - context carrying an initialized Loader service.
+ * @param absoluteConfigPath - absolute YAML or JSON configuration path.
+ * @param patches - initial app and personal patches, applied in order.
+ * @returns the created root Include entry, or `undefined` when a surface
+ * disposed the whole tree (taking the Loader service with it) while the
+ * transactional create was still settling entry lifecycle.
+ */
+export async function mountRootInclude(
+  ctx: Context,
+  absoluteConfigPath: string,
+  patches: readonly PatchOptions[] = [],
+): Promise<Entry | undefined> {
+  ctx.loader.builtins.include = Include
+  // Pinned id: the bootstrap include is app glue, not a config row, and its
+  // id appears in Loader failure chains — a random id would make startup
+  // diagnostics unstable across runs (and snapshot fixtures).
+  const rootInclude: EntryOptions = {
+    id: 'include',
+    name: 'cordis:include',
+    config: {
+      path: pathToFileURL(absoluteConfigPath).href,
+      ...patches.length > 0 ? { patches: [...patches] } : {},
+    },
+  }
+  const includeId = await ctx.loader.create(rootInclude)
+  const loader = ctx.get('loader')
+  if (loader === undefined) return undefined
+  const entry = loader.resolve(includeId)
+  bootstrapIncludes.set(ctx, entry)
+  return entry
+}
+
 /**
  * The slice of `process` {@link installFailLoud} needs — injectable so tests
  * exercise the handler without registering on (or exiting) the real process.
@@ -463,21 +546,9 @@ export async function boot(
     ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
     ctx.provide('dshHomePath', dshHomePath)
     await ctx.plugin(Loader)
-    ctx.loader.builtins.include = Include
     await prepare?.(ctx)
     stage = 'plugin tree failed to load'
-    // Pinned id: the bootstrap include is app glue, not a config row, and its
-    // id appears in Loader failure chains — a random id would make startup
-    // diagnostics unstable across runs (and snapshot fixtures).
-    const rootInclude: EntryOptions = {
-      id: 'include',
-      name: 'cordis:include',
-      config: {
-        path: pathToFileURL(absoluteConfigPath).href,
-        ...patches !== undefined && patches.length > 0 ? { patches } : {},
-      },
-    }
-    await ctx.loader.create(rootInclude)
+    await mountRootInclude(ctx, absoluteConfigPath, patches)
     // A surface can finish and dispose the whole tree while startup is still
     // in flight: the TUI renders as soon as its own fiber starts, so an `/exit`
     // typed before the last entry settles tears the context down under us. The

packages/ui/app-boot/tests/personal-config.spec.ts

@@ -4,21 +4,36 @@
  * a real Loader tree.
  */
 
-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, unlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
-import type { Context } from 'cordis'
+import { Context } from 'cordis'
+import Hmr from '@cordisjs/plugin-hmr'
+import Loader from '@cordisjs/plugin-loader'
+import Timer from '@cordisjs/plugin-timer'
 import {
   boot,
   loadPersonalPatches,
   PERSONAL_CONFIG_FILENAME,
+  watchPersonalPatches,
 } from '../src/index.ts'
 
 const NAME = 'dsh-test-bin'
 
 const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-personal-config-'))
 
+async function eventually(test: () => boolean, message: string): Promise<void> {
+  const deadline = Date.now() + 10_000
+  while (!test()) {
+    if (Date.now() >= deadline) throw new Error(message)
+    await new Promise(resolve => setTimeout(resolve, 10))
+  }
+}
+
+const settleChokidarChangeThrottle = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 75))
+
 describe('loadPersonalPatches', () => {
   afterEach(() => {
     delete process.env.DSH_HOME
@@ -86,7 +101,13 @@ describe('loadPersonalPatches', () => {
 
 describe('boot with personal patches', () => {
   function writeTree(dir: string): string {
-    writeFileSync(join(dir, 'noop.mjs'), 'export const name = "noop"\nexport function apply() {}\n')
+    writeFileSync(join(dir, 'noop.mjs'), [
+      'export const name = "noop"',
+      'export function apply(_ctx, config = {}) {',
+      '  if (config.fail) throw new Error("candidate config failed")',
+      '}',
+      '',
+    ].join('\n'))
     writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: base\n')
     return join(dir, 'cordis.yml')
   }
@@ -138,4 +159,78 @@ describe('boot with personal patches', () => {
       await ctxEmpty.fiber.dispose()
     }
   })
+
+  it('watches add, failure, recovery, and removal through transactional HMR', { timeout: 20_000 }, async () => {
+    const dir = tmp()
+    const personal = tmp()
+    const filename = join(personal, PERSONAL_CONFIG_FILENAME)
+    const basePatches = [{ id: 'noop', config: { value: 'generated' } }]
+    const ctx = await boot(NAME, writeTree(dir), basePatches)
+    await ctx.plugin(Timer)
+    await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+    const failures: Array<{ filename: string; error: Error }> = []
+    ctx.on('hmr/config-update-failed', (failedFilename, error) => {
+      failures.push({ filename: failedFilename, error })
+    })
+    const dispose = await watchPersonalPatches(ctx, {
+      binName: NAME,
+      dir: personal,
+      compose: personalPatches => [...basePatches, ...personalPatches],
+    })
+    try {
+      writeFileSync(filename, '- id: noop\n  config:\n    value: live\n')
+      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'live', 'personal config addition was not applied')
+
+      writeFileSync(filename, '- id: noop\n  config:\n    fail: true\n')
+      await eventually(() => failures.length === 1, 'failed candidate was not broadcast')
+      expect(failures[0]).toMatchObject({ filename })
+      expect(failures[0]?.error).toBeInstanceOf(Error)
+      expect((entryConfig(ctx, 'noop') as { value?: string }).value).toBe('live')
+      await settleChokidarChangeThrottle()
+
+      writeFileSync(filename, 'invalid: [unclosed\n')
+      await eventually(() => failures.length === 2, 'parse failure was not broadcast')
+      expect(failures[1]?.error).toBeInstanceOf(Error)
+      expect((entryConfig(ctx, 'noop') as { value?: string }).value).toBe('live')
+      await settleChokidarChangeThrottle()
+
+      writeFileSync(filename, '- id: noop\n  config:\n    value: recovered\n')
+      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'recovered', 'valid recovery was not applied')
+      await settleChokidarChangeThrottle()
+
+      unlinkSync(filename)
+      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'generated', 'personal config removal did not restore the app-owned patch')
+      expect(failures).toHaveLength(2)
+      await settleChokidarChangeThrottle()
+
+      // Default compose: the personal overlay IS the whole patch list, so a
+      // fresh generation replaces the app-owned layer instead of stacking on it.
+      await dispose()
+      const disposeDefault = await watchPersonalPatches(ctx, { binName: NAME, dir: personal })
+      try {
+        writeFileSync(filename, '- id: noop\n  config:\n    value: identity\n')
+        await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'identity', 'default-compose personal patch was not applied')
+      } finally {
+        await disposeDefault()
+      }
+    } finally {
+      await dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('fails loud when the exact watcher lacks HMR or a root Include', async () => {
+    const dir = tmp()
+    const withoutHmr = await boot(NAME, writeTree(dir))
+    await expect(watchPersonalPatches(withoutHmr, { binName: NAME, dir: tmp() })).rejects.toThrow('requires the Cordis HMR service')
+    await withoutHmr.fiber.dispose()
+
+    const withoutInclude = new Context()
+    withoutInclude.baseUrl = pathToFileURL(`${tmp()}/`).href
+    await withoutInclude.plugin(Loader)
+    await withoutInclude.plugin(Timer)
+    await withoutInclude.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+    await expect(watchPersonalPatches(withoutInclude, { binName: NAME, dir: tmp() })).rejects.toThrow('requires the root Include entry')
+    await withoutInclude.fiber.dispose()
+  })
 })

packages/ui/app-boot/tests/repository-cache.spec.ts

@@ -112,17 +112,27 @@ describe('RepositoryCache', () => {
     await expect(cache.resolve(specifier)).rejects.toThrow('repository cache marker is invalid')
   })
 
-  it('runs a Git dependency prepare script through the bundled pnpm', { timeout: 60_000 }, async () => {
+  it('selects and prepares a root .dsh-plugin Git subpath through the bundled pnpm', { timeout: 60_000 }, async () => {
     const root = await temporaryRoot('repository-pnpm')
     const repository = join(root, 'source')
-    await mkdir(repository)
+    await mkdir(join(repository, '.dsh-plugin'), { recursive: true })
+    await mkdir(join(repository, 'skills', 'fixture'), { recursive: true })
     await writeFile(join(repository, 'package.json'), `${JSON.stringify({
       name: 'repository-fixture',
       version: '1.0.0',
-      scripts: { prepare: 'node prepare.mjs' },
     })}\n`)
-    await writeFile(join(repository, 'prepare.mjs'), [
-      "import { writeFile } from 'node:fs/promises'",
+    await writeFile(join(repository, 'skills', 'fixture', 'SKILL.md'), 'repository skill source\n')
+    await writeFile(join(repository, '.dsh-plugin', 'package.json'), `${JSON.stringify({
+      name: 'repository-plugin-fixture',
+      version: '1.0.0',
+      scripts: { prepare: 'node prepare.mjs' },
+      dsh: { skills: ['../skills'] },
+    })}\n`)
+    await writeFile(join(repository, '.dsh-plugin', 'prepare.mjs'), [
+      "import { cp, mkdir, writeFile } from 'node:fs/promises'",
+      "await mkdir('dsh-plugin-assets/skills', { recursive: true })",
+      "await cp('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
+      "await writeFile('dsh-plugin.mjs', 'export function apply() {}\\n')",
       "await writeFile('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
       '',
     ].join('\n'))
@@ -134,11 +144,16 @@ describe('RepositoryCache', () => {
       'commit', '--quiet', '-m', 'fixture',
     ], { cwd: repository })
     const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repository, encoding: 'utf8' })
-    const specifier = `git+${pathToFileURL(repository).href}#${stdout.trim()}`
+    const specifier = `git+${pathToFileURL(repository).href}#${stdout.trim()}&path:/.dsh-plugin`
     vi.stubEnv('REPOSITORY_TEST_VISIBLE', 'visible')
     vi.stubEnv('REPOSITORY_TEST_TOKEN', 'hidden')
 
     const installed = await new RepositoryCache(join(root, 'cache')).resolve(specifier)
     await expect(readFile(join(installed, 'prepared.txt'), 'utf8')).resolves.toBe('visible|absent\n')
+    await expect(readFile(join(installed, 'dsh-plugin.mjs'), 'utf8')).resolves.toContain('export function apply')
+    await expect(readFile(join(installed, 'dsh-plugin-assets/skills/0/fixture/SKILL.md'), 'utf8'))
+      .resolves.toBe('repository skill source\n')
+    await expect(readFile(join(installed, 'package.json'), 'utf8'))
+      .resolves.toContain('repository-plugin-fixture')
   })
 })

packages/ui/app-boot/tsconfig.json

@@ -17,6 +17,9 @@
     {
       "path": "../../../vendor/include"
     },
+    {
+      "path": "../../../vendor/hmr"
+    },
     {
       "path": "../../support/invariants"
     },