Skip to content
  • Home
  • Plugin manual
  • dsh-stall-guard

akira399/dsh-stall-guard

30Last commit Aug 14, 2026

dsh-stall-guard DSH plugin

The dsh-stall-guard plugin continuously monitors task execution status in DSH, detecting true stalls based on inactivity and absence of in-flight operations. It uses a laddered approach: first diagnose, then fix, then redirect, injecting messages to guide the agent to recover. The plugin never terminates any task.

developer-tools

How to install the dsh-stall-guard DSH plugin

dsh plugin --profile web add github:akira399/dsh-stall-guard

Copying does not run this command. Review the repository and version before installing the dsh-stall-guard DSH plugin.

dsh-stall-guard DSH plugin data source

dsh-stall-guard DSH plugin snapshot date: Aug 16, 2026

discovered

What the dsh-stall-guard DSH plugin can do

  • Monitors task execution status and detects true stalls using activity events and in-flight operations.
  • Uses a three-level ladder (diagnose → fix → redirect) to guide recovery via injected user messages.
  • Provides configurable thresholds (stallThresholdMs, checkIntervalMs, etc.) with hot-reload support.
  • Logs all events to events.jsonl and exposes a status API endpoint (GET /api/dsh-stall-guard/status).
  • Never terminates tasks; only injects guidance messages, ensuring no accidental task loss.

Where the dsh-stall-guard DSH plugin fits

  • Prevent long-running tasks from being stuck indefinitely without progress.
  • Automatically recover stalled agents during complex multi-step workflows.
  • Monitor and debug tasks that hang due to tool call failures or LLM timeouts.
  • Provide a non-destructive safety net for production agent deployments.

Who the dsh-stall-guard DSH plugin is for

  • DSH users who run long-running tasks and want automatic stall detection without task termination.
  • Developers and operators of agent-based systems built on DSH.

dsh-stall-guard DSH plugin limitations

  • Only detects stalls based on 'no events + no in-flight operations'; tasks that are making progress but stuck logically (e.g., infinite loop generating events) are not detected.
  • Stalled agents that are stuck in an unawaitable synchronous operation cannot receive the injected messages until the operation completes; the plugin may keep guiding but cannot force recovery.
  • The plugin depends on DSH's event system and turn/step events; it may not function if the event pipeline is broken.

dsh-stall-guard DSH plugin: from the repository README

Quoted from the akira399/dsh-stall-guard README, the upstream source of the dsh-stall-guard DSH plugin. Copyright remains with the original authors.

DeepSeek Harness（DSH）**任务看门狗插件**：监控任务执行状态，判断是否真正卡死，并通过"排查→修复→换方向"的阶梯式引导帮助任务恢复——**全程不终止任何任务**。 ## 核心流程（监控 → 判断 → 继续 / 修复 / 换方向） ``` agent/status (running/idle) ─┐ session/event (turn/step/tool/llm) ─┼─→ 追踪每个会话的"最后活动时间"与"在飞操作" │ 周期扫描（checkIntervalMs）──→ 运行中且 静默 > stallThresholdMs ？ │ ├─ 有在飞操作（busy>0）或持续有事件 → 判定"推进中" → 继续执行，不干预 │ （超 busyTimeoutMs 仅记一条 LONG_RUNNING 日志） │ └─ 真静默（无事件 + 无在飞）→ 阶梯式引导（注入提示消息）： 第1级 诊断（DIAGNOSED） ：请 Agent 排查当前状态、说明卡住原因（附看门狗诊断现场） 第2级 修复（FIXING） ：请 Agent 针对卡点重试/完成/修复后继续 第3级+ 换方向（REDIRECTING）：请 Agent 放弃当前方法、改用替代方案持续推进 （每级按冷却间隔推进，第3级后循环；任何活动事件都会重置回第1级） │ 事件写入 $DSH_HOME/stall-guard/events.jsonl 状态查询 GET /api/dsh-stall-guard/status ``` **关键承诺：插件永不终止任务。** 它只通过注入消息引导 Agent 自己排查、修复、换方向；没有 `terminate` 选项，也没有任何终止指令。 ## 安装 ```sh npx -p @deepseek-ai/dsh dsh plugin --profile web add github:akira399/dsh-stall-guard ``` 安装后重启 DSH。插件**默认启用**。 ## 配置（settings.yaml 的 `stall-guard` 命名空间） | 键 | 默认值 | 说明 | | --- | ---

Read the full READMERepository license: MIT

dsh-stall-guard DSH plugin questions

How do I install dsh-stall-guard?

Run the command: `npx -p @deepseek-ai/dsh dsh plugin --profile web add github:akira399/dsh-stall-guard`. After installation, restart DSH. The plugin is enabled by default.

Does dsh-stall-guard ever terminate tasks?

No, the plugin never terminates tasks. It only injects guidance messages (diagnose, fix, redirect) to help the agent recover. There is no terminate option or any kill command in the plugin.

How can I change the stall detection threshold?

Edit the settings.yaml file under the `stall-guard` namespace. For example, set `stall-guard.stallThresholdMs: 60000` to 60 seconds. Changes are hot-reloaded without restarting DSH.

Where can I see the stall events log?

Events are written to ~/.dsh/stall-guard/events.jsonl. Each line is a JSON event (STALL, LONG_RUNNING, DIAGNOSED, etc.). You can also query the real-time status via GET http://127.0.0.1:3080/api/dsh-stall-guard/status.

Why is my long-running task not being detected as stalled?

The plugin only triggers stall recovery when there are no events and no in-flight operations. If your task is still generating events (e.g., tool calls, LLM streams) or has an in-flight operation, it is considered 'making progress' and will not be touched. This is by design to avoid false positives.