dsh-disk-cleaner 1.6.5 → 1.6.6

package/README.md

@@ -5,7 +5,7 @@
 <!-- badges -->
 | | |
 | --- | --- |
-| **version** | `1.6.5` |
+| **version** | `1.6.6` |
 | **DSH** | `0.2.1-rc.5`（开发与实测版本；用到 `plugins.bundle.config`、`settings.section`） |
 | **license** | [MIT](LICENSE) |
 | **Node** | `>= 22`（仅运行冒烟测试需要） |
@@ -166,16 +166,16 @@ These are enforced in `lib/catalog.js` and must not be relaxed:
 
 Listed in the curated [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) catalog, which powers **dshmarket → Discover** ([PR #12970](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/12970), merged): search **dsh-disk-cleaner** there and install it in one click. The direct installs below do the same thing by hand.
 
-Published on npm as [`dsh-disk-cleaner`](https://www.npmjs.com/package/dsh-disk-cleaner) — latest `1.6.5`:
+Published on npm as [`dsh-disk-cleaner`](https://www.npmjs.com/package/dsh-disk-cleaner) — latest `1.6.6`:
 
 ```bash
 npm i dsh-disk-cleaner
 ```
 
-A prebuilt tarball is attached to the [v1.6.5 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.5); installing from it skips DSH's build-approval step:
+A prebuilt tarball is attached to the [v1.6.6 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.6); installing from it skips DSH's build-approval step:
 
 ```bash
-dsh plugin --profile <profile> add https://github.com/stallenlu/dsh-disk-cleaner/releases/download/v1.6.5/dsh-disk-cleaner-1.6.5.tgz
+dsh plugin --profile <profile> add https://github.com/stallenlu/dsh-disk-cleaner/releases/download/v1.6.6/dsh-disk-cleaner-1.6.6.tgz
 ```
 
 Then enable it in the profile — in `$DSH_PROFILE_DIR/package.json`:
@@ -183,7 +183,7 @@ Then enable it in the profile — in `$DSH_PROFILE_DIR/package.json`:
 ```json
 {
   "dependencies": {
-    "dsh-disk-cleaner": "^1.6.5"
+    "dsh-disk-cleaner": "^1.6.6"
   },
   "dsh": {
     "profile": {
@@ -204,7 +204,7 @@ The bundle's own `cordis.patch.yml` inserts the plugin row; no profile patch edi
 ### Development
 
 ```bash
-node smoke.mjs                       # 98 assertions, zero dependencies
+node smoke.mjs                       # 110 assertions, zero dependencies
 node --check lib/client.js           # and lib/index.js, lib/catalog.js, lib/audit.js, lib/plan.js
 ```
 
@@ -258,22 +258,23 @@ What the smoke test deliberately does **not** cover: anything that walks a real
 ```
 ├─ package.json           dsh.bundle.patch + dsh.client { platform: "web" }
 ├─ cordis.patch.yml       - insert:  id: dsh-disk-cleaner
-├─ lib/index.js    (434)  Host: HTTP route + disk_cleaner tool, same run() for both; reveal
+├─ lib/index.js    (482)  Host: HTTP route + disk_cleaner tool, same run() for both; reveal
 ├─ lib/catalog.js  (1222)  The 32 targets, measurePath / purgePath / resolveTargets / drives
 ├─ lib/audit.js    (365)  Read-only assessment, 10-minute cache, areaPaths, exposes no deletion
 ├─ lib/plan.js     (150)  Pure: measurements → ordered steps
-├─ lib/client.js  (1597)  Client half: slots, panel, preferences, zh/en dictionaries, CSS
+├─ lib/client.js  (1808)  Client half: slots, panel, preferences, zh/en dictionaries, CSS
 ├─ locale/{en,zh}.json    Display metadata (meta.title / meta.description)
 ├─ icon.svg               Plugin icon
 ├─ README.md              This file
 ├─ LICENSE                MIT
-└─ smoke.mjs              98 assertions, zero dependencies
+└─ smoke.mjs              110 assertions, zero dependencies
 ```
 
 Client-half slots: `sidebar.panellist` (order 50, disposed in settings-only mode), `main` (keyed by the package name), `settings.section` (order 30, disposed in sidebar-only mode), `plugins.bundle.config` (keyed by the package name).
 
 ### What's new
 
+- **1.6.6** — The results the plugin already computed are now shown. A **Dry run** button next to *Clean* asks the exact same question without `confirm`, so you see what a delete would free before anything goes; the result banner then survives the rescan that follows it (it used to be erased a line later). Plan steps name targets in words instead of printing `npm-cache, chrome-cache, pip-cache`, an empty plan says "nothing worth doing" instead of rendering a hole, and route errors arrive as a stable `code` the panel translates, so a Chinese user never reads `origin rejected` or `unknown target: x`. Every real clean now appends one line to `$DSH_HOME/dsh-disk-cleaner/history.jsonl`, and a **Clean history** panel reads it back with a *Copy as CSV* button. Under the hood: scan walks four targets at a time instead of all 32 at once, `SystemRoot` decides where the Windows targets live instead of a hardcoded `C:`, a request without an `Origin` header is refused, and a refused directory removal is counted separately from a legitimately full one.
 - **1.6.5** — Documentation only: the install section now points at the Release it names (the prebuilt-tarball link is labelled v1.6.5 and resolves to the v1.6.5 tag), and the catalog paragraph says the awesome-dsh-plugin entry is merged rather than pending review. No code change.
 - **1.6.4** — The panel now paints itself with [dsh-design-baseline](https://github.com/stallenlu/dsh-design-baseline): the stylesheet is inlined into the client bundle, the panel root carries `dsb-root`, and every colour resolves through a `--dsb-*` token instead of a host `--dsw-alias-*` name. That means it follows the host's light and dark themes (including `color-scheme`, so native `<select>` menus and scrollbars match), and colour is spent only on data that has state — the primary button and the active chip are now inverted neutrals rather than brand blue. No behaviour changes.
 - **1.6.3** — Safety and honesty rather than new features. The Recycle Bin is no longer filed under `safe`: emptying it cannot be undone, so it is never preselected, never picked by "select all", and carries its own `irreversible` note instead of the generic "rebuilt; next start is slower". The confirm dialog now names each target and the total instead of asking a generic "delete these?". A target that names no environment root is bounded by the volume it sits on rather than skipping the boundary check. `measure` and `purge` now count entries in the same unit, and a walk that hits the 2,000,000-entry cap says so (`truncated`) instead of claiming exact totals. A directory removal refused for a reason other than "not empty" is counted as `blocked` instead of being swallowed, and a clean that left files behind reports a warning rather than a green success. The orphan target is named for what it actually measures (the QQGuild folder).
@@ -437,16 +438,16 @@ Client-half slots: `sidebar.panellist` (order 50, disposed in settings-only mode
 
 已收录进精选目录 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)，它是 **dshmarket → 发现** 的数据源（[PR #12970](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/12970)，已合并）：在 dshmarket 里搜索 **dsh-disk-cleaner** 即可一键安装。下面的直接安装方式就是手动做同一件事。
 
-已发布到 npm：[`dsh-disk-cleaner`](https://www.npmjs.com/package/dsh-disk-cleaner)，最新版 `1.6.5`。
+已发布到 npm：[`dsh-disk-cleaner`](https://www.npmjs.com/package/dsh-disk-cleaner)，最新版 `1.6.6`。
 
 ```bash
 npm i dsh-disk-cleaner
 ```
 
-[v1.6.5 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.5) 还附带一个预构建 tarball，从它安装可跳过 DSH 的构建授权步骤：
+[v1.6.6 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.6) 还附带一个预构建 tarball，从它安装可跳过 DSH 的构建授权步骤：
 
 ```bash
-dsh plugin --profile <profile> add https://github.com/stallenlu/dsh-disk-cleaner/releases/download/v1.6.5/dsh-disk-cleaner-1.6.5.tgz
+dsh plugin --profile <profile> add https://github.com/stallenlu/dsh-disk-cleaner/releases/download/v1.6.6/dsh-disk-cleaner-1.6.6.tgz
 ```
 
 然后在 profile 里启用 —— 在 `$DSH_PROFILE_DIR/package.json`：
@@ -454,7 +455,7 @@ dsh plugin --profile <profile> add https://github.com/stallenlu/dsh-disk-cleaner
 ```json
 {
   "dependencies": {
-    "dsh-disk-cleaner": "^1.6.5"
+    "dsh-disk-cleaner": "^1.6.6"
   },
   "dsh": {
     "profile": {
@@ -475,7 +476,7 @@ bundle 自带的 `cordis.patch.yml` 会插入插件行，无需改 profile 的 p
 ### 开发
 
 ```bash
-node smoke.mjs                       # 98 条断言，零依赖
+node smoke.mjs                       # 110 条断言，零依赖
 node --check lib/client.js           # 以及 lib/index.js、lib/catalog.js、lib/audit.js、lib/plan.js
 ```
 
@@ -529,22 +530,23 @@ node --check lib/client.js           # 以及 lib/index.js、lib/catalog.js、li
 ```
 ├─ package.json           dsh.bundle.patch + dsh.client { platform: "web" }
 ├─ cordis.patch.yml       - insert:  id: dsh-disk-cleaner
-├─ lib/index.js    (434)  Host：HTTP 路由 + disk_cleaner 工具，共用同一个 run()，含 reveal
+├─ lib/index.js    (482)  Host：HTTP 路由 + disk_cleaner 工具，共用同一个 run()，含 reveal
 ├─ lib/catalog.js  (1222)  32 个目标，measurePath / purgePath / resolveTargets / drives
 ├─ lib/audit.js    (365)  只读评估，10 分钟缓存，带 areaPaths，不暴露任何删除
 ├─ lib/plan.js     (150)  纯函数：测量结果 → 有序步骤
-├─ lib/client.js  (1597)  Client 半面：slot、面板、偏好、zh/en 字典、CSS
+├─ lib/client.js  (1808)  Client 半面：slot、面板、偏好、zh/en 字典、CSS
 ├─ locale/{en,zh}.json    展示元数据（meta.title / meta.description）
 ├─ icon.svg               插件图标
 ├─ README.md              本文件
 ├─ LICENSE                MIT
-└─ smoke.mjs              98 条断言，零依赖
+└─ smoke.mjs              110 条断言，零依赖
 ```
 
 Client 半面注册的 slot：`sidebar.panellist`（order 50，仅设置页模式下拆除）、`main`（以包名为 key）、`settings.section`（order 30，仅侧边栏模式下拆除）、`plugins.bundle.config`（以包名为 key）。
 
 ### 更新记录
 
+- **1.6.6** — 把插件本来就算出来的结果真正显示出来。*清理* 旁边多了 **预演** 按钮：发同一个请求但不带 `confirm`，删之前就能看到会释放多少；清理结果横幅不再被紧随其后的重新扫描抹掉（以前下一行就被清空）。计划步骤改用目标名称，不再直出 `npm-cache, chrome-cache, pip-cache`；没有可做的事时说明「现在没有值得动手的地方」，而不是留一片空白；接口错误改带稳定 `code`，由面板翻成中文，不会再出现 `origin rejected` 或 `unknown target: x`。每次真正清理都会往 `$DSH_HOME/dsh-disk-cleaner/history.jsonl` 追加一行，新增的 **清理记录** 面板可读回并按 *复制为 CSV* 导出。底层：扫描从「32 个目标同时跑」改为每次 4 个，Windows 目标路径改由 `SystemRoot` 决定而不再硬编码 `C:`，缺少 `Origin` 头的请求会被拒绝，目录删除被拒与非空目录被跳过分别计数。
 - **1.6.5** — 仅文档修正：安装段现在指向它所写的那个 Release（预构建 tarball 的链接标为 v1.6.5，且指向 v1.6.5 的 tag）；目录段落也从「审核中」改为「已合并」。代码无变化。
 - **1.6.4** — 面板改用 [dsh-design-baseline](https://github.com/stallenlu/dsh-design-baseline) 上色：样式表内联进 client bundle，根节点带 `dsb-root`，所有颜色都走 `--dsb-*` 令牌而不是宿主的 `--dsw-alias-*` 名字。因此它跟随宿主的明暗主题（含 `color-scheme`，原生 `<select>` 弹层与滚动条也跟着变），并且颜色只花在有状态的数据上——主按钮与选中项改成中性反色，不再是品牌蓝。行为没有变化。
 - **1.6.3** — 改的是安全与诚实，不是新功能。回收站不再归入「安全」：清空不可恢复，所以它永不被预选、不被「全选」勾中，并单独带 `irreversible` 注意码，而不是笼统的「重建，下次启动慢一些」。确认框现在逐条列出目标名与合计字节，不再只问一句「删除选中缓存目录里的文件？」。没有声明根目录的目标，改为按所在卷做边界校验，而不是直接跳过检查。`measure` 与 `purge` 现在用同一单位计数，走查触到 200 万条上限时会如实标 `truncated`，不再声称精确总量。目录删除失败若原因不是「非空」会计入 `blocked`（此前被静默吞掉），清理后仍有残留的目标会报警告而不是绿色成功。orphan 目标按它实际测量的东西重新命名（QQ 频道目录）。

package/lib/catalog.js

@@ -643,7 +643,9 @@ const CATALOG = [
     // the user to an elevated prompt that changed nothing and hid the bytes from the plan.
     note: 'in-use',
     roots: ['SystemRoot'],
-    paths: () => ['C:\\Windows\\Temp'],
+    // SystemRoot, not a hardcoded C: — the boundary check above already trusted it,
+    // so a machine whose Windows sits on another volume must delete from the same place.
+    paths: () => [path.join(env('SystemRoot') ?? 'C:\\Windows', 'Temp')],
   },
   {
     id: 'npm-cache',
@@ -717,7 +719,7 @@ const CATALOG = [
     risk: 'caution',
     note: 'elevation',
     roots: ['SystemRoot'],
-    paths: () => ['C:\\Windows\\SoftwareDistribution\\Download'],
+    paths: () => [path.join(env('SystemRoot') ?? 'C:\\Windows', 'SoftwareDistribution', 'Download')],
   },
   {
     id: 'recycle-bin',
@@ -1057,27 +1059,45 @@ export async function measurePath(abs, cutoff) {
  * folders hold. Reporting both is what tells the user "245 MB here, 0.2 MB past the limit"
  * instead of a small number that reads as "nothing found".
  */
+const measureTarget = async (target) => {
+  const cutoff = target.minAgeDays > 0 ? Date.now() - target.minAgeDays * DAY : undefined;
+  let bytes = 0;
+  let files = 0;
+  let totalBytes = 0;
+  let totalFiles = 0;
+  let truncated = false;
+  for (const abs of target.paths) {
+    const size = await measurePath(abs, cutoff);
+    bytes += size.bytes;
+    files += size.files;
+    totalBytes += size.totalBytes;
+    totalFiles += size.totalFiles;
+    truncated = truncated || size.truncated === true;
+  }
+  return { ...target, bytes, files, totalBytes, totalFiles, truncated };
+};
+
+/**
+ * Measuring all 32 targets at once meant 32 concurrent directory walks, which turns a
+ * scan on a spinning disk (or behind a scanner) into a stall. Four at a time keeps the
+ * wall clock close and the disk queue short; results keep catalog order either way.
+ */
+const SCAN_CONCURRENCY = 4;
+
 export async function scan(only, drive) {
   const targets = resolveTargets(only, drive);
-  const measured = await Promise.all(
-    targets.map(async (target) => {
-      const cutoff = target.minAgeDays > 0 ? Date.now() - target.minAgeDays * DAY : undefined;
-      let bytes = 0;
-      let files = 0;
-      let totalBytes = 0;
-      let totalFiles = 0;
-      let truncated = false;
-      for (const abs of target.paths) {
-        const size = await measurePath(abs, cutoff);
-        bytes += size.bytes;
-        files += size.files;
-        totalBytes += size.totalBytes;
-        totalFiles += size.totalFiles;
-        truncated = truncated || size.truncated === true;
-      }
-      return { ...target, bytes, files, totalBytes, totalFiles, truncated };
-    }),
-  );
+  const measured = new Array(targets.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < targets.length) {
+      const index = next;
+      next += 1;
+      measured[index] = await measureTarget(targets[index]);
+    }
+  };
+  const workers = [];
+  for (let i = 0; i < Math.min(SCAN_CONCURRENCY, targets.length); i += 1) workers.push(worker());
+  await Promise.all(workers);
   return measured;
 }
 

package/lib/client.js

@@ -102,6 +102,32 @@ window.__ModuleLoader__.load({
       cleanConfirmList: '即将清理 {n} 项，合计 {bytes}：\n\n{list}\n\n回收站等不可恢复的项目会单独标出。',
       cleanConfirmIrreversible: '\n\n注意：其中「回收站」清空后无法恢复。',
       truncatedHint: '这个目录太大，只统计/清理了前 {n} 条，实际释放可能少于这个数。',
+      dryRunHint: '预演完成：没有删除任何文件。',
+      wouldFree: '可释放',
+      dryRunBtn: '预演',
+      dryRunBusy: '预演中…',
+      listSep: '、',
+      planEmpty: '现在没有值得动手的地方：缓存都还小，或者才清过。等它们长回来再看。',
+      historyTitle: '清理记录',
+      historyOpen: '查看清理记录',
+      historyLoading: '读取中…',
+      historyEmpty: '还没有清理记录。真正执行过一次清理后，这里会留下每一条。',
+      historyCopy: '复制为 CSV',
+      historyCopied: '已复制',
+      historyRun: '{time} · 释放 {bytes} · {files} 个文件',
+      historySourceAgent: '由 Agent 执行',
+      'err_method-not-allowed': '这个接口只接受本地面板的请求。',
+      'err_origin-rejected': '请求来源不被接受：请从面板里操作。',
+      'err_body-too-large': '请求内容过大。',
+      'err_body-invalid': '请求内容无法解析。',
+      'err_bad-ids': '目标列表格式不对。',
+      'err_too-many-ids': '一次选的目标太多了。',
+      'err_unknown-target': '有不认识的目标名称，请重新扫描后再试。',
+      'err_unknown-drive': '磁盘名称不认识。',
+      'err_drive-not-mounted': '这个盘当前没有挂载。',
+      'err_no-targets': '没有选中任何目标。',
+      'err_unknown-action': '不支持的操作。',
+      'err_internal': '插件内部出错了，详细信息见日志。',
       'target_temp': '用户临时文件',
       'target_windows-temp': 'Windows 临时文件',
       'target_npm-cache': 'npm 缓存',
@@ -278,6 +304,32 @@ window.__ModuleLoader__.load({
       cleanConfirmList: 'About to clean {n} target(s), {bytes} in total:\n\n{list}\n\nAnything irreversible is called out separately.',
       cleanConfirmIrreversible: '\n\nNote: emptying the Recycle Bin cannot be undone.',
       truncatedHint: 'This folder is too large: only the first {n} entries were measured or removed, so less may be freed.',
+      dryRunHint: 'Dry run finished: nothing was deleted.',
+      wouldFree: 'Could free',
+      dryRunBtn: 'Dry run',
+      dryRunBusy: 'Running…',
+      listSep: ', ',
+      planEmpty: 'Nothing worth doing right now: the caches are still small, or you just cleaned them. Come back when they grow.',
+      historyTitle: 'Clean history',
+      historyOpen: 'Show clean history',
+      historyLoading: 'Reading…',
+      historyEmpty: 'No runs recorded yet. Every real clean leaves one entry here.',
+      historyCopy: 'Copy as CSV',
+      historyCopied: 'Copied',
+      historyRun: '{time} · freed {bytes} · {files} file(s)',
+      historySourceAgent: 'run by the agent',
+      'err_method-not-allowed': 'This route only accepts requests from the local panel.',
+      'err_origin-rejected': 'Request origin rejected: use the panel.',
+      'err_body-too-large': 'The request was too large.',
+      'err_body-invalid': 'The request could not be parsed.',
+      'err_bad-ids': 'The target list is malformed.',
+      'err_too-many-ids': 'Too many targets in one request.',
+      'err_unknown-target': 'Unknown target name; scan again and retry.',
+      'err_unknown-drive': 'Unknown drive.',
+      'err_drive-not-mounted': 'That drive is not mounted.',
+      'err_no-targets': 'No target selected.',
+      'err_unknown-action': 'Unsupported action.',
+      'err_internal': 'The plugin hit an internal error; see the log.',
       'target_temp': 'User temp files',
       'target_windows-temp': 'Windows temp files',
       'target_npm-cache': 'npm cache',
@@ -545,6 +597,21 @@ window.__ModuleLoader__.load({
       return label === key ? id : label;
     }
 
+    /**
+     * The route answers with a stable `code` beside its English message. The panel shows the
+     * translated code and only falls back to the message when the code is unknown, so a
+     * Chinese user never reads "origin rejected" or "unknown target: x".
+     */
+    function describeError(t, err) {
+      const code = err && typeof err.code === 'string' ? err.code : '';
+      if (code !== '') {
+        const key = `err_${code}`;
+        const text = t(key);
+        if (text !== key) return text;
+      }
+      return err instanceof Error ? err.message : String(err);
+    }
+
     async function call(action, payload) {
       const response = await fetch(ROUTE, {
         method: 'POST',
@@ -558,7 +625,9 @@ window.__ModuleLoader__.load({
         throw new Error(`HTTP ${response.status}`);
       }
       if (!response.ok || !data || data.ok !== true) {
-        throw new Error((data && data.error) || `HTTP ${response.status}`);
+        const error = new Error((data && data.error) || `HTTP ${response.status}`);
+        if (data && typeof data.code === 'string') error.code = data.code;
+        throw error;
       }
       return data;
     }
@@ -779,10 +848,15 @@ window.__ModuleLoader__.load({
         };
       }, [drives.length, setDrives]);
 
-      const scan = useCallback(async () => {
+      /**
+       * `keepNotice` is what makes the clean result readable at all: a clean ends by
+       * rescanning, and a rescan used to clear the banner it had just set.
+       */
+      const scan = useCallback(async (options) => {
+        const keepNotice = options !== null && typeof options === 'object' && options.keepNotice === true;
         setBusy('scan');
         setError('');
-        setNotice(null);
+        if (!keepNotice) setNotice(null);
         try {
           const data = await call('scan', drive === '' ? undefined : { drive });
           const targets = Array.isArray(data.targets) ? data.targets : [];
@@ -798,7 +872,7 @@ window.__ModuleLoader__.load({
                   .map((row) => row.id);
           setPicked(new Set(preselect));
         } catch (err) {
-          setError(`${t('scanError')}: ${err instanceof Error ? err.message : String(err)}`);
+          setError(`${t('scanError')}: ${describeError(t, err)}`);
         } finally {
           setBusy('');
         }
@@ -830,10 +904,16 @@ window.__ModuleLoader__.load({
         setPicked(new Set(eligible));
       };
 
-      const runClean = async () => {
+      /**
+       * `dry` runs the exact same request without `confirm`, so the number the panel reports
+       * is the number the delete would achieve. It never asks for confirmation: it deletes
+       * nothing. A real run keeps asking.
+       */
+      const runClean = async (dry) => {
+        const isDry = dry === true;
         if (!rows || picked.size === 0) return;
         const chosen = shown.filter((row) => picked.has(row.id));
-        if (confirmFirst.get() === 'always') {
+        if (!isDry && confirmFirst.get() === 'always') {
           // A confirm box that does not say what it deletes is not a confirmation. Name the
           // targets and the total, and call out anything that cannot be undone.
           const bytes = chosen.reduce((sum, row) => sum + (row.bytes || 0), 0);
@@ -851,12 +931,20 @@ window.__ModuleLoader__.load({
         setError('');
         setNotice(null);
         try {
-          const data = await call('clean', drive === '' ? { ids, confirm: true } : { ids, drive, confirm: true });
+          const body = isDry ? { ids } : { ids, confirm: true };
+          const data = await call('clean', drive === '' ? body : { ...body, drive });
           const results = Array.isArray(data.results) ? data.results : [];
           const bytes = results.reduce((sum, item) => sum + (item.bytes || 0), 0);
           const files = results.reduce((sum, item) => sum + (item.removed || 0), 0);
           const failed = results.reduce((sum, item) => sum + (item.failed || 0), 0);
           const truncated = results.filter((item) => item.truncated === true).length > 0;
+          if (isDry) {
+            setNotice({
+              kind: 'ok',
+              text: `${t('dryRunHint')} ${t('wouldFree')} ${formatBytes(bytes)} · ${files} ${t('files')}`,
+            });
+            return;
+          }
           // A run that left files behind is not a success banner: an all-ok green line over
           // "12 skipped" reads as done when it is not.
           const kind = failed > 0 ? 'warn' : 'ok';
@@ -864,9 +952,9 @@ window.__ModuleLoader__.load({
           if (failed > 0) parts.push(`${t('failed')} ${failed} (${t('failedHint')})`);
           if (truncated) parts.push(t('truncatedHint').replace('{n}', String(results.length)));
           setNotice({ kind, text: parts.join(' · ') });
-          await scan();
+          await scan({ keepNotice: true });
         } catch (err) {
-          setError(`${t('cleanError')}: ${err instanceof Error ? err.message : String(err)}`);
+          setError(`${t('cleanError')}: ${describeError(t, err)}`);
         } finally {
           setBusy('');
         }
@@ -977,13 +1065,26 @@ window.__ModuleLoader__.load({
                   picked.size > 0 ? ` · ${t('selected')} ${formatBytes(pickedBytes)}` : '',
                 )
               : null,
+            rows
+              ? h(
+                  'button',
+                  {
+                    type: 'button',
+                    className: 'dsc-btn',
+                    onClick: () => runClean(true),
+                    disabled: busy !== '' || picked.size === 0,
+                    title: t('dryRunHint'),
+                  },
+                  busy === 'clean' ? t('dryRunBusy') : t('dryRunBtn'),
+                )
+              : null,
             rows
               ? h(
                   'button',
                   {
                     type: 'button',
                     className: 'dsc-btn dsc-btn-danger',
-                    onClick: runClean,
+                    onClick: () => runClean(false),
                     disabled: busy !== '' || picked.size === 0,
                   },
                   busy === 'clean' ? t('cleaning') : t('clean'),
@@ -1088,10 +1189,110 @@ window.__ModuleLoader__.load({
           ),
         ),
         h(Audit, { t }),
+        h(History, { t }),
             ],
       );
     }
 
+    /**
+     * Every real clean appends one line to a JSONL file under $DSH_HOME. The panel reads it
+     * back, so "what did I actually clean, and when" has an answer that outlives the tab —
+     * and the CSV copy takes that answer out of the app.
+     */
+    function History({ t }) {
+      const [runs, setRuns] = useState(null);
+      const [busy, setBusy] = useState(false);
+      const [error, setError] = useState('');
+      const [copied, setCopied] = useState(false);
+
+      const load = async () => {
+        setBusy(true);
+        setError('');
+        try {
+          const data = await call('history');
+          setRuns(Array.isArray(data.runs) ? data.runs : []);
+        } catch (err) {
+          setError(`${t('historyTitle')}: ${describeError(t, err)}`);
+        } finally {
+          setBusy(false);
+        }
+      };
+
+      /** Quote every cell: a target list contains commas, and Excel must not split it. */
+      const copyCsv = async () => {
+        const rows = [['when', 'bytes', 'files', 'failed', 'truncated', 'targets', 'source']];
+        for (const run of runs || []) {
+          rows.push([
+            run.at || '',
+            String(run.bytes || 0),
+            String(run.files || 0),
+            String(run.failed || 0),
+            run.truncated === true ? 'yes' : 'no',
+            (Array.isArray(run.ids) ? run.ids : []).join(' '),
+            run.source === 'agent' ? 'agent' : 'panel',
+          ]);
+        }
+        const csv = rows
+          .map((row) => row.map((cell) => `"${String(cell).replace(/"/g, '""')}"`).join(','))
+          .join('\r\n');
+        try {
+          await navigator.clipboard.writeText(csv);
+          setCopied(true);
+        } catch {
+          setError(t('historyCopy'));
+        }
+      };
+
+      return h(
+        'section',
+        { className: 'dsc-card' },
+        h(
+          'div',
+          { className: 'dsc-card-title' },
+          t('historyTitle'),
+          h('span', { className: 'dsc-spacer' }),
+          runs && runs.length > 0
+            ? h('button', { type: 'button', className: 'dsc-btn', onClick: copyCsv }, copied ? t('historyCopied') : t('historyCopy'))
+            : null,
+          h(
+            'button',
+            { type: 'button', className: 'dsc-btn', onClick: load, disabled: busy },
+            busy ? t('historyLoading') : t('historyOpen'),
+          ),
+        ),
+        error ? h('div', { className: 'dsc-notice dsc-err' }, error) : null,
+        runs === null
+          ? null
+          : runs.length === 0
+            ? h('div', { className: 'dsc-empty' }, t('historyEmpty'))
+            : runs.map((run, index) =>
+                h(
+                  'div',
+                  { className: 'dsc-audit-row', key: `${run.at || ''}/${index}` },
+                  h(
+                    'span',
+                    { className: 'dsc-audit-name' },
+                    h(
+                      'span',
+                      { className: 'dsc-audit-label' },
+                      t('historyRun')
+                        .replace('{time}', run.at ? new Date(run.at).toLocaleString() : '')
+                        .replace('{bytes}', formatBytes(run.bytes || 0))
+                        .replace('{files}', String(run.files || 0)),
+                    ),
+                    h(
+                      'span',
+                      { className: 'dsc-audit-why' },
+                      run.source === 'agent'
+                        ? t('historySourceAgent')
+                        : (Array.isArray(run.ids) ? run.ids : []).map((id) => targetName(t, id)).join(t('listSep')),
+                    ),
+                  ),
+                ),
+              ),
+      );
+    }
+
     /**
      * The plan turns the numbers into an order of operations. Steps that this plugin can
      * actually perform get a button; the rest show the exact command, because "compact
@@ -1100,7 +1301,17 @@ window.__ModuleLoader__.load({
     function Plan({ plan, t, onRan, busy }) {
       const [copied, setCopied] = useState('');
 
-      if (!plan || !Array.isArray(plan.steps) || plan.steps.length === 0) return null;
+      if (!plan || !Array.isArray(plan.steps)) return null;
+      // An empty plan is an answer — "there is nothing worth doing" — not a reason to
+      // render a hole where the plan was.
+      if (plan.steps.length === 0) {
+        return h(
+          'div',
+          { className: 'dsc-plan' },
+          h('div', { className: 'dsc-audit-group-title' }, t('planTitle')),
+          h('div', { className: 'dsc-plan-detail' }, t('planEmpty')),
+        );
+      }
 
       const copy = (code, command) => {
         const done = () => {
@@ -1125,7 +1336,7 @@ window.__ModuleLoader__.load({
           const detailKey = `plan_code_${step.code}_detail`;
           const detail = t(detailKey)
             .replace('{n}', String(step.count || 0))
-            .replace('{ids}', (step.ids || []).join(', '))
+            .replace('{ids}', (step.ids || []).map((id) => targetName(t, id)).join(t('listSep')))
             .replace('{name}', step.name || '')
             .replace('{scope}', step.scope === 'local' ? t('planScopeLocal') : t('planScopeRoaming'))
             .replace('{folder}', step.folder || '')

package/lib/history.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * What each real run actually freed, appended as one JSON line per run.
+ *
+ * The panel is the only writer and it writes after the deletion has already happened, so a
+ * failed append must never turn a successful clean into an error: every function here answers
+ * with a value instead of throwing. Nothing else reads this file, which is why it is a plain
+ * JSONL log rather than a database.
+ */
+
+const MAX_BYTES = 512 * 1024;
+
+export function historyDir(env = process.env) {
+  const home =
+    typeof env.DSH_HOME === 'string' && env.DSH_HOME.trim() !== ''
+      ? env.DSH_HOME.trim()
+      : path.join(os.homedir(), '.dsh');
+  return path.join(home, 'dsh-disk-cleaner');
+}
+
+export function historyFile(env = process.env) {
+  return path.join(historyDir(env), 'history.jsonl');
+}
+
+const trim = (file) => {
+  try {
+    const stat = fs.statSync(file);
+    if (stat.size <= MAX_BYTES) return;
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter((line) => line.trim() !== '');
+    // Keep the newest half, which is what a reader ever asks about.
+    const kept = lines.slice(Math.floor(lines.length / 2));
+    fs.writeFileSync(file, `${kept.join('\n')}\n`, 'utf8');
+  } catch {
+    /* a log that cannot be trimmed is still a log */
+  }
+};
+
+export function appendRun(record, env = process.env) {
+  try {
+    const dir = historyDir(env);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = historyFile(env);
+    fs.appendFileSync(file, `${JSON.stringify(record)}\n`, 'utf8');
+    trim(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readRuns(limit = 50, env = process.env) {
+  try {
+    const text = fs.readFileSync(historyFile(env), 'utf8');
+    const lines = text.split('\n').filter((line) => line.trim() !== '');
+    const out = [];
+    for (const line of lines.slice(-limit)) {
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed !== null && typeof parsed === 'object') out.push(parsed);
+      } catch {
+        /* a torn last line is not a reason to lose the rest */
+      }
+    }
+    return out.reverse();
+  } catch {
+    return [];
+  }
+}

package/lib/index.js

@@ -11,6 +11,7 @@ import { spawn } from 'node:child_process';
 
 import { areaPaths, audit, invalidateAudit } from './audit.js';
 import { clean, drives, hasTarget, resolveTargets, scan } from './catalog.js';
+import { appendRun, readRuns } from './history.js';
 
 export const name = 'dsh-disk-cleaner';
 
@@ -20,6 +21,16 @@ const ROUTE_PREFIX = '/api/disk-cleaner/';
 const MAX_BODY = 4096;
 const MAX_IDS = 32;
 
+/**
+ * Every rejection carries a code beside its message. The message is for logs and curl; the
+ * code is what the panel translates, so a Chinese user never reads "origin rejected".
+ */
+const coded = (code, message) => {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+};
+
 const sendJson = (res, status, value) => {
   const body = JSON.stringify(value);
   res.writeHead(status, {
@@ -30,11 +41,18 @@ const sendJson = (res, status, value) => {
   res.end(body);
 };
 
-/** A same-origin page is the only caller that can reach a state-changing route. */
+/**
+ * A same-origin page is the only caller that can reach a state-changing route.
+ *
+ * An absent Origin used to pass, which let any local process drive clean/set-key by simply
+ * not sending the header. Browsers always send it on a cross-context POST, so requiring it
+ * costs the panel nothing and shuts the door; a missing Host is treated the same way.
+ */
 const sameOrigin = (req) => {
   const origin = req.headers.origin;
   const host = req.headers.host;
-  return origin === undefined || host === undefined || origin === `http://${host}` || origin === `https://${host}`;
+  if (typeof origin !== 'string' || typeof host !== 'string') return false;
+  return origin === `http://${host}` || origin === `https://${host}`;
 };
 
 const readBody = (req) =>
@@ -74,10 +92,10 @@ const readBody = (req) =>
 /** Only catalog ids are accepted; an unknown or malformed id rejects the request. */
 const readIds = (value) => {
   if (value === undefined || value === null) return undefined;
-  if (!Array.isArray(value)) throw new Error('ids must be an array');
-  if (value.length > MAX_IDS) throw new Error('too many ids');
+  if (!Array.isArray(value)) throw coded('bad-ids', 'ids must be an array');
+  if (value.length > MAX_IDS) throw coded('too-many-ids', 'too many ids');
   for (const id of value) {
-    if (typeof id !== 'string' || !hasTarget(id)) throw new Error(`unknown target: ${String(id)}`);
+    if (typeof id !== 'string' || !hasTarget(id)) throw coded('unknown-target', `unknown target: ${String(id)}`);
   }
   return value;
 };
@@ -91,10 +109,10 @@ const readDrive = (value) => {
   if (value === undefined || value === null || value === '') return undefined;
   const raw = typeof value === 'string' ? value.trim() : '';
   const match = /^([A-Za-z])(?::[\\/]?)?$/.exec(raw);
-  if (match === null) throw new Error(`unknown drive: ${String(value)}`);
+  if (match === null) throw coded('unknown-drive', `unknown drive: ${String(value)}`);
   const letter = match[1].toUpperCase();
   const mounted = drives().find((drive) => drive.root[0] === letter);
-  if (!mounted) throw new Error(`drive not mounted: ${letter}:`);
+  if (!mounted) throw coded('drive-not-mounted', `drive not mounted: ${letter}:`);
   return mounted.root;
 };
 
@@ -173,24 +191,38 @@ async function run(action, payload) {
   if (action === 'reveal') return reveal(payload);
   if (action === 'clean') {
     const ids = readIds(payload.ids);
-    if (ids === undefined || ids.length === 0) throw new Error('clean needs at least one target id');
+    if (ids === undefined || ids.length === 0) throw coded('no-targets', 'clean needs at least one target id');
     const dryRun = payload.confirm !== true;
     const results = await clean(ids, { dryRun, drive: readDrive(payload.drive) });
     // A real deletion changes the numbers the assessment reported, so the cached plan is
     // no longer the truth. A dry run removed nothing and leaves it valid.
-    if (!dryRun) invalidateAudit();
+    if (!dryRun) {
+      invalidateAudit();
+      // Written after the fact and never allowed to fail the request: the bytes are already
+      // gone by the time this runs, so a broken log must not read as a broken clean.
+      appendRun({
+        at: new Date().toISOString(),
+        bytes: results.reduce((sum, item) => sum + (item.bytes || 0), 0),
+        files: results.reduce((sum, item) => sum + (item.removed || 0), 0),
+        failed: results.reduce((sum, item) => sum + (item.failed || 0), 0),
+        truncated: results.some((item) => item.truncated === true),
+        ids: results.map((item) => item.id),
+        results,
+      });
+    }
     return { dryRun, results };
   }
-  throw new Error(`unknown action: ${String(action)}`);
+  if (action === 'history') return { runs: readRuns(50) };
+  throw coded('unknown-action', `unknown action: ${String(action)}`);
 }
 
 const handle = async (req, res) => {
   if (req.method !== 'POST') {
-    sendJson(res, 405, { ok: false, error: 'method not allowed' });
+    sendJson(res, 405, { ok: false, code: 'method-not-allowed', error: 'method not allowed' });
     return;
   }
   if (!sameOrigin(req)) {
-    sendJson(res, 403, { ok: false, error: 'origin rejected' });
+    sendJson(res, 403, { ok: false, code: 'origin-rejected', error: 'origin rejected' });
     return;
   }
   try {
@@ -198,7 +230,11 @@ const handle = async (req, res) => {
     const action = typeof payload.action === 'string' ? payload.action : '';
     sendJson(res, 200, { ok: true, ...(await run(action, payload)) });
   } catch (error) {
-    sendJson(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+    sendJson(res, 400, {
+      ok: false,
+      code: typeof error?.code === 'string' ? error.code : 'internal',
+      error: error instanceof Error ? error.message : String(error),
+    });
   }
 };
 
@@ -413,10 +449,22 @@ export function apply(ctx) {
           }
           if (action === 'clean') {
             const ids = readIds(args.ids);
-            if (ids === undefined || ids.length === 0) throw new Error('clean needs at least one target id');
+            if (ids === undefined || ids.length === 0) throw coded('no-targets', 'clean needs at least one target id');
             const dryRun = args.confirm !== true;
             const results = await clean(ids, { dryRun, drive: readDrive(args.drive) });
-            if (!dryRun) invalidateAudit();
+            if (!dryRun) {
+              invalidateAudit();
+              appendRun({
+                at: new Date().toISOString(),
+                bytes: results.reduce((sum, item) => sum + (item.bytes || 0), 0),
+                files: results.reduce((sum, item) => sum + (item.removed || 0), 0),
+                failed: results.reduce((sum, item) => sum + (item.failed || 0), 0),
+                truncated: results.some((item) => item.truncated === true),
+                ids: results.map((item) => item.id),
+                source: 'agent',
+                results,
+              });
+            }
             const freed = results.reduce((sum, item) => sum + item.bytes, 0);
             const files = results.reduce((sum, item) => sum + item.removed, 0);
             const failed = results.reduce((sum, item) => sum + item.failed, 0);
@@ -426,7 +474,7 @@ export function apply(ctx) {
               : `Freed ${formatBytes(freed)} across ${files} file(s).`;
             return `${head}\n${detail}\nLocked or denied entries skipped: ${failed}`;
           }
-          throw new Error(`unknown action: ${action}`);
+          throw coded('unknown-action', `unknown action: ${action}`);
         },
       }),
     'dsh-disk-cleaner: tool',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-disk-cleaner",
-  "version": "1.6.5",
+  "version": "1.6.6",
   "type": "module",
   "description": "Disk Cleaner for DSH: scan known-safe cache locations, see what they occupy, and reclaim the space from a panel or from the agent.",
   "keywords": [
@@ -23,6 +23,7 @@
     "lib/catalog.js",
     "lib/audit.js",
     "lib/plan.js",
+    "lib/history.js",
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",

package/smoke.mjs

@@ -229,6 +229,7 @@ const index = read('lib/index.js');
 const catalog = read('lib/catalog.js');
 const plan = read('lib/plan.js');
 const auditSrc = read('lib/audit.js');
+const historySrc = read('lib/history.js');
 
 const { apply } = await import(pathToFileURL(path.join(here, 'lib/index.js')).href);
 check('host exports apply()', typeof apply === 'function');
@@ -264,7 +265,7 @@ check('tool needs no id for overview', JSON.stringify(definition.parameters.requ
 check('tool description warns audit is read-only', /read-only: it never removes anything/.test(definition.description));
 check('every effect is labelled', applied.every((label) => typeof label === 'string' && label.startsWith('dsh-disk-cleaner:')));
 check('tool output schema matches its string reply', definition.output.schema.type === 'string' && typeof (await definition.execute({ action: 'overview' })) === 'string');
-check('the read-only agent clean keeps the audit cache in sync', /if \(!dryRun\) invalidateAudit\(\);[\s\S]*const freed = results\.reduce/.test(index));
+check('the read-only agent clean keeps the audit cache in sync', /if \(!dryRun\) \{[\s\S]*?invalidateAudit\(\);[\s\S]*?const freed = results\.reduce/.test(index));
 check('orphan target descriptions state the real 30-day rule, not four signals / two years',
   /30 days/.test(catalog) && /30 days/.test(index) && /QQGuild data folder/.test(source) &&
   !/four independent signals|over two years|no Start-menu shortcut|two years/.test(catalog + index + source));
@@ -412,7 +413,106 @@ check(
     source.includes('QQ') ,
   'it only ever measures the QQGuild folder',
 );
-check('the version badge and package agree', pkg.version === '1.6.5');
+check('the version badge and package agree', pkg.version === '1.6.6');
+
+check(
+  'a dry run is one click away and never sends confirm',
+  /const runClean = async \(dry\) => \{/.test(source) &&
+    /const body = isDry \? \{ ids \} : \{ ids, confirm: true \};/.test(source) &&
+    /onClick: \(\) => runClean\(true\)/.test(source) &&
+    /onClick: \(\) => runClean\(false\)/.test(source),
+  'the panel must be able to ask what a delete would free before doing it',
+);
+
+check(
+  'a dry run never claims it freed anything',
+  /if \(isDry\) \{[\s\S]{0,320}t\('dryRunHint'\)[\s\S]{0,320}return;/.test(source) &&
+    /dryRunHint: '/.test(source),
+  'the dry-run banner must say nothing was deleted',
+);
+
+check(
+  'the notice a clean sets survives the rescan that follows it',
+  /await scan\(\{ keepNotice: true \}\);/.test(source) &&
+    /if \(!keepNotice\) setNotice\(null\);/.test(source),
+  'rescanning used to erase the result the user just asked for',
+);
+
+check(
+  'plan steps name targets in words, never catalog ids',
+  !source.includes("(step.ids || []).join(', ')") &&
+    source.includes('(step.ids || []).map((id) => targetName(t, id))'),
+  'the panel must not print npm-cache, chrome-cache, pip-cache at the user',
+);
+
+check(
+  'an empty plan says so instead of rendering nothing',
+  /if \(plan.steps.length === 0\)/.test(source) &&
+    /planEmpty: '/.test(source) &&
+    /t\('planEmpty'\)/.test(source),
+  'nothing worth doing is a conclusion, not a blank',
+);
+
+check(
+  'route errors carry a stable code the panel can translate',
+  /const coded = \(code, message\) => \{/.test(index) &&
+    /coded\('unknown-target'/.test(index) &&
+    /coded\('no-targets'/.test(index) &&
+    /code: typeof error\?\.code === 'string' \? error\.code : 'internal'/.test(index) &&
+    /function describeError\(t, err\) \{/.test(source) &&
+    /if \(data && typeof data\.code === 'string'\) error\.code = data\.code;/.test(source),
+  'a Chinese panel must not print "origin rejected" or "unknown target: x"',
+);
+
+check(
+  'every route error code has both a Chinese and an English sentence',
+  ['method-not-allowed', 'origin-rejected', 'bad-ids', 'too-many-ids', 'unknown-target', 'unknown-drive', 'drive-not-mounted', 'no-targets', 'unknown-action', 'internal'].every(
+    (code) => source.includes(`'err_${code}': `),
+  ),
+  'an untranslated code falls back to the English message',
+);
+
+check(
+  'a real clean writes one history line and the panel can read it back',
+  /import \{ appendRun, readRuns \} from '\.\/history\.js';/.test(index) &&
+    /if \(action === 'history'\) return \{ runs: readRuns\(50\) \};/.test(index) &&
+    /appendRun\(\{/.test(index) &&
+    /export function appendRun/.test(historySrc) &&
+    /export function readRuns/.test(historySrc) &&
+    /historyTitle: '/.test(source) &&
+    /function History\(\{ t \}\)/.test(source) &&
+    /h\(History, \{ t \}\)/.test(source),
+  'history must survive the tab, and be exportable',
+);
+
+check(
+  'history never throws into the clean path',
+  /try \{/.test(historySrc) &&
+    /catch/.test(historySrc) &&
+    !/throw /.test(historySrc),
+  'the bytes are already gone; failing to log them must not look like a failed clean',
+);
+
+check(
+  'scan bounds its own concurrency instead of walking every target at once',
+  /const SCAN_CONCURRENCY = \d+;/.test(catalog) &&
+    /const worker = async \(\) => \{/.test(catalog) &&
+    !/await Promise\.all\(targets\.map/.test(catalog),
+  '32 volumes at once stalls a spinning disk and the antivirus',
+);
+
+check(
+  'a system target under SystemRoot is read from SystemRoot, not from C:',
+  (catalog.match(/env\('SystemRoot'\)/g) ?? []).length === 2 &&
+    !/C:\\+Windows\\+Temp/.test(catalog),
+  'the boundary check already trusted SystemRoot; the paths have to agree',
+);
+
+check(
+  'a request without an Origin is refused',
+  /if \(typeof origin !== 'string' \|\| typeof host !== 'string'\) return false;/.test(index),
+  'any local process could otherwise drive a destructive route',
+);
 
 check(
   'the panel carries dsh-design-baseline (full mode: css inlined, root tagged, tokens only)',