dsh-wsl-tool 1.10.10 → 1.10.11

package/README.md

@@ -119,6 +119,13 @@ specifier you install under.
 
 3. Restart DSH.
 
+The settings panel is the one optional piece: its form needs
+`@deepseek-ai/schemastery`, which most profiles already have (any plugin that
+depends on it brings it in — add it to the profile's dependencies if yours does
+not). Without it, the three tools and the panel's 「WSL 终端启动路径」 field work
+as usual and only the switches are absent — the panel says so instead of waiting
+forever.
+
 ## Compatibility
 
 Verified against DSH **0.1.7-rc.2** (and 0.1.5-rc.2 before it): the tool schemas
@@ -149,7 +156,9 @@ explanation.
 | `wsl-env` 能力体检 | registers the `wsl-env` tool |
 | 后台任务 | whether `wsl` accepts `runInBackground` |
 | 自动转换路径 | the default for the per-call `translatePaths` |
-| 默认跟随会话工作区 | start in the session's directory instead of `~` when `workdir` is omitted |
+| 默认跟随会话工作区 | start in the session's directory instead of `~` when `workdir` is omitted. **On by default**: with it off, every relative path an agent writes lands in the Linux home, which is invisible from Explorer and grows the WSL disk image |
+| Linux 默认工作目录 | a fixed Linux directory (for example `/mnt/d/project`) used when `workdir` is omitted. Filling it in wins over the switch above; clearing it goes back to following the session |
+| WSL 终端启动路径 | the optional sidebar terminal's startup directory — `--cd <dir>` on the `terminal-controller` row of your **profile patch** (see [Optional: a WSL terminal in the sidebar](#optional-a-wsl-terminal-in-the-sidebar)). Empty clears it, and the panel reads the current value from the same file |
 | 危险命令守卫 | whether a destructive command needs an explicit `allowDangerous` |
 
 The panel edits the plugin's own configuration, so the same values can be written
@@ -159,6 +168,11 @@ environment, then the built-in defaults** — and a switch left at its default l
 the layer below decide, which is why `DSH_WSL_WORKDIR=session` keeps working for
 someone who never opened the panel.
 
+「WSL 终端启动路径」 is the one exception: the sidebar terminal belongs to another
+plugin, so that field edits your profile's patch layer instead — the file is backed
+up before every write, only the terminal row's `args` line is rewritten, and the
+result is read back and undone if it is not exactly that one line.
+
 **A change takes effect at the next DSH start**: the host reads this configuration
 once per mount, and the panel says so. Distro and timeout are values rather than
 features — set them in the patch or with `DSH_WSL_DISTRO` / `DSH_WSL_TIMEOUT_MS`,
@@ -188,6 +202,14 @@ To turn it on, copy that entry into your profile's own patch layer
 (`$DSH_HOME/profiles/<profile>/cordis.patch.yml`); a CLI launch can instead pass
 `--patch <path to the installed file>`. It applies at the next app start.
 
+The panel can set the startup directory for you: 「WSL 终端启动路径」 (beside 「默认
+Linux 工作目录」) reads the current value out of that file and writes `--cd <dir>` onto
+the row's `args` line — backing the patch up first, changing only that one line, and
+checking what landed before it is kept. Clearing the field removes the flag, which puts
+the terminal back on the session workspace (the Windows directory it is started from,
+translated to `/mnt/…`); `~` pins it to the Linux home. It takes effect at the next app
+start too.
+
 ```yaml
 - id: terminal-controller
   config:

package/README.zh-CN.md

@@ -103,6 +103,10 @@ launcher: WSL 版本: 2.6.3.0 · 内核版本: 6.6.87.2-1 · WSLg 版本: 1.0.71
 
 3. 重启 DSH。
 
+设置面板是唯一可选的一块：它的表单需要 `@deepseek-ai/schemastery`，多数 profile 已经有了
+（只要装过任何依赖它的插件；没有的话把它加进 profile 的依赖即可）。没有它时，三个工具与
+面板里的「WSL 终端启动路径」照常可用，只是开关不显示 —— 面板会直接说明这一点，不会一直转圈等待。
+
 ## 兼容性
 
 已在 DSH **0.1.7-rc.2** 上验证（此前为 0.1.5-rc.2）：工具 schema 通过 DSH 自己的
@@ -130,13 +134,19 @@ DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
 | `wsl-env` 能力体检 | 是否注册 `wsl-env` 工具 |
 | 后台任务 | `wsl` 是否接受 `runInBackground` |
 | 自动转换路径 | 每次调用的 `translatePaths` 默认值 |
-| 默认跟随会话工作区 | 未传 `workdir` 时从会话目录开始，而不是 `~` |
+| 默认跟随会话工作区 | 未传 `workdir` 时从会话目录开始，而不是 `~`。**默认开**：关掉的话，agent 写的相对路径都会落进 Linux 家目录 —— 那儿在资源管理器里看不见，还会撑大 WSL 磁盘镜像 |
+| Linux 默认工作目录 | 未传 `workdir` 时使用的固定 Linux 目录（如 `/mnt/d/project`）。填了就优先于上面的开关；清空则回到跟随会话 |
+| WSL 终端启动路径 | 可选的侧边栏终端从哪个目录启动 —— 写进你 **profile patch** 里 `terminal-controller` 那一行的 `--cd <目录>`（见[可选：在侧边栏开一个 WSL 终端](#可选在侧边栏开一个-wsl-终端)）。留空则删掉该参数；当前值也是从这个文件读的 |
 | 危险命令守卫 | 危险命令是否必须显式 `allowDangerous` |
 
 面板改的是插件自己的配置，所以同样的值也可以手写进 profile patch（`- id: tool-wsl` 加 `config:`）
 或用环境变量设。优先级由 `lib/config.js` 定：**插件配置 > 环境变量 > 内置默认值**；开关停在默认值时
 下层说了算 —— 这正是"从没打开过面板的人，`DSH_WSL_WORKDIR=session` 依然生效"的原因。
 
+「WSL 终端启动路径」是唯一的例外：侧边栏终端属于另一个插件，所以那个输入框改的是你 profile 的
+patch 层 —— 每次写入前先备份该文件，只重写终端那一行的 `args`，写后还会读回来核对，只要不是"只改了
+这一行"就当场还原。
+
 **改动在下次启动 DSH 后生效**：宿主每次挂载只读一次该配置，面板里也写着这句。发行版与超时属于"值"
 而不是"功能"：在 patch 里或用 `DSH_WSL_DISTRO` / `DSH_WSL_TIMEOUT_MS` 设置，面板只显示当前生效值。
 
@@ -158,6 +168,11 @@ DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
 （`$DSH_HOME/profiles/<profile>/cordis.patch.yml`）；命令行启动也可以改成
 `--patch <已安装文件路径>`。**下次启动应用时生效。**
 
+这个启动目录也能在面板里设：顶部的「WSL 终端启动路径」（挨着「默认 Linux 工作目录」）会从那个
+文件读出当前值，再把 `--cd <目录>` 写到该行 `args` 上 —— 写前先备份 patch 文件，只改这一行，
+写后读回来核对。**清空**则删掉该参数，终端回到跟随会话工作区（启动时的 Windows 目录会被翻译成
+`/mnt/…`）；填 `~` 固定到 Linux 家目录。改完同样**重启 DSH 生效**。
+
 ```yaml
 - id: terminal-controller
   config:

package/SUPPORT.md

@@ -0,0 +1,36 @@
+# 支持与反馈 / Support and feedback
+
+这个插件只有一个维护者，所以"发对地方"能省掉一轮来回。
+This plugin has one maintainer, so getting the report to the right place saves a round trip.
+
+## 去哪儿反馈什么 / Where to report what
+
+| 你遇到的问题 / What you hit | 发到哪儿 / Where |
+|---|---|
+| **插件的 bug**：命令失败、路径转换不对、面板开关无效、后台任务异常… / A **plugin** bug | **[本仓库的 Issue](https://github.com/XINY11451/dsh-wsl/issues/new/choose)**（有模板，会问你环境）/ **Issues here** (templates ask for the environment) |
+| **功能建议**：想要一个新能力 / A **feature request** | **[本仓库的 Issue](https://github.com/XINY11451/dsh-wsl/issues/new/choose)**，选「功能建议」模板 / Issues here, the feature template |
+| **用法问题、想法、经验分享** / Usage questions, ideas, war stories | **[Discussions](https://github.com/XINY11451/dsh-wsl/discussions)** |
+| **DSH 本体的问题**（与 WSL 无关的界面、会话、模型…）/ **DSH itself** | [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness/issues) |
+| **插件市场的界面问题**（浏览、安装按钮、列表渲染…）/ The **market UI** | [dsh-market](https://github.com/dsh-market/dsh-market/issues) |
+| **收录/目录问题**（列表文案、分类、截图没更新…）/ The **catalog listing** | [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/issues) —— 注意：那里的 Issue 只处理列表与站点本身，插件 bug 发过去会被关掉 / Note: Issues there cover the list and its site only; plugin bugs are closed |
+
+## 提交 bug 前，先把这几件事准备好 / Before filing a bug
+
+1. **插件版本** —— 面板底部的「复制插件信息」会替你读出来（来自 `package.json`），或 `npm ls dsh-wsl-tool` / The plugin version, read out by 「复制插件信息」 in the panel (from `package.json`), or `npm ls dsh-wsl-tool`
+2. **DSH 版本** —— 同一个按钮也会读出来（从应用自己的 manifest），设置里也能看到 / The same button reads it out (from the application's own manifest); Settings shows it too
+3. **WSL 发行版与内核** —— 同一个按钮会替你探测（默认发行版、内核、systemd/docker/GPU 等能力标记）；也可用 `wsl -l -v` 或 `wsl-env` 工具 / The same button probes them (default distribution, kernel, capability flags such as systemd, docker and GPU); `wsl -l -v` or one `wsl-env` call work too
+4. **原文**：完整命令、完整报错、界面上出现的话 —— 不要转述 / The exact command, the exact error, the exact UI text — not a paraphrase
+
+侧边栏面板底部是**一个**反馈入口：旁边写着提交指南（标题怎么起、正文写哪三段、粘到哪个字段），以及一个「复制插件信息」按钮。点它会由宿主半**自动读取**：包名、版本、仓库（来自本包的 `package.json`）、Node 与平台、它正运行在哪个 DSH 构建里、以及 WSL 的默认发行版/内核/能力标记 —— 再配上当前生效的配置和各开关状态，一次复制完。粘进 Issue 的「补充」栏即可。读取要跑几次 WSL 探测，所以按钮会先显示「正在读取…」；读不到的项会写明"未能读取"，不会编造。它**不会**自己发送任何东西。
+The panel ends with **one** feedback entry: a submission guide beside it (how to title it, which three paragraphs the body needs, which field to paste into) and a 「复制插件信息」 button. The host half **reads it all in**: package name, version and repository (from this package's `package.json`), Node and the platform, the DSH build it is running inside, and WSL's default distribution, kernel and capability flags — plus the effective configuration and the switch states. Paste that into the issue's 「补充」 field. A few WSL probes run first, so the button reads 「正在读取…」; anything unreadable says so instead of guessing. It sends nothing by itself.
+
+## 关于隐私 / Privacy
+
+- 插件**不做任何静默上报**：不点反馈入口，就不会有网络请求。/ The plugin reports nothing by itself — no request happens unless you open the feedback entry.
+- 面板复制出来的文本只含**版本号、包名、仓库、Node 与平台、发行版名、超时，以及你面板里各开关的状态**；不含完整路径、主机名、用户名或任何凭据。/ The copied block contains versions, the package name, the repository, Node and the platform, the distribution name, the timeout and your switch states — no full paths, host names, user names or credentials.
+- Issue 是**公开**的。提交前请自己过一眼，把不想公开的删掉。/ Issues are **public**. Read it once before submitting and delete what you would rather not publish.
+
+## 修复的节奏 / How fixes happen
+
+报告 → 复现（必要时我会请你补 `wsl-env` 输出）→ 改代码 → 测试（这个插件有 347 项宿主检查 + 76 项客户端检查）→ 发版（npm + 市场资产同一次发布，逐字节一致）→ 你升级后回帖确认 → 关闭。
+Report → reproduce (I may ask for a full `wsl-env`) → fix → tests (the plugin ships with 347 host checks and 76 client checks) → release (npm and the market asset go out byte-identical in one run) → you confirm after upgrading → close.

package/index.js

@@ -21,14 +21,15 @@
 // A configuration change is a mount, not something a running session re-reads:
 // every switch below is consulted once, in `apply`.
 
-import { readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { copyFileSync, existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
 
 import { CAPABILITY_PROBE, capabilityLines, parseFacts } from './lib/diagnostics.js'
 import { parseDefaultDistro } from './lib/tools/wsl-env.js'
 import { resolveConfig } from './lib/config.js'
 import { pickSchemaBuilder } from './lib/schema.js'
 import { createRunner } from './lib/runner.js'
+import { readTerminalCwd, reviewTerminalWrite, writeTerminalCwd } from './lib/terminal-cwd.js'
 import { createWslTool } from './lib/tools/wsl.js'
 import { createWslPathTool } from './lib/tools/wsl-path.js'
 import { createWslEnvTool } from './lib/tools/wsl-env.js'
@@ -85,16 +86,17 @@ if (Schema === null) {
  */
 export const Config = Schema?.object({
   tools: Schema.object({
-    wsl: Schema.boolean().default(true).description('注册 `wsl` 工具：在 WSL 里执行 Linux 命令。').volatile(),
-    path: Schema.boolean().default(true).description('注册 `wsl-path` 工具：Windows 路径与 /mnt/... 互转。').volatile(),
-    env: Schema.boolean().default(true).description('注册 `wsl-env` 工具：汇总 WSL 环境能力。').volatile(),
-  }).description('要注册哪几个工具；这三个开关在下次启动 DSH 后生效。'),
-  backgroundJobs: Schema.boolean().default(true).description('允许 `runInBackground`，由内置 job 工具读回结果。').volatile(),
-  translatePaths: Schema.boolean().default(true).description('默认把命令里的 Windows 路径转成 /mnt/...。').volatile(),
-  startInSessionWorkspace: Schema.boolean().default(false).description('未传 `workdir` 时从会话工作区开始，而不是 Linux 家目录。').volatile(),
-  dangerGuard: Schema.boolean().default(true).description('危险命令必须显式 `allowDangerous` 才放行。关掉后模型可直接删除/分区。').volatile(),
-  distro: Schema.string().default('').description('要固定使用的发行版；留空则用系统默认（也可用 DSH_WSL_DISTRO）。').volatile(),
-  timeoutMs: Schema.number().default(0).description('默认命令超时毫秒数；0 表示用内置默认（也可用 DSH_WSL_TIMEOUT_MS）。').volatile(),
+    wsl: Schema.boolean().default(true).description('注册 `wsl` 工具：在 WSL 发行版中执行 Linux 命令。').volatile(),
+    path: Schema.boolean().default(true).description('注册 `wsl-path` 工具：在 Windows 路径与 `/mnt/...` 之间互转。').volatile(),
+    env: Schema.boolean().default(true).description('注册 `wsl-env` 工具：汇总发行版、内核、systemd、cgroup、GPU 直通、docker 与挂载盘。').volatile(),
+  }).description('要注册哪些工具；这三项在重启 DSH 后生效。'),
+  backgroundJobs: Schema.boolean().default(true).description('允许长任务以 `runInBackground` 后台执行，结果由内置 job 工具读取。').volatile(),
+  translatePaths: Schema.boolean().default(true).description('命令中的 Windows 路径默认转为 `/mnt/...`。').volatile(),
+  startInSessionWorkspace: Schema.boolean().default(true).description('未传 `workdir` 时从会话目录启动；默认开。关闭后使用下方固定目录，该目录留空时为家目录 `~`。').volatile(),
+  workdir: Schema.string().default('').description('未传 `workdir` 时使用的固定 Linux 目录（如 `/mnt/d/project`），优先于「跟随会话工作区」；留空表示不指定。').volatile(),
+  dangerGuard: Schema.boolean().default(true).description('危险命令（删除、分区、关机等）需显式 `allowDangerous` 才放行；关闭后模型可直接执行。').volatile(),
+  distro: Schema.string().default('').description('固定使用的发行版；留空表示使用系统默认（也可用 `DSH_WSL_DISTRO`）。').volatile(),
+  timeoutMs: Schema.number().default(0).description('默认命令超时（毫秒）；0 表示使用内置默认（也可用 `DSH_WSL_TIMEOUT_MS`）。').volatile(),
 }).description('dsh-wsl 的功能开关与默认值。')
 
 /**
@@ -103,6 +105,373 @@ export const Config = Schema?.object({
  */
 const INFO_ROUTE = '/dsh-wsl-tool/info'
 
+/**
+ * The sidebar terminal's startup directory, as one GET/POST pair.
+ *
+ * That value does NOT live in this plugin's configuration: the 新建终端 shell belongs
+ * to another plugin, and only the profile's own patch layer can override its `args`.
+ * So the panel edits that file through these routes, and `lib/terminal-cwd.js` owns the
+ * rules for doing it safely (one line, backed up first, read back afterwards).
+ *
+ * `GET`  -> `{ path, available, error }`: what the patch says now, and whether the
+ *           terminal row is there at all (`available: false` means the opt-in has not
+ *           been applied, which is a different instruction than an empty value).
+ * `POST` -> `{ ok, path, error }`, body `{ path }`; `path: ''` removes the flag.
+ */
+const TERMINAL_ROUTE = '/dsh-wsl-tool/terminal-cwd'
+
+/** The profile patch layer this plugin reads and edits, under `DSH_PROFILE_DIR`. */
+const PATCH_FILE_NAME = 'cordis.patch.yml'
+
+/**
+ * The profile patch this process was started with, or `null` when it cannot be found.
+ *
+ * The host's own answer comes first: `profileContext.patchPath` is the file the platform's
+ * settings UI edits — `dsh-app-boot` and `dsh-config-editor` both read it, and it is the
+ * only reliable source. `DSH_PROFILE_DIR` is injected into MODEL TOOL subprocesses, not
+ * into the desktop host process itself: measured, the host answered "no DSH_PROFILE_DIR"
+ * while the profile patch sat exactly where it belonged. The environment therefore stays
+ * as a fallback for a test or a host without that service, never as the primary.
+ *
+ * Read at REQUEST time rather than captured at mount: the value belongs to the host, and a
+ * request that cannot name a file must say so instead of writing to a path from boot.
+ */
+function resolvePatchFile(ctx, env) {
+  let service
+  try {
+    service = ctx === undefined || ctx === null || typeof ctx.get !== 'function'
+      ? undefined
+      : ctx.get('profileContext')
+  } catch {
+    service = undefined
+  }
+  const patchPath = service === undefined || service === null ? undefined : service.patchPath
+  if (typeof patchPath === 'string' && patchPath.trim() !== '') return patchPath.trim()
+  const dir = env === undefined || env === null ? undefined : env.DSH_PROFILE_DIR
+  if (typeof dir === 'string' && dir.trim() !== '') return join(dir.trim(), PATCH_FILE_NAME)
+  return null
+}
+
+/** Why the file could not be named, worded so the next reader knows where to look. */
+const NO_PATCH_ERROR = '宿主既没有 profileContext.patchPath 也没有 DSH_PROFILE_DIR，读不到 profile 的 patch 文件'
+
+/** A body past this is not a path; refuse it instead of buffering whatever arrives. */
+const MAX_TERMINAL_BODY_BYTES = 4096
+
+/**
+ * How many of THIS plugin's own backups to keep beside the patch.
+ *
+ * One backup per save is the point — the file is the user's composition — but leaving
+ * every one of them forever would litter the profile directory. Old ones are pruned by
+ * age, and only files matching the exact name this plugin writes are ever considered.
+ */
+const MAX_PATCH_BACKUPS = 10
+
+/**
+ * `cordis.patch.yml.bak-YYYYMMDD-HHMMSSmmm` (with a `-N` counter as a last resort).
+ *
+ * The millisecond field is not cosmetic: pruning FREES names, and without it the next
+ * save reuses the un-suffixed name of the second — so a freed (old) name would sort as
+ * the newest and the wrong backup would be deleted. The older name without milliseconds is
+ * still recognized, so backups written by a previous build are pruned by the same rule.
+ */
+const BACKUP_NAME_RE = /\.bak-(\d{8})-(\d{6})(\d{3})?(?:-(\d+))?$/
+
+/**
+ * The chronological key a backup name carries: fixed-width stamp text, then the counter.
+ *
+ * A string, not a number: `YYYYMMDDHHMMSSmmm` is 17 digits, past what a double holds
+ * exactly, and fixed width means plain string comparison IS chronological.
+ */
+function backupOrder(name) {
+  const match = BACKUP_NAME_RE.exec(name)
+  if (match === null) return { stamp: '', counter: 0 }
+  return {
+    stamp: `${match[1]}${match[2]}${match[3] ?? '000'}`,
+    counter: match[4] === undefined ? 1 : Number(match[4]),
+  }
+}
+
+function answerJson(response, code, payload) {
+  response.writeHead(code, {
+    'content-type': 'application/json; charset=utf-8',
+    // A value that was just read or written must describe this moment, not a cached one.
+    'cache-control': 'no-store',
+  })
+  response.end(JSON.stringify(payload))
+}
+
+/** One request header, from a node:http request or a fetch-style request object. */
+function requestHeader(request, name) {
+  const headers = request === undefined || request === null ? undefined : request.headers
+  if (headers === undefined || headers === null) return ''
+  const value = typeof headers.get === 'function' ? headers.get(name) : headers[name.toLowerCase()]
+  return typeof value === 'string' ? value : ''
+}
+
+/** Read one bounded JSON object body. @returns `{ value }` or `{ error }`. */
+function readJsonBody(request, limit = MAX_TERMINAL_BODY_BYTES) {
+  return new Promise((resolve) => {
+    if (request === null || typeof request.on !== 'function') {
+      resolve({ error: '读不到请求体' })
+      return
+    }
+    const chunks = []
+    let size = 0
+    let settled = false
+    const finish = (result) => {
+      if (!settled) {
+        settled = true
+        resolve(result)
+      }
+    }
+    request.on('data', (chunk) => {
+      size += chunk.length
+      if (size > limit) {
+        finish({ error: `请求体超过 ${limit} 字节` })
+        return
+      }
+      chunks.push(chunk)
+    })
+    request.on('end', () => {
+      const text = Buffer.concat(chunks).toString('utf8').trim()
+      if (text === '') {
+        finish({ error: '请求体是空的' })
+        return
+      }
+      let parsed
+      try {
+        parsed = JSON.parse(text)
+      } catch {
+        finish({ error: '请求体不是合法 JSON' })
+        return
+      }
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        finish({ error: '请求体必须是一个 JSON 对象' })
+        return
+      }
+      finish({ value: parsed })
+    })
+    request.on('error', () => finish({ error: '读取请求体失败' }))
+  })
+}
+
+/**
+ * Copy the patch next to itself before touching it.
+ *
+ * The file is the user's own composition: an edit that turns out badly has to be
+ * recoverable by hand even if this process dies mid-write. The stamp carries milliseconds
+ * (with a counter as a last resort), and no colons, because Windows refuses those in a
+ * file name.
+ */
+function backupPatchFile(file) {
+  const iso = new Date().toISOString()
+  // 20261005-144428123, no colons: Windows refuses them in a file name.
+  const stamp = `${iso.slice(0, 10).replace(/-/g, '')}-${iso.slice(11, 19).replace(/:/g, '')}${iso.slice(20, 23)}`
+  let target = `${file}.bak-${stamp}`
+  let suffix = 2
+  while (existsSync(target)) {
+    target = `${file}.bak-${stamp}-${suffix}`
+    suffix += 1
+  }
+  copyFileSync(file, target)
+  return target
+}
+
+/**
+ * Keep the newest {@link MAX_PATCH_BACKUPS} backups of one patch, delete the rest.
+ *
+ * Deliberately conservative: a file is a candidate only when its name starts with this
+ * patch's name and matches the exact stamp format above, so a `.bak` the user made by
+ * hand (or another patch's backup) is never touched. `keep` is the backup that was just
+ * written and is never a candidate, whatever the mtimes say. Never throws — a backup that
+ * could not be pruned is a tidiness problem, not a reason to fail a save.
+ */
+function prunePatchBackups(file, keep) {
+  const dir = dirname(file)
+  const prefix = `${basename(file)}.bak-`
+  const protectedName = typeof keep === 'string' ? basename(keep) : ''
+  let names
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return
+  }
+  const mine = []
+  for (const name of names) {
+    if (name === protectedName) continue
+    if (!name.startsWith(prefix) || !BACKUP_NAME_RE.test(name)) continue
+    let time = 0
+    try {
+      time = statSync(join(dir, name)).mtimeMs
+    } catch {
+      // Raced away (or unreadable): it cannot be ordered, so treat it as the oldest.
+    }
+    mine.push({ name, time, order: backupOrder(name) })
+  }
+  // The backup just written counts against the budget too, so the total on disk never
+  // exceeds the cap.
+  const reserved = protectedName !== '' && names.includes(protectedName) ? 1 : 0
+  const budget = MAX_PATCH_BACKUPS - reserved
+  if (mine.length <= budget) return
+  // Newest first by mtime, with the name's own timestamp as the tie-break so a burst of
+  // saves in one clock tick still has a defined order.
+  mine.sort((left, right) => {
+    if (right.time !== left.time) return right.time - left.time
+    if (left.order.stamp !== right.order.stamp) return left.order.stamp < right.order.stamp ? 1 : -1
+    return right.order.counter - left.order.counter
+  })
+  for (const entry of mine.slice(budget)) {
+    try {
+      rmSync(join(dir, entry.name), { force: true })
+    } catch (error) {
+      console.warn('dsh-wsl-tool: could not prune an old profile-patch backup', error)
+    }
+  }
+}
+
+/**
+ * Serve the terminal startup directory.
+ *
+ * Takes the host context because the file's location comes from it
+ * (`profileContext.patchPath`). Never throws: every failure becomes a structured answer the
+ * panel can show, because a 500 here would take the panel's field down without saying why.
+ */
+async function serveTerminalCwd(ctx, request, response) {
+  const file = resolvePatchFile(ctx, process.env)
+  if (file === null) {
+    answerJson(response, 200, { ok: false, path: '', available: false, error: NO_PATCH_ERROR })
+    return
+  }
+
+  if (request.method === 'GET') {
+    let text
+    try {
+      text = readFileSync(file, 'utf8')
+    } catch {
+      answerJson(response, 200, { path: '', available: false, error: `读不到 ${PATCH_FILE_NAME}` })
+      return
+    }
+    const read = readTerminalCwd(text)
+    answerJson(response, 200, { path: read.path, available: read.row, error: read.error })
+    return
+  }
+
+  if (request.method !== 'POST') {
+    response.writeHead(405, { allow: 'GET, POST' })
+    response.end()
+    return
+  }
+
+  // This route WRITES a file in the user's profile, and the host's web server carries no
+  // origin policy of its own (its README: "route owners … enforce their own request
+  // policy"). Requiring the JSON content type is the same gate the platform's own upload
+  // route uses: `application/json` is not a CORS-safelisted content type, so a cross-site
+  // page can only send it after a preflight — and this server answers no preflight — while
+  // a form or a `no-cors` fetch cannot set it at all. The panel is same-origin and already
+  // sends it, so this costs an honest caller nothing and keeps a hostile page from
+  // rewriting the patch.
+  const contentType = requestHeader(request, 'content-type')
+  if (!/^application\/json\s*(?:;|$)/i.test(contentType)) {
+    answerJson(response, 415, { ok: false, path: '', error: '请求必须是 application/json' })
+    return
+  }
+
+  const body = await readJsonBody(request)
+  if (body.error !== undefined) {
+    answerJson(response, 400, { ok: false, path: '', error: body.error })
+    return
+  }
+  if (typeof body.value.path !== 'string') {
+    answerJson(response, 400, { ok: false, path: '', error: '请求体里需要一个字符串字段 path' })
+    return
+  }
+
+  let original
+  try {
+    original = readFileSync(file, 'utf8')
+  } catch {
+    answerJson(response, 200, { ok: false, path: '', error: `读不到 ${PATCH_FILE_NAME}` })
+    return
+  }
+
+  // Bad input (a line break, a quote) and an unrecognized file both stop HERE, with the
+  // file still byte-for-byte what it was.
+  const next = writeTerminalCwd(original, body.value.path)
+  if (!next.ok) {
+    answerJson(response, 200, {
+      ok: false,
+      path: readTerminalCwd(original).path,
+      error: next.error,
+    })
+    return
+  }
+  if (next.text === original) {
+    // Already what was asked for: no write, and no backup for a no-op.
+    answerJson(response, 200, { ok: true, path: next.path, error: null })
+    return
+  }
+
+  let backup
+  try {
+    backup = backupPatchFile(file)
+  } catch (error) {
+    console.warn('dsh-wsl-tool: could not back up the profile patch', error)
+    answerJson(response, 200, {
+      ok: false,
+      path: readTerminalCwd(original).path,
+      error: '备份 profile patch 失败，未改动文件',
+    })
+    return
+  }
+  prunePatchBackups(file, backup)
+
+  try {
+    writeFileSync(file, next.text, 'utf8')
+  } catch (error) {
+    console.warn('dsh-wsl-tool: writing the profile patch failed', error)
+    answerJson(response, 200, {
+      ok: false,
+      path: readTerminalCwd(original).path,
+      error: '写入 profile patch 失败',
+    })
+    return
+  }
+
+  // Read back what actually landed. Anything other than exactly one changed line is
+  // undone from the copy held in memory, so a surprise never stays in the user's file —
+  // unless the file is no longer our text at all, which means somebody else wrote to it
+  // after us and their version must not be overwritten.
+  let written = null
+  try {
+    written = readFileSync(file, 'utf8')
+  } catch {
+    written = null
+  }
+  const review = reviewTerminalWrite(original, written, next.text, next.path)
+  if (review.verdict === 'conflict') {
+    answerJson(response, 200, { ok: false, path: '', error: review.error })
+    return
+  }
+  if (review.verdict === 'undo') {
+    let restored = true
+    try {
+      writeFileSync(file, original, 'utf8')
+    } catch (error) {
+      console.error('dsh-wsl-tool: could not restore the profile patch', error)
+      restored = false
+    }
+    answerJson(response, 200, {
+      ok: false,
+      path: readTerminalCwd(original).path,
+      error: `写入校验失败（${review.error}）${restored ? '，已还原' : '，且还原失败，请从备份恢复'}`,
+    })
+    return
+  }
+
+  answerJson(response, 200, { ok: true, path: next.path, error: null })
+}
+
 /** Read this package's own manifest once; a broken manifest must not break the route. */
 let manifestCache
 function readManifest() {
@@ -247,39 +616,41 @@ export function apply(ctx, settings = {}) {
       ctx.inject(['webServer'], (inner) => {
         const webServer = inner.webServer
         if (webServer === undefined || webServer === null || typeof webServer.register !== 'function') return
-        const disposer = webServer.register({
-          kind: 'exact',
-          path: INFO_ROUTE,
-          handler: async (request, response) => {
-            if (request.method !== 'GET') {
-              response.writeHead(405, { allow: 'GET' })
-              response.end()
-              return
-            }
-            let body
-            try {
-              // The WSL probes cost a few WSL round trips; they run concurrently and
-              // every one of them may fail without failing the request.
-              body = JSON.stringify(await selfInfo(config, runner))
-            } catch (error) {
-              console.warn('dsh-wsl-tool: reading self info failed', error)
-              body = JSON.stringify({ name: 'dsh-wsl-tool', version: null, dsh: null, wsl: null })
-            }
-            response.writeHead(200, {
-              'content-type': 'application/json; charset=utf-8',
-              // A copied block must describe this moment, not a cached one.
-              'cache-control': 'no-store',
-            })
-            response.end(body)
-          },
-        })
-        if (typeof inner.effect === 'function') {
-          inner.effect(() => disposer, 'dsh-wsl-tool: self-info route')
+        // Two routes, published together: the read-only self info, and the terminal
+        // startup directory the panel reads and writes. Both are optional — an older
+        // host without `webServer` simply gets no panel features that need one.
+        const publish = (path, handler, label) => {
+          const disposer = webServer.register({ kind: 'exact', path, handler })
+          if (typeof inner.effect === 'function') inner.effect(() => disposer, label)
         }
+        publish(INFO_ROUTE, async (request, response) => {
+          if (request.method !== 'GET') {
+            response.writeHead(405, { allow: 'GET' })
+            response.end()
+            return
+          }
+          let body
+          try {
+            // The WSL probes cost a few WSL round trips; they run concurrently and
+            // every one of them may fail without failing the request.
+            body = JSON.stringify(await selfInfo(config, runner))
+          } catch (error) {
+            console.warn('dsh-wsl-tool: reading self info failed', error)
+            body = JSON.stringify({ name: 'dsh-wsl-tool', version: null, dsh: null, wsl: null })
+          }
+          response.writeHead(200, {
+            'content-type': 'application/json; charset=utf-8',
+            // A copied block must describe this moment, not a cached one.
+            'cache-control': 'no-store',
+          })
+          response.end(body)
+        }, 'dsh-wsl-tool: self-info route')
+        publish(TERMINAL_ROUTE, (request, response) => serveTerminalCwd(ctx, request, response),
+          'dsh-wsl-tool: terminal-cwd route')
       })
     }
   } catch (error) {
-    console.warn('dsh-wsl-tool: could not publish the self-info route', error)
+    console.warn('dsh-wsl-tool: could not publish the plugin routes', error)
   }
 
   // A volatile edit is written into the same object the loader handed us and then