DSH Plugins Marketplace

DSH Plugins

Plugins

/

dsh-restart-win

B

dsh-restart-win

Manifest valid

Fail-closed safe restart for DSH on Windows: prove a throwaway instance boots before the running host is touched, then detach through a scheduled task so the restarter survives the host it restarts.

UI (client)hasBundlePatch

dsh-restart-win

A Windows-only, verify-before-you-stop restart engine for a DSH host. It boots a throw-away instance in a temporary home on a free port, proves that this configuration can come up, and only then touches the instance that is serving you. The stop and the launch run from a detached supervisor or a scheduled task, so the host dying cannot take the executor with it.

@brainzombie/dsh-restart-win · Windows 10/11 · Node ≥ 20 · DSH 0.2.x · MIT

English | 中文


1. What this is

A DSH host plugin that turns "restart safely" into five verifiable steps:

  1. Discover — the authority for "which process is the host" is the port listener from netstat -ano -p TCP, not WMI/CIM and not command-line matching.
  2. Prove — boot a real instance in an isolated home on a free port. Only 401/200 counts as ready (404 means the port is bound but routes are not registered yet).
  3. Gate — if the preflight fails, nothing moves: the old instance is untouched, the call returns a non-zero exit code with a reason.
  4. Stop and launch — write the resume notice → stop the old instance → wait until the port is actually bindable → rebuild the environment block → launch → verify port ownership and the parent chain.
  5. Close out — every outcome writes an audit record; if the abort happened after the stop, try one rescue launch.

It is an engine, not a button. The four host tools and the CLI all drive the same PowerShell script, scripts/dsh-restart.ps1, and keep the old engine's parameters, exit codes, terminal words and state files.


2. How it differs from the restart plugins already out there

Most restart options are "a button that restarts immediately" or "a watchdog outside the process that retries". These are the 13 projects that GitHub's dsh-plugin topic returned by stars in 2026-11:

ProjectShapeRelation to this plugin
anweat/dsh-restart (npm dsh-restart)Configurable restart + post-restart prompt resume + watchdogOverlapping (resume, watchdog); different package name
npm dsh-restart-guardOut-of-process watchdog, restarts and reports to IM/webhookComplementary: it watches from outside, this plugin initiates from inside
edusrez/dsh-smart-restartRestart detection + agent wake-up + systemd unit + canaryComplementary: this plugin owns the Windows-side verification and stop, it owns returning to the session
893413974-bit/dsh-setting-restartSettings-page one-click restartDifferent shape (UI button)
xiaolu511/dsh-hot-restartIn-window button, restarts and reopensDifferent shape (UI button)
luoshuizhiwei/dsh-desktop-restartDesktop restart button + downtime readoutDifferent shape (UI button)
1123762794/dsh-web-restartSidebar one-click web restartDifferent shape (UI button)
PPsz-qqq/dsh-restart-buttonSession-header restart button + waits for tasksDifferent shape (UI button)
xichen-62/dsh-power-menuDesktop power menu (shut down / restart)Different shape (UI menu)
keyiadiannao/dsh-power-buttonSidebar power button + its own restart engineDifferent shape (UI button)
regrevia/dsh-unlagDesktop refresh buttonDifferent capability
hulibuld/dsh-refresh-restartRefresh/restart buttonDifferent shape (UI button)
fakechris/dsh-harness-opsA/B snapshot upgrades + supervised launch + doctorAdjacent (self-healing), via snapshot upgrades

The differences concentrate in five places:

Button-styleWatchdog-styleThis plugin
Proves the new configuration boots before stoppingNoNoYes — isolated home, free port, one real boot
Process discoveryRemembered pid or nameRemembered pidPort listener, with parent-chain verification
Stops without verificationYesYesRefuses (-Fast without -ForceUnverified → exit code 10)
Executor leaves the host process treeNoYesYes — detached supervisor or scheduled task
Scriptable read-only surfaceUsually nonePartialYes — single-JSON -Status -Json, stable exit codes

It does not provide "return to the previous conversation after the restart": the host does that by consuming <DshHome>\.smart-restart\pending-notice.json (which is what a plugin like dsh-smart-restart does). This plugin only guarantees the notice is written before the stop.


3. Requirements

ItemRequirementNotes
OSWindows 10 / 11The engine targets Windows only; elsewhere there is no PowerShell and the tools fail with an explicit error
PowerShellpwsh 7.4+A verified restart needs Start-Process -Environment. With only 5.1, -Status / -DryRun / -Stop / -Start / -Fast work, and any action that needs deep verification aborts before the stop with exit code 2 engine-requires-pwsh
Node.js≥ 20The host's own runtime; the detached launcher lib/delayed-spawn.mjs runs on the same node
DSH0.2.x (>=0.2.1-rc.1 <0.3.0-0)See dsh.compatibility in package.json
RightsAble to terminate the host processUsually no elevation for a host started by the same user; the scheduled task registers as HighestAvailable

4. Install

4.1 Check the patch against your profile first (no install needed)

dsh --profile web --dump-config --patch .\cordis.patch.yml

This only composes the layer stack: it overlays the patch on the target profile's configuration and prints the result. It changes no configuration and needs no restart. Exit code 0 plus a dsh-restart-win row in the output means this patch resolves for this profile.

It does not activate the plugin. Activation is 4.2 / 4.3 below, followed by the host restart you perform in 4.4.

4.2 Add it to a profile

# from the GitHub repository (the current distribution channel)
dsh plugin --profile web add github:BrainZombie/dsh-restart-win

# pin a commit (reproducible install)
dsh plugin --profile web add github:BrainZombie/dsh-restart-win#<sha>

# or point at a local checkout
dsh plugin --profile web add <repo>

This version is not published to npm: dsh plugin --profile web add @brainzombie/dsh-restart-win only works once the package is on npm. Until then, use one of the GitHub forms above.

dsh plugin add forwards its arguments to pnpm inside that profile directory and records the dependency in the profile's package.json. The plugin inserts its own dsh-restart-win row through its cordis.patch.yml.

It also has to be activated: append the package to dsh.profile.bundles. dsh plugin add only puts the package into node_modules and dependencies. At startup the host composes the tree from the profile's layer stack, which has exactly three sources: the explicit dsh.profile.bundles list, the profile's own cordis.patch.yml, and the launcher's --patch. Without this step the host prints skipping profile bundle "@brainzombie/dsh-restart-win", or simply never loads the plugin's tools.

Open %USERPROFILE%\.dsh\profiles\<profile>\package.json and append the package name to the end of dsh.profile.bundles (append; order does not affect this plugin):

// %USERPROFILE%\.dsh\profiles\<profile>\package.json
"dsh": {
  "profile": {
    "bundles": [
      /* ...keep every existing entry... */,
      "@brainzombie/dsh-restart-win"
    ]
  }
}

Never replace or empty the existing list: @deepseek-ai/dsh-base, @deepseek-ai/dsh-web-app and every plugin you already have live there. If the profile has no dsh.profile section yet, copy the baseline first and then add this plugin (for the web profile the baseline is ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app"]).

4.3 One-shot install with install.ps1 (recommended)

cd <repo>
pwsh -NoProfile -File .\install.ps1 -Profile web

Four idempotent steps:

  1. validate the checkout (package.json name and bin, plus scripts\dsh-restart.ps1, must exist);
  2. run dsh plugin --profile <p> add <repo> (skipped when the dependency is already declared; -Force re-runs it);
  3. activate: append the package name to the profile's dsh.profile.bundles. Before writing it confirms this package really declares dsh.bundle.patch (a non-bundle name in that list breaks the whole profile), backs up the original package.json, then re-reads and asserts "the name appears exactly once / the other bundles keep their order / the top-level keys and the dependency count are unchanged". Skipped when the name is already there;
  4. write an ASCII CLI shim to %LOCALAPPDATA%\dsh-restart\bin\dsh-restart-win.cmd and add that directory to the user PATH (-SkipPathUpdate writes the shim only).

Step 3 is why you do not have to edit dsh.profile.bundles by hand; anyone who installed with a manual dsh plugin add still has to do it, as described at the end of 4.2.

Useful switches: -SkipPluginAdd (you already ran pnpm link: skips dsh plugin add; activation and the shim still run), -ShimDir <path>, -WhatIf (print the plan, write nothing). Any failed step exits with code 1 and a message; nothing degrades silently.

install.ps1 does not restart the host for you.

4.4 Restart the host (you do this)

The new tools are registered when the host starts. Perform that restart yourself: trigger one from a session, or close the host and start it again.

4.5 Self-check

Both checks must hold — miss one and the tools will not appear:

# 1) the package is in the layer tree (if not, go back to the end of 4.2)
(Get-Content "$env:USERPROFILE\.dsh\profiles\web\package.json" -Raw |
  ConvertFrom-Json).dsh.profile.bundles

# 2) the composed layer stack contains the row
dsh --profile web --dump-config | Select-String 'dsh-restart-win'

Then check the engine and the tools:

dsh-restart-win -Status -Json            # one JSON object, exit code 0
dsh-restart-win -Preflight               # deep verification (slow; boots a throw-away instance)

After the host restarts, the four win_restart* tools should be visible in a session.


4.6 DSH Desktop (Electron) hosts

The engine also drives the DSH Desktop shell (DeepSeek Harness.exe), whose shape differs from dsh web in four ways a restarter must respect:

dsh webDSH Desktop
Host processnode.exe ... dsh\lib\bin.js weban Electron Node-mode child (--expose-internals ...\app.asar\dsh\node_modules\@deepseek-ai\dsh-desktop-host\lib\index.js), process name DeepSeek Harness.exe
Portfixed (--port 3080)--port 0: random on every launch
Stopkill the port listenerkill the Electron main process tree; killing the child alone leaves the shell on a host-crash dialog
Isolated verificationdsh web in a temporary homethe same Electron host entry in a temporary home (the app holds a single-instance lock, so a second DeepSeek Harness.exe only focuses the window)

hostKind (config key, per-call argument, or -HostKind) selects auto (default), web, or desktop. On a desktop profile, point the row at that profile in the user layer:

# %USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml
- id: dsh-restart-win
  config:
    profile: desktop      # the plugin's own default is `web`

With desktop, the engine discovers the host by command line and parent chain (four identity checks), reverse-looks the real port from netstat, writes the resume notice, stops the Electron main tree with taskkill /T /F, relaunches the recorded executable, and waits for a new host child whose listening port answers 401/200. -Status reports hostKind, mainPid, resolvedPort, configuredPort, portSource and instanceShape; -Port becomes a hint (status.portSource = "netstat"). Record the app once so a cold start knows what to launch:

dsh-restart-win -Record -RecordCommand '"C:\<app>\DeepSeek Harness.exe"' -RecordWorkingDirectory "$env:USERPROFILE"

-Preflight on a desktop profile boots the Electron host entry directly (Node mode + isolated home), so it validates the same plugin stack without touching the running app.

4.7 The sidebar panel

The package ships a client half (client.js, declared through dsh.client in the manifest), so a desktop or web host grows a DSH 重启 / DSH restart tab in the right sidebar:

  • Status: host shape, resolved vs configured port, Electron main pid, host pid, HTTP probe, profile, version, and the authenticated launch URL with a copy button. Refreshes every 8 s.
  • Actions: refresh, dry run, deep preflight, safe restart, stop only, start only. restart and stop ask for a second click.
  • Output: a detached run is followed by runId; the panel renders the engine's steps line by line, then the summary, exit code and result file. The runId is kept in localStorage, so the panel resumes polling after the host restarts.
  • History: the last five restart-history.jsonl records.

The panel talks to /dsh-restart-win/api/* on the same origin (the host's session auth applies; mutating calls must prove their Origin). The routes delegate to the same four tool implementations the agent calls — no second code path. A host without a web server cannot load the plugin (inject: ['tools', 'webServer']), which is the same trade-off other panel plugins make.

The client half is part of the package, so it appears after one host restart; no build step is involved.

5. The four tools

Every argument is whitelist-validated before it reaches an argv array (a shell string is never built); an invalid value returns an error instead of falling back to a default. Each tool can be switched off through tools.

5.1 win_restart

Start a restart (or start / stop / dry-run / record / scheduled-task management). Restart-class actions run detached: the tool returns { started, runId, resultFile } immediately and the engine touches the host only after restartDelayMs (default 1500 ms), so this call's result is already on disk.

ParameterTypeDefaultMeaning
actionstring enumrestartrestart safe full restart; start launch only; stop stop only; status read-only snapshot; dry_run rehearse; record save the launch command; task_register / task_unregister manage the scheduled task; preflight / verify_only long isolated verification
fastbooleanfalseSkip deep verification. With a running instance the engine still refuses to stop unless forceUnverified is also set
forceUnverifiedbooleanfalseExplicitly accept stopping an instance that was not deep-verified (only meaningful with fast)
viaTaskbooleanfalseLet the scheduled task perform the restart, leaving the host process tree
dryRunbooleanfalseRehearse; valid only with action=restart, equivalent to the engine's -DryRun
tryCtrlCbooleanfalseTry one graceful Ctrl+C before terminating
waitIdleSecinteger0Seconds to wait for the session to go idle (0 = do not wait)
idleMaxSecinteger300Hard cap on the idle wait
delayMsintegerconfig restartDelayMsDetached actions: delay before the engine touches the host
profile / port / bindHoststring / integer / stringconfig valuesPer-call override of profile, port, probe address
hostKindstring enumconfig valueauto / web / desktop; desktop discovers the random port and stops the Electron main tree
dshHome / stateDirstringconfig valuesPer-call override of the DSH home and the engine state directory
taskNamestringconfig valueScheduled-task name
pwshPathstringautoPowerShell executable (default pwsh, then powershell.exe)
readySec / verifyReadySec / graceSec / portFreeSecinteger90 / 150 / 3 / 30Wait budgets
sessionstringcurrent sessionSession id the resume notice is addressed to
reasonstringengine defaultReason text stored in the resume notice
recordCommandstring—Required for action=record: the exact command that started the host
recordWorkingDirectorystring—action=record: the working directory the host was started in
verifyTempRootstring%TEMP%Temp root for the isolated verification instance

Output: ok, action, started, state ∈ ok/failed/running, runId, resultFile, exitCode, summary, error, delayMs, detail. state=running means scheduled; read the verdict with win_restart_result.

5.2 win_restart_status

Read-only snapshot, runs in the foreground, changes nothing. Parameters: profile, port, bindHost, dshHome, stateDir, pwshPath.

Output: ok, state, result, version, exitCode, durationMs, hostUrl, targetPid, warnings[], status (the engine status object passed through unchanged: instances / http / serving / bootRecord / lastRestart / marker / launchUrl …), stateDir, logPath, error, stderrTail.

5.3 win_restart_preflight

Long isolated verification: symlink-privilege probe plus a real throw-away boot in a temporary home. Nothing production is touched. Runs detached and returns { started, runId, resultFile } immediately.

ParameterTypeDefaultMeaning
modestring enumpreflightpreflight or verify_only; the engine handles both in one branch, so they are equivalent (see §8)
delayMsintegerconfig restartDelayMsDelay before the isolated run starts
verifyTempRootstring%TEMP%Temp root for the isolated instance
profile / port / bindHost / dshHome / stateDir / pwshPath—config valuesAs in win_restart
readySec / verifyReadySec / graceSec / portFreeSecinteger90 / 150 / 3 / 30Wait budgets

Output: ok, started, state ∈ running/failed, mode, runId, resultFile, delayMs, error, detail (includes verifyTimeoutMs). Read the verdict with win_restart_result.

5.4 win_restart_result

Read back a detached run by runId (or an explicit resultFile inside stateDir). Four states: ok / failed / running / unknown.

ParameterTypeDefaultMeaning
runIdstring—Id returned by win_restart / win_restart_preflight, e.g. 20260101-120000-a1b2c3
resultFilestring—Explicit result file; must live inside stateDir
stateDirstringconfig valueSet when that run used a non-default state directory
waitMsinteger0Wait up to this many milliseconds (max 120000); 0 = read once

Output: ok, state, runId, resultFile, action, startedAt, finishedAt, exitCode, summary, ageMs, error, envelope (the engine envelope as written).


6. The command line: dsh-restart-win

bin/dsh-restart-win.mjs is the CLI twin of the engine: no config layer, no extra validation, exactly the engine's switches and exit codes. Stdio is inherited, so a long run prints live.

dsh-restart-win -Status -Json
dsh-restart-win -Preflight -ResultFile "$env:TEMP\preflight.json"
dsh-restart-win -DryRun

The %LOCALAPPDATA%\dsh-restart\bin\dsh-restart-win.cmd shim that install.ps1 writes just forwards to this entry point through node.

6.1 Every engine switch

SwitchValueEffect
-Status—Read-only status
-DryRun—Rehearse without side effects
-Start—Launch only (cold start); writes no resume notice
-Stop—Stop only (mutually exclusive with -Start)
-Json—Emit a single JSON object on stdout
-Fast—Skip deep verification
-ForceUnverified—With -Fast, explicitly accept an unverified stop
-VerifyOnly—Deep verification only
-Preflight—Equivalent to -VerifyOnly
-Record—Write the launch record
-RegisterTask / -UnregisterTask—Register / delete the scheduled task
-TryCtrlC—Try one graceful Ctrl+C before terminating
-ViaTask—Let the scheduled task do it (returns immediately)
-ViaTaskInner—Marker used by the scheduled task; no branch consumes it, kept for compatibility
-ResultFilepathWrite the final result JSON there (every terminal outcome)
-NoWait—Do not linger at the end: skip the 20 s boot-token wait and scan once
-ProfilestringDSH profile (default web)
-HostKindauto / web / desktopHost shape; auto detects DSH Desktop and otherwise stays on dsh web
-RepairSharedScope—Rebuild <DSH_HOME>\profiles\node_modules (the base-package projection the desktop host resolves @deepseek-ai/* from) out of the installed app.asar, then exit. Use it when the app no longer starts and its crash log lists base packages as ERR_MODULE_NOT_FOUND
-CheckShadowed—Move any @deepseek-ai/* inside the profile whose version differs from the app's own copy into .stale-packages (that shadowing makes the settings service never register: the app shows Web RPC failed and six plugins stay pending)
-PortintHost port (default 3080; also names the mutex)
-BindHoststringProbe address (default 127.0.0.1). It does not change the host's listen address — see §8
-DshHomepathDSH home (default %DSH_HOME%, else %USERPROFILE%\.dsh)
-StateDirpathState directory (default %DSH_RESTART_HOME%, else %LOCALAPPDATA%\dsh-restart)
-ReadySec / -VerifyReadySec / -GraceSec / -PortFreeSecint90 / 150 / 3 / 30 seconds
-WaitIdleSec / -IdleMaxSecintIdle wait and its cap (0 / 300)
-SessionstringTarget session for the resume notice; auto picks the newest one
-ReasonstringReason text in the resume notice
-RecordCommand / -RecordWorkingDirectorystringLaunch command and working directory for -Record
-TaskNamestringScheduled-task name (default DSH Restart)
-VerifyTempRootpathTemp root for the isolated verification instance (default %TEMP%)
-DoNotTouchDshHome—Compatibility switch: no branch consumes it, so it behaves as a no-op

7. Configuration

Configuration lives under the plugin row's config in cordis.patch.yml (or in the host's plugin settings UI). The defaults are exactly the behaviour the engine already had on Windows.

KeyTypeDefaultMeaning
profilestringwebDSH profile being restarted
hostKindstringautoHost shape: auto detects DSH Desktop, web / desktop pin it
portinteger3080Host port; also the mutex name and the discovery key
bindHoststring127.0.0.1Address used for probes and status display. Changing it does not change the host's listen address (see §8)
dshHomestring''Empty = %DSH_HOME%, then %USERPROFILE%\.dsh
stateDirstring''Empty = %DSH_RESTART_HOME%, then %LOCALAPPDATA%\dsh-restart. Keep the default to reuse existing logs, boot records and resume notices
taskNamestringDSH RestartScheduled-task name (used by -ViaTask / -RegisterTask / -UnregisterTask)
pwshPathstring''Empty = auto: pwsh first, then powershell.exe
readySecinteger90Wait budget for the restarted host to become ready
verifyReadySecinteger150Readiness budget for the isolated verification instance
graceSecinteger3Graceful stop grace period
portFreeSecinteger30Wait budget for the port to be released
restartDelayMsinteger1500The tool returns first, then waits this long before touching the host
toolTimeoutMsinteger30000Foreground short-task timeout
verifyTimeoutMsinteger600000Budget for a detached verification run (also bounds how long win_restart_result waits)
trustedHostsstring[][]Extra Host authorities the dashboard API accepts besides loopback: exact hostnames or *.suffix wildcards. Needed when the GUI is reached through a reverse proxy such as tailscale serve (Host: <host>.tailnet.ts.net); loopback-only stays the default
injectHostEnvbooleantrueWhether to inject DSH_UC_PROFILE_NODE_MODULES / NPM_CONFIG_LEGACY_PEER_DEPS into the child process that becomes the host (see 7.1); false starts the engine with DSH_RESTART_INJECT_HOST_ENV=0 so it skips them
tools.restartbooleantrueRegister win_restart
tools.statusbooleantrueRegister win_restart_status
tools.preflightbooleantrueRegister win_restart_preflight
tools.resultbooleantrueRegister win_restart_result

An invalid value fails plugin load with the field name (dsh-restart-win config: <field>: ...); nothing silently falls back to a default.

7.1 The two environment variables injected when launching the host

Before launching the host, the engine writes two variables into the environment of the process it is about to start:

VariableValueWhy it exists
DSH_UC_PROFILE_NODE_MODULES<DshHome>\profiles\node_modulesPlugins live under the profile's node_modules; without an explicit pointer the update checker can install a package into node_modules without updating package.json and pnpm-lock.yaml, so the next install drops it
NPM_CONFIG_LEGACY_PEER_DEPStrueThe rc host's peer ranges rarely agree; without this flag npm fetching packages in a temporary directory fails with ERESOLVE

Three things to know:

  1. Process scope only. The values are set in the engine's own process environment and reach the new host through Start-Process. Nothing is written at user or machine level, so nothing survives the host and the npm in your own terminal is unaffected.
  2. You can turn it off. With injectHostEnv: false (default true) the plugin starts the engine with DSH_RESTART_INJECT_HOST_ENV=0; the engine skips both injections and records a skip step. Use it on a machine that does not need these workarounds — the default reproduces the old behaviour.
  3. Check that nothing leaked into the system (both must print nothing):
[Environment]::GetEnvironmentVariable('NPM_CONFIG_LEGACY_PEER_DEPS', 'User')
[Environment]::GetEnvironmentVariable('DSH_UC_PROFILE_NODE_MODULES', 'User')

8. Three interface facts you must know

  1. -Preflight and -VerifyOnly are equivalent. The old help text implied -Preflight did an extra symlink preflight; both actually run the same branch and both probe the symlink privilege. The documentation states the equivalence and does not invent a difference.
  2. -BindHost is not part of the launch command. Which address the host binds is decided by the launch record (boot-record.json) or the default launch plan; -BindHost only affects the probe URL and the status display. To change the listen address, change the launch record, not this setting.
  3. -DoNotTouchDshHome is a dead parameter. It is declared, accepted, and no branch consumes it, so it behaves as a no-op. It stays for command-line compatibility.

9. Exit codes and terminal words

Exit codes and result words are an existing scriptable interface and have not changed. With -Json they appear as exitCode / result in the envelope, and the process exit code matches.

Exit coderesult wordMeaning
0restarted-okRestart succeeded
0statusRead-only status returned
0verify-only-okPreflight / deep verification passed
0dry-runRehearsal completed (no side effects)
0stoppedStop completed, or there was no target instance
0task-registeredScheduled task registered / updated
0task-unregisteredScheduled task deleted
0via-task-dispatchedHanded to the scheduled task, returned immediately
0recordedLaunch record written
0rescued-after-abort:<reason>Abort happened after the stop; rescue launch succeeded
1aborted:<first exception line>Uncaught exception (the terminal outcome is still recorded)
1task-register-failedScheduled-task registration failed
1task-unregisteredschtasks /Delete failed (task missing or access denied); the envelope also carries ok=false
2lockedAnother restart is already running (no queueing, no retry)
2engine-requires-pwshThis action needs pwsh 7.4+; aborted before the stop
2invalid-argsIllegal argument combination (e.g. -Stop with -Start)
3config-invalid--dump-config combination check failed; the old instance was untouched
4verify-only-failedPreflight / deep verification failed; logs are kept
4verify-failedPre-restart deep verification failed; the old instance was untouched
5gate-blockedConfiguration-operation gate hit (transaction / lock files)
6stop-failedStop failed (including permission boundaries)
7port-busyPort was not released; launch abandoned
8ready-failed:<reason>Not ready after launch; this launch chain was collected. Reason ∈ port-owner-mismatch / exited / timeout
9via-task-failedTask not registered, or triggering it failed
10verify-requiredAn instance exists and the restart is unverified: refused
11launch-prereq-failedLaunch preflight failed; aborted before the stop
12stop-refusedThe port owner is not node / dsh / bun; stop refused

The three ready-failed: reasons and the rescued-after-abort: / aborted: prefixes are literal contracts: logs and troubleshooting scripts depend on them.


10. State directory and files

Default state directory: %LOCALAPPDATA%\dsh-restart (override with stateDir; keep the default to reuse the existing files).

FileWritten byPurpose
boot-record.jsonengine (-Record)Launch record: recordedAt / command / cwd / profile / port / host / dshHome / note; the restart replays this command
restart-history.jsonlengineOne JSON audit record per execution (16 fields: ts / version / result / rc / profile / port / target_pid / new_pid / url / session / reason / host / user / steps / warnings / audit). Never rotated
dsh-restart.logengineOne human-readable terminal line per execution
web-auth-url.txtengineLaunch-URL cache: url / token / pid / port / profile / savedAt / source. Contains a real token — treat it as a credential
host.<hostKind>.out.log / .err.logenginestdout / stderr of the launched host (banner appended, then redirected). Separate files per host kind: the desktop app keeps its own log handle for its whole lifetime, so sharing one name makes the other kind's launch fail
dsh-restart.task.xmlengine (-RegisterTask)Scheduled-task definition, UTF-16LE with BOM (schtasks requires it)
fallback\engineSecond location when the log / history write fails
runs\<runId>.pending.jsonpluginDetached-run registration (action, delay, engine script, pwsh source, host pid, launcher pid)
runs\<runId>.request.jsonpluginLauncher request (delay, runId, execPath, full argv)
runs\<runId>.launch.jsonpluginLauncher receipt (enginePid, delay, success, engine exit code)
runs\<runId>.result.jsonengineThe -ResultFile envelope; win_restart_result reads it

Two other locations:

PathPurpose
<DshHome>\.smart-restart\pending-notice.jsonResume notice {sessionId, reason, when}, UTF-8 without BOM, written before the stop and deleted by the host once consumed
<DshHome>\.smart-restart\marker.jsonpid / lastBootAt / dshVersion written by the host; the engine only reads it
<VerifyTempRoot>\dsh-verify.<8hex>Temporary home of the isolated verification instance; logs are kept on failure

11. Prerequisites and permissions

PrerequisiteWhyHow
Symlink creation privilegeThe host's cold start and the isolated verification both create junctions/symlinks; without them the preflight fails while the old instance is still running (exit code 4), so no half-started instance is left behindTurn on Windows Developer Mode, or run once as administrator
pwsh 7.4+Start-Process -Environment is what injects the isolated environmentInstall PowerShell 7; with only 5.1, verified actions abort with exit code 2
Permission to terminate the host processThe stop uses taskkill; insufficient rights report stop-failed with the root causeRun as the same user that started the host; a host started under another user or a service context needs matching rights
Scheduled task (only for -ViaTask / -RegisterTask)Lets the executor leave the host process treedsh-restart-win -RegisterTask; the task registers as HighestAvailable
%DSH_HOME% (optional)Distinguish state when several DSH homes existSet the variable, or configure dshHome

12. Safety boundaries

This plugin kills and restarts the DSH host you are using. You own the consequences of that sentence, so here are the boundaries:

  1. You perform the restart. The plugin supplies the tool; an agent may call it with your authorization, but the moment the host disappears the session is cut. Do not treat it as a silent background operation — watch the first one.
  2. It must be allowed to kill processes. The stop goes through taskkill; there is no "soft landing" guarantee, and -TryCtrlC is only one attempt before termination, off by default.
  3. It verifies before it stops, but does not verify your business state. Deep verification proves that this profile combination can come up and answer 401/200; it does not prove your data, sessions or plugin state are intact.
  4. It does not elevate itself. No UAC prompt, no system-wide configuration, no user-level environment variable changes (it writes the user PATH only when you run install.ps1). The scheduled task runs with the rights it already has.
  5. It is not networked. Every decision comes from local ports, processes, files and HTTP probes.
  6. web-auth-url.txt holds a real token. Do not paste it into issues, logs or screenshots.
  7. restart-history.jsonl is never cleaned up. It grows for as long as you use it; archive it yourself when it matters.

13. Troubleshooting

Look at three places first: the tool's error (or the CLI's stderr), the last line of <stateDir>\dsh-restart.log, and the last record in <stateDir>\restart-history.jsonl.

The app shows 应用无法启动/Web RPC failed although the host is listening. A third-party install can hoist an older @deepseek-ai/dsh-settings (or another base package) into the profile's node_modules, shadowing the app's copy; the settings service then never registers and the welcome window's RPC fails. Run dsh-restart-win -CheckShadowed (the engine also does it before every launch and moves the offenders to .stale-packages).

The app no longer starts at all, and its host crash log lists base packages as ERR_MODULE_NOT_FOUND. The desktop host resolves @deepseek-ai/* from <DSH_HOME>\profiles\node_modules — a projection of app.asar\dsh\node_modules — and a profile pnpm install can prune it. Run dsh-restart-win -RepairSharedScope (rebuilds it from the installed app.asar); the engine also repairs it automatically before it launches the app. A fresh empty profile fails the same way, so this is not a corrupted profile.

Symptom / exit codeCauseAction
2 lockedA restart is already running (mutex Local\dsh-restart-p<port>)Wait for it; make sure no engine process is stuck
2 engine-requires-pwshThe current PowerShell lacks a capability this action needsInstall pwsh 7.4+, or point pwshPath at it
2 invalid-args-Stop with -Start, or -ResultFile is not writableFix the argument combination; check the result-file directory
3 config-invalidThe --dump-config combination check failedFix the profile per the logged reason; permission errors are not config errors and do not land here
4 verify-failed / verify-only-failedThe isolated instance would not startRead the logs in the kept dsh-verify.* directory; usual causes are a missing node_modules or missing symlink privilege
5 gate-blockedAn unfinished configuration transaction or lock fileClear *.transaction / RECOVERY_REQUIRED* first; the log prints the stale-lock recovery command
6 stop-failedInsufficient rights, or the process survivedRead the Access is denied section and its two ways out; retry from the same user or an elevated shell
7 port-busyThe old instance is gone but the port is still heldFind the owner (netstat -ano -p TCP) and clear it deliberately
8 ready-failed:timeoutThe new host was not ready within budgetRaise readySec; read host.<hostKind>.err.log (on a web host: host.web.err.log)
8 ready-failed:exitedThe new host started and immediately exitedRead the tail of host.<hostKind>.err.log / .out.log; usually the launch command or the profile
8 ready-failed:port-owner-mismatchThe listener on the port is not the process this run launchedCheck for a wrapper script; the engine walks the parent chain
9 via-task-failedTask not registered, or triggering failed-RegisterTask first, then -ViaTask
10 verify-required-Fast met a running instanceDrop -Fast and verify, or pass -ForceUnverified explicitly
11 launch-prereq-failedThe first word of the launch command does not resolve, or the cwd package.json defines it as a local scriptWrite a runnable command with -Record, then restart
12 stop-refusedThe port owner is not node / dsh / bunIdentify that process; the guard exists to avoid killing the wrong thing
0 rescued-after-abort:Abort happened after the stop; a rescue launch already ranThe host is back — still check the abort reason in the log
tool returns state=unknownThe runId does not exist, or the result file is not written yetCall win_restart_result with waitMs, or confirm stateDir matches

Deep verification is slow (default budget 150 s × up to two attempts, plus assembling the isolated home). win_restart_preflight returning running is normal: poll with win_restart_result.


14. What is verified and what is not

Exercised by this repository's automation, with output you can reproduce: the parameter table (35 parameters; -ResultFile / -NoWait added), the exit-code literal set, the single-object -Json envelope, real -Status / -DryRun / -Preflight runs, -ResultFile on success and on an unwritable path, the -Stop -Start conflict path, human mode emitting no JSON line, scripts/check-encoding.ps1 with errors=0 under both pwsh 7 and Windows PowerShell 5.1, install.ps1 idempotency and -WhatIf, npm test, the four tools loading without a host, win_restart_status against the real engine, the CLI matching the engine's exit code, a detached run returning in under 5 s and settling to ok after the delay, and engine stdout never entering host stdio.

"Can it run on another machine" has one concrete data point: on a fresh clone (the repository pins line endings with .gitattributes and eol=lf), npm test exited 0 — selftest 77 passed, parity asserted all 243 rows, integration 16 passed with 1 skipped — and the engine was still UTF-8 BOM + LF in that clone (scripts\check-encoding.ps1 passed). So "clone it on another machine and it runs" is a measurement, not a promise. The install-side activation step was exercised against a fixture profile too: it backs the original manifest up, appends at the end, keeps the other bundles' relative order, skips on a second run, and refuses to write dsh.profile.bundles when the package is not actually present in the profile (that "listed but not installed" state is what the host otherwise skips silently).

Not executed by this repository's automation (they stop the host, need administrator rights, or need a live instance; the logic was ported line by line and the decision paths were not changed):

Not verifiedWhy it was not runHow to check it once yourself
A full restart (the default action)It kills the current host and interrupts running sessionsWhen an interruption is acceptable: dsh-restart-win -DryRun to confirm the plan, then one real restart
-Stop against a live instanceSamePick an idle window; -DryRun first
-RegisterTask / -UnregisterTaskWrites a system scheduled task, may need administrator rightsdsh-restart-win -RegisterTask, then check schtasks /Query /TN "DSH Restart"
-ViaTask dispatchDepends on the previous rowAfter registering, run -ViaTask and read the task's last result
-TryCtrlCNeeds an interactive host console; off by defaultOnly enable it when you know the consequences
-ForceUnverifiedIts semantics are accepting the riskNot recommended as routine use

So treat "not verified" as "not tried", not as "broken" — but do not make your first real restart happen during a critical window.


15. Development and tests

npm test                                  # node --check + unit / contract tests
node test/parity.mjs                      # asserts every docs/parity-matrix.md row has an implementation and evidence
pwsh -NoProfile -File scripts\check-encoding.ps1
powershell.exe -NoProfile -File scripts\check-encoding.ps1

Encoding rules (both engines must parse the same file):

  • .ps1 must be UTF-8 with BOM + LF. Without the BOM, Windows PowerShell 5.1 parses a script containing Chinese as the local code page and reports dozens of syntax errors.
  • scripts/dsh-restart.task.xml must be UTF-16LE with BOM (schtasks requires it).
  • The .cmd shim must be pure ASCII + CRLF (cmd.exe reads it with the OEM code page).

Repository layout:

lib/index.js              plugin entry: normalize config → resolve tools → register / dispose
lib/config.js             config and call-argument normalization, whitelist validation (pure, fail-closed)
lib/paths.js              pwsh / engine script / dshHome / stateDir / runs directory resolution
lib/runner.js             argv builder, foreground runs, detached runs, run-record I/O
lib/tools.js              the four tool definitions (parameters, output schema, render, execute)
lib/delayed-spawn.mjs     detached launcher: wait restartDelayMs, then run the engine to completion
bin/dsh-restart-win.mjs   CLI: forwards arguments to the engine
scripts/dsh-restart.ps1   the engine (single source of executable truth)
scripts/dsh-restart.task.xml  scheduled-task template (placeholder form)
scripts/check-encoding.ps1    encoding / newline / dual-engine parser check
install.ps1               add to profile + write the PATH shim
test/selftest.mjs         unit and contract tests
docs/parity-matrix.md     capability matrix (source position, target, verification per row)
docs/migration.md         switching from the old engine and rolling back

CI (.github/workflows/ci.yml): Ubuntu runs the Node tests and node --check; Windows runs the dual-engine check-encoding, Parser::ParseFile over every .ps1, npm test and test/parity.mjs.


16. Uninstall and rollback

# 1. remove the plugin from the profile (tools disappear on the next host start)
#    installed from GitHub, the dependency name is still the package name
dsh plugin --profile web remove @brainzombie/dsh-restart-win

# 2. also delete "@brainzombie/dsh-restart-win" from dsh.profile.bundles
#    step 1 alone leaves the host printing skipping profile bundle on every start

# 3. delete the PATH shim (optional)
Remove-Item "$env:LOCALAPPDATA\dsh-restart\bin\dsh-restart-win.cmd"

# 4. delete the scheduled task (only if you registered it)
dsh-restart-win -UnregisterTask

The state directory is not deleted by default: the logs, launch record and history under %LOCALAPPDATA%\dsh-restart are assets — deleting them throws away resume and troubleshooting evidence. Remove the whole directory only when you are sure.

Rolling back to the old engine: docs/migration.md has the full sequence (freeze the old directory as an archive → let the plugin take over → switch back when needed) and a line-by-line table from old commands to the new tools and CLI.


17. License

MIT, copyright BrainZombie. See LICENSE.

Comments

Loading…

Similar plugins

dsh-restart

by zhengjy01

One-click restart for DeepSeek Harness: a web button (plus a dsh_restart agent tool) hands the relaunch to a detached helper, the page reconnects by itself, and a recovery console shows the boot error

Development & InfrastructureManifest valid

★ 0

MIT

JavaScript

Sep 29, 2026

dsh plugin --profile web add @zhengjunyao/dsh-restart

by Eason-22

DeepSeek Harness plugin: restart without losing work, with an idle-aware graceful restart and automatic session resume after the host comes back. Built-in restart supports the Windows desktop app only

Tools & CapabilitiesTerminal & ClientsSessions & MessagesManifest valid

★ 2

MIT

JavaScript

Nov 11, 2026

dsh plugin --profile web add dsh-autorestart

by NYSM803

Draggable floating restart button for the DeepSeek Harness(dsh) Web GUI:confirm, then restart the app and host.

UI & ExperienceDevelopment & InfrastructureManifest valid

★ 1

MIT

JavaScript

Nov 8, 2026

dsh plugin --profile web add dsh-plugin-restart-button

One-call restart for the running DSH process, with launchd-aware supervision detection, a verifiable restart log, and a bottom-right GUI control.

Development & InfrastructureTerminal & ClientsManifest valid

★ 0

dsh plugin --profile web add dsh-restart

by Mr54233

One-click full-app restart for the DSH desktop client: a sidebar footer button and a settings section with a live config form (master switch, confirm dialog, delay, target executable). Restart is perf

Development & InfrastructureManifest valid

★ 4

JavaScript

Nov 5, 2026

dsh plugin --profile web add dsh-restart-now

by Mandarin715

Windows boot autostart and one-click restart for the DSH service, from inside DSH: a windowless HKCU-Run bootstrap entry, a restart button in the settings card, the current tokenised access URL, and a

UI & ExperienceDevelopment & InfrastructureManifest valid

★ 1

↓ 7/wk

MIT

JavaScript

Oct 1, 2026

dsh plugin --profile web add dsh-autostart