Introduction

The plugin-based architecture of DeepSeek Harness allows developers to extend behavior. In long-running session scenarios that require strict time control or anomaly detection, manual monitoring is often inefficient and prone to missing issues. acosmi/dsh-session-supervisor provides a fact-based lifecycle supervision mechanism to address silent timeouts, deadline delays, and abnormal turns in active sessions.

What Is This

This is a persistent, budget-aware lifecycle supervision plugin for active DeepSeek Harness sessions (where the host process is alive). It is driven by periodic evaluations and makes judgments solely based on session lifecycle facts, without performing any external operations.

Core Features

  • Lifecycle Supervision: Supports three supervision contracts—silence detection (no events for N consecutive seconds), deadline detection (an RFC3339 deadline has passed), and abnormal turn streak detection (K consecutive turn/end entries with states such as error/blocked).
  • Persistence and Queuing: When a policy is violated, the plugin forms a persistent incident record, limits evidence quantity and size, and queues a follow-up to the owner session when configured to do so.
  • Guardian Tools: Provides commands to create, list, update (pause/resume/acknowledge/close), and check status.
  • Observe Only, No Execution: No shell execution, no network requests, and no Agent cancellation, ensuring the supervisor does not interfere with business logic.
  • Cold Session Recovery: Supports merging expired deadlines when resuming a session and re-anchoring silence detection.

Installation and Enablement

Before installing, make sure to pin a specific version and do not use latest.

dsh plugin --profile <name> add @<publisher>/dsh-session-supervisor@0.1.0-beta.1

After installation, the plugin writes a configuration object as a whole-object replacement into the profile’s cordis.patch.yml. Make sure the configuration file structure remains intact.

Typical Usage

  1. Declare Supervision Contracts: Define policies such as lifecycle_silence, deadline_unclosed, or abnormal_turn_streak in the configuration.
  2. Manage Guard State: Use guardian_create to create a supervision target, and use guardian_update to acknowledge or close an incident.
  3. Manually Trigger a Check: Use guardian_check_now for a single evaluation, recording only state transitions that actually occur.
  4. Resume a Session: When resuming a session, the plugin automatically merges overdue deadlines and continues supervision after re-anchoring silence.

Applicable Scenarios and Notes

  • Host Process Dependency: Timing occurs only while the harness process is alive. If the host process crashes, timing stops and cold sessions cannot be supervised.
  • Notification Idempotency: Due to the at-least-once delivery mechanism, notifications may be duplicated. Deduplication must rely on the incident ID.
  • Agent Non-Recoverability: A hung Agent cannot be recovered by this plugin (the plugin does not cancel the Agent); only a follow-up can be queued.
  • Zero Log Pollution: Version 1 does not write any events to session logs; state is stored in a separate directory.
  • Version Pinning: Each released version must be pinned individually to avoid compatibility issues.
  • Architecture Limitation: Single-host, single-process architecture, with no coordination across multiple hosts.

Conclusion

This plugin is suitable for scenarios that require strict lifecycle management capabilities. It provides a complete workflow from detection and recording to queuing follow-ups, but developers must be aware of its observe-only, no-execution behavior and its dependency on the host process being alive.

Project URL: https://github.com/acosmi/dsh-session-supervisor