feat: configure repository plugins from DSH home

2026-07-30 06:00:53 +08:00
parent 0664b25cd9
commit 2448496803
40 changed files with 783 additions and 76 deletions
--- a/packages/cordis/repository-plugin/README.i18n.yaml
+++ b/packages/cordis/repository-plugin/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/cordis/repository-plugin/README.md
-README.md: 80744eb489d1714f59ba6e53207476a8ce222e24
-README.zh.md: d297b44e4a065fa99865e3a42d2c823c7b7c5848
+README.md: 0ba1ce86d99a12e0f94e7a39fd3ae44dc29889a7
+README.zh.md: 2d9544166eafbb1066b65031969925890f2b9797
--- a/packages/cordis/repository-plugin/README.md
+++ b/packages/cordis/repository-plugin/README.md
@@ -28,6 +28,23 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:

 `dsh.skills` is an optional array of local skill roots. `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one field is required. Paths are relative to `.dsh-plugin`, must stay under its parent source directory, and may therefore refer to existing repository assets such as `../skills`. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.

+## Standalone app configuration
+
+The shipped `dsh` TUI, Web, and headless trees contain an empty `repository-plugins` row. A standalone user enables exact GitHub generations by replacing that row's config in `$DSH_HOME/config.yaml` (default `~/.dsh/config.yaml`):
+
+```yaml
+- id: repository-plugins
+  name: '@deepseek-ai/dsh-repository-plugin'
+  config:
+    repositories:
+      - 'github:PolyArch/humanize#<commit>'
+      - 'github:owner/repository#<ref>&path:/plugins/one/.dsh-plugin'
+```
+
+Each source must use `github:owner/repository#<ref>`. Omitting `&path:` selects `/.dsh-plugin`; an explicit path is absolute within the repository and must end in `.dsh-plugin`. A commit ref gives the clearest immutable identity, while tags and branches remain accepted exact config values. `cacheDir` may override the default `$DSH_HOME/cache/repository-plugins` cache root.
+
+The TUI and Web watch `config.yaml` through Cordis HMR. A valid source-list change installs and swaps the complete repository Plugin generation; a failed fetch, prepare, import, or Plugin application keeps the last good tree and broadcasts `hmr/config-update-failed(filename, error)`. Headless runs consume the file only at startup. An identical source string permanently reuses its prepared cache entry, so selecting changed code requires a ref, path, or other source-config change. App integration rationale: [config-only repository Plugins Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md).
+
 ## Preparation

 `dsh-plugin-prepare` validates `package.json#dsh`, verifies skill-root types, parses the MCP file, copies assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. The wrapper contains only the normalized static manifest and fixed code that looks up the `dsh-repository-plugin` Loader builtin. It neither discovers nor compiles repository JavaScript, and the runtime never imports another repository entry point.
--- a/packages/cordis/repository-plugin/README.zh.md
+++ b/packages/cordis/repository-plugin/README.zh.md
@@ -28,6 +28,23 @@

 `dsh.skills` 是可选的本地 skill 根数组。`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；两者至少声明一个。路径相对于 `.dsh-plugin`，必须留在其父级源码目录下，因此可以引用 `../skills` 等仓库现有资源。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` package。

+## 独立应用配置
+
+已交付的 `dsh` TUI、Web 和无头配置树包含一个空的 `repository-plugins` 配置项。独立用户只需在 `$DSH_HOME/config.yaml`（默认 `~/.dsh/config.yaml`）中替换该配置项的配置，即可启用精确指定的 GitHub generation：
+
+```yaml
+- id: repository-plugins
+  name: '@deepseek-ai/dsh-repository-plugin'
+  config:
+    repositories:
+      - 'github:PolyArch/humanize#<commit>'
+      - 'github:owner/repository#<ref>&path:/plugins/one/.dsh-plugin'
+```
+
+每个源都必须采用 `github:owner/repository#<ref>`。省略 `&path:` 时选择 `/.dsh-plugin`；显式路径是仓库内的绝对路径，并且必须以 `.dsh-plugin` 结尾。commit ref 提供最清晰的不可变身份；tag 和 branch 仍可作为显式配置值使用。`cacheDir` 可覆盖默认缓存根 `$DSH_HOME/cache/repository-plugins`。
+
+TUI 和 Web 通过 Cordis HMR（热模块替换）监视 `config.yaml`。有效的源列表变更会安装并替换整套仓库插件 generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。无头运行只在启动时使用该文件。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入仓库插件的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
+
 ## 准备阶段

 `dsh-plugin-prepare` 校验 `package.json#dsh`、确认 skill 根类型、解析 MCP 文件、把资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。包装模块只包含规范化后的静态 manifest（元数据清单），以及查找 `dsh-repository-plugin` Loader builtin 的固定代码；它不会发现或编译仓库 JavaScript，运行时也不会导入仓库的其他入口。
--- a/packages/cordis/repository-plugin/package.json
+++ b/packages/cordis/repository-plugin/package.json
@@ -34,6 +34,7 @@
    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-mcp-client": "^0.0.1",
+    "@deepseek-ai/dsh-paths": "^0.0.1",
    "@deepseek-ai/dsh-skill-local": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
@@ -44,6 +45,7 @@
    "@cordisjs/plugin-loader": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-mcp-client": "workspace:^",
+    "@deepseek-ai/dsh-paths": "workspace:^",
    "@deepseek-ai/dsh-skill": "workspace:^",
    "@deepseek-ai/dsh-skill-local": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
--- a/packages/cordis/repository-plugin/src/index.ts
+++ b/packages/cordis/repository-plugin/src/index.ts
@@ -8,8 +8,10 @@ import { dirname, isAbsolute, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { Context } from 'cordis'
 import type {} from '@cordisjs/plugin-loader'
+import { RepositoryCache } from '@cordisjs/plugin-loader/repository'
 import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import * as McpClient from '@deepseek-ai/dsh-mcp-client'
+import { z } from 'zod'
 import {
  REPOSITORY_PLUGIN_BUILTIN,
  isOutside,
@@ -17,6 +19,11 @@ import {
  type PreparedPluginConfig,
 } from './format.ts'
 import { parseMcpDocument, resolveMcpServers } from './mcp.ts'
+import {
+  loadPreparedRepository,
+  resolveRepositoryCacheDirectory,
+  resolveRepositorySpecifier,
+} from './source.ts'

 export {
  PREPARED_ASSET_DIRECTORY,
@@ -31,6 +38,19 @@ export const name = 'repository-plugin'
 /** Loader service required to register the fixed prepared-wrapper builtin. */
 export const inject = ['loader']

+/** Repository Plugin runtime and source-list configuration. */
+export interface Config {
+  /** GitHub repository sources with explicit refs and optional `.dsh-plugin` subpaths. */
+  repositories?: string[]
+  /** Persistent generation cache; defaults to `$DSH_HOME/cache/repository-plugins`. */
+  cacheDir?: string
+}
+
+export const Config = z.object({
+  repositories: z.array(z.string().min(1)).default([]),
+  cacheDir: z.string().min(1).optional(),
+}).strict().default({ repositories: [] })
+
 function preparedPath(baseUrl: string, configured: string): string {
  if (isAbsolute(configured)) throw new Error(`prepared DSH plugin path must be relative: ${JSON.stringify(configured)}`)
  const directory = dirname(fileURLToPath(baseUrl))
@@ -101,16 +121,25 @@ const preparedRuntime = {
 * Register the DSH-owned runtime as the Loader builtin used by fixed prepared wrappers.
 * @param ctx - plugin context carrying the Loader service.
 */
-export function apply(ctx: Context): void {
+export async function apply(ctx: Context, config: Config = {}): Promise<void> {
  if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] !== undefined) {
    throw new Error(`Loader builtin ${REPOSITORY_PLUGIN_BUILTIN} is already registered`)
  }
-  ctx.effect(function* () {
+  const repositories = (config.repositories ?? []).map(resolveRepositorySpecifier)
+  if (new Set(repositories).size !== repositories.length) {
+    throw new Error('repository sources must resolve to unique exact specifiers')
+  }
+  const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir))
+  await ctx.effect(async function* () {
    ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
    yield () => {
      if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
        Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
      }
    }
-  }, 'repository-plugin Loader builtin')
+    for (const repository of repositories) {
+      const plugin = await loadPreparedRepository(ctx, cache, repository)
+      yield plugin.dispose
+    }
+  }, 'repository-plugin runtime and sources')
 }
--- a/packages/cordis/repository-plugin/src/source.ts
+++ b/packages/cordis/repository-plugin/src/source.ts
@@ -0,0 +1,74 @@
+/**
+ * GitHub repository source validation and prepared-wrapper loading.
+ * @module
+ */
+
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Context, Fiber, Plugin } from 'cordis'
+import type { RepositoryCache } from '@cordisjs/plugin-loader/repository'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { PREPARED_ENTRY_FILENAME } from './format.ts'
+
+/** Directory under the Harness home containing immutable repository generations. */
+export const DEFAULT_REPOSITORY_CACHE_DIRECTORY = 'repository-plugins'
+
+const GITHUB_SOURCE_PATTERN = /^github:([^/\s#&]+)\/([^/\s#&]+)#([^\s&]+)(?:&path:(\/[^\s&]+))?$/
+
+function validPluginPath(path: string): boolean {
+  const segments = path.split('/').slice(1)
+  return segments.length > 0
+    && segments.at(-1) === '.dsh-plugin'
+    && segments.every(segment => segment.length > 0 && segment !== '.' && segment !== '..')
+}
+
+/**
+ * Normalize one user-facing GitHub source to the exact pnpm dependency specifier.
+ * @param configured - `github:owner/repo#ref` with an optional `&path:/.../.dsh-plugin`.
+ * @returns the exact specifier, with the root `.dsh-plugin` subpath added when omitted.
+ * @throws when the GitHub owner, repository, explicit ref, or plugin subpath is invalid.
+ */
+export function resolveRepositorySpecifier(configured: string): string {
+  const match = GITHUB_SOURCE_PATTERN.exec(configured)
+  if (match === null) {
+    throw new Error(`repository source must use github:owner/repo#<ref> with an optional &path:/.../.dsh-plugin: ${JSON.stringify(configured)}`)
+  }
+  const path = match[4]
+  if (path !== undefined && !validPluginPath(path)) {
+    throw new Error(`repository source path must be an absolute repository subpath ending in .dsh-plugin without empty, . or .. segments: ${JSON.stringify(path)}`)
+  }
+  return path === undefined ? `${configured}&path:/.dsh-plugin` : configured
+}
+
+/**
+ * Resolve the persistent repository cache root.
+ * @param configured - explicit cache directory, or undefined for `$DSH_HOME/cache/repository-plugins`.
+ * @returns an absolute cache directory.
+ */
+export function resolveRepositoryCacheDirectory(configured: string | undefined): string {
+  return resolve(configured ?? join(resolveDshHome(), 'cache', DEFAULT_REPOSITORY_CACHE_DIRECTORY))
+}
+
+/**
+ * Load one exact repository generation's generated wrapper as a child Cordis fiber.
+ * @param ctx - repository runtime context that owns the child.
+ * @param cache - package-manager-native immutable repository cache.
+ * @param specifier - normalized exact pnpm dependency specifier.
+ * @returns the settled prepared-wrapper fiber.
+ * @throws when installation, wrapper import, manifest validation, or child registration fails.
+ */
+export async function loadPreparedRepository(
+  ctx: Context,
+  cache: Pick<RepositoryCache, 'resolve'>,
+  specifier: string,
+): Promise<Fiber> {
+  const directory = await cache.resolve(specifier)
+  const filename = join(directory, PREPARED_ENTRY_FILENAME)
+  try {
+    const plugin = await import(/* @vite-ignore */pathToFileURL(filename).href) as Plugin
+    const fiber = ctx.plugin(plugin)
+    return await fiber
+  } catch (cause) {
+    throw new Error(`failed to load prepared repository Plugin ${JSON.stringify(specifier)} from ${filename}`, { cause })
+  }
+}
--- a/packages/cordis/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/cordis/repository-plugin/tests/repository-plugin.spec.ts
@@ -2,9 +2,10 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
+import { RepositoryCache } from '@cordisjs/plugin-loader/repository'
 import SkillService from '@deepseek-ai/dsh-skill'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -12,6 +13,11 @@ import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as RepositoryPlugin from '@deepseek-ai/dsh-repository-plugin'
 import * as RepositoryPluginInvariant from '@deepseek-ai/dsh-repository-plugin/invariant'
 import { parsePreparedPluginConfig } from '../src/format.ts'
+import {
+  loadPreparedRepository,
+  resolveRepositoryCacheDirectory,
+  resolveRepositorySpecifier,
+} from '../src/source.ts'

 const roots: string[] = []

@@ -35,6 +41,8 @@ async function writeSkill(root: string, name: string): Promise<void> {
 }

 afterEach(async () => {
+  vi.restoreAllMocks()
+  vi.unstubAllEnvs()
  await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true })))
 })

@@ -253,7 +261,7 @@ describe('prepared repository plugin Loader composition', () => {
    await ctx.plugin(Loader)
    const registrar = ctx.plugin(RepositoryPlugin)
    await registrar
-    expect(() => { RepositoryPlugin.apply(ctx) }).toThrow('already registered')
+    await expect(RepositoryPlugin.apply(ctx)).rejects.toThrow('already registered')

    const replacement = { name: 'replacement', apply() {} }
    ctx.loader.builtins[RepositoryPlugin.REPOSITORY_PLUGIN_BUILTIN] = replacement
@@ -263,6 +271,113 @@ describe('prepared repository plugin Loader composition', () => {
  })
 })

+describe('configured GitHub repository sources', () => {
+  it('defaults an omitted source list and rejects unknown configuration fields', () => {
+    expect(RepositoryPlugin.Config.parse(undefined)).toEqual({ repositories: [] })
+    expect(RepositoryPlugin.Config.safeParse({ repositories: [], unexpected: true }).success).toBe(false)
+  })
+
+  it('accepts an empty direct-apply config', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Loader)
+    await RepositoryPlugin.apply(ctx, {})
+    expect(ctx.loader.builtins[RepositoryPlugin.REPOSITORY_PLUGIN_BUILTIN]).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('adds the root plugin subpath and preserves an explicit nested plugin subpath', () => {
+    expect(resolveRepositorySpecifier('github:PolyArch/humanize#v1.0.0'))
+      .toBe('github:PolyArch/humanize#v1.0.0&path:/.dsh-plugin')
+    expect(resolveRepositorySpecifier('github:owner/repository#feature/ref&path:/plugins/one/.dsh-plugin'))
+      .toBe('github:owner/repository#feature/ref&path:/plugins/one/.dsh-plugin')
+  })
+
+  it('rejects absent refs and invalid plugin subpaths', () => {
+    for (const source of [
+      'github:owner/repository',
+      'github:owner/repository#',
+      'https://github.com/owner/repository#ref',
+      'github:owner/repository#ref&path:relative/.dsh-plugin',
+    ]) {
+      expect(() => resolveRepositorySpecifier(source)).toThrow('must use github:owner/repo#<ref>')
+    }
+    for (const path of [
+      '/plugins//.dsh-plugin',
+      '/plugins/../.dsh-plugin',
+      '/plugins/./.dsh-plugin',
+      '/plugins/not-a-plugin',
+    ]) {
+      expect(() => resolveRepositorySpecifier(`github:owner/repository#ref&path:${path}`))
+        .toThrow('path must be an absolute repository subpath')
+    }
+  })
+
+  it('resolves the default cache under DSH_HOME and an explicit cache absolutely', async () => {
+    const root = await temporaryDirectory('cache-root')
+    vi.stubEnv('DSH_HOME', root)
+    expect(resolveRepositoryCacheDirectory(undefined)).toBe(join(root, 'cache', 'repository-plugins'))
+    expect(resolveRepositoryCacheDirectory(join(root, 'explicit'))).toBe(join(root, 'explicit'))
+  })
+
+  it('loads a configured source through the immutable cache and removes its skill on teardown', async () => {
+    const root = await temporaryDirectory('configured-source')
+    await writeSkill(join(root, 'skills'), 'configured-repository-skill')
+    const directory = await writePlugin(root, 'configured-source-fixture', { skills: ['../skills'] })
+    await RepositoryPlugin.prepareDshPlugin(directory)
+    const resolved: string[] = []
+    const cacheDirectory = join(root, 'cache')
+    vi.spyOn(RepositoryCache.prototype, 'resolve').mockImplementation(async function (this: RepositoryCache, specifier) {
+      expect(this.directory).toBe(cacheDirectory)
+      resolved.push(specifier)
+      return directory
+    })
+
+    const ctx = new Context()
+    await ctx.plugin(Loader)
+    await ctx.plugin(SkillService)
+    const registrar = ctx.plugin(RepositoryPlugin, {
+      repositories: ['github:owner/repository#fixed-ref'],
+      cacheDir: cacheDirectory,
+    })
+    await registrar
+    expect(resolved).toEqual(['github:owner/repository#fixed-ref&path:/.dsh-plugin'])
+    await expect(ctx.skills.get('configured-repository-skill')).resolves.toMatchObject({
+      provider: 'repository:configured-source-fixture',
+    })
+
+    await registrar.dispose()
+    await expect(ctx.skills.get('configured-repository-skill')).resolves.toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects duplicate generations and cleans the builtin after cache preparation fails', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Loader)
+    await expect(RepositoryPlugin.apply(ctx, {
+      repositories: [
+        'github:owner/repository#ref',
+        'github:owner/repository#ref',
+      ],
+    })).rejects.toThrow('must resolve to unique exact specifiers')
+
+    vi.spyOn(RepositoryCache.prototype, 'resolve').mockRejectedValue(new Error('prepare failed'))
+    await expect(RepositoryPlugin.apply(ctx, {
+      repositories: ['github:owner/repository#other'],
+    })).rejects.toThrow('prepare failed')
+    expect(ctx.loader.builtins[RepositoryPlugin.REPOSITORY_PLUGIN_BUILTIN]).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('labels a missing prepared wrapper with its exact source and path', async () => {
+    const root = await temporaryDirectory('missing-wrapper')
+    const ctx = new Context()
+    const specifier = 'github:owner/repository#missing&path:/.dsh-plugin'
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, specifier))
+      .rejects.toThrow(`failed to load prepared repository Plugin ${JSON.stringify(specifier)}`)
+    await ctx.fiber.dispose()
+  })
+})
+
 describe('repository plugin invariant companion', () => {
  it('registers its explained empty invariant', async () => {
    const ctx = new Context()
--- a/packages/cordis/repository-plugin/tsconfig.json
+++ b/packages/cordis/repository-plugin/tsconfig.json
@@ -23,6 +23,9 @@
    {
      "path": "../../mcp/mcp-client"
    },
+    {
+      "path": "../../util/paths"
+    },
    {
      "path": "../../support/invariants"
    }
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/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
--- a/packages/ui/app-boot/README.md
+++ b/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
--- a/packages/ui/app-boot/README.zh.md
+++ b/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（测试前置数据）中。

 ## 模型体验
--- a/packages/ui/app-boot/package.json
+++ b/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:^",
--- a/packages/ui/app-boot/src/index.ts
+++ b/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
--- a/packages/ui/app-boot/tests/personal-config.spec.ts
+++ b/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()
+  })
 })
--- a/packages/ui/app-boot/tests/repository-cache.spec.ts
+++ b/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')
  })
 })
--- a/packages/ui/app-boot/tsconfig.json
+++ b/packages/ui/app-boot/tsconfig.json
@@ -17,6 +17,9 @@
    {
      "path": "../../../vendor/include"
    },
+    {
+      "path": "../../../vendor/hmr"
+    },
    {
      "path": "../../support/invariants"
    },