dsh-console-sentinel 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,231 @@
+# Changelog
+
+## 0.3.0 (2026-11-03) — 设置面板 UI（任务栏窗口清理 / 白名单 / 窗口状态）
+
+用户需求：想看插件「现在什么状态」，并要「清理任务栏窗口」的操作入口 + 有没有 UI 设计。
+此前插件是纯宿主插件（无 `dsh.client`），只能在对话里让模型调工具，用户自己点不了。
+
+### 新增
+1. **客户端设置面板** `lib/client.js`（`__ModuleLoader__` bundle，`dsh.client` 声明，
+   platform `web`，id=完整包名）：在 DSH「设置」页注册「控制台哨兵」分区。分区内含
+   - 概览：总窗口 / 空壳 / 可见空壳 / 已隐藏 计数 + 「隐藏可见空壳」按钮；
+   - 任务栏窗口清理：预演 / 一键关闭其他窗口；
+   - 控制台窗口列表：逐行显示并可 隐藏 / 显示 / 关闭；
+   - 豁免白名单：进程名 / 标题关键字 标签式增删与清空。
+2. **宿主 HTTP 路由** `lib/index.js` `registerHttpUi()`：`/dsh-console-sentinel/{status,scan,hide-empty,window,desktop-cleanup,whitelist}`，
+   均做 loopback 校验；客户端 fetch 根相对路径（桌面端 Electron renderer 自动带
+   capability header，普通 curl 仍 403）。webServer 缺失时面板优雅降级，不影响工具功能。
+3. `package.json`：新增 `dsh.client`、`exports["./client"]`，版本 0.2.0→0.3.0。
+4. `tests/client.test.mjs`：DOM stub 评估真实 bundle，断言 bundle id / `exports.inject`
+   为数组 / `settings.section` 注册 / 首屏计数-窗口-白名单渲染 / 按钮触发路由。
+
+### 约束（都遵守，来自本机踩坑）
+- `exports.inject` 必须是普通数组；`ctx.slots.inject("settings.section", …)` 直接调用不包 `ctx.effect`；
+  组件不用 React hooks，结果按 id 写回 DOM 并在渲染入口 `setTimeout(0)` 自愈重挂载。
+- 样式只用 `--dsw-alias-*` 设计令牌；不使用 iframe；不轮询 agent/status。
+- 客户端无绝对 URL（探针断言 https?:// 计数 0、iframe 计数 0）。
+
+### 修复（2026-11-04，仍在 0.3.0 内）
+1. **插件根本没加载（duplicate loader entry）**：`dsh-console-sentinel` 同时出现在
+   `profiles/desktop/package.json` 的 `dsh.profile.bundles` 与 `profiles/desktop/cordis.patch.yml`
+   两条同 id 条目中，加载器按 duplicate 处理 → 插件不挂载（日志无任何 mounted 行、对话里
+   也无 `console_windows_list` 等工具）。按 `dsh-artifact-linker` 的约定，**配置迁入插件自身
+   bundle patch `cordis.patch.yml`**，并删除 profile `cordis.patch.yml` 里的手工条目（bundles 保留）。
+   校验：profile 28 条目、无 sentinel、bundles 36 项含 sentinel、trueDuplicates=[]。
+2. **Windows Terminal 空壳识别**：可见的「黑窗」主要是 `CASCADIA_HOSTING_WINDOW_CLASS`
+   （窗口属主是 `WindowsTerminal.exe`，不是里面的 shell），旧的 `isEmptyConsole` 只认解释器
+   进程本身 → 永远判「非空」。新增 `isBareShellTitle()` 与 `isEmptyConsole` 的 CASCADIA 分支
+   （标题为裸解释器路径如 `…\powershell.exe` / `…\cmd.exe` 且 `cpuPct ≤ 1` 才算空），并把
+   `windowsterminal` 从 `HARD_PROTECTED_PROCESSES` 移出（`autoAction` 仍为 `none`，只经
+   `emptyConsoleAction: hide` 处理空壳）。实测 8 个可见窗口中 5 个 CASCADIA 黑窗被判空。
+3. `tests/cascadia.test.mjs`：`isBareShellTitle` + CASCADIA 空判定 3 用例。
+4. **bundle patch 里 `disabled: !!js …` 使整条 insert 静默失败**（2026-11-04 二次实测，真凶）：
+   插件自己的 `cordis.patch.yml` 属 **bundle patch**，由普通 YAML 解析器读取，不认自定义标签；
+   本机 17 个能正常加载的插件其 patch **无一使用自定义标签**。移除该行（平台守卫保留在
+   `apply()`：非 Windows 打 `staying inert` 并 return），普通 YAML 解析通过。
+   同时在 `apply()` 入口加 `logger.info('host half mounted (v0.3.0, …)')`，以后日志可直接确认挂载。
+5. **扫描定时器被宿主 dispose 清掉（真凶 2）**：`ctx.effect(() => () => clearInterval(scanTimer))`
+   的 disposer 在宿主侧 teardown/reload 时会被调用，导致**第一轮 `scan #1` 之后定时器被
+   `clearInterval`**，之后再无 `scan #2`、也无任何异常日志（`catch` 不触发）。改为**进程自有的
+   plain `setInterval`（不挂 `ctx.effect`）**，并保留一个「超过 3×周期未扫描就强制补扫」的自愈
+   supervisor；临时的心跳/逐窗口诊断日志已清理。
+   实测（修复后）：启动 22 秒内 **6 个空壳窗口被自动隐藏**（5 个 Windows Terminal `CASCADIA` +
+   1 个 orphaned powershell），`visibleAfter=false`、`stillWindow=true`。
+6. 默认 `idleThresholdSec` 180 → **60**（空壳窗口更快消失；CPU 持续空闲才计数，不影响正在
+   计算的 Fluent/mpiexec 控制台）。
+
+### 生效方式
+- 改 `lib/client.js` → **Ctrl+Shift+R** 硬刷新；
+- 改宿主 `lib/index.js` / `package.json` / 挂载 → **完全退出 DSH 再启动**。
+
+## 0.2.0 (2026-11-03) — 空壳 PowerShell 安全清理 + 一键关窗口统一白名单
+
+用户需求：检查插件运营状态；能否有效隐藏/关闭「没有进程捆绑的空 PowerShell」；
+把之前开发的一键关闭其他窗口加进来；可设置豁免软件白名单。
+
+### 修的真问题
+0.1.x 的 `scope.orphaned` 默认 `false`，导致最常见的痛点——WMI/脚本退出后残留的
+**空 PowerShell 窗口**——永远不被自动处理；而直接打开 `orphaned` 又会误伤
+`mpiexec`（Fluent MPI）、`fl2610`（求解器）等在跑的计算（同属「父进程已退出」）。
+空判定缺位 = 只能二选一，两个都不对。
+
+### 新增
+1. **空控制台安全判定**（`lib/logic.js` `isEmptyConsole`）：解释器进程
+   （powershell/pwsh/cmd/python/pythonw）**且没有任何工作子进程**（children 去掉
+   conhost/openconsole 后为空）才算「空壳」。probe 现返回每进程 `Children`
+   （`lib/probe.js` 用 NtQueryInformationProcess 自建父子表，零依赖）。新配置
+   `scope.emptyConsole`（默认 `true`）+ `emptyConsoleAction`（默认 `hide`，独立于
+   `autoAction`）——只清空壳、绝不碰在跑计算。
+2. **硬保护进程集** `HARD_PROTECTED_PROCESSES`：explorer/taskmgr/dsh desktop/
+   dwm/winlogon/csrss/lsass 等系统进程，以及 fl2610/cx2610/mpiexec/smpd/fluent/
+   fluent-meshing/launcher1 —— 无论配置如何都拒绝管理。
+3. **持久化豁免白名单** `lib/whitelist.js` + 新工具 `sentinel_whitelist`
+   （list/add/remove/reset，kind=process|title）。落盘
+   `~/.dsh/console-sentinel/whitelist.json`，与静态 `config.whitelist` 合并，工具
+   改动即时生效、无需改 yml 或重启。白名单同时作用于自动动作与
+   `desktop_windows_cleanup`。
+4. **一键关闭其他窗口**（`desktop_windows_cleanup`）现在读统一白名单，
+   `protectedProcesses`/`keepTitles` 合并用户名单。
+5. `console_windows_list` 每行新增 `kids=`（子进程数）与 `[empty]` 标记。
+
+### 测试
+`desktop.test.mjs` D5 默认保护列表断言从 4 项更新为实际 9 项（实现更安全，测试
+落后于实现，改测试不改实现）。全套 `node --test` 51 断言全绿
+（logic 29 + desktop 17 + tool-output 5）。
+
+## 0.1.2 (2026-09-23) — the ledger claimed hides it never verified
+
+Reported by the user, correctly: “你说你隐藏了 13 个真的假的”. It was **partly
+false**. An independent Win32 check (`IsWindowVisible`) of the 13 hwnds the
+plugin had reported as `[hidden]` found **9 genuinely hidden, 4 already
+destroyed, and 1 still visible** (a minimised Windows Terminal). Three defects:
+
+1. **`hidden` was set from intent, not from observation** (`lib/index.js`
+   `actOn`). `rec.hidden = true` ran as soon as `runWindowAction` returned
+   `ok`, before anything re-checked the window. The action script *already*
+   measured the post-state (`afterVisible`, `stillWindow`) — the ledger simply
+   never looked at it. `hidden` is now derived from that measured state, and a
+   failed action can no longer leave a stale `hidden` claim behind.
+2. **“destroyed” and “hidden” were conflated.** A window that no longer exists
+   was counted as a successful hide, which inflated the reported number. There
+   is now a separate `destroyed` flag, surfaced in the list as `[gone]`, and a
+   gone window is never counted as hidden. This is why “I hid 13” was wrong:
+   4 of them were gone, not hidden.
+3. **`console_window_action` returned invalid output on every success**
+   (`lib/index.js`). It built `reason: res.ok ? undefined : res.reason`, so a
+   successful call carried an explicit `reason: undefined` against a
+   schema-declared `string` → validation failed and the runtime dropped the
+   whole result as *“value is not lossless JSON”*. The hide really happened;
+   the caller just never saw it. `reason` is now omitted on success (and
+   coerced to a string on failure) instead of being set to `undefined`.
+   **`desktop_windows_cleanup` had the identical defect** — and there it sat on
+   the tool's *normal* path (returning a dry-run plan), so it broke every call,
+   not just some. Fixed in both; a grep for the pattern now matches only the
+   explanatory comment.
+
+Also added:
+
+- **`probeVisibility()`** (`lib/probe.js`) — a lightweight batch
+  `IsWindowVisible` query (no full scan), used as an independent source of
+  truth.
+- **`ledger.reconcileVisibility()`** (`lib/logic.js`) — an anti-lie guard.
+  `console_windows_list` now re-measures every tracked window before printing,
+  so `[hidden]` can only appear for a window that is genuinely not visible at
+  that moment; windows missing from the truth map are reported as `[gone]`.
+
+Tests: `tests/logic.test.mjs` 24 → 29 assertions (destroyed-vs-hidden, and
+reconcileVisibility in all three directions); new `tests/tool-output.test.mjs`
+(5 assertions) locks the schema contract and **asserts the old shape was
+buggy**, so the defect cannot silently return.
+
+Lesson recorded: a plugin’s own ledger is not evidence. “The bookkeeping says
+success” and “the user can see it worked” are different claims, and only the
+second one is worth reporting — verify with something outside the component
+that is making the claim.
+
+## 0.1.1 (2026-09-22) — desktop-cleanup path repaired + protected set widened
+
+The console path (`console_windows_list` / `_action` / `_sweep`) was fine, but
+the **desktop-cleanup path was dead on arrival** — `desktop_windows_cleanup`,
+`desktop-cli.mjs list|cleanup`, and the 一键关闭其他窗口 shortcut all failed.
+Four defects, each found by running the code rather than reading it:
+
+1. **Marker never substituted** (`lib/desktop.js`). The probe template used
+   `'${JSON_BEGIN}'` but was never `.replace()`d, so the literal text
+   `${JSON_BEGIN}` reached PowerShell and `extractMarkeredJson` found nothing
+   → `no-marker-output`. `probe.js` had always done this correctly
+   (`.replace(/__JSON_BEGIN__/g, …)`); desktop.js now matches it.
+2. **`@(['Progman',…])` is a PowerShell parse error** (`lib/desktop.js`).
+   `SHELL_CLASSES_PS` wrapped the list in `[ … ]`, and the call site wrapped
+   that again in `@( … )` → *"Missing type name after '['"*, aborting the
+   probe before any window was enumerated.
+3. **Every selection guard silently fell through** (`lib/desktop.js`).
+   `selectCleanupTargets` read `w.hwnd` / `w.process` / `w.class` / `w.title`,
+   but the embedded probe emits **PascalCase** (`Hwnd` / `Process` / `Class` /
+   `Title`). All comparisons were `undefined !== anything`, so the foreground
+   guard, the shell-class filter **and the protected-process guarantee** did
+   nothing — DSH Desktop itself, explorer and Taskmgr landed in the close list.
+   Rows are now normalised through one `raw.x ?? raw.X` shim.
+4. **CLI crashed printing the plan** (`lib/desktop-cli.mjs`). `t.title.slice()`
+   on the same casing mismatch → `TypeError: Cannot read properties of
+   undefined`. Shares the normaliser now, and tolerates empty titles.
+
+### Protected set widened (user-approved, beyond upstream)
+
+Upstream protected only `powershell / pwsh / python / pythonw`. Each addition
+below was justified against a live probe, not guessed:
+
+| added | why |
+|---|---|
+| `dsh desktop` | closing the harness host kills the session |
+| `explorer` | shell/taskbar; multiple file-manager Hwnds share one pid |
+| `taskmgr` | closing Task Manager is a forced-end acting on other apps |
+| `fluent`, `launcher1` | Fluent Launcher / solver front-ends are long-running CFD work |
+
+### Verification
+
+- `node tests/logic.test.mjs` — **24/24 still pass** (no regression)
+- live probe: enumerates 30 windows, 10 visible consoles
+- `desktop-cli.mjs list` — 14–18 targets, **0** protected/foreground/shell-class
+  windows selected (DSH Desktop, explorer, Taskmgr, Fluent all correctly kept)
+- `desktop-cli.mjs cleanup` — dry run prints the plan, closes nothing
+
+## 0.1.0 (2026-09-16) — first MVP
+
+Host-side cordis plugin: auto-hide idle AI/script console windows on Windows.
+
+### Configured defaults (per user's MVP decision)
+- `autoAction: hide` (lossless; process keeps running, `show` restores it)
+- `idleThresholdSec: 60`, `cpuThresholdPct: 1`, `spikeTolerance: 2`
+- scope: `wmiDetached` + `dshHost` + `scriptConsole` ON, `orphaned` OFF
+- host-side only; no client bundle in v1
+
+### Empirical findings fixed during development
+1. **Windows Terminal windows are classified by title, not parent chain.**
+   A WT top-level window belongs to the WindowsTerminal process (parent
+   svchost), not to the script it hosts — parent-chain classification left
+   all 8 stacked black windows as `manual` (unmanaged). Added `script-console`
+   source keyed on the console title being a script executable path.
+   (Interactive consoles keep prompt-style titles like "Windows PowerShell"
+   and stay unmanaged.)
+2. **`SW_SHOW(5)` cannot restore a hidden WT window.** Measured: after
+   `SW_HIDE`, `SW_SHOW` leaves `IsWindowVisible` false; `SW_SHOWNORMAL(1)`
+   restores it. Show action now uses SW_SHOWNORMAL with SW_RESTORE fallback.
+3. **Single-sample CPU spikes reset the idle clock.** The WindowsTerminal
+   host process spikes briefly even when all its sessions are idle, so
+   stacked windows never accumulated 60s of idle. `spikeTolerance=2` now
+   requires two consecutive busy samples to break an idle streak.
+4. **`NtQueryInformationProcess` over CIM for parent-pid.** Measured 39 s vs
+   24 ms for 13 processes (`Get-CimInstance Win32_Process`). Full probe
+   ~350 ms at a 10 s scan interval.
+5. **dsh-tools output-schema constraints**: object schemas must declare
+   `additionalProperties` explicitly; output value schemas reject `required`.
+   Caught only by the real-runtime load precheck, not by `node --check`.
+
+### Verification
+- `node tests/logic.test.mjs` — 24/24 (classification, idle accumulation,
+  spike tolerance, scope guards, GC, ordering)
+- `node tests/e2e.mjs` — live probe (24 windows), reversible hide→show
+- load precheck against the profile's real cordis/schemastery/dsh-tools —
+  3 tools register, scheduler effect mounts, config defaults correct
+- privacy audit: 0 hits across 9 files; `npm pack` 8 files / 16.1 kB

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loyalchiiina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-es.md

@@ -0,0 +1,29 @@
+# Console Sentinel
+
+> Watch the browser console and DSH logs, surface errors early, and auto-hide finished console windows.
+
+> Full documentation: [English README](./README.md)
+
+## How it works
+
+> 📖 [Leer esta sección en el README principal](./README.md#how-it-works)
+
+## Install
+
+> 📖 [Leer esta sección en el README principal](./README.md#install)
+
+## Tools (model-visible)
+
+> 📖 [Leer esta sección en el README principal](./README.md#tools-model-visible)
+
+## Config (cordis.yml)
+
+> 📖 [Leer esta sección en el README principal](./README.md#config-cordisyml)
+
+## Safety
+
+> 📖 [Leer esta sección en el README principal](./README.md#safety)
+
+## Development
+
+> 📖 [Leer esta sección en el README principal](./README.md#development)

package/README-hi.md

@@ -0,0 +1,29 @@
+# Console Sentinel
+
+> Watch the browser console and DSH logs, surface errors early, and auto-hide finished console windows.
+
+> Full documentation: [English README](./README.md)
+
+## How it works
+
+> 📖 [यह अनुभाग मुख्य README में पढ़ें](./README.md#how-it-works)
+
+## Install
+
+> 📖 [यह अनुभाग मुख्य README में पढ़ें](./README.md#install)
+
+## Tools (model-visible)
+
+> 📖 [यह अनुभाग मुख्य README में पढ़ें](./README.md#tools-model-visible)
+
+## Config (cordis.yml)
+
+> 📖 [यह अनुभाग मुख्य README में पढ़ें](./README.md#config-cordisyml)
+
+## Safety
+
+> 📖 [यह अनुभाग मुख्य README में पढ़ें](./README.md#safety)
+
+## Development
+
+> 📖 [यह अनुभाग मुख्य README में पढ़ें](./README.md#development)

package/README-pt.md

@@ -0,0 +1,29 @@
+# Console Sentinel
+
+> Watch the browser console and DSH logs, surface errors early, and auto-hide finished console windows.
+
+> Full documentation: [English README](./README.md)
+
+## How it works
+
+> 📖 [Ler esta seção no README principal](./README.md#how-it-works)
+
+## Install
+
+> 📖 [Ler esta seção no README principal](./README.md#install)
+
+## Tools (model-visible)
+
+> 📖 [Ler esta seção no README principal](./README.md#tools-model-visible)
+
+## Config (cordis.yml)
+
+> 📖 [Ler esta seção no README principal](./README.md#config-cordisyml)
+
+## Safety
+
+> 📖 [Ler esta seção no README principal](./README.md#safety)
+
+## Development
+
+> 📖 [Ler esta seção no README principal](./README.md#development)

package/README-zh.md

@@ -0,0 +1,29 @@
+# dsh-console-sentinel
+
+> 盯住浏览器控制台与 DSH 日志，提前发现报错，并自动隐藏已经跑完的控制台窗口。
+
+> 完整文档以 [English README](./README.md) 为准，本页提供中文导读与关键信息速查。
+
+## How it works
+
+本节内容详见 [English README](./README.md)。
+
+## Install
+
+本节内容详见 [English README](./README.md)。
+
+## Tools (model-visible)
+
+本节内容详见 [English README](./README.md)。
+
+## Config (cordis.yml)
+
+本节内容详见 [English README](./README.md)。
+
+## Safety
+
+本节内容详见 [English README](./README.md)。
+
+## Development
+
+本节内容详见 [English README](./README.md)。

package/README.en.md

@@ -0,0 +1,127 @@
+# dsh-console-sentinel
+
+Auto-hide (or close) idle AI/script console windows on Windows — a
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin.
+
+Long-running harness workflows (unattended Fluent jobs, batch scripts,
+WMI-launched detached processes) leave PowerShell/Python console windows
+stacked in the taskbar. You cannot tell which are still working and you do not
+want to kill them by hand. This plugin tracks them, tells busy from finished,
+and hides the finished ones for you — the process keeps running, nothing is
+lost, and every window can be brought back on demand.
+
+## How it works
+
+1. Every `scanIntervalSec` seconds (default 10) it enumerates console windows
+   with a zero-dependency Windows PowerShell probe (`user32` + `ntdll`
+   P/Invoke): `CASCADIA_HOSTING_WINDOW_CLASS` (Windows Terminal),
+   `ConsoleWindowClass` (classic conhost), and `PseudoConsoleWindow` (ConPTY).
+2. Each console's process is classified: by its **parent process**
+   (`WmiPrvSE.exe` → `wmi-detached` — WMI-launched detached jobs, how
+   unattended Fluent runs are started; `DSH Desktop.exe` → `dsh-host`;
+   parent already exited → `orphaned`), or, when the parent chain is
+   uninformative (a Windows Terminal window belongs to the WindowsTerminal
+   process, not to the script it hosts), by the **console title**: a scripted
+   session defaults its title to the launched executable path
+   (`...\python.exe`), while an interactive console keeps a prompt-style
+   title (`Windows PowerShell`) → `script-console`.
+3. CPU usage is sampled per scan (process total CPU time deltas). A window
+   under `cpuThresholdPct` (default 1%) for `idleThresholdSec` (default 60)
+   counts as **finished**. Single-sample background jitter does not reset the
+   idle clock (`spikeTolerance`, default 2).
+4. Finished windows **in scope** get the configured `autoAction`
+   (default `hide` = `SW_HIDE`; the process keeps running). `close` sends
+   `WM_CLOSE`. The focused window is never touched (`guardForeground`).
+
+Parent-pid lookup uses `NtQueryInformationProcess` rather than CIM
+(`Get-CimInstance Win32_Process`), which measured **39 s vs 24 ms** for 13
+processes on the reference machine. A full probe takes ~350 ms.
+
+## Install
+
+```sh
+dsh plugin --profile <name> add dsh-console-sentinel
+```
+
+Bundle plugin (`dsh.bundle.patch`): enters the profile bundle stack, takes
+effect on restart. Windows-only — the patch row is `disabled` on every other
+platform and `apply()` also guards at runtime.
+
+## Tools (model-visible)
+
+- `console_windows_list` — every tracked console window with idle state and
+  origin classification. Use this first.
+- `console_window_action` — hide / show / minimize / restore / close one
+  window (by `hwnd` or `pid`). `hide` is lossless; `close` may lose unsaved
+  output. Pass `force` to act on the focused window.
+- `console_windows_sweep` — apply the action to every idle in-scope window at
+  once (handy after a batch of Fluent jobs).
+- `desktop_windows_cleanup` — **close all other windows**: close every desktop
+  app window except the focused one, self, shell classes, and protected
+  processes (`dryRun` first for a plan; `protected` / `keepTitle` / `keepPid`
+  add temporary protection).
+- `sentinel_whitelist` — manage the **persistent exemption whitelist**:
+  `list` / `add` / `remove` / `reset`, `kind=process` (image name, e.g.
+  `code.exe`) or `kind=title` (title substring). Applies to both auto-actions
+  and desktop cleanup; stored at `~/.dsh/console-sentinel/whitelist.json`.
+
+## Config (cordis.yml)
+
+| Key | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | master switch |
+| `scanIntervalSec` | `10` | how often to scan + sample CPU |
+| `idleThresholdSec` | `60` | sustained-low-CPU seconds before a window counts as finished |
+| `cpuThresholdPct` | `1` | average CPU below this = idle |
+| `autoAction` | `hide` | `none` \| `hide` \| `close` |
+| `probeTimeoutMs` | `20000` | hard probe timeout |
+| `spikeTolerance` | `2` | consecutive busy samples needed to reset the idle clock |
+| `guardForeground` | `true` | never auto-manage the focused window |
+| `scope.wmiDetached` | `true` | manage WMI-launched detached consoles |
+| `scope.dshHost` | `true` | manage host-spawned consoles |
+| `scope.orphaned` | `false` | manage consoles whose parent already exited |
+| `scope.scriptConsole` | `true` | manage consoles whose title is a script executable path (Windows Terminal windows hosting a scripted session) |
+| `scope.excludeTitles` | `[]` | title substring blocklist |
+| `scope.emptyConsole` | `true` | treat an interpreter console (PowerShell/Python/cmd with only conhost and **no workload child**) as an empty shell and manage it regardless of parent chain — the safe way to clean up leftover empty PowerShell windows without enabling the whole `orphaned` scope (which would also match mpiexec / fl2610 / live compute) |
+| `emptyConsoleAction` | `hide` | action for empty shells: `none` \| `hide` \| `close`; independent of `autoAction` |
+| `whitelist.processes` | `[]` | exempt image names (e.g. `code.exe`), never auto-managed nor bulk-closed (edit at runtime via `sentinel_whitelist`) |
+| `whitelist.titles` | `[]` | exempt title substrings, never auto-managed nor bulk-closed |
+
+```yaml
+- id: dsh-console-sentinel
+  config:
+    idleThresholdSec: 90
+    scope:
+      excludeTitles:
+        - keep-alive
+```
+
+## Safety
+
+`hide` only calls `ShowWindow(SW_HIDE)` — the process, its logs, and its
+output are untouched; `console_window_action` with `show` restores it
+(`SW_SHOWNORMAL` — measured: `SW_SHOW` leaves a hidden Windows Terminal
+window invisible). `close` sends `WM_CLOSE` (graceful, same as clicking the
+X) but may lose unsaved state, so it is never the default. Automatic actions
+never touch the focused window, manually opened consoles (`manual` source),
+title-blocklisted or **whitelisted** windows, or any process in
+`HARD_PROTECTED_PROCESSES` (explorer, taskmgr, dsh desktop,
+fl2610/cx2610/mpiexec/smpd/fluent, etc.). Every action is emitted as
+`console-sentinel/action` and logged.
+
+## Development
+
+```
+lib/index.js      Cordis plugin: config, scan scheduler, tools
+lib/logic.js      pure ledger/idle state machine + empty-console detection (unit-tested)
+lib/probe.js      embedded PowerShell probe + window actions
+lib/desktop.js    desktop-wide window close (一键关闭其他窗口)
+lib/whitelist.js  persistent exemption whitelist (JSON)
+tests/            node-only regression tests, no live Windows needed
+```
+
+`node --test tests/*.test.mjs` — 51 assertions (logic 29 + desktop 17 +
+tool-output 5) covering classification, idle accumulation, busy-blip reset,
+scope guards, empty-console detection, whitelist, GC, and ordering.
+
+MIT License.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# dsh-console-sentinel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+自动隐藏（或关闭）Windows 上空闲的 AI/脚本控制台窗口 —— 一个
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件。
+
+长时间运行的自动化工作流（Fluent 无人值守任务、批量脚本、WMI 拉起的脱离进程）
+会在任务栏堆下一排 PowerShell/Python 黑窗口。你分不清哪些还在跑，也不敢随手关。
+本插件替你追踪它们、区分「在忙」和「用完了」，并把用完的隐藏掉 —— 进程继续跑、
+数据不丢，每个窗口都能随时叫回来。
+
+## 工作原理
+
+1. 每隔 `scanIntervalSec` 秒（默认 10）用零依赖的 Windows PowerShell 探针
+   （`user32` + `ntdll` P/Invoke）枚举控制台窗口：`CASCADIA_HOSTING_WINDOW_CLASS`
+   （Windows Terminal）、`ConsoleWindowClass`（传统 conhost）、
+   `PseudoConsoleWindow`（ConPTY 伪控制台）。
+2. 按进程归类：优先看**父进程**（父进程是 `WmiPrvSE.exe` → `wmi-detached`，
+   WMI 拉起的脱离任务，无人值守 Fluent 计算正是这样启动的；父进程是
+   `DSH Desktop.exe` → `dsh-host`；父进程已退出 → `orphaned`）。当父链说明
+   不了问题时（Windows Terminal 的窗口归属于 WindowsTerminal 进程，而不是
+   它里面跑的脚本），改看**控制台标题**：脚本启动的控制台标题默认是
+   被启动程序的路径（`...\python.exe`），而交互式手开的控制台是提示符式
+   标题（`Windows PowerShell`）→ 归为 `script-console`。
+3. 每轮采样进程 CPU（累计 CPU 时间差值）。CPU 低于 `cpuThresholdPct`（默认 1%）
+   且持续 `idleThresholdSec`（默认 60 秒）即判定为**用完了**。单次采样的后台
+   CPU 抖动不会重置空闲时钟（`spikeTolerance`，默认 2）。
+4. 在管理范围内的「用完了」窗口执行配置的 `autoAction`（默认 `hide` = `SW_HIDE`，
+   进程继续跑）。`close` 发送 `WM_CLOSE`。前台窗口永不自动处理（`guardForeground`）。
+
+父进程 PID 用 `NtQueryInformationProcess` 而非 CIM（`Get-CimInstance Win32_Process`）
+—— 参考机上实测 **39 秒 vs 24 毫秒**（13 个进程）。单次完整探针约 350 毫秒。
+
+## 安装
+
+```sh
+dsh plugin --profile <name> add dsh-console-sentinel
+```
+
+Bundle 插件（`dsh.bundle.patch`）：进入 profile bundle 栈，重启后生效。
+仅限 Windows —— patch 行在其他平台 `disabled`，`apply()` 运行时也会再守一次。
+
+## 工具（模型可见）
+
+- `console_windows_list` —— 列出所有被追踪的控制台窗口及其空闲状态和来源归类。先用它。
+- `console_window_action` —— 对单个窗口执行 hide / show / minimize / restore / close
+  （用 `hwnd` 或 `pid` 定位）。`hide` 无损；`close` 可能丢失未保存输出。
+  对前台窗口操作需传 `force`。
+- `console_windows_sweep` —— 一次性对所有空闲且在范围内的窗口执行动作
+  （跑完一批 Fluent 任务后清任务栏很好用）。
+- `desktop_windows_cleanup` —— **一键关闭其他窗口**：关闭桌面上除前台、自身、
+  系统外壳和受保护进程以外的所有应用窗口（`dryRun` 先出计划；`protected` /
+  `keepTitle` / `keepPid` 可临时加固保护）。
+- `sentinel_whitelist` —— 管理**持久化豁免白名单**：`list` / `add` / `remove` / `reset`，
+  `kind=process`（按映像名，如 `code.exe`）或 `kind=title`（按标题子串）。
+  白名单同时作用于自动隐藏/关闭与一键关闭窗口，落盘到
+  `~/.dsh/console-sentinel/whitelist.json`。
+
+## 设置面板（DSH 设置页 · 0.3.0+）
+
+插件在 DSH「设置」里注册「控制台哨兵」分区（客户端 bundle `lib/client.js`），
+不记工具名也能点操作：
+
+- **概览**：总窗口 / 空壳 PowerShell / 可见空壳 / 已隐藏 计数 + 「隐藏可见空壳」。
+- **任务栏窗口清理**：预演 / 一键关闭其他窗口（前台、系统进程、白名单自动跳过）。
+- **控制台窗口**：逐行显示进程名 / 标题 / hwnd / pid / CPU / 空闲秒数 / 子进程数，行内可隐藏 / 显示 / 关闭。
+- **豁免白名单**：进程名与标题关键字 标签式增删、清空，即时落盘。
+
+面板通过宿主路由 `/dsh-console-sentinel/*` 取数（客户端 fetch 根相对路径，桌面端自动带
+capability header），不使用 iframe。改 `lib/client.js` 后按 **Ctrl+Shift+R** 硬刷新；
+改宿主（`lib/index.js` / `package.json`）需**完全退出 DSH 再启动**。
+
+## 配置（cordis.yml）
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `enabled` | `true` | 总开关 |
+| `scanIntervalSec` | `10` | 扫描 + CPU 采样间隔 |
+| `idleThresholdSec` | `60` | 持续低 CPU 多少秒算「用完了」 |
+| `cpuThresholdPct` | `1` | CPU 低于此值算空闲 |
+| `autoAction` | `hide` | `none` \| `hide` \| `close` |
+| `probeTimeoutMs` | `20000` | 探针硬超时 |
+| `spikeTolerance` | `2` | 连续多少次「忙」采样才重置空闲时钟 |
+| `guardForeground` | `true` | 永不自动处理前台窗口 |
+| `scope.wmiDetached` | `true` | 管理 WMI 拉起的脱离控制台 |
+| `scope.dshHost` | `true` | 管理宿主派生的控制台 |
+| `scope.orphaned` | `false` | 管理父进程已退出的控制台 |
+| `scope.scriptConsole` | `true` | 管理标题是脚本可执行文件路径的控制台（Windows Terminal 承载的脚本会话） |
+| `scope.excludeTitles` | `[]` | 标题 substring 黑名单 |
+| `scope.emptyConsole` | `true` | 把「没有任何工作子进程」的解释器控制台（PowerShell/Python/cmd 只剩 conhost）判为**空壳**，无论父链如何都纳入管理 —— 这是安全清理残留空 PowerShell 的开关（不必打开整个 `orphaned`，后者会误伤 mpiexec/fl2610/在跑的计算） |
+| `emptyConsoleAction` | `hide` | 对空壳控制台的动作：`none` \| `hide` \| `close`；独立于 `autoAction`，即便自动动作关闭也能单独生效 |
+| `whitelist.processes` | `[]` | 豁免进程映像名（如 `code.exe`），永不自动处理/一键关闭（运行时用 `sentinel_whitelist` 增删） |
+| `whitelist.titles` | `[]` | 豁免标题子串，永不自动处理/一键关闭 |
+
+```yaml
+- id: dsh-console-sentinel
+  config:
+    idleThresholdSec: 90
+    scope:
+      excludeTitles:
+        - keep-alive
+```
+
+## 安全性
+
+`hide` 只调用 `ShowWindow(SW_HIDE)` —— 进程、日志、输出一概不动；
+`console_window_action` 的 `show` 可随时恢复（用 `SW_SHOWNORMAL` ——
+实测 `SW_SHOW` 无法恢复被隐藏的 Windows Terminal 窗口）。`close` 发 `WM_CLOSE`
+（优雅关闭，和你点 X 一样），但可能丢失未保存状态，所以从不是默认动作。
+自动动作绝不触碰：前台窗口、手动打开的控制台（`manual` 来源）、
+标题命中黑名单或**白名单**的窗口、以及 `HARD_PROTECTED_PROCESSES` 里的系统/计算进程
+（explorer、taskmgr、dsh desktop、fl2610/cx2610/mpiexec/smpd/fluent 等）。
+每个动作都发 `console-sentinel/action` 事件并写日志。
+
+## 开发
+
+```
+lib/index.js   Cordis 插件：配置、扫描调度、工具
+lib/logic.js   纯台账/空闲状态机（单测覆盖）
+lib/probe.js   内嵌 PowerShell 探针 + 窗口动作
+tests/         仅 node 的回归测试，不需要真实 Windows
+```
+
+`node tests/logic.test.mjs` —— 24 项断言，覆盖来源归类、空闲累积、
+忙碌脉冲重置、范围守卫、台账 GC、排序。
+
+MIT License。