Merge remote-tracking branch 'origin/feat/ripgrep-packaged-binary' into feat/pwsh-tool

# Conflicts:
#	apps/cli/package.json

apps/cli/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 apps/cli/README.md
-README.md: 6b67cbfccd21c6f1c32b5bc9417ab71309898b24
-README.zh.md: 71e242398fe56616c2b146562a6c7ce74fb0f6e1
+README.md: 76d9ed65398322cb9244a31661ee59b60c23f793
+README.zh.md: 16a7a4ec52b830e45c32a61a103d87be5941ab3b

apps/cli/README.md

@@ -11,7 +11,7 @@ The TUI surface:
 - resumes a persisted session with `dsh --resume <session-id>` and, when the Node host exposes `process.execve`, supplies the TUI's in-place handoff host: after selector preflight and current-session flush, the host disposes the app and replaces the process with a normalized resume invocation; runtimes without process replacement leave the session running and say so. This CLI owns session identity and the exit line rather than the config: it mints or selects the `main` session id and provides it, plus the exact command that reproduces this invocation, on the boot context ([`MAIN_SESSION_ID_KEY`](../../packages/ui/tui/README.md) and `TUI_GOODBYE_MESSAGE_KEY`). No `cordis.yml` key can drop resume, and a missing or unreadable id fails loud instead of creating a fresh session;
 - treats the **invoking directory** as the workspace — sessions, relative paths, and workspace instructions resolve from the cwd (`dsh meta` is the sole exception, below);
 - tells the agent where its own source lives: after boot it adds a prompt section naming this harness checkout, resolved from the launcher's real path so it holds under a PATH symlink and an arbitrary cwd, so the self-referential `cordis` toolset can read and modify it;
-- applies the personal overlay from `~/.dsh` (see [app-boot's Personal config](../../packages/ui/app-boot/README.md#personal-config)): `config.yaml` patches the booted tree, while `.env` there is the credential provider's own store (never hoisted into the environment, so keys stay rotatable). Environment precedence is ambient > project `.env`.
+- applies the personal overlay from `~/.dsh` (see [app-boot's Personal config](../../packages/ui/app-boot/README.md#personal-config)): `config.yaml` patches the booted tree, while `.env` there is the credential provider's own store (never hoisted into the environment, so keys stay rotatable). Environment precedence is ambient > project `.env`. The shipped tree's Cordis HMR keeps `config.yaml` live; an explicit `--config` tree replaces that overlay, and a tree without HMR reads it at startup only.
 - presents the [versioned first-run welcome](../../.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md) through the mounted TUI overlay service when its immutable marker is absent under `DSH_HOME`; only Enter creates that version's marker, while Escape, disposal, or process exit leaves it eligible. The official DeepSeek icon, responsive terminal rasters, all-locale Chinese copy, and notice version are static local owners; the overlay never writes a session event or model context.
 - registers bare `/compact`: while the agent is idle, it summarizes useful older history even below automatic pressure, rejects arguments, and reports success only after the standalone replacement bracket is durable. A prompt submitted during compaction keeps its queue identity and starts after that checkpoint; injected context remains visible.
 
@@ -25,6 +25,18 @@ The Web and headless surfaces boot `base.cordis.yml` plus `web.cordis.yml`, then
 
 The shared composition defaults new TUI, Web, and headless sessions to the `workspace-write` permission preset (`workspace-write` file mode plus `ask` approval policy). Sandbox-enforced bash and filesystem mutations may write only under the session workspace and platform temporary roots; reads, network access, and process visibility are not confined. The browser answers one-shot approval requests and exposes the Access picker; the TUI exposes `/permission`, but has no approval-request answerer, so an automatic wider retry there fails closed until the user deliberately changes the session preset. `DSH_PERMISSION_MODE` changes the process fallback, while a stored General-settings Permission value applies to later sessions without changing an open one.
 
+All three surfaces consume `$DSH_HOME/config.yaml`; the TUI and Web apply valid edits live, while one-shot headless runs read it at startup. The shipped trees include an empty `repository-plugins` row, so a standalone user can add prepared GitHub Plugins without an SDK project or install command:
+
+```yaml
+- id: repository-plugins
+  name: '@deepseek-ai/dsh-repository-plugin'
+  config:
+    repositories:
+      - 'github:PolyArch/humanize#<commit>'
+```
+
+The repository must contain a prepared `.dsh-plugin` package; the [repository Plugin contract](../../packages/cordis/repository-plugin/README.md#standalone-app-configuration) documents authoring, nested Plugin paths, the immutable cache, trust boundary, and failure semantics. A failed live edit keeps the last good tree and emits Cordis's `hmr/config-update-failed` event.
+
 The shipped TUI and Web compositions register the native DeepSeek adapter plus pi-ai OpenAI and Anthropic profiles. Credentials and endpoint overrides come from the provider-standard `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`, `OPENAI_API_KEY` / `OPENAI_BASE_URL`, and `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` pairs in the boot's layered environment.
 
 Every surface also registers `web_search` and only `web_search`. Search uses DeepSeek's Anthropic-compatible Messages endpoint, resolves the same `DEEPSEEK_API_KEY` reference for every call, and accepts the separate `DEEPSEEK_SEARCH_BASE_URL` endpoint override; each search is an auxiliary model request with its own latency and token cost. `web_fetch` remains disabled and the composition mounts no default fetch provider, so deployments that need arbitrary page retrieval must opt in through an overlay. The deployment decision and its security boundary live in the [default Web search Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md).

apps/cli/README.zh.md

@@ -11,7 +11,7 @@ TUI 界面：
 - 使用 `dsh --resume <session-id>` 恢复已持久化会话。当 Node 宿主公开 `process.execve` 时，还会提供 TUI 的原地移交宿主：选择器预检并刷新当前会话后，宿主会释放应用，并以规范化的恢复调用替换进程；不支持进程替换的运行时会让会话继续运行并给出提示。会话身份与退出行由本 CLI 拥有，而非由配置指定：它创建或选定 `main` 会话 id，并把该 id 以及可复现本次调用的确切命令一起提供到启动上下文（[`MAIN_SESSION_ID_KEY`](../../packages/ui/tui/README.md) 与 `TUI_GOODBYE_MESSAGE_KEY`）。任何 `cordis.yml` 键都无法移除恢复能力；缺失或无法读取的 id 会明确报错，而不会创建新会话；
 - 将 **调用目录** 视为 workspace：会话、相对路径和 workspace 指令都从 cwd 解析（`dsh meta` 是唯一例外，见下文）；
 - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它；
-- 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`config.yaml` 修补已启动的树，而那里的 `.env` 是凭据 provider 自己的存储（绝不会被提升进环境，因此密钥始终可轮换）。环境优先级为环境中已有的值 > 项目 `.env`。
+- 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`config.yaml` 修补已启动的树，而那里的 `.env` 是凭据 provider 自己的存储（绝不会被提升进环境，因此密钥始终可轮换）。环境优先级为环境中已有的值 > 项目 `.env`。已交付配置树中的 Cordis HMR 会持续应用 `config.yaml` 的变更；显式 `--config` 配置树会替代该个人覆盖，未包含 HMR 的配置树只在启动时读取该文件。
 - 当 `DSH_HOME` 下不存在不可变确认标记时，通过已挂载的 TUI overlay 服务呈现[版本化首次运行欢迎页](../../.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md)；只有 Enter 会创建该版本的标记，Escape、资源释放或进程退出仍保留展示资格。官方 DeepSeek 图标、响应式终端栅格图、所有 locale 共用的中文文案和通知版本均由静态本地文件持有；overlay 不会写入会话事件或模型上下文。
 - 注册裸 `/compact`：agent 空闲时，即使未达到自动压力，也会摘要有效的较早历史；该命令拒绝参数，并只在独立替换标记对持久化后报告成功。压缩（compaction）期间提交的提示词保留其队列身份，并在该检查点之后启动；注入的上下文仍保持可见。
 
@@ -25,6 +25,18 @@ Web 和无头界面启动 `base.cordis.yml` 与 `web.cordis.yml`，随后应用
 
 共享组合把新建 TUI、Web 和无头会话的权限默认设为 `workspace-write` preset（`workspace-write` 文件模式加 `ask` 审批策略）。由沙箱强制约束的 bash 与文件系统修改只能写入会话工作区和平台临时根目录；读取、网络访问和进程可见性不受该策略约束。浏览器可以应答一次性审批请求，并提供 Access 选择器；TUI 提供 `/permission`，但没有审批请求应答者，因此自动请求更宽权限的重试会以拒绝方式关闭，直到用户主动更改会话 preset。`DSH_PERMISSION_MODE` 会更改进程回退值，而「通用」设置中已存储的「权限」值只适用于之后的会话，不会更改已打开的会话。
 
+三个界面都会使用 `$DSH_HOME/config.yaml`；TUI 和 Web 实时应用有效编辑，而一次性无头运行只在启动时读取。已交付的配置树包含一个空的 `repository-plugins` 配置项，因此独立用户无需 SDK 项目或安装命令，只需配置即可添加已准备的 GitHub 插件：
+
+```yaml
+- id: repository-plugins
+  name: '@deepseek-ai/dsh-repository-plugin'
+  config:
+    repositories:
+      - 'github:PolyArch/humanize#<commit>'
+```
+
+仓库必须包含已准备的 `.dsh-plugin` 包；[仓库插件契约](../../packages/cordis/repository-plugin/README.md#standalone-app-configuration)说明创作方式、嵌套插件路径、不可变缓存、信任边界和失败语义。实时编辑失败时，最后一个可用树保持运行，并发出 Cordis 的 HMR（热模块替换）事件 `hmr/config-update-failed`。
+
 已交付的 TUI 和 Web 组合会注册原生 DeepSeek 适配器，以及 pi-ai 的 OpenAI 和 Anthropic 提供方配置。凭据和端点覆盖来自启动分层环境中的提供方标准变量对：`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`、`OPENAI_API_KEY` / `OPENAI_BASE_URL` 和 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`。
 
 每个界面也都只注册 `web_search` 这一个 Web 工具。搜索使用 DeepSeek 的 Anthropic 兼容 Messages 端点，每次调用都会解析同一个 `DEEPSEEK_API_KEY` 凭据引用，并接受独立的 `DEEPSEEK_SEARCH_BASE_URL` 端点覆盖；每次搜索都是一次辅助模型请求，会产生独立的延迟与 token 成本。`web_fetch` 仍处于禁用状态，组合也未挂载默认抓取提供方；需要任意页面抓取能力的部署必须通过覆盖层选择启用。部署决策及其安全边界见[默认 Web 搜索 Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md)。

apps/cli/composition.md

@@ -12,6 +12,8 @@ flowchart LR
   cfg --> plugin_tui_timer
   plugin_tui_hmr["hmr<br/>@cordisjs/plugin-hmr"]
   cfg --> plugin_tui_hmr
+  plugin_tui_repository_plugins["repository-plugins<br/>@deepseek-ai/dsh-repository-plugin"]
+  cfg --> plugin_tui_repository_plugins
   plugin_tui_llm["llm<br/>@deepseek-ai/dsh-llm"]
   cfg --> plugin_tui_llm
   plugin_tui_session["session<br/>@deepseek-ai/dsh-session"]
@@ -116,8 +118,6 @@ flowchart LR
   cfg --> plugin_tui_tool_goal
   plugin_tui_tool_ralph["tool-ralph<br/>@deepseek-ai/dsh-tool-ralph"]
   cfg --> plugin_tui_tool_ralph
-  plugin_tui_tool_session_query["tool-session-query<br/>@deepseek-ai/dsh-tool-session-query"]
-  cfg --> plugin_tui_tool_session_query
   plugin_tui_tool_str_replace_editor["tool-str-replace-editor<br/>@deepseek-ai/dsh-tool-str-replace-editor"]
   cfg --> plugin_tui_tool_str_replace_editor
   plugin_tui_repeat_tool_guard["repeat-tool-guard<br/>@deepseek-ai/dsh-repeat-tool-guard"]
@@ -144,6 +144,7 @@ flowchart LR
 | --- | --- |
 | `timer` | `@cordisjs/plugin-timer` |
 | `hmr` | `@cordisjs/plugin-hmr` |
+| `repository-plugins` | `@deepseek-ai/dsh-repository-plugin` |
 | `llm` | `@deepseek-ai/dsh-llm` |
 | `session` | `@deepseek-ai/dsh-session` |
 | `session-title` | `@deepseek-ai/dsh-session-title` |
@@ -196,7 +197,6 @@ flowchart LR
 | `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
 | `tool-goal` | `@deepseek-ai/dsh-tool-goal` |
 | `tool-ralph` | `@deepseek-ai/dsh-tool-ralph` |
-| `tool-session-query` | `@deepseek-ai/dsh-tool-session-query` |
 | `tool-str-replace-editor` | `@deepseek-ai/dsh-tool-str-replace-editor` |
 | `repeat-tool-guard` | `@deepseek-ai/dsh-repeat-tool-guard` |
 | `web` | `@deepseek-ai/dsh-web` |

apps/cli/config/base.cordis.yml

@@ -22,6 +22,13 @@
   config:
     root: ['.']
 
+# `$DSH_HOME/config.yaml` replaces this row's config to select exact GitHub
+# repository Plugin generations. The app registers the DSH-owned runtime even
+# when the list is empty so a later personal-config edit can load
+# transactionally; one-shot headless runs consume the startup value only.
+- id: repository-plugins
+  name: '@deepseek-ai/dsh-repository-plugin'
+
 - id: llm
   name: '@deepseek-ai/dsh-llm'
 
@@ -309,12 +316,6 @@
     subagentProvider: spawn
     maxRounds: 64
 
-- id: tool-session-query
-  name: '@deepseek-ai/dsh-tool-session-query'
-  config:
-    maxSearchResults: 100
-    searchTimeoutMs: 30000
-
 - id: tool-str-replace-editor
   name: '@deepseek-ai/dsh-tool-str-replace-editor'
   config:

apps/cli/config/core-web.cordis.yml

@@ -45,9 +45,6 @@
 - id: tool-ralph
   disabled: true
 
-- id: tool-session-query
-  disabled: true
-
 - id: tool-str-replace-editor
   disabled: true
 

apps/cli/package.json

@@ -78,6 +78,7 @@
     "@deepseek-ai/dsh-pty": "workspace:^",
     "@deepseek-ai/dsh-pty-local": "workspace:^",
     "@deepseek-ai/dsh-pwsh-local": "workspace:^",
+    "@deepseek-ai/dsh-repository-plugin": "workspace:^",
     "@deepseek-ai/dsh-sandbox-local": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
@@ -117,7 +118,6 @@
     "@deepseek-ai/dsh-tool-fs-search": "workspace:^",
     "@deepseek-ai/dsh-tool-goal": "workspace:^",
     "@deepseek-ai/dsh-tool-ralph": "workspace:^",
-    "@deepseek-ai/dsh-tool-session-query": "workspace:^",
     "@deepseek-ai/dsh-tool-skill": "workspace:^",
     "@deepseek-ai/dsh-tool-str-replace-editor": "workspace:^",
     "@deepseek-ai/dsh-tool-subagent": "workspace:^",

apps/cli/src/app-cli-entry.ts

@@ -1,6 +1,6 @@
 /**
  * AppCLIEntry — the pre-cordis boot glue the config-tree dsh surfaces share
- * for the Web/headless surface.
+ * (`dsh web` and `dsh -p`; the TUI composes dsh-app-boot directly).
  * Everything here is what must exist before the Loader runs: the patch
  * composition over the shipped base and surface overlay (profile json + CLI
  * flags + the resolved frontend dist), and the fail-loud activation audit after the tree
@@ -16,7 +16,13 @@ import { join, resolve } from 'node:path'
 import { Context } from 'cordis'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import yaml from 'js-yaml'
-import { boot, installFailLoud, loadOverlayPatches, loadPersonalPatches } from '@deepseek-ai/dsh-app-boot'
+import {
+  boot,
+  installFailLoud,
+  loadOverlayPatches,
+  loadPersonalPatches,
+  watchPersonalPatches,
+} from '@deepseek-ai/dsh-app-boot'
 // Empty type import carries the httpServer Context merge for the port read below.
 import type {} from '@deepseek-ai/dsh-host-webserver'
 
@@ -140,8 +146,10 @@ export interface AppCLIEntryOptions {
    * `$DSH_HOME/config.yaml` overlay is applied instead.
    */
   extraOverlayPath?: string
-  /** Whether to append the HMR row (the whole prod/dev difference; web surface only). */
+  /** Whether to append client-bundle HMR (the Web surface's prod/dev difference). */
   dev: boolean
+  /** Whether `$DSH_HOME/config.yaml` remains live after the initial boot. */
+  watchPersonalConfig: boolean
   /** --host when explicitly passed; undefined keeps the yml engineering default. */
   host?: string
   /**
@@ -235,11 +243,12 @@ export class AppCLIEntry {
     // user config. Workspace knowledge stays here.
     put('webserver', 'distIndex', this.resolveDistIndex())
 
-    this.patches = [...overrides.entries()].map(([id, bag]) => {
+    const generated = [...overrides.entries()].map(([id, bag]) => {
       const yml = rows.get(id)
       if (yml === undefined) throw new Error(`dsh: patch target row "${id}" not found in ${this.options.configPath}`)
       return { id, config: { ...(yml.config ?? {}) as Record<string, unknown>, ...bag } }
     })
+    this.patches = generated
 
     // Telemetry opt-out: a row can only be turned off at the patch layer
     // (config cannot disable an entry), and the switch must hold BEFORE the
@@ -254,17 +263,30 @@ export class AppCLIEntry {
     // list: patches never cross an include boundary, so nesting them would
     // silently stop reaching base rows. The surface overlay applies first, then
     // this entry's profile-json and CLI-flag patches, which therefore win.
-    const patches = [
+    const compose = (overlay: PatchOptions[]): PatchOptions[] => [
       ...loadOverlayPatches('dsh', this.options.overlayPath),
-      ...this.options.extraOverlayPath === undefined
-        ? loadPersonalPatches('dsh') ?? []
-        : loadOverlayPatches('dsh', this.options.extraOverlayPath),
+      ...overlay,
       ...this.patches,
     ]
+    // An explicit --config overlay REPLACES the personal overlay, so there is
+    // then no personal layer to keep live — the watcher is personal-only.
+    const watchPersonal = this.options.watchPersonalConfig && this.options.extraOverlayPath === undefined
+    const patches = compose(
+      this.options.extraOverlayPath === undefined
+        ? loadPersonalPatches('dsh') ?? []
+        : loadOverlayPatches('dsh', this.options.extraOverlayPath),
+    )
     this.ctx = await boot('dsh', resolve(this.options.configPath), patches, async (ctx) => {
       await this.options.prepare?.(ctx)
+      // Config-only HMR for the personal overlay: module reload stays off for
+      // this surface (web.cordis.yml disables the shared `hmr` row until its
+      // reload lifecycle is tested), so this row watches no module roots.
+      if (watchPersonal) await ctx.loader.create({ name: '@cordisjs/plugin-hmr', config: { root: [] } })
       if (this.options.dev) await ctx.loader.create({ name: '@deepseek-ai/dsh-client-hmr' })
     })
+    if (watchPersonal) {
+      await watchPersonalPatches(this.ctx, { binName: 'dsh', compose })
+    }
   }
 
   /** Install the diagnostic for plugin rejections that happen after settled boot. */

apps/cli/src/headless.ts

@@ -78,6 +78,7 @@ export async function runHeadless(task: string): Promise<void> {
     configPath: fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url)),
     overlayPath: fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url)),
     dev: false,
+    watchPersonalConfig: false,
     port: 0,
   })
   const { ctx, port } = await entry.run()

apps/cli/src/tui.ts

@@ -28,8 +28,10 @@ import {
   loadOverlayPatches,
   loadPersonalPatches,
   resolveConfigPath,
+  watchPersonalPatches,
 } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import type { PatchOptions } from '@cordisjs/plugin-include'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { configHasTelemetryRow, resolveTelemetryPatch } from './app-cli-entry.ts'
 import { SESSION_QUERY_SQLITE_PATH_KEY } from '@deepseek-ai/dsh-session-query-sqlite'
@@ -201,15 +203,16 @@ export async function runTui(
   // presence is checked against the tree actually booting, so a
   // --config-replace tree is judged on its own rows, not the shipped base's.
   const telemetryPatch = resolveTelemetryPatch(process.env.DSH_TELEMETRY_DISABLED, configHasTelemetryRow(bootConfig))
-  const patches = [
+  const composePatches = (personalPatches: PatchOptions[]): PatchOptions[] => [
     ...replaceTree ? [] : [
       ...loadOverlayPatches(NAME, TUI_OVERLAY),
       ...resolvedConfig === undefined
-        ? loadPersonalPatches(NAME) ?? []
+        ? personalPatches
         : loadOverlayPatches(NAME, resolveConfigPath(resolvedConfig, undefined)),
     ],
     ...telemetryPatch === undefined ? [] : [telemetryPatch],
   ]
+  const patches = composePatches(loadPersonalPatches(NAME) ?? [])
   const queryIndexPath = join(tmpdir(), SESSION_QUERY_DB)
   const ctx = await boot(
     NAME,
@@ -246,6 +249,14 @@ export async function runTui(
       }
     },
   )
+  // The shipped tree includes HMR and keeps personal config live. An explicit
+  // --config tree replaces the personal overlay (so there is nothing to keep
+  // live), and a --config-replace or HMR-less tree remains a valid composition
+  // that still receives the startup overlay but deliberately has no hidden
+  // watcher.
+  if (resolvedConfig === undefined && !replaceTree && ctx.get('hmr') !== undefined) {
+    await watchPersonalPatches(ctx, { binName: NAME, compose: composePatches })
+  }
   app.current = ctx
   addHarnessSourceSection(ctx, SOURCE_ROOT)
   if (showFirstRunWelcome) {

apps/cli/src/web.ts

@@ -109,6 +109,7 @@ export async function runWeb(
     ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
     dev,
     prepare: (ctx) => { prepareWebRuntimeContext(ctx, SOURCE_ROOT, mode) },
+    watchPersonalConfig: true,
     ...host !== undefined && { host },
     ...port !== undefined && { port },
     ...workspaceRoot !== undefined && { workspaceRoot },

apps/cli/tests/shipped-composition.e2e.ts

@@ -35,11 +35,6 @@ const EXPECTED_TUI_TOOLS = [
   'get_goal',
   'ralph',
   'read',
-  'session_event_read',
-  'session_event_search',
-  'session_event_trace',
-  'session_search',
-  'session_trace',
   'skill',
   'str_replace_editor',
   'subagent',

apps/cli/tests/tui-keyless-smoke.e2e.ts

@@ -1,4 +1,5 @@
 import { createUserMessage, createMessage } from '@deepseek-ai/dsh-llm'
+import { createHash } from 'node:crypto'
 import { realpathSync } from 'node:fs'
 import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
@@ -6,6 +7,7 @@ import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS } from '@deepseek-ai/dsh-loader-smoke'
+import { PREPARED_ENTRY_FILENAME, prepareDshPlugin } from '@deepseek-ai/dsh-repository-plugin'
 import { packChunkRuns, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
 import { logPath, toHeaderLine } from '../../../packages/session-persistence/session-persistence-jsonl/src/format.ts'
 import { runTuiPtySmoke, type TuiPtySmokeOptions } from './pty-harness.ts'
@@ -66,6 +68,38 @@ function seedWorkspace(
   }
 }
 
+/**
+ * Run the real `prepareDshPlugin` over an equivalent one-skill `.dsh-plugin`
+ * package and return the generated wrapper text, so the smoke's cache-seeded
+ * wrapper can never drift from the generator's template.
+ */
+async function generatePreparedWrapper(pluginName: string): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-smoke-wrapper-'))
+  try {
+    const plugin = join(root, '.dsh-plugin')
+    await mkdir(join(root, 'skills', 'config-only-repository'), { recursive: true })
+    await writeFile(join(root, 'skills', 'config-only-repository', 'SKILL.md'), [
+      '---',
+      'name: config-only-repository',
+      'description: Generator input; the seeded cache copy owns the visible text.',
+      '---',
+      '',
+      'Repository instructions.',
+      '',
+    ].join('\n'))
+    await mkdir(plugin, { recursive: true })
+    await writeFile(join(plugin, 'package.json'), `${JSON.stringify({
+      name: pluginName,
+      version: '0.0.0',
+      dsh: { skills: ['../skills'] },
+    }, undefined, 2)}\n`)
+    await prepareDshPlugin(plugin)
+    return await readFile(join(plugin, PREPARED_ENTRY_FILENAME), 'utf8')
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+}
+
 /** Seed one real plaintext JSONL session for the `/resume` selector and host handoff smoke. */
 async function seedResumeSession(cwd: string): Promise<void> {
   const sessionCwd = realpathSync.native(cwd)
@@ -640,6 +674,54 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     expect(output).toContain('\u001B[?2004l')
   }, PTY_SMOKE_TEST_TIMEOUT_MS)
 
+  it('loads a cached repository Plugin from personal config alone', async () => {
+    const source = 'github:fixture/repository#fixed-ref'
+    const specifier = `${source}&path:/.dsh-plugin`
+    const key = createHash('sha256').update(specifier).digest('hex')
+    const packageRoot = `cache/repository-plugins/${key}/node_modules/repository`
+    // Produced by the real generator (prepareDshPlugin over an equivalent
+    // .dsh-plugin package) rather than hand-written, so a wrapper-template
+    // change cannot leave this smoke exercising a stale shape. The cache
+    // LAYOUT below (sha256 key, marker, node_modules/repository) remains a
+    // deliberate external pin of the durable on-disk format.
+    const wrapper = await generatePreparedWrapper('config-only-fixture')
+    const output = await smoke({
+      label: 'dsh personal repository Plugin',
+      tempDirPrefix: 'dsh-personal-repository-plugin-',
+      binScript: dshBinScript,
+      configArgs: [],
+      prepare: seedWorkspace({
+        personal: {
+          'config.yaml': [
+            '- id: repository-plugins',
+            "  name: '@deepseek-ai/dsh-repository-plugin'",
+            '  config:',
+            '    repositories:',
+            `      - '${source}'`,
+            '',
+          ].join('\n'),
+          [`cache/repository-plugins/${key}/.repository-cache.json`]: `${JSON.stringify({ specifier })}\n`,
+          [`${packageRoot}/dsh-plugin.mjs`]: wrapper,
+          [`${packageRoot}/dsh-plugin-assets/skills/0/config-only-repository/SKILL.md`]: [
+            '---',
+            'name: config-only-repository',
+            'description: CONFIG_ONLY_REPOSITORY_SKILL',
+            '---',
+            '',
+            'Repository instructions.',
+            '',
+          ].join('\n'),
+        },
+      }),
+      actions: [
+        { waitFor: 'main-session-', send: '/skill:config-only' },
+        { waitFor: 'CONFIG_ONLY_REPOSITORY_SKILL', send: '\x03/exit\r' },
+      ],
+    })
+    expect(output).toContain('CONFIG_ONLY_REPOSITORY_SKILL')
+    expect(output).toContain('\u001B[?2004l')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('fails loud instead of booting when the personal config.yaml is invalid', async () => {
     const output = await smoke({
       label: 'dsh invalid personal config',