dsh-wsl-workspace 0.7.2 → 0.7.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-wsl-workspace",
   "description": "WSL workspace support for DeepSeek Harness: add a WSL workspace from the web GUI and run the whole agent session (bash + file tools) inside the WSL distribution, VS Code Remote-WSL style. No toolchain install inside WSL required.",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "repository": {
     "type": "git",
@@ -45,7 +45,8 @@
         "0.1.2-rc.1": "compatible",
         "0.1.3-alpha.2": "compatible",
         "0.1.5-rc.1": "compatible",
-        "0.1.5-rc.2": "compatible"
+        "0.1.5-rc.2": "compatible",
+        "0.1.7-rc.1": "compatible"
       }
     }
   },
@@ -68,6 +69,7 @@
   ],
   "peerDependencies": {
     "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/cordis-plugin-include": "*",
     "@deepseek-ai/dsh-fs": "*",
     "@deepseek-ai/dsh-fs-local": "*",
     "@deepseek-ai/dsh-sandbox": "*",
@@ -76,10 +78,12 @@
     "@deepseek-ai/dsh-timeout": "*",
     "@deepseek-ai/dsh-tool-fs-search": "*",
     "@deepseek-ai/dsh-tools": "*",
-    "@deepseek-ai/schemastery": "*"
+    "@deepseek-ai/schemastery": "*",
+    "js-yaml": "*"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": { "optional": true },
+    "@deepseek-ai/cordis-plugin-include": { "optional": true },
     "@deepseek-ai/dsh-fs": { "optional": true },
     "@deepseek-ai/dsh-fs-local": { "optional": true },
     "@deepseek-ai/dsh-sandbox": { "optional": true },
@@ -88,7 +92,8 @@
     "@deepseek-ai/dsh-timeout": { "optional": true },
     "@deepseek-ai/dsh-tool-fs-search": { "optional": true },
     "@deepseek-ai/dsh-tools": { "optional": true },
-    "@deepseek-ai/schemastery": { "optional": true }
+    "@deepseek-ai/schemastery": { "optional": true },
+    "js-yaml": { "optional": true }
   },
   "files": [
     "lib",

package/src/client/locales.ts

@@ -41,8 +41,8 @@ export const zh: Record<string, string> = {
   'help.compat.versionLabel': '插件版本',
   'help.compat.unknown': '未能读取版本与兼容声明（宿主端没有响应）',
   'help.compat.body': '上方是这份构建声明兼容的 DSH 版本，每一条都在隔离实例上实测过（独立 DSH_HOME、依赖固定到该版本、跑满十项门禁）。\n插件在运行时自动识别 DSH 版本并选用对应的 API；两边都不支持时会明确报错，而不是留下一个空工作区。\n版本不在列表里通常仍然可用，但未经验证。',
-  'help.news.title': '本次更新（0.7.2）',
-  'help.news.body': '修掉了 WSL 技能目录在请求路径上重走的问题（issue #25）：宿主会在请求期间重建技能目录并等待各 provider 的 list()，而插件只把答案保留 10 秒，于是每次重新收集都得重走整棵工作区，工作区一大就正好卡在走查的 4096 目录预算上。\n9P 共享上单次 readdir 实测 3~16 毫秒，所以命中预算的工作区那次走查要 20 秒；现在已发布的目录直接照原样返回，只有插件自己的探针确认变化时才丢弃缓存，重复查找降到 1~3 毫秒、且完全不碰文件系统。\n走查本身也变便宜：同一层并发探测（有上限）、按 frontier 顺序发布以保证目录顺序确定，且只在目录清单里出现 .dsh / .agents 时才探测对应 skills。同机实测命中预算的走查从 20.4 秒降到 4.8 秒。\n修掉了 npm 安装失败：npm 会自动安装缺失的同伴依赖，而 @deepseek-ai/dsh-tool-fs-search 自己又依赖并未公开发布的 @deepseek-ai/dsh-retention，于是 npm install dsh-wsl-workspace 直接 E404 失败（dsh plugin 走 pnpm、只警告，所以一直没暴露）。\n十个宿主同伴依赖现在都标为 optional：包仍声明宿主必须提供什么，但 npm 不再尝试下载它们。\nWSL 世界现在在会话能察觉到的每一处都与宿主一致：Linux 符号链接、会话的访问模式、发行版内的 grep / glob、实时技能目录、有状态的 shell，以及可跟踪的后台任务。\n新增 bash_background：持久 shell 的 schema 只有 command，没有生产者时 job_list 永远说"没有后台任务"，而传给 bash 的 run_in_background 会被静默忽略；现在后台任务可跟踪，job_output 增量读取、job_kill 取消都照常工作。\nbash 的工具描述写明两件宿主没说的事：cd / export 跨调用保留，命令以 & 结尾会把整条命令后台化（请写成单独一行的 ( 长任务 > log 2>&1 ) &）。0.1.0-rc.7 的宿主缺少 Windows 进程检查器、持久 shell 起不来，插件会在启动时探测并回退到一次性 bash，不再让每次调用都报错。',
+  'help.news.title': '本次更新（0.7.3）',
+  'help.news.body': '插件在 DSH 0.1.7 上重新可加载、模式也回来了：那条线把预设平面改成了声明式的 @deepseek-ai/dsh-agent-preset 行，read() 变成 readDocument()、AgentPreset 不再有 path，于是变体生成器每次启动都抛 agentPresets.read is not a function，选择器里一个 wsl-* 模式都不会出现。现在按能力探测两代接口，两代都服务。\n在 0.1.7 上变体改为通过 ctx.agentPresets.register() 发布成一条声明；注销器由插件的 effect 持有，卸载或热重载会注销这些变体，而不是留下下一次 apply 无法替换的孤儿。更早的版本仍走原来的目录通道，行为不变。\n该通道下世界自己的 provider 行必须以 file: URL 命名：由声明挂载的预设由注册表自己的 entry tree 导入，它不会像启动期的 Include 那样把绝对路径翻译成 file: URL，否则那些行根本不会启动、整个变体被判为不可用而拒绝。relay 与解释器这类配置值仍保持原生路径。\n修掉了 PTC 变体的显示名：标签表里只登记了旧 id code，而 0.1.7 不发布显示名，于是模式显示为 WSL · ptc、描述也退化成 WSL execution world for ptc: …；现在两条通道都显示为 WSL · PTC mode（PTC 模式）。\n兼容性清单增加 0.1.7-rc.1；声明通道需要的两个模块（@deepseek-ai/cordis-plugin-include、js-yaml）在调用时解析，并声明为可选同伴依赖。',
   'help.usage.title': '用法与特性',
   'help.usage.body': '点击侧边栏底部的 W 按钮 → 选发行版 → 输入或浏览 Linux 路径 → 检查 → 创建并打开。\n创建出的会话里，bash 与文件工具都落在该发行版内，模型看到的路径全是 Linux 路径；Windows 盘可从会话内通过 /mnt/<盘符> 访问。\n四种模式（标准 / PTC / 极简 / 创造）各有 WSL 变体，在模式选择器里直接选即可，名字形如 WSL · Standard mode（标准模式）。\n用户名可选，等价于 wsl.exe -u <用户名>，只改变 bash 与 persistent-bash 的运行身份；文件工具走 Windows 侧共享，不受它影响。\n技能目录从会话 cwd 最近的 .git 祖先开始向下扫描 .dsh/skills 与 .agents/skills（含嵌套项目），上限 4 层目录 / 64 个技能目录 / 4096 个已访问目录，并按扫描根缓存 10 秒。9P 解不开的符号链接交给发行版 readlink 解析出真实路径（每次查找最多 32 条）后继续扫描，链接进来的项目与它下面的嵌套项目都能扫到。\n目录不再冻结：对 UNC 关闭文件监视之后，插件每 3 秒重查一次已发布的技能目录、并比对每个技能文件的修改时间与大小，所以新增、删除与改写都会在下一个回合生效；完整重新发现每 30 秒一次，用于找到此前不存在的技能目录（技能正文始终实时读取）。\n文件搜索由发行版内的 grep / glob 提供，源预设没有这两个工具的模式（极简）不会多出来：grep 用 GNU grep -E（\\d、\\w、(?i) 可用，环视与反向引用不支持），跳过隐藏项与 node_modules，不读 .gitignore；glob 用 GNU find 列文件、按 gitignore 风格匹配（* 不跨目录、** 跨、{a,b}、前导 ! 取反），按修改时间从旧到新排序。\n文件工具在链接处按真实路径工作，并按真实路径判策略：链接指向工作区外就等于工作区外。\nbash 由 PTY 承载的持久 shell 提供：登录环境、起始目录就是会话工作区，cd / export / venv / 后台任务跨调用保留（它取代了原先一次性 bash）。\n需要可跟踪的后台任务时用 bash_background：它立刻返回 job id，job_list / job_output（增量读取）/ job_kill 都作用于它；bash 本身没有 run_in_background 参数，传了会被忽略。job id 只在本次 DSH 进程内唯一，重启后会重新编号，引用前先用 job_list 确认。\nbash 与文件工具的 shell 都在发行版内运行、不受 DSH 文件策略约束；文件工具（read/write/edit）受策略约束，工作区内修改模式下只能写工作区内。',
   'help.known.title': '已知问题',
@@ -89,8 +89,8 @@ export const en: Record<string, string> = {
   'help.compat.versionLabel': 'Plugin version',
   'help.compat.unknown': 'Version and compatibility declaration unavailable (the host side did not answer)',
   'help.compat.body': 'The chips above are the DSH releases this build declares, each verified on an isolated instance (own DSH_HOME, dependencies pinned to that release, full check suite).\nThe plugin detects the DSH generation at runtime and picks the matching API; a release exposing neither fails loudly instead of leaving an empty workspace.\nA release outside the list usually still works, but is unverified.',
-  'help.news.title': "What's new in 0.7.2",
-  'help.news.body': 'Fixed the WSL skill catalog being re-walked on the request path (issue #25): the host rebuilds the catalog during a request and awaits each provider\'s list(), while this plugin kept its answer for only 10 s - so every re-collection re-walked the whole workspace.\nA readdir over the WSL 9P share costs 3-16 ms and the walk\'s budget is 4096 directories, so a large workspace sat 20 s on it. The published catalog is now served as-is until the provider\'s own watcher sees a change, which takes a repeat lookup to 1-3 ms with no filesystem traffic at all.\nThe walk is cheaper too: one BFS layer is probed concurrently and published in frontier order, and a directory\'s .dsh/skills is probed only when its own listing showed .dsh. A budget-sized walk measured 20.4 s before and 4.8 s after.\nFixed a failed npm install: npm auto-installs missing peers, and @deepseek-ai/dsh-tool-fs-search peers on @deepseek-ai/dsh-retention, which is not published - so npm install dsh-wsl-workspace died with E404.\nThe ten host peer dependencies are now marked optional, so npm leaves them to the host (dsh plugin add uses pnpm and only warned, which is why this stayed hidden).\nThe WSL world now matches the host everywhere a session can tell the difference: Linux symlinks, the session\'s access mode, in-distribution grep / glob, a live skill catalog, a stateful shell, and tracked background jobs.\nNew: bash_background. The persistent shell takes `command` only, so without a producer job_list always answered "no background jobs" and a run_in_background argument passed to bash was silently ignored; background work is now tracked, with incremental job_output reads and job_kill.\nThe bash tool description now states two things the host does not: cd / exports carry into the next call, and a command ending in & backgrounds the whole command - background the subshell instead, as ( long-job > log 2>&1 ) &.\n0.1.0-rc.7 lacks the Windows process inspector the persistent shell needs, so the plugin probes for it and falls back to a one-shot bash instead of failing every call.',
+  'help.news.title': "What's new in 0.7.3",
+  'help.news.body': 'The plugin loads on DSH 0.1.7 again, and its modes come back: that line turned the preset plane into declarative @deepseek-ai/dsh-agent-preset rows, renamed read() to readDocument() and dropped AgentPreset.path.\nThe variant generator therefore threw agentPresets.read is not a function on every boot and no wsl-* mode reached the picker; both roster generations are now probed by capability.\nOn 0.1.7 a variant is published as a declaration through ctx.agentPresets.register(); the effect installed by the plugin owns the returned disposers, so an unload or hot reload retires the variants instead of leaving orphans the next apply could not replace.\nEarlier releases keep the directory channel, unchanged.\nOn that channel the provider rows of the world must be named as file: URLs: a preset mounted from a declaration is imported by the entry tree of the registry, which does not translate an absolute path the way the boot-time Include does.\nWithout that rewrite those rows never started and the whole variant was refused as unusable. Config values such as the relay and the interpreter stay native paths.\nThe PTC variant is named again: the label table carried only the older id code, and 0.1.7 publishes no display name, so the mode read WSL · ptc with the generic description WSL execution world for ptc: …; both channels now show WSL · PTC mode（PTC 模式）.\nThe compatibility manifest adds 0.1.7-rc.1, and the two modules the declaration channel needs (@deepseek-ai/cordis-plugin-include, js-yaml) are resolved at call time and declared as optional peers.',
   'help.usage.title': 'Usage and features',
   'help.usage.body': 'Click the W button at the sidebar foot, pick a distribution, type or browse to a Linux path, press Check, then Create & open.\nIn that session the bash tool and the file tools run inside the distribution, so every path the model sees is a Linux path; Windows drives stay reachable as /mnt/<drive>.\nEach mode (Standard / PTC / Minimal / Creator) has a WSL variant in the mode picker, named like WSL · Standard mode.\nThe optional username behaves like wsl.exe -u <user> for bash and persistent-bash; the file tools go through the Windows-side share and are unaffected.\nThe skill catalog is discovered from the nearest .git ancestor of the session cwd downwards (.dsh/skills and .agents/skills, nested projects included), bounded to 4 levels / 64 skill directories / 4096 visited directories, and cached per scan root for 10 seconds.\nA link the share cannot follow is resolved through the distribution (wsl.exe readlink, at most 32 per lookup) and the scan continues at the real path, so a linked-in project and its own nested projects are found too.\nThe catalog is not frozen: published skills directories are re-checked every 3 seconds (skill file mtime + size), so an add, remove or edit appears on the next turn; a 30-second walk finds a skills directory that did not exist before.\nFile search comes from grep / glob inside the distribution, and a mode that mounts no search suite (Minimal) gains none. grep is GNU grep -E (no lookaround or backreferences), skips hidden entries and node_modules, and does not read .gitignore; glob matches gitignore-style patterns here, oldest first.\nThe file tools work at the resolved real path of a link, and the policy is judged there too: a link out of the workspace is an outside write.\n`bash` is a PTY-backed stateful shell: login environment, starting directory the session workspace, and cd / exports / background jobs survive between calls.\nFor a tracked background job use bash_background: it returns a job id immediately, and job_list / job_output (incremental) / job_kill act on it.\n`bash` itself has no run_in_background parameter and ignores one; job ids are unique within this DSH process, so confirm with job_list before acting on one.\nBoth it and the file tools\' shell run inside the distribution, outside the DSH file policy; read/write/edit are inside it, and workspace-write only writes inside the workspace.',
   'help.known.title': 'Known issues',

package/src/index.ts

@@ -1,15 +1,18 @@
 /**
  * Host half of dsh-wsl-workspace. Three responsibilities:
  *
- * 1. Materialize a `wsl-<mode>` variant for every healthy roster preset
- *    under `<dshHome>/.agent-presets/` (the roster's auto-scanned user
- *    root), so the WSL execution world — `shell-wsl` + `fs-wsl` behind one
- *    entry-local realm, with `tool-bash`/`tool-fs` consumers — composes with
- *    ANY mode instead of being a mode itself; the legacy standalone `wsl`
- *    preset directory and stale variants are removed on boot. The preset
- *    rows name THIS package's built lib files by absolute path, which the
- *    preset mount resolves to `file:` URLs without relying on bare specifier
- *    resolution from the preset's home directory.
+ * 1. Publish a `wsl-<mode>` variant for every healthy roster preset, so the
+ *    WSL execution world — `shell-wsl` + `fs-wsl` behind one entry-local
+ *    realm, with `tool-bash`/`tool-fs` consumers — composes with ANY mode
+ *    instead of being a mode itself. The channel follows the release:
+ *    `0.1.7-alpha.1+` stopped scanning any user preset root and builds its roster
+ *    from declarative `@deepseek-ai/dsh-agent-preset` rows, so there a variant
+ *    is a *declaration registered through `ctx.agentPresets`* — and only that
+ *    path rewrites the absolute provider specifiers below into `file:` URLs,
+ *    because a registered preset's entry tree does not translate them the way
+ *    the boot-time Include does; earlier releases still get a variant directory
+ *    under `<dshHome>/.agent-presets/`, whose legacy standalone `wsl` directory
+ *    and stale variants are removed on boot.
  *
  * 2. Serve the browser dialog's data route (`/wsl-workspace/api`):
  *    distribution discovery, one-level directory listing, path checks, and
@@ -26,8 +29,8 @@
 import { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { cpSync, existsSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, isAbsolute, join } from 'node:path'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { homedir } from 'node:os'
 import { joinUnc, mntToWindowsPath, normalizeLinuxPath, isAbsoluteLinuxPath, isValidWslUsername, parseWslUnc } from './shared/paths.ts'
@@ -47,10 +50,18 @@ export const DEFAULT_ROUTE = '/wsl-workspace/api'
  * preset.yml text verbatim, so the plugin writes one bilingual string so
  * both locales can identify each variant. Custom presets keep their own
  * name.
+ *
+ * This table is consulted before anything the release publishes, so every id
+ * the mode has ever carried needs an entry. `code` was the id up to
+ * `0.1.0-rc.8` and `ptc` is the id from `0.1.1` on; without the `ptc` entry the
+ * lookup returned undefined and the variant fell through to the release's own
+ * display name — which `0.1.7` does not publish at all, leaving the mode named
+ * `WSL · ptc` with the generic description `WSL execution world for ptc: …`.
  */
 const MODE_DISPLAY_LABELS: Readonly<Record<string, { en: string; zh: string }>> = {
   standard: { en: 'Standard mode', zh: '标准模式' },
   code: { en: 'Code mode', zh: 'PTC 模式' },
+  ptc: { en: 'PTC mode', zh: 'PTC 模式' },
   minimal: { en: 'Minimal mode', zh: '极简模式' },
   cordis: { en: 'Creator mode', zh: '创造模式' },
 }
@@ -352,10 +363,149 @@ async function dispatch(method: string, params: Record<string, unknown>): Promis
   }
 }
 
-/** The `ctx.agentPresets` roster face this plugin consumes (optional service). */
+/** One roster entry as the `ctx.agentPresets` face reports it. */
+interface AgentPresetRosterEntry {
+  id: string
+  name?: string
+  description?: string
+  /** Roster position; `list()` sorts by it. */
+  order?: number
+  broken?: string
+  /** Legacy (≤ 0.1.6-alpha.2) only: the source preset's directory. */
+  path?: string
+}
+
+/** One preset's declared composition, as the declaration channel reports it. */
+interface AgentPresetDocument {
+  agentPreset: string
+  /** The declared child plugin list as entry-list YAML, `!!js` expressions included. */
+  content: string
+  name?: string
+  description?: string
+}
+
+/** A declaration this plugin publishes; mirrors the Host's `PresetDefinition`. */
+interface PresetDeclaration {
+  id: string
+  name?: string
+  description?: string
+  order?: number
+  plugins: readonly unknown[]
+}
+
+/**
+ * The `ctx.agentPresets` roster face this plugin consumes (optional service).
+ *
+ * Two generations sit behind this one shape, so both are probed by capability
+ * rather than by version:
+ *
+ *  - `0.1.0-rc.7 … 0.1.6-alpha.2`: `list()` reports each preset's directory in
+ *    `path`, and `read(id)` returns the composition text. A variant is a
+ *    *directory* under the roster's scanned user root (`$DSH_HOME/.agent-presets/`).
+ *  - `0.1.7-alpha.1+`: `read()` is renamed `readDocument()` and returns a document
+ *    instead of a bare string, `AgentPreset.path` is gone, and **nothing scans
+ *    the user root any more** — the roster is built from declarative
+ *    `@deepseek-ai/dsh-agent-preset` rows carried by bundle patches. A variant
+ *    is therefore a declaration row published through `register()`.
+ */
 interface AgentPresetsService {
-  list(): Promise<{ id: string; broken?: string; path: string }[]>
-  read(id: string): Promise<string>
+  list(): Promise<AgentPresetRosterEntry[]>
+  /** Legacy (≤ 0.1.6-alpha.2): the source composition text. */
+  read?(id: string): Promise<string>
+  /** 0.1.7-alpha.1+: the declared composition beside its published metadata. */
+  readDocument?(id: string): Promise<AgentPresetDocument>
+  /** 0.1.7-alpha.1+: publish a declaration; the returned disposer retires it. */
+  register?(definition: PresetDeclaration): Promise<() => Promise<void>>
+}
+
+/**
+ * Read one preset's declared composition across both roster generations.
+ * @param agentPresets - the roster face.
+ * @param preset - the roster entry to read.
+ * @returns the composition text, plus the display name when the face publishes it.
+ */
+async function readPresetComposition(
+  agentPresets: AgentPresetsService,
+  preset: AgentPresetRosterEntry,
+): Promise<{ content: string; name?: string }> {
+  if (typeof agentPresets.readDocument === 'function') {
+    const document = await agentPresets.readDocument(preset.id)
+    return document.name === undefined
+      ? { content: document.content }
+      : { content: document.content, name: document.name }
+  }
+  if (typeof agentPresets.read === 'function') return { content: await agentPresets.read(preset.id) }
+  throw new Error(
+    `agentPresets: this DSH release exposes neither readDocument() nor read() (preset "${preset.id}")`,
+  )
+}
+
+/**
+ * Parse one transformed composition back into declaration rows.
+ *
+ * The composition is the entry-list YAML dialect, whose `!!js` scalars are
+ * expression nodes the Loader evaluates when it activates the row.
+ * `@deepseek-ai/cordis-plugin-include` exports `entryListSchema` precisely so
+ * config tooling can round-trip that dialect, and it is the same schema the
+ * harness parses preset patches with. Parsing the text back is what lets the
+ * (text-level) WSL transform keep working unchanged now that a variant is a
+ * declaration row instead of a directory of YAML.
+ *
+ * Both modules are resolved at call time rather than at module load: they are
+ * Host-provided (`dsh` depends on `cordis-plugin-include`, which depends on
+ * `js-yaml`), and a release that ever drops them must fail this one variant
+ * rather than refuse to load the whole plugin.
+ * @param content - the variant composition text.
+ * @returns the declaration's plugin rows.
+ */
+async function parseVariantComposition(content: string): Promise<unknown[]> {
+  const includeSpecifier = '@deepseek-ai/cordis-plugin-include'
+  const yamlSpecifier = 'js-yaml'
+  const [include, yamlModule] = await Promise.all([
+    import(includeSpecifier) as Promise<{ entryListSchema: unknown }>,
+    import(yamlSpecifier) as Promise<{
+      load?(source: string, options: { schema: unknown }): unknown
+      default?: { load(source: string, options: { schema: unknown }): unknown }
+    }>,
+  ])
+  const load = yamlModule.load ?? yamlModule.default?.load
+  if (typeof load !== 'function') throw new Error('js-yaml: no load() export')
+  const rows = load(content, { schema: include.entryListSchema })
+  if (!Array.isArray(rows)) throw new Error('the transformed composition did not parse as an entry list')
+  return toImportableSpecifiers(rows)
+}
+
+/**
+ * Rewrite every absolute local module specifier as a `file:` URL.
+ *
+ * The generated world names THIS package's built providers (`shell.js`,
+ * `fs.js`, …) by absolute path. That is what the directory mechanism needed:
+ * those rows sat in an Include-backed tree, and the boot-time Include
+ * translates an absolute path into a `file:` URL before importing it. A preset
+ * mounted from a *declaration* is loaded by the registry's own entry tree,
+ * which has no such translation — handing it `C:/…/lib/shell.js` leaves those
+ * rows without a fiber, the audit reports them "never started", and the whole
+ * variant is refused. Rewriting the specifier is therefore part of adapting to
+ * the declaration mechanism, not a change to what the variant mounts.
+ *
+ * Only `name` is touched: config values (the relay path handed to the PTY
+ * backend, the interpreter path in `shellPath`) must stay native filesystem
+ * paths. Group rows carry their children in a `config` array, so those are
+ * walked too.
+ * @param rows - the parsed declaration rows.
+ * @returns the same rows with their module specifiers made importable.
+ */
+function toImportableSpecifiers(rows: unknown[]): unknown[] {
+  const rewrite = (row: unknown): unknown => {
+    if (row === null || typeof row !== 'object') return row
+    const entry = row as { name?: unknown; config?: unknown }
+    if (typeof entry.name === 'string' && isAbsolute(entry.name)) {
+      entry.name = pathToFileURL(entry.name).href
+    }
+    if (Array.isArray(entry.config)) entry.config = entry.config.map(rewrite)
+    return row
+  }
+  return rows.map(rewrite)
 }
 
 /**
@@ -469,6 +619,7 @@ async function materializeVariants(
   dshHome: string,
   paths: { shell: string; fs: string; relay: string; node: string; sandbox: string; search: string; jobs: string },
   persistentShell: boolean,
+  track: (dispose: unknown) => void,
 ): Promise<void> {
   const presets = await agentPresets.list()
   const userRoot = join(dshHome, '.agent-presets')
@@ -477,12 +628,33 @@ async function materializeVariants(
     if (preset.broken !== undefined) continue
     if (isWslVariantId(preset.id)) continue
     const variantId = variantIdFor(preset.id)
-    const source = await agentPresets.read(preset.id)
-    const transformed = transformPresetForWsl(source, paths.shell, paths.fs, persistentShell ? {
+    const composition = await readPresetComposition(agentPresets, preset)
+    const transformed = transformPresetForWsl(composition.content, paths.shell, paths.fs, persistentShell ? {
       relayPath: paths.relay,
       nodePath: paths.node,
       sandboxPath: paths.sandbox,
     } : undefined, paths.search, paths.jobs)
+    // 0.1.7-alpha.1+ publishes a variant as a declaration row (the composition is
+    // already the exact entry-list dialect the declaration wants, so the only
+    // conversion is YAML back to rows); earlier releases still discover one as
+    // a directory under the roster's scanned user root.
+    if (typeof agentPresets.register === 'function') {
+      const plugins = await parseVariantComposition(transformed)
+      // A shipped mode keeps its bilingual label; a custom preset keeps the
+      // display name it published, falling back to its id.
+      const declaration: PresetDeclaration = {
+        id: variantId,
+        name: variantName(preset.id, composition.name ?? preset.name ?? preset.id),
+        description: variantDescription(preset.id),
+        ...(preset.order === undefined ? {} : { order: preset.order }),
+        plugins,
+      }
+      track(await agentPresets.register(declaration))
+      continue
+    }
+    if (preset.path === undefined) {
+      throw new Error(`agentPresets: roster entry "${preset.id}" carries no path on this release`)
+    }
     const dir = join(userRoot, variantId)
     const staging = `${dir}.staging`
     rmSync(staging, { recursive: true, force: true })
@@ -524,15 +696,20 @@ async function materializeVariants(
     publishVariant(staging, dir)
     generated.add(variantId)
   }
-  for (const entry of readdirSync(userRoot, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue
-    if (entry.name === 'wsl') {
-      // The legacy standalone WSL mode: folded into the variants above.
+  // Clean up the retired directory mechanism. `generated` holds the
+  // directories the directory path wrote on THIS boot; from 0.1.7-alpha.1 on it is
+  // always empty, because a variant is a declaration row and the roster no
+  // longer scans this root at all — so every `wsl*` entry left here (the legacy
+  // standalone `wsl` mode included) is inert leftover, and a `wsl-<mode>/`
+  // beside a registered `wsl-<mode>` declaration would only mislead. An absent
+  // root (a fresh install that never used the old mechanism) is not a failure.
+  if (existsSync(userRoot)) {
+    for (const entry of readdirSync(userRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      if (!/^wsl(-[a-z0-9-]+)?$/.test(entry.name)) continue
+      if (generated.has(entry.name)) continue
       rmSync(join(userRoot, entry.name), { recursive: true, force: true })
-      continue
     }
-    if (!/^wsl-[a-z0-9-]+$/.test(entry.name)) continue
-    if (!generated.has(entry.name)) rmSync(join(userRoot, entry.name), { recursive: true, force: true })
   }
 }
 
@@ -576,6 +753,21 @@ export function apply(ctx: Context, config: Config): void {
   const agentPresets = ctx.get('agentPresets') as unknown as AgentPresetsService | undefined
   if (agentPresets !== undefined) {
     ctx.effect(() => {
+      // On 0.1.7-alpha.1+ the variants are declaration rows in Host state rather
+      // than files, so the effect owns their disposers: a plugin unload or hot
+      // reload retires them instead of leaving orphans the next apply could not
+      // replace (`Duplicate agent preset: wsl-<mode>`).
+      let stopped = false
+      const disposers: (() => Promise<void>)[] = []
+      const track = (dispose: unknown): void => {
+        if (typeof dispose !== 'function') return
+        const retire = dispose as () => Promise<void>
+        if (stopped) {
+          void Promise.resolve(retire()).catch(() => {})
+          return
+        }
+        disposers.push(retire)
+      }
       void (async () => {
         const persistentShell = await supportsPersistentShell(ctx)
         await materializeVariants(agentPresets, dshHome, {
@@ -586,14 +778,19 @@ export function apply(ctx: Context, config: Config): void {
           sandbox: sandboxPath,
           search: searchPath,
           jobs: jobsPath,
-        }, persistentShell)
+        }, persistentShell, track)
       })().catch((error) => {
         // Variant generation is best-effort over a live roster: a missing or
         // unreadable source preset must not take the whole plugin down, but
         // the failure is surfaced loudly rather than hidden.
         console.error(`dsh-wsl-workspace: WSL preset-variant generation failed: ${messageOf(error)}`)
       })
-      return () => {}
+      return () => {
+        stopped = true
+        for (const retire of disposers.splice(0, disposers.length)) {
+          void Promise.resolve(retire()).catch(() => {})
+        }
+      }
     }, 'dsh-wsl-workspace: WSL preset variants')
   }