dsh-keepalive

English | 中文

Status: Feature Plugin with Compatibility Patch. Tested only with DeepSeek Harness 0.1.0-rc.6.

dsh-keepalive runs a detached watchdog for the DSH Web process. When explicitly enabled, the watchdog restarts DSH after a process exit. An optional repair agent can inspect repeated startup failures, modify the plugin workspace, and retry from a snapshot.

Problem

A Web process that exits cannot restart itself. DSH provides stream idle watchdogs and browser reconnect backoff, but those mechanisms do not supervise the host process.

Behavior

• Adds a Plugins settings card for watchdog configuration.
• Starts a detached Node watchdog only when enabled is true.
• Checks process health and relaunches the same DSH binary and arguments.
• Applies guarded compatibility patches for the settings namespace and hidden Windows child processes.
• Optionally runs a repair agent after repeated boot failures.
• Snapshots the allowed repair workspace, validates resulting paths/configuration/syntax, and rolls back failed repairs.

Both enabled and autoRepair require explicit opt-in; automatic repair defaults to false.

Non-goals

This package is not a high-availability cluster, service manager, sandbox, malware boundary, secret scrubber, or guarantee that a failed DSH instance can be repaired automatically. It does not replace systemd, Windows Service Control Manager, containers, or external monitoring.

Compatibility patches

The plugin targets exactly:

• @deepseek-ai/dsh-host-apiproxy@0.1.0-rc.6: allow the keepalive settings namespace in the Web settings API.
• @deepseek-ai/dsh-subprocess-local@0.1.0-rc.6: use windowsHide: true for local tool subprocesses on Windows.

Version policy is adaptive by default: a copy whose installed version differs from 0.1.0-rc.6 is still patched when every anchor matches uniquely (recorded as an adaptive match), and skipped with a reason when anchors drifted; a strict programmatic mode restores the old exact-version-only apply behavior. One drifted copy never blocks the other target, and patch application never throws during host or watchdog startup. The settings-namespace row is inserted at the top of the allowlist array so it cannot consume the tail anchor shared with dsh-tavily-search-provider; both plugins coexist in either install order. Restore (uninstall) remains strictly version-guarded. Writes use temporary files and rename, validate syntax after replacement, and restore the previous bytes on validation failure.

Compatibility

Requires DeepSeek Harness 0.1.0-rc.6, Node.js ^22.19.0 || >=24, and pnpm >=10. The watchdog is designed for the current DSH CLI layout and is tested on Windows.

Install

dsh plugin --profile web add "github:xiaohj233/dsh-keepalive#v0.1.0"

Restart the Web profile. Installation alone does not enable watchdog restart or repair.

Configuration

Configure the keepalive settings section through the Plugins card or settings file:

keepalive:
  enabled: false
  autoRepair: false
  checkIntervalMs: 3000
  bootWaitMs: 15000
  repairProvider: ""
  repairModel: ""

Provider, model, base URL, API name, and credential-reference values are serialized as single-line YAML-safe strings. Keep repair disabled until the selected model and credential path have been tested.

Explicit uninstall and restore

Run the package's uninstall command before removing it from the profile:

pnpm --dir "$DSH_HOME/profiles/web" exec dsh-keepalive-uninstall
dsh plugin --profile web remove dsh-keepalive

When $DSH_HOME is unset the profile lives under the home directory (POSIX: ~/.dsh/profiles/web; Windows PowerShell: %USERPROFILE%\.dsh\profiles\web); on Windows pass the resolved path to pnpm --dir instead of ~.

The command disables keepalive state, terminates only the recorded watchdog process, and restores both patched official files. It exits nonzero if any step is incomplete. Normal Web shutdown does not reverse patches because shutdown is the event the watchdog supervises.

Safety

The repair agent receives startup diagnostics as prompt input. Those diagnostics are untrusted and may contain misleading instructions. The repair runtime uses workspace-write, inherits environment information available to the launched process, and can modify the plugin workspace; this is not complete isolation or a confidentiality boundary. Snapshot, path, syntax, and rollback checks reduce accidental damage but do not make arbitrary agent output safe.

Review changes after every repair. Do not enable repair on a machine or plugin directory containing credentials that the repair process must not read.

Additional known limitations:

• Watchdog supervision and uninstall identify the watchdog only by recorded PID. If that PID was reused by an unrelated process after the watchdog died, supervision stops silently and dsh-keepalive-uninstall can terminate the unrelated process. Check for a running watchdog before uninstalling.
• After repeated missed polls, the watchdog force-terminates whatever process listens on the configured port (the intended relaunch target). An unrelated service holding that port is killed too.
• Failed-launch diagnostics and the last repair-agent output (up to 4 KB) are persisted in keepalive state and can be read from /api/keepalive/status by a same-origin or trusted page. Failed-launch logs may embed secrets from the environment.
• The snapshot/diff/rollback layer walks regular files and directories; a junction or symlink placed inside the plugin workspace by a compromised repair agent can redirect writes outside the snapshot scope without being detected.
• Host and watchdog both rewrite keepalive.json; a concurrent write can transiently lose one update (self-corrects on the next write).

Tests

npm test
npm run check:syntax
npm pack --dry-run

The suite covers defaults, YAML injection/round trips, exact patch/restore behavior, ambiguous anchors, syntax rollback, snapshots, a real detached-process uninstall, watchdog startup, and the --unpatch argument contract.

Limitations and upstream status

Restart/self-healing plugins already exist in the DSH community, and upstream may add an official keepalive implementation. This package is scoped to a Windows-friendly detached watchdog with opt-in snapshot-checked repair. It cannot recover from OS shutdown, account logout, unavailable Node/DSH binaries, or host-level resource exhaustion.

License

MIT. Patch targets are MIT-licensed; see THIRD_PARTY_NOTICES.md.