Preface¶

When running long-duration DSH tasks, developers often need to determine whether a task is simply “taking a long time to execute” or has truly stopped making progress. dsh-stall-guard is a DeepSeek Harness (DSH) task watchdog plugin designed to monitor task execution status, distinguish between genuine silence and in-flight operations, and provide graduated guidance for tasks that are truly stuck. It never terminates the task.

What This Is¶

dsh-stall-guard is a DSH task watchdog plugin hosted in the akira399/dsh-stall-guard repository, licensed under MIT.

It does three things:

1. Monitors DSH task execution status.
2. Determines whether a task is genuinely stuck.
3. Helps the task recover through a graduated “diagnose → fix → redirect” approach.

The plugin is enabled by default, requires Node >=20, and has zero npm dependencies.

Core Features¶

The verified capabilities of dsh-stall-guard include:

• Monitors DSH task execution status and tracks the session’s last activity time and in-flight operations.
• Periodically scans to identify genuine silence, defined as “running, no events, no in-flight operations.”
• Exempts tasks with in-flight operations (busy>0) or those continuously generating events — no guidance or intervention is applied.
• When truly silent, injects guidance messages in a graduated sequence of diagnosis, repair, and redirection, looping through the process.
• Does not terminate tasks: no terminate option, no termination commands, and no termination-type events.
• Writes STALL, LONG_RUNNING, DIAGNOSED, FIXING, and REDIRECTING events to JSONL.
• Provides a loopback status route at GET /api/dsh-stall-guard/status.
• Supports configuration via the stall-guard namespace in settings.yaml, with hot-reloading of changes.
• Supports policy=auto for graduated guidance and policy=report for logging only, without guidance.
• Delivers diagnostic, repair, and redirection instructions to the Agent by injecting user/message events.
• Each graduated message includes diagnostic context: last activity, turn/step position, and silence duration.

Configurable options include:

enabled
stallThresholdMs
checkIntervalMs
busyTimeoutMs
stallRecordIntervalMs
policy
nudgeCooldownMs
diagnoseMessage
fixMessage
redirectMessage

Installation and Enablement¶

The installation command uses the full command provided in the documentation:

npx -p @deepseek-ai/dsh dsh plugin --profile web add github:akira399/dsh-stall-guard

Restart DSH after installation. The plugin is enabled by default.

Typical Usage¶

First, confirm that your environment meets the Node >=20 requirement, then run the installation command above.

After installation, you can configure the plugin under the stall-guard namespace in settings.yaml. The example provided in the documentation is as follows:

stall-guard:
  stallThresholdMs: 60000
  checkIntervalMs: 3000
  policy: auto

Configuration changes take effect immediately via hot-reload, with no restart required.

When viewing event logs, the path example provided in the documentation is:

~/.dsh/stall-guard/events.jsonl

The documentation also mentions $DSH_HOME/stall-guard/events.jsonl; whether these two paths are equivalent is not clarified in the documentation.

An example request for querying real-time status is:

GET http://127.0.0.1:3080/api/dsh-stall-guard/status

The documentation does not specify whether this port is fixed.

The verification command is as follows:

pnpm verify

Use Cases and Notes¶

This plugin is suitable for developers who want to observe whether DSH tasks are truly making no progress, without having the watchdog terminate the task directly.

Keep the following points in mind:

• When tool calls or LLM requests are in-flight, the plugin considers the task to be progressing and will not guide or intervene.
• When busyTimeoutMs is exceeded, only a single LONG_RUNNING event is logged.
• With policy=report, only logging is performed, without guidance.
• With policy=auto, guidance is provided in the graduated sequence of diagnosis, repair, and redirection.
• The plugin runs with the current DSH process privileges and participates in task recovery through event monitoring and message injection; it is recommended to review the source code and license before installation.

Conclusion¶

The value of dsh-stall-guard lies in transforming “task stuck” from a manual observation into a recordable watchdog process: guiding the Agent to diagnose, fix, or redirect when genuinely silent, maintaining exemptions during in-flight operations, and never terminating the task throughout the entire process.

GitHub repository:

https://github.com/akira399/dsh-stall-guard

This documentation does not provide a standalone directory page URL; if you need to view it in the DSH plugin directory, you can search for the plugin by name dsh-stall-guard.