@zhengjunyao/dsh-restart

September 19, 2026 · View on GitHub

English | 中文

A restart button for DeepSeek Harness. Installing or updating a plugin changes host-side code, and only a fresh dsh web process picks it up — that used to mean going back to a terminal. Now it is one click in the Web GUI: the page reconnects on its own, and if the new process fails to boot, the error is shown right there (an in-page overlay, plus a recovery console on its own port that stays up even when DSH is dead).

Why

A self-restart is the moment things go wrong invisibly: the tab loses its server, the new process crashes, and the only trace is in a terminal you already left. dsh-restart handles all three:

  • one click from the settings card or the sidebar entry;
  • two strategies, auto-detected — when the host is a launchd job (com.dsh.web, KeepAlive), the helper delegates with launchctl kickstart -k and only observes (spawning our own host would race the job for the port); otherwise it relaunches the exact same command (argv / cwd / env / Node flags) after waiting for the port to be actually released, instead of guessing with a fixed delay;
  • the new process's stdout+stderr stream into a log, the lines that look like errors are lifted out, and the helper's recovery console (http://127.0.0.1:3099 by default, CORS-open) keeps answering after DSH is gone — showing phase, boot log, error lines and exit code, with a one-click retry.

Features

  • Settings card 「重启」, sidebar entry next to your other plugin entries, and a full-screen overlay while the handoff happens.
  • Auto-reconnect: the page probes /api/dsh-restart/probe and reloads itself as soon as the new host answers (autoReload, on by default).
  • Failure handling: error lines are detected (Error / EADDRINUSE / MODULE_NOT_FOUND / stack frames), the boot log is shown in the overlay, and maxAttempts (default 2) automatic retries run before giving up.
  • Readiness is not "the port answers": dsh web binds its port before the plugin tree loads, so the helper only reports ready once the port answers, the process is still alive, and the boot output carries no fatal line — held over readyConfirmMs (4s) first, then watched for bootWatchMs (30s) so a host that reports ready and dies seconds later is reclassified as a failed restart instead of a silent success.
  • Agent tools: dsh_restart_status (read-only) and dsh_restart, which demands confirm: true because the local standing rule is that DSH is never restarted without explicit user consent.
  • Stale-tab recovery: a restart's failure state lives in the page, so once the host is back (or launchd rescued it) the page clears that leftover "boot failed" text by itself — it keeps probing a failed state, re-checks on focus, and drops a persisted failure the moment the host answers.
  • Fresh-token self-heal: every dsh web boot mints a new launch token, so an old tab's URL is refused with 401 once its cookie is gone. The page then swaps the current process's token for a cookie in place (same authority as the tab, no navigation) and reloads only after the tab really authenticates — a restart ends with the app back on screen, not with an address to copy. If even that fails it falls back to the clickable 「用新 token 地址打开」 link, so a dead cookie can never turn a reload into the host's plain-text 401 page.
  • Bookmarkable entry: GET /api/dsh-restart/goto always answers 303 with a relative Location carrying the current process's token, so the one URL that never expires is also the one that works on any authority. It is what the 401 card hands out — bookmark it and a missing cookie stops mattering.
  • The waiting overlay says don't reload manually (the port is dead for ~3–5s, then the page returns by itself): refreshing inside the restart window lands on ERR_CONNECTION_REFUSED, where the browser has replaced the page and no client-side recovery can run.
  • History at ~/.dsh/dsh-restart/history.json; logs under ~/.dsh/dsh-restart/logs/; config at ~/.dsh/dsh-restart.json (0600).

Install

dsh plugin --profile web add @zhengjunyao/dsh-restart   # npm
dsh plugin --profile web add link:/path/to/dsh-restart
# or, from GitHub (repo tagged with the dsh-plugin topic)
dsh plugin --profile web add github:zhengjy01/dsh-restart

Restart dsh web once to load it — the last manual restart you need.

HTTP surface

All loopback-only, same-origin, matching the other dsh-* panels: GET /status, GET /probe, GET /auth, POST /restart, GET /logs, GET /history, POST /config, GET /helper, POST /helper/retry — all under /api/dsh-restart/. GET /auth is intentionally cookie-free (still loopback only): the tab that needs the fresh token URL is the one whose token just went stale.

How it works

panel / dsh_restart
      │ POST /api/dsh-restart/restart
      ▼
  host (old process) ──writes pending-spec.json──▶ detached helper (zero deps)
      │ replies 202, SIGTERMs itself ~0.7s later              │
      ▼                                                       │ waits for the port
   process exits ─────────────────────────────────────────────┤
                                                              ▼
                                     spawns the new host with the same command
                                     (stdout/stderr → logs/<stamp>-<pid>.log)
                                                              │
                     status.json ◀── phase/progress/errors ───┤
                     http://127.0.0.1:3099 ◀── recovery console┘
                                                              │
   page polls /probe ──▶ new host answers ──▶ location.reload()┘

Compatibility

  • Requires DeepSeek Harness ≥ 0.1.5-rc.1 (declared as dsh.engines.dsh).
  • Verified against: 0.1.5-rc.1 on macOS with Node 25.8.1 — host half, browser half and a real restart.
  • Platforms: only macOS has actually been exercised. When the host is launchd-managed, the helper delegates with launchctl kickstart -k; elsewhere it falls back to relaunching the same command itself (the launchd path is platform-guarded; Linux and Windows are untested).
  • Compatibility is also derived from the union of the @deepseek-ai/dsh-* peerDependencies ranges, which is what the plugin market displays.

Tests

pnpm test    # 208 assertions across six suites

smoke (config/history/log detection/host identity), helper (the real helper against fake hosts: crash capture + console + manual retry, and a successful relaunch), routes (synthetic req/res, including the loopback/cross-site/method guards and the connection→token-URL wiring), handoff (end-to-end on fake ports: restart → old process really exits → helper relaunches generation 2 → the port answers with a new pid), launchd (pid→job matching and observe mode, which must never spawn), selfheal (the real browser bundle with stubbed globals: a persisted "boot failed" whose host recovered is cleared on mount, and a 401 page gets the current token URL instead of a dead reload).

Limits

  • Only restarts: it does not install plugins or repair a profile (that is dsh-doctor's job).
  • A restart always interrupts the current turn and connection — replacing the host process cannot be invisible. What is guaranteed is that the interruption is observable, recoverable, and its errors readable.
  • The helper registers no OS-level service; it lives for one restart and exits after readiness (or stays put on failure until you deal with it).

License

MIT