DSH Maestro Supervisor: DSH Web Recovery Daemon

In the DSH Web environment, process crashes or network instability can interrupt sessions, making it difficult to restore state after a system restart. DSH Maestro Supervisor is a daemon and plugin combination that automatically detects DSH Web crashes, rolls back to a known good state (LKG), and recovers interrupted sessions.

The plugin is maintained by ddtcorex and released under the MIT License. It maintains liveness through a system-level daemon independent of the pnpm tree, while also acting as an internal DSH Web plugin to handle session recovery and browser reloads.

Core Features¶

1. Crash Detection and LKG Rollback¶

The daemon runs outside the dsh web process tree and is managed by Systemd or started manually. It polls the Web service port every 3 seconds. When the service is unavailable or has crashed, the daemon attempts to roll the system back to the most recent known good snapshot (LKG).

• Storage location: LKG snapshots are stored in the ~/.dsh/.supervisor/lkg/ directory.
• Validation: Snapshot files are verified using SHA256 checksums.
• Rollback trigger: After a crash is detected, the daemon waits for a 60-second debounce before performing the rollback.

2. Automatic Recovery of Interrupted Sessions¶

After DSH Web restarts, the plugin automatically scans and recovers interrupted sessions and unfinished open turns.

• Scan scope: Scans session logs from the last 5 minutes (default configuration).
• Recovery logic: Finds sessions containing interruption markers (reason.kind === 'interrupted'), or finds unclosed turns, and attempts to reconnect or restore context via RPC.
• Client behavior: The browser-side plugin attempts to fetch header information every 1 second when offline, when the WebSocket disconnects, or when page visibility changes, and automatically refreshes the page after success.

3. Health Reports¶

After a crash or rollback operation completes, the daemon generates a health report. The report includes a system status summary, Git diff, and recent log snippets.

Installation and Enablement¶

1. Build the Plugin¶

If installing from source, build commands must be executed. Note that the client build requires the build-client.mjs wrapper; using tsc directly will result in incomplete client files.

pnpm --dir packages/dsh-maestro-supervisor install
pnpm --dir packages/dsh-maestro-supervisor build
pnpm --dir packages/dsh-maestro-supervisor verify

2. Add to DSH Web Profile¶

Add the plugin to the Web configuration file. The package declares dsh.client, so the browser side loads it automatically.

dsh plugin --profile web add @ddtcorex/dsh-maestro-supervisor
pnpm --dir ~/.dsh/profiles/web install

Pre-checks: Before adding the plugin to the bundles of an active configuration, ensure dry-boot passes. This captures load-time failures (such as missing lib/index.js, stale build caches, etc.).

DSH_HOME=$(mktemp -d) pnpm --dir deepseek-harness dsh web --port 0 &
# Wait for successful startup and curl 200, then kill

3. Install Daemon¶

To survive process-tree crashes, installing a Systemd daemon is recommended.

bash packages/dsh-maestro-supervisor/scripts/install-systemd.sh
systemctl --user daemon-reload
systemctl --user enable --now dsh-web-supervisor

If not using Systemd, you can manually run the daemon in the foreground for debugging.

node packages/dsh-maestro-supervisor/lib/index.js daemon

Configuration¶

The plugin’s automatic recovery behavior is controlled by configuration files. Priority from high to low: Cordis configuration > environment variables > Supervisor configuration file > Maestro settings > defaults.

Configuration file is located at ~/.dsh/.supervisor/config.json.

{
  "autoResumeEnabled": true,
  "autoResumeWithin": 5
}

Usage¶

Daemon Management¶

node packages/dsh-maestro-supervisor/lib/index.js status
node packages/dsh-maestro-supervisor/lib/index.js logs --tail 50
node packages/dsh-maestro-supervisor/lib/index.js daemon

Manual Rollback¶

When you need to forcibly roll back to the latest LKG:

node packages/dsh-maestro-supervisor/lib/index.js rollback --latest

RPC Interface (Loopback)¶

The daemon provides services through a loopback RPC interface for manually scanning and resuming specific sessions.

Scan interrupted sessions:

curl -s http://127.0.0.1:3080/dsh-maestro-supervisor-resume/scan -X POST \
  -H 'content-type: application/json' \
  -d '{"type":"client-request","rpcId":"r1","method":"scan","payload":{"withinMs":300000}}'

Resume specified sessions:

curl -s http://127.0.0.1:3080/dsh-maestro-supervisor-resume/resume -X POST \
  -H 'content-type: application/json' \
  -d '{"type":"client-request","rpcId":"r2","method":"resume","payload":{"ids":["session-id"]}}'

Notes¶

1. Build dependencies: Any changes to the src/ directory require running pnpm build. The client build depends on build-client.mjs; using tsc directly cannot generate the correct client bundle.
2. File locations: LKG snapshots are stored in the .supervisor folder under the user directory.
3. Permissions: The daemon runs with user privileges. If Telegram notifications are required, uncomment the relevant environment variables in the Systemd configuration.
4. Ecosystem note: The DSH plugin catalog has no official affiliation with DeepSeek or Huanfang; it serves only as a community resource index.

Links¶

• Plugin catalog: [catalog_url]
• GitHub repository: [github_url]