DSH-RESTART-TOOL

> Reliable restart & shutdown for DeepSeek Harness (dsh) web, for agents (model tools) and the GUI (sidebar power control). > 可靠地重啟 / 關閉 DeepSeek Harness (dsh) web 服務，供 agent（模型工具） 與 GUI（側邊欄電源控制） 使用。


Why this exists / 為什麼存在

On Windows, naive restart flows end with "the port closes but nothing comes back". We hit every one of these traps and worked around them in code — worth knowing even if you never install this plugin: 在 Windows 上，「普通重啟」往往以「端口關了、服務沒起來」收場。以下四個坑我們都踩過並在代碼裡繞過——就算你不裝這個插件，也值得知道：

1. Async spawn race (the sneakiest) / 異步 spawn 競態（最隱蔽） — Node's child_process.spawn is async on Windows. A helper that spawns and then drains its event loop (child.unref() with nothing else pending) exits before CreateProcess finishes — the new process is never created, leaving only empty logs. Fix: await the 'spawn' event (with retry) or keep the event loop referenced (polling / a listener). Node 在 Windows 上 child_process.spawn 是異步的：helper 在 spawn(...) 後若事件循環立即清空，會在進程創建完成前退出——新進程從未被創建，只剩兩個空日誌。修法：等 'spawn' 事件（失敗重試）或保持事件循環被引用。 2. The agent sandbox kill-on-close job / agent 沙箱 kill-on-close job — DSH wraps the agent shell in a JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE job (no breakaway): when the host dies, the agent's shell and everything it spawned die with it. An agent can never reliably kill-and-relaunch the host itself; the reliable path is for the HOST to spawn the helper (a host child is outside that job). DSH 給 agent 的 shell 套了 kill-on-close job（無 BREAKAWAY）：宿主一死，agent 的 shell 及其 spawn 的一切全部陪葬。可靠的路徑是讓宿主自己 spawn helper（宿主的子進程不在這個 job 裡）。 3. SIGTERM is an uncatchable hard kill on Windows / Windows 上 SIGTERM 是不可捕獲硬殺 — process.kill(pid, 'SIGTERM') maps to TerminateProcess; DSH's graceful SIGTERM handler never runs. Only Ctrl+C (SIGINT) is catchable. process.kill(pid,'SIGTERM') 在 Windows 映射為 TerminateProcess，優雅關閉處理器不會執行；只有 Ctrl+C（SIGINT）可捕獲。 4. taskkill /T /F kills the helper too / taskkill /T /F 會殺到 helper 自己 — if the helper is a child of the host, a tree kill takes out the process that is supposed to relaunch the host. Kill a single process, or exclude your own chain during tree traversal. 若 helper 是宿主的子進程，樹殺會把負責拉起的 helper 一起幹掉。要麼精確殺單個進程，要麼在樹遍歷時排除自身鏈。

Features / 功能

Install / 安裝

dsh plugin --profile web add github:julensun-ir/DSH-RESTART-TOOL
# or local / 或本地
dsh plugin --profile web add file:./dsh-restart-tool

Restart dsh to activate. Optional config (in the profile's cordis.patch.yml): 重啟 dsh 生效。可選配置（profile 的 cordis.patch.yml）：

- id: dsh-restart-tool
  config:
    watchdogEnabled: true      # supervisor, default off / 監督者，默認關閉
    watchdogCooldownMs: 60000
    watchdogPollMs: 2000
    autoContinueEnabled: true
    continuePrompt: "The system has restarted. Please continue the work that was in progress."

GUI usage / GUI 使用

At the bottom of the sidebar (footer actions) you get two icon-only buttons (no text, so they do not squeeze neighbouring items such as the usage-stats row): 側邊欄底部出現兩個純圖標按鈕（無文字，避免擠壓相鄰項目如用量統計）：

• Refresh icon (Restart) / 刷新圖標（重啟） — click → full-screen "Restarting DeepSeek Harness…" overlay → the page auto-reloads once the new instance is up; hover shows a tooltip / 點擊後顯示全屏遮罩，新實例起來後頁面自動刷新，懸停有提示。
• Power icon (Shutdown) / 電源圖標（關機） — graceful shutdown, no auto-relaunch (start dsh manually afterwards) / 優雅關閉，不會自動重啟。
• Status dot / 狀態圓點 — green = online, red = offline/restarting, grey = unknown / 綠=在線，紅=離線/重啟中，灰=未知。

Architecture / 架構

Host process (node bin.js web)
 ├─ plugin apply (inject: tools, agents): tools / routes / auto-resume / watchdog
 ├─ restart_dsh called:
 │    ├─ runningSessionIds(ctx) records running sessions (an agent-triggered call captures the current session)
 │    ├─ writes the intent marker + resume marker
 │    ├─ spawns a detached helper (detached, windowsHide, a real .cjs file)
 │    └─ ctx.appExit graceful exit after 2s → hard-kill backstop at 12s
 ├─ new instance apply:
 │    ├─ reads the marker (time-window match, compatible with the hidden-console wrapper) → status reports restarted
 │    └─ tryAutoContinue: polls agents.get(sessionId), injects the "continue" nudge once resumed
 └─ helper (a host child, outside the sandbox job, survives the host's death):
      ├─ waits for the port to free (up to 90s)
      ├─ relaunches with the same command line (Windows: hidden-console powershell wrapper)
      ├─ awaits the 'spawn' event (retry ×3) → confirms the process exists
      ├─ updates marker.newPid → the new host self-proves the restart
      └─ verifies HTTP 200 → exits

Relationship with similar plugins / 與同類插件的關係

This plugin combines an agent tool + GUI power control + a full verification loop (spawn confirmation + HTTP 200 + marker self-proof + auto-resume). Honest caveats / 誠實聲明: the watchdog is not battle-tested in production; macOS/Linux paths are untested (POSIX branches exist but unverified); the shutdown action is mechanism-verified only. For full cross-platform production assurance, also look at dsh-power-button and anweat/dsh-restart. 本插件提供 agent 工具 + GUI 電源控制 + 完整驗證閉環（spawn 確認 + HTTP 200 + marker 自證 + 續跑提示）。誠實聲明：watchdog 未在生產環境實戰；macOS/Linux 未實測；關機僅機制驗證。如需全平台生產級保障，請同時參考 power-button 與 anweat/dsh-restart。

Verification / 驗證清單

• [x] Automated: GET /dsh-restart/status restarted:true + fromInstanceId logic (marker time-window match) — covered by the test suite
• [x] Automated: helper log (port free, spawned pid, http200=true) — covered by the test suite (real helper subprocess + fake host)
• [ ] New host PID differs from the old one, HTTP 200 — live check (helper newPid + HTTP 200 are suite-covered)
• [ ] An agent-triggered restart delivers the "continue" nudge to the session — live check (nudge injection is suite-covered)
• [ ] After shutdown, dsh-stopped.flag exists and the port is no longer listening — live check (flag write is suite-covered)

Testing / 測試

npm test

Zero-dependency suite built on Node's built-in node:test runner (runs in one process — the node --test CLI runner spawns per-file subprocesses over pipes, which the DSH agent sandbox blocks with EPERM):

The three dsh peer imports (@deepseek-ai/dsh-tools, dsh-llm, schemastery) are stubbed via an ESM resolve hook (test/loader.mjs) — the real packages live in the dsh runtime. Integration tests assert through the log/marker files the spawned processes write, since the sandbox blocks capturing subprocess stdout.

License / 許可證

MIT